diff --git a/.env.example b/.env.example
index 42a2702..9391b37 100644
--- a/.env.example
+++ b/.env.example
@@ -6,7 +6,7 @@ VITE_APP_NAME=BeatDesign
 VITE_APP_DESCRIPTION=The open-source, local-first AI canvas for image and video creation.
 VITE_APP_LOGO=/logo.png
 VITE_DEFAULT_LOCALE=en
-VITE_GENERATION_PROVIDER=beatapi
+GENERATION_PROVIDER=beatapi
 
 # Local persistence
 DATABASE_PROVIDER=sqlite
diff --git a/.github/workflows/quality.yaml b/.github/workflows/quality.yaml
index e6e1a65..047251e 100644
--- a/.github/workflows/quality.yaml
+++ b/.github/workflows/quality.yaml
@@ -23,6 +23,9 @@ jobs:
           node-version: 22
           cache: pnpm
       - run: pnpm install --frozen-lockfile
+      # The MCP stdio probe exercises real Project queries, so CI needs the
+      # same local SQLite schema created by the documented quick-start flow.
+      - run: pnpm db:push
       # The Vite build generates the gitignored Paraglide and TanStack Router
       # artifacts that TypeScript needs in a clean checkout.
       - run: pnpm build
diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 0000000..f8ac110
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "beatdesign": {
+      "command": "pnpm",
+      "args": ["--silent", "mcp"]
+    }
+  }
+}
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index ed5e8da..f8903df 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -9,28 +9,59 @@ Projects
   + Home
   + Studio
   + Canvas
+  + Editor
   + Assets
   + Generation history
   + Provider configuration
   + Storage configuration
 ```
 
-Studio, Canvas, and Assets are three views over the same project, generation, and asset services. Switching modes never creates a second project or backend.
+Studio, Canvas, Editor, and Assets are views over the same project, generation, asset, and history services. Switching modes never creates a second project or backend.
+
+The shared product model is asset-first:
+
+- A generation creates an `Asset`; it does not own a single UI placement.
+- A Canvas node references an Asset, Generation, or Timeline.
+- A Timeline clip pins a concrete Asset and never silently follows a Canvas generation's latest output.
+- A Take is an alternate Asset for one clip; the original source remains recoverable.
+- Canvas edges describe visual organization. Generation lineage describes real derivation and is stored separately.
 
 ## Runtime flow
 
-The browser calls local `/api` routes. Server routes validate input and call the BeatAPI adapter. The adapter submits image/video generation tasks or the stable `/v1/video-analysis/tasks` workflow, then checks `/v1/tasks/:id`. Generation state and analysis text are stored locally, while provider result URLs are indexed as project assets.
+The browser calls local `/api` routes. Server routes validate input and resolve a logical model through the active Generation Provider contract. BeatAPI is the built-in/default provider; forks can register another source-level provider without changing Canvas, Editor, MCP, or the asset-first request contract.
 
 Provider credentials are read from environment variables or the local `config` table. Browser components never receive the raw API key.
 
 Upload storage is a separate adapter boundary. File selection remains browser-local. A successful generation precheck creates a short-lived, one-time SQLite intent that binds the project, model, exact upload count, uploaded URLs, and final generation submission. Required references are promoted only after that point and immediately before task submission; they become project assets only after BeatAPI accepts the task. The built-in provider is fixed to the official `https://api.beatapi.io` endpoint. Official `BEATAPI_MANAGED_R2_*` secrets and self-hosted `R2_*` credentials are deliberately separate and never fall through to each other.
 
+## Command boundary
+
+UI actions, the local MCP server, and a future CLI call the same Command Kernel. The kernel owns validation and pure document operations for Canvas and Editor. Persistence boundaries remain responsible for revision checks, durable writes, and returning the authoritative document.
+
+```text
+UI / MCP / CLI
+       |
+Command envelope + validation
+       |
+Canvas / Editor / Generation commands
+       |
+revision-checked project persistence
+       |
+SQLite + project media files
+```
+
+MCP does not write SQLite directly or replace an entire Canvas or Timeline document. Its tools call `persistBeatDesignCommand` with a transport-controlled `origin=mcp`. The public UI route assigns `origin=ui` server-side and rejects an `origin` request field. UI-only timeline replacement exists for local autosave and undo/redo, remains revision-checked, and is rejected for MCP/CLI origins. Generation commands are asset-first and intentionally have no `placement` field; the server compiles provider media URLs from project-owned Asset IDs and the one-time generation intent before submission.
+
+Canvas layout persistence is the deliberate exception on the UI side: drag, resize, viewport, and the complete visual arrangement are saved as a revision-checked snapshot. Semantic Canvas operations are also exposed through `canvas.apply`, and external agents must use those operations rather than snapshot replacement.
+
 ## Persistence
 
-The SQLite/D1 schema contains ten tables:
+The SQLite/D1 schema contains twelve tables:
 
 - `project`
 - `project_canvas_state`
+- `project_timeline_state`
+- `project_command_receipt`
 - `project_workflow_state`
 - `generation_history`
 - `generation_upload_intent`
@@ -40,11 +71,13 @@ The SQLite/D1 schema contains ten tables:
 - `project_asset_membership`
 - `config`
 
+`project_command_receipt` stores bounded, short-lived command results for retry idempotency and powers the current MCP history tool. It is not a permanent audit log; long-term Agent Activity still needs a separate durable event contract.
+
 No user, session, role, order, subscription, payment, credit, API-key, ticket, or CMS table belongs in this repository.
 
 ## Model catalog
 
-`src/core/effects/effect-registry.ts` is the canonical user-facing catalog. `src/core/adapters/beatapi-adapter.ts` maps that catalog to BeatAPI request bodies. Do not add a second database-backed model registry.
+`src/core/effects/effect-registry.ts` is the canonical user-facing logical catalog. `src/core/generation-providers/` maps those logical IDs to provider bindings and adapters. `src/core/adapters/beatapi-adapter.ts` contains BeatAPI request mapping. Do not leak upstream effect IDs or field names into MCP tools, and do not add a second database-backed model registry.
 
 ## Deployment boundary
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..743d64e
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to BeatDesign are documented in this file.
+
+## [0.2.0] - 2026-08-30
+
+### Added
+
+- A local stdio MCP server with 20 Project, Asset, Canvas, Generation, and Editor tools.
+- A shared Command Kernel with runtime schemas, revision checks, stable IDs, idempotent receipts, and project Asset validation.
+- Canvas-to-Editor workflows: tail-frame extraction, continuation generation nodes, Timeline nodes, and multi-asset timeline creation.
+- Local image, video, and audio import through both the UI and MCP.
+- Image clips, audio tracks, non-destructive Takes, split/trim/move/delete, undo/redo, timeline diagnostics, and browser-native MP4 export.
+- BeatAPI model capability discovery and asset-first generation contracts.
+- Codex plugin packaging plus generic MCP configuration for Claude Code, Cursor, OpenCode, and other stdio hosts.
+
+### Changed
+
+- Canvas and Editor now check for Agent/MCP revisions every two seconds and whenever the page regains focus.
+- Canvas rebases pending local layout edits onto newer Agent revisions instead of blocking visible MCP updates; snapshot restoration also removes stale shapes before rebuilding the current document.
+- Editor autosave adopts the canonical saved document and ignores timestamp-only differences, preventing repeated save echoes from blocking MCP updates.
+- Generated and imported media are persisted in project-owned local storage and indexed in SQLite.
+- External Canvas media writes require project-owned Asset IDs, and local image/video/audio imports validate type and size before reading file contents.
+- GitHub documentation now includes a product-first English/Chinese README and a BeatDesign release cover.
+
+### Current boundaries
+
+- Editor snapshots are semantic rather than pixel-rendered.
+- MP4 export remains browser-driven and is not yet available as a headless MCP tool.
+- Captions, transitions, speed controls, multiple named timelines, and native desktop packaging remain follow-up work.
+
+[0.2.0]: https://github.com/BeatAPI/BeatDesign/releases/tag/v0.2.0
diff --git a/PROVIDERS.md b/PROVIDERS.md
index 4020e0f..246b782 100644
--- a/PROVIDERS.md
+++ b/PROVIDERS.md
@@ -1,6 +1,6 @@
 # Provider configuration
 
-BeatAPI is the fixed built-in generation and analysis provider implemented by this repository. The upstream URL is intentionally fixed to `https://api.beatapi.io`; users only provide their own BeatAPI API key.
+BeatAPI is the built-in and default generation/analysis provider. The official BeatAPI adapter keeps its upstream URL fixed to `https://api.beatapi.io`; users only provide their own BeatAPI API key.
 
 Configure it in either place:
 
@@ -17,13 +17,15 @@ The adapter uses:
 - `GET /v1/tasks/:id`
 - `POST /v1/files` for supported reference files
 
-Model support is defined in `src/core/effects/effect-registry.ts`, not discovered dynamically. This keeps Canvas and Studio behavior deterministic. When adding a model, update the registry, request mapping, media capability rules, and tests together.
+User-facing model capabilities are defined in `src/core/effects/effect-registry.ts`. Provider bindings live in `src/core/generation-providers/`; MCP and UI use the logical model id and capability schema, not BeatAPI `effectId` or raw upstream fields.
 
 Kling 2.6 and Kling 3.0 Motion Control are exposed as BeatAPI models. Each run requires exactly one character image and one MP4/MOV motion video uploaded through the connected BeatAPI account. The Workspace never asks users for a KIE key; BeatAPI owns the upstream provider route, billing, polling, and output persistence.
 
 Video Analysis is exposed as a stable BeatAPI workflow with Standard and Deep depth controls. The Workspace uploads one MP4/MOV input, submits the analysis task, polls `GET /v1/tasks/:id`, and stores the returned report text and usage in the local project history. Provider-specific Gemini routing remains private to BeatAPI.
 
-An API with a different request or polling contract still needs its own adapter. This repository does not ship placeholder KIE, Vidu, Evolink, Gemini, Fal, Replicate, or payment-provider integrations.
+An API with a different request or polling contract needs its own adapter. Forks can register one in `src/config/generation-providers.ts`, bind only the logical models they support, and set server-side `GENERATION_PROVIDER=<id>`. BeatAPI is the default only when no custom provider is selected; an unknown configured id fails explicitly so it cannot accidentally submit a task to another provider. This repository does not ship placeholder KIE, Vidu, Evolink, Gemini, Fal, Replicate, or payment-provider integrations.
+
+A custom provider definition owns adapter construction, readiness checks, parameter validation, model bindings, upstream model names, and upload paths. Provider credentials must stay server-side. Switching providers does not change Canvas nodes, Editor clips, Asset IDs, or MCP requests; each submitted task also records its provider/model identity so polling does not silently follow a later default-provider change.
 
 ## Storage
 
diff --git a/README.md b/README.md
index 421a814..8db9c7d 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,62 @@
-# BeatDesign
+<p align="center">
+  <img src="./docs/assets/beatdesign-readme-cover-v3.jpg" alt="BeatDesign — one local creative workspace, controlled by any MCP-capable agent" width="100%" />
+</p>
 
-**Beat complexity. Design freely.**
+<h1 align="center">BeatDesign</h1>
 
-The open-source, local-first AI canvas for image and video creation and analysis. BeatDesign brings Projects, a guided Studio, a node-based Canvas, shared assets, generation history, configurable storage, and an official BeatAPI connection into one focused workspace.
+<p align="center">
+  <strong>One local creative workspace. Any agent.</strong><br />
+  Generate on a Canvas, edit on a timeline, and let an MCP-capable Agent operate the same project beside you.
+</p>
 
-There is no login, account system, payment flow, subscription, local credit ledger, admin panel, or API-key issuing service in this repository.
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#agent-control-through-mcp">MCP</a> ·
+  <a href="./docs/PRODUCT_PLAN_AND_STATUS.md">Product status</a> ·
+  <a href="./README.zh-CN.md">中文</a>
+</p>
 
-[中文说明](./README.zh-CN.md)
+BeatDesign is a free, open-source, local-first AI media workbench. It combines a guided Studio, an infinite Canvas, a short-form video Editor, and one shared Asset library inside a single local Project.
 
-## What is included
+The browser is your visual workspace. An Agent such as Codex, Claude Code, Cursor, or another MCP stdio host can read and modify the same Project through BeatDesign's 20 local tools. There is no account system, subscription, local credit ledger, or admin panel in this repository.
 
-- Studio for prompt-first image and video generation, plus Standard and Deep video analysis.
-- React Flow Canvas for connected, multi-step creative workflows.
-- A project-scoped Assets view shared by Studio and Canvas.
-- Local projects, snapshots, generation history, and asset indexing.
-- One code-defined catalog of supported BeatAPI image and video models.
-- BeatAPI task submission and status polling.
-- BeatAPI as the fixed built-in provider; users supply their own BeatAPI API key.
-- BeatAPI managed R2 by default, with optional bring-your-own R2/S3 storage.
-- Local connection configuration, with optional encryption at rest.
-- English and Chinese UI.
-- Local SQLite by default and Cloudflare D1 as an optional deployment target.
+## The creative loop
+
+```text
+Prompt or local media
+        ↓
+Studio / Canvas ── generate, branch, connect, reuse
+        ↓
+Shared Assets ─── image, video, audio, extracted clip, render
+        ↓
+Editor ────────── trim, split, move, mix, AI redo, export MP4
+        ↑
+Any MCP Agent ─── inspect and apply project-level commands
+```
+
+The result is one continuous workflow instead of separate AI generators, download folders, and editing tools.
+
+## One Project, four views
+
+| View | What it is for |
+| --- | --- |
+| **Studio** | Prompt-first image/video generation and Standard or Deep video analysis. |
+| **Canvas** | Connected media nodes, generation history, references, branching, and reusable outputs. |
+| **Editor** | A local short-form timeline for video, still images, and audio, with non-destructive editing and MP4 export. |
+| **Assets** | The project-scoped source of truth shared by Studio, Canvas, Editor, and MCP. |
+
+## Why it feels different
+
+- **Local by default.** Projects, Canvas snapshots, timelines, generation history, and imported media stay in the local workspace.
+- **Agent-native, not Agent-locked.** BeatDesign exposes a standard stdio MCP server instead of embedding one proprietary chatbot.
+- **Asset-first.** Generated and imported media become stable project Assets before they are placed on Canvas or Editor.
+- **One command path.** UI and MCP writes pass through the same Command Kernel, revision checks, and persisted receipts.
+- **No system FFmpeg setup.** Preview and MP4 export use browser-native WebCodecs and Mediabunny.
+- **Provider boundary is explicit.** BeatAPI is the built-in generation adapter; forks can register their own adapter without rewriting Canvas or Editor.
 
 ## Quick start
 
-Requirements: Node.js 22+ and pnpm 10+.
+Requirements: Node.js 22+, pnpm 10+, and current Chrome on macOS or Windows.
 
 ```bash
 pnpm install
@@ -33,73 +65,116 @@ pnpm db:push
 pnpm dev
 ```
 
-Open `http://localhost:3020`. Home is the default route. Opening Studio or Canvas does not create a database record until you confirm that you want to start a project. Use the connection button in a workspace header to add your own [BeatAPI API key](https://beatapi.io/dashboard/apikeys) and choose storage, or configure both through `.env.development`.
+Open [http://127.0.0.1:3020](http://127.0.0.1:3020).
 
-## How data flows
+Local import, Canvas work, timeline editing, preview, and MP4 export do not require an API key. Add your own [BeatAPI API key](https://beatapi.io/dashboard/apikeys) only when you want to generate, analyze media, or use AI redo.
 
-```text
-Studio / Canvas / Assets
-  -> local server routes
-  -> imported files saved under data/project-assets and indexed in SQLite
-  -> generation precheck and a one-time SQLite generation intent
-  -> just-in-time provider upload of the durable local reference
-  -> BeatAPI image or video task API
-  -> provider status polling
-  -> generated media copied into the local project asset directory
-  -> local generation history and asset index
-```
+## Agent control through MCP
 
-The API key and storage credentials remain server-side. Project state and history live in the local SQLite database. In local SQLite mode, imported image and video files are copied immediately into the project-owned `data/project-assets/<project-id>/` directory and indexed in SQLite before a card is added to the Canvas. Video analysis uploads MP4/MOV input through BeatAPI's file endpoint and stores the resulting text in the same project generation history. Generated images, videos, and video covers are downloaded into the same project-owned directory before the Canvas receives their URLs; provider URLs remain metadata only.
+BeatDesign runs as two local processes over the same SQLite database:
 
-Canvas state is saved as a complete project snapshot after changes, checked again every five seconds while dirty, and flushed when the page is hidden, refreshed, or closed. A populated snapshot cannot be replaced by an unconfirmed empty snapshot.
+| Process | Command | Role |
+| --- | --- | --- |
+| Visual workspace | `pnpm dev` | Opens Studio, Canvas, Editor, and Assets in the browser. |
+| Agent control plane | `pnpm --silent mcp` | Exposes project-level tools over stdio. |
 
-Selecting or dragging in a local file does not send it to a provider, but it is persisted immediately on the user's own machine so a refresh, restart, or development hot reload cannot lose it. When the user confirms Generate, the server validates the project, model, prompt, concurrency, and BeatAPI connection, then creates a short-lived, one-time generation intent in SQLite. The durable local reference is uploaded to the configured provider storage only for that confirmed generation. The intent fixes the project, model, and exact upload count, and is consumed when the billable task is submitted.
+The repository includes a root `.mcp.json` for compatible hosts and a thin Codex launcher under `integrations/codex/beatdesign`.
 
-The `data/` directory is gitignored and contains both the SQLite database and local project assets. Back up or move the directory as one unit when migrating a workspace to another machine.
+The 20 tools are grouped by durable product concepts:
 
-Storage entitlement follows BeatAPI billing. The built-in provider is fixed to the official `https://api.beatapi.io` endpoint and uses the user's BeatAPI API key. Supported image, audio, and subtitle inputs go through BeatAPI Files; an official hosted deployment can preconfigure managed R2 for video inputs that Files does not accept through the separate `BEATAPI_MANAGED_R2_*` secrets. Self-hosters may instead provide their own Cloudflare R2 or other S3-compatible endpoint, bucket, credentials, and public URL through `R2_*`. The two credential sets never fall through to each other.
+- **Project (3):** list, read, create.
+- **Asset (3):** list, read, import a local image/video/audio file.
+- **Canvas (3):** read, search, apply incremental operations.
+- **Generation (5):** discover models and parameters, submit, refresh status, read history.
+- **Editor (6):** read, edit, inspect a semantic snapshot, diagnose, deep-link a view, read command history.
 
-No shared R2 secret is committed to this repository. “Preconfigured” means the official deployment supplies its storage credentials as deployment secrets, while a source checkout uses BeatAPI managed Files for supported inputs or the operator's own bucket.
+MCP does not automate UI pixels. The Agent reads the Project, applies stable commands, and BeatDesign refreshes the visible Canvas or Editor from the same local state.
 
-## Supported model catalog
+See [MCP setup and tool boundaries](./docs/MCP.md).
 
-The canonical catalog lives in `src/core/effects/effect-registry.ts`. The current workspace exposes four image models and seven video models through one BeatAPI adapter, including Kling 2.6 and Kling 3.0 Motion Control. Update the registry and adapter together when BeatAPI's public contract changes.
+## What works today
 
-## Commands
+### Canvas and generation
 
-| Command | Purpose |
-| --- | --- |
-| `pnpm dev` | Start the local app on `127.0.0.1:3020` |
-| `pnpm typecheck` | Check TypeScript contracts |
-| `pnpm test` | Run unit and contract tests |
-| `pnpm i18n:check` | Validate English and Chinese messages |
-| `pnpm media:localize` | Copy provider-hosted media in existing project snapshots into local project storage |
-| `pnpm build` | Build the production app |
-| `pnpm db:push` | Apply the schema during local development |
-| `pnpm db:generate` | Generate a reviewable D1/SQLite migration |
-| `pnpm cf:build` | Build the Cloudflare Workers artifact |
-
-## Project structure
+- Image, video, audio, timeline, and text-oriented Canvas nodes.
+- Prompt/model/parameter configuration from one code-defined BeatAPI catalog.
+- Asset references, connected workflows, generation history, and locally persisted outputs.
+- Image/video generation plus Standard and Deep video analysis.
+- Canvas-to-Editor handoff through shared Assets and timeline nodes.
+
+### Local Editor
+
+- Video, still-image, and audio clips on a shared timeline.
+- Drag-to-trim, split, move, delete, ripple delete, and still-image duration editing.
+- Undo/redo, playback, source range selection, audio volume and fades.
+- Selected-range AI redo as non-destructive Takes.
+- Timeline diagnostics for gaps, overlaps, missing media, duration mismatches, and tiny clips.
+- Browser-side H.264/AAC MP4 export; completed renders return to project Assets.
+
+### Local persistence
+
+- SQLite project data under `data/`.
+- Project-owned media under `data/project-assets/<project-id>/`.
+- Revision-aware Canvas and Editor saving.
+- English and Chinese UI.
+- Optional Cloudflare D1 deployment target.
+
+## Data and provider boundary
 
 ```text
-src/components/beatcanvas   Canvas UI and interactions
-src/components/studio       Guided Studio UI
-src/core/adapters           BeatAPI generation adapter
-src/core/effects            Model registry and generation lifecycle
-src/core/projects           Projects and snapshots
-src/core/workspace-lib      Shared asset and workspace utilities
-src/routes/api              Local server API
-src/config/db               SQLite/D1 schema
+Browser UI / MCP
+      ↓
+Command Kernel + Project services
+      ↓
+SQLite + data/project-assets
+      ↓ only after a confirmed generation request
+Generation adapter (BeatAPI by default)
+      ↓
+Output copied back into the local Asset library
 ```
 
-See [ARCHITECTURE.md](./ARCHITECTURE.md), [PROVIDERS.md](./PROVIDERS.md), and [WORKSPACE_MODES.md](./WORKSPACE_MODES.md) for contributor details.
+API keys and storage credentials remain server-side. Selecting or dragging a local file does not send it to a provider. BeatDesign persists the file locally first and uploads only the durable project Asset required by a confirmed generation request.
+
+BeatDesign does not reproduce provider billing, balance, or rate-limit logic. It returns the provider's result or error to the UI/MCP caller. The upstream repository ships the official BeatAPI adapter; a fork can implement `BaseAdapter` and register it in `src/config/generation-providers.ts`.
+
+Read [provider architecture](./PROVIDERS.md) and [system architecture](./ARCHITECTURE.md) for the full contract.
+
+## Current v0.2 boundaries
+
+BeatDesign v0.2 is focused on local, short-form AI video workflows:
+
+- Current Chrome on macOS and Windows.
+- Common browser-decodable images, MP4/MOV video, and MP3/WAV/M4A/AAC/OGG audio.
+- One active timeline per Project and browser-memory-constrained export.
+- Canvas and Editor poll for Agent revisions every two seconds; a realtime event bus is not implemented yet.
+- Editor MCP snapshot is semantic inspection, not a rendered pixel frame.
+- Captions, transitions, speed controls, waveforms, multiple named timelines, and native desktop packaging remain follow-up work.
+
+The complete completed/planned boundary lives in [Product plan and status](./docs/PRODUCT_PLAN_AND_STATUS.md).
+
+## Developer commands
+
+| Command | Purpose |
+| --- | --- |
+| `pnpm dev` | Start the local app on `127.0.0.1:3020`. |
+| `pnpm --silent mcp` | Start the local MCP server over stdio. |
+| `pnpm typecheck` | Check TypeScript contracts. |
+| `pnpm test` | Run unit and contract tests. |
+| `pnpm i18n:check` | Validate English and Chinese messages. |
+| `pnpm build` | Build the production app. |
+| `pnpm db:push` | Apply the local SQLite schema during development. |
+| `pnpm media:localize` | Copy provider-hosted media in existing snapshots into local project storage. |
 
-## Security and deployment
+## Contributing
 
-The default development server binds to `127.0.0.1`. Connection settings are writable from the trusted local workspace only. If you expose this application to the internet, configure provider and storage credentials through deployment secrets and add your own network access control in front of the app.
+Start with [CONTRIBUTING.md](./CONTRIBUTING.md), then use:
 
-Never commit `.env.development`, local databases, or provider credentials.
+- [ARCHITECTURE.md](./ARCHITECTURE.md) for system boundaries.
+- [WORKSPACE_MODES.md](./WORKSPACE_MODES.md) for product surfaces.
+- [docs/MCP.md](./docs/MCP.md) for Agent integration.
+- [DESIGN.md](./DESIGN.md) for the BeatDesign visual language.
+- [SECURITY.md](./SECURITY.md) for local and deployment safety.
 
 ## License
 
-Licensed under the [Apache License 2.0](./LICENSE). The license covers the code, not BeatAPI trademarks, logos, service access, model-provider rights, or third-party assets. See [TRADEMARKS.md](./TRADEMARKS.md).
+BeatDesign is licensed under [Apache License 2.0](./LICENSE). The license covers the code, not BeatAPI trademarks, service access, model-provider rights, or third-party assets. The timeline contract is derived from MIT-licensed OpenReel and the browser media pipeline uses MPL-2.0 Mediabunny; see [`third_party/`](./third_party) and [TRADEMARKS.md](./TRADEMARKS.md).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 6925b08..4c7e678 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,28 +1,62 @@
-# BeatDesign
+<p align="center">
+  <img src="./docs/assets/beatdesign-readme-cover-v3.jpg" alt="BeatDesign——一个可被任意 MCP Agent 操控的本地创作工作台" width="100%" />
+</p>
 
-**化繁为简，自由创作。**
+<h1 align="center">BeatDesign</h1>
 
-开源、本地优先的 AI 图片、视频创作与分析画布。BeatDesign 将项目、Studio、节点式 Canvas、共享素材、生成历史、可配置存储和 BeatAPI 官方连接整合在一个专注的工作台中。
+<p align="center">
+  <strong>一个本地创作工作台，连接任意 Agent。</strong><br />
+  在 Canvas 上生成，在时间线上编辑，让支持 MCP 的 Agent 在旁边操控同一个项目。
+</p>
 
-本仓库不包含登录、账号、支付、订阅、本地积分、后台管理、RBAC 或 API Key 发放系统。
+<p align="center">
+  <a href="#快速开始">快速开始</a> ·
+  <a href="#通过-mcp-让-agent-操控">MCP</a> ·
+  <a href="./docs/PRODUCT_PLAN_AND_STATUS.md">产品状态</a> ·
+  <a href="./README.md">English</a>
+</p>
 
-## 包含什么
+BeatDesign 是一个免费、开源、本地优先的 AI 媒体工作台。它把引导式 Studio、无限 Canvas、短视频 Editor 和共享 Asset 素材库放进同一个本地 Project。
 
-- Studio：以提示词和参数为主的快速生成体验，并支持 Standard 与 Deep 视频分析。
-- Canvas：基于 React Flow 的多步骤节点画布。
-- Assets：Studio 与 Canvas 共用的项目素材库。
-- 本地项目、画布快照、生成历史和素材索引。
-- 由代码统一维护的 BeatAPI 图片/视频模型目录。
-- BeatAPI 任务提交、状态轮询和结果回填。
-- 内置 Provider 固定使用 BeatAPI，用户填写自己的 BeatAPI API Key。
-- 默认使用 BeatAPI 托管 R2，也允许切换到自己的 Cloudflare R2/S3。
-- Provider 与存储配置保留在服务端，可选静态加密。
-- 中英文界面。
-- 默认 SQLite，可选部署到 Cloudflare D1。
+浏览器是用户可见的创作空间。Codex、Claude Code、Cursor 或其他支持 MCP stdio 的 Agent，可以通过 BeatDesign 的 20 个本地工具读取和修改同一个 Project。本仓库不包含账号、订阅、本地积分账本、支付或管理后台。
+
+## 连续创作闭环
+
+```text
+提示词或本地素材
+        ↓
+Studio / Canvas ── 生成、分支、连接、复用
+        ↓
+共享 Assets ───── 图片、视频、音频、截取片段、成片
+        ↓
+Editor ────────── 裁剪、切分、移动、混音、AI 重做、导出 MP4
+        ↑
+任意 MCP Agent ── 读取项目并执行项目级指令
+```
+
+它把原本分散在 AI 生成器、下载文件夹和剪辑软件里的步骤，收敛成一条连续工作流。
+
+## 一个 Project，四个视图
+
+| 视图 | 用途 |
+| --- | --- |
+| **Studio** | 用提示词完成图片/视频生成，以及 Standard / Deep 视频分析。 |
+| **Canvas** | 组织媒体节点、生成历史、引用关系、分支与可复用输出。 |
+| **Editor** | 在本地时间线上编辑视频、图片和音频，并导出 MP4。 |
+| **Assets** | Studio、Canvas、Editor 和 MCP 共享的项目级素材事实层。 |
+
+## BeatDesign 的核心区别
+
+- **本地优先。** Project、Canvas 快照、时间线、生成历史和导入媒体都保存在本地工作区。
+- **Agent 原生，但不绑定某个 Agent。** BeatDesign 暴露标准 stdio MCP Server，而不是内置一个封闭聊天机器人。
+- **Asset-first。** 生成和导入的媒体先成为稳定的 Project Asset，再进入 Canvas 或 Editor。
+- **统一命令路径。** UI 与 MCP 写操作共用 Command Kernel、revision 检查和持久化 receipt。
+- **不要求安装系统 FFmpeg。** 预览和 MP4 导出使用浏览器 WebCodecs 与 Mediabunny。
+- **Provider 边界清楚。** BeatAPI 是默认内置生成适配器；fork 可以增加自己的适配器，不需要重写 Canvas 或 Editor。
 
 ## 快速开始
 
-需要 Node.js 22+ 与 pnpm 10+。
+需要 Node.js 22+、pnpm 10+，以及 macOS 或 Windows 上的新版 Chrome。
 
 ```bash
 pnpm install
@@ -31,54 +65,116 @@ pnpm db:push
 pnpm dev
 ```
 
-打开 `http://localhost:3020` 会直接进入 Home。访问 Studio 或 Canvas 不会立即写入项目数据库，只有确认开始项目后才会创建记录。点击工作台顶部的连接配置按钮，可以填写你自己的 [BeatAPI API Key](https://beatapi.io/dashboard/apikeys) 并选择存储；也可以通过 `.env.development` 配置。
+打开 [http://127.0.0.1:3020](http://127.0.0.1:3020)。
+
+本地导入、Canvas 操作、时间线剪辑、预览和 MP4 导出都不需要 API Key。只有在生成、分析媒体或使用 AI 重做时，才需要填写自己的 [BeatAPI API Key](https://beatapi.io/dashboard/apikeys)。
+
+## 通过 MCP 让 Agent 操控
+
+BeatDesign 本地运行两个进程，它们读取同一个 SQLite 数据库：
+
+| 进程 | 命令 | 作用 |
+| --- | --- | --- |
+| 可视工作台 | `pnpm dev` | 在浏览器中打开 Studio、Canvas、Editor 和 Assets。 |
+| Agent 控制面 | `pnpm --silent mcp` | 通过 stdio 暴露项目级工具。 |
 
-## 数据逻辑
+仓库根目录已经包含兼容宿主可读取的 `.mcp.json`；Codex 的轻量启动封装位于 `integrations/codex/beatdesign`。
+
+20 个工具按照稳定的产品概念分组：
+
+- **Project（3）：** 列表、读取、创建。
+- **Asset（3）：** 列表、读取、导入本地图片/视频/音频。
+- **Canvas（3）：** 读取、搜索、增量修改。
+- **Generation（5）：** 获取模型与参数、提交生成、刷新状态、读取历史。
+- **Editor（6）：** 读取、编辑、语义快照、诊断、视图深链、命令历史。
+
+MCP 不会模拟点击界面像素。Agent 读取 Project、提交稳定命令，BeatDesign 再从同一份本地状态刷新用户可见的 Canvas 或 Editor。
+
+详细接入方式见 [MCP 设置与工具边界](./docs/MCP.md)。
+
+## 当前已经支持
+
+### Canvas 与生成
+
+- 图片、视频、音频、时间线及文本向 Canvas 节点。
+- 由一份代码目录统一定义的 BeatAPI 模型、参数与引用能力。
+- Asset 引用、连接工作流、生成历史和本地持久化输出。
+- 图片/视频生成，以及 Standard / Deep 视频分析。
+- 通过共享 Asset 与时间线节点完成 Canvas-to-Editor 交接。
+
+### 本地 Editor
+
+- 视频、静态图片和音频共用一条时间线。
+- 拖动裁剪、切分、移动、删除、波纹删除，以及静态图片时长调整。
+- Undo/redo、播放、源素材范围选择、音量和淡入淡出。
+- 把选中区间交给 AI 重做，并以非破坏性 Take 保存。
+- 检查空隙、重叠、素材缺失、时长不一致和过短片段。
+- 在浏览器中导出 H.264/AAC MP4；成片会回到 Project Assets。
+
+### 本地持久化
+
+- Project 数据保存在 `data/` 下的 SQLite。
+- 项目媒体保存在 `data/project-assets/<project-id>/`。
+- Canvas 与 Editor 使用 revision-aware 保存。
+- 中英文界面。
+- 可选 Cloudflare D1 部署目标。
+
+## 数据与 Provider 边界
 
 ```text
-Studio / Canvas / Assets
-  -> 本地服务端接口
-  -> 导入文件立即保存到 data/project-assets，并写入 SQLite 素材索引
-  -> 生成预检与 SQLite 一次性生成意图
-  -> 仅在确认生成后，把已持久化的本地引用上传到 Provider
-  -> BeatAPI 图片、视频生成任务或视频分析接口
-  -> 轮询 Provider 状态
-  -> 将生成媒体复制到本地项目素材目录
-  -> 写入本地生成历史与素材索引
+浏览器 UI / MCP
+      ↓
+Command Kernel + Project services
+      ↓
+SQLite + data/project-assets
+      ↓ 仅在用户确认生成后
+Generation adapter（默认 BeatAPI）
+      ↓
+输出复制回本地 Asset 素材库
 ```
 
-API Key 与存储密钥只保留在服务端。项目和历史数据保存在本地 SQLite。在本地 SQLite 模式下，导入的图片和视频会先复制到项目自己的 `data/project-assets/<project-id>/` 目录，并写入 SQLite 素材索引，然后才加入 Canvas。视频分析会把 MP4/MOV 输入上传到 BeatAPI Files，并把返回的分析文本写入同一份项目生成历史。生成的图片、视频和视频封面都会先下载到同一个项目素材目录，Canvas 再使用对应的本地地址；Provider 地址只保留为元数据。
+API Key 和存储凭据只留在服务端。选择或拖入本地文件不会把它发送给 Provider；BeatDesign 会先把它持久化为本地 Project Asset，只有用户确认生成后，才上传该次生成真正需要的素材。
+
+BeatDesign 不重复实现 Provider 的余额、计费或限流逻辑，只把 Provider 的结果或错误返回给 UI / MCP。上游仓库内置官方 BeatAPI 适配器；fork 可以实现 `BaseAdapter`，并在 `src/config/generation-providers.ts` 中注册。
 
-Canvas 内容变化后会保存一份完整项目快照；存在未保存变化时，每 5 秒再检查一次，并在页面切到后台、刷新或关闭时强制落盘。已有内容的快照不会被未经确认的空快照覆盖。
+完整约定见 [Provider 架构](./PROVIDERS.md) 与 [系统架构](./ARCHITECTURE.md)。
 
-用户选择文件或从 Finder 拖入文件时，不会立刻发送给 Provider，但会立即持久化在用户自己的电脑上，因此刷新、重启或开发热更新都不会丢失。用户确认“生成”后，服务端先检查项目、模型、提示词、并发限制和 BeatAPI 连接，再在 SQLite 中创建短时、一次性的生成意图；只有这时，已经持久化的本地引用才会上传到配置好的 Provider 存储。意图会绑定项目、模型和准确上传数量，并在提交付费任务时被消费。
+## v0.2 当前边界
 
-`data/` 目录已被 Git 忽略，其中同时包含 SQLite 数据库和本地项目素材。把工作台迁移到另一台电脑时，应将整个目录一起备份或复制。
+BeatDesign v0.2 聚焦本地 AI 短视频工作流：
 
-存储权益跟随 BeatAPI 计费：内置 Provider 固定通过官方 `https://api.beatapi.io` 接口，并使用用户自己的 BeatAPI API Key。图片、音频和字幕通过 BeatAPI Files 进入托管存储；官方部署通过独立的 `BEATAPI_MANAGED_R2_*` Secret 预配置 R2，处理 Files 暂不支持的视频输入。源码用户也可以通过 `R2_*` 配置自己的 Cloudflare R2 或其他 S3 兼容存储。两组凭据不会互相回退。
+- 支持 macOS / Windows 上的新版 Chrome。
+- 支持常见浏览器可解码图片、MP4/MOV 视频，以及 MP3/WAV/M4A/AAC/OGG 音频。
+- 每个 Project 当前只有一条活动时间线；导出仍受浏览器内存约束。
+- Canvas 和 Editor 每两秒轮询 Agent revision；暂未实现实时事件总线。
+- Editor MCP snapshot 是语义检查，不是像素截图。
+- 字幕、转场、变速、波形、多时间线和原生桌面封装仍属于后续阶段。
 
-仓库不会内置或泄露共享 R2 密钥。所谓“默认配置好”，指官方部署通过部署 Secret 注入托管 R2；源码用户对受支持输入使用 BeatAPI 托管 Files，或自行接入自己的存储。
+完整的已完成/待完成边界见 [产品规划与当前状态](./docs/PRODUCT_PLAN_AND_STATUS.md)。
 
-## 主要命令
+## 开发命令
 
-| 命令 | 用途 |
+| 命令 | 作用 |
 | --- | --- |
-| `pnpm dev` | 在 `127.0.0.1:3020` 启动本地应用 |
-| `pnpm typecheck` | 类型检查 |
-| `pnpm test` | 单元与契约测试 |
-| `pnpm i18n:check` | 检查中英文文案 |
-| `pnpm media:localize` | 将现有项目快照中的 Provider 媒体复制到本地项目存储 |
-| `pnpm build` | 生产构建 |
-| `pnpm cf:build` | 构建 Cloudflare Workers 产物 |
-| `pnpm db:push` | 本地同步数据库结构 |
-| `pnpm db:generate` | 生成可审阅的 SQLite/D1 迁移 |
+| `pnpm dev` | 在 `127.0.0.1:3020` 启动本地应用。 |
+| `pnpm --silent mcp` | 通过 stdio 启动本地 MCP Server。 |
+| `pnpm typecheck` | 检查 TypeScript 契约。 |
+| `pnpm test` | 运行单元与契约测试。 |
+| `pnpm i18n:check` | 校验中英文消息。 |
+| `pnpm build` | 构建生产版本。 |
+| `pnpm db:push` | 在本地开发中应用 SQLite schema。 |
+| `pnpm media:localize` | 把旧 Project 快照中的 Provider 媒体复制到本地素材目录。 |
 
-## 安全提示
+## 参与贡献
 
-开发服务默认只监听 `127.0.0.1`，连接配置只允许在可信本地环境修改。如果部署到公网，请通过部署平台 Secret 配置 Provider 与存储凭据，并在应用前增加网络访问控制。
+先阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)，再按需查看：
 
-不要提交 `.env.development`、本地数据库或任何 Provider 凭据。
+- [ARCHITECTURE.md](./ARCHITECTURE.md)：系统边界。
+- [WORKSPACE_MODES.md](./WORKSPACE_MODES.md)：产品视图。
+- [docs/MCP.md](./docs/MCP.md)：Agent 接入。
+- [DESIGN.md](./DESIGN.md)：BeatDesign 视觉语言。
+- [SECURITY.md](./SECURITY.md)：本地与部署安全。
 
-## 许可证
+## License
 
-代码采用 [Apache License 2.0](./LICENSE)。许可证不授予 BeatAPI 商标、Logo、服务访问、模型供应商权利或第三方素材的使用权，详见 [TRADEMARKS.md](./TRADEMARKS.md)。
+BeatDesign 使用 [Apache License 2.0](./LICENSE)。许可证覆盖代码，不覆盖 BeatAPI 商标、服务访问、模型 Provider 权利或第三方素材。时间线契约派生自 MIT 许可的 OpenReel，浏览器媒体管线使用 MPL-2.0 Mediabunny；详见 [`third_party/`](./third_party) 与 [TRADEMARKS.md](./TRADEMARKS.md)。
diff --git a/RELEASE_SCOPE.md b/RELEASE_SCOPE.md
index ecd1e58..5edee36 100644
--- a/RELEASE_SCOPE.md
+++ b/RELEASE_SCOPE.md
@@ -6,4 +6,16 @@ Included: homepage, projects, Studio, Canvas, provider configuration, supported
 
 Excluded: authentication, login, accounts, payments, subscriptions, credits, API-key issuing, invitations, RBAC, admin, support tickets, CMS, email delivery, and unrelated AI-provider adapters.
 
-Release verification requires a clean install, schema creation, typecheck, test, i18n check, production build, and local route smoke test. A real paid BeatAPI generation is a separate credentialed end-to-end check.
+Release verification requires a clean install, schema creation, production build (which generates Paraglide and route types), typecheck, test, i18n check, MCP stdio handshake, and local route smoke test. A real paid BeatAPI generation is a separate credentialed end-to-end check.
+
+## v0.2.0 release gate
+
+- [x] Package, MCP server, and Codex plugin versions agree on `0.2.0`.
+- [x] Canvas, Editor, and MCP contracts have automated coverage.
+- [x] MCP exposes Project, Asset, Canvas, Generation, and Editor groups without full-document replacement tools.
+- [x] Local media import and image clips are documented as shipped capabilities.
+- [x] Verify a clean checkout with `pnpm install --frozen-lockfile`, schema creation, `pnpm build`, typecheck, tests, i18n, and MCP handshake—in that order.
+- [x] Run a visible Canvas/Editor + MCP smoke test: Canvas prompt changes and Editor duration changes appeared without a page refresh, then the QA fixture was restored through MCP.
+- [x] Prepare the local release branch and release documentation; GitHub push, merge, tag, and Release remain explicit external actions performed only with user authorization.
+
+Release notes are maintained in [`CHANGELOG.md`](./CHANGELOG.md).
diff --git a/SECURITY.md b/SECURITY.md
index 56e2b84..6a4040a 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -10,4 +10,4 @@ Include the affected route or component, reproduction steps, impact, and any sug
 
 BeatDesign is a single-user, local-first application and does not include authentication. The development server binds to localhost. Operators who expose it to a network must add access control in front of the application and provide provider and storage credentials through deployment secrets.
 
-The maintainers support the latest released `0.1.x` version. Security fixes are published in the next patch release when possible.
+The maintainers support the latest released `0.2.x` version. Security fixes are published in the next patch release when possible.
diff --git a/WORKSPACE_MODES.md b/WORKSPACE_MODES.md
index e0c160b..135db2c 100644
--- a/WORKSPACE_MODES.md
+++ b/WORKSPACE_MODES.md
@@ -1,15 +1,17 @@
 # Workspace modes
 
-Each project can be opened in three modes:
+Each project can be opened in four views:
 
 - **Studio** is a guided, form-first surface for image/video generation and Standard or Deep video analysis.
 - **Canvas** is a node-based surface for connected references, generation, and durable video-analysis reports.
-- **Assets** is the project-scoped library shared by Studio and Canvas.
+- **Editor** is the local timeline for arranging, trimming, splitting, previewing, and exporting short-form video.
+- **Assets** is the project-scoped media library shared by Studio, Canvas, Editor, and MCP.
 
-All three modes share the same project ID, assets, model catalog, provider connection, generation and analysis history, and persistence layer. The last opened mode is stored on the project so the project list can resume in place.
+All four views share the same project ID, Assets, model catalog, provider connection, generation and analysis history, and persistence layer. The last opened view is stored on the project so the project list can resume in place.
 
 Routes:
 
 - `/studio/:projectId`
 - `/canvas/:projectId`
+- `/editor/:projectId`
 - `/assets/:projectId`
diff --git a/docs/MCP.md b/docs/MCP.md
new file mode 100644
index 0000000..3718420
--- /dev/null
+++ b/docs/MCP.md
@@ -0,0 +1,94 @@
+# BeatDesign MCP
+
+BeatDesign exposes one local stdio MCP server. It uses the same project,
+Asset, Command Kernel, provider, and SQLite services as the browser UI; it is
+not a second backend.
+
+## Start
+
+```bash
+pnpm install
+pnpm db:push
+pnpm --silent mcp
+```
+
+For a generic MCP host, register:
+
+```json
+{
+  "mcpServers": {
+    "beatdesign": {
+      "command": "/absolute/path/to/Beat Design/node_modules/.bin/tsx",
+      "args": ["/absolute/path/to/Beat Design/scripts/mcp-server.ts"]
+    }
+  }
+}
+```
+
+The Codex plugin source is under `integrations/codex/beatdesign`. When a host
+copies that plugin outside this repository, pass `BEATDESIGN_ROOT` with the
+absolute repository path.
+
+## Mental model
+
+BeatDesign is two processes sharing one local database:
+
+1. `pnpm dev` is the visual workbench in the browser.
+2. `pnpm mcp` is the Agent control plane over stdio.
+
+An Agent never "opens the Canvas as a sidebar" inside Codex or Claude Code.
+It calls tools. You watch the same project at `http://127.0.0.1:3020`.
+
+The Codex plugin is optional packaging. Claude Code, OpenCode, Cursor, and any
+other MCP stdio host can skip it and start `pnpm --silent mcp` directly. A
+marketplace application is not required for local use.
+
+Repo-root `.mcp.json` is the Claude Code / generic host config. See
+`integrations/codex/beatdesign/README.md` for Codex folder install and
+OpenCode `mcp` config.
+
+## Tool groups
+
+There are **20** tools:
+
+- Project (3): list, get, create.
+- Asset (3): list, get by project membership, and import a local file.
+- Canvas (3): get, search, incremental apply.
+- Generation (5): list model capabilities, read one model, submit an
+  asset-first request, refresh status, and list history.
+- Editor (6): get, incremental edit, semantic snapshot, diagnostics, deep-link
+  view, and command history.
+
+MCP writes use `origin=mcp` assigned inside the server. `canvas.apply` and
+`editor.apply` accept stable IDs, revisions, and idempotency keys. The server
+does not expose full Canvas or Timeline replacement.
+
+Generation tools accept a logical `modelId`, generic `parameters`, and Asset
+references. Call `bdesign_generation_models` or
+`bdesign_generation_model_get` before choosing parameters. Outputs are Assets;
+placing them on Canvas or Editor remains a separate command.
+`bdesign_generation_submit` submits once through the configured generation
+provider. BeatDesign does not duplicate API-key validity, balance, billing, or
+rate-limit policy. BeatAPI (or a fork's selected provider) remains authoritative,
+and its response or error details are returned to the MCP caller.
+
+`bdesign_canvas_apply` and `bdesign_editor_edit` advertise every supported
+incremental operation as a concrete JSON Schema. Agents can discover required
+IDs, time fields, media roles, card parameters, Takes, and render fields from
+the MCP tool contract instead of guessing an opaque operation object.
+
+## Current boundaries
+
+- `bdesign_editor_snapshot` resolves active clips and source times; it does not
+  rasterize a pixel frame yet.
+- Browser-only MP4 export is not exposed as a headless MCP tool yet.
+- `bdesign_asset_import` copies a local image, video, or audio file into the
+  project Asset library from an absolute path. It does not place the Asset on
+  Canvas or Editor; use `bdesign_canvas_apply` or `bdesign_editor_edit` after.
+- `bdesign_asset_import` is the local-file bridge. Generation still accepts
+  project Asset IDs rather than arbitrary file paths; the shared generation
+  path performs any provider upload that is required after submission.
+- Command history is a bounded retry receipt log, not a permanent audit trail.
+- Live UI event push is not implemented. Canvas and Editor poll project
+  revisions every two seconds while idle and check again on focus/visibility,
+  so MCP writes become visible without a full event bus.
diff --git a/docs/PRODUCT_PLAN_AND_STATUS.md b/docs/PRODUCT_PLAN_AND_STATUS.md
new file mode 100644
index 0000000..65a37a1
--- /dev/null
+++ b/docs/PRODUCT_PLAN_AND_STATUS.md
@@ -0,0 +1,274 @@
+# BeatDesign 产品规划与当前完成状态
+
+- 文档用途：给新加入的开发者、Codex、Claude Code 和其他 AI Agent 提供统一产品上下文
+- 当前基线：BeatDesign v0.2 Phase 1 本地实现
+- 最后核对：2026-08-30
+- 事实边界：只有代码、测试和本文“已完成”栏目共同证明的能力才算完成；规划项不等于已发布
+- 发布状态：当前工作树已实现并完成本地工程验证，尚未据此声明 GitHub Release 或桌面端发布
+
+## 1. BeatDesign 是什么
+
+BeatDesign 是一个免费、开源、本地优先的 AI 图片/视频创作工作台。它把 Studio、节点 Canvas、项目 Assets、本地视频 Editor、生成历史和 BeatAPI 连接放在同一个 Project 中。
+
+长期产品形态：
+
+> One local creative workspace. Any agent.
+
+用户可以独立使用 BeatDesign，也可以让 Codex、Claude Code 或其他通用 Agent 通过 MCP 操控画布和编辑器。BeatDesign 不在画布里重新内置一个通用 Agent。
+
+## 2. 产品边界
+
+### 开源 BeatDesign 负责
+
+- 本地项目、素材、快照和时间线。
+- Studio、Canvas、Editor、Assets 和 Generation History。
+- 图片/视频生成、视频分析和后续音频能力入口。
+- 本地媒体处理、预览、剪辑、诊断和导出。
+- Command Kernel、MCP、CLI 和可视化交接。
+- BeatAPI 官方连接和 BYOK。
+
+### BeatAPI 服务负责
+
+- 远程 AI 模型能力。
+- 异步任务、模型路由和服务计费。
+- 用户通过自己的 BeatAPI API Key 使用服务。
+
+### 不属于本仓库
+
+- SaaS 账户、登录、支付、订阅、积分和管理后台。
+- 通用聊天 Agent、通用 Router/Planner/Executor 平台。
+- 社交平台发布、飞书连接和其他外部应用自动化。
+
+## 3. 产品架构
+
+```text
+Studio ─────┐
+Canvas ─────┼── Project / Assets / Generation / History
+Editor ─────┘                    │
+                                ▼
+                         Local SQLite + Files
+                                │
+                         BeatAPI（确认后调用）
+```
+
+- Studio：引导式单次生成和分析。
+- Canvas：复杂生成、参考素材、分支和血缘。
+- Editor：时间组织、剪辑、音频、字幕和交付。
+- Assets：媒体事实来源，所有工作空间共享。
+
+未来 Agent 架构：
+
+```text
+Codex / Claude Code / Other Agent
+               │
+          BeatDesign MCP
+               │
+          Command Kernel
+               │
+ Studio / Canvas / Editor / Assets / Generation
+```
+
+## 4. 统一术语
+
+| 名称 | 含义 |
+|---|---|
+| Asset | 本地真实媒体文件及其元数据 |
+| Canvas Node | Asset、Generation 或 Timeline 在画布上的引用 |
+| Generation | 产生 Asset 的异步任务，不绑定单一 placement |
+| Timeline | 项目级剪辑文档 |
+| Clip | Asset 在 Timeline 上的一次使用 |
+| Take | 同一 Clip 的备选媒体版本，可恢复 Original |
+| Canvas Edge | 用户视觉组织关系 |
+| Generation Lineage | 真实生成或派生来源关系 |
+| Command Kernel | UI、MCP、CLI 共用的唯一业务操作层 |
+
+## 5. 已完成并有代码支撑的能力
+
+### Project / Local-first
+
+- 项目创建、打开、重命名和本地 SQLite 持久化。
+- Canvas Snapshot 自动保存、页面隐藏时刷新和版本冲突保护。
+- 本地上传图片、视频、音频后立即复制到项目目录。
+- 生成图片、视频和封面在展示前本地化。
+- 项目 Assets 和生成历史索引。
+- BeatAPI 与存储凭证保留在服务端。
+
+### Studio / Canvas
+
+- Studio 图片、视频生成和 Standard/Deep 视频分析。
+- React Flow 节点 Canvas。
+- 图片、视频、音频 Asset Node。
+- 图片/视频 Generation Node、Generation Output 与多个版本。
+- 模型、提示词、画幅、时长、质量和参考素材配置。
+- Canvas 节点连接、分组、复制、删除、撤销/重做。
+- 音频节点和 Timeline Node。
+- Asset、Canvas、Editor 之间的基础导航。
+
+### Editor
+
+- 项目级 TimelineDocument、Video/Audio Track、Clip 和 Take。
+- 视频和音频导入。
+- 非破坏式 trim、split、move、delete 和 ripple delete。
+- undo/redo。
+- 音量、静音、淡入和淡出。
+- 浏览器本地预览。
+- 选区派生 MP4。
+- BeatAPI 选区 AI redo。
+- Redo 结果作为 Take 保存、激活和恢复 Original。
+- 完整 Timeline H.264/AAC MP4 导出。
+- 导出写回 Assets 和 Canvas Timeline Node。
+- 缺失素材、Clip 重叠和视频轨空隙诊断。
+- Editor 自动保存统一走 Command Kernel；并发写入使用 revision/CAS 和三方合并，不再用旧文档覆盖新版本。
+- 同一次加入时间线使用稳定 Clip ID 和幂等键，重复点击、网络重试不会重复插入同一批 Clip。
+- Take 必须覆盖 Clip 时长；过短 Take 不可激活，诊断会阻止可能产生冻结尾帧的导出。
+
+### 媒体技术
+
+- 使用 WebCodecs + Mediabunny 在浏览器完成媒体检查、编码和 MP4 封装。
+- 不要求用户安装系统 FFmpeg。
+- OpenReel 只作为时间线术语、文档模型和非破坏式编辑行为的参考；未打包其完整 UI 和应用外壳。
+- 媒体 metadata 采用限并发队列并带超时释放；单个损坏媒体不会永久阻塞后续卡片。
+
+### Command Kernel / Agent-ready 基础
+
+- `POST /api/app/projects/:id/commands` 是 Canvas/Editor 业务命令的统一写入口。
+- 命令请求使用严格运行时 Schema，拒绝未知命令、缺少稳定 ID 的 Clip/Take 操作和越界参数。
+- 命令中的 Asset 会按当前 Project membership 重新验证，并由服务端写入权威媒体 URL。
+- `project_command_receipt` 保存短期幂等回执；同一项目和幂等键只执行一次，并有限时、限量清理。
+- 幂等键会绑定首次 command；复用到另一个 command 会返回 `INVALID_COMMAND`，不会静默冒用旧结果。
+- UI 内部允许 revision-checked `editor.replace_document` 支撑 undo/redo 和本地自动保存；MCP/CLI 被明确禁止整份替换，只能调用 `editor.apply`。
+- Generation 的 `AssetFirstGenerationRequest` 已成为服务端权威输入：适配器媒体参数由 Asset ID 和当前 generation intent 编译，旧的客户端 URL 字段不再决定引用事实。
+- UI 命令入口不再接受客户端 `origin`；服务端固定写入 `ui`，MCP 入口在内核边界固定写入 `mcp`。
+- Provider Contract 已将逻辑模型目录与 BeatAPI effectId、上传路径和上游模型名拆开；BeatAPI 是默认实现，Fork 可在源码扩展点注册其他 Provider。
+- 本地 stdio MCP Server 提供 20 个工具（Project / Asset / Canvas / Generation / Editor），模型和参数通过 capability discovery 暴露；Canvas / Editor 增量操作使用完整 JSON Schema，Agent 可直接发现操作类型和参数。MCP 生成直接调用当前 Provider，本地产品不重复实现 API Key、余额、计费或限流策略，只透传 Provider 的结果与错误。`bdesign_asset_import` 把本地文件导入项目 Asset 库。
+
+## 6. v0.2 Phase 1 本地已实现
+
+主 PRD：[BEATDESIGN_V0_2.md](./prd/BEATDESIGN_V0_2.md)
+
+- 统一 asset-first 产品模型。
+- Command Kernel 基础、严格请求 Schema、Project Asset 边界和短期幂等回执。
+- Canvas 视频尾帧提取。
+- 使用尾帧创建下一段视频生成节点。
+- 多个 Canvas 视频一次创建/追加时间线。
+- Canvas -> Timeline Node -> Editor 连续工作流。
+- Editor 自动保存接入命令入口，并补齐冲突三方合并、重复操作保护和稳定播放头时间。
+- 图片 Clip、时间线拖拽调整持续时间与图片/视频统一视觉轨。
+- 本地 MCP Server 提供 20 个 Project、Asset、Canvas、Generation、Editor 工具；支持从绝对路径导入本地素材。
+- Canvas 与 Editor 每 2 秒并在页面重新聚焦时检查 MCP 写入的新 revision。
+
+本阶段的本地验收边界：类型检查、自动测试、国际化检查、生产构建和浏览器关键路径。Git 提交、远端合并和公开 Release 属于后续独立状态。
+
+2026-08-30 浏览器实操证据：保留了本地项目 `v0.2 QA – Canvas-to-Editor`。一段 10.01 秒本地 MP4 已完成“尾帧提取 -> 派生图片 Asset -> 下一段视频 Generation Node -> Timeline Node -> 打开 Editor -> 裁取 3.00–7.00 秒 -> 得到 4.00 秒 Clip -> 导出 H.264/AAC MP4 -> Render 写回 Assets”的闭环。实操同时发现并修复了开发服务器把 `Sec-Fetch-Dest: video/image/audio` 错当成静态文件、导致本地媒体 404 的问题。
+
+2026-08-30 本轮内核验收：未知 command 返回 `INVALID_COMMAND`；伪造 Asset 返回 `NOT_FOUND`；相同幂等键连续提交两次只产生一条回执且返回同一 revision；`origin=mcp` 的整份 Timeline 替换被拒绝。本地 MCP 工具目录为 20 个；Canvas / Editor 操作的完整 JSON Schema、未知 command、伪造 Asset、幂等回执、MCP 本地素材导入和 `origin=mcp` 禁止整份 Timeline 替换均有自动测试覆盖。发布门禁的最新测试数量以仓库当前 `pnpm test` 结果为准。
+
+2026-08-30 MCP 可见联调证据：在已打开的本地 Canvas 中，通过 stdio MCP 修改生成节点提示词，页面在轮询周期内自动显示新内容；在已打开的 Editor 中，通过 `bdesign_editor_edit` 把图片 Clip 从 4.00 秒改为 3.50 秒，时间线和素材信息同步更新，无需刷新。联调完成后，Canvas 提示词与 Editor 时长均通过 MCP 恢复原值。该联调同时修复了 Canvas 在存在待保存本地布局时跳过 Agent revision 的问题。
+
+## 7. 尚未完成
+
+### 产品 P1
+
+- 字幕轨、SRT 导入、字幕样式和转录入口。
+- 时间线吸附、缩放、音频波形和多选。
+- 变速和音频变速策略。
+- 交叉溶解、淡入淡出、黑场转场。
+- 合成 Preview Frame、短区间预览和更完整 Diagnostics。
+- AI Bridge 衔接片段。
+- 多个命名 Timeline。
+- 更广的浏览器/编码兼容矩阵和代理媒体。
+
+### Agent / MCP 后续边界
+
+- MCP Resources 和更完整的 schema versioning。
+- Agent Activity、命令审计和实时 UI 事件桥。
+- Claude Code 等宿主的一键安装体验；Codex 当前只有仓库内薄插件封装。
+- headless 预览/导出本地媒体 Worker。
+
+当前可以称为“已支持本地 MCP 基础版”，但不能称为完整 Agent 编辑环境：像素级 Snapshot、headless 导出、实时 UI 事件和永久审计仍未实现。本地文件导入桥已完成；UI 当前使用 2 秒 revision 轮询和聚焦检查，而不是实时事件推送。
+
+Canvas 的拖拽、缩放、视口和完整布局仍使用 revision-checked Snapshot 自动保存；Canvas/Timeline 业务 operation 已有 Command 合同，Timeline Node 回写也已接入 `/commands`。后续做 MCP parity 时，应继续把可语义化的 Canvas UI 动作迁移为 `canvas.apply`，不能让外部 Agent 调用完整 Snapshot 覆盖。
+
+### 桌面端
+
+- Electron/Tauri 壳。
+- 内置 Node runtime、MCP 和媒体 Worker。
+- 原生文件选择、系统集成、签名、公证和自动更新。
+- 需要时再评估内置原生 FFmpeg；当前开源 localhost 版本不要求它。
+
+## 8. 路线图
+
+### v0.2：Canvas-to-Editor Creative Loop
+
+- 统一模型和 Command Kernel。
+- 尾帧续写。
+- 多片段创建时间线。
+- 人工操作闭环稳定。
+
+### v0.3：Short-form Completion
+
+- 图片、字幕、变速、基础转场。
+- 波形、吸附和预览诊断。
+- AI Bridge。
+
+### v0.4：Agent Control
+
+- 本地 MCP Server 基础版已前置完成。
+- UI/MCP parity tests。
+- Codex 优先接入。
+- Agent 操作实时可见、可撤销、可审计。
+
+### v0.5：Desktop Experience
+
+- 桌面壳、一键安装、后台媒体 Worker。
+- 更稳定的大文件和长任务处理。
+
+## 9. 必须保持的设计原则
+
+1. 没有 Agent 时，BeatDesign 仍然是完整可用的产品。
+2. 每次生成先形成 Asset，再由 Canvas 或 Editor 引用。
+3. Editor 锁定具体 Asset，不自动跟随 Canvas 切换版本。
+4. UI、MCP 和 CLI 必须调用同一个 Command Kernel。
+5. MCP 不直接写 SQLite，不盲目覆盖完整 Snapshot。
+6. 本地操作不自动把素材上传到外部服务。
+7. 付费生成必须经过 precheck 和用户确认。
+8. Agent 操作必须可见、可撤销、可验证。
+9. 生成操作和确定性剪辑/转码必须区分。
+10. 开源仓库不混入 SaaS 账户、支付和积分系统。
+
+## 10. 新 AI 接手时的阅读顺序
+
+1. `AGENTS.md`
+2. 本文 `docs/PRODUCT_PLAN_AND_STATUS.md`
+3. `docs/prd/BEATDESIGN_V0_2.md`
+4. `README.md`
+5. `ARCHITECTURE.md`
+6. `PROVIDERS.md`
+7. `docs/prd/VIDEO_TIMELINE_PHASE_1.md`
+
+修改产品前先运行：
+
+```text
+git status --short
+pnpm typecheck
+pnpm test
+pnpm i18n:check
+pnpm build
+```
+
+不要把“本地测试通过”“代码存在”“GitHub 已推送”“桌面端已发布”混为同一种完成状态。
+
+## 11. 交给其他 AI 的检查清单
+
+请先保持本文的产品边界，不要把 SaaS Template、内置通用 Agent 或桌面壳提前混入本阶段。然后重点检查：
+
+1. `docs/prd/BEATDESIGN_V0_2.md` 的每条 Phase 1 验收标准，是否有对应实现和测试证据。
+2. Canvas 与 Editor 的写操作是否真正复用 `src/core/commands/`，有没有 UI 独有且 MCP 未来无法复用的第二套业务逻辑。
+3. Timeline Clip 是否始终引用具体 Asset；Canvas 切换 Generation pinned output 时，是否可能静默改变已经剪好的片段。
+4. 多素材加入 Timeline 的顺序、重复调用、版本冲突重试和部分失败，是否会产生重复 Clip 或丢失更新。
+5. 尾帧提取面对无效历史 URL、跨域媒体、零时长/极短视频和不支持解码的编码格式时，错误是否可理解且不留下半成品节点。
+6. Canvas Snapshot 与 Timeline revision/CAS 是否覆盖 UI 与未来 MCP 并发写入；MCP 是否能避免整份覆盖文档。
+7. 新增依赖、OpenReel 派生合同和 Mediabunny 使用是否满足许可证归档与分发要求。
+8. 使用一段本地视频完整走通：Canvas 选中视频 -> 尾帧续写节点 -> 多选片段 -> 创建 Timeline -> trim/split -> 导出 MP4 -> Render 回到 Assets/Canvas。
+
+审查输出请区分：阻断问题、Phase 1 应修问题、v0.3 建议和纯偏好；不要把 v0.3 功能缺失当成 v0.2 回归。
diff --git a/docs/assets/beatdesign-readme-cover-v3.jpg b/docs/assets/beatdesign-readme-cover-v3.jpg
new file mode 100644
index 0000000..d7a2558
Binary files /dev/null and b/docs/assets/beatdesign-readme-cover-v3.jpg differ
diff --git a/docs/prd/BEATDESIGN_V0_2.md b/docs/prd/BEATDESIGN_V0_2.md
new file mode 100644
index 0000000..c3ac7d0
--- /dev/null
+++ b/docs/prd/BEATDESIGN_V0_2.md
@@ -0,0 +1,261 @@
+# BeatDesign v0.2 主 PRD：Canvas-to-Editor Creative Loop & Agent Control
+
+- 状态：Phase 1 与 MCP v0.2 adapter implemented locally
+- 目标版本：v0.2
+- 产品范围：BeatDesign 开源本地工作台
+- 更新时间：2026-08-30
+- 关联文档：[产品规划与完成状态](../PRODUCT_PLAN_AND_STATUS.md)
+
+## 1. 产品结论
+
+BeatDesign v0.2 的目标不是在画布里增加一个内置聊天 Agent，而是把 BeatDesign 建成通用 Agent 可操控的本地视觉创作运行环境。
+
+产品有三个用户可见工作空间：
+
+1. Studio：最快完成一次生成或分析的引导式入口。
+2. Canvas：组织素材、生成节点、版本分支和生成血缘。
+3. Editor：组织时间、精确剪辑、音频、字幕、预览和导出。
+
+三者共享同一个 Project、Assets、Generation、Media 和 History。Generation 是共享能力，不是第四个工作空间。
+
+```text
+通用 Agent / 用户界面
+        │
+        ▼
+BeatDesign Command Kernel
+        │
+        ├── Project / Assets
+        ├── Canvas
+        ├── Generation
+        └── Editor
+                │
+                ▼
+       SQLite + 本地媒体 + BeatAPI
+```
+
+## 2. v0.2 主链路
+
+本版本必须让用户先手动、后由 Agent 完成同一条创作链路：
+
+```text
+在 Canvas 生成视频 A
+  -> 从 A 提取尾帧
+  -> 以尾帧为下一段首帧创建视频生成节点 B
+  -> 继续生成 B / C
+  -> 选择 A、B、C 创建或追加 Timeline
+  -> 在 Editor trim / split / move / delete
+  -> 选择局部范围执行 BeatAPI AI redo
+  -> 在 Original 与多个 Take 之间切换
+  -> 诊断时间线
+  -> 导出 MP4
+  -> Render 回到 Assets 与 Canvas Timeline Node
+```
+
+## 3. 统一产品模型
+
+### 3.1 Project
+
+唯一项目边界。Studio、Canvas、Editor 和 Assets 都是同一 Project 的视图，不创建第二套后端或媒体副本。
+
+### 3.2 Asset
+
+本地媒体事实来源。每次上传、生成、帧提取、片段截取和时间线导出都先形成 Asset。
+
+Asset 可以被 Canvas Node、Timeline Clip、Generation Reference 同时引用。删除视图中的引用不等于删除 Asset。
+
+### 3.3 Canvas Node
+
+Canvas 对 Asset、Generation 配置或 Timeline 的可视化引用。节点位置和连线表达用户当前的组织意图，不自动等价于生成血缘。
+
+### 3.4 Generation
+
+产生 Asset 的异步任务。核心请求不包含单一 `placement` 字段；生成完成后由 Canvas、Editor 或 Studio 再引用结果 Asset。
+
+### 3.5 Timeline / Clip / Take
+
+- Timeline：项目级剪辑文档。
+- Clip：一个 Asset 在时间线上的一次使用，保存 start、in/out、duration 和音频参数。
+- Take：同一 Clip 时间槽的备选媒体版本。激活 Take 不改变原 Clip 的位置和原始 Asset，可随时恢复 Original。
+
+### 3.6 两类关系
+
+1. Canvas Edge：用户排列、连接和关注关系。
+2. Generation Lineage：真实的 `derived_from`、`first_frame`、`last_frame`、`continuation_of`、`redo_of`、`timeline_render` 等来源关系。
+
+本轮先在派生 Asset metadata 与 Canvas 引用中记录尾帧和时间线关系；后续升级为独立可查询的 lineage contract。
+
+## 4. Canvas 与 Editor 的结合
+
+### 4.1 Canvas -> Editor
+
+- 单个视频或音频：加入当前时间线。
+- 多个视频：按照显式选择顺序创建/追加时间线。
+- 创建 Timeline Node，展示时长、Clip 数量和最近 Render。
+- Timeline Node 打开 `/editor/:projectId`。
+
+### 4.2 Editor -> Canvas
+
+- 将 Timeline Node 写回 Canvas。
+- 导出 Render 更新 Timeline Node。
+- 截取片段保存为派生 Asset。
+- AI redo 结果保存为 Asset 并挂为 Clip Take。
+- 后续支持从 Editor 展开某次生成在 Canvas 中的完整血缘。
+
+### 4.3 稳定引用规则
+
+Editor Clip 必须引用具体 `assetId`，不能动态跟随 Canvas Generation Node 的当前 pinned output。Canvas 切换版本时，Editor 只有在用户明确确认后才能替换 Clip。
+
+## 5. v0.2 功能范围
+
+### P0：本轮
+
+- 统一产品术语与 asset-first Generation contract。
+- Command Kernel 基础合同。
+- Editor 现有核心操作接入统一 command executor。
+- 视频尾帧本地提取并保存为派生 Asset。
+- 尾帧节点与下一段视频 Generation Node 自动创建。
+- 多选 Canvas 视频创建/追加时间线。
+- Timeline Node 在 Canvas 中可见并可打开 Editor。
+- revision/CAS 保持现有保护。
+- Command 请求运行时 Schema、Project Asset 校验、稳定 ID 和短期幂等回执。
+- Editor 并发保存三方合并；MCP/CLI 只能执行增量 `editor.apply`，不能整份替换时间线。
+- Generation 服务端从 Asset ID 与 generation intent 编译权威媒体输入。
+- 图片 Clip 与可拖动的图片持续时间。
+- MCP 本地素材导入桥与 2 秒 UI revision 同步。
+- 单元测试、类型检查、i18n 和生产构建通过。
+
+### P1：产品成片能力
+
+- 字幕轨和 SRT 导入。
+- 时间线吸附、缩放、波形和多选。
+- 变速。
+- 交叉溶解、淡入淡出和黑场过渡。
+- 合成帧 Preview 与更完整 Diagnostics。
+- AI Bridge：使用前后帧生成衔接片段。
+
+### P2：Agent Control
+
+- 本地 MCP Server。`已完成基础版`
+- Project、Canvas、Editor、Assets、Generation 工具组。`已完成基础版`
+- 模型 capability discovery。`已完成`
+- 只读 MCP Resources。`未完成`
+- 付费生成确认、幂等键、结构化结果和操作历史。
+- Agent 修改后 UI 实时刷新。
+- Codex 优先接入，Claude Code 和其他宿主使用同一协议。
+
+## 6. Command Kernel
+
+Command Kernel 是 UI、MCP 和未来 CLI 的唯一写入入口。MCP 不直接修改 SQLite，也不整份覆盖 Canvas Snapshot。
+
+统一结果目标：
+
+```ts
+type CommandResult = {
+  ok: boolean;
+  projectId: string;
+  commandId: string;
+  changedIds: string[];
+  revision?: number;
+  warnings: string[];
+  jobId?: string;
+  editorUrl?: string;
+};
+```
+
+第一阶段命令域：
+
+```text
+project.*
+asset.*
+canvas.apply
+generation.prepare / submit / status / cancel
+editor.apply / validate / export
+```
+
+所有写命令必须支持稳定 ID、预期 revision、幂等和可审计 origin。API Key、余额、计费和限流由所选 Provider 后端负责；BeatDesign 只提交请求并呈现返回结果或错误。外部上传、不可恢复删除和覆盖导出仍保留明确确认边界。
+
+## 7. MCP 工具目录
+
+MCP 是 Command Kernel 的薄适配层，不重新实现业务逻辑。
+
+```text
+Project:    list / create / get / open
+Canvas:     get / apply / search / focus
+Editor:     get / apply / preview / validate / focus / history / export
+Assets:     list / import / inspect
+Generation: models / prepare / submit / status / cancel
+```
+
+工具返回 Asset ID、本地 URL、节点 ID、Clip ID、revision 和 job status，不通过 MCP 传输大型视频二进制。
+
+## 8. 交互要求
+
+### 8.1 视频节点“继续生成”
+
+1. 用户选择一个有本地 URL 的视频 Asset 或 Generation Output。
+2. 点击“尾帧续写”。
+3. BeatDesign 在浏览器本地解码最后一个可用画面。
+4. PNG 保存到项目 Assets，metadata 标记 `video_tail_frame`。
+5. Canvas 在原视频右侧创建尾帧 Asset Node。
+6. Canvas 在尾帧右侧创建视频 Generation Node，并把尾帧作为首帧参考。
+7. Composer 自动聚焦到新节点，用户填写下一段提示词后确认生成。
+
+### 8.2 多片段创建时间线
+
+1. 用户按顺序选择多个可用视频结果。
+2. 点击“创建时间线”。
+3. BeatDesign 一次读取并持久化时间线，避免逐个写入产生冲突。
+4. Clip 按选择顺序首尾排列。
+5. Canvas 创建或更新 Timeline Node，并连接所选视频。
+6. 用户点击 Timeline Node 打开 Editor。
+
+## 9. 安全与失败边界
+
+- 文件选择和帧提取保持本地，不因选择或预览自动上传给 BeatAPI。
+- 尾帧只在用户明确触发后写入项目本地 Assets。
+- 生成仍走现有 precheck 和一次性 intent；Provider 后端是 API Key、余额、计费与限流状态的唯一事实来源。
+- Timeline 与 Canvas 保存继续使用 revision/CAS。
+- 多操作命令必须原子应用到内存文档，再执行一次持久化。
+- 页面未打开时，浏览器预览与导出不可假装完成；未来由本地媒体 Worker 承接 headless 执行。
+
+## 10. 验收标准
+
+### 人工闭环
+
+- 从本地视频或生成结果成功提取尾帧。
+- 尾帧成为可复用 Asset，并在刷新后仍存在。
+- 新视频 Generation Node 正确引用尾帧。
+- 两个以上视频可以一次创建连续 Timeline。
+- Timeline Node 可打开 Editor。
+- Clip 顺序、时长和 Asset 引用正确。
+- 原有 trim、split、move、delete、AI redo、Take、导出无回归。
+
+### Agent-ready 内核
+
+- Editor operations 可由纯 command executor 调用。
+- Canvas operations 有稳定 contract 和纯文档 executor。
+- Generation request 是 asset-first 且不绑定单一 placement。
+- 命令结果结构可被后续 MCP 直接包装。
+- 未知命令、非本项目 Asset 和 MCP 整份 Timeline 替换会被拒绝。
+- 相同幂等键的重试返回同一持久化结果，不重复创建 Clip。
+- 幂等键复用于不同 command 时必须失败，不能返回不相关的旧结果。
+
+### 工程门禁
+
+```text
+pnpm typecheck
+pnpm test
+pnpm i18n:check
+pnpm build
+```
+
+当前基础版不暴露整份 Snapshot 替换；`editor.snapshot` 是语义时间点快照，像素预览、浏览器导出、本地文件导入和 UI 实时事件桥仍未完成。
+
+## 11. 本版本非目标
+
+- 不内置通用聊天 Agent。
+- 不实现多个宿主的完整一键安装器与 headless 媒体 Worker。
+- 不引入完整 OpenReel 应用外壳。
+- 不要求系统安装 FFmpeg。
+- 不做桌面签名、公证和自动更新。
+- 不做多人协作、云项目同步、支付和账户系统。
diff --git a/docs/prd/VIDEO_TIMELINE_PHASE_1.md b/docs/prd/VIDEO_TIMELINE_PHASE_1.md
new file mode 100644
index 0000000..a77efde
--- /dev/null
+++ b/docs/prd/VIDEO_TIMELINE_PHASE_1.md
@@ -0,0 +1,826 @@
+# BeatDesign 视频时间线与音频画布第一阶段 PRD
+
+- 状态：Draft for implementation
+- 目标版本：Phase 1 / localhost open-source release
+- 产品范围：BeatDesign 开源仓库，不包含 SaaS Template
+- 主要参考：Updream 的画布—编辑器闭环、MiniMax Design 的 OpenReel 编辑器集成
+- 更新时间：2026-08-29
+
+## 1. 产品结论
+
+下一阶段将 BeatDesign 从“本地 AI 图片/视频生成画布”升级为“本地优先的 AI 视频创作工作台”。
+
+产品由两个互补工作空间组成：
+
+1. Canvas：负责素材、提示词、生成任务、版本和来源关系。
+2. Editor：负责时间线、精确裁剪、音频、字幕、预览和 MP4 导出。
+
+第一阶段只完成 GitHub 开源版和 localhost 工作流。Electron 桌面壳、通用 Plugin SDK、MCP/CLI 和内置 Agent 均不在本阶段范围内。
+
+第一阶段必须跑通的唯一主链路：
+
+```text
+BeatAPI 生成 10 秒视频
+  -> 视频本地化为 Asset
+  -> 添加到时间线
+  -> 截取其中 3-4 秒
+  -> 导出 MP4
+  -> 将选区交给 BeatAPI 重做
+  -> 新结果作为 Take 返回原 Clip
+  -> 替换并再次导出
+  -> 导出结果回到 Canvas
+```
+
+## 2. 为什么现在做
+
+当前 BeatDesign 已具备：
+
+- Project、Studio、Canvas、Assets 和 Generation History。
+- 图片与视频生成、视频分析和 BeatAPI 连接。
+- 本地 SQLite、项目快照和本地项目素材目录。
+- 生成结果自动本地化和素材来源记录。
+- 底层 `AssetType` 已包含 `audio`。
+
+当前关键缺口：
+
+- Canvas 只能正式表达图片、视频和分析结果，不能表达音频素材。
+- 没有 TimelineDocument、Track、Clip、Take 和 Render Job。
+- 不能从生成视频中精确选择一个范围。
+- 不能组合多个生成片段并导出一个成片。
+- 不能将时间线选区重新送入 BeatAPI 并无损替换。
+
+## 3. 产品目标与非目标
+
+### 3.1 目标
+
+1. 用户克隆仓库后，只需安装项目依赖并启动 localhost，不需要单独安装 FFmpeg。
+2. 将 OpenReel 编辑能力作为第一方模块集成到 BeatDesign。
+3. 支持视频、图片和音频素材进入同一时间线。
+4. 支持非破坏式 trim、split、move、delete 和 undo/redo。
+5. 支持 1080p MP4/H.264/AAC 导出。
+6. 支持导出到本地下载，也支持保存为 BeatDesign 项目素材并创建 Canvas 节点。
+7. 支持选区生成派生素材并调用 BeatAPI 重做。
+8. 支持一个 Clip 保留多个 Take，并允许预览、切换和替换。
+9. 增加 Canvas 音频素材节点，并打通音频到时间线的路径。
+10. 保持当前 BeatDesign 视觉系统和本地优先边界。
+
+### 3.2 非目标
+
+- 不做 Electron、macOS 签名、公证和自动更新。
+- 不分发原生 FFmpeg 二进制。
+- 不做通用 Plugin SDK。
+- 不做 MCP、CLI 或画布内聊天 Agent。
+- 不做完整剪映、Premiere 或 DaVinci 功能对齐。
+- 不承诺 4K 长视频、ProRes、多机位和电影级调色。
+- 不做多人协作、云项目同步和素材市场。
+- 不做完整 Skill 商店；可在后续独立维护示例 Skill 集合。
+
+## 4. 第一阶段用户范围
+
+主要用户：
+
+- 使用 BeatAPI 生成图片和短视频的独立创作者。
+- 希望在本机管理素材、选择片段并快速重做的 AI 视频开发者。
+- 希望通过 GitHub 直接运行一个完整 AI 视频工作台的开源用户。
+
+建议第一阶段媒体边界：
+
+- 项目时长：5-120 秒。
+- 默认输出：1920x1080、30 FPS、MP4、H.264/AAC。
+- 首发浏览器：Chrome 稳定版；Edge 作为兼容目标。
+- 素材：MP4/MOV 视频、PNG/JPEG/WebP 图片、MP3/WAV/M4A/AAC 音频。
+- 一个主视频轨、最多两个附加视频/图片轨、最多三个音频轨、一个字幕轨。
+
+## 5. 信息架构
+
+现有 AppShell 模式从：
+
+```text
+Studio | Canvas | Assets
+```
+
+扩展为：
+
+```text
+Studio | Canvas | Edit | Assets
+```
+
+`Edit` 是项目级视图，不创建第二套 Project。进入方式包括：
+
+- 顶部 WorkspaceSwitcher 的 Edit。
+- 视频节点上下文工具栏中的“添加到时间线”。
+- Timeline Node 中的“打开编辑器”。
+- Assets 中素材菜单的“添加到时间线”。
+
+项目层级：
+
+```text
+Project
+├── CanvasSnapshot
+├── Assets
+├── Generations
+└── Timelines
+    ├── Timeline A
+    └── Timeline B
+```
+
+## 6. Canvas 新增节点
+
+### 6.1 Audio Asset Node
+
+第一阶段必须新增音频素材节点。它代表可连接、可播放、可送入时间线或模型的音频 Asset，不承担精确音频编辑。
+
+字段：
+
+```text
+id
+assetId
+type: audio
+audioRole: music | voice | sound_effect | source_audio | reference
+name
+url
+durationSec
+waveformPeaks
+sourceGenerationId?
+sourceAssetId?
+```
+
+节点能力：
+
+- 播放、暂停、跳转。
+- 显示波形、时长和音频用途。
+- 添加到当前时间线。
+- 作为 BeatAPI reference/driving audio。
+- 从视频节点“提取音频”后生成。
+- 展示本地化、缺失和失败状态。
+
+节点视觉：
+
+- 推荐尺寸 320x104。
+- 使用 `--beat-surface`、`--beatcanvas-line` 和 8px 圆角。
+- 波形使用冷蓝 `--beat-graph`，不使用新的紫色或绿色品牌色。
+- Play 按钮使用中性高对比色；只有生成、重做、导出等主动作使用橙色。
+- 时间码使用 Geist Mono 和 tabular numerals。
+- 被选中时沿用 Canvas 冷蓝边框和外发光。
+
+### 6.2 Timeline Node
+
+Timeline Node 是 Canvas 对一个 TimelineDocument 的入口和结果摘要，不把完整时间线塞进无限画布。
+
+字段：
+
+```text
+id
+timelineId
+name
+durationSec
+aspectRatio
+lastRenderAssetId?
+coverAssetId?
+clipCount
+updatedAt
+```
+
+节点能力：
+
+- 打开编辑器。
+- 接收图片、视频、音频 Asset 连接。
+- 显示最新成片封面、项目时长和 Clip 数量。
+- 导出成功后更新最新 Render。
+- 将 Render 拖出/连接到下游生成节点。
+
+节点视觉：
+
+- 推荐尺寸 360x220。
+- 上部为 16:9/9:16 预览区域，下部为简化时间线条带。
+- 节点标签使用 `Timeline` 或本地化名称，不命名为 Plugin。
+- “打开编辑器”是中性导航动作；“导出”与“AI 重做”才使用橙色主动作。
+
+### 6.3 Derived Clip Asset
+
+截取选区后创建新的 Video Asset Node，而不是创建新的特殊节点类型。
+
+通过 metadata 表达：
+
+```text
+assetClass: derived
+parentAssetId
+sourceInSec
+sourceOutSec
+operation: timeline_extract
+timelineId
+clipId
+```
+
+节点显示“截取 3.2-6.8s”等来源徽标。
+
+### 6.4 本阶段不新增的节点
+
+- 不新增独立 Music、Voice、Sound Effect 节点类型；统一为 Audio Asset + audioRole。
+- 不新增 Subtitle Canvas Node；字幕第一阶段属于 TimelineDocument。
+- 不新增 Agent Node、MCP Node 和 Skill Node。
+- 不新增 FFmpeg Node；媒体引擎是内部实现细节。
+
+## 7. Editor 界面设计
+
+### 7.1 总体布局
+
+Editor 使用当前 AppShell 的 56px 顶栏和全屏生产工作区，不增加永久全局侧边栏。
+
+```text
+┌──────────────────────────────────────────────────────────────┐
+│ Back to Canvas | Timeline name | Saved | Ratio | Export      │
+├──────────────┬───────────────────────────────┬───────────────┤
+│              │                               │               │
+│ Project      │          Preview              │   Inspector   │
+│ Assets       │                               │               │
+│              │                               │               │
+├──────────────┴───────────────────────────────┴───────────────┤
+│ Toolbar: Undo Redo Split Delete Snap Zoom                    │
+├──────────────────────────────────────────────────────────────┤
+│ Video 2  ─────────────────────────────────────────────       │
+│ Video 1  ───── Clip A ───── Clip B ───────────────────       │
+│ Audio 1  ───────── Waveform ──────────────────────────       │
+│ Captions ───── Cue ───── Cue ───── Cue ───────────────       │
+└──────────────────────────────────────────────────────────────┘
+```
+
+布局建议：
+
+- 左侧素材区：260-300px，可折叠。
+- 右侧 Inspector：280-320px，无选择时折叠或显示项目设置。
+- Timeline：默认 260px 高，可上下拖动。
+- Preview：占据剩余空间。
+- 小于 960px 时，素材区和 Inspector 改为抽屉；时间线仍保持可操作。
+
+### 7.2 与 BeatDesign UI 匹配
+
+必须直接复用现有 Token：
+
+- 背景：`--beat-bg`。
+- 主表面：`--beat-surface`。
+- 抬升表面：`--beat-surface-2`。
+- 边线：`--beat-border` / `--beatcanvas-line`。
+- 文本：`--beat-text-1/2/3`。
+- 品牌动作：`--beat-accent`。
+- 选择、吸附、轨道焦点：`--beat-graph`。
+- 成功、警告、错误：现有 Canvas semantic tokens。
+
+字体：
+
+- UI：Figtree / CJK fallback。
+- 时间码、FPS、时长、导出数据：Geist Mono。
+
+形状：
+
+- 控件 4-8px 圆角。
+- Panel 12px 圆角。
+- Preview/媒体 16px 圆角。
+- 不把 OpenReel 默认皮肤直接搬入 BeatDesign。
+- 不引入第二套紫色、渐变主色和高饱和多色按钮。
+
+交互：
+
+- 80ms/160ms 微交互，不给拖动、播放头或 trim handle 增加延迟感。
+- 所有 Timeline 操作支持键盘和可见焦点。
+- 状态不能只靠颜色表达。
+- 所有触控目标尽可能达到 44px。
+
+### 7.3 第一阶段显示的工具
+
+左侧：
+
+- Project Assets。
+- Videos / Images / Audio 筛选。
+- 搜索。
+- 添加到时间线。
+
+顶部：
+
+- 返回 Canvas。
+- Timeline 名称。
+- 自动保存状态。
+- 画幅。
+- Export。
+
+Preview：
+
+- 播放、暂停。
+- 前后跳转。
+- 当前时间/总时长。
+- 静音。
+- 预览缩放。
+- 适应画布。
+
+Timeline：
+
+- Select、Split、Delete。
+- Trim handles。
+- Drag move。
+- Snap。
+- Undo/Redo。
+- Timeline zoom。
+- Track lock/mute/solo。
+- Add track。
+
+Inspector：
+
+- Transform：position、scale、rotation、fit。
+- Audio：volume、mute、fade in/out。
+- Speed：第一阶段只支持 0.5x、1x、2x；如实现风险高可移至 Phase 1.1。
+- Clip metadata：素材名称、source in/out、timeline start/end。
+
+### 7.4 默认隐藏的 OpenReel 功能
+
+- Graphics、SVG、Stickers、Backgrounds。
+- 高级 Effects 和模板。
+- LUT、Scopes、复杂 Color Grading。
+- Keyframes、Speed Ramp、Optical Flow、Stabilization。
+- Recording、Webcam、Screen Capture。
+- Multicam、3D、Motion Tracking。
+- AI Agent、Chat、MCP、任意第三方模型 Provider。
+- Templates Marketplace、Stock Media、Music Marketplace。
+
+代码可以保留在 Fork 中，但不进入首发导航和默认 Bundle；无法按需拆包的模块应在 Fork 中删除或延迟加载。
+
+## 8. OpenReel 引入方案
+
+### 8.1 引入方式
+
+OpenReel 以固定 commit 的 Fork 形式进入 BeatDesign，不使用 Git Submodule。
+
+推荐先作为同仓第一方 micro-frontend：
+
+```text
+packages/openreel-editor
+  -> 独立 Vite build
+  -> 同源挂载在 /editor-runtime/
+  -> BeatDesign /editor/:timelineId 路由承载
+```
+
+理由：
+
+- OpenReel 当前是完整应用而不是稳定的 UI npm 包。
+- 隔离 OpenReel 的 React、Zustand、Worker、WASM 和样式依赖。
+- 避免立即将 OpenReel 大量状态耦合到 Canvas 组件。
+- 后续同步上游更新更清晰。
+- 可以通过同源 API 和 typed bridge 与 BeatDesign 通信。
+
+第一阶段 bridge 不是通用 Plugin SDK，只定义本编辑器需要的固定协议：
+
+```text
+host.ready
+host.getTimeline
+host.saveTimeline
+host.listAssets
+host.resolveAsset
+host.saveDerivedAsset
+host.submitGeneration
+host.getGenerationStatus
+editor.selectionChanged
+editor.exportProgress
+editor.projectChanged
+```
+
+### 8.2 保留
+
+- `packages/core` 中 timeline、actions、undo/redo、media、playback。
+- WebCodecs Export Backend。
+- MediaBunny 容器读写。
+- WebGPU/Canvas2D Preview。
+- Web Audio、waveform 和基础音频能力。
+- Trim、split、ripple delete、move、snap。
+- Text/caption 基础模型。
+- 项目 JSON schema 和版本迁移能力。
+- 缺失素材检查所需能力。
+
+### 8.3 删除
+
+- OpenReel 内置 Agent、Chat 和模型配置界面。
+- KieAI 或其他与 BeatAPI 重复的生成 Provider。
+- OpenReel 自带账户、云同步、订阅或远程项目功能。
+- Desktop、mobile 和原生安装器代码，不进入 BeatDesign Phase 1 构建。
+- OpenReel Welcome、Recent Projects 和独立项目首页。
+- 重复的导航、主题切换和品牌外壳。
+- 与 BeatDesign Assets/Generations 重复的云素材来源。
+
+### 8.4 替换
+
+- OpenReel IndexedDB 项目保存 -> BeatDesign Timeline service + SQLite/D1。
+- OpenReel 最近项目 -> BeatDesign Project/Timeline 列表。
+- OpenReel 媒体导入 -> BeatDesign Asset Adapter。
+- OpenReel 下载导出 -> BeatDesign Render service；仍保留“下载文件”选项。
+- OpenReel 生成能力 -> BeatAPI Generation service。
+- OpenReel UI tokens -> BeatDesign `--beat-*` 和 `--beatcanvas-*`。
+- OpenReel toast/dialog -> BeatDesign 现有组件和 i18n。
+
+### 8.5 暂时保留但关闭入口
+
+- 字幕样式、基础转场、基础特效、图形、关键帧。
+- 后续可以逐项打开，不在第一阶段重写。
+
+## 9. FFmpeg 与浏览器媒体方案
+
+### 9.1 第一阶段
+
+用户不安装系统 FFmpeg。
+
+默认媒体链路：
+
+```text
+Preview        -> WebCodecs + WebGPU/Canvas2D
+Audio          -> Web Audio
+MP4 mux        -> MediaBunny
+Export         -> OpenReel WebCodecsBackend
+Fallback       -> ffmpeg.wasm（可选、短素材）
+```
+
+第一阶段不把原生 macOS/Windows/Linux FFmpeg 二进制提交到 Git 仓库。
+
+### 9.2 ffmpeg.wasm 策略
+
+- 不作为 P0 导出主引擎。
+- 如必须启用，以依赖方式安装并从 localhost 自托管 Core，不从 CDN 动态获取。
+- 只用于不兼容素材转码、短选区截取或浏览器能力 Fallback。
+- 默认先采用单线程版本，避免第一阶段强制 COOP/COEP；多线程与长视频性能留到后续。
+- 在 `THIRD_PARTY_NOTICES.md` 中单独记录 wrapper、core 和 FFmpeg license。
+- 在许可证方案正式确认前，可通过 feature flag 关闭 wasm fallback，不阻塞 WebCodecs 主链路。
+
+### 9.3 桌面阶段
+
+Electron 阶段再把合规的原生 FFmpeg/ffprobe 作为 Sidecar 放入安装包。届时替换 Export Backend，不重写 Timeline、Preview、项目格式和 Canvas 闭环。
+
+## 10. 核心数据模型
+
+### 10.1 TimelineDocument
+
+```ts
+type TimelineDocument = {
+  schemaVersion: 1;
+  id: string;
+  projectId: string;
+  name: string;
+  width: number;
+  height: number;
+  frameRate: number;
+  sampleRate: number;
+  channels: number;
+  tracks: TimelineTrack[];
+  markers: TimelineMarker[];
+  durationSec: number;
+  createdAt: string;
+  updatedAt: string;
+};
+```
+
+### 10.2 Track
+
+```ts
+type TimelineTrack = {
+  id: string;
+  kind: 'video' | 'audio' | 'subtitle' | 'text' | 'graphics';
+  name: string;
+  order: number;
+  locked: boolean;
+  hidden: boolean;
+  muted: boolean;
+  solo: boolean;
+  clips: TimelineClip[];
+};
+```
+
+### 10.3 Clip
+
+```ts
+type TimelineClip = {
+  id: string;
+  assetId: string;
+  trackId: string;
+  timelineStartSec: number;
+  sourceInSec: number;
+  sourceOutSec: number;
+  durationSec: number;
+  speed: number;
+  volume: number;
+  fadeInSec: number;
+  fadeOutSec: number;
+  activeTakeId: string | null;
+  takeIds: string[];
+};
+```
+
+### 10.4 Take
+
+```ts
+type ClipTake = {
+  id: string;
+  clipId: string;
+  assetId: string;
+  generationId: string | null;
+  source: 'original' | 'derived' | 'beatapi';
+  prompt: string | null;
+  modelId: string | null;
+  status: 'ready' | 'pending' | 'failed';
+  createdAt: string;
+};
+```
+
+### 10.5 RenderJob
+
+```ts
+type RenderJob = {
+  id: string;
+  projectId: string;
+  timelineId: string;
+  status: 'queued' | 'rendering' | 'saving' | 'succeeded' | 'failed' | 'cancelled';
+  progress: number;
+  format: 'mp4';
+  width: number;
+  height: number;
+  frameRate: number;
+  resultAssetId: string | null;
+  error: string | null;
+};
+```
+
+### 10.6 数据库范围
+
+建议新增：
+
+- `timeline_document`
+- `timeline_take`
+- `render_job`
+
+TimelineDocument 第一阶段可以整体 JSON 保存并使用 revision/CAS，避免过早把每个 Clip 拆成关系表。Take 与 RenderJob 单独建表以便关联 Generation 和 Asset。
+
+Canvas snapshot 升级时必须兼容旧项目；旧项目打开后不得丢失图片或视频节点。
+
+## 11. 功能需求
+
+### FR-1 创建与打开时间线
+
+- 一个 Project 可以有多个 Timeline。
+- 第一次添加素材时可以自动创建“Timeline 1”。
+- 用户可以从 Canvas、Assets 或 Edit 进入。
+- 重启 localhost 后时间线可恢复。
+
+### FR-2 素材进入时间线
+
+- 图片、视频、音频均可添加。
+- 同一 Asset 重复添加时复用 Asset，不重复复制文件。
+- 默认添加到兼容轨道；没有轨道时自动创建。
+- OpenReel 内部只保存 `assetId` 和相对引用，不保存临时 Blob URL 作为真相。
+
+### FR-3 非破坏式剪辑
+
+- 支持 trim、split、move、delete、ripple delete。
+- 原始 Asset 不改变。
+- Clip 的 sourceIn/sourceOut 不得越界。
+- 同轨 Clip 默认不允许重叠。
+- 所有 P0 剪辑操作必须进入 Undo/Redo。
+
+### FR-4 音频
+
+- Canvas 可创建和恢复 Audio Asset Node。
+- Timeline 可添加音频轨和音频 Clip。
+- Preview 可同步播放音视频。
+- 支持 volume、mute、fade in/out。
+- 第一阶段不要求自动字幕、Beat Sync 和降噪。
+
+### FR-5 选区派生素材
+
+- 用户可选择一个 Clip 或时间范围。
+- “截取为新素材”生成新的本地 Video Asset。
+- 派生 Asset 记录 parent、sourceIn/out、timeline、clip 和 operation。
+- 新 Asset 可出现在 Assets 和 Canvas。
+
+### FR-6 BeatAPI 重做
+
+- 用户选择 Clip/选区并点击“AI 重做”。
+- 弹出与现有 BeatDesign Composer 一致的轻量生成面板。
+- 显示模型、提示词、参考输入和付费确认。
+- 使用派生视频或首尾帧作为 BeatAPI 输入。
+- 返回结果必须先本地化，再进入 Take。
+- 失败不改变当前 Clip。
+- 成功后用户可预览新 Take 并选择替换。
+
+第一阶段只保证一种已验证的 BeatAPI 视频编辑/视频转视频路径。模型能力由现有 effect registry 和 adapter 决定，不在 Editor 内建立第二套模型目录。
+
+### FR-7 MP4 导出
+
+- 默认 1080p/30fps/H.264/AAC。
+- 支持下载文件和保存到项目。
+- 保存到项目后创建 Render Asset，并允许创建 Canvas Output Node。
+- 显示进度、取消、成功和失败状态。
+- 导出期间不冻结整个界面。
+- 导出结果不得包含未解释黑帧、重叠 Clip 或丢失素材。
+
+### FR-8 自动保存与恢复
+
+- 时间线变更采用 dirty state + debounce 自动保存。
+- 页面隐藏、刷新和离开前执行 flush。
+- 使用 revision/CAS 防止旧状态覆盖新状态。
+- 保存失败要明确提示，不得伪装为 Saved。
+- 空文档不得覆盖已有非空文档。
+
+## 12. 关键状态和错误处理
+
+必须处理：
+
+- Asset 文件丢失。
+- 不支持的 Codec。
+- 浏览器不支持 WebCodecs/WebGPU。
+- 导出内存不足。
+- 导出取消。
+- BeatAPI 任务失败或超时。
+- 派生素材保存失败。
+- 页面刷新时仍在保存。
+- 时间线文档版本冲突。
+- Audio duration/metadata 读取失败。
+- Clip 超出源时长。
+- 同轨重叠和可见视频空隙。
+
+Editor 必须提供只读 Diagnostics：
+
+- `timeline_gap`
+- `clip_overlap`
+- `media_missing`
+- `caption_overlap`
+- `caption_out_of_video`
+- `tiny_clip`
+- `empty_track`
+
+P0 导出前自动运行 Diagnostics；Error 级问题阻止导出，Warning 级问题允许用户确认后继续。
+
+## 13. 测试与验收计划
+
+### 13.1 单元测试
+
+- Clip trim 数学和边界。
+- Split 后 sourceIn/sourceOut 连续。
+- Ripple delete 后轨道位置。
+- Move 和 snap 计算。
+- Take 创建、切换、替换和回滚。
+- Audio 节点序列化、反序列化和旧快照兼容。
+- Timeline schema normalize/migrate。
+- RenderJob 状态机。
+- revision/CAS 冲突。
+- 空时间线保护。
+
+### 13.2 集成测试
+
+- BeatDesign Asset -> OpenReel MediaItem。
+- OpenReel Project JSON -> Timeline service -> reload。
+- Export Blob -> localhost -> project-assets -> Asset index。
+- 选区 -> Derived Asset -> generation intent。
+- 模拟 BeatAPI 成功、失败、超时和取消。
+- Take 替换后 Timeline 保存和恢复。
+- 音频 Asset 添加到音频轨并恢复。
+
+### 13.3 E2E 主路径
+
+使用一个固定 10 秒测试视频：
+
+1. 打开 Canvas。
+2. 将视频添加到 Timeline。
+3. Trim 为 3.2-6.8 秒。
+4. 保存并刷新页面。
+5. 验证 Clip 仍为 3.6 秒。
+6. 导出 MP4。
+7. 本地 probe 输出：分辨率、时长、FPS、音频流。
+8. 选择该 Clip 并创建 Derived Asset。
+9. 使用 mock BeatAPI 返回新视频。
+10. 新视频成为 Take。
+11. 切换并替换当前 Clip。
+12. 再次导出。
+13. 保存到项目并在 Canvas 创建 Output Node。
+
+### 13.4 媒体测试矩阵
+
+- 横屏 MP4、有音频。
+- 横屏 MP4、无音频。
+- 竖屏 MP4。
+- MOV 输入。
+- MP3、WAV、M4A。
+- 图片作为定长 Clip。
+- 两个连续视频 Clip。
+- 视频 + 背景音乐。
+- 30 秒、60 秒、120 秒时间线。
+- 缺失文件和损坏文件。
+
+### 13.5 视觉与音频 QA
+
+- Preview 与导出画面比例一致。
+- Trim 后第一帧、最后一帧符合选区。
+- 无意外黑帧。
+- 转场未启用时是硬切。
+- 音画同步。
+- 音频无意外静音、爆音和截断。
+- Canvas Output Node 展示真实导出封面。
+- 音频节点波形、时长和播放状态一致。
+
+### 13.6 回归门槛
+
+每个合并批次必须通过：
+
+```text
+pnpm typecheck
+pnpm i18n:check
+pnpm test
+pnpm build
+```
+
+同时保留 Canvas 的：
+
+- Zoom、pan、connect、selection、undo/redo。
+- 项目快照与空状态保护。
+- 生成任务和本地化。
+- Assets/Studio/Canvas 模式切换。
+- 当前 Start Here 空状态视觉。
+
+## 14. 实施里程碑
+
+### M0：技术验证
+
+- Fork 并固定 OpenReel commit。
+- 在 BeatDesign 仓库内完成独立构建。
+- 加载一个本地 10 秒 MP4。
+- Preview、trim、split、MP4 export 可用。
+- 不要求保存、Canvas 或 BeatAPI。
+
+退出条件：用户不安装系统 FFmpeg即可完成 10 秒 -> 3.6 秒 -> MP4。
+
+### M1：本地项目闭环
+
+- Timeline service 和数据库。
+- Asset Adapter。
+- 自动保存、刷新恢复。
+- Canvas Timeline Node。
+- Audio Asset Node。
+- Export 保存到项目并返回 Canvas。
+
+退出条件：重启 localhost 后项目、视频、音频、时间线和导出节点都可恢复。
+
+### M2：BeatAPI 重做闭环
+
+- 选区派生素材。
+- 现有 effect registry 接入。
+- 付费确认。
+- Generation -> Take。
+- Take 预览、替换和回滚。
+
+退出条件：选区可重做，失败不破坏原 Clip，成功可替换并导出。
+
+### M3：可靠性与发布准备
+
+- Diagnostics。
+- Export progress/cancel。
+- 不支持格式提示与 fallback。
+- 许可证和 Third Party Notices。
+- 中英文文案。
+- README、架构文档、示例项目和演示素材。
+
+退出条件：主路径、媒体矩阵、回归门槛全部通过。
+
+## 15. 开源用户体验
+
+目标启动方式：
+
+```bash
+pnpm install
+cp .env.example .env.development
+pnpm db:push
+pnpm dev
+```
+
+要求：
+
+- 不要求 `brew install ffmpeg`。
+- 不要求 Git Submodule。
+- 不从 CDN 动态加载 OpenReel、WASM、字体或编辑器核心。
+- 没有 BeatAPI key 时仍可导入、剪辑和导出本地视频。
+- 用户只在调用 BeatAPI 时配置 key。
+- README 明确支持的浏览器、格式、时长和已知限制。
+- 提供一个体积可控、许可证清楚的测试素材和示例时间线。
+
+## 16. 开源与许可证
+
+- BeatDesign 主项目继续使用 Apache-2.0。
+- OpenReel Fork 保留 MIT License、版权声明和上游 commit。
+- Mediabunny、FFmpeg wrapper/core、字体、图标和测试素材单独记录。
+- 新增 `THIRD_PARTY_NOTICES.md`。
+- 如启用 ffmpeg.wasm core，必须明确其实际 license，不将其声明为 Apache-2.0。
+- 第一阶段不复制 MiniMax Design 打包文件、其 FFmpeg 二进制或专有 Host 代码。
+
+## 17. 发布判定
+
+第一阶段被认为完成，当且仅当：
+
+1. 新用户从 GitHub 克隆后无需安装系统 FFmpeg即可剪辑和导出。
+2. 10 秒生成视频可在 Timeline 中精确截取 3-4 秒。
+3. 时间线、音频节点和本地素材可在刷新/重启后恢复。
+4. MP4 可下载，也可保存到项目并回到 Canvas。
+5. 选区可调用 BeatAPI 重做并作为 Take 返回。
+6. 原 Clip 和原 Asset 始终可以恢复。
+7. 主 E2E、媒体 QA 和项目回归全部通过。
+8. 不引入侧边 Agent、Electron、通用 Plugin SDK 或 MCP。
diff --git a/drizzle.config.ts b/drizzle.config.ts
index a6bb1bd..6388880 100644
--- a/drizzle.config.ts
+++ b/drizzle.config.ts
@@ -14,6 +14,6 @@ export default defineConfig({
   out: './drizzle/d1',
   dialect: 'sqlite',
   dbCredentials: {
-    url: process.env.DATABASE_URL || 'file:data/local.db',
+    url: process.env.DATABASE_URL || 'file:data/workspace.db',
   },
 });
diff --git a/drizzle/d1/0002_lethal_micromacro.sql b/drizzle/d1/0002_lethal_micromacro.sql
new file mode 100644
index 0000000..7c964d8
--- /dev/null
+++ b/drizzle/d1/0002_lethal_micromacro.sql
@@ -0,0 +1,9 @@
+CREATE TABLE `project_timeline_state` (
+	`project_id` text PRIMARY KEY NOT NULL,
+	`document_json` text NOT NULL,
+	`version` integer DEFAULT 1 NOT NULL,
+	`updated_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	FOREIGN KEY (`project_id`) REFERENCES `project`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE INDEX `project_timeline_state_updated_at_idx` ON `project_timeline_state` (`updated_at`);
\ No newline at end of file
diff --git a/drizzle/d1/0003_slow_the_phantom.sql b/drizzle/d1/0003_slow_the_phantom.sql
new file mode 100644
index 0000000..8b5a653
--- /dev/null
+++ b/drizzle/d1/0003_slow_the_phantom.sql
@@ -0,0 +1,15 @@
+CREATE TABLE `project_command_receipt` (
+	`id` text PRIMARY KEY NOT NULL,
+	`project_id` text NOT NULL,
+	`idempotency_key` text NOT NULL,
+	`command_id` text NOT NULL,
+	`origin` text NOT NULL,
+	`command_type` text NOT NULL,
+	`result_json` text NOT NULL,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	FOREIGN KEY (`project_id`) REFERENCES `project`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE INDEX `project_command_receipt_project_idx` ON `project_command_receipt` (`project_id`);--> statement-breakpoint
+CREATE INDEX `project_command_receipt_command_idx` ON `project_command_receipt` (`command_id`);--> statement-breakpoint
+CREATE UNIQUE INDEX `project_command_receipt_idempotency_unique` ON `project_command_receipt` (`project_id`,`idempotency_key`);
\ No newline at end of file
diff --git a/drizzle/d1/meta/0002_snapshot.json b/drizzle/d1/meta/0002_snapshot.json
new file mode 100644
index 0000000..5105701
--- /dev/null
+++ b/drizzle/d1/meta/0002_snapshot.json
@@ -0,0 +1,1352 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "330a5db6-48ea-498b-ac5d-790bada59f0f",
+  "prevId": "7cf09fc2-c7d9-4243-b0f8-fb0ff41a485c",
+  "tables": {
+    "config": {
+      "name": "config",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "value": {
+          "name": "value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "generation_asset_link": {
+      "name": "generation_asset_link",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "generation_id": {
+          "name": "generation_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "asset_id": {
+          "name": "asset_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "generation_asset_link_generation_idx": {
+          "name": "generation_asset_link_generation_idx",
+          "columns": [
+            "generation_id"
+          ],
+          "isUnique": false
+        },
+        "generation_asset_link_asset_idx": {
+          "name": "generation_asset_link_asset_idx",
+          "columns": [
+            "asset_id"
+          ],
+          "isUnique": false
+        },
+        "generation_asset_link_unique": {
+          "name": "generation_asset_link_unique",
+          "columns": [
+            "generation_id",
+            "asset_id",
+            "role"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "generation_asset_link_generation_id_generation_history_id_fk": {
+          "name": "generation_asset_link_generation_id_generation_history_id_fk",
+          "tableFrom": "generation_asset_link",
+          "tableTo": "generation_history",
+          "columnsFrom": [
+            "generation_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "generation_asset_link_asset_id_asset_id_fk": {
+          "name": "generation_asset_link_asset_id_asset_id_fk",
+          "tableFrom": "generation_asset_link",
+          "tableTo": "asset",
+          "columnsFrom": [
+            "asset_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "generation_history": {
+      "name": "generation_history",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "project_id": {
+          "name": "project_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "effect_id": {
+          "name": "effect_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "provider_task_id": {
+          "name": "provider_task_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "lifecycle_phase": {
+          "name": "lifecycle_phase",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "last_provider_sync_at": {
+          "name": "last_provider_sync_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "execution_mode": {
+          "name": "execution_mode",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'create_new'"
+        },
+        "submitted_prompt": {
+          "name": "submitted_prompt",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "submitted_params": {
+          "name": "submitted_params",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "result_asset_id": {
+          "name": "result_asset_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "input": {
+          "name": "input",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "output": {
+          "name": "output",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "error": {
+          "name": "error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "completed_at": {
+          "name": "completed_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "failed_at": {
+          "name": "failed_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "generation_history_project_idx": {
+          "name": "generation_history_project_idx",
+          "columns": [
+            "project_id"
+          ],
+          "isUnique": false
+        },
+        "generation_history_effect_idx": {
+          "name": "generation_history_effect_idx",
+          "columns": [
+            "effect_id"
+          ],
+          "isUnique": false
+        },
+        "generation_history_status_idx": {
+          "name": "generation_history_status_idx",
+          "columns": [
+            "status"
+          ],
+          "isUnique": false
+        },
+        "generation_history_provider_task_idx": {
+          "name": "generation_history_provider_task_idx",
+          "columns": [
+            "provider_task_id"
+          ],
+          "isUnique": false
+        },
+        "generation_history_lifecycle_idx": {
+          "name": "generation_history_lifecycle_idx",
+          "columns": [
+            "lifecycle_phase"
+          ],
+          "isUnique": false
+        },
+        "generation_history_result_asset_idx": {
+          "name": "generation_history_result_asset_idx",
+          "columns": [
+            "result_asset_id"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "generation_history_project_id_project_id_fk": {
+          "name": "generation_history_project_id_project_id_fk",
+          "tableFrom": "generation_history",
+          "tableTo": "project",
+          "columnsFrom": [
+            "project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "generation_history_result_asset_id_asset_id_fk": {
+          "name": "generation_history_result_asset_id_asset_id_fk",
+          "tableFrom": "generation_history",
+          "tableTo": "asset",
+          "columnsFrom": [
+            "result_asset_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "generation_intent_upload": {
+      "name": "generation_intent_upload",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "intent_id": {
+          "name": "intent_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'reserved'"
+        },
+        "storage_provider": {
+          "name": "storage_provider",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "bucket": {
+          "name": "bucket",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "object_key": {
+          "name": "object_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "public_url": {
+          "name": "public_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "filename": {
+          "name": "filename",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "mime_type": {
+          "name": "mime_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "size_bytes": {
+          "name": "size_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        },
+        "completed_at": {
+          "name": "completed_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "generation_intent_upload_intent_idx": {
+          "name": "generation_intent_upload_intent_idx",
+          "columns": [
+            "intent_id"
+          ],
+          "isUnique": false
+        },
+        "generation_intent_upload_status_idx": {
+          "name": "generation_intent_upload_status_idx",
+          "columns": [
+            "status"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "generation_intent_upload_intent_id_generation_upload_intent_id_fk": {
+          "name": "generation_intent_upload_intent_id_generation_upload_intent_id_fk",
+          "tableFrom": "generation_intent_upload",
+          "tableTo": "generation_upload_intent",
+          "columnsFrom": [
+            "intent_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "generation_upload_intent": {
+      "name": "generation_upload_intent",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "project_id": {
+          "name": "project_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "effect_id": {
+          "name": "effect_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'pending'"
+        },
+        "expected_upload_count": {
+          "name": "expected_upload_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "reserved_upload_count": {
+          "name": "reserved_upload_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "completed_upload_count": {
+          "name": "completed_upload_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "generation_id": {
+          "name": "generation_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "consumed_at": {
+          "name": "consumed_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "generation_upload_intent_project_idx": {
+          "name": "generation_upload_intent_project_idx",
+          "columns": [
+            "project_id"
+          ],
+          "isUnique": false
+        },
+        "generation_upload_intent_status_expiry_idx": {
+          "name": "generation_upload_intent_status_expiry_idx",
+          "columns": [
+            "status",
+            "expires_at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "generation_upload_intent_project_id_project_id_fk": {
+          "name": "generation_upload_intent_project_id_project_id_fk",
+          "tableFrom": "generation_upload_intent",
+          "tableTo": "project",
+          "columnsFrom": [
+            "project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "generation_upload_intent_generation_id_generation_history_id_fk": {
+          "name": "generation_upload_intent_generation_id_generation_history_id_fk",
+          "tableFrom": "generation_upload_intent",
+          "tableTo": "generation_history",
+          "columnsFrom": [
+            "generation_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "project": {
+      "name": "project",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cover_asset_id": {
+          "name": "cover_asset_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'active'"
+        },
+        "current_state_version": {
+          "name": "current_state_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 1
+        },
+        "last_workspace_mode": {
+          "name": "last_workspace_mode",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'canvas'"
+        },
+        "last_opened_at": {
+          "name": "last_opened_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archived_at": {
+          "name": "archived_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "project_status_idx": {
+          "name": "project_status_idx",
+          "columns": [
+            "status"
+          ],
+          "isUnique": false
+        },
+        "project_updated_at_idx": {
+          "name": "project_updated_at_idx",
+          "columns": [
+            "updated_at"
+          ],
+          "isUnique": false
+        },
+        "project_last_opened_at_idx": {
+          "name": "project_last_opened_at_idx",
+          "columns": [
+            "last_opened_at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "project_asset_membership": {
+      "name": "project_asset_membership",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "project_id": {
+          "name": "project_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "asset_id": {
+          "name": "asset_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "source_run_id": {
+          "name": "source_run_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "category": {
+          "name": "category",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workflow_type": {
+          "name": "workflow_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "workflow_instance_id": {
+          "name": "workflow_instance_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "slot_id": {
+          "name": "slot_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "project_asset_membership_project_idx": {
+          "name": "project_asset_membership_project_idx",
+          "columns": [
+            "project_id"
+          ],
+          "isUnique": false
+        },
+        "project_asset_membership_asset_idx": {
+          "name": "project_asset_membership_asset_idx",
+          "columns": [
+            "asset_id"
+          ],
+          "isUnique": false
+        },
+        "project_asset_membership_unique": {
+          "name": "project_asset_membership_unique",
+          "columns": [
+            "project_id",
+            "asset_id",
+            "category"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "project_asset_membership_project_id_project_id_fk": {
+          "name": "project_asset_membership_project_id_project_id_fk",
+          "tableFrom": "project_asset_membership",
+          "tableTo": "project",
+          "columnsFrom": [
+            "project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "project_asset_membership_asset_id_asset_id_fk": {
+          "name": "project_asset_membership_asset_id_asset_id_fk",
+          "tableFrom": "project_asset_membership",
+          "tableTo": "asset",
+          "columnsFrom": [
+            "asset_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "project_asset_membership_source_run_id_generation_history_id_fk": {
+          "name": "project_asset_membership_source_run_id_generation_history_id_fk",
+          "tableFrom": "project_asset_membership",
+          "tableTo": "generation_history",
+          "columnsFrom": [
+            "source_run_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "project_canvas_state": {
+      "name": "project_canvas_state",
+      "columns": {
+        "project_id": {
+          "name": "project_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "document_json": {
+          "name": "document_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 1
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "project_canvas_state_updated_at_idx": {
+          "name": "project_canvas_state_updated_at_idx",
+          "columns": [
+            "updated_at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "project_canvas_state_project_id_project_id_fk": {
+          "name": "project_canvas_state_project_id_project_id_fk",
+          "tableFrom": "project_canvas_state",
+          "tableTo": "project",
+          "columnsFrom": [
+            "project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "project_timeline_state": {
+      "name": "project_timeline_state",
+      "columns": {
+        "project_id": {
+          "name": "project_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "document_json": {
+          "name": "document_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 1
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "project_timeline_state_updated_at_idx": {
+          "name": "project_timeline_state_updated_at_idx",
+          "columns": [
+            "updated_at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "project_timeline_state_project_id_project_id_fk": {
+          "name": "project_timeline_state_project_id_project_id_fk",
+          "tableFrom": "project_timeline_state",
+          "tableTo": "project",
+          "columnsFrom": [
+            "project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "project_workflow_state": {
+      "name": "project_workflow_state",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "project_id": {
+          "name": "project_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workflow_type": {
+          "name": "workflow_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workflow_instance_id": {
+          "name": "workflow_instance_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "template_slug": {
+          "name": "template_slug",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'draft'"
+        },
+        "form_json": {
+          "name": "form_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "layout_json": {
+          "name": "layout_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "selection_json": {
+          "name": "selection_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 1
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "project_workflow_state_project_idx": {
+          "name": "project_workflow_state_project_idx",
+          "columns": [
+            "project_id"
+          ],
+          "isUnique": false
+        },
+        "project_workflow_state_unique": {
+          "name": "project_workflow_state_unique",
+          "columns": [
+            "project_id",
+            "workflow_type",
+            "workflow_instance_id"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "project_workflow_state_project_id_project_id_fk": {
+          "name": "project_workflow_state_project_id_project_id_fk",
+          "tableFrom": "project_workflow_state",
+          "tableTo": "project",
+          "columnsFrom": [
+            "project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "asset": {
+      "name": "asset",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "source": {
+          "name": "source",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "asset_class": {
+          "name": "asset_class",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'original'"
+        },
+        "storage_provider": {
+          "name": "storage_provider",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "bucket": {
+          "name": "bucket",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'beatapi'"
+        },
+        "object_key": {
+          "name": "object_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "public_url": {
+          "name": "public_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "filename": {
+          "name": "filename",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "mime_type": {
+          "name": "mime_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "size_bytes": {
+          "name": "size_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sha256": {
+          "name": "sha256",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "width": {
+          "name": "width",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "height": {
+          "name": "height",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "duration_ms": {
+          "name": "duration_ms",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "origin_project_id": {
+          "name": "origin_project_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "thumbnail_asset_id": {
+          "name": "thumbnail_asset_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "asset_type_idx": {
+          "name": "asset_type_idx",
+          "columns": [
+            "type"
+          ],
+          "isUnique": false
+        },
+        "asset_class_idx": {
+          "name": "asset_class_idx",
+          "columns": [
+            "asset_class"
+          ],
+          "isUnique": false
+        },
+        "asset_origin_project_idx": {
+          "name": "asset_origin_project_idx",
+          "columns": [
+            "origin_project_id"
+          ],
+          "isUnique": false
+        },
+        "asset_created_at_idx": {
+          "name": "asset_created_at_idx",
+          "columns": [
+            "created_at"
+          ],
+          "isUnique": false
+        },
+        "asset_bucket_object_key_unique": {
+          "name": "asset_bucket_object_key_unique",
+          "columns": [
+            "bucket",
+            "object_key"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "asset_origin_project_id_project_id_fk": {
+          "name": "asset_origin_project_id_project_id_fk",
+          "tableFrom": "asset",
+          "tableTo": "project",
+          "columnsFrom": [
+            "origin_project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "asset_thumbnail_asset_id_asset_id_fk": {
+          "name": "asset_thumbnail_asset_id_asset_id_fk",
+          "tableFrom": "asset",
+          "tableTo": "asset",
+          "columnsFrom": [
+            "thumbnail_asset_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/drizzle/d1/meta/0003_snapshot.json b/drizzle/d1/meta/0003_snapshot.json
new file mode 100644
index 0000000..4fc272f
--- /dev/null
+++ b/drizzle/d1/meta/0003_snapshot.json
@@ -0,0 +1,1456 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "6622e3e9-3968-4f55-a0a6-cf8538d1a594",
+  "prevId": "330a5db6-48ea-498b-ac5d-790bada59f0f",
+  "tables": {
+    "config": {
+      "name": "config",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "value": {
+          "name": "value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "generation_asset_link": {
+      "name": "generation_asset_link",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "generation_id": {
+          "name": "generation_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "asset_id": {
+          "name": "asset_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "generation_asset_link_generation_idx": {
+          "name": "generation_asset_link_generation_idx",
+          "columns": [
+            "generation_id"
+          ],
+          "isUnique": false
+        },
+        "generation_asset_link_asset_idx": {
+          "name": "generation_asset_link_asset_idx",
+          "columns": [
+            "asset_id"
+          ],
+          "isUnique": false
+        },
+        "generation_asset_link_unique": {
+          "name": "generation_asset_link_unique",
+          "columns": [
+            "generation_id",
+            "asset_id",
+            "role"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "generation_asset_link_generation_id_generation_history_id_fk": {
+          "name": "generation_asset_link_generation_id_generation_history_id_fk",
+          "tableFrom": "generation_asset_link",
+          "tableTo": "generation_history",
+          "columnsFrom": [
+            "generation_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "generation_asset_link_asset_id_asset_id_fk": {
+          "name": "generation_asset_link_asset_id_asset_id_fk",
+          "tableFrom": "generation_asset_link",
+          "tableTo": "asset",
+          "columnsFrom": [
+            "asset_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "generation_history": {
+      "name": "generation_history",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "project_id": {
+          "name": "project_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "effect_id": {
+          "name": "effect_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "provider_task_id": {
+          "name": "provider_task_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "lifecycle_phase": {
+          "name": "lifecycle_phase",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "last_provider_sync_at": {
+          "name": "last_provider_sync_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "execution_mode": {
+          "name": "execution_mode",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'create_new'"
+        },
+        "submitted_prompt": {
+          "name": "submitted_prompt",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "submitted_params": {
+          "name": "submitted_params",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "result_asset_id": {
+          "name": "result_asset_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "input": {
+          "name": "input",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "output": {
+          "name": "output",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "error": {
+          "name": "error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "completed_at": {
+          "name": "completed_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "failed_at": {
+          "name": "failed_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "generation_history_project_idx": {
+          "name": "generation_history_project_idx",
+          "columns": [
+            "project_id"
+          ],
+          "isUnique": false
+        },
+        "generation_history_effect_idx": {
+          "name": "generation_history_effect_idx",
+          "columns": [
+            "effect_id"
+          ],
+          "isUnique": false
+        },
+        "generation_history_status_idx": {
+          "name": "generation_history_status_idx",
+          "columns": [
+            "status"
+          ],
+          "isUnique": false
+        },
+        "generation_history_provider_task_idx": {
+          "name": "generation_history_provider_task_idx",
+          "columns": [
+            "provider_task_id"
+          ],
+          "isUnique": false
+        },
+        "generation_history_lifecycle_idx": {
+          "name": "generation_history_lifecycle_idx",
+          "columns": [
+            "lifecycle_phase"
+          ],
+          "isUnique": false
+        },
+        "generation_history_result_asset_idx": {
+          "name": "generation_history_result_asset_idx",
+          "columns": [
+            "result_asset_id"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "generation_history_project_id_project_id_fk": {
+          "name": "generation_history_project_id_project_id_fk",
+          "tableFrom": "generation_history",
+          "tableTo": "project",
+          "columnsFrom": [
+            "project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "generation_history_result_asset_id_asset_id_fk": {
+          "name": "generation_history_result_asset_id_asset_id_fk",
+          "tableFrom": "generation_history",
+          "tableTo": "asset",
+          "columnsFrom": [
+            "result_asset_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "generation_intent_upload": {
+      "name": "generation_intent_upload",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "intent_id": {
+          "name": "intent_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'reserved'"
+        },
+        "storage_provider": {
+          "name": "storage_provider",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "bucket": {
+          "name": "bucket",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "object_key": {
+          "name": "object_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "public_url": {
+          "name": "public_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "filename": {
+          "name": "filename",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "mime_type": {
+          "name": "mime_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "size_bytes": {
+          "name": "size_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        },
+        "completed_at": {
+          "name": "completed_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "generation_intent_upload_intent_idx": {
+          "name": "generation_intent_upload_intent_idx",
+          "columns": [
+            "intent_id"
+          ],
+          "isUnique": false
+        },
+        "generation_intent_upload_status_idx": {
+          "name": "generation_intent_upload_status_idx",
+          "columns": [
+            "status"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "generation_intent_upload_intent_id_generation_upload_intent_id_fk": {
+          "name": "generation_intent_upload_intent_id_generation_upload_intent_id_fk",
+          "tableFrom": "generation_intent_upload",
+          "tableTo": "generation_upload_intent",
+          "columnsFrom": [
+            "intent_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "generation_upload_intent": {
+      "name": "generation_upload_intent",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "project_id": {
+          "name": "project_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "effect_id": {
+          "name": "effect_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'pending'"
+        },
+        "expected_upload_count": {
+          "name": "expected_upload_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "reserved_upload_count": {
+          "name": "reserved_upload_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "completed_upload_count": {
+          "name": "completed_upload_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "generation_id": {
+          "name": "generation_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "consumed_at": {
+          "name": "consumed_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "generation_upload_intent_project_idx": {
+          "name": "generation_upload_intent_project_idx",
+          "columns": [
+            "project_id"
+          ],
+          "isUnique": false
+        },
+        "generation_upload_intent_status_expiry_idx": {
+          "name": "generation_upload_intent_status_expiry_idx",
+          "columns": [
+            "status",
+            "expires_at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "generation_upload_intent_project_id_project_id_fk": {
+          "name": "generation_upload_intent_project_id_project_id_fk",
+          "tableFrom": "generation_upload_intent",
+          "tableTo": "project",
+          "columnsFrom": [
+            "project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "generation_upload_intent_generation_id_generation_history_id_fk": {
+          "name": "generation_upload_intent_generation_id_generation_history_id_fk",
+          "tableFrom": "generation_upload_intent",
+          "tableTo": "generation_history",
+          "columnsFrom": [
+            "generation_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "project": {
+      "name": "project",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cover_asset_id": {
+          "name": "cover_asset_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'active'"
+        },
+        "current_state_version": {
+          "name": "current_state_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 1
+        },
+        "last_workspace_mode": {
+          "name": "last_workspace_mode",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'canvas'"
+        },
+        "last_opened_at": {
+          "name": "last_opened_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archived_at": {
+          "name": "archived_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "project_status_idx": {
+          "name": "project_status_idx",
+          "columns": [
+            "status"
+          ],
+          "isUnique": false
+        },
+        "project_updated_at_idx": {
+          "name": "project_updated_at_idx",
+          "columns": [
+            "updated_at"
+          ],
+          "isUnique": false
+        },
+        "project_last_opened_at_idx": {
+          "name": "project_last_opened_at_idx",
+          "columns": [
+            "last_opened_at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "project_asset_membership": {
+      "name": "project_asset_membership",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "project_id": {
+          "name": "project_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "asset_id": {
+          "name": "asset_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "source_run_id": {
+          "name": "source_run_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "category": {
+          "name": "category",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workflow_type": {
+          "name": "workflow_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "workflow_instance_id": {
+          "name": "workflow_instance_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "slot_id": {
+          "name": "slot_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "project_asset_membership_project_idx": {
+          "name": "project_asset_membership_project_idx",
+          "columns": [
+            "project_id"
+          ],
+          "isUnique": false
+        },
+        "project_asset_membership_asset_idx": {
+          "name": "project_asset_membership_asset_idx",
+          "columns": [
+            "asset_id"
+          ],
+          "isUnique": false
+        },
+        "project_asset_membership_unique": {
+          "name": "project_asset_membership_unique",
+          "columns": [
+            "project_id",
+            "asset_id",
+            "category"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "project_asset_membership_project_id_project_id_fk": {
+          "name": "project_asset_membership_project_id_project_id_fk",
+          "tableFrom": "project_asset_membership",
+          "tableTo": "project",
+          "columnsFrom": [
+            "project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "project_asset_membership_asset_id_asset_id_fk": {
+          "name": "project_asset_membership_asset_id_asset_id_fk",
+          "tableFrom": "project_asset_membership",
+          "tableTo": "asset",
+          "columnsFrom": [
+            "asset_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "project_asset_membership_source_run_id_generation_history_id_fk": {
+          "name": "project_asset_membership_source_run_id_generation_history_id_fk",
+          "tableFrom": "project_asset_membership",
+          "tableTo": "generation_history",
+          "columnsFrom": [
+            "source_run_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "project_canvas_state": {
+      "name": "project_canvas_state",
+      "columns": {
+        "project_id": {
+          "name": "project_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "document_json": {
+          "name": "document_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 1
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "project_canvas_state_updated_at_idx": {
+          "name": "project_canvas_state_updated_at_idx",
+          "columns": [
+            "updated_at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "project_canvas_state_project_id_project_id_fk": {
+          "name": "project_canvas_state_project_id_project_id_fk",
+          "tableFrom": "project_canvas_state",
+          "tableTo": "project",
+          "columnsFrom": [
+            "project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "project_command_receipt": {
+      "name": "project_command_receipt",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "project_id": {
+          "name": "project_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "idempotency_key": {
+          "name": "idempotency_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "command_id": {
+          "name": "command_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "origin": {
+          "name": "origin",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "command_type": {
+          "name": "command_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "result_json": {
+          "name": "result_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "project_command_receipt_project_idx": {
+          "name": "project_command_receipt_project_idx",
+          "columns": [
+            "project_id"
+          ],
+          "isUnique": false
+        },
+        "project_command_receipt_command_idx": {
+          "name": "project_command_receipt_command_idx",
+          "columns": [
+            "command_id"
+          ],
+          "isUnique": false
+        },
+        "project_command_receipt_idempotency_unique": {
+          "name": "project_command_receipt_idempotency_unique",
+          "columns": [
+            "project_id",
+            "idempotency_key"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "project_command_receipt_project_id_project_id_fk": {
+          "name": "project_command_receipt_project_id_project_id_fk",
+          "tableFrom": "project_command_receipt",
+          "tableTo": "project",
+          "columnsFrom": [
+            "project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "project_timeline_state": {
+      "name": "project_timeline_state",
+      "columns": {
+        "project_id": {
+          "name": "project_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "document_json": {
+          "name": "document_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 1
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "project_timeline_state_updated_at_idx": {
+          "name": "project_timeline_state_updated_at_idx",
+          "columns": [
+            "updated_at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "project_timeline_state_project_id_project_id_fk": {
+          "name": "project_timeline_state_project_id_project_id_fk",
+          "tableFrom": "project_timeline_state",
+          "tableTo": "project",
+          "columnsFrom": [
+            "project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "project_workflow_state": {
+      "name": "project_workflow_state",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "project_id": {
+          "name": "project_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workflow_type": {
+          "name": "workflow_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workflow_instance_id": {
+          "name": "workflow_instance_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "template_slug": {
+          "name": "template_slug",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'draft'"
+        },
+        "form_json": {
+          "name": "form_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "layout_json": {
+          "name": "layout_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "selection_json": {
+          "name": "selection_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 1
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "project_workflow_state_project_idx": {
+          "name": "project_workflow_state_project_idx",
+          "columns": [
+            "project_id"
+          ],
+          "isUnique": false
+        },
+        "project_workflow_state_unique": {
+          "name": "project_workflow_state_unique",
+          "columns": [
+            "project_id",
+            "workflow_type",
+            "workflow_instance_id"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "project_workflow_state_project_id_project_id_fk": {
+          "name": "project_workflow_state_project_id_project_id_fk",
+          "tableFrom": "project_workflow_state",
+          "tableTo": "project",
+          "columnsFrom": [
+            "project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "asset": {
+      "name": "asset",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "source": {
+          "name": "source",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "asset_class": {
+          "name": "asset_class",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'original'"
+        },
+        "storage_provider": {
+          "name": "storage_provider",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "bucket": {
+          "name": "bucket",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'beatapi'"
+        },
+        "object_key": {
+          "name": "object_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "public_url": {
+          "name": "public_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "filename": {
+          "name": "filename",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "mime_type": {
+          "name": "mime_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "size_bytes": {
+          "name": "size_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sha256": {
+          "name": "sha256",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "width": {
+          "name": "width",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "height": {
+          "name": "height",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "duration_ms": {
+          "name": "duration_ms",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "origin_project_id": {
+          "name": "origin_project_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "thumbnail_asset_id": {
+          "name": "thumbnail_asset_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "asset_type_idx": {
+          "name": "asset_type_idx",
+          "columns": [
+            "type"
+          ],
+          "isUnique": false
+        },
+        "asset_class_idx": {
+          "name": "asset_class_idx",
+          "columns": [
+            "asset_class"
+          ],
+          "isUnique": false
+        },
+        "asset_origin_project_idx": {
+          "name": "asset_origin_project_idx",
+          "columns": [
+            "origin_project_id"
+          ],
+          "isUnique": false
+        },
+        "asset_created_at_idx": {
+          "name": "asset_created_at_idx",
+          "columns": [
+            "created_at"
+          ],
+          "isUnique": false
+        },
+        "asset_bucket_object_key_unique": {
+          "name": "asset_bucket_object_key_unique",
+          "columns": [
+            "bucket",
+            "object_key"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "asset_origin_project_id_project_id_fk": {
+          "name": "asset_origin_project_id_project_id_fk",
+          "tableFrom": "asset",
+          "tableTo": "project",
+          "columnsFrom": [
+            "origin_project_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "asset_thumbnail_asset_id_asset_id_fk": {
+          "name": "asset_thumbnail_asset_id_asset_id_fk",
+          "tableFrom": "asset",
+          "tableTo": "asset",
+          "columnsFrom": [
+            "thumbnail_asset_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/drizzle/d1/meta/_journal.json b/drizzle/d1/meta/_journal.json
index 6d3a0b5..4b1fca2 100644
--- a/drizzle/d1/meta/_journal.json
+++ b/drizzle/d1/meta/_journal.json
@@ -15,6 +15,20 @@
       "when": 1787227875042,
       "tag": "0001_tiresome_xavin",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1788020112960,
+      "tag": "0002_lethal_micromacro",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "6",
+      "when": 1788060451792,
+      "tag": "0003_slow_the_phantom",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/integrations/codex/beatdesign/.codex-plugin/plugin.json b/integrations/codex/beatdesign/.codex-plugin/plugin.json
new file mode 100644
index 0000000..e7724ad
--- /dev/null
+++ b/integrations/codex/beatdesign/.codex-plugin/plugin.json
@@ -0,0 +1,27 @@
+{
+  "name": "beatdesign",
+  "version": "0.2.0",
+  "description": "Control a local BeatDesign Canvas, generation workspace, and video Editor through MCP.",
+  "author": {
+    "name": "BeatAPI"
+  },
+  "homepage": "https://github.com/BeatAPI/BeatDesign",
+  "repository": "https://github.com/BeatAPI/BeatDesign",
+  "license": "Apache-2.0",
+  "keywords": ["beatdesign", "canvas", "video-editor", "generation", "mcp"],
+  "interface": {
+    "displayName": "BeatDesign",
+    "shortDescription": "Create and edit local media projects",
+    "longDescription": "BeatDesign connects Codex to a free local-first Canvas and video Editor. Read projects and Assets, generate media with logical model capabilities, and apply safe incremental Canvas or timeline edits.",
+    "developerName": "BeatAPI",
+    "category": "Design",
+    "capabilities": ["Read", "Write"],
+    "defaultPrompt": [
+      "Open my latest BeatDesign project and summarize the canvas",
+      "Turn these project assets into a rough video timeline",
+      "Diagnose the current timeline and fix safe editing issues"
+    ],
+    "brandColor": "#111111"
+  },
+  "mcpServers": "./.mcp.json"
+}
diff --git a/integrations/codex/beatdesign/.mcp.json b/integrations/codex/beatdesign/.mcp.json
new file mode 100644
index 0000000..fd0aa3e
--- /dev/null
+++ b/integrations/codex/beatdesign/.mcp.json
@@ -0,0 +1,17 @@
+{
+  "mcpServers": {
+    "beatdesign": {
+      "command": "./scripts/launch_beatdesign_mcp",
+      "cwd": ".",
+      "env_vars": [
+        "BEATDESIGN_ROOT",
+        "NODE_ENV",
+        "DATABASE_PROVIDER",
+        "DATABASE_URL",
+        "DATABASE_AUTH_TOKEN",
+        "GENERATION_PROVIDER"
+      ],
+      "tool_timeout_sec": 3600
+    }
+  }
+}
diff --git a/integrations/codex/beatdesign/README.md b/integrations/codex/beatdesign/README.md
new file mode 100644
index 0000000..c1aafff
--- /dev/null
+++ b/integrations/codex/beatdesign/README.md
@@ -0,0 +1,74 @@
+# BeatDesign Codex plugin
+
+This folder is only a **Codex packaging wrapper**. It starts the same local
+stdio MCP server as `pnpm mcp`. It does not embed the Canvas UI.
+
+## What actually happens
+
+```text
+Browser: pnpm dev  →  http://127.0.0.1:3020  (you look at Canvas/Editor)
+Agent:   MCP stdio →  pnpm mcp               (Agent calls 20 tools)
+Both processes share the same local SQLite + project files.
+```
+
+The Agent does **not** open a BeatDesign sidebar inside Codex. You keep the
+browser open; the Agent writes through MCP; the UI polls and refreshes.
+
+You do **not** need this plugin for every Agent. Any MCP host that can start a
+local stdio command can use BeatDesign. The Codex plugin is only the convenient
+install shape for Codex.
+
+## Local Codex install (no marketplace)
+
+1. `pnpm install && pnpm db:push && pnpm dev` in the BeatDesign repo.
+2. In Codex, install a **local plugin from folder**:
+   `integrations/codex/beatdesign`
+3. If Codex copies the plugin elsewhere, set
+   `BEATDESIGN_ROOT=/absolute/path/to/Beat Design`
+4. Start a new Codex thread and check that `bdesign_project_list` exists.
+
+Marketplace submission is later. Local folder install is enough to test.
+
+## Other Agents
+
+Same MCP command, different config files:
+
+| Host | Needs Codex plugin? | Config |
+|---|---|---|
+| Codex | Yes, this folder | Local plugin install |
+| Claude Code | No | Repo-root `.mcp.json` |
+| OpenCode | No | `opencode.json` `mcp.beatdesign` local command |
+| Cursor / generic MCP | No | stdio `pnpm --silent mcp` |
+| Pi / WorkBuddy / Hermes | Only if that host speaks MCP stdio | Same command |
+
+Generic stdio config:
+
+```json
+{
+  "mcpServers": {
+    "beatdesign": {
+      "command": "pnpm",
+      "args": ["--silent", "mcp"]
+    }
+  }
+}
+```
+
+OpenCode:
+
+```json
+{
+  "mcp": {
+    "beatdesign": {
+      "type": "local",
+      "command": ["pnpm", "--silent", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Run the host **from the BeatDesign repository** so `pnpm mcp` can find
+`package.json`. If the host starts in another directory, point `command` at
+this repo's `node_modules/.bin/tsx` and `scripts/mcp-server.ts`, or set
+`BEATDESIGN_ROOT`.
diff --git a/integrations/codex/beatdesign/scripts/launch_beatdesign_mcp b/integrations/codex/beatdesign/scripts/launch_beatdesign_mcp
new file mode 100755
index 0000000..f2c298e
--- /dev/null
+++ b/integrations/codex/beatdesign/scripts/launch_beatdesign_mcp
@@ -0,0 +1,23 @@
+#!/bin/sh
+set -eu
+
+launcher_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+plugin_root=$(CDPATH= cd -- "$launcher_dir/.." && pwd)
+workspace_root=${BEATDESIGN_ROOT:-}
+
+if [ -z "$workspace_root" ]; then
+  workspace_root=$(CDPATH= cd -- "$plugin_root/../../.." && pwd)
+fi
+
+if [ ! -f "$workspace_root/package.json" ]; then
+  echo "BeatDesign root not found. Set BEATDESIGN_ROOT to the cloned repository path." >&2
+  exit 1
+fi
+
+tsx_bin="$workspace_root/node_modules/.bin/tsx"
+if [ ! -x "$tsx_bin" ]; then
+  echo "BeatDesign dependencies are missing. Run pnpm install in BEATDESIGN_ROOT." >&2
+  exit 1
+fi
+
+exec "$tsx_bin" "$workspace_root/scripts/mcp-server.ts"
diff --git a/messages/en.json b/messages/en.json
index 3bd7619..b81ab17 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -137,8 +137,10 @@
         "recentAssetsTitle": "Recent assets",
         "recentImages": "Recent images",
         "recentVideos": "Recent videos",
+        "recentAudios": "Recent audio",
         "recentImageAlt": "Recent image",
         "recentVideoAlt": "Recent video",
+        "recentAudioAlt": "Recent audio",
         "loading": "Loading...",
         "loadFailed": "Failed to load assets",
         "emptyAssets": "No assets yet"
@@ -557,6 +559,129 @@
       "emptyDescription": "Create your first project to start building a canvas-driven pipeline for product images and videos.",
       "updatedAt": "Updated {value}"
     },
+    "editor": {
+      "media": {
+        "eyebrow": "Local media",
+        "title": "Project source",
+        "drop": "Drop an image or video here",
+        "localOnly": "The original stays on this device",
+        "stillDuration": "Still image · {duration}s"
+      },
+      "empty": {
+        "title": "Import an image or video to start editing",
+        "description": "Drop a local image or MP4. Arrange, trim, preview, and export without installing system FFmpeg."
+      },
+      "status": {
+        "ready": "Ready",
+        "reading": "Reading media…",
+        "saving": "Saving…",
+        "saved": "Saved locally",
+        "canvasAdded": "Timeline added to Canvas"
+      },
+      "actions": {
+        "import": "Import image or video",
+        "importAudio": "Import audio",
+        "play": "Play selection",
+        "pause": "Pause",
+        "split": "Split",
+        "undo": "Undo edit",
+        "redoEdit": "Redo edit",
+        "redo": "AI redo",
+        "redoHint": "Redo the selected range with BeatAPI",
+        "extract": "Extract asset",
+        "addTimelineToCanvas": "Add timeline to Canvas",
+        "export": "Export MP4",
+        "exporting": "Export {progress}%",
+        "cancelExport": "Cancel {progress}%"
+      },
+      "redo": {
+        "title": "AI redo selection",
+        "description": "The selected range is extracted non-destructively and sent to one verified BeatAPI video-to-video path.",
+        "close": "Close AI redo",
+        "billingNotice": "Uses your configured BeatAPI key and may consume API credits.",
+        "placeholder": "Describe how this selected clip should be remade…",
+        "confirm": "Confirm and generate",
+        "running": "Generating…",
+        "takes": "Takes",
+        "original": "Original clip",
+        "rollback": "Restore original",
+        "preparing": "Preparing the selected range…",
+        "ready": "New Take is ready. Preview it before replacing the clip.",
+        "status": {
+          "validating": "Validating BeatAPI request…",
+          "uploading": "Uploading the derived clip…",
+          "submitting": "Submitting generation…",
+          "processing": "BeatAPI is generating a new Take…",
+          "succeeded": "Generation completed."
+        }
+      },
+      "trim": {
+        "in": "In",
+        "out": "Out"
+      },
+      "timeline": {
+        "tracks": "Tracks",
+        "title": "Timeline",
+        "visualTrack": "Visual 1",
+        "audioTrack": "Audio 1",
+        "start": "Start",
+        "dragHint": "Drag the clip to move · drag either edge to trim",
+        "trimStart": "Drag to trim the clip start",
+        "trimEnd": "Drag to trim the clip end",
+        "seek": "Move timeline playhead",
+        "seekHint": "Click to move the playhead",
+        "delete": "Delete",
+        "rippleDelete": "Ripple delete"
+      },
+      "clipInspector": {
+        "sourceRange": "Source range",
+        "sourceFrom": "Source start",
+        "sourceTo": "Source end",
+        "stillDuration": "Still duration",
+        "clipDuration": "Clip duration",
+        "timelinePosition": "Timeline position",
+        "exactControls": "Exact",
+        "type": {
+          "image": "Still image",
+          "video": "Video clip",
+          "audio": "Audio clip"
+        }
+      },
+      "audio": {
+        "volume": "Volume",
+        "fadeIn": "Fade in",
+        "fadeOut": "Fade out",
+        "mute": "Mute",
+        "unmute": "Unmute"
+      },
+      "diagnostics": {
+        "timeline_gap": "Export is blocked because the visible video track contains a gap.",
+        "clip_overlap": "Export is blocked because clips overlap on the same track.",
+        "media_missing": "Export is blocked because a source file is missing.",
+        "take_duration_mismatch": "Export is blocked because the active AI Take is shorter than its timeline clip.",
+        "caption_overlap": "Export is blocked because captions overlap.",
+        "caption_out_of_video": "Export is blocked because a caption sits outside the video range.",
+        "tiny_clip": "A clip is too short to export reliably.",
+        "empty_track": "An empty track will be ignored."
+      },
+      "errors": {
+        "videoOnly": "Choose a video file.",
+        "visualOnly": "Choose an image or video file.",
+        "audioOnly": "Choose an MP3, WAV, M4A, AAC, or OGG audio file.",
+        "noVideoTrack": "This file does not contain a readable video track.",
+        "noAudioTrack": "This file does not contain a readable audio track.",
+        "inspectFailed": "The browser could not read this media file.",
+        "exportFailed": "MP4 export failed.",
+        "exportCancelled": "MP4 export was cancelled.",
+        "loadFailed": "The saved timeline could not be loaded.",
+        "saveFailed": "The timeline could not be saved.",
+        "sourceUnavailable": "The source video is no longer available.",
+        "canvasNodeFailed": "The timeline could not be added to Canvas.",
+        "redoAssetMissing": "The generated Take was not saved into project assets.",
+        "redoFailed": "BeatAPI could not redo this selection.",
+        "clipOverlap": "This position overlaps another clip on the same track."
+      }
+    },
     "header": {
       "backHome": "Back home",
       "untitledCanvas": "Untitled project",
@@ -570,22 +695,40 @@
       "studioDescription": "Focused generation and analysis",
       "canvas": "Canvas",
       "canvasDescription": "Visual multi-step workflow",
+      "editor": "Edit",
       "assets": "Assets",
       "projectAssets": {
         "triggerLabel": "Project assets",
         "title": "Project assets",
-        "description": "Studio and Canvas share this same collection. Every completed generation and project upload appears here.",
+        "description": "Studio, Canvas, and Edit share this collection. Uploads, generated media, tail frames, and timeline renders all appear here.",
         "canvasHint": "Click an asset to add it, or drag it anywhere onto the canvas.",
         "addToCanvas": "Add to canvas",
+        "addToTimeline": "Add to timeline",
+        "createTimeline": "Create timeline",
+        "continueFromTailFrame": "Continue from tail frame",
+        "extractingTailFrame": "Extracting the tail frame locally...",
+        "tailFrameName": "{name} tail frame",
+        "tailFrameInsertFailed": "The extracted tail frame could not be added to Canvas.",
+        "continuationInsertFailed": "The continuation generation node could not be created.",
+        "tailFrameFailed": "The tail frame could not be extracted.",
+        "continuationReady": "Tail frame saved. Describe the next shot to continue.",
+        "timelineCreated": "Timeline created from the selected clips",
+        "derivedClip": "Derived clip",
+        "tailFrame": "Tail frame",
+        "timelineRender": "Timeline render",
+        "timelineExtract": "Extracted clip",
         "openOriginal": "Open original",
         "addedToCanvas": "Added to canvas",
+        "addedToTimeline": "Added to timeline",
         "imageName": "Project image",
         "videoName": "Project video",
+        "audioName": "Project audio",
         "loading": "Loading project assets...",
         "loadFailed": "Project assets could not be loaded.",
         "empty": "Generate or upload an asset to start this project collection.",
         "images": "Images",
-        "videos": "Videos"
+        "videos": "Videos",
+        "audios": "Audio"
       },
       "apiConfig": {
         "triggerLabel": "API configuration",
diff --git a/messages/zh.json b/messages/zh.json
index 56712d7..591bf24 100644
--- a/messages/zh.json
+++ b/messages/zh.json
@@ -138,8 +138,10 @@
         "recentAssetsTitle": "最近素材",
         "recentImages": "最近图片",
         "recentVideos": "最近视频",
+        "recentAudios": "最近音频",
         "recentImageAlt": "最近图片",
         "recentVideoAlt": "最近视频",
+        "recentAudioAlt": "最近音频",
         "loading": "加载中...",
         "loadFailed": "加载素材失败",
         "emptyAssets": "还没有素材"
@@ -558,6 +560,129 @@
       "emptyDescription": "先创建第一个项目，再开始搭建基于画布的电商图片和视频工作流。",
       "updatedAt": "最近更新：{value}"
     },
+    "editor": {
+      "media": {
+        "eyebrow": "本地素材",
+        "title": "项目源文件",
+        "drop": "拖入图片或视频",
+        "localOnly": "原文件只保留在当前设备",
+        "stillDuration": "静态画面 {duration} 秒"
+      },
+      "empty": {
+        "title": "导入图片或视频，开始剪辑",
+        "description": "拖入本地图片、MP4 或选择文件，无需安装系统 FFmpeg，即可编排、裁剪、预览并导出。"
+      },
+      "status": {
+        "ready": "就绪",
+        "reading": "正在读取素材…",
+        "saving": "保存中…",
+        "saved": "已保存到本地",
+        "canvasAdded": "时间线已加入 Canvas"
+      },
+      "actions": {
+        "import": "导入图片或视频",
+        "importAudio": "导入音频",
+        "play": "播放选区",
+        "pause": "暂停",
+        "split": "分割",
+        "undo": "撤销剪辑",
+        "redoEdit": "重做剪辑",
+        "redo": "AI 重做",
+        "redoHint": "使用 BeatAPI 重做当前选区",
+        "extract": "截取为素材",
+        "addTimelineToCanvas": "时间线加入 Canvas",
+        "export": "导出 MP4",
+        "exporting": "导出 {progress}%",
+        "cancelExport": "取消 {progress}%"
+      },
+      "redo": {
+        "title": "AI 重做选区",
+        "description": "系统会非破坏式截取当前选区，并通过一条已验证的 BeatAPI 视频转视频路径重做。",
+        "close": "关闭 AI 重做",
+        "billingNotice": "将使用你配置的 BeatAPI Key，可能消耗 API 点数。",
+        "placeholder": "描述你希望怎样重做这一段视频…",
+        "confirm": "确认并生成",
+        "running": "生成中…",
+        "takes": "版本 Takes",
+        "original": "原始片段",
+        "rollback": "恢复原片段",
+        "preparing": "正在准备选区…",
+        "ready": "新 Take 已完成，请预览后再替换当前片段。",
+        "status": {
+          "validating": "正在校验 BeatAPI 请求…",
+          "uploading": "正在上传派生片段…",
+          "submitting": "正在提交生成任务…",
+          "processing": "BeatAPI 正在生成新 Take…",
+          "succeeded": "生成完成。"
+        }
+      },
+      "trim": {
+        "in": "入点",
+        "out": "出点"
+      },
+      "timeline": {
+        "tracks": "轨道",
+        "title": "时间线",
+        "visualTrack": "画面 1",
+        "audioTrack": "声音 1",
+        "start": "起始位置",
+        "dragHint": "拖动片段调整位置 · 拖动两侧边缘裁剪",
+        "trimStart": "拖动以裁剪片段开头",
+        "trimEnd": "拖动以裁剪片段结尾",
+        "seek": "移动时间线播放头",
+        "seekHint": "点击以移动播放头",
+        "delete": "删除",
+        "rippleDelete": "波纹删除"
+      },
+      "clipInspector": {
+        "sourceRange": "素材截取范围",
+        "sourceFrom": "素材起点",
+        "sourceTo": "素材终点",
+        "stillDuration": "画面持续时间",
+        "clipDuration": "片段时长",
+        "timelinePosition": "成片位置",
+        "exactControls": "精确参数",
+        "type": {
+          "image": "静态图片",
+          "video": "视频片段",
+          "audio": "音频片段"
+        }
+      },
+      "audio": {
+        "volume": "音量",
+        "fadeIn": "淡入",
+        "fadeOut": "淡出",
+        "mute": "静音",
+        "unmute": "取消静音"
+      },
+      "diagnostics": {
+        "timeline_gap": "可见视频轨存在空隙，已阻止导出，避免产生未解释的黑帧。",
+        "clip_overlap": "同一轨道存在片段重叠，已阻止导出。",
+        "media_missing": "有源素材文件缺失，已阻止导出。",
+        "take_duration_mismatch": "当前 AI Take 短于时间线片段，已阻止导出，避免尾帧冻结。",
+        "caption_overlap": "字幕存在重叠，已阻止导出。",
+        "caption_out_of_video": "有字幕超出视频范围，已阻止导出。",
+        "tiny_clip": "有片段过短，可能无法稳定导出。",
+        "empty_track": "空轨道将在导出时忽略。"
+      },
+      "errors": {
+        "videoOnly": "请选择视频文件。",
+        "visualOnly": "请选择图片或视频文件。",
+        "audioOnly": "请选择 MP3、WAV、M4A、AAC 或 OGG 音频文件。",
+        "noVideoTrack": "这个文件里没有可读取的视频轨道。",
+        "noAudioTrack": "这个文件里没有可读取的音频轨道。",
+        "inspectFailed": "浏览器无法读取这个媒体文件。",
+        "exportFailed": "MP4 导出失败。",
+        "exportCancelled": "已取消 MP4 导出。",
+        "loadFailed": "无法加载已保存的时间线。",
+        "saveFailed": "时间线保存失败。",
+        "sourceUnavailable": "源视频已无法访问。",
+        "canvasNodeFailed": "无法将时间线加入 Canvas。",
+        "redoAssetMissing": "生成结果没有保存到项目素材。",
+        "redoFailed": "BeatAPI 无法重做这个选区。",
+        "clipOverlap": "这个位置会与同一轨道上的其他片段重叠。"
+      }
+    },
     "header": {
       "backHome": "返回首页",
       "untitledCanvas": "未命名项目",
@@ -571,22 +696,40 @@
       "studioDescription": "专注生成与分析",
       "canvas": "Canvas",
       "canvasDescription": "可视化多步骤工作流",
+      "editor": "剪辑",
       "assets": "素材",
       "projectAssets": {
         "triggerLabel": "项目素材",
         "title": "项目素材",
-        "description": "Studio 与 Canvas 共用这组素材，项目内完成的生成结果和上传文件都会出现在这里。",
+        "description": "Studio、Canvas 和 Edit 共用这组素材。上传、生成结果、尾帧和时间线成片都会出现在这里。",
         "canvasHint": "点击素材即可加入，或直接拖到画布上的任意位置。",
         "addToCanvas": "加入画布",
+        "addToTimeline": "加入时间线",
+        "createTimeline": "创建时间线",
+        "continueFromTailFrame": "从尾帧续写",
+        "extractingTailFrame": "正在本地提取尾帧……",
+        "tailFrameName": "{name} 尾帧",
+        "tailFrameInsertFailed": "尾帧已提取，但无法加入画布。",
+        "continuationInsertFailed": "无法创建续写视频节点。",
+        "tailFrameFailed": "无法提取视频尾帧。",
+        "continuationReady": "尾帧已保存，请描述下一镜头后继续生成。",
+        "timelineCreated": "已用所选片段创建时间线",
+        "derivedClip": "派生片段",
+        "tailFrame": "尾帧",
+        "timelineRender": "时间线成片",
+        "timelineExtract": "截取片段",
         "openOriginal": "查看原文件",
         "addedToCanvas": "已加入画布",
+        "addedToTimeline": "已加入时间线",
         "imageName": "项目图片",
         "videoName": "项目视频",
+        "audioName": "项目音频",
         "loading": "正在加载项目素材...",
         "loadFailed": "暂时无法加载项目素材。",
         "empty": "生成或上传第一个素材，开始建立这个项目的素材集合。",
         "images": "图片",
-        "videos": "视频"
+        "videos": "视频",
+        "audios": "音频"
       },
       "apiConfig": {
         "triggerLabel": "API 配置",
diff --git a/package.json b/package.json
index 578c4c7..92336b8 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "beatdesign",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": true,
   "description": "The open-source, local-first AI canvas for image and video creation and analysis",
   "license": "Apache-2.0",
@@ -20,10 +20,11 @@
   "type": "module",
   "scripts": {
     "dev": "tsx scripts/prepare-paraglide.ts && vite dev --host 127.0.0.1 --port 3020",
-    "test": "sh -c 'rg --files src -g \"*.test.ts\" -g \"*.test.tsx\" | sort | xargs node --import tsx --test'",
+    "test": "node scripts/run-tests.mjs",
     "typecheck": "tsc --noEmit",
     "i18n:check": "node scripts/check-i18n.mjs",
     "media:localize": "tsx scripts/with-env.ts pnpm exec tsx scripts/localize-project-media.ts",
+    "mcp": "tsx scripts/mcp-server.ts",
     "prebuild": "node scripts/db-setup.mjs",
     "build": "tsx scripts/prepare-paraglide.ts && vite build && node scripts/sanitize-output.mjs",
     "start": "tsx scripts/with-env.ts node .output/server/index.mjs",
@@ -52,6 +53,7 @@
     "@fontsource-variable/space-grotesk": "^5.3.0",
     "@libsql/client": "^0.14.0",
     "@mdx-js/react": "^3.1.1",
+    "@modelcontextprotocol/server": "^2.0.0",
     "@tanstack/react-query": "^5.101.0",
     "@tanstack/react-router": "1.170.11",
     "@tanstack/react-start": "1.168.19",
@@ -62,6 +64,7 @@
     "drizzle-orm": "^0.45.2",
     "jszip": "^3.10.1",
     "lucide-react": "^0.511.0",
+    "mediabunny": "1.25.3",
     "motion": "^12.38.0",
     "next-themes": "^0.4.6",
     "react": "^19.2.1",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 3dd39ab..4087f90 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -56,6 +56,9 @@ importers:
       '@mdx-js/react':
         specifier: ^3.1.1
         version: 3.1.1(@types/react@19.2.14)(react@19.2.5)
+      '@modelcontextprotocol/server':
+        specifier: ^2.0.0
+        version: 2.0.0
       '@tanstack/react-query':
         specifier: ^5.101.0
         version: 5.101.0(react@19.2.5)
@@ -86,6 +89,9 @@ importers:
       lucide-react:
         specifier: ^0.511.0
         version: 0.511.0(react@19.2.5)
+      mediabunny:
+        specifier: 1.25.3
+        version: 1.25.3
       motion:
         specifier: ^12.38.0
         version: 12.38.0(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
@@ -1017,6 +1023,10 @@ packages:
     peerDependencies:
       rollup: '>=2'
 
+  '@modelcontextprotocol/core@2.0.0':
+    resolution: {integrity: sha512-pJCEwGG7Lfr/+PQp9ZTwKXNeO5wzbfKL7H3MYpCorM4oFBoQrdjnBgEoqG+RjhsvS1FKrDbKux+M1HhlnGWqcA==}
+    engines: {node: '>=20'}
+
   '@modelcontextprotocol/sdk@1.29.0':
     resolution: {integrity: sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==}
     engines: {node: '>=18'}
@@ -1027,6 +1037,10 @@ packages:
       '@cfworker/json-schema':
         optional: true
 
+  '@modelcontextprotocol/server@2.0.0':
+    resolution: {integrity: sha512-YhHWdHfpFMQfd0prsEnxKeS3Qz3ytIGmsS0sth4KDjnacIT7hxk6hXHkJ9KysxlkvTM+WZAtQbbcUhdoP4Hvtw==}
+    engines: {node: '>=20'}
+
   '@napi-rs/lzma-linux-x64-gnu@1.5.1':
     resolution: {integrity: sha512-oTXEIha4SsuXdTA4Iyskj0kpdx2yVXdhd75c2v3xGrHFfVMsbhTPZU/nMPL4sWKo4pBHm3aucLaqGlF696dTyQ==}
     engines: {node: ^22.20 || ^24.12 || >=25}
@@ -1842,6 +1856,12 @@ packages:
   '@types/debug@4.1.13':
     resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==}
 
+  '@types/dom-mediacapture-transform@0.1.12':
+    resolution: {integrity: sha512-d7/QsLRwF864A5mgIM/YrfiglHoYn7zgCcAoJgW404r+2DwnNr7EBbLnCWpmOMgH8y0te73L1AV6H1bmauaWFw==}
+
+  '@types/dom-webcodecs@0.1.13':
+    resolution: {integrity: sha512-O5hkiFIcjjszPIYyUSyvScyvrBoV3NOEEZx/pMlsu44TKzWNkLVBBxnxJz42in5n3QIolYOcBYFCPZZ0h8SkwQ==}
+
   '@types/estree-jsx@1.0.5':
     resolution: {integrity: sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==}
 
@@ -3060,6 +3080,9 @@ packages:
     resolution: {integrity: sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==}
     engines: {node: '>= 0.8'}
 
+  mediabunny@1.25.3:
+    resolution: {integrity: sha512-+LDXv/kybsElRQCmMlrdbKmPNvegeIyouGeOUzW5DJ8+M56H4G6wyEL2AJ1A45UcOB+U62qJMV7tuFO9S7yA7g==}
+
   merge-descriptors@2.0.0:
     resolution: {integrity: sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==}
     engines: {node: '>=18'}
@@ -5123,6 +5146,10 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  '@modelcontextprotocol/core@2.0.0':
+    dependencies:
+      zod: 4.4.3
+
   '@modelcontextprotocol/sdk@1.29.0(zod@3.25.76)':
     dependencies:
       '@hono/node-server': 1.19.13(hono@4.12.12)
@@ -5145,6 +5172,11 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  '@modelcontextprotocol/server@2.0.0':
+    dependencies:
+      '@modelcontextprotocol/core': 2.0.0
+      zod: 4.4.3
+
   '@napi-rs/lzma-linux-x64-gnu@1.5.1':
     optional: true
 
@@ -5866,6 +5898,12 @@ snapshots:
     dependencies:
       '@types/ms': 2.1.0
 
+  '@types/dom-mediacapture-transform@0.1.12':
+    dependencies:
+      '@types/dom-webcodecs': 0.1.13
+
+  '@types/dom-webcodecs@0.1.13': {}
+
   '@types/estree-jsx@1.0.5':
     dependencies:
       '@types/estree': 1.0.9
@@ -6985,6 +7023,11 @@ snapshots:
 
   media-typer@1.1.0: {}
 
+  mediabunny@1.25.3:
+    dependencies:
+      '@types/dom-mediacapture-transform': 0.1.12
+      '@types/dom-webcodecs': 0.1.13
+
   merge-descriptors@2.0.0: {}
 
   merge-stream@2.0.0: {}
diff --git a/scripts/localize-project-media.ts b/scripts/localize-project-media.ts
index 53f5c9a..a4b8f2c 100644
--- a/scripts/localize-project-media.ts
+++ b/scripts/localize-project-media.ts
@@ -38,7 +38,9 @@ const localizeProject = async (projectId: string) => {
   if (!state) return { cards: 0, files: 0 };
 
   const cardsWithRemoteMedia = state.snapshot.cards.filter(
-    (card) => Boolean(card.url && isOfficialBeatApiMediaUrl(card.url))
+    (card): card is typeof card & { type: 'image' | 'video'; url: string } =>
+      (card.type === 'image' || card.type === 'video') &&
+      Boolean(card.url && isOfficialBeatApiMediaUrl(card.url))
   );
   if (cardsWithRemoteMedia.length === 0) return { cards: 0, files: 0 };
 
diff --git a/scripts/mcp-server.ts b/scripts/mcp-server.ts
new file mode 100644
index 0000000..43f13b2
--- /dev/null
+++ b/scripts/mcp-server.ts
@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function loadEnvFile(path: string) {
+  if (!existsSync(path)) return false;
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const separator = trimmed.indexOf('=');
+    if (separator < 1) continue;
+    const key = trimmed.slice(0, separator).trim();
+    let value = trimmed.slice(separator + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    process.env[key] ??= value;
+  }
+  return true;
+}
+
+const nodeEnv = process.env.NODE_ENV || 'development';
+for (const filename of [
+  `.env.${nodeEnv}.local`,
+  `.env.${nodeEnv}`,
+  '.env.local',
+  '.env',
+]) {
+  if (loadEnvFile(resolve(filename))) break;
+}
+
+const { startBeatDesignMcpServer } = await import('../src/mcp/server');
+startBeatDesignMcpServer();
+console.error('BeatDesign MCP server is running on stdio.');
diff --git a/scripts/run-tests.mjs b/scripts/run-tests.mjs
new file mode 100644
index 0000000..215a24a
--- /dev/null
+++ b/scripts/run-tests.mjs
@@ -0,0 +1,28 @@
+import { spawnSync } from 'node:child_process';
+import { globSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const files = [
+  ...globSync('src/**/*.test.ts', { cwd: root }),
+  ...globSync('src/**/*.test.tsx', { cwd: root }),
+]
+  .sort()
+  .map((file) => join(root, file));
+
+if (files.length === 0) {
+  console.error('No test files found.');
+  process.exit(1);
+}
+
+const result = spawnSync(
+  process.execPath,
+  ['--import', 'tsx', '--test', ...files],
+  {
+    cwd: root,
+    stdio: 'inherit',
+  }
+);
+
+process.exit(result.status ?? 1);
diff --git a/src/components/app/product-page-shell.test.ts b/src/components/app/product-page-shell.test.ts
index 6d0d95c..5b8809a 100644
--- a/src/components/app/product-page-shell.test.ts
+++ b/src/components/app/product-page-shell.test.ts
@@ -21,11 +21,14 @@ test('workspace header keeps mode switching, shared assets, and API configuratio
   assert.match(shellSource, /\/assets\//);
   assert.match(shellSource, /header\.studio/);
   assert.match(shellSource, /header\.canvas/);
+  assert.match(shellSource, /header\.editor/);
   assert.match(shellSource, /header\.assets/);
   assert.match(shellSource, /href=\{`\/studio\/\$\{projectId\}`\}/);
   assert.match(shellSource, /href=\{`\/canvas\/\$\{projectId\}`\}/);
+  assert.match(shellSource, /href=\{`\/editor\/\$\{projectId\}`\}/);
   assert.match(shellSource, /aria-current=\{workspaceMode === 'studio'/);
   assert.match(shellSource, /aria-current=\{workspaceMode === 'canvas'/);
+  assert.match(shellSource, /aria-current=\{workspaceMode === 'editor'/);
   assert.match(shellSource, /aria-current=\{workspaceMode === 'assets'/);
   assert.doesNotMatch(shellSource, /DropdownMenu/);
   assert.doesNotMatch(shellSource, /ChevronDown/);
diff --git a/src/components/app/product-page-shell.tsx b/src/components/app/product-page-shell.tsx
index f18666c..620ab5a 100644
--- a/src/components/app/product-page-shell.tsx
+++ b/src/components/app/product-page-shell.tsx
@@ -2,7 +2,7 @@
 
 import type { ReactNode } from 'react';
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { Images, LayoutPanelTop, Workflow } from 'lucide-react';
+import { Images, LayoutPanelTop, Scissors, Workflow } from 'lucide-react';
 
 import { WorkspaceApiConfigDialog } from '@/components/app/workspace-api-config-dialog';
 import { GitHubIcon } from '@/components/icons/github';
@@ -159,6 +159,15 @@ export function ProductPageShell({
                     <Workflow className="size-3.5" aria-hidden="true" />
                     <span className="hidden sm:inline">{t('header.canvas')}</span>
                   </Link>
+                  <Link
+                    href={`/editor/${projectId}`}
+                    aria-current={workspaceMode === 'editor' ? 'page' : undefined}
+                    aria-label={t('header.editor')}
+                    className={workspaceTabClassName(workspaceMode === 'editor')}
+                  >
+                    <Scissors className="size-3.5" aria-hidden="true" />
+                    <span className="hidden sm:inline">{t('header.editor')}</span>
+                  </Link>
                   <Link
                     href={`/assets/${projectId}`}
                     aria-current={workspaceMode === 'assets' ? 'page' : undefined}
diff --git a/src/components/app/project-assets-dialog.tsx b/src/components/app/project-assets-dialog.tsx
index 2ff983d..06ae651 100644
--- a/src/components/app/project-assets-dialog.tsx
+++ b/src/components/app/project-assets-dialog.tsx
@@ -2,6 +2,7 @@
 
 import { useQuery } from '@tanstack/react-query';
 import {
+  AudioLines,
   ExternalLink,
   FolderOpen,
   Images,
@@ -11,6 +12,7 @@ import {
   Video,
 } from 'lucide-react';
 import { useState } from 'react';
+import { toast } from 'sonner';
 
 import {
   Dialog,
@@ -33,6 +35,13 @@ import {
   type ProjectAssetInsertDetail,
   type ProjectAssetTransfer,
 } from '@/core/beatcanvas/project-asset-transfer';
+import { addProjectAssetToTimeline } from '@/core/editor/timeline-client';
+
+const assetOperation = (asset: RecentAsset) => {
+  if (!asset.metadata || typeof asset.metadata !== 'object') return '';
+  const operation = (asset.metadata as { operation?: unknown }).operation;
+  return typeof operation === 'string' ? operation : '';
+};
 
 function AssetTile({
   asset,
@@ -41,16 +50,21 @@ function AssetTile({
   canAddToCanvas,
   onAdded,
   addLabel,
+  addTimelineLabel,
+  badgeLabel,
   openLabel,
 }: {
   asset: RecentAsset;
-  mediaType: 'image' | 'video';
+  mediaType: 'image' | 'video' | 'audio';
   projectId: string;
   canAddToCanvas: boolean;
   onAdded: () => void;
   addLabel: string;
+  addTimelineLabel: string;
+  badgeLabel: string | null;
   openLabel: string;
 }) {
+  const [isAddingToTimeline, setIsAddingToTimeline] = useState(false);
   const transfer: ProjectAssetTransfer = {
     ...asset,
     projectId,
@@ -84,12 +98,30 @@ function AssetTile({
       onDragEnd={(event) => {
         if (event.dataTransfer.dropEffect === 'copy') onAdded();
       }}
-      className={`group relative h-[200px] w-fit overflow-hidden rounded-[14px] bg-transparent transition hover:-translate-y-0.5 ${
+      className={`group relative overflow-hidden rounded-[14px] bg-white/[0.025] transition hover:-translate-y-0.5 ${
+        mediaType === 'audio' ? 'h-[112px] w-[360px]' : 'h-[200px] w-fit'
+      } ${
         canAddToCanvas ? 'cursor-grab active:cursor-grabbing' : ''
       }`}
       title={asset.filename || addLabel}
     >
-      {mediaType === 'video' ? (
+      {mediaType === 'audio' ? (
+        <div className="flex size-full flex-col justify-between border border-white/[0.08] px-4 py-3">
+          <div className="flex items-center gap-2">
+            <AudioLines className="size-4 text-[var(--beat-graph)]" />
+            <p className="min-w-0 flex-1 truncate text-xs font-medium text-white/80">
+              {asset.filename || asset.id}
+            </p>
+          </div>
+          <audio
+            src={asset.publicUrl}
+            controls
+            preload="metadata"
+            className="h-8 w-full opacity-75"
+            onPointerDown={(event) => event.stopPropagation()}
+          />
+        </div>
+      ) : mediaType === 'video' ? (
         <video
           src={asset.publicUrl}
           muted
@@ -109,20 +141,52 @@ function AssetTile({
           <Video className="size-3.5" />
         </span>
       ) : null}
+      {badgeLabel ? (
+        <span className="pointer-events-none absolute left-2 top-2 rounded-md border border-[#ff7a33]/25 bg-black/65 px-2 py-1 text-[9px] font-semibold uppercase tracking-[0.1em] text-[#ffad7e] backdrop-blur">
+          {badgeLabel}
+        </span>
+      ) : null}
 
-      {canAddToCanvas ? (
-        <button
-          type="button"
-          onClick={addToCanvas}
-          className="absolute inset-0 flex items-end justify-center bg-gradient-to-t from-black/80 via-black/5 to-transparent px-2 pb-2 opacity-0 transition duration-200 group-hover:opacity-100 group-focus-within:opacity-100"
-          aria-label={`${addLabel}: ${asset.filename || asset.id}`}
-        >
-          <span className="inline-flex h-7 items-center gap-1 rounded-full border border-white/15 bg-white/12 px-2.5 text-[10px] font-semibold text-white shadow-lg backdrop-blur-md">
-            <Plus className="size-3" />
-            {addLabel}
-          </span>
-        </button>
-      ) : (
+      {canAddToCanvas || mediaType === 'image' || mediaType === 'video' || mediaType === 'audio' ? (
+        <div className="absolute inset-0 flex items-end justify-center gap-1.5 bg-gradient-to-t from-black/85 via-black/10 to-transparent px-2 pb-2 opacity-0 transition duration-200 group-hover:opacity-100 group-focus-within:opacity-100">
+          {canAddToCanvas ? (
+            <button
+              type="button"
+              onClick={addToCanvas}
+              className="inline-flex h-7 items-center gap-1 rounded-full border border-white/15 bg-white/12 px-2.5 text-[10px] font-semibold text-white shadow-lg backdrop-blur-md"
+              aria-label={`${addLabel}: ${asset.filename || asset.id}`}
+            >
+              <Plus className="size-3" />
+              {addLabel}
+            </button>
+          ) : null}
+          {mediaType === 'image' || mediaType === 'video' || mediaType === 'audio' ? (
+            <button
+              type="button"
+              disabled={isAddingToTimeline}
+              onClick={() => {
+                if (isAddingToTimeline) return;
+                setIsAddingToTimeline(true);
+                void addProjectAssetToTimeline({ projectId, asset, mediaType })
+                  .then(() => toast.success(addTimelineLabel))
+                  .catch((error: Error) => toast.error(error.message))
+                  .finally(() => setIsAddingToTimeline(false));
+              }}
+              className="inline-flex h-7 items-center gap-1 rounded-full border border-white/15 bg-white/12 px-2.5 text-[10px] font-semibold text-white shadow-lg backdrop-blur-md disabled:cursor-wait disabled:opacity-55"
+              aria-label={`${addTimelineLabel}: ${asset.filename || asset.id}`}
+            >
+              {isAddingToTimeline ? (
+                <Loader2 className="size-3 animate-spin" />
+              ) : mediaType === 'image' ? (
+                  <Images className="size-3" />
+                ) : (
+                  <Video className="size-3" />
+              )}
+              {addTimelineLabel}
+            </button>
+          ) : null}
+        </div>
+      ) : mediaType === 'image' ? (
         <a
           href={asset.publicUrl}
           target="_blank"
@@ -130,7 +194,7 @@ function AssetTile({
           className="absolute inset-0"
           aria-label={`${openLabel}: ${asset.filename || asset.id}`}
         />
-      )}
+      ) : null}
 
       {canAddToCanvas ? (
         <a
@@ -166,7 +230,16 @@ export function ProjectAssetsLibrary({
   });
   const images = assetsQuery.data?.images ?? [];
   const videos = assetsQuery.data?.videos ?? [];
-  const total = images.length + videos.length;
+  const audios = assetsQuery.data?.audios ?? [];
+  const total = images.length + videos.length + audios.length;
+  const badgeFor = (asset: RecentAsset) => {
+    const operation = assetOperation(asset);
+    if (operation === 'video_tail_frame') return t('tailFrame');
+    if (operation === 'timeline_render') return t('timelineRender');
+    if (operation === 'timeline_extract') return t('timelineExtract');
+    if (asset.assetClass === 'derived') return t('derivedClip');
+    return null;
+  };
 
   return (
     <>
@@ -211,6 +284,8 @@ export function ProjectAssetsLibrary({
                     canAddToCanvas={canAddToCanvas}
                     onAdded={() => onAdded?.()}
                     addLabel={t('addToCanvas')}
+                    addTimelineLabel={t('addToTimeline')}
+                    badgeLabel={badgeFor(asset)}
                     openLabel={t('openOriginal')}
                   />
                 ))}
@@ -233,6 +308,32 @@ export function ProjectAssetsLibrary({
                     canAddToCanvas={canAddToCanvas}
                     onAdded={() => onAdded?.()}
                     addLabel={t('addToCanvas')}
+                    addTimelineLabel={t('addToTimeline')}
+                    badgeLabel={badgeFor(asset)}
+                    openLabel={t('openOriginal')}
+                  />
+                ))}
+              </div>
+            </section>
+          ) : null}
+
+          {audios.length > 0 ? (
+            <section>
+              <h3 className={`mb-3 ${beatPanelLabelClassName}`}>
+                {t('audios')}
+              </h3>
+              <div className="flex flex-wrap gap-3">
+                {audios.map((asset) => (
+                  <AssetTile
+                    key={asset.id}
+                    asset={asset}
+                    mediaType="audio"
+                    projectId={projectId}
+                    canAddToCanvas={canAddToCanvas}
+                    onAdded={() => onAdded?.()}
+                    addLabel={t('addToCanvas')}
+                    addTimelineLabel={t('addToTimeline')}
+                    badgeLabel={badgeFor(asset)}
                     openLabel={t('openOriginal')}
                   />
                 ))}
diff --git a/src/components/app/workspace-project-route-page.tsx b/src/components/app/workspace-project-route-page.tsx
index b25b5e2..2766cc8 100644
--- a/src/components/app/workspace-project-route-page.tsx
+++ b/src/components/app/workspace-project-route-page.tsx
@@ -2,6 +2,7 @@ import { ProductPageShell } from '@/components/app/product-page-shell';
 import { ProjectAssetsWorkspace } from '@/components/app/project-assets-workspace';
 import { BeatStudioWorkspace } from '@/components/studio/beat-studio-workspace';
 import { BeatCanvasShell } from '@/components/beatcanvas/beatcanvas-shell';
+import { VideoEditorWorkspace } from '@/components/editor/video-editor-workspace';
 import type { loadWorkspaceProjectRoute } from '@/core/projects/workspace-project-route-loader';
 
 type WorkspaceProjectRouteData = Awaited<
@@ -28,6 +29,11 @@ export function WorkspaceProjectRoutePage({
         />
       ) : data.workspaceMode === 'assets' ? (
         <ProjectAssetsWorkspace projectId={data.project.id} />
+      ) : data.workspaceMode === 'editor' ? (
+        <VideoEditorWorkspace
+          projectId={data.project.id}
+          projectName={data.project.name}
+        />
       ) : (
         <BeatCanvasShell
           projectId={data.project.id}
diff --git a/src/components/beatcanvas/beatcanvas-context-toolbar.test.tsx b/src/components/beatcanvas/beatcanvas-context-toolbar.test.tsx
index f4a18d2..c3398ce 100644
--- a/src/components/beatcanvas/beatcanvas-context-toolbar.test.tsx
+++ b/src/components/beatcanvas/beatcanvas-context-toolbar.test.tsx
@@ -36,3 +36,24 @@ test('context toolbar can render localized batch download actions', () => {
 
   assert.match(html, /Batch download/);
 });
+
+test('context toolbar exposes add-to-timeline for selected video or audio assets', () => {
+  const html = renderToStaticMarkup(
+    <BeatCanvasContextToolbar
+      canDownload={true}
+      canPreview={false}
+      downloadLabel="Download"
+      previewLabel={null}
+      addToTimelineLabel="Add to timeline"
+      canAddToTimeline={true}
+      onAddToTimeline={() => {}}
+      continueVideoLabel="Continue from tail frame"
+      canContinueVideo={true}
+      onContinueVideo={() => {}}
+      onDownload={() => {}}
+      onPreview={() => {}}
+    />
+  );
+  assert.match(html, /Add to timeline/);
+  assert.match(html, /Continue from tail frame/);
+});
diff --git a/src/components/beatcanvas/beatcanvas-context-toolbar.tsx b/src/components/beatcanvas/beatcanvas-context-toolbar.tsx
index 8c12be7..a4a894a 100644
--- a/src/components/beatcanvas/beatcanvas-context-toolbar.tsx
+++ b/src/components/beatcanvas/beatcanvas-context-toolbar.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { cn } from '@/lib/utils';
-import { Download, DownloadIcon, Eye } from 'lucide-react';
+import { Download, DownloadIcon, Eye, Film, Sparkles } from 'lucide-react';
 
 import { beatcanvasPanelClassName } from './beatcanvas-theme';
 
@@ -13,6 +13,12 @@ export function BeatCanvasContextToolbar({
   previewLabel,
   onDownload,
   onPreview,
+  addToTimelineLabel,
+  canAddToTimeline = false,
+  onAddToTimeline,
+  continueVideoLabel,
+  canContinueVideo = false,
+  onContinueVideo,
 }: {
   canDownload: boolean;
   canPreview: boolean;
@@ -21,6 +27,12 @@ export function BeatCanvasContextToolbar({
   previewLabel: string | null;
   onDownload: () => void;
   onPreview: () => void;
+  addToTimelineLabel?: string | null;
+  canAddToTimeline?: boolean;
+  onAddToTimeline?: () => void;
+  continueVideoLabel?: string | null;
+  canContinueVideo?: boolean;
+  onContinueVideo?: () => void;
 }) {
   const actionClassName =
     'inline-flex h-8 items-center gap-1.5 rounded-[11px] px-2.5 text-[12px] font-semibold text-[var(--beatcanvas-ink-soft)] transition-all duration-150 hover:bg-black/[0.045] hover:text-[var(--beatcanvas-ink)]';
@@ -58,6 +70,28 @@ export function BeatCanvasContextToolbar({
           <span>{previewLabel}</span>
         </button>
       ) : null}
+      {continueVideoLabel ? (
+        <button
+          type="button"
+          className={cn(actionClassName, !canContinueVideo && 'opacity-45')}
+          onClick={onContinueVideo}
+          disabled={!canContinueVideo}
+        >
+          <Sparkles className="size-4" strokeWidth={2.1} />
+          <span>{continueVideoLabel}</span>
+        </button>
+      ) : null}
+      {addToTimelineLabel ? (
+        <button
+          type="button"
+          className={cn(actionClassName, !canAddToTimeline && 'opacity-45')}
+          onClick={onAddToTimeline}
+          disabled={!canAddToTimeline}
+        >
+          <Film className="size-4" strokeWidth={2.1} />
+          <span>{addToTimelineLabel}</span>
+        </button>
+      ) : null}
     </section>
   );
 }
diff --git a/src/components/beatcanvas/beatcanvas-media-preview.test.ts b/src/components/beatcanvas/beatcanvas-media-preview.test.ts
index ea98405..4dd6985 100644
--- a/src/components/beatcanvas/beatcanvas-media-preview.test.ts
+++ b/src/components/beatcanvas/beatcanvas-media-preview.test.ts
@@ -30,7 +30,7 @@ const makeCard = (overrides: Partial<CanvasCard>): CanvasCard => ({
   quality: 'standard',
   sourceGenerationId: null,
   ...overrides,
-});
+}) as CanvasCard;
 
 test('recognizes real asset and generated media cards as previewable and downloadable', () => {
   assert.equal(isPreviewableCanvasCard(makeCard({})), true);
diff --git a/src/components/beatcanvas/beatcanvas-media-preview.ts b/src/components/beatcanvas/beatcanvas-media-preview.ts
index 6eef50d..1082663 100644
--- a/src/components/beatcanvas/beatcanvas-media-preview.ts
+++ b/src/components/beatcanvas/beatcanvas-media-preview.ts
@@ -13,7 +13,7 @@ export const isDownloadableCanvasCard = (
 
 export const isPreviewableCanvasCard = (
   card: CanvasCard | null | undefined
-) =>
+): card is CanvasCard & { type: 'image' | 'video'; url: string } =>
   Boolean(
     isDownloadableCanvasCard(card) &&
       card &&
diff --git a/src/components/beatcanvas/beatcanvas-shell.tsx b/src/components/beatcanvas/beatcanvas-shell.tsx
index 34f099c..2b2e856 100644
--- a/src/components/beatcanvas/beatcanvas-shell.tsx
+++ b/src/components/beatcanvas/beatcanvas-shell.tsx
@@ -31,6 +31,7 @@ import {
   rewriteCanvasReferenceAliases,
 } from '@/core/beatcanvas/reference-mentions';
 import { getSelectableModel } from '@/core/beatcanvas/generation-controller';
+import { resolveConcreteCanvasMediaCard } from '@/core/beatcanvas/generation-history';
 import {
   PROJECT_ASSET_DRAG_MIME,
   PROJECT_ASSET_INSERT_EVENT,
@@ -44,6 +45,11 @@ import { useQueryClient } from '@tanstack/react-query';
 import { useTranslations } from '@/core/workspace-lib/shims/next-intl';
 import { Suspense, lazy, useCallback, useEffect, useMemo, useState } from 'react';
 import { toast } from 'sonner';
+import {
+  addProjectAssetsToTimeline,
+} from '@/core/editor/timeline-client';
+import { extractVideoFrame } from '@/core/media/video-frame';
+import { uploadLocalProjectAsset } from '@/core/workspace-lib/app/local-project-asset-client';
 import { useCanvasComposerLabels } from './use-canvas-composer-labels';
 import { useProjectSnapshotLifecycle } from './use-project-snapshot-lifecycle';
 import { useBeatCanvasGraph } from './use-beatcanvas-graph';
@@ -264,6 +270,9 @@ export function BeatCanvasShell({
   const [previewMedia, setPreviewMedia] = useState<BeatCanvasPreviewMedia | null>(
     null
   );
+  const [isContinuingVideo, setIsContinuingVideo] = useState(false);
+  const [isAddingSelectionToTimeline, setIsAddingSelectionToTimeline] =
+    useState(false);
 
   const insertProjectAsset = useCallback(
     (
@@ -283,11 +292,18 @@ export function BeatCanvasShell({
         name:
           asset.filename?.trim() ||
           projectAssetsT(
-            asset.mediaType === 'image' ? 'imageName' : 'videoName'
+            asset.mediaType === 'image'
+              ? 'imageName'
+              : asset.mediaType === 'audio'
+                ? 'audioName'
+                : 'videoName'
           ),
         kind: 'asset',
         activateOnInsert: true,
         size,
+        durationSec:
+          typeof asset.durationMs === 'number' ? asset.durationMs / 1000 : null,
+        audioRole: asset.mediaType === 'audio' ? 'music' : undefined,
         ...(pagePoint
           ? {
               frame: {
@@ -877,6 +893,226 @@ export function BeatCanvasShell({
   const isGroupSelected = effectiveSelectedGroupCards.length > 0;
   const canDownloadSelection =
     isSingleDownloadable || downloadableGroupCards.length > 0;
+  const selectedCardsForActions = useMemo(
+    () =>
+      isGroupSelected
+        ? effectiveSelectedGroupCards
+        : selectedSingleCard
+          ? [selectedSingleCard]
+          : [],
+    [effectiveSelectedGroupCards, isGroupSelected, selectedSingleCard]
+  );
+  const selectedTimelineMedia = useMemo(
+    () =>
+      selectedCardsForActions.flatMap((sourceCard) => {
+        const mediaCard = resolveConcreteCanvasMediaCard({
+          cards: canvasCards,
+          card: sourceCard,
+        });
+        return mediaCard?.url &&
+          mediaCard.assetId &&
+          (mediaCard.type === 'video' || mediaCard.type === 'audio')
+          ? [{ sourceCard, mediaCard }]
+          : [];
+      }),
+    [canvasCards, selectedCardsForActions]
+  );
+  const canAddSelectionToTimeline = selectedTimelineMedia.length > 0;
+  const continuationSelection =
+    selectedTimelineMedia.length === 1 &&
+    selectedTimelineMedia[0]?.mediaCard.type === 'video'
+      ? selectedTimelineMedia[0]
+      : null;
+  const handleAddSelectionToTimeline = useCallback(() => {
+    if (selectedTimelineMedia.length === 0 || isAddingSelectionToTimeline) return;
+    setIsAddingSelectionToTimeline(true);
+    void addProjectAssetsToTimeline({
+      projectId,
+      assets: selectedTimelineMedia.map(({ mediaCard }) => ({
+        asset: {
+          id: mediaCard.assetId as string,
+          publicUrl: mediaCard.url!,
+          filename: mediaCard.name,
+          width: null,
+          height: null,
+          durationMs:
+            typeof mediaCard.durationSec === 'number'
+              ? mediaCard.durationSec * 1000
+              : null,
+          createdAt: new Date().toISOString(),
+        },
+        mediaType: mediaCard.type as 'video' | 'audio',
+      })),
+    })
+      .then((saved) => {
+        const document = saved.timeline?.document;
+        if (!document) return;
+        const cardId = `timeline:${document.id}`;
+        const sourceCardIds = selectedTimelineMedia.map(
+          ({ sourceCard }) => sourceCard.id
+        );
+        const clipCount = document.tracks.reduce(
+          (count, track) => count + track.clips.length,
+          0
+        );
+        const existing = canvasCardsRef.current[cardId];
+        if (existing?.kind === 'asset' && existing.type === 'timeline') {
+          recordCanvasHistory();
+          updateCanvasCard(cardId, {
+            durationSec: document.duration,
+            clipCount,
+            lastRenderAssetId: document.lastRenderAssetId,
+            url: document.lastRenderUrl,
+            referenceCardIds: Array.from(
+              new Set([...existing.referenceCardIds, ...sourceCardIds])
+            ),
+          });
+          const timelineShape = editorRef.current?.getShape?.(cardId as any) as
+            | { type: string; props?: Record<string, unknown> }
+            | undefined;
+          if (timelineShape) {
+            editorRef.current?.updateShape?.({
+              id: cardId,
+              type: timelineShape.type,
+              props: {
+                ...timelineShape.props,
+                title: document.name,
+                thumbnailUrl: document.lastRenderUrl ?? '',
+                durationSec: document.duration,
+                timelineId: document.id,
+                clipCount,
+              },
+            } as any);
+          }
+          for (const sourceCardId of sourceCardIds) {
+            createConnectorBetweenCards(sourceCardId, cardId);
+          }
+          focusShape(cardId);
+        } else {
+          insertAssetCard({
+            type: 'timeline',
+            url: document.lastRenderUrl,
+            name: document.name,
+            assetId: document.lastRenderAssetId,
+            sourceCardIds,
+            anchorCardIds: sourceCardIds,
+            shapeId: cardId,
+            size: { w: 360, h: 220 },
+            durationSec: document.duration,
+            timelineId: document.id,
+            clipCount,
+            lastRenderAssetId: document.lastRenderAssetId,
+          });
+        }
+        toast.success(
+          projectAssetsT(
+            selectedTimelineMedia.length > 1
+              ? 'timelineCreated'
+              : 'addedToTimeline'
+          )
+        );
+      })
+      .catch((error: Error) => toast.error(error.message))
+      .finally(() => setIsAddingSelectionToTimeline(false));
+  }, [
+    canvasCardsRef,
+    createConnectorBetweenCards,
+    editorRef,
+    focusShape,
+    insertAssetCard,
+    isAddingSelectionToTimeline,
+    projectAssetsT,
+    projectId,
+    recordCanvasHistory,
+    selectedTimelineMedia,
+    updateCanvasCard,
+  ]);
+
+  const handleContinueFromTailFrame = useCallback(() => {
+    if (
+      !continuationSelection?.mediaCard.url ||
+      !continuationSelection.mediaCard.assetId ||
+      isContinuingVideo
+    )
+      return;
+    const { mediaCard, sourceCard } = continuationSelection;
+    void (async () => {
+      setIsContinuingVideo(true);
+      setErrorMessage(null);
+      setStatusMessage(projectAssetsT('extractingTailFrame'));
+      try {
+        const frame = await extractVideoFrame({
+          url: mediaCard.url!,
+          position: 'last',
+          filename: `${sanitizeDownloadName(mediaCard.name) || 'video'}-tail-frame.png`,
+        });
+        const asset = await uploadLocalProjectAsset({
+          projectId,
+          file: frame.file,
+          assetClass: 'derived',
+          metadata: {
+            operation: 'video_tail_frame',
+            parentAssetId: mediaCard.assetId,
+            sourceCardId: sourceCard.id,
+            sourceTimeSec: frame.timeSeconds,
+            sourceDurationSec: frame.durationSeconds,
+            relation: 'continuation_first_frame',
+          },
+        });
+        await invalidateWorkspaceAfterAssetMutation(queryClient);
+        const maxEdge = 320;
+        const ratio = frame.width / frame.height;
+        const size =
+          ratio >= 1
+            ? { w: maxEdge, h: Math.round(maxEdge / ratio) }
+            : { w: Math.round(maxEdge * ratio), h: maxEdge };
+        const tailFrameCardId = insertAssetCard({
+          type: 'image',
+          url: asset.publicUrl,
+          name: projectAssetsT('tailFrameName', { name: mediaCard.name }),
+          assetId: asset.id,
+          sourceCardIds: [sourceCard.id],
+          anchorCardIds: [sourceCard.id],
+          size,
+          fitMode: 'contain',
+        });
+        if (!tailFrameCardId) {
+          throw new Error(projectAssetsT('tailFrameInsertFailed'));
+        }
+        const nextDraftId = createDraftCard({
+          taskType: 'video',
+          prompt: '',
+          referenceCardIds: [tailFrameCardId],
+          anchorCardIds: [tailFrameCardId],
+          placementSide: 'right',
+        });
+        if (!nextDraftId) {
+          throw new Error(projectAssetsT('continuationInsertFailed'));
+        }
+        setStatusMessage('');
+        toast.success(projectAssetsT('continuationReady'), {
+          id: `continuation-${sourceCard.id}`,
+        });
+      } catch (error) {
+        setStatusMessage('');
+        setErrorMessage(
+          error instanceof Error
+            ? error.message
+            : projectAssetsT('tailFrameFailed')
+        );
+      } finally {
+        setIsContinuingVideo(false);
+      }
+    })();
+  }, [
+    continuationSelection,
+    createDraftCard,
+    insertAssetCard,
+    isContinuingVideo,
+    projectAssetsT,
+    projectId,
+    queryClient,
+  ]);
 
   const resolveDownloadUrl = useCallback((card: CanvasCard) => {
     if (!card.url) {
@@ -906,7 +1142,13 @@ export function BeatCanvasShell({
         }
       } catch {}
 
-      return `${baseName}.${card.type === 'video' ? 'mp4' : 'png'}`;
+      const fallbackExtension =
+        card.type === 'video' || card.type === 'timeline'
+          ? 'mp4'
+          : card.type === 'audio'
+            ? 'mp3'
+            : 'png';
+      return `${baseName}.${fallbackExtension}`;
     },
     [resolveDownloadUrl]
   );
@@ -1070,7 +1312,10 @@ export function BeatCanvasShell({
       ? studioT('multiSelect.download')
       : null;
   const showContextToolbar = Boolean(
-    canPreviewSelection || isSingleDownloadable || isGroupSelected
+    canPreviewSelection ||
+      isSingleDownloadable ||
+      isGroupSelected ||
+      canAddSelectionToTimeline
   );
   const snapshotChangeSignal = useMemo(
     () => ({
@@ -1415,6 +1660,28 @@ export function BeatCanvasShell({
                   void handleDownloadSelection();
                 }}
                 onPreview={handlePreviewSelection}
+                continueVideoLabel={
+                  continuationSelection
+                    ? projectAssetsT('continueFromTailFrame')
+                    : null
+                }
+                canContinueVideo={Boolean(
+                  continuationSelection && !isContinuingVideo
+                )}
+                onContinueVideo={handleContinueFromTailFrame}
+                addToTimelineLabel={
+                  canAddSelectionToTimeline
+                    ? projectAssetsT(
+                        selectedTimelineMedia.length > 1
+                          ? 'createTimeline'
+                          : 'addToTimeline'
+                      )
+                    : null
+                }
+                canAddToTimeline={
+                  canAddSelectionToTimeline && !isAddingSelectionToTimeline
+                }
+                onAddToTimeline={handleAddSelectionToTimeline}
               />
             </Suspense>
           ) : null}
diff --git a/src/components/beatcanvas/beatcanvas-sidebar-panels.tsx b/src/components/beatcanvas/beatcanvas-sidebar-panels.tsx
index d3c38e1..0d523ac 100644
--- a/src/components/beatcanvas/beatcanvas-sidebar-panels.tsx
+++ b/src/components/beatcanvas/beatcanvas-sidebar-panels.tsx
@@ -8,6 +8,7 @@ import { recentAssetsKeys } from '@/core/workspace-lib/app/workspace-query-keys'
 import { useTranslations } from '@/core/workspace-lib/shims/next-intl';
 import { useQuery } from '@tanstack/react-query';
 import {
+  AudioLines,
   Loader2,
   Video,
 } from 'lucide-react';
@@ -21,7 +22,7 @@ export function HistoryPanel({
   projectId,
 }: {
   onSelectAsset: (
-    asset: RecentAsset & { mediaType: 'image' | 'video' }
+    asset: RecentAsset & { mediaType: 'image' | 'video' | 'audio' }
   ) => void;
   projectId?: string | null;
 }) {
@@ -34,10 +35,11 @@ export function HistoryPanel({
 
   const images = data?.images ?? [];
   const videos = data?.videos ?? [];
+  const audios = data?.audios ?? [];
   const loading = isLoading;
   const error = isError ? t('sidebar.loadFailed') : null;
 
-  const hasContent = images.length > 0 || videos.length > 0;
+  const hasContent = images.length > 0 || videos.length > 0 || audios.length > 0;
 
   return (
     <div className="flex flex-col p-2">
@@ -88,6 +90,25 @@ export function HistoryPanel({
           ))}
         </AssetSection>
       ) : null}
+
+      {!loading && audios.length > 0 ? (
+        <AssetSection label={t('sidebar.recentAudios')}>
+          {audios.map((audio) => (
+            <button
+              key={audio.id}
+              type="button"
+              onClick={() => onSelectAsset({ ...audio, mediaType: 'audio' })}
+              className="group flex aspect-square flex-col items-center justify-center gap-1 overflow-hidden rounded-lg border border-white/[0.08] bg-white/[0.04] text-white/50 transition hover:border-[var(--beat-graph)] hover:text-white"
+              title={audio.filename || t('sidebar.recentAudioAlt')}
+            >
+              <AudioLines className="size-5 text-[var(--beat-graph)]" />
+              <span className="max-w-full truncate px-1 text-[9px]">
+                {audio.filename || t('sidebar.recentAudioAlt')}
+              </span>
+            </button>
+          ))}
+        </AssetSection>
+      ) : null}
     </div>
   );
 }
diff --git a/src/components/beatcanvas/beatcanvas-sidebar.tsx b/src/components/beatcanvas/beatcanvas-sidebar.tsx
index 848d948..a81ab12 100644
--- a/src/components/beatcanvas/beatcanvas-sidebar.tsx
+++ b/src/components/beatcanvas/beatcanvas-sidebar.tsx
@@ -27,7 +27,7 @@ export type BeatCanvasSidebarProps = {
   onUploadMedia: () => void;
   onCreateImageDraft: () => void;
   onInsertHistoryAsset: (
-    asset: RecentAsset & { mediaType: 'image' | 'video' }
+    asset: RecentAsset & { mediaType: 'image' | 'video' | 'audio' }
   ) => void;
   uploadIntent: SidebarUploadIntent | null;
 };
diff --git a/src/components/beatcanvas/nodes/asset-card-node.tsx b/src/components/beatcanvas/nodes/asset-card-node.tsx
index fa73118..03ae266 100644
--- a/src/components/beatcanvas/nodes/asset-card-node.tsx
+++ b/src/components/beatcanvas/nodes/asset-card-node.tsx
@@ -6,11 +6,31 @@ import {
   Position,
   type NodeProps,
 } from '@xyflow/react';
-import { useEffect, useState, type MouseEvent } from 'react';
+import {
+  useEffect,
+  useRef,
+  useState,
+  type MouseEvent,
+  type VideoHTMLAttributes,
+} from 'react';
 
+import { enqueueMediaMetadataLoad } from '@/core/media/media-load-queue';
 import { getBeatCanvasNodeCopy } from './beatcanvas-node-copy';
 import type { BeatCanvasFlowNode } from '../react-flow/beatcanvas-react-flow-types';
 
+function QueuedVideo({
+  src,
+  ...props
+}: VideoHTMLAttributes<HTMLVideoElement> & { src: string }) {
+  const videoRef = useRef<HTMLVideoElement>(null);
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video || !src) return;
+    return enqueueMediaMetadataLoad(video, src);
+  }, [src]);
+  return <video ref={videoRef} {...props} />;
+}
+
 const CARD_RADIUS = 8;
 
 export function AssetCardNode({
@@ -21,8 +41,18 @@ export function AssetCardNode({
   const props = data.props;
   if (!('thumbnailUrl' in props)) return null;
 
-  const { w, h, cardMediaType, title, thumbnailUrl, fitMode, chromeMode } =
-    props;
+  const {
+    w,
+    h,
+    cardMediaType,
+    title,
+    thumbnailUrl,
+    fitMode,
+    chromeMode,
+    durationSec,
+    audioRole,
+    clipCount,
+  } = props;
   const shapeCopy = getBeatCanvasNodeCopy();
   const isContain = fitMode === 'contain';
   const isFrameless = chromeMode === 'frameless';
@@ -37,7 +67,8 @@ export function AssetCardNode({
   const canPreviewMedia =
     Boolean(thumbnailUrl) &&
     (cardMediaType === 'video' ||
-      !thumbnailUrl.startsWith('data:image/svg+xml'));
+      (cardMediaType === 'image' &&
+        !thumbnailUrl.startsWith('data:image/svg+xml')));
 
   const handlePreviewMedia = (event: MouseEvent<HTMLElement>) => {
     if (!canPreviewMedia || typeof window === 'undefined') return;
@@ -56,6 +87,14 @@ export function AssetCardNode({
     );
   };
 
+  const openTimelineEditor = (event: MouseEvent<HTMLElement>) => {
+    if (cardMediaType !== 'timeline' || typeof window === 'undefined') return;
+    event.preventDefault();
+    event.stopPropagation();
+    const nextPath = window.location.pathname.replace('/canvas/', '/editor/');
+    window.location.assign(nextPath || window.location.pathname);
+  };
+
   return (
     <>
       <NodeResizer
@@ -95,7 +134,7 @@ export function AssetCardNode({
           boxSizing: 'border-box',
         }}
       >
-        {!thumbnailUrl && (
+        {!thumbnailUrl && cardMediaType !== 'audio' && cardMediaType !== 'timeline' && (
           <div
             style={{
               position: 'absolute',
@@ -114,7 +153,82 @@ export function AssetCardNode({
               (cardMediaType === 'video' ? shapeCopy.video : shapeCopy.image)}
           </div>
         )}
-        {thumbnailUrl && mediaStatus === 'error' ? (
+        {cardMediaType === 'audio' ? (
+          <div className="flex size-full flex-col justify-between px-4 py-3">
+            <div className="flex items-center justify-between gap-3">
+              <div className="min-w-0">
+                <p className="truncate text-[12px] font-semibold text-white">{title}</p>
+                <p className="mt-0.5 text-[10px] uppercase tracking-[0.12em] text-white/38">
+                  {audioRole?.replace('_', ' ') || 'audio'}
+                </p>
+              </div>
+              <span className="font-mono text-[10px] tabular-nums text-white/45">
+                {typeof durationSec === 'number' ? `${durationSec.toFixed(2)}s` : '—'}
+              </span>
+            </div>
+            <div className="flex h-7 items-center gap-[3px]" aria-hidden="true">
+              {Array.from({ length: 28 }, (_, index) => (
+                <span
+                  key={index}
+                  className="w-[2px] flex-1 rounded-full bg-[var(--beat-graph)]/70"
+                  style={{ height: `${22 + ((index * 37) % 72)}%` }}
+                />
+              ))}
+            </div>
+            {thumbnailUrl ? (
+              <audio
+                src={thumbnailUrl}
+                controls
+                preload="metadata"
+                className="nodrag nopan nowheel h-7 w-full opacity-80"
+                onLoadedMetadata={() => setMediaStatus('ready')}
+                onError={() => setMediaStatus('error')}
+                onPointerDown={(event) => event.stopPropagation()}
+              />
+            ) : null}
+          </div>
+        ) : cardMediaType === 'timeline' ? (
+          <button
+            type="button"
+            onClick={openTimelineEditor}
+            onDoubleClick={openTimelineEditor}
+            className="nodrag nopan flex size-full flex-col text-left"
+          >
+            <div className="relative flex-1 overflow-hidden bg-black/45">
+              {thumbnailUrl ? (
+                <QueuedVideo
+                  src={thumbnailUrl}
+                  muted
+                  playsInline
+                  preload="metadata"
+                  className="size-full object-cover opacity-70"
+                  onLoadedMetadata={() => setMediaStatus('ready')}
+                  onError={() => setMediaStatus('error')}
+                />
+              ) : (
+                <div className="grid size-full place-items-center text-[11px] uppercase tracking-[0.18em] text-white/28">
+                  Timeline
+                </div>
+              )}
+              <span className="absolute left-3 top-3 rounded-md border border-white/10 bg-black/55 px-2 py-1 text-[9px] font-semibold uppercase tracking-[0.14em] text-white/65">
+                Timeline
+              </span>
+            </div>
+            <div className="border-t border-white/10 px-3 py-2.5">
+              <div className="flex items-center justify-between gap-2">
+                <p className="truncate text-[12px] font-semibold text-white">{title}</p>
+                <span className="font-mono text-[10px] tabular-nums text-white/40">
+                  {typeof durationSec === 'number' ? `${durationSec.toFixed(1)}s` : '0.0s'}
+                </span>
+              </div>
+              <div className="mt-2 flex h-2 gap-1 rounded-sm bg-white/[0.04] p-px">
+                {Array.from({ length: Math.max(1, Math.min(8, clipCount ?? 1)) }, (_, index) => (
+                  <span key={index} className="flex-1 rounded-[2px] bg-[var(--beat-graph)]/55" />
+                ))}
+              </div>
+            </div>
+          </button>
+        ) : thumbnailUrl && mediaStatus === 'error' ? (
           <div
             className="grid size-full place-items-center px-4 text-center text-xs text-[var(--beat-text-3)]"
             role="status"
@@ -123,7 +237,7 @@ export function AssetCardNode({
           </div>
         ) : thumbnailUrl && cardMediaType === 'video' ? (
           <>
-            <video
+            <QueuedVideo
               src={thumbnailUrl}
               aria-label={title}
               muted
diff --git a/src/components/beatcanvas/react-flow/beatcanvas-react-flow-types.ts b/src/components/beatcanvas/react-flow/beatcanvas-react-flow-types.ts
index 77782b0..785dce9 100644
--- a/src/components/beatcanvas/react-flow/beatcanvas-react-flow-types.ts
+++ b/src/components/beatcanvas/react-flow/beatcanvas-react-flow-types.ts
@@ -1,4 +1,5 @@
 import type { GenerationTake } from '@/core/beatcanvas/generation-history';
+import type { CanvasAssetMediaType } from '@/core/beatcanvas/canvas-types';
 import type {
   Edge,
   Node,
@@ -20,11 +21,15 @@ export type BeatCanvasNodeMeta = Record<string, unknown>;
 export type AssetCardNodeProps = {
   w: number;
   h: number;
-  cardMediaType: 'image' | 'video';
+  cardMediaType: CanvasAssetMediaType;
   title: string;
   thumbnailUrl: string;
   fitMode: 'cover' | 'contain';
   chromeMode: 'default' | 'frameless';
+  durationSec?: number | null;
+  audioRole?: string;
+  timelineId?: string | null;
+  clipCount?: number | null;
 };
 
 export type GenerationCardNodeProps = {
diff --git a/src/components/beatcanvas/use-beatcanvas-react-flow-adapter.test.ts b/src/components/beatcanvas/use-beatcanvas-react-flow-adapter.test.ts
index 9cc4bc4..39184a4 100644
--- a/src/components/beatcanvas/use-beatcanvas-react-flow-adapter.test.ts
+++ b/src/components/beatcanvas/use-beatcanvas-react-flow-adapter.test.ts
@@ -13,6 +13,21 @@ import {
   resolveDraftShapeSize,
 } from './use-beatcanvas-react-flow-adapter';
 
+test('snapshot restore replaces stale Canvas shapes before rebuilding the document', () => {
+  const source = readFileSync(
+    new URL('./use-beatcanvas-react-flow-adapter.ts', import.meta.url),
+    'utf8'
+  );
+  const restoreStart = source.indexOf('const restoreProjectSnapshot = useCallback');
+  const restoreEnd = source.indexOf('const applyHistoryDocument', restoreStart);
+  const restoreSource = source.slice(restoreStart, restoreEnd);
+
+  assert.match(restoreSource, /editor\.deleteShapes\(currentShapeIds\)/);
+  assert.match(restoreSource, /replaceCanvasCards\(\{\}\)/);
+  assert.match(restoreSource, /syncedDraftShapeSignaturesRef\.current = \{\}/);
+  assert.match(restoreSource, /syncedAssetShapeSignaturesRef\.current = \{\}/);
+});
+
 const makeDraft = (
   type: CanvasDraftCard['type'],
   aspectRatio: CanvasDraftCard['aspectRatio']
diff --git a/src/components/beatcanvas/use-beatcanvas-react-flow-adapter.ts b/src/components/beatcanvas/use-beatcanvas-react-flow-adapter.ts
index e9a2b6a..2e3ebc9 100644
--- a/src/components/beatcanvas/use-beatcanvas-react-flow-adapter.ts
+++ b/src/components/beatcanvas/use-beatcanvas-react-flow-adapter.ts
@@ -13,8 +13,11 @@ import type {
   ProjectSnapshotDocument,
   ProjectSnapshotShapeFrame,
 } from '@/core/projects/project-snapshot';
+import { parseLocalProjectAssetUrl } from '@/core/projects/local-project-asset-url';
 import type {
   CanvasCard,
+  CanvasAssetMediaType,
+  CanvasAssetCard,
   CanvasCardMediaType,
   CanvasDraftCard,
   CanvasOutputCard,
@@ -31,7 +34,10 @@ import {
   resolveReferenceDrivenDraftAspectRatio,
   resolveWorkspaceAspectRatioFromDimensions,
 } from '@/core/beatcanvas/composer';
-import { resolveCanvasBatchOffset } from '@/core/beatcanvas/upload-layout';
+import {
+  resolveCanvasBatchOffset,
+  resolveNonOverlappingPlacement,
+} from '@/core/beatcanvas/upload-layout';
 import {
   type MutableRefObject,
   useCallback,
@@ -119,10 +125,12 @@ const getDraftFrameSize = (
   };
 };
 
-const getAssetFrameSize = (taskType: CanvasCardMediaType): ShapeSize =>
-  taskType === 'video'
-    ? { w: 420, h: VIDEO_FRAME_HEIGHT }
-    : { w: CARD_RESULT_SIZE, h: CARD_RESULT_SIZE };
+const getAssetFrameSize = (taskType: CanvasAssetMediaType): ShapeSize => {
+  if (taskType === 'video') return { w: 420, h: VIDEO_FRAME_HEIGHT };
+  if (taskType === 'audio') return { w: 320, h: 104 };
+  if (taskType === 'timeline') return { w: 360, h: 220 };
+  return { w: CARD_RESULT_SIZE, h: CARD_RESULT_SIZE };
+};
 
 const getDraftShapeSignature = (
   card: CanvasDraftCard,
@@ -687,14 +695,35 @@ export function useBeatCanvasReactFlowAdapter({
       const editor = editorRef.current;
       if (!editor) {
         return {
-          x: 200 + offset.x,
-          y: 180 + offset.y,
+          x: 80 + offset.x,
+          y: 80 + offset.y,
         };
       }
 
       const existingBounds = sourceIds
         .map((id) => editor.getShapePageBounds(id as any))
         .filter(Boolean);
+      const width = size?.w ?? 360;
+      const height = size?.h ?? 260;
+      const occupied = Object.keys(canvasCardsRef.current).flatMap((cardId) => {
+        const bounds = editor.getShapePageBounds(cardId as any) as
+          | { minX: number; minY: number; maxX: number; maxY: number }
+          | undefined;
+        return bounds
+          ? [
+              {
+                x: bounds.minX,
+                y: bounds.minY,
+                w: bounds.maxX - bounds.minX,
+                h: bounds.maxY - bounds.minY,
+              },
+            ]
+          : [];
+      });
+      let next = {
+        x: 80 + offset.x,
+        y: 80 + offset.y,
+      };
 
       if (existingBounds.length > 0) {
         const right = Math.max(
@@ -709,32 +738,29 @@ export function useBeatCanvasReactFlowAdapter({
         const bottom = Math.max(
           ...existingBounds.map((bounds: any) => bounds.maxY)
         );
-        const width = size?.w ?? 360;
-        const height = size?.h ?? 260;
-
-        return {
+        next = {
           x:
             side === 'left'
               ? left - width - 96 - offset.x
               : right + 96 + offset.x,
           y: top + Math.max(0, (bottom - top - height) / 2) + offset.y,
         };
-      }
-
-      if (size && typeof editor.getViewportPageBounds === 'function') {
-        const viewportCenter = editor.getViewportPageBounds().center;
-        return {
-          x: viewportCenter.x - size.w / 2 + offset.x,
-          y: viewportCenter.y - size.h / 2 + offset.y,
+      } else if (occupied.length > 0) {
+        const maxX = Math.max(...occupied.map((frame) => frame.x + frame.w));
+        const minY = Math.min(...occupied.map((frame) => frame.y));
+        next = {
+          x: maxX + 48 + offset.x,
+          y: minY + offset.y,
         };
       }
-
-      return {
-        x: 200 + offset.x,
-        y: 160 + offset.y,
-      };
+      return resolveNonOverlappingPlacement({
+        ...next,
+        w: width,
+        h: height,
+        occupied,
+      });
     },
-    []
+    [canvasCardsRef]
   );
 
   const createConnectorBetweenCards = useCallback(
@@ -830,7 +856,7 @@ export function useBeatCanvasReactFlowAdapter({
 
   const syncAssetShape = useCallback((card: CanvasCard) => {
     const editor = editorRef.current;
-    if (!editor || !card.url) return;
+    if (!editor || card.kind !== 'asset') return;
 
     editor.updateShape({
       id: card.id,
@@ -851,7 +877,11 @@ export function useBeatCanvasReactFlowAdapter({
       },
       props: {
         title: card.name,
-        thumbnailUrl: card.url,
+        thumbnailUrl: card.url ?? '',
+        durationSec: card.durationSec,
+        audioRole: card.audioRole,
+        timelineId: card.timelineId,
+        clipCount: card.clipCount,
       },
     });
   }, []);
@@ -861,7 +891,6 @@ export function useBeatCanvasReactFlowAdapter({
       type,
       url,
       name,
-      kind,
       assetId,
       sourceGenerationId,
       sourceCardIds = [],
@@ -876,12 +905,17 @@ export function useBeatCanvasReactFlowAdapter({
       fitMode = 'cover',
       chromeMode = 'default',
       workflowTemplateId = null,
+      durationSec,
+      audioRole,
+      timelineId,
+      clipCount,
+      lastRenderAssetId,
       recordHistory = true,
     }: {
-      type: CanvasCardMediaType;
-      url: string;
+      type: CanvasAssetMediaType;
+      url?: string | null;
       name: string;
-      kind: CanvasCard['kind'];
+      kind?: 'asset';
       assetId?: string | null;
       sourceGenerationId?: string | null;
       sourceCardIds?: string[];
@@ -892,10 +926,15 @@ export function useBeatCanvasReactFlowAdapter({
       size?: ShapeSize;
       shapeId?: string;
       frame?: ProjectSnapshotShapeFrame;
-      existingCard?: CanvasCard;
+      existingCard?: CanvasAssetCard;
       fitMode?: 'cover' | 'contain';
       chromeMode?: 'default' | 'frameless';
       workflowTemplateId?: string | null;
+      durationSec?: number | null;
+      audioRole?: CanvasCard['audioRole'];
+      timelineId?: string | null;
+      clipCount?: number | null;
+      lastRenderAssetId?: string | null;
       recordHistory?: boolean;
     }) => {
       const editor = editorRef.current;
@@ -929,7 +968,7 @@ export function useBeatCanvasReactFlowAdapter({
         x,
         y,
         meta: {
-          [CARD_KIND_META_KEY]: kind,
+          [CARD_KIND_META_KEY]: 'asset',
           [CARD_TYPE_META_KEY]: type,
           ...(sourceGenerationId
             ? {
@@ -947,9 +986,13 @@ export function useBeatCanvasReactFlowAdapter({
           h: nextSize.h,
           cardMediaType: type,
           title: name,
-          thumbnailUrl: url,
+          thumbnailUrl: url ?? '',
           fitMode,
           chromeMode,
+          durationSec: durationSec ?? existingCard?.durationSec,
+          audioRole: audioRole ?? existingCard?.audioRole,
+          timelineId: timelineId ?? existingCard?.timelineId,
+          clipCount: clipCount ?? existingCard?.clipCount,
         },
       });
 
@@ -963,10 +1006,10 @@ export function useBeatCanvasReactFlowAdapter({
           : {
               id: nextShapeId,
               assetId: assetId ?? null,
-              kind,
+              kind: 'asset',
               type,
               name,
-              url,
+              url: url ?? null,
               prompt: '',
               referenceCardIds: sourceCardIds,
               workflowTemplateId,
@@ -980,6 +1023,11 @@ export function useBeatCanvasReactFlowAdapter({
               variant: 'standard',
               quality: 'standard',
               sourceGenerationId: sourceGenerationId ?? null,
+              durationSec: durationSec ?? null,
+              audioRole,
+              timelineId: timelineId ?? null,
+              clipCount: clipCount ?? null,
+              lastRenderAssetId: lastRenderAssetId ?? null,
             }
       );
 
@@ -1192,6 +1240,8 @@ export function useBeatCanvasReactFlowAdapter({
 
       const completedOutputCard: CanvasOutputCard = {
         ...current,
+        assetId:
+          parseLocalProjectAssetUrl(url)?.assetId ?? current.assetId ?? null,
         name,
         url: url ?? null,
         resultText,
@@ -1399,6 +1449,19 @@ export function useBeatCanvasReactFlowAdapter({
 
   const restoreProjectSnapshot = useCallback(
     (document: ProjectSnapshotDocument) => {
+      const editor = editorRef.current;
+      if (!editor) return;
+
+      const currentShapeIds = editor
+        .getCurrentPageShapes()
+        .map((shape) => shape.id);
+      if (currentShapeIds.length > 0) {
+        editor.deleteShapes(currentShapeIds);
+      }
+      replaceCanvasCards({});
+      syncedDraftShapeSignaturesRef.current = {};
+      syncedAssetShapeSignaturesRef.current = {};
+
       const restorePlan = createProjectSnapshotRestorePlan(document);
       const restoredCardIds: string[] = [];
       const restoredDraftIds: string[] = [];
@@ -1505,6 +1568,7 @@ export function useBeatCanvasReactFlowAdapter({
       editorRef,
       focusShapes,
       insertAssetCard,
+      replaceCanvasCards,
       setActiveComposerCardId,
     ]
   );
diff --git a/src/components/beatcanvas/use-beatcanvas-upload-actions.test.ts b/src/components/beatcanvas/use-beatcanvas-upload-actions.test.ts
index 335275d..14902f1 100644
--- a/src/components/beatcanvas/use-beatcanvas-upload-actions.test.ts
+++ b/src/components/beatcanvas/use-beatcanvas-upload-actions.test.ts
@@ -2,11 +2,28 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 
 import {
+  createUploadMediaMetadata,
   materializePersistedImageUploadsToCanvas,
   shouldPersistCanvasImportLocally,
   type UploadRequest,
 } from './use-beatcanvas-upload-actions';
 
+test('normalizes imported video metadata for both Asset and Canvas', () => {
+  assert.deepEqual(
+    createUploadMediaMetadata({
+      width: 640,
+      height: 360,
+      durationSec: 6.004,
+    }),
+    {
+      width: 640,
+      height: 360,
+      size: { w: 360, h: 200 },
+      durationMs: 6004,
+    }
+  );
+});
+
 test('persists image selections immediately after canvas insertion', () => {
   const imageRequests: UploadRequest[] = [
     { intent: 'image', mode: 'global' },
diff --git a/src/components/beatcanvas/use-beatcanvas-upload-actions.ts b/src/components/beatcanvas/use-beatcanvas-upload-actions.ts
index 2083662..c9970a0 100644
--- a/src/components/beatcanvas/use-beatcanvas-upload-actions.ts
+++ b/src/components/beatcanvas/use-beatcanvas-upload-actions.ts
@@ -46,6 +46,40 @@ type TranslateFn = (
 export type UploadIntent = CanvasCardMediaType;
 export type UploadActivityIntent = UploadIntent | 'media';
 
+export type UploadMediaMetadata = {
+  size?: AssetShapeSize;
+  width?: number;
+  height?: number;
+  durationMs?: number;
+};
+
+export function createUploadMediaMetadata({
+  width,
+  height,
+  durationSec,
+}: {
+  width: number;
+  height: number;
+  durationSec?: number;
+}): UploadMediaMetadata {
+  const validWidth = Number.isFinite(width) && width > 0 ? Math.round(width) : undefined;
+  const validHeight = Number.isFinite(height) && height > 0 ? Math.round(height) : undefined;
+  const validDurationMs =
+    Number.isFinite(durationSec) && (durationSec ?? 0) > 0
+      ? Math.round((durationSec ?? 0) * 1000)
+      : undefined;
+  return {
+    ...(validWidth && validHeight
+      ? {
+          width: validWidth,
+          height: validHeight,
+          size: computeAdaptiveAssetSize(validWidth, validHeight),
+        }
+      : {}),
+    ...(validDurationMs ? { durationMs: validDurationMs } : {}),
+  };
+}
+
 export type UploadRequest =
   | {
       intent: 'media';
@@ -105,6 +139,7 @@ export function materializePersistedImageUploadsToCanvas({
     fitMode?: 'cover' | 'contain';
     chromeMode?: 'default' | 'frameless';
     workflowTemplateId?: string | null;
+    durationSec?: number | null;
   }) => string | null;
 }) {
   const insertedAssetCardIds: string[] = [];
@@ -312,27 +347,32 @@ export function useBeatCanvasUploadActions({
     input.click();
   }, [setErrorMessage, setStatusMessage, studioT]);
 
-  function resolveUploadNaturalSize(
+  function resolveUploadMediaMetadata(
     objectUrl: string,
     intent: UploadIntent
-  ): Promise<AssetShapeSize | undefined> {
+  ): Promise<UploadMediaMetadata> {
     if (intent === 'image') {
       return new Promise((resolve) => {
         const img = new Image();
         img.onload = () =>
-          resolve(
-            computeAdaptiveAssetSize(img.naturalWidth, img.naturalHeight)
-          );
-        img.onerror = () => resolve(undefined);
+          resolve(createUploadMediaMetadata({
+            width: img.naturalWidth,
+            height: img.naturalHeight,
+          }));
+        img.onerror = () => resolve({});
         img.src = objectUrl;
       });
     }
     return new Promise((resolve) => {
       const video = document.createElement('video');
       video.onloadedmetadata = () => {
-        resolve(computeAdaptiveAssetSize(video.videoWidth, video.videoHeight));
+        resolve(createUploadMediaMetadata({
+          width: video.videoWidth,
+          height: video.videoHeight,
+          durationSec: video.duration,
+        }));
       };
-      video.onerror = () => resolve(undefined);
+      video.onerror = () => resolve({});
       video.preload = 'metadata';
       video.src = objectUrl;
     });
@@ -349,13 +389,17 @@ export function useBeatCanvasUploadActions({
         return;
       }
       const files = request.mode === 'global' ? allFiles : allFiles.slice(0, 1);
-      const uploads = files.map((file) => ({
-        file,
-        intent:
+      const uploads = files.map((file) => {
+        const detectedType =
           request.intent === 'media'
             ? detectUploadedMediaType(file)
-            : request.intent,
-      }));
+            : request.intent;
+        return {
+          file,
+          // Audio enters through the dedicated editor track flow for now.
+          intent: detectedType === 'audio' ? null : detectedType,
+        };
+      });
 
       for (const upload of uploads) {
         if (!upload.intent) {
@@ -398,13 +442,19 @@ export function useBeatCanvasUploadActions({
             continue;
           }
           const localObjectUrl = URL.createObjectURL(file);
-          const naturalSize = await resolveUploadNaturalSize(localObjectUrl, intent);
+          const mediaMetadata = await resolveUploadMediaMetadata(localObjectUrl, intent);
           URL.revokeObjectURL(localObjectUrl);
           const persistedAsset = shouldPersistCanvasImportLocally({
             request,
-            hasResolvedFrame: Boolean(naturalSize),
+            hasResolvedFrame: Boolean(mediaMetadata.size),
           })
-            ? await uploadLocalProjectAsset({ projectId, file })
+            ? await uploadLocalProjectAsset({
+                projectId,
+                file,
+                width: mediaMetadata.width,
+                height: mediaMetadata.height,
+                durationMs: mediaMetadata.durationMs,
+              })
             : null;
           if (!persistedAsset) {
             throw new Error('Canvas imports must be saved locally before insertion');
@@ -418,9 +468,12 @@ export function useBeatCanvasUploadActions({
             anchorCardIds:
               request.mode === 'reference' ? [request.draftId] : undefined,
             placementSide: request.mode === 'reference' ? 'left' : 'right',
-            placementOffsetIndex: request.mode === 'global' ? index : 0,
+            placementOffsetIndex: index,
             activateOnInsert: request.mode !== 'reference',
-            ...(naturalSize ? { size: naturalSize } : {}),
+            ...(mediaMetadata.size ? { size: mediaMetadata.size } : {}),
+            ...(mediaMetadata.durationMs
+              ? { durationSec: mediaMetadata.durationMs / 1000 }
+              : {}),
           });
 
           if (!assetCardId) {
diff --git a/src/components/beatcanvas/use-project-snapshot-lifecycle.test.ts b/src/components/beatcanvas/use-project-snapshot-lifecycle.test.ts
index e27f874..a8a320b 100644
--- a/src/components/beatcanvas/use-project-snapshot-lifecycle.test.ts
+++ b/src/components/beatcanvas/use-project-snapshot-lifecycle.test.ts
@@ -1,13 +1,16 @@
 import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
 import test from 'node:test';
 
+import { normalizeProjectSnapshotDocument } from '@/core/projects/project-snapshot';
 import {
   PROJECT_SNAPSHOT_AUTOSAVE_DELAY_MS,
   PROJECT_SNAPSHOT_CHECKPOINT_INTERVAL_MS,
+  PROJECT_SNAPSHOT_EXTERNAL_POLL_INTERVAL_MS,
   buildProjectPathWithoutEntryIntentSearch,
   buildProjectSnapshotRequestHeaders,
+  mergeProjectSnapshotsAfterConflict,
 } from './use-project-snapshot-lifecycle';
-import { readFileSync } from 'node:fs';
 
 test('removes one-time prompt and template query params without dropping other params', () => {
   const path = buildProjectPathWithoutEntryIntentSearch({
@@ -37,6 +40,25 @@ test('snapshot persistence uses a fast debounce plus a five-second dirty checkpo
   assert.match(source, /serializedSnapshot === lastSavedProjectSnapshotRef\.current/);
 });
 
+test('canvas checks for Agent changes within two seconds', () => {
+  assert.equal(PROJECT_SNAPSHOT_EXTERNAL_POLL_INTERVAL_MS, 2_000);
+});
+
+test('canvas external polling rebases pending local edits instead of blocking Agent refreshes', () => {
+  const source = readFileSync(
+    new URL('./use-project-snapshot-lifecycle.ts', import.meta.url),
+    'utf8'
+  );
+  assert.doesNotMatch(
+    source,
+    /if \(pendingProjectSnapshotRef\.current\) \{\s*return;\s*\}/
+  );
+  assert.match(source, /const pendingSnapshot = pendingProjectSnapshotRef\.current/);
+  assert.match(source, /local: pendingSnapshot,/);
+  assert.match(source, /remote: payload\.document,/);
+  assert.match(source, /restoreProjectSnapshot\(snapshotToRestore\)/);
+});
+
 test('snapshot persistence flushes the complete current document when the page exits or becomes hidden', () => {
   const source = readFileSync(
     new URL('./use-project-snapshot-lifecycle.ts', import.meta.url),
@@ -57,13 +79,72 @@ test('snapshot autosave sends explicit authorization before replacing a populate
   assert.match(source, /allowEmpty,/);
 });
 
-test('snapshot autosave preserves the local draft and stops after a version conflict', () => {
+test('snapshot autosave retries a version conflict without permanently stopping sync', () => {
   const source = readFileSync(
     new URL('./use-project-snapshot-lifecycle.ts', import.meta.url),
     'utf8'
   );
-  assert.match(source, /snapshotConflictRef\.current = true/);
+  assert.doesNotMatch(source, /snapshotConflictRef/);
+  assert.match(source, /mergeProjectSnapshotsAfterConflict/);
+  assert.match(source, /response = await sendSaveRequest\(latest\.version\)/);
   assert.match(source, /onProjectSnapshotConflict\?\.\(\)/);
-  assert.equal(source.match(/await sendSaveRequest/g)?.length, 1);
-  assert.doesNotMatch(source, /let response/);
+});
+
+test('snapshot conflict recovery preserves independent local and Agent edits', () => {
+  const base = normalizeProjectSnapshotDocument({
+    version: 3,
+    cards: [
+      {
+        id: 'draft-1',
+        kind: 'generation',
+        type: 'video',
+        name: 'Draft',
+        prompt: 'Base prompt',
+        referenceCardIds: [],
+      },
+    ],
+    frames: { 'draft-1': { x: 0, y: 0, w: 320, h: 180 } },
+    camera: { x: 0, y: 0, z: 1 },
+  });
+  const local = normalizeProjectSnapshotDocument({
+    ...base,
+    cards: base.cards.map((card) => ({
+      ...card,
+      prompt: 'Locally edited prompt',
+    })),
+    frames: { 'draft-1': { x: 240, y: 120, w: 320, h: 180 } },
+    camera: { x: 50, y: -20, z: 0.9 },
+  });
+  const remote = normalizeProjectSnapshotDocument({
+    ...base,
+    cards: [
+      {
+        ...base.cards[0],
+        referenceCardIds: ['asset-agent'],
+      },
+      {
+        id: 'asset-agent',
+        assetId: 'asset-agent',
+        kind: 'asset',
+        type: 'video',
+        name: 'Agent clip',
+        url: '/api/app/projects/project-1/assets/asset-agent',
+        referenceCardIds: [],
+      },
+    ],
+    frames: {
+      ...base.frames,
+      'asset-agent': { x: 400, y: 0, w: 320, h: 180 },
+    },
+  });
+
+  const merged = mergeProjectSnapshotsAfterConflict({ base, local, remote });
+  const draft = merged.cards.find((card) => card.id === 'draft-1');
+
+  assert.equal(draft?.prompt, 'Locally edited prompt');
+  assert.deepEqual(draft?.referenceCardIds, ['asset-agent']);
+  assert.ok(merged.cards.some((card) => card.id === 'asset-agent'));
+  assert.equal(merged.frames['draft-1']?.x, 240);
+  assert.equal(merged.frames['asset-agent']?.x, 400);
+  assert.deepEqual(merged.camera, { x: 50, y: -20, z: 0.9 });
 });
diff --git a/src/components/beatcanvas/use-project-snapshot-lifecycle.ts b/src/components/beatcanvas/use-project-snapshot-lifecycle.ts
index 18b3e13..5798d21 100644
--- a/src/components/beatcanvas/use-project-snapshot-lifecycle.ts
+++ b/src/components/beatcanvas/use-project-snapshot-lifecycle.ts
@@ -1,6 +1,9 @@
 'use client';
 
-import type { ProjectSnapshotDocument } from '@/core/projects/project-snapshot';
+import {
+  normalizeProjectSnapshotDocument,
+  type ProjectSnapshotDocument,
+} from '@/core/projects/project-snapshot';
 import type { CanvasCardMediaType } from '@/core/beatcanvas/canvas-types';
 import {
   WORKSPACE_MUTATION_HEADER,
@@ -15,6 +18,7 @@ type SnapshotSaveFailure = {
 
 export const PROJECT_SNAPSHOT_AUTOSAVE_DELAY_MS = 350;
 export const PROJECT_SNAPSHOT_CHECKPOINT_INTERVAL_MS = 5_000;
+export const PROJECT_SNAPSHOT_EXTERNAL_POLL_INTERVAL_MS = 2_000;
 
 const readSnapshotSaveFailure = async (
   response: Response
@@ -66,6 +70,109 @@ const hasHydratableProjectSnapshot = (
     snapshot && (snapshot.cards.length > 0 || snapshot.workflows?.activeTemplate)
   );
 
+const valuesEqual = (left: unknown, right: unknown) =>
+  JSON.stringify(left) === JSON.stringify(right);
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const mergeThreeWayValue = (
+  base: unknown,
+  local: unknown,
+  remote: unknown,
+  key?: string
+): unknown => {
+  if (valuesEqual(local, base)) return remote;
+  if (valuesEqual(remote, base) || valuesEqual(local, remote)) return local;
+  if (local === undefined) return remote;
+  if (remote === undefined) return local;
+
+  if (
+    key === 'referenceCardIds' &&
+    Array.isArray(local) &&
+    Array.isArray(remote)
+  ) {
+    return Array.from(
+      new Set(
+        [...remote, ...local].filter(
+          (value): value is string => typeof value === 'string'
+        )
+      )
+    );
+  }
+
+  if (isRecord(local) && isRecord(remote)) {
+    const baseRecord = isRecord(base) ? base : {};
+    return Array.from(
+      new Set([
+        ...Object.keys(baseRecord),
+        ...Object.keys(remote),
+        ...Object.keys(local),
+      ])
+    ).reduce<Record<string, unknown>>((merged, childKey) => {
+      const value = mergeThreeWayValue(
+        baseRecord[childKey],
+        local[childKey],
+        remote[childKey],
+        childKey
+      );
+      if (value !== undefined) merged[childKey] = value;
+      return merged;
+    }, {});
+  }
+
+  // Both sides changed the same scalar or ordered list. Keep the local edit;
+  // remote-only fields are still retained by the object merge above.
+  return local;
+};
+
+export const mergeProjectSnapshotsAfterConflict = ({
+  base,
+  local,
+  remote,
+}: {
+  base: ProjectSnapshotDocument | null;
+  local: ProjectSnapshotDocument;
+  remote: ProjectSnapshotDocument;
+}): ProjectSnapshotDocument => {
+  const empty = normalizeProjectSnapshotDocument({ cards: [], frames: {} });
+  const baseDocument = base ?? empty;
+  const baseCards = new Map(baseDocument.cards.map((card) => [card.id, card]));
+  const localCards = new Map(local.cards.map((card) => [card.id, card]));
+  const remoteCards = new Map(remote.cards.map((card) => [card.id, card]));
+  const cardIds = Array.from(
+    new Set([...baseCards.keys(), ...remoteCards.keys(), ...localCards.keys()])
+  ).sort();
+  const cards = cardIds.flatMap((cardId) => {
+    const merged = mergeThreeWayValue(
+      baseCards.get(cardId),
+      localCards.get(cardId),
+      remoteCards.get(cardId)
+    );
+    return isRecord(merged) ? [merged] : [];
+  });
+
+  return normalizeProjectSnapshotDocument({
+    version: 3,
+    cards,
+    frames: mergeThreeWayValue(
+      baseDocument.frames,
+      local.frames,
+      remote.frames
+    ),
+    camera: mergeThreeWayValue(
+      baseDocument.camera,
+      local.camera,
+      remote.camera
+    ),
+    workflows: mergeThreeWayValue(
+      baseDocument.workflows,
+      local.workflows,
+      remote.workflows
+    ),
+  });
+};
+
 export function buildProjectPathWithoutEntryIntentSearch({
   projectPath,
   search,
@@ -125,43 +232,78 @@ export function useProjectSnapshotLifecycle({
     initialProjectSnapshotVersion
   );
   const saveQueueRef = useRef(Promise.resolve());
-  const snapshotConflictRef = useRef(false);
+  const externalPollInFlightRef = useRef(false);
 
   const saveSerializedSnapshot = useCallback(
     async (serializedSnapshot: string, allowEmpty: boolean) => {
       const runSave = async () => {
-        if (snapshotConflictRef.current) return;
-        if (serializedSnapshot === lastSavedProjectSnapshotRef.current) {
-          if (pendingProjectSnapshotRef.current === serializedSnapshot) {
+        const targetSerializedSnapshot =
+          pendingProjectSnapshotRef.current ?? serializedSnapshot;
+        if (targetSerializedSnapshot === lastSavedProjectSnapshotRef.current) {
+          if (
+            pendingProjectSnapshotRef.current === targetSerializedSnapshot
+          ) {
             pendingProjectSnapshotRef.current = null;
           }
           return;
         }
 
-        const snapshotDocument = JSON.parse(
-          serializedSnapshot
+        const localSnapshotDocument = JSON.parse(
+          targetSerializedSnapshot
         ) as ProjectSnapshotDocument;
+        const baseSnapshotDocument = lastSavedProjectSnapshotRef.current
+          ? (JSON.parse(
+              lastSavedProjectSnapshotRef.current
+            ) as ProjectSnapshotDocument)
+          : null;
 
         const sendSaveRequest = (baseVersion: number | null) =>
           fetch(`/api/app/projects/${projectId}/snapshot`, {
             method: 'PUT',
             headers: buildProjectSnapshotRequestHeaders(),
             body: JSON.stringify({
-              document: snapshotDocument,
+              document: snapshotToSave,
               baseVersion,
               allowEmpty,
             }),
           });
 
-        const response = await sendSaveRequest(
+        let snapshotToSave = localSnapshotDocument;
+        let recoveredFromConflict = false;
+        let response = await sendSaveRequest(
           lastSavedProjectSnapshotVersionRef.current
         );
 
         if (response.status === 409) {
-          const failure = await readSnapshotSaveFailure(response);
-          snapshotConflictRef.current = true;
-          onProjectSnapshotConflict?.();
-          throw new Error(failure.message);
+          const firstFailure = await readSnapshotSaveFailure(response);
+          const latestResponse = await fetch(
+            `/api/app/projects/${encodeURIComponent(projectId)}/snapshot`
+          );
+          if (!latestResponse.ok) {
+            onProjectSnapshotConflict?.();
+            throw new Error(firstFailure.message);
+          }
+          const latest = (await latestResponse.json()) as {
+            version?: number;
+            document?: ProjectSnapshotDocument;
+          };
+          if (typeof latest.version !== 'number' || !latest.document) {
+            onProjectSnapshotConflict?.();
+            throw new Error(firstFailure.message);
+          }
+
+          snapshotToSave = mergeProjectSnapshotsAfterConflict({
+            base: baseSnapshotDocument,
+            local: localSnapshotDocument,
+            remote: latest.document,
+          });
+          response = await sendSaveRequest(latest.version);
+          recoveredFromConflict = response.ok;
+          if (response.status === 409) {
+            const retryFailure = await readSnapshotSaveFailure(response);
+            onProjectSnapshotConflict?.();
+            throw new Error(retryFailure.message);
+          }
         }
 
         if (!response.ok) {
@@ -174,11 +316,35 @@ export function useProjectSnapshotLifecycle({
         if (typeof result?.version === 'number') {
           lastSavedProjectSnapshotVersionRef.current = result.version;
         }
-        lastSavedProjectSnapshotRef.current = serializedSnapshot;
-        if (pendingProjectSnapshotRef.current === serializedSnapshot) {
+        const savedSerializedSnapshot = JSON.stringify(snapshotToSave);
+        lastSavedProjectSnapshotRef.current = savedSerializedSnapshot;
+
+        const newestPendingSnapshot = pendingProjectSnapshotRef.current;
+        let restoredRebasedSnapshot = false;
+        if (
+          recoveredFromConflict &&
+          newestPendingSnapshot &&
+          newestPendingSnapshot !== targetSerializedSnapshot
+        ) {
+          const rebasedLocalSnapshot = mergeProjectSnapshotsAfterConflict({
+            base: localSnapshotDocument,
+            local: JSON.parse(newestPendingSnapshot) as ProjectSnapshotDocument,
+            remote: snapshotToSave,
+          });
+          pendingProjectSnapshotRef.current = JSON.stringify(
+            rebasedLocalSnapshot
+          );
+          restoreProjectSnapshot(rebasedLocalSnapshot);
+          restoredRebasedSnapshot = true;
+        } else if (
+          pendingProjectSnapshotRef.current === targetSerializedSnapshot
+        ) {
           pendingProjectSnapshotRef.current = null;
         }
-        if (allowEmpty && snapshotDocument.cards.length === 0) {
+        if (recoveredFromConflict && !restoredRebasedSnapshot) {
+          restoreProjectSnapshot(snapshotToSave);
+        }
+        if (allowEmpty && snapshotToSave.cards.length === 0) {
           onEmptyProjectSnapshotSaved?.();
         }
       };
@@ -187,7 +353,12 @@ export function useProjectSnapshotLifecycle({
       saveQueueRef.current = queuedSave.catch(() => {});
       await queuedSave;
     },
-    [onEmptyProjectSnapshotSaved, onProjectSnapshotConflict, projectId]
+    [
+      onEmptyProjectSnapshotSaved,
+      onProjectSnapshotConflict,
+      projectId,
+      restoreProjectSnapshot,
+    ]
   );
 
   useEffect(() => {
@@ -309,11 +480,83 @@ export function useProjectSnapshotLifecycle({
     saveSerializedSnapshot,
   ]);
 
+  useEffect(() => {
+    if (!isCanvasReady || !isHydratedFromProject) return;
+    const pollExternalSnapshot = async () => {
+      if (externalPollInFlightRef.current) return;
+      externalPollInFlightRef.current = true;
+      try {
+        const response = await fetch(
+          `/api/app/projects/${encodeURIComponent(projectId)}/snapshot`
+        );
+        if (!response.ok) return;
+        const payload = (await response.json()) as {
+          version?: number;
+          document?: ProjectSnapshotDocument;
+        };
+        if (
+          typeof payload.version !== 'number' ||
+          !payload.document ||
+          payload.version <= (lastSavedProjectSnapshotVersionRef.current ?? 0)
+        ) {
+          return;
+        }
+
+        const baseSnapshot = lastSavedProjectSnapshotRef.current
+          ? (JSON.parse(
+              lastSavedProjectSnapshotRef.current
+            ) as ProjectSnapshotDocument)
+          : null;
+        const pendingSnapshot = pendingProjectSnapshotRef.current
+          ? (JSON.parse(
+              pendingProjectSnapshotRef.current
+            ) as ProjectSnapshotDocument)
+          : null;
+        const snapshotToRestore = pendingSnapshot
+          ? mergeProjectSnapshotsAfterConflict({
+              base: baseSnapshot,
+              local: pendingSnapshot,
+              remote: payload.document,
+            })
+          : payload.document;
+
+        lastSavedProjectSnapshotVersionRef.current = payload.version;
+        lastSavedProjectSnapshotRef.current = JSON.stringify(payload.document);
+        pendingProjectSnapshotRef.current = pendingSnapshot
+          ? JSON.stringify(snapshotToRestore)
+          : null;
+        restoreProjectSnapshot(snapshotToRestore);
+      } catch {
+        // External refresh is best-effort; the next poll retries automatically.
+      } finally {
+        externalPollInFlightRef.current = false;
+      }
+    };
+
+    const pollWhenVisible = () => {
+      if (document.visibilityState === 'visible') {
+        void pollExternalSnapshot();
+      }
+    };
+
+    void pollExternalSnapshot();
+    const intervalId = window.setInterval(
+      () => void pollExternalSnapshot(),
+      PROJECT_SNAPSHOT_EXTERNAL_POLL_INTERVAL_MS
+    );
+    window.addEventListener('focus', pollWhenVisible);
+    document.addEventListener('visibilitychange', pollWhenVisible);
+    return () => {
+      window.clearInterval(intervalId);
+      window.removeEventListener('focus', pollWhenVisible);
+      document.removeEventListener('visibilitychange', pollWhenVisible);
+    };
+  }, [isCanvasReady, isHydratedFromProject, projectId, restoreProjectSnapshot]);
+
   useEffect(() => {
     if (!isCanvasReady || !isHydratedFromProject) return;
 
     const flushPendingSnapshot = () => {
-      if (snapshotConflictRef.current) return;
       const serializedSnapshot =
         pendingProjectSnapshotRef.current ??
         JSON.stringify(buildProjectSnapshotDocument());
diff --git a/src/components/editor/video-editor-workspace.test.ts b/src/components/editor/video-editor-workspace.test.ts
new file mode 100644
index 0000000..fb3d00e
--- /dev/null
+++ b/src/components/editor/video-editor-workspace.test.ts
@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createTimelineDocument } from '@/core/editor/timeline-document';
+import {
+  PROJECT_TIMELINE_EXTERNAL_POLL_INTERVAL_MS,
+  shouldPersistTimelineDocument,
+  timelineDocumentsEqualForPersistence,
+} from './video-editor-workspace';
+
+test('does not echo a remotely loaded timeline back through UI autosave', () => {
+  const remote = createTimelineDocument({
+    projectId: 'project-1',
+    name: 'Remote timeline',
+  });
+
+  assert.equal(
+    shouldPersistTimelineDocument({
+      isHydrated: true,
+      document: remote,
+      lastSavedDocument: structuredClone(remote),
+    }),
+    false
+  );
+  assert.equal(
+    shouldPersistTimelineDocument({
+      isHydrated: true,
+      document: { ...remote, name: 'Local edit' },
+      lastSavedDocument: remote,
+    }),
+    true
+  );
+});
+
+test('server-only timestamp normalization does not create an autosave echo', () => {
+  const local = createTimelineDocument({
+    projectId: 'project-1',
+    name: 'Timeline',
+  });
+  const saved = {
+    ...structuredClone(local),
+    updatedAt: new Date(Date.now() + 1_000).toISOString(),
+  };
+
+  assert.equal(timelineDocumentsEqualForPersistence(local, saved), true);
+  assert.equal(
+    shouldPersistTimelineDocument({
+      isHydrated: true,
+      document: local,
+      lastSavedDocument: saved,
+    }),
+    false
+  );
+});
+
+test('editor checks for Agent changes within two seconds', () => {
+  assert.equal(PROJECT_TIMELINE_EXTERNAL_POLL_INTERVAL_MS, 2_000);
+});
+
+test('does not persist the empty bootstrap document before hydration finishes', () => {
+  const remote = createTimelineDocument({
+    projectId: 'project-1',
+    name: 'Remote timeline',
+  });
+  const bootstrap = createTimelineDocument({
+    projectId: 'project-1',
+    name: 'Bootstrap timeline',
+  });
+
+  assert.equal(
+    shouldPersistTimelineDocument({
+      isHydrated: false,
+      document: bootstrap,
+      lastSavedDocument: remote,
+    }),
+    false
+  );
+});
diff --git a/src/components/editor/video-editor-workspace.tsx b/src/components/editor/video-editor-workspace.tsx
new file mode 100644
index 0000000..a2be6eb
--- /dev/null
+++ b/src/components/editor/video-editor-workspace.tsx
@@ -0,0 +1,2281 @@
+'use client';
+
+import {
+  Download,
+  FileVideo2,
+  ImageIcon,
+  Music2,
+  Pause,
+  Play,
+  RotateCcw,
+  Scissors,
+  SlidersHorizontal,
+  Sparkles,
+  Trash2,
+  Upload,
+  Undo2,
+  Redo2,
+  Volume2,
+} from 'lucide-react';
+import {
+  type ChangeEvent,
+  type DragEvent,
+  type PointerEvent as ReactPointerEvent,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import { useTranslations } from '@/core/workspace-lib/shims/next-intl';
+import { uploadLocalProjectAsset } from '@/core/workspace-lib/app/local-project-asset-client';
+import { executeProjectCommand } from '@/core/commands/client';
+import { createCommandId } from '@/core/commands/contracts';
+import {
+  applyEditorOperations,
+  type EditorOperation,
+} from '@/core/commands/editor-commands';
+import {
+  createTimelineDocument,
+  findTimelineClip,
+  getTimelineClipSource,
+  type TimelineClip,
+  type TimelineDocument,
+} from '@/core/editor/timeline-document';
+import { DEFAULT_IMAGE_CLIP_DURATION } from '@/core/editor/timeline-client';
+import {
+  downloadBlob,
+  exportTimelineMp4,
+  exportTrimmedMp4,
+  inspectLocalMedia,
+  type LocalMediaMetadata,
+} from '@/core/editor/media-export';
+import { diagnoseTimeline } from '@/core/editor/timeline-diagnostics';
+import { mergeTimelineDocuments } from '@/core/editor/timeline-merge';
+import {
+  buildTimelineDragPreview,
+  timelineTimeFromClientX,
+  type TimelineClipInteractionPreview,
+  type TimelineDragMode,
+} from '@/core/editor/timeline-interaction';
+import { redoTimelineSelection } from '@/core/editor/beatapi-redo';
+import { fetchRecentAssets } from '@/core/workspace-lib/app/workspace-client-api';
+import { apiJsonGet, apiJsonPost } from '@/lib/api-client';
+import {
+  WORKSPACE_MUTATION_HEADER,
+  WORKSPACE_MUTATION_HEADER_VALUE,
+} from '@/lib/trusted-local-request';
+
+const MIN_CLIP_DURATION = 0.04;
+export const PROJECT_TIMELINE_EXTERNAL_POLL_INTERVAL_MS = 2_000;
+
+type TimelineDragSession = {
+  clip: TimelineClip;
+  mode: TimelineDragMode;
+  originClientX: number;
+  timelineWidth: number;
+  timelineDuration: number;
+  preview: TimelineClipInteractionPreview;
+};
+
+export function shouldPersistTimelineDocument({
+  isHydrated,
+  document,
+  lastSavedDocument,
+}: {
+  isHydrated: boolean;
+  document: TimelineDocument;
+  lastSavedDocument: TimelineDocument | null;
+}) {
+  return (
+    isHydrated &&
+    (!lastSavedDocument ||
+      !timelineDocumentsEqualForPersistence(document, lastSavedDocument))
+  );
+}
+
+export function timelineDocumentsEqualForPersistence(
+  left: TimelineDocument,
+  right: TimelineDocument
+) {
+  const { updatedAt: _leftUpdatedAt, ...leftContent } = left;
+  const { updatedAt: _rightUpdatedAt, ...rightContent } = right;
+  return JSON.stringify(leftContent) === JSON.stringify(rightContent);
+}
+
+const formatTime = (seconds: number) => {
+  const safe = Number.isFinite(seconds) ? Math.max(0, seconds) : 0;
+  const minutes = Math.floor(safe / 60);
+  const remainder = safe - minutes * 60;
+  return `${minutes}:${remainder.toFixed(2).padStart(5, '0')}`;
+};
+
+const safeFilename = (name: string) =>
+  name
+    .replace(/\.[^.]+$/, '')
+    .replace(/[^a-zA-Z0-9\u4e00-\u9fff_-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'beatdesign-clip';
+
+const saveTimelineThroughCommand = async ({
+  projectId,
+  document,
+  expectedRevision,
+  commandId = createCommandId(),
+}: {
+  projectId: string;
+  document: TimelineDocument;
+  expectedRevision: number | null;
+  commandId?: string;
+}) => {
+  const result = await executeProjectCommand({
+    projectId,
+    commandId,
+    idempotencyKey: commandId,
+    expectedRevision,
+    command: { type: 'editor.replace_document', document },
+  });
+  if (!result.ok) {
+    const error = new Error(result.message) as Error & { code?: string };
+    error.code = result.code;
+    throw error;
+  }
+  if (!result.data.timeline || typeof result.revision !== 'number') {
+    throw new Error('Timeline command returned no saved document.');
+  }
+  return { document: result.data.timeline, version: result.revision };
+};
+
+function TimelineClipBlock({
+  clip,
+  totalDuration,
+  selected,
+  onSelect,
+  onPointerAction,
+  trimStartLabel,
+  trimEndLabel,
+}: {
+  clip: TimelineClip;
+  totalDuration: number;
+  selected: boolean;
+  onSelect: () => void;
+  onPointerAction: (
+    mode: TimelineDragMode,
+    event: ReactPointerEvent<HTMLElement>
+  ) => void;
+  trimStartLabel: string;
+  trimEndLabel: string;
+}) {
+  const left = totalDuration > 0 ? (clip.startTime / totalDuration) * 100 : 0;
+  const width = totalDuration > 0 ? (clip.duration / totalDuration) * 100 : 100;
+
+  return (
+    <div
+      className={`group absolute inset-y-1 touch-none overflow-hidden rounded-[9px] border text-left transition ${
+        selected
+          ? 'cursor-grab border-[var(--beat-accent)] bg-[#2a1a12] shadow-[0_0_0_1px_rgba(255,103,0,0.3),0_8px_24px_rgba(0,0,0,0.2)] active:cursor-grabbing'
+          : clip.sourceType === 'audio'
+            ? 'cursor-grab border-[var(--beat-graph)]/30 bg-[var(--beat-graph)]/12 hover:border-[var(--beat-graph)]/50 hover:bg-[var(--beat-graph)]/18 active:cursor-grabbing'
+            : 'cursor-grab border-white/12 bg-[#202124] hover:border-white/24 hover:bg-[#242529] active:cursor-grabbing'
+      }`}
+      style={{ left: `${left}%`, width: `${Math.max(width, 1.2)}%` }}
+      title={
+        clip.sourceType === 'image'
+          ? `${clip.name} · ${clip.duration.toFixed(2)}s`
+          : `${clip.name} · ${formatTime(clip.inPoint)}–${formatTime(clip.outPoint)}`
+      }
+    >
+      <button
+        type="button"
+        onClick={(event) => {
+          event.stopPropagation();
+          onSelect();
+        }}
+        onPointerDown={(event) => onPointerAction('move', event)}
+        className="absolute inset-0 z-10 cursor-grab touch-none overflow-hidden text-left active:cursor-grabbing"
+        aria-label={`${clip.name} ${clip.duration.toFixed(2)}s`}
+      >
+        {clip.sourceType === 'image' ? (
+          <img
+            src={clip.sourceUrl}
+            alt=""
+            className="absolute inset-0 size-full object-cover opacity-48 transition group-hover:opacity-58"
+          />
+        ) : clip.sourceType === 'video' ? (
+          <video
+            src={clip.sourceUrl}
+            muted
+            playsInline
+            preload="metadata"
+            aria-hidden="true"
+            onLoadedMetadata={(event) => {
+              event.currentTarget.currentTime = Math.min(
+                clip.inPoint + 0.05,
+                Math.max(0, clip.outPoint - 0.05)
+              );
+            }}
+            className="absolute inset-0 size-full object-cover opacity-28 transition group-hover:opacity-38"
+          />
+        ) : null}
+        <span className="absolute inset-0 bg-gradient-to-r from-black/72 via-black/38 to-black/10" />
+        <span className="relative flex h-full min-w-0 flex-col justify-between px-2.5 py-2">
+          <span className="block truncate text-[11px] font-[560] tracking-[-0.01em] text-white/95">
+            {clip.name}
+          </span>
+          <span className="flex items-center gap-1.5 text-[10px] font-[500] tabular-nums text-white/62">
+            {clip.sourceType === 'image' ? (
+              <ImageIcon className="size-3" />
+            ) : clip.sourceType === 'video' ? (
+              <FileVideo2 className="size-3" />
+            ) : (
+              <Volume2 className="size-3" />
+            )}
+            {clip.duration.toFixed(2)}s
+          </span>
+        </span>
+      </button>
+      <button
+        type="button"
+        aria-label={trimStartLabel}
+        title={trimStartLabel}
+        onClick={(event) => event.stopPropagation()}
+        onPointerDown={(event) => {
+          event.stopPropagation();
+          onPointerAction('trim-start', event);
+        }}
+        className={`absolute inset-y-0 left-0 z-30 w-2.5 cursor-ew-resize touch-none transition ${
+          selected
+            ? 'bg-gradient-to-r from-[var(--beat-accent)]/80 to-transparent opacity-100'
+            : 'opacity-0 group-hover:opacity-70'
+        }`}
+      >
+        <span className="absolute bottom-2 left-1 top-2 w-px rounded-full bg-white/80" />
+      </button>
+      <button
+        type="button"
+        aria-label={trimEndLabel}
+        title={trimEndLabel}
+        onClick={(event) => event.stopPropagation()}
+        onPointerDown={(event) => {
+          event.stopPropagation();
+          onPointerAction('trim-end', event);
+        }}
+        className={`absolute inset-y-0 right-0 z-30 w-2.5 cursor-ew-resize touch-none transition ${
+          selected
+            ? 'bg-gradient-to-l from-[var(--beat-accent)]/80 to-transparent opacity-100'
+            : 'opacity-0 group-hover:opacity-70'
+        }`}
+      >
+        <span className="absolute bottom-2 right-1 top-2 w-px rounded-full bg-white/80" />
+      </button>
+    </div>
+  );
+}
+
+export function VideoEditorWorkspace({
+  projectId,
+  projectName,
+}: {
+  projectId: string;
+  projectName: string;
+}) {
+  const t = useTranslations('AppShell.editor');
+  const loadFailedMessage = t('errors.loadFailed');
+  const saveFailedMessage = t('errors.saveFailed');
+  const videoRef = useRef<HTMLVideoElement>(null);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const audioInputRef = useRef<HTMLInputElement>(null);
+  const sourceFileRef = useRef<File | null>(null);
+  const audioElementsRef = useRef(new Map<string, HTMLAudioElement>());
+  const imagePlaybackFrameRef = useRef<number | null>(null);
+  const timelineDragRef = useRef<TimelineDragSession | null>(null);
+  const timelineLoadedRef = useRef(false);
+  const timelineVersionRef = useRef<number | null>(null);
+  const lastSavedDocumentRef = useRef<TimelineDocument | null>(null);
+  const saveQueueRef = useRef(Promise.resolve());
+  const externalPollInFlightRef = useRef(false);
+  const exportControllerRef = useRef<AbortController | null>(null);
+  const documentRef = useRef<TimelineDocument | null>(null);
+  const pastDocumentsRef = useRef<TimelineDocument[]>([]);
+  const futureDocumentsRef = useRef<TimelineDocument[]>([]);
+  const [document, setDocument] = useState(() =>
+    createTimelineDocument({ projectId, name: projectName })
+  );
+  const [isTimelineHydrated, setIsTimelineHydrated] = useState(false);
+  const [sourceUrl, setSourceUrl] = useState<string | null>(null);
+  const [metadata, setMetadata] = useState<LocalMediaMetadata | null>(null);
+  const [selectedClipId, setSelectedClipId] = useState<string | null>(null);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [timelineCursorTime, setTimelineCursorTime] = useState(0);
+  const [timelineDragPreview, setTimelineDragPreview] =
+    useState<TimelineClipInteractionPreview | null>(null);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [exactControlsOpen, setExactControlsOpen] = useState(false);
+  const [isInspecting, setIsInspecting] = useState(false);
+  const [isExporting, setIsExporting] = useState(false);
+  const [exportProgress, setExportProgress] = useState(0);
+  const [saveStatus, setSaveStatus] = useState<'idle' | 'saving' | 'saved'>('idle');
+  const [redoOpen, setRedoOpen] = useState(false);
+  const [redoPrompt, setRedoPrompt] = useState('');
+  const [redoStatus, setRedoStatus] = useState('');
+  const [isRedoing, setIsRedoing] = useState(false);
+  const [historyRevision, setHistoryRevision] = useState(0);
+  const [error, setError] = useState<string | null>(null);
+
+  const clips = useMemo(
+    () => document.tracks.flatMap((track) => track.clips),
+    [document.tracks]
+  );
+  const selectedClip = selectedClipId
+    ? findTimelineClip(document, selectedClipId)
+    : undefined;
+  const displayedSelectedClip =
+    selectedClip && timelineDragPreview?.id === selectedClip.id
+      ? { ...selectedClip, ...timelineDragPreview }
+      : selectedClip;
+  const selectedSource = selectedClip
+    ? getTimelineClipSource(selectedClip)
+    : null;
+  const timelineCurrentTime = Math.max(
+    0,
+    Math.min(timelineCursorTime, document.duration)
+  );
+  const timelineDisplayDuration = Math.max(
+    document.duration,
+    timelineDragPreview
+      ? timelineDragPreview.startTime + timelineDragPreview.duration
+      : 0,
+    0.001
+  );
+  const primaryVisualClip = clips.find((clip) => clip.sourceType !== 'audio');
+  const canUndo = historyRevision >= 0 && pastDocumentsRef.current.length > 0;
+  const canRedo = historyRevision >= 0 && futureDocumentsRef.current.length > 0;
+  documentRef.current = document;
+
+  const commitDocument = (
+    updater: typeof document | ((current: typeof document) => typeof document)
+  ) => {
+    setDocument((current) => {
+      const next = typeof updater === 'function' ? updater(current) : updater;
+      if (next === current || JSON.stringify(next) === JSON.stringify(current)) {
+        return current;
+      }
+      pastDocumentsRef.current.push(current);
+      if (pastDocumentsRef.current.length > 100) pastDocumentsRef.current.shift();
+      futureDocumentsRef.current = [];
+      setHistoryRevision((value) => value + 1);
+      return next;
+    });
+  };
+
+  const resetDocument = (next: typeof document) => {
+    pastDocumentsRef.current = [];
+    futureDocumentsRef.current = [];
+    setHistoryRevision((value) => value + 1);
+    setDocument(next);
+  };
+
+  const undoTimeline = () => {
+    const previous = pastDocumentsRef.current.pop();
+    if (!previous) return;
+    futureDocumentsRef.current.push(document);
+    setDocument(previous);
+    setHistoryRevision((value) => value + 1);
+  };
+
+  const redoTimeline = () => {
+    const next = futureDocumentsRef.current.pop();
+    if (!next) return;
+    pastDocumentsRef.current.push(document);
+    setDocument(next);
+    setHistoryRevision((value) => value + 1);
+  };
+
+  useEffect(() => {
+    let active = true;
+    timelineLoadedRef.current = false;
+    setIsTimelineHydrated(false);
+    void apiJsonGet<{
+      timeline: { document: typeof document; version: number } | null;
+    }>(`/api/app/projects/${encodeURIComponent(projectId)}/timeline`)
+      .then((payload) => {
+        if (!active) return;
+        if (!payload.timeline) {
+          const emptyDocument = createTimelineDocument({
+            projectId,
+            name: projectName,
+          });
+          timelineVersionRef.current = null;
+          lastSavedDocumentRef.current = null;
+          documentRef.current = emptyDocument;
+          resetDocument(emptyDocument);
+          setSelectedClipId(null);
+          setSourceUrl(null);
+          setMetadata(null);
+          setCurrentTime(0);
+          setTimelineCursorTime(0);
+          timelineLoadedRef.current = true;
+          setIsTimelineHydrated(true);
+          return;
+        }
+        timelineVersionRef.current = payload.timeline.version;
+        const nextDocument = payload.timeline.document;
+        lastSavedDocumentRef.current = nextDocument;
+        documentRef.current = nextDocument;
+        const visualClips = nextDocument.tracks
+          .flatMap((track) => track.clips)
+          .filter((clip) => clip.sourceType !== 'audio');
+        const requestedTimelineTime = Number(
+          new URLSearchParams(window.location.search).get('t')
+        );
+        const requestedVisual = Number.isFinite(requestedTimelineTime)
+          ? visualClips.find(
+              (clip) =>
+                requestedTimelineTime >= clip.startTime &&
+                requestedTimelineTime < clip.startTime + clip.duration
+            )
+          : undefined;
+        const firstVisual = requestedVisual ?? visualClips[0];
+        resetDocument(nextDocument);
+        setSelectedClipId(firstVisual?.id ?? null);
+        const firstSource = firstVisual ? getTimelineClipSource(firstVisual) : null;
+        const initialTimelineTime = firstVisual
+          ? Number.isFinite(requestedTimelineTime)
+            ? Math.max(
+                firstVisual.startTime,
+                Math.min(
+                  firstVisual.startTime + firstVisual.duration,
+                  requestedTimelineTime
+                )
+              )
+            : firstVisual.startTime
+          : 0;
+        setSourceUrl(firstSource?.sourceUrl ?? null);
+        setTimelineCursorTime(initialTimelineTime);
+        setCurrentTime(
+          firstVisual &&
+            firstVisual.sourceType === 'video' &&
+            firstSource &&
+            Number.isFinite(requestedTimelineTime)
+            ? firstSource.inPoint +
+                Math.max(
+                  0,
+                  Math.min(
+                    firstVisual.duration,
+                    requestedTimelineTime - firstVisual.startTime
+                  )
+                )
+            : (firstSource?.inPoint ?? 0)
+        );
+        setMetadata(
+          firstVisual?.sourceType === 'video'
+            ? {
+                duration: firstVisual.sourceDuration,
+                width: null,
+                height: null,
+                hasVideo: true,
+                hasAudio: false,
+                videoCodec: null,
+                audioCodec: null,
+              }
+            : null
+        );
+        timelineLoadedRef.current = true;
+        setIsTimelineHydrated(true);
+      })
+      .catch((cause) => {
+        if (active) {
+          setError(cause instanceof Error ? cause.message : loadFailedMessage);
+        }
+      });
+    return () => {
+      active = false;
+    };
+  }, [loadFailedMessage, projectId, projectName]);
+
+  useEffect(() => {
+    if (
+      !shouldPersistTimelineDocument({
+        isHydrated: isTimelineHydrated,
+        document,
+        lastSavedDocument: lastSavedDocumentRef.current,
+      })
+    ) {
+      setSaveStatus('saved');
+      return;
+    }
+    setSaveStatus('saving');
+    const timer = window.setTimeout(() => {
+      const saveCandidate = async () => {
+        try {
+          const saved = await saveTimelineThroughCommand({
+            projectId,
+            document,
+            expectedRevision: timelineVersionRef.current,
+          });
+          timelineVersionRef.current = saved.version;
+          lastSavedDocumentRef.current = saved.document;
+          if (documentRef.current === document) {
+            documentRef.current = saved.document;
+            setDocument(saved.document);
+          }
+          setSaveStatus('saved');
+        } catch (cause) {
+          if (
+            cause instanceof Error &&
+            (cause as Error & { code?: string }).code === 'REVISION_CONFLICT'
+          ) {
+            const latest = await apiJsonGet<{
+              timeline: { document: TimelineDocument; version: number } | null;
+            }>(`/api/app/projects/${encodeURIComponent(projectId)}/timeline`);
+            const base = lastSavedDocumentRef.current;
+            if (base && latest.timeline) {
+              const merged = mergeTimelineDocuments({
+                base,
+                local: document,
+                remote: latest.timeline.document,
+              });
+              if (merged.conflicts.length === 0) {
+                const saved = await saveTimelineThroughCommand({
+                  projectId,
+                  document: merged.document,
+                  expectedRevision: latest.timeline.version,
+                });
+                timelineVersionRef.current = saved.version;
+                lastSavedDocumentRef.current = saved.document;
+                if (
+                  documentRef.current &&
+                  timelineDocumentsEqualForPersistence(
+                    documentRef.current,
+                    document
+                  )
+                ) {
+                  documentRef.current = saved.document;
+                  setDocument(saved.document);
+                }
+                setSaveStatus('saved');
+                return;
+              }
+              timelineVersionRef.current = latest.timeline.version;
+              lastSavedDocumentRef.current = latest.timeline.document;
+              throw new Error(
+                `Timeline edit conflict at ${merged.conflicts[0].path}. Your local edit is still open.`
+              );
+            }
+          }
+          setSaveStatus('idle');
+          setError(cause instanceof Error ? cause.message : saveFailedMessage);
+        }
+      };
+      const queued = saveQueueRef.current.then(saveCandidate, saveCandidate);
+      saveQueueRef.current = queued.catch(() => undefined);
+    }, 700);
+    return () => window.clearTimeout(timer);
+  }, [clips.length, document, isTimelineHydrated, projectId, saveFailedMessage]);
+
+  useEffect(() => {
+    if (!isTimelineHydrated) return;
+    const pollExternalTimeline = async () => {
+      if (saveStatus === 'saving') return;
+      const current = documentRef.current;
+      const saved = lastSavedDocumentRef.current;
+      if (
+        current &&
+        saved &&
+        !timelineDocumentsEqualForPersistence(current, saved)
+      ) {
+        return;
+      }
+      if (externalPollInFlightRef.current) return;
+      externalPollInFlightRef.current = true;
+      try {
+        const payload = await apiJsonGet<{
+          timeline: { document: TimelineDocument; version: number } | null;
+        }>(`/api/app/projects/${encodeURIComponent(projectId)}/timeline`);
+        const remote = payload.timeline;
+        if (!remote) return;
+        const localVersion = timelineVersionRef.current;
+        if (
+          typeof localVersion === 'number' &&
+          remote.version <= localVersion
+        ) {
+          return;
+        }
+        timelineVersionRef.current = remote.version;
+        lastSavedDocumentRef.current = remote.document;
+        documentRef.current = remote.document;
+        resetDocument(remote.document);
+
+        const remoteVisualClips = remote.document.tracks
+          .flatMap((track) => track.clips)
+          .filter((clip) => clip.sourceType !== 'audio');
+        const nextSelectedClip =
+          (selectedClipId
+            ? remoteVisualClips.find((clip) => clip.id === selectedClipId)
+            : undefined) ?? remoteVisualClips[0];
+        const nextSource = nextSelectedClip
+          ? getTimelineClipSource(nextSelectedClip)
+          : null;
+        setSelectedClipId(nextSelectedClip?.id ?? null);
+        setSourceUrl(nextSource?.sourceUrl ?? null);
+        setTimelineCursorTime((time) =>
+          Math.max(0, Math.min(time, remote.document.duration))
+        );
+        setCurrentTime((time) =>
+          nextSelectedClip
+            ? Math.max(
+                nextSource?.inPoint ?? 0,
+                Math.min(time, nextSource?.outPoint ?? nextSelectedClip.duration)
+              )
+            : 0
+        );
+        setMetadata(
+          nextSelectedClip?.sourceType === 'video'
+            ? {
+                duration: nextSelectedClip.sourceDuration,
+                width: null,
+                height: null,
+                hasVideo: true,
+                hasAudio: false,
+                videoCodec: null,
+                audioCodec: null,
+              }
+            : null
+        );
+      } catch {
+        // External refresh is best-effort; the next poll retries automatically.
+      } finally {
+        externalPollInFlightRef.current = false;
+      }
+    };
+
+    const pollWhenVisible = () => {
+      if (globalThis.document.visibilityState === 'visible') {
+        void pollExternalTimeline();
+      }
+    };
+
+    void pollExternalTimeline();
+    const timer = window.setInterval(
+      () => void pollExternalTimeline(),
+      PROJECT_TIMELINE_EXTERNAL_POLL_INTERVAL_MS
+    );
+    window.addEventListener('focus', pollWhenVisible);
+    globalThis.document.addEventListener('visibilitychange', pollWhenVisible);
+    return () => {
+      window.clearInterval(timer);
+      window.removeEventListener('focus', pollWhenVisible);
+      globalThis.document.removeEventListener(
+        'visibilitychange',
+        pollWhenVisible
+      );
+    };
+  }, [isTimelineHydrated, projectId, saveStatus, selectedClipId]);
+
+  useEffect(() => {
+    const flushTimeline = () => {
+      const current = documentRef.current;
+      if (!timelineLoadedRef.current || !current) {
+        return;
+      }
+      const commandId = createCommandId();
+      void fetch(
+        `/api/app/projects/${encodeURIComponent(projectId)}/commands`,
+        {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            [WORKSPACE_MUTATION_HEADER]: WORKSPACE_MUTATION_HEADER_VALUE,
+          },
+          body: JSON.stringify({
+            commandId,
+            idempotencyKey: commandId,
+            expectedRevision: timelineVersionRef.current,
+            command: { type: 'editor.replace_document', document: current },
+          }),
+          keepalive: true,
+        }
+      ).catch(() => undefined);
+    };
+    const onVisibilityChange = () => {
+      if (globalThis.document.visibilityState === 'hidden') flushTimeline();
+    };
+    window.addEventListener('pagehide', flushTimeline);
+    globalThis.document.addEventListener('visibilitychange', onVisibilityChange);
+    return () => {
+      window.removeEventListener('pagehide', flushTimeline);
+      globalThis.document.removeEventListener(
+        'visibilitychange',
+        onVisibilityChange
+      );
+    };
+  }, [projectId]);
+
+  useEffect(
+    () => () => {
+      if (sourceUrl?.startsWith('blob:')) URL.revokeObjectURL(sourceUrl);
+    },
+    [sourceUrl]
+  );
+
+  useEffect(
+    () => () => {
+      if (imagePlaybackFrameRef.current !== null) {
+        cancelAnimationFrame(imagePlaybackFrameRef.current);
+      }
+    },
+    []
+  );
+
+  useEffect(() => {
+    if (!selectedClip || selectedClip.sourceType === 'audio') return;
+    const nextSource = getTimelineClipSource(selectedClip);
+    if (sourceUrl !== nextSource.sourceUrl) {
+      sourceFileRef.current = null;
+      setSourceUrl(nextSource.sourceUrl);
+      setCurrentTime(
+        selectedClip.sourceType === 'video' ? nextSource.inPoint : 0
+      );
+      setTimelineCursorTime(selectedClip.startTime);
+    }
+  }, [selectedClip?.activeTakeId, selectedClip?.id, selectedClip?.sourceUrl, sourceUrl]);
+
+  const stopImagePlayback = () => {
+    if (imagePlaybackFrameRef.current !== null) {
+      cancelAnimationFrame(imagePlaybackFrameRef.current);
+      imagePlaybackFrameRef.current = null;
+    }
+    setIsPlaying(false);
+  };
+
+  const seek = (time: number, timelineTime?: number) => {
+    const video = videoRef.current;
+    if (video) video.currentTime = time;
+    setCurrentTime(time);
+    setTimelineCursorTime(
+      timelineTime ??
+        (selectedClip && selectedSource
+          ? selectedClip.startTime + (time - selectedSource.inPoint)
+          : time)
+    );
+  };
+
+  const syncAudioTracks = (sourceTime: number, shouldPlay: boolean) => {
+    if (!selectedClip || !selectedSource) return;
+    const timelineTime =
+      selectedClip.startTime + (sourceTime - selectedSource.inPoint);
+    for (const clip of clips.filter((item) => item.sourceType === 'audio')) {
+      const audio = audioElementsRef.current.get(clip.id);
+      if (!audio) continue;
+      const offset = timelineTime - clip.startTime;
+      const active = offset >= 0 && offset < clip.duration && !clip.muted;
+      if (!active) {
+        audio.pause();
+        continue;
+      }
+      const target = clip.inPoint + offset;
+      if (Math.abs(audio.currentTime - target) > 0.12) audio.currentTime = target;
+      const fadeInGain = clip.fadeIn > 0 ? Math.min(1, offset / clip.fadeIn) : 1;
+      const fadeOutGain =
+        clip.fadeOut > 0
+          ? Math.min(1, (clip.duration - offset) / clip.fadeOut)
+          : 1;
+      audio.volume = Math.max(
+        0,
+        Math.min(1, clip.volume * Math.min(fadeInGain, fadeOutGain))
+      );
+      if (shouldPlay && audio.paused) void audio.play().catch(() => undefined);
+    }
+  };
+
+  const selectClip = (clip: TimelineClip, timelineTime = clip.startTime) => {
+    stopImagePlayback();
+    setSelectedClipId(clip.id);
+    if (clip.sourceType !== 'audio') {
+      const source = getTimelineClipSource(clip);
+      const offset = Math.max(
+        0,
+        Math.min(clip.duration, timelineTime - clip.startTime)
+      );
+      setSourceUrl(source.sourceUrl);
+      sourceFileRef.current = null;
+      setTimelineCursorTime(clip.startTime + offset);
+      if (clip.sourceType === 'video') {
+        const sourceTime = source.inPoint + offset;
+        if (videoRef.current) videoRef.current.currentTime = sourceTime;
+        setCurrentTime(sourceTime);
+      } else {
+        videoRef.current?.pause();
+        setCurrentTime(offset);
+        setMetadata(null);
+      }
+    } else {
+      videoRef.current?.pause();
+      setTimelineCursorTime(clip.startTime);
+    }
+  };
+
+  const seekTimeline = (requestedTime: number) => {
+    const timelineTime = Math.max(
+      0,
+      Math.min(document.duration, requestedTime)
+    );
+    const visualClips = clips
+      .filter((clip) => clip.sourceType !== 'audio')
+      .sort((a, b) => a.startTime - b.startTime);
+    const activeClip =
+      visualClips.find(
+        (clip) =>
+          timelineTime >= clip.startTime &&
+          timelineTime < clip.startTime + clip.duration
+      ) ??
+      [...visualClips]
+        .reverse()
+        .find(
+          (clip) =>
+            timelineTime === document.duration &&
+            Math.abs(clip.startTime + clip.duration - timelineTime) < 0.001
+        );
+
+    if (!activeClip) {
+      videoRef.current?.pause();
+      stopImagePlayback();
+      setTimelineCursorTime(timelineTime);
+      return;
+    }
+    if (activeClip.id !== selectedClipId) {
+      selectClip(activeClip, timelineTime);
+      return;
+    }
+    const offset = Math.max(
+      0,
+      Math.min(activeClip.duration, timelineTime - activeClip.startTime)
+    );
+    setTimelineCursorTime(activeClip.startTime + offset);
+    if (activeClip.sourceType === 'video') {
+      seek(activeClip.inPoint + offset, activeClip.startTime + offset);
+    } else {
+      setCurrentTime(offset);
+    }
+  };
+
+  const loadFile = async (file: File) => {
+    const isImage = file.type.startsWith('image/');
+    const isVideo = file.type.startsWith('video/');
+    if (!isImage && !isVideo) {
+      setError(t('errors.visualOnly'));
+      return;
+    }
+
+    setError(null);
+    setIsInspecting(true);
+    try {
+      const nextMetadata = isVideo ? await inspectLocalMedia(file) : null;
+      if (isVideo && (!nextMetadata?.hasVideo || nextMetadata.duration <= 0)) {
+        throw new Error(t('errors.noVideoTrack'));
+      }
+      const imageBitmap = isImage ? await createImageBitmap(file) : null;
+
+      const persistedAsset = await uploadLocalProjectAsset({
+        projectId,
+        file,
+        width: imageBitmap?.width ?? nextMetadata?.width ?? undefined,
+        height: imageBitmap?.height ?? nextMetadata?.height ?? undefined,
+        durationMs: nextMetadata ? nextMetadata.duration * 1000 : undefined,
+      });
+      imageBitmap?.close();
+      const nextDocument = applyEditorOperations(document, [
+        {
+          type: 'add_clip',
+          assetId: persistedAsset.id,
+          sourceUrl: persistedAsset.publicUrl,
+          name: file.name,
+          sourceType: isImage ? 'image' : 'video',
+          sourceDuration: nextMetadata?.duration ?? DEFAULT_IMAGE_CLIP_DURATION,
+        },
+      ]).document;
+      const nextClip = nextDocument.tracks
+        .flatMap((track) => track.clips)
+        .find((clip) => clip.assetId === persistedAsset.id);
+
+      if (sourceUrl?.startsWith('blob:')) URL.revokeObjectURL(sourceUrl);
+      sourceFileRef.current = isVideo ? file : null;
+      setSourceUrl(persistedAsset.publicUrl);
+      setMetadata(nextMetadata);
+      commitDocument(nextDocument);
+      setSelectedClipId(nextClip?.id ?? null);
+      setCurrentTime(0);
+      setTimelineCursorTime(nextClip?.startTime ?? 0);
+      setIsPlaying(false);
+      setExportProgress(0);
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : t('errors.inspectFailed'));
+    } finally {
+      setIsInspecting(false);
+    }
+  };
+
+  const handleFileInput = (event: ChangeEvent<HTMLInputElement>) => {
+    const [file] = Array.from(event.target.files ?? []);
+    if (file) void loadFile(file);
+    event.target.value = '';
+  };
+
+  const loadAudioFile = async (file: File) => {
+    if (
+      !file.type.startsWith('audio/') &&
+      !/\.(mp3|wav|m4a|aac|ogg)$/i.test(file.name)
+    ) {
+      setError(t('errors.audioOnly'));
+      return;
+    }
+    setError(null);
+    setIsInspecting(true);
+    try {
+      const audioMetadata = await inspectLocalMedia(file);
+      if (!audioMetadata.hasAudio || audioMetadata.duration <= 0) {
+        throw new Error(t('errors.noAudioTrack'));
+      }
+      const persistedAsset = await uploadLocalProjectAsset({
+        projectId,
+        file,
+        durationMs: audioMetadata.duration * 1000,
+      });
+      const nextDocument = applyEditorOperations(document, [
+        {
+          type: 'add_clip',
+          assetId: persistedAsset.id,
+          sourceUrl: persistedAsset.publicUrl,
+          name: file.name,
+          sourceType: 'audio',
+          sourceDuration: audioMetadata.duration,
+          startTime: 0,
+          audioRole: 'music',
+        },
+      ]).document;
+      const nextClip = nextDocument.tracks
+        .flatMap((track) => track.clips)
+        .find((clip) => clip.assetId === persistedAsset.id);
+      commitDocument(nextDocument);
+      setSelectedClipId(nextClip?.id ?? selectedClipId);
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : t('errors.inspectFailed'));
+    } finally {
+      setIsInspecting(false);
+    }
+  };
+
+  const handleAudioInput = (event: ChangeEvent<HTMLInputElement>) => {
+    const [file] = Array.from(event.target.files ?? []);
+    if (file) void loadAudioFile(file);
+    event.target.value = '';
+  };
+
+  const handleDrop = (event: DragEvent<HTMLDivElement>) => {
+    event.preventDefault();
+    const [file] = Array.from(event.dataTransfer.files);
+    if (!file) return;
+    if (
+      file.type.startsWith('audio/') ||
+      /\.(mp3|wav|m4a|aac|ogg)$/i.test(file.name)
+    ) {
+      void loadAudioFile(file);
+      return;
+    }
+    void loadFile(file);
+  };
+
+  const togglePlayback = async () => {
+    if (!selectedClip || !selectedSource || selectedClip.sourceType === 'audio') {
+      return;
+    }
+    if (selectedClip.sourceType === 'image') {
+      if (isPlaying) {
+        stopImagePlayback();
+        syncAudioTracks(currentTime, false);
+        return;
+      }
+      const initialOffset =
+        currentTime >= selectedClip.duration - MIN_CLIP_DURATION
+          ? 0
+          : Math.max(0, currentTime);
+      const startedAt = performance.now() - initialOffset * 1000;
+      setIsPlaying(true);
+      const tick = (now: number) => {
+        const offset = Math.min(
+          selectedClip.duration,
+          Math.max(0, (now - startedAt) / 1000)
+        );
+        setCurrentTime(offset);
+        setTimelineCursorTime(selectedClip.startTime + offset);
+        syncAudioTracks(offset, true);
+        if (offset >= selectedClip.duration) {
+          imagePlaybackFrameRef.current = null;
+          setIsPlaying(false);
+          syncAudioTracks(offset, false);
+          return;
+        }
+        imagePlaybackFrameRef.current = requestAnimationFrame(tick);
+      };
+      imagePlaybackFrameRef.current = requestAnimationFrame(tick);
+      return;
+    }
+
+    const video = videoRef.current;
+    if (!video) return;
+    if (!video.paused) {
+      video.pause();
+      return;
+    }
+    if (
+      video.currentTime < selectedSource.inPoint ||
+      video.currentTime >= selectedSource.outPoint
+    ) {
+      seek(selectedSource.inPoint);
+    }
+    await video.play();
+  };
+
+  const updateTrim = (edge: 'in' | 'out', value: number) => {
+    if (!selectedClip || selectedClip.activeTakeId) return;
+    const nextIn =
+      edge === 'in'
+        ? Math.min(value, selectedClip.outPoint - MIN_CLIP_DURATION)
+        : selectedClip.inPoint;
+    const nextOut =
+      edge === 'out'
+        ? Math.max(value, selectedClip.inPoint + MIN_CLIP_DURATION)
+        : selectedClip.outPoint;
+    commitDocument((current) =>
+      applyEditorOperations(current, [
+        {
+          type: 'trim_clip',
+          clipId: selectedClip.id,
+          inPoint: nextIn,
+          outPoint: nextOut,
+        },
+      ]).document
+    );
+    if (selectedClip.sourceType === 'video') {
+      seek(edge === 'in' ? nextIn : nextOut);
+    }
+  };
+
+  const resizeSelectedImage = (duration: number) => {
+    if (!selectedClip || selectedClip.sourceType !== 'image') return;
+    commitDocument((current) =>
+      applyEditorOperations(current, [
+        {
+          type: 'set_clip_duration',
+          clipId: selectedClip.id,
+          duration: Math.max(MIN_CLIP_DURATION, duration),
+        },
+      ]).document
+    );
+  };
+
+  const splitAtPlayhead = () => {
+    if (!selectedClip || selectedClip.activeTakeId) return;
+    const nextDocument = applyEditorOperations(document, [
+      {
+        type: 'split_clip',
+        clipId: selectedClip.id,
+        sourceTime: currentTime,
+      },
+    ]).document;
+    if (nextDocument === document) return;
+    commitDocument(nextDocument);
+    const rightClip = nextDocument.tracks
+      .flatMap((track) => track.clips)
+      .find(
+        (clip) =>
+          clip.assetId === selectedClip.assetId &&
+          Math.abs(clip.inPoint - currentTime) < 0.001
+      );
+    setSelectedClipId(rightClip?.id ?? selectedClip.id);
+  };
+
+  const moveSelectedClip = (startTime: number) => {
+    if (!selectedClip) return;
+    let next: TimelineDocument;
+    try {
+      next = applyEditorOperations(document, [
+        { type: 'move_clip', clipId: selectedClip.id, startTime },
+      ]).document;
+    } catch {
+      setError(t('errors.clipOverlap'));
+      return;
+    }
+    commitDocument(next);
+  };
+
+  const beginTimelineDrag = (
+    clip: TimelineClip,
+    mode: TimelineDragMode,
+    event: ReactPointerEvent<HTMLElement>
+  ) => {
+    if (mode !== 'move' && clip.activeTakeId) return;
+    const timelineTrack = event.currentTarget.closest<HTMLElement>(
+      '[data-timeline-track]'
+    );
+    if (!timelineTrack || document.duration <= 0) return;
+    event.preventDefault();
+    videoRef.current?.pause();
+    stopImagePlayback();
+    if (selectedClipId !== clip.id) selectClip(clip);
+
+    const rect = timelineTrack.getBoundingClientRect();
+    const initialPreview: TimelineClipInteractionPreview = {
+      id: clip.id,
+      startTime: clip.startTime,
+      duration: clip.duration,
+      inPoint: clip.inPoint,
+      outPoint: clip.outPoint,
+      sourceDuration: clip.sourceDuration,
+    };
+    timelineDragRef.current = {
+      clip,
+      mode,
+      originClientX: event.clientX,
+      timelineWidth: rect.width,
+      timelineDuration: Math.max(document.duration, 0.001),
+      preview: initialPreview,
+    };
+    setTimelineDragPreview(initialPreview);
+
+    const finishDrag = () => {
+      const session = timelineDragRef.current;
+      timelineDragRef.current = null;
+      window.removeEventListener('pointermove', moveDrag);
+      window.removeEventListener('pointerup', finishDrag);
+      window.removeEventListener('pointercancel', finishDrag);
+      setTimelineDragPreview(null);
+      if (!session) return;
+      const preview = session.preview;
+      if (
+        preview.startTime === session.clip.startTime &&
+        preview.duration === session.clip.duration &&
+        preview.inPoint === session.clip.inPoint &&
+        preview.outPoint === session.clip.outPoint
+      ) {
+        return;
+      }
+
+      const operations: EditorOperation[] = [];
+      if (session.mode === 'move') {
+        operations.push({
+          type: 'move_clip',
+          clipId: session.clip.id,
+          startTime: preview.startTime,
+        });
+      } else if (session.clip.sourceType === 'image') {
+        operations.push({
+          type: 'set_clip_duration',
+          clipId: session.clip.id,
+          duration: preview.duration,
+        });
+        if (session.mode === 'trim-start') {
+          operations.push({
+            type: 'move_clip',
+            clipId: session.clip.id,
+            startTime: preview.startTime,
+          });
+        }
+      } else {
+        operations.push({
+          type: 'trim_clip',
+          clipId: session.clip.id,
+          inPoint: preview.inPoint,
+          outPoint: preview.outPoint,
+        });
+        if (session.mode === 'trim-start') {
+          operations.push({
+            type: 'move_clip',
+            clipId: session.clip.id,
+            startTime: preview.startTime,
+          });
+        }
+      }
+
+      try {
+        const next = applyEditorOperations(document, operations).document;
+        commitDocument(next);
+        const nextCursor = Math.max(
+          preview.startTime,
+          Math.min(
+            preview.startTime + preview.duration,
+            timelineCurrentTime
+          )
+        );
+        setTimelineCursorTime(nextCursor);
+        if (session.clip.sourceType === 'image') {
+          setCurrentTime(nextCursor - preview.startTime);
+        } else {
+          setCurrentTime(preview.inPoint + (nextCursor - preview.startTime));
+        }
+      } catch {
+        setError(t('errors.clipOverlap'));
+      }
+    };
+
+    const moveDrag = (pointerEvent: PointerEvent) => {
+      const session = timelineDragRef.current;
+      if (!session || session.timelineWidth <= 0) return;
+      const deltaTime =
+        ((pointerEvent.clientX - session.originClientX) /
+          session.timelineWidth) *
+        session.timelineDuration;
+      const preview = buildTimelineDragPreview({
+        document,
+        clip: session.clip,
+        mode: session.mode,
+        deltaTime,
+      });
+      session.preview = preview;
+      setTimelineDragPreview(preview);
+    };
+
+    window.addEventListener('pointermove', moveDrag);
+    window.addEventListener('pointerup', finishDrag);
+    window.addEventListener('pointercancel', finishDrag);
+  };
+
+  const deleteSelectedClip = (ripple: boolean) => {
+    if (!selectedClip) return;
+    commitDocument(
+      applyEditorOperations(document, [
+        { type: 'remove_clip', clipId: selectedClip.id, ripple },
+      ]).document
+    );
+    setSelectedClipId(null);
+    videoRef.current?.pause();
+    stopImagePlayback();
+  };
+
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      const target = event.target;
+      if (
+        target instanceof HTMLElement &&
+        target.closest('input, textarea, select, [contenteditable="true"]')
+      ) {
+        return;
+      }
+      const commandKey = event.metaKey || event.ctrlKey;
+      const key = event.key.toLowerCase();
+
+      if (commandKey && key === 'z') {
+        event.preventDefault();
+        if (event.shiftKey) redoTimeline();
+        else undoTimeline();
+        return;
+      }
+      if (commandKey && key === 'b') {
+        event.preventDefault();
+        splitAtPlayhead();
+        return;
+      }
+      if (event.code === 'Space') {
+        event.preventDefault();
+        void togglePlayback();
+        return;
+      }
+      if (event.key === 'Delete' || event.key === 'Backspace') {
+        if (!selectedClip) return;
+        event.preventDefault();
+        deleteSelectedClip(false);
+        return;
+      }
+      if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
+        event.preventDefault();
+        const direction = event.key === 'ArrowLeft' ? -1 : 1;
+        seekTimeline(
+          timelineCurrentTime + direction * (event.shiftKey ? 1 : 0.04)
+        );
+      }
+    };
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  });
+
+  const createDerivedSelection = async () => {
+    if (!selectedClip || !selectedSource) return null;
+    setError(null);
+    setIsExporting(true);
+    setExportProgress(0);
+    try {
+      let file = sourceFileRef.current;
+      if (!file || selectedSource.assetId !== clips[0]?.assetId) {
+        const response = await fetch(selectedSource.sourceUrl);
+        if (!response.ok) throw new Error(t('errors.sourceUnavailable'));
+        const blob = await response.blob();
+        file = new File([blob], selectedSource.name, {
+          type: blob.type || 'video/mp4',
+        });
+        sourceFileRef.current = file;
+      }
+      const blob = await exportTrimmedMp4({
+        file,
+        start: selectedSource.inPoint,
+        end: selectedSource.outPoint,
+        onProgress: setExportProgress,
+      });
+      const filename = `${safeFilename(selectedSource.name)}-${selectedSource.inPoint.toFixed(2)}-${selectedSource.outPoint.toFixed(2)}.mp4`;
+      const derivedFile = new File([blob], filename, { type: 'video/mp4' });
+      const derivedMetadata = await inspectLocalMedia(derivedFile);
+      const asset = await uploadLocalProjectAsset({
+        projectId,
+        file: derivedFile,
+        assetClass: 'derived',
+        width: derivedMetadata.width ?? undefined,
+        height: derivedMetadata.height ?? undefined,
+        durationMs: selectedClip.duration * 1000,
+        metadata: {
+          parentAssetId: selectedSource.assetId,
+          sourceInSec: selectedSource.inPoint,
+          sourceOutSec: selectedSource.outPoint,
+          operation: 'timeline_extract',
+          timelineId: document.id,
+          clipId: selectedClip.id,
+        },
+      });
+      return { asset, file: derivedFile, blob, filename };
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : t('errors.exportFailed'));
+      return null;
+    } finally {
+      setIsExporting(false);
+    }
+  };
+
+  const exportSelection = () =>
+    void (async () => {
+      const blockingDiagnostic = diagnoseTimeline(document).find(
+        (diagnostic) => diagnostic.severity === 'error'
+      );
+      if (blockingDiagnostic) {
+        setError(t(`diagnostics.${blockingDiagnostic.code}`));
+        return;
+      }
+
+      setError(null);
+      setIsExporting(true);
+      setExportProgress(0);
+      const controller = new AbortController();
+      exportControllerRef.current = controller;
+      try {
+        const blob = await exportTimelineMp4({
+          document,
+          signal: controller.signal,
+          onProgress: setExportProgress,
+        });
+        const filename = `${safeFilename(document.name)}-timeline.mp4`;
+        const renderFile = new File([blob], filename, { type: 'video/mp4' });
+        const renderMetadata = await inspectLocalMedia(renderFile);
+        const asset = await uploadLocalProjectAsset({
+          projectId,
+          file: renderFile,
+          assetClass: 'derived',
+          width: renderMetadata.width ?? undefined,
+          height: renderMetadata.height ?? undefined,
+          durationMs: document.duration * 1000,
+          metadata: {
+            operation: 'timeline_render',
+            timelineId: document.id,
+            clipCount: clips.length,
+          },
+        });
+        const nextDocument = applyEditorOperations(document, [
+          {
+            type: 'set_render',
+            assetId: asset.id,
+            publicUrl: asset.publicUrl,
+          },
+        ]).document;
+        commitDocument(nextDocument);
+        const saved = await saveTimelineThroughCommand({
+          projectId,
+          document: nextDocument,
+          expectedRevision: timelineVersionRef.current,
+        });
+        timelineVersionRef.current = saved.version;
+        lastSavedDocumentRef.current = saved.document;
+        await apiJsonPost(
+          `/api/app/projects/${encodeURIComponent(projectId)}/timeline`,
+          {}
+        );
+        downloadBlob(blob, filename);
+      } catch (cause) {
+        setError(
+          cause instanceof DOMException && cause.name === 'AbortError'
+            ? t('errors.exportCancelled')
+            : cause instanceof Error
+              ? cause.message
+              : t('errors.exportFailed')
+        );
+      } finally {
+        exportControllerRef.current = null;
+        setIsExporting(false);
+      }
+    })();
+
+  const addTimelineToCanvas = async () => {
+    try {
+      const saved = await saveTimelineThroughCommand({
+        projectId,
+        document,
+        expectedRevision: timelineVersionRef.current,
+      });
+      timelineVersionRef.current = saved.version;
+      lastSavedDocumentRef.current = saved.document;
+      await apiJsonPost(
+        `/api/app/projects/${encodeURIComponent(projectId)}/timeline`,
+        {}
+      );
+      setRedoStatus(t('status.canvasAdded'));
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : t('errors.canvasNodeFailed'));
+    }
+  };
+
+  const runRedo = async () => {
+    if (!selectedClip || selectedClip.sourceType !== 'video') return;
+    setIsRedoing(true);
+    setError(null);
+    setRedoStatus(t('redo.preparing'));
+    try {
+      const derived = await createDerivedSelection();
+      if (!derived) return;
+      const result = await redoTimelineSelection({
+        projectId,
+        file: derived.file,
+        prompt: redoPrompt,
+        durationSec: selectedClip.duration,
+        onStatus: (status) => setRedoStatus(t(`redo.status.${status}`)),
+      });
+      const resultFileResponse = await fetch(result.resultUrl);
+      if (!resultFileResponse.ok) throw new Error(t('errors.sourceUnavailable'));
+      const resultBlob = await resultFileResponse.blob();
+      const resultFile = new File([resultBlob], 'beatapi-redo.mp4', {
+        type: resultBlob.type || 'video/mp4',
+      });
+      const resultMetadata = await inspectLocalMedia(resultFile);
+      const assets = await fetchRecentAssets(projectId);
+      const resultAsset = assets.videos.find(
+        (asset) =>
+          asset.id === result.assetId || asset.publicUrl === result.resultUrl
+      );
+      if (!resultAsset && !result.assetId) {
+        throw new Error(t('errors.redoAssetMissing'));
+      }
+      commitDocument((current) =>
+        applyEditorOperations(current, [
+          {
+            type: 'add_take',
+            clipId: selectedClip.id,
+            take: {
+              assetId: resultAsset?.id ?? result.assetId!,
+              sourceUrl: result.resultUrl,
+              name: `${selectedClip.name} · AI Take`,
+              sourceDuration: resultMetadata.duration,
+              sourceGenerationId: result.generationId,
+              prompt: redoPrompt.trim(),
+            },
+          },
+        ]).document
+      );
+      setRedoStatus(t('redo.ready'));
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : t('errors.redoFailed'));
+      setRedoStatus('');
+    } finally {
+      setIsRedoing(false);
+    }
+  };
+
+  const activateTake = (takeId: string | null) => {
+    if (!selectedClip) return;
+    const next = applyEditorOperations(document, [
+      { type: 'activate_take', clipId: selectedClip.id, takeId },
+    ]).document;
+    const nextClip = findTimelineClip(next, selectedClip.id);
+    if (!nextClip) return;
+    const nextSource = getTimelineClipSource(nextClip);
+    commitDocument(next);
+    setSourceUrl(nextSource.sourceUrl);
+    sourceFileRef.current = null;
+    seek(nextSource.inPoint);
+  };
+
+  return (
+    <div
+      className="beat-product-shell flex min-h-0 flex-1 flex-col bg-[var(--beat-bg)] text-[var(--beat-text-1)]"
+      onDragOver={(event) => event.preventDefault()}
+      onDrop={handleDrop}
+    >
+      <input
+        ref={fileInputRef}
+        type="file"
+        accept="image/jpeg,image/png,image/webp,image/gif,image/avif,video/mp4,video/quicktime,video/webm,image/*,video/*"
+        className="hidden"
+        onChange={handleFileInput}
+      />
+      <input
+        ref={audioInputRef}
+        type="file"
+        accept="audio/mpeg,audio/wav,audio/mp4,audio/aac,audio/ogg,.mp3,.wav,.m4a,.aac,.ogg"
+        className="hidden"
+        onChange={handleAudioInput}
+      />
+      {clips
+        .filter((clip) => clip.sourceType === 'audio')
+        .map((clip) => (
+          <audio
+            key={clip.id}
+            ref={(element) => {
+              if (element) audioElementsRef.current.set(clip.id, element);
+              else audioElementsRef.current.delete(clip.id);
+            }}
+            src={clip.sourceUrl}
+            preload="auto"
+            className="hidden"
+          />
+        ))}
+
+      <div className="flex min-h-0 flex-1">
+        <aside className="hidden w-64 shrink-0 border-r border-white/[0.07] bg-[var(--beat-surface)] p-4 lg:block">
+          <div className="mb-4 flex items-center justify-between">
+            <div>
+              <p className="text-[11px] font-[540] tracking-[-0.01em] text-white/42">
+                {t('media.eyebrow')}
+              </p>
+              <h2 className="mt-1 text-sm font-semibold text-white">
+                {t('media.title')}
+              </h2>
+            </div>
+            <div className="flex items-center gap-1.5">
+              <button
+                type="button"
+                onClick={() => audioInputRef.current?.click()}
+                className="inline-flex size-8 items-center justify-center rounded-lg border border-white/10 bg-white/[0.04] text-white/60 transition hover:bg-white/[0.08] hover:text-white"
+                aria-label={t('actions.importAudio')}
+                title={t('actions.importAudio')}
+              >
+                <Music2 className="size-4" />
+              </button>
+              <button
+                type="button"
+                onClick={() => fileInputRef.current?.click()}
+                className="inline-flex size-8 items-center justify-center rounded-lg border border-white/10 bg-white/[0.04] text-white/60 transition hover:bg-white/[0.08] hover:text-white"
+                aria-label={t('actions.import')}
+              >
+                <Upload className="size-4" />
+              </button>
+            </div>
+          </div>
+          {primaryVisualClip ? (
+            <button
+              type="button"
+              onClick={() => selectClip(primaryVisualClip)}
+              className="w-full rounded-xl border border-white/10 bg-white/[0.04] p-3 text-left transition hover:border-white/20"
+            >
+              <div className="relative mb-3 flex aspect-video items-center justify-center overflow-hidden rounded-lg bg-black/55">
+                {primaryVisualClip.sourceType === 'image' ? (
+                  <img
+                    src={primaryVisualClip.sourceUrl}
+                    alt=""
+                    className="size-full object-cover"
+                  />
+                ) : (
+                  <video
+                    src={primaryVisualClip.sourceUrl}
+                    muted
+                    playsInline
+                    preload="metadata"
+                    className="size-full object-cover opacity-75"
+                  />
+                )}
+              </div>
+              <p className="truncate text-xs font-medium text-white">
+                {primaryVisualClip.name}
+              </p>
+              <p className="mt-1 text-[11px] text-white/40">
+                {metadata?.width && metadata.height
+                  ? `${metadata.width}×${metadata.height} · `
+                  : ''}
+                {primaryVisualClip.sourceType === 'image'
+                  ? t('media.stillDuration', {
+                      duration: primaryVisualClip.duration.toFixed(1),
+                    })
+                  : formatTime(
+                      metadata?.duration ?? primaryVisualClip.sourceDuration
+                    )}
+              </p>
+            </button>
+          ) : (
+            <button
+              type="button"
+              onClick={() => fileInputRef.current?.click()}
+              className="flex w-full flex-col items-center rounded-xl border border-dashed border-white/12 px-4 py-8 text-center text-white/40 transition hover:border-[var(--beat-accent)]/50 hover:bg-white/[0.025] hover:text-white/70"
+            >
+              <Upload className="mb-3 size-5" />
+              <span className="text-xs font-medium">{t('media.drop')}</span>
+              <span className="mt-1 text-[11px]">{t('media.localOnly')}</span>
+            </button>
+          )}
+        </aside>
+
+        <section className="flex min-w-0 flex-1 flex-col">
+          <div className="flex h-12 shrink-0 items-center justify-between border-b border-white/[0.07] px-3 sm:px-4">
+            <div className="flex items-center gap-2 text-xs text-white/55">
+              <span className="rounded-md border border-white/10 bg-white/[0.04] px-2 py-1 text-[11px] font-[520] tabular-nums tracking-[-0.01em]">
+                {metadata?.width && metadata.height
+                  ? `${metadata.width}×${metadata.height}`
+                  : '—'}
+              </span>
+              <span className="hidden sm:inline">
+                {metadata?.videoCodec?.toUpperCase() ?? t('status.ready')}
+              </span>
+              {saveStatus !== 'idle' ? (
+                <span className="text-white/35">
+                  {saveStatus === 'saving' ? t('status.saving') : t('status.saved')}
+                </span>
+              ) : null}
+            </div>
+            <div className="flex items-center gap-2">
+              <div className="hidden items-center rounded-lg border border-white/10 sm:flex">
+                <button
+                  type="button"
+                  onClick={undoTimeline}
+                  disabled={!canUndo}
+                  className="grid size-8 place-items-center text-white/55 hover:bg-white/[0.06] hover:text-white disabled:opacity-25"
+                  aria-label={t('actions.undo')}
+                  title={t('actions.undo')}
+                >
+                  <Undo2 className="size-3.5" />
+                </button>
+                <button
+                  type="button"
+                  onClick={redoTimeline}
+                  disabled={!canRedo}
+                  className="grid size-8 place-items-center border-l border-white/10 text-white/55 hover:bg-white/[0.06] hover:text-white disabled:opacity-25"
+                  aria-label={t('actions.redoEdit')}
+                  title={t('actions.redoEdit')}
+                >
+                  <Redo2 className="size-3.5" />
+                </button>
+              </div>
+              <button
+                type="button"
+                onClick={() => void addTimelineToCanvas()}
+                disabled={clips.length === 0}
+                className="hidden h-8 items-center gap-1.5 rounded-lg border border-white/10 px-3 text-xs font-medium text-white/65 transition hover:bg-white/[0.06] hover:text-white disabled:opacity-35 md:inline-flex"
+              >
+                {t('actions.addTimelineToCanvas')}
+              </button>
+              <button
+                type="button"
+                onClick={() => void createDerivedSelection()}
+                disabled={!selectedClip || selectedClip.sourceType !== 'video' || isExporting}
+                className="hidden h-8 items-center gap-1.5 rounded-lg border border-white/10 px-3 text-xs font-medium text-white/65 transition hover:bg-white/[0.06] hover:text-white disabled:opacity-35 sm:inline-flex"
+              >
+                <Scissors className="size-3.5" />
+                {t('actions.extract')}
+              </button>
+              <button
+                type="button"
+                onClick={() => setRedoOpen((current) => !current)}
+                disabled={!selectedClip || selectedClip.sourceType !== 'video' || isRedoing}
+                className="inline-flex h-8 items-center gap-1.5 rounded-lg border border-white/10 px-3 text-xs font-medium text-white/65 transition hover:bg-white/[0.06] hover:text-white disabled:cursor-not-allowed disabled:opacity-35"
+                title={t('actions.redoHint')}
+              >
+                <Sparkles className="size-3.5" />
+                <span className="hidden sm:inline">{t('actions.redo')}</span>
+              </button>
+              <button
+                type="button"
+                onClick={() =>
+                  isExporting
+                    ? exportControllerRef.current?.abort()
+                    : exportSelection()
+                }
+                disabled={
+                  !isExporting && !clips.some((clip) => clip.sourceType !== 'audio')
+                }
+                className={`inline-flex h-8 items-center gap-1.5 rounded-lg px-3 text-xs font-semibold text-white transition disabled:cursor-not-allowed disabled:opacity-45 ${
+                  isExporting
+                    ? 'border border-white/12 bg-white/[0.06] hover:bg-white/[0.1]'
+                    : 'bg-[var(--beat-accent)] hover:brightness-110'
+                }`}
+              >
+                <Download className="size-3.5" />
+                {isExporting
+                  ? t('actions.cancelExport', {
+                      progress: Math.round(exportProgress * 100),
+                    })
+                  : t('actions.export')}
+              </button>
+            </div>
+          </div>
+
+          <div className="relative flex min-h-0 flex-1 items-center justify-center overflow-hidden bg-black/35 p-4 sm:p-8">
+            {sourceUrl && selectedClip?.sourceType === 'image' ? (
+              <img
+                src={sourceUrl}
+                alt={selectedClip.name}
+                className="h-full w-full max-w-5xl rounded-xl bg-black object-contain shadow-2xl"
+              />
+            ) : sourceUrl && selectedClip?.sourceType === 'video' ? (
+              <video
+                ref={videoRef}
+                src={sourceUrl}
+                playsInline
+                className="h-full w-full max-w-5xl rounded-xl bg-black object-contain shadow-2xl"
+                onLoadedMetadata={(event) => {
+                  if (!selectedClip || !selectedSource) return;
+                  const target = Math.max(
+                    selectedSource.inPoint,
+                    Math.min(selectedSource.outPoint, currentTime)
+                  );
+                  event.currentTarget.currentTime = target;
+                }}
+                onPlay={(event) => {
+                  setIsPlaying(true);
+                  syncAudioTracks(event.currentTarget.currentTime, true);
+                }}
+                onPause={(event) => {
+                  setIsPlaying(false);
+                  syncAudioTracks(event.currentTarget.currentTime, false);
+                }}
+                onTimeUpdate={(event) => {
+                  const time = event.currentTarget.currentTime;
+                  if (selectedClip && selectedSource && time >= selectedSource.outPoint) {
+                    event.currentTarget.pause();
+                    event.currentTarget.currentTime = selectedSource.outPoint;
+                    setCurrentTime(selectedSource.outPoint);
+                    setTimelineCursorTime(
+                      selectedClip.startTime + selectedClip.duration
+                    );
+                    return;
+                  }
+                  setCurrentTime(time);
+                  if (selectedClip && selectedSource) {
+                    setTimelineCursorTime(
+                      selectedClip.startTime + (time - selectedSource.inPoint)
+                    );
+                  }
+                  syncAudioTracks(time, !event.currentTarget.paused);
+                }}
+              />
+            ) : (
+              <button
+                type="button"
+                onClick={() => fileInputRef.current?.click()}
+                className="flex max-w-md flex-col items-center rounded-2xl border border-dashed border-white/12 bg-white/[0.018] px-10 py-12 text-center transition hover:border-[var(--beat-accent)]/45 hover:bg-white/[0.03]"
+              >
+                <span className="mb-4 inline-flex size-12 items-center justify-center rounded-2xl bg-[var(--beat-accent)]/12 text-[var(--beat-accent)]">
+                  <ImageIcon className="size-6" />
+                </span>
+                <span className="text-sm font-semibold text-white">
+                  {isInspecting ? t('status.reading') : t('empty.title')}
+                </span>
+                <span className="mt-2 text-xs leading-5 text-white/40">
+                  {t('empty.description')}
+                </span>
+              </button>
+            )}
+
+            {redoOpen && selectedClip?.sourceType === 'video' ? (
+              <aside className="absolute bottom-4 right-4 top-4 z-20 flex w-[min(340px,calc(100%-2rem))] flex-col rounded-2xl border border-white/10 bg-[#111214]/96 p-4 shadow-2xl backdrop-blur-xl">
+                <div className="flex items-start justify-between gap-3">
+                  <div>
+                    <p className="text-sm font-semibold text-white">{t('redo.title')}</p>
+                    <p className="mt-1 text-[11px] leading-4 text-white/42">
+                      {t('redo.description')}
+                    </p>
+                  </div>
+                  <button
+                    type="button"
+                    onClick={() => setRedoOpen(false)}
+                    className="text-lg leading-none text-white/35 hover:text-white"
+                    aria-label={t('redo.close')}
+                  >
+                    ×
+                  </button>
+                </div>
+                <div className="mt-4 rounded-xl border border-white/[0.08] bg-white/[0.035] px-3 py-2.5">
+                  <div className="flex items-center justify-between text-[11px]">
+                    <span className="font-medium text-white/75">Seedance 2</span>
+                    <span className="font-[520] tabular-nums tracking-[-0.01em] text-white/42">{selectedClip.duration.toFixed(2)}s</span>
+                  </div>
+                  <p className="mt-1 text-[10px] text-white/35">{t('redo.billingNotice')}</p>
+                </div>
+                <textarea
+                  value={redoPrompt}
+                  onChange={(event) => setRedoPrompt(event.target.value)}
+                  placeholder={t('redo.placeholder')}
+                  maxLength={5000}
+                  className="mt-3 min-h-24 resize-none rounded-xl border border-white/10 bg-black/30 px-3 py-2.5 text-xs leading-5 text-white outline-none placeholder:text-white/25 focus:border-[var(--beat-accent)]/55"
+                />
+                <button
+                  type="button"
+                  onClick={() => void runRedo()}
+                  disabled={isRedoing || !redoPrompt.trim()}
+                  className="mt-3 inline-flex h-9 items-center justify-center gap-2 rounded-lg bg-[var(--beat-accent)] px-3 text-xs font-semibold text-white transition hover:brightness-110 disabled:opacity-40"
+                >
+                  <Sparkles className="size-3.5" />
+                  {isRedoing ? t('redo.running') : t('redo.confirm')}
+                </button>
+                {redoStatus ? (
+                  <p className="mt-2 text-center text-[10px] text-white/42">{redoStatus}</p>
+                ) : null}
+                <div className="mt-4 min-h-0 flex-1 overflow-y-auto border-t border-white/[0.07] pt-3">
+                  <p className="mb-2 text-[10px] font-[540] tracking-[-0.01em] text-white/36">
+                    {t('redo.takes')}
+                  </p>
+                  <button
+                    type="button"
+                    onClick={() => activateTake(null)}
+                    className={`mb-2 flex w-full items-center justify-between rounded-lg border px-3 py-2 text-left text-[11px] ${
+                      !selectedClip.activeTakeId
+                        ? 'border-[var(--beat-graph)]/50 bg-[var(--beat-graph)]/10 text-white'
+                        : 'border-white/[0.08] text-white/55 hover:bg-white/[0.04]'
+                    }`}
+                  >
+                    <span>{t('redo.original')}</span>
+                    {!selectedClip.activeTakeId ? <span>✓</span> : null}
+                  </button>
+                  {selectedClip.takes.map((take, index) => (
+                    <button
+                      key={take.id}
+                      type="button"
+                      onClick={() => activateTake(take.id)}
+                      className={`mb-2 flex w-full items-center justify-between rounded-lg border px-3 py-2 text-left text-[11px] ${
+                        selectedClip.activeTakeId === take.id
+                          ? 'border-[var(--beat-accent)]/55 bg-[var(--beat-accent)]/10 text-white'
+                          : 'border-white/[0.08] text-white/55 hover:bg-white/[0.04]'
+                      }`}
+                    >
+                      <span className="min-w-0 truncate">AI Take {index + 1} · {take.prompt}</span>
+                      {selectedClip.activeTakeId === take.id ? <span>✓</span> : null}
+                    </button>
+                  ))}
+                  {selectedClip.activeTakeId ? (
+                    <button
+                      type="button"
+                      onClick={() => activateTake(null)}
+                      className="mt-1 inline-flex items-center gap-1.5 text-[10px] text-white/45 hover:text-white"
+                    >
+                      <RotateCcw className="size-3" />
+                      {t('redo.rollback')}
+                    </button>
+                  ) : null}
+                </div>
+              </aside>
+            ) : null}
+          </div>
+
+          <div className="shrink-0 border-t border-white/[0.07] bg-[#151618]">
+            <div className="flex h-12 items-center justify-center gap-3 border-b border-white/[0.07] px-4">
+              <span className="w-16 text-right text-[11px] font-[520] tabular-nums tracking-[-0.01em] text-white/48">
+                {formatTime(timelineCurrentTime)}
+              </span>
+              <button
+                type="button"
+                onClick={() => void togglePlayback()}
+                disabled={!selectedClip || selectedClip.sourceType === 'audio'}
+                className="inline-flex size-8 items-center justify-center rounded-full bg-white text-black shadow-[0_5px_18px_rgba(0,0,0,0.28)] transition hover:scale-105 disabled:cursor-not-allowed disabled:opacity-30"
+                aria-label={isPlaying ? t('actions.pause') : t('actions.play')}
+                title={`${isPlaying ? t('actions.pause') : t('actions.play')} · Space`}
+              >
+                {isPlaying ? (
+                  <Pause className="size-4 fill-current" />
+                ) : (
+                  <Play className="ml-0.5 size-4 fill-current" />
+                )}
+              </button>
+              <button
+                type="button"
+                onClick={splitAtPlayhead}
+                disabled={
+                  !selectedClip ||
+                  selectedClip.sourceType !== 'video' ||
+                  Boolean(selectedClip.activeTakeId) ||
+                  currentTime <= selectedClip.inPoint + MIN_CLIP_DURATION ||
+                  currentTime >= selectedClip.outPoint - MIN_CLIP_DURATION
+                }
+                className="inline-flex h-8 items-center gap-1.5 rounded-lg px-2.5 text-xs font-[520] text-white/62 transition hover:bg-white/[0.06] hover:text-white disabled:cursor-not-allowed disabled:opacity-30"
+                title={`${t('actions.split')} · ⌘/Ctrl+B`}
+              >
+                <Scissors className="size-3.5" />
+                {t('actions.split')}
+                <kbd className="hidden rounded bg-white/[0.055] px-1 py-0.5 text-[9px] font-[520] text-white/35 sm:inline">
+                  ⌘B
+                </kbd>
+              </button>
+              <span className="w-16 text-[11px] font-[520] tabular-nums tracking-[-0.01em] text-white/48">
+                {formatTime(document.duration)}
+              </span>
+            </div>
+
+            {selectedClip && displayedSelectedClip ? (
+              <div className="border-b border-white/[0.07] px-3 py-2 lg:px-4">
+                <div className="flex min-w-0 items-center gap-2.5">
+                  <span className="grid size-8 shrink-0 place-items-center rounded-lg bg-white/[0.055] text-white/62">
+                    {selectedClip.sourceType === 'image' ? (
+                      <ImageIcon className="size-4" />
+                    ) : selectedClip.sourceType === 'video' ? (
+                      <FileVideo2 className="size-4" />
+                    ) : (
+                      <Volume2 className="size-4" />
+                    )}
+                  </span>
+                  <span className="min-w-0">
+                    <span className="block truncate text-[12px] font-[560] tracking-[-0.01em] text-white/88">
+                      {selectedClip.name}
+                    </span>
+                    <span className="mt-0.5 block text-[10px] font-[500] text-white/38">
+                      {t(`clipInspector.type.${selectedClip.sourceType}`)} ·{' '}
+                      {displayedSelectedClip.duration.toFixed(2)}s
+                    </span>
+                  </span>
+                  <span className="ml-2 hidden min-w-0 flex-1 text-[10px] font-[500] text-white/30 md:block">
+                    {t('timeline.dragHint')}
+                  </span>
+                  <div className="ml-auto flex items-center gap-1.5">
+                    <button
+                      type="button"
+                      onClick={() => setExactControlsOpen((value) => !value)}
+                      aria-expanded={exactControlsOpen}
+                      className={`inline-flex h-8 items-center gap-1.5 rounded-lg border px-2.5 text-[10px] font-[520] transition ${
+                        exactControlsOpen
+                          ? 'border-white/18 bg-white/[0.08] text-white/80'
+                          : 'border-white/10 text-white/42 hover:bg-white/[0.05] hover:text-white/75'
+                      }`}
+                    >
+                      <SlidersHorizontal className="size-3" />
+                      {t('clipInspector.exactControls')}
+                    </button>
+                    <button
+                      type="button"
+                      onClick={() => deleteSelectedClip(false)}
+                      title={`${t('timeline.delete')} · Delete`}
+                      className="inline-flex size-8 items-center justify-center rounded-lg border border-white/10 text-white/42 transition hover:border-red-400/25 hover:bg-red-400/10 hover:text-red-100"
+                      aria-label={t('timeline.delete')}
+                    >
+                      <Trash2 className="size-3.5" />
+                    </button>
+                    <button
+                      type="button"
+                      onClick={() => deleteSelectedClip(true)}
+                      className="inline-flex h-8 items-center rounded-lg border border-white/10 px-2.5 text-[10px] font-[520] text-white/42 transition hover:bg-white/[0.06] hover:text-white"
+                    >
+                      {t('timeline.rippleDelete')}
+                    </button>
+                  </div>
+                </div>
+
+                {exactControlsOpen ? (
+                  <div className="mt-2 flex flex-wrap items-end gap-3 rounded-xl border border-white/[0.07] bg-black/15 px-3 py-2">
+                    <div>
+                      <p className="mb-1 text-[9px] font-[520] text-white/32">
+                        {selectedClip.sourceType === 'video'
+                          ? t('clipInspector.sourceRange')
+                          : selectedClip.sourceType === 'image'
+                            ? t('clipInspector.stillDuration')
+                            : t('clipInspector.clipDuration')}
+                      </p>
+                      {selectedClip.sourceType === 'video' && !selectedClip.activeTakeId ? (
+                        <div className="flex items-center gap-2">
+                      <input
+                        type="number"
+                        min={0}
+                        max={selectedClip.outPoint - MIN_CLIP_DURATION}
+                        step={0.01}
+                        value={Number(selectedClip.inPoint.toFixed(2))}
+                        onChange={(event) =>
+                          updateTrim('in', Number(event.target.value))
+                        }
+                        className="h-7 min-w-0 flex-1 rounded-lg border border-white/10 bg-black/20 px-2 text-[11px] font-[520] tabular-nums text-white/82 outline-none transition focus:border-[var(--beat-accent)]/55"
+                        aria-label={t('clipInspector.sourceFrom')}
+                      />
+                      <span className="text-[10px] text-white/28">→</span>
+                      <input
+                        type="number"
+                        min={selectedClip.inPoint + MIN_CLIP_DURATION}
+                        max={selectedClip.sourceDuration}
+                        step={0.01}
+                        value={Number(selectedClip.outPoint.toFixed(2))}
+                        onChange={(event) =>
+                          updateTrim('out', Number(event.target.value))
+                        }
+                        className="h-7 min-w-0 flex-1 rounded-lg border border-white/10 bg-black/20 px-2 text-[11px] font-[520] tabular-nums text-white/82 outline-none transition focus:border-[var(--beat-accent)]/55"
+                        aria-label={t('clipInspector.sourceTo')}
+                      />
+                        </div>
+                      ) : selectedClip.sourceType === 'image' ? (
+                        <div className="flex items-center gap-2">
+                      <input
+                        type="number"
+                        min={MIN_CLIP_DURATION}
+                        step={0.1}
+                        value={Number(selectedClip.duration.toFixed(2))}
+                        onChange={(event) =>
+                          resizeSelectedImage(Number(event.target.value))
+                        }
+                        className="h-7 w-24 rounded-lg border border-white/10 bg-black/20 px-2 text-[11px] font-[520] tabular-nums text-white/82 outline-none transition focus:border-[var(--beat-accent)]/55"
+                        aria-label={t('clipInspector.stillDuration')}
+                      />
+                      <span className="text-[10px] text-white/35">s</span>
+                        </div>
+                      ) : (
+                        <p className="text-[11px] font-[520] tabular-nums text-white/72">
+                          {selectedClip.duration.toFixed(2)}s
+                        </p>
+                      )}
+                    </div>
+
+                    <div>
+                      <p className="mb-1 text-[9px] font-[520] text-white/32">
+                        {t('clipInspector.timelinePosition')}
+                      </p>
+                      <div className="flex items-center gap-2">
+                    <input
+                      type="number"
+                      min={0}
+                      step={0.01}
+                      value={Number(selectedClip.startTime.toFixed(2))}
+                      onChange={(event) =>
+                        moveSelectedClip(Number(event.target.value))
+                      }
+                      className="h-7 w-24 rounded-lg border border-white/10 bg-black/20 px-2 text-[11px] font-[520] tabular-nums text-white/82 outline-none transition focus:border-[var(--beat-accent)]/55"
+                      aria-label={t('clipInspector.timelinePosition')}
+                    />
+                    <span className="text-[10px] text-white/35">s</span>
+                      </div>
+                    </div>
+                  </div>
+                ) : null}
+              </div>
+            ) : null}
+
+            {selectedClip?.sourceType === 'audio' ? (
+              <div className="grid grid-cols-[auto_1fr_auto] items-center gap-x-3 gap-y-2 border-b border-white/[0.07] px-4 py-2.5">
+                <label className="text-[10px] font-[520] text-white/40">
+                  {t('audio.volume')}
+                </label>
+                <input
+                  type="range"
+                  min={0}
+                  max={1}
+                  step={0.01}
+                  value={Math.min(1, selectedClip.volume)}
+                  onChange={(event) =>
+                    commitDocument((current) =>
+                      applyEditorOperations(current, [
+                        {
+                          type: 'update_audio',
+                          clipId: selectedClip.id,
+                          patch: { volume: Number(event.target.value) },
+                        },
+                      ]).document
+                    )
+                  }
+                  className="h-1 w-full accent-[var(--beat-graph)]"
+                  aria-label={t('audio.volume')}
+                />
+                <span className="w-12 text-right text-[11px] font-[520] tabular-nums text-white/58">
+                  {Math.round(Math.min(1, selectedClip.volume) * 100)}%
+                </span>
+
+                <label className="text-[10px] font-[520] text-white/40">
+                  {t('audio.fadeIn')}
+                </label>
+                <input
+                  type="range"
+                  min={0}
+                  max={selectedClip.duration}
+                  step={0.01}
+                  value={selectedClip.fadeIn}
+                  onChange={(event) =>
+                    commitDocument((current) =>
+                      applyEditorOperations(current, [
+                        {
+                          type: 'update_audio',
+                          clipId: selectedClip.id,
+                          patch: { fadeIn: Number(event.target.value) },
+                        },
+                      ]).document
+                    )
+                  }
+                  className="h-1 w-full accent-[var(--beat-graph)]"
+                  aria-label={t('audio.fadeIn')}
+                />
+                <span className="w-12 text-right text-[11px] font-[520] tabular-nums text-white/58">
+                  {selectedClip.fadeIn.toFixed(2)}s
+                </span>
+
+                <label className="text-[10px] font-[520] text-white/40">
+                  {t('audio.fadeOut')}
+                </label>
+                <input
+                  type="range"
+                  min={0}
+                  max={selectedClip.duration}
+                  step={0.01}
+                  value={selectedClip.fadeOut}
+                  onChange={(event) =>
+                    commitDocument((current) =>
+                      applyEditorOperations(current, [
+                        {
+                          type: 'update_audio',
+                          clipId: selectedClip.id,
+                          patch: { fadeOut: Number(event.target.value) },
+                        },
+                      ]).document
+                    )
+                  }
+                  className="h-1 w-full accent-[var(--beat-graph)]"
+                  aria-label={t('audio.fadeOut')}
+                />
+                <button
+                  type="button"
+                  onClick={() =>
+                    commitDocument((current) =>
+                      applyEditorOperations(current, [
+                        {
+                          type: 'update_audio',
+                          clipId: selectedClip.id,
+                          patch: { muted: !selectedClip.muted },
+                        },
+                      ]).document
+                    )
+                  }
+                  className={`h-7 rounded-md border px-2 text-[10px] transition ${
+                    selectedClip.muted
+                      ? 'border-red-400/25 bg-red-400/10 text-red-100'
+                      : 'border-white/10 text-white/50 hover:bg-white/[0.06] hover:text-white'
+                  }`}
+                >
+                  {selectedClip.muted ? t('audio.unmute') : t('audio.mute')}
+                </button>
+              </div>
+            ) : null}
+
+            <div className="max-h-56 min-h-44 overflow-auto">
+              <div className="grid min-w-[760px] grid-cols-[128px_1fr]">
+                <div className="flex h-8 items-center border-b border-r border-white/[0.07] px-3 text-[10px] font-[540] tracking-[-0.01em] text-white/36">
+                  {t('timeline.title')}
+                </div>
+                <button
+                  type="button"
+                  aria-label={t('timeline.seek')}
+                  title={t('timeline.seekHint')}
+                  onClick={(event) => {
+                    const rect = event.currentTarget.getBoundingClientRect();
+                    seekTimeline(
+                      timelineTimeFromClientX({
+                        clientX: event.clientX,
+                        left: rect.left,
+                        width: rect.width,
+                        duration: timelineDisplayDuration,
+                      })
+                    );
+                  }}
+                  className="relative h-8 border-b border-white/[0.07] bg-black/[0.08] text-left"
+                >
+                  {[0, 0.25, 0.5, 0.75, 1].map((point) => (
+                    <span
+                      key={point}
+                      className="absolute top-2 text-[9px] font-[500] tabular-nums tracking-[-0.01em] text-white/28"
+                      style={{ left: `${point * 100}%` }}
+                    >
+                      {formatTime(timelineDisplayDuration * point)}
+                    </span>
+                  ))}
+                  <span
+                    className="pointer-events-none absolute inset-y-0 z-20 w-px bg-[var(--beat-accent)]/85 shadow-[0_0_8px_rgba(255,103,0,0.4)]"
+                    style={{
+                      left: `${
+                        (timelineCurrentTime / timelineDisplayDuration) * 100
+                      }%`,
+                    }}
+                  />
+                </button>
+                {document.tracks.map((track) => (
+                  <div key={track.id} className="contents">
+                    <div className="flex h-16 items-center gap-2.5 border-b border-r border-white/[0.07] px-3 text-[11px] font-[520] text-white/55">
+                      {track.kind === 'audio' ? (
+                        <Volume2 className="size-3.5" />
+                      ) : (
+                        <FileVideo2 className="size-3.5" />
+                      )}
+                      {track.kind === 'audio'
+                        ? t('timeline.audioTrack')
+                        : t('timeline.visualTrack')}
+                    </div>
+                    <div
+                      data-timeline-track
+                      className="relative h-16 cursor-text border-b border-white/[0.07] bg-white/[0.012]"
+                      onClick={(event) => {
+                        const rect = event.currentTarget.getBoundingClientRect();
+                        seekTimeline(
+                          timelineTimeFromClientX({
+                            clientX: event.clientX,
+                            left: rect.left,
+                            width: rect.width,
+                            duration: timelineDisplayDuration,
+                          })
+                        );
+                      }}
+                    >
+                      {track.clips.map((clip) => {
+                        const displayedClip =
+                          timelineDragPreview?.id === clip.id
+                            ? { ...clip, ...timelineDragPreview }
+                            : clip;
+                        return (
+                          <TimelineClipBlock
+                            key={clip.id}
+                            clip={displayedClip}
+                            totalDuration={timelineDisplayDuration}
+                            selected={selectedClipId === clip.id}
+                            onSelect={() => selectClip(clip)}
+                            onPointerAction={(mode, event) =>
+                              beginTimelineDrag(clip, mode, event)
+                            }
+                            trimStartLabel={t('timeline.trimStart')}
+                            trimEndLabel={t('timeline.trimEnd')}
+                          />
+                        );
+                      })}
+                      {selectedClip &&
+                      (track.kind === selectedClip.sourceType ||
+                        (track.kind === 'video' &&
+                          selectedClip.sourceType === 'image')) ? (
+                        <span
+                          className="pointer-events-none absolute inset-y-0 z-20 w-px bg-white shadow-[0_0_0_1px_rgba(0,0,0,0.35)]"
+                          style={{
+                            left: `${
+                              (timelineCurrentTime / timelineDisplayDuration) *
+                              100
+                            }%`,
+                          }}
+                        />
+                      ) : null}
+                    </div>
+                  </div>
+                ))}
+              </div>
+            </div>
+          </div>
+        </section>
+      </div>
+
+      {error ? (
+        <div className="absolute bottom-4 left-1/2 z-50 max-w-lg -translate-x-1/2 rounded-xl border border-red-400/25 bg-red-950/90 px-4 py-3 text-xs text-red-100 shadow-2xl backdrop-blur">
+          {error}
+        </div>
+      ) : null}
+    </div>
+  );
+}
diff --git a/src/config/database-defaults.test.ts b/src/config/database-defaults.test.ts
new file mode 100644
index 0000000..1d05310
--- /dev/null
+++ b/src/config/database-defaults.test.ts
@@ -0,0 +1,18 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+
+test('Drizzle and the runtime use the same default local SQLite database', () => {
+  const runtimeConfig = readFileSync(
+    new URL('./index.ts', import.meta.url),
+    'utf8'
+  );
+  const drizzleConfig = readFileSync(
+    new URL('../../drizzle.config.ts', import.meta.url),
+    'utf8'
+  );
+
+  assert.match(runtimeConfig, /file:data\/workspace\.db/);
+  assert.match(drizzleConfig, /file:data\/workspace\.db/);
+  assert.doesNotMatch(drizzleConfig, /file:data\/local\.db/);
+});
diff --git a/src/config/db/schema.sqlite.ts b/src/config/db/schema.sqlite.ts
index 641b855..4c8a96b 100644
--- a/src/config/db/schema.sqlite.ts
+++ b/src/config/db/schema.sqlite.ts
@@ -233,6 +233,47 @@ export const projectCanvasState = sqliteTable(
   (table) => [index('project_canvas_state_updated_at_idx').on(table.updatedAt)]
 );
 
+export const projectTimelineState = sqliteTable(
+  'project_timeline_state',
+  {
+    projectId: text('project_id')
+      .primaryKey()
+      .references(() => project.id, { onDelete: 'cascade' }),
+    documentJson: jsonText('document_json').notNull(),
+    version: integer('version').notNull().default(1),
+    updatedAt: integer('updated_at', { mode: 'timestamp_ms' })
+      .default(sqliteNowMs)
+      .notNull(),
+  },
+  (table) => [index('project_timeline_state_updated_at_idx').on(table.updatedAt)]
+);
+
+export const projectCommandReceipt = sqliteTable(
+  'project_command_receipt',
+  {
+    id: text('id').primaryKey(),
+    projectId: text('project_id')
+      .notNull()
+      .references(() => project.id, { onDelete: 'cascade' }),
+    idempotencyKey: text('idempotency_key').notNull(),
+    commandId: text('command_id').notNull(),
+    origin: text('origin').notNull(),
+    commandType: text('command_type').notNull(),
+    resultJson: jsonText('result_json').notNull(),
+    createdAt: integer('created_at', { mode: 'timestamp_ms' })
+      .default(sqliteNowMs)
+      .notNull(),
+  },
+  (table) => [
+    index('project_command_receipt_project_idx').on(table.projectId),
+    index('project_command_receipt_command_idx').on(table.commandId),
+    uniqueIndex('project_command_receipt_idempotency_unique').on(
+      table.projectId,
+      table.idempotencyKey
+    ),
+  ]
+);
+
 export const projectWorkflowState = sqliteTable(
   'project_workflow_state',
   {
@@ -302,6 +343,8 @@ export const projectAssetMembership = sqliteTable(
 export type Config = typeof config.$inferSelect;
 export type Project = typeof project.$inferSelect;
 export type NewProject = typeof project.$inferInsert;
+export type ProjectTimelineState = typeof projectTimelineState.$inferSelect;
+export type ProjectCommandReceipt = typeof projectCommandReceipt.$inferSelect;
 export type Asset = typeof userAsset.$inferSelect;
 export type NewAsset = typeof userAsset.$inferInsert;
 export type Generation = typeof generationHistory.$inferSelect;
diff --git a/src/config/generation-providers.ts b/src/config/generation-providers.ts
new file mode 100644
index 0000000..ff328d4
--- /dev/null
+++ b/src/config/generation-providers.ts
@@ -0,0 +1,12 @@
+import type { GenerationProviderRegistrar } from '@/core/generation-providers/contracts';
+
+/**
+ * Source-level extension point for open-source forks.
+ *
+ * BeatAPI is registered by the core and remains the default. A fork can add a
+ * provider implementation here, then set GENERATION_PROVIDER to its id. Keep
+ * credentials inside that provider's server-only implementation.
+ */
+export function registerProjectGenerationProviders(
+  _register: GenerationProviderRegistrar
+) {}
diff --git a/src/config/index.ts b/src/config/index.ts
index e808aef..17262d9 100644
--- a/src/config/index.ts
+++ b/src/config/index.ts
@@ -12,7 +12,10 @@ export const envConfigs: Record<string, string> = {
     publicEnv('VITE_APP_DESCRIPTION') ??
     'The open-source, local-first AI canvas for image and video creation.',
   app_logo: publicEnv('VITE_APP_LOGO') ?? '/logo.png',
-  generation_provider: publicEnv('VITE_GENERATION_PROVIDER') ?? 'beatapi',
+  generation_provider:
+    procEnv.GENERATION_PROVIDER ??
+    publicEnv('VITE_GENERATION_PROVIDER') ??
+    'beatapi',
 
   database_provider: procEnv.DATABASE_PROVIDER ?? 'sqlite',
   database_url: procEnv.DATABASE_URL ?? 'file:data/workspace.db',
diff --git a/src/config/workspace-modes.test.ts b/src/config/workspace-modes.test.ts
index e79ff13..6a850fd 100644
--- a/src/config/workspace-modes.test.ts
+++ b/src/config/workspace-modes.test.ts
@@ -3,10 +3,11 @@ import test from 'node:test';
 
 import { resolveWorkspaceMode, workspaceModes } from './workspace-modes';
 
-test('workspace modes expose Studio, Canvas, and Assets', () => {
-  assert.deepEqual(workspaceModes, ['studio', 'canvas', 'assets']);
+test('workspace modes expose Studio, Canvas, Edit, and Assets', () => {
+  assert.deepEqual(workspaceModes, ['studio', 'canvas', 'editor', 'assets']);
   assert.equal(resolveWorkspaceMode('studio'), 'studio');
   assert.equal(resolveWorkspaceMode('canvas'), 'canvas');
+  assert.equal(resolveWorkspaceMode('editor'), 'editor');
   assert.equal(resolveWorkspaceMode('assets'), 'assets');
   assert.equal(resolveWorkspaceMode('unknown'), 'canvas');
   assert.equal(resolveWorkspaceMode(undefined), 'canvas');
diff --git a/src/config/workspace-modes.ts b/src/config/workspace-modes.ts
index ffe6d5f..c0ed749 100644
--- a/src/config/workspace-modes.ts
+++ b/src/config/workspace-modes.ts
@@ -1,4 +1,4 @@
-export const workspaceModes = ['studio', 'canvas', 'assets'] as const;
+export const workspaceModes = ['studio', 'canvas', 'editor', 'assets'] as const;
 
 export type WorkspaceMode = (typeof workspaceModes)[number];
 
@@ -12,6 +12,7 @@ export function resolveWorkspaceMode(value?: string | null): WorkspaceMode {
 
 export function workspaceModePath(mode: WorkspaceMode) {
   if (mode === 'studio') return '/studio';
+  if (mode === 'editor') return '/editor';
   if (mode === 'assets') return '/assets';
   return '/canvas';
 }
diff --git a/src/core/adapters/adapter-factory.ts b/src/core/adapters/adapter-factory.ts
index db1da8c..b536f2a 100644
--- a/src/core/adapters/adapter-factory.ts
+++ b/src/core/adapters/adapter-factory.ts
@@ -1,14 +1,10 @@
-import { BeatApiAdapter } from './beatapi-adapter';
-import { MockAdapter } from './mock-adapter';
+import { getGenerationProvider } from '@/core/generation-providers';
 import type { EffectRecord } from './base-adapter';
 
 export const createAdapter = (effect: EffectRecord) => {
-  switch (effect.provider) {
-    case 'beatapi':
-      return new BeatApiAdapter(effect);
-    case 'mock':
-      return new MockAdapter(effect);
-    default:
-      throw new Error(`Unsupported generation provider: ${effect.provider}`);
+  const provider = getGenerationProvider(effect.provider);
+  if (!provider) {
+    throw new Error(`Unsupported generation provider: ${effect.provider}`);
   }
+  return provider.createAdapter(effect);
 };
diff --git a/src/core/adapters/beatapi-adapter.ts b/src/core/adapters/beatapi-adapter.ts
index 4b848c6..48ef889 100644
--- a/src/core/adapters/beatapi-adapter.ts
+++ b/src/core/adapters/beatapi-adapter.ts
@@ -57,6 +57,25 @@ const inputSchema = z.object({
   backgroundSource: z.enum(['input_image', 'input_video']).optional(),
 });
 
+export const validateBeatApiTaskInput = ({
+  effectType,
+  model,
+  input,
+}: {
+  effectType: number;
+  model: string;
+  input: Record<string, unknown>;
+}) => {
+  const unknownKeys = Object.keys(input).filter(
+    (key) => !(key in inputSchema.shape)
+  );
+  if (unknownKeys.length > 0) {
+    throw new Error(`Unsupported model parameters: ${unknownKeys.join(', ')}`);
+  }
+  const parsed = inputSchema.parse(input);
+  return buildBeatApiTaskRequest({ effectType, model, input: parsed });
+};
+
 type BeatApiMedia = {
   type?: unknown;
   url?: unknown;
diff --git a/src/core/beatcanvas/canvas-types.ts b/src/core/beatcanvas/canvas-types.ts
index 91f56b4..d94f027 100644
--- a/src/core/beatcanvas/canvas-types.ts
+++ b/src/core/beatcanvas/canvas-types.ts
@@ -12,6 +12,7 @@ import type {
 import type { VideoAnalysisDepth } from '@/core/effects/video-analysis';
 
 export type CanvasCardMediaType = 'image' | 'video';
+export type CanvasAssetMediaType = CanvasCardMediaType | 'audio' | 'timeline';
 export type CanvasGenerationMode = CanvasCardMediaType | 'analysis';
 export type CanvasCardKind = 'asset' | 'generation' | 'output';
 export type CanvasCardStatus =
@@ -21,11 +22,11 @@ export type CanvasCardStatus =
   | 'succeeded'
   | 'failed';
 
-export type CanvasCard = {
+type CanvasCardBase = {
   id: string;
   assetId?: string | null;
   kind: CanvasCardKind;
-  type: CanvasCardMediaType;
+  type: CanvasAssetMediaType;
   generationMode?: CanvasGenerationMode;
   analysisDepth?: VideoAnalysisDepth;
   name: string;
@@ -52,10 +53,16 @@ export type CanvasCard = {
   generationSnapshot?: CanvasGenerationSnapshot | null;
   /** Generation card: output card id whose result is pinned on the node. */
   pinnedOutputId?: string | null;
+  audioRole?: 'music' | 'voice' | 'sound_effect' | 'source_audio' | 'reference';
+  durationSec?: number | null;
+  waveformPeaks?: number[];
+  timelineId?: string | null;
+  clipCount?: number | null;
+  lastRenderAssetId?: string | null;
 };
 
 export type CanvasGenerationSnapshot = Pick<
-  CanvasCard,
+  CanvasCardBase,
   | 'type'
   | 'generationMode'
   | 'analysisDepth'
@@ -74,20 +81,33 @@ export type CanvasGenerationSnapshot = Pick<
   | 'backgroundSource'
   | 'resultText'
 > & {
+  type: CanvasCardMediaType;
   capturedAt: string;
 };
 
-export type CanvasGenerationCard = CanvasCard & {
+export type CanvasAssetCard = CanvasCardBase & {
+  kind: 'asset';
+  type: CanvasAssetMediaType;
+};
+
+export type CanvasGenerationCard = CanvasCardBase & {
   kind: 'generation';
+  type: CanvasCardMediaType;
 };
 
-export type CanvasOutputCard = CanvasCard & {
+export type CanvasOutputCard = CanvasCardBase & {
   kind: 'output';
+  type: CanvasCardMediaType;
   sourceConfigCardId: string;
   generationRunId: string;
   generationSnapshot: CanvasGenerationSnapshot;
 };
 
+export type CanvasCard =
+  | CanvasAssetCard
+  | CanvasGenerationCard
+  | CanvasOutputCard;
+
 export const isCanvasGenerationCard = (
   card: CanvasCard | null | undefined
 ): card is CanvasGenerationCard => card?.kind === 'generation';
@@ -104,7 +124,9 @@ export type CanvasDraftCard = CanvasGenerationCard;
 
 export const getCanvasGenerationMode = (
   card: Pick<CanvasCard, 'type' | 'generationMode'>
-): CanvasGenerationMode => card.generationMode ?? card.type;
+): CanvasGenerationMode =>
+  card.generationMode ??
+  (card.type === 'image' || card.type === 'video' ? card.type : 'video');
 
 export const isCanvasAnalysisCard = (
   card: CanvasCard | null | undefined
diff --git a/src/core/beatcanvas/composer-references.test.ts b/src/core/beatcanvas/composer-references.test.ts
index 0990436..0011120 100644
--- a/src/core/beatcanvas/composer-references.test.ts
+++ b/src/core/beatcanvas/composer-references.test.ts
@@ -49,7 +49,7 @@ const makeCard = (
   quality: 'standard',
   sourceGenerationId: null,
   ...overrides,
-});
+}) as CanvasCard;
 
 const makeDraft = (): CanvasGenerationCard => ({
   ...makeCard({
@@ -60,7 +60,7 @@ const makeDraft = (): CanvasGenerationCard => ({
     modelId: 'model-1',
   }),
   kind: 'generation',
-});
+}) as CanvasGenerationCard;
 
 test('Composer stops offering @Image references at the model limit', () => {
   const first = makeCard({ id: 'image-1' });
diff --git a/src/core/beatcanvas/composer.ts b/src/core/beatcanvas/composer.ts
index c17f178..7bf0ce1 100644
--- a/src/core/beatcanvas/composer.ts
+++ b/src/core/beatcanvas/composer.ts
@@ -296,7 +296,11 @@ export const canUseCanvasCardAsGenerationReference = ({
     return true;
   }
 
-  return targetType === 'video' && targetModel?.supportsSourceVideo === true;
+  return (
+    sourceCard.type === 'video' &&
+    targetType === 'video' &&
+    targetModel?.supportsSourceVideo === true
+  );
 };
 
 export const listCompatibleCanvasReferenceCards = ({
@@ -320,8 +324,13 @@ export const listCompatibleCanvasReferenceCards = ({
     0
   );
 
-  return Object.values(cards).filter((card): card is CanvasCard => {
-    if (!card || card.id === draftCard.id) {
+  return Object.values(cards).filter(
+    (card): card is CanvasCard & { type: CanvasCardMediaType } => {
+    if (
+      !card ||
+      (card.type !== 'image' && card.type !== 'video') ||
+      card.id === draftCard.id
+    ) {
       return false;
     }
 
@@ -357,7 +366,8 @@ export const listCompatibleCanvasReferenceCards = ({
       targetModel: model,
       targetGenerationMode: draftCard.generationMode,
     });
-  });
+    }
+  );
 };
 
 export const removeReferenceCardId = (
diff --git a/src/core/beatcanvas/generation-controller-motion-control.test.ts b/src/core/beatcanvas/generation-controller-motion-control.test.ts
index c667bd4..26fc7bd 100644
--- a/src/core/beatcanvas/generation-controller-motion-control.test.ts
+++ b/src/core/beatcanvas/generation-controller-motion-control.test.ts
@@ -30,7 +30,7 @@ const makeCard = (overrides: Partial<CanvasCard>): CanvasCard => ({
   quality: 'standard',
   sourceGenerationId: null,
   ...overrides,
-});
+}) as CanvasCard;
 
 test('Canvas Motion Control controls reach the BeatAPI provider request', async () => {
   const model = findWorkspaceModelOption(
diff --git a/src/core/beatcanvas/generation-controller-video-analysis.test.ts b/src/core/beatcanvas/generation-controller-video-analysis.test.ts
index 9ae4dd1..cd694a3 100644
--- a/src/core/beatcanvas/generation-controller-video-analysis.test.ts
+++ b/src/core/beatcanvas/generation-controller-video-analysis.test.ts
@@ -28,7 +28,7 @@ const makeCard = (overrides: Partial<CanvasCard>): CanvasCard => ({
   quality: 'standard',
   sourceGenerationId: null,
   ...overrides,
-});
+}) as CanvasCard;
 
 test('Canvas video analysis uses the same BeatAPI contract as Studio', async () => {
   const video = makeCard({ id: 'video-1' });
diff --git a/src/core/beatcanvas/generation-controller.ts b/src/core/beatcanvas/generation-controller.ts
index e9a37af..b50abe4 100644
--- a/src/core/beatcanvas/generation-controller.ts
+++ b/src/core/beatcanvas/generation-controller.ts
@@ -26,6 +26,10 @@ import {
   findWorkspaceModelOption,
   type WorkspaceModelOption,
 } from '@/core/effects/workspace-models';
+import {
+  buildAssetFirstReferencesFromCanvasCards,
+  normalizeAssetFirstGenerationRequest,
+} from '@/core/commands/generation-contract';
 import {
   type CanvasCard,
   type CanvasCardMediaType,
@@ -156,13 +160,18 @@ export const loadVideoDurationSeconds = (
 
 export const toWorkflowReferenceCard = (
   card: CanvasCard
-): WorkflowReferenceCard => ({
-  id: card.id,
-  name: card.name,
-  type: card.type,
-  url: card.url ?? '',
-  role: 'asset',
-});
+): WorkflowReferenceCard => {
+  if (card.type !== 'image' && card.type !== 'video') {
+    throw new Error('Only image and video cards can be generation references');
+  }
+  return {
+    id: card.id,
+    name: card.name,
+    type: card.type,
+    url: card.url ?? '',
+    role: 'asset',
+  };
+};
 
 export const getSelectableModel = (
   models: WorkspaceModelOption[],
@@ -299,7 +308,10 @@ export const buildGenerationEffectInput = async ({
   const referenceCards = draftCard.referenceCardIds
     .map((cardId) => canvasCards[cardId])
     .flatMap((card) => {
-      if (!card?.url) return [];
+      if (
+        !card?.url ||
+        (card.type !== 'image' && card.type !== 'video')
+      ) return [];
       const providerUrl = referenceUrlOverrides[card.id] ?? card.url;
       if (isLocalWorkspaceMediaUrl(providerUrl)) return [];
       return [
@@ -686,11 +698,55 @@ export const runDraftGeneration = async ({
     });
     setStatusMessage(translate('messages.submittingRequest'));
 
+    const submittedCard = getCurrentCard(draftId);
+    const generation =
+      projectId && isCanvasDraftCard(submittedCard)
+        ? normalizeAssetFirstGenerationRequest({
+            version: 1,
+            projectId,
+            mode: isCanvasAnalysisCard(submittedCard)
+              ? 'analysis'
+              : submittedCard.type,
+            modelId: submittedCard.modelId || model.id,
+            prompt: submittedCard.prompt,
+            references: buildAssetFirstReferencesFromCanvasCards({
+              cards: Object.fromEntries(
+                submittedCard.referenceCardIds.flatMap((cardId) => {
+                  const card = getCurrentCard(cardId);
+                  return card ? [[cardId, card]] : [];
+                })
+              ),
+              referenceCardIds: submittedCard.referenceCardIds,
+              mode: isCanvasAnalysisCard(submittedCard)
+                ? 'analysis'
+                : submittedCard.type,
+              deliveryUrlsByCardId: referenceUrlOverrides,
+            }),
+            parameters: Object.fromEntries(
+              Object.entries(input).filter(
+                ([key]) =>
+                  ![
+                    'prompt',
+                    'image_url',
+                    'image_urls',
+                    'video_url',
+                    'video_urls',
+                    'audio_url',
+                    'audio_urls',
+                    'first_frame',
+                    'last_frame',
+                  ].includes(key)
+              )
+            ),
+          })
+        : undefined;
+
     const response = await generateEffectImpl({
       effectId,
       input,
       projectId,
       generationIntentToken,
+      generation,
     });
     if (!response.ok) {
       throw new GenerationFailure(
diff --git a/src/core/beatcanvas/generation-history.test.ts b/src/core/beatcanvas/generation-history.test.ts
index 482d990..028242a 100644
--- a/src/core/beatcanvas/generation-history.test.ts
+++ b/src/core/beatcanvas/generation-history.test.ts
@@ -5,6 +5,7 @@ import type { CanvasCard, CanvasOutputCard } from './canvas-types';
 import {
   buildGenerationTakes,
   listGenerationOutputsForDraft,
+  resolveConcreteCanvasMediaCard,
   resolvePinnedGenerationOutputId,
 } from './generation-history';
 
@@ -49,6 +50,41 @@ const makeOutput = (
   },
 });
 
+test('resolves a generation node to its pinned concrete output asset', () => {
+  const older = makeOutput('output-old', '2026-08-16T00:00:00.000Z');
+  const newer = makeOutput('output-new', '2026-08-16T00:02:00.000Z');
+  const draft: CanvasCard = {
+    id: 'draft-1',
+    kind: 'generation',
+    type: 'image',
+    name: 'Image generation',
+    url: newer.url,
+    prompt: 'A product shot',
+    referenceCardIds: [],
+    workflowTemplateId: null,
+    status: 'idle',
+    error: null,
+    modelId: 'model',
+    aspectRatio: '1:1',
+    outputQuality: '1k',
+    duration: '5s',
+    mode: 'quality',
+    variant: 'standard',
+    quality: 'standard',
+    sourceGenerationId: null,
+    pinnedOutputId: older.id,
+  };
+  const cards = {
+    [draft.id]: draft,
+    [older.id]: older,
+    [newer.id]: newer,
+  };
+  assert.equal(
+    resolveConcreteCanvasMediaCard({ cards, card: draft })?.id,
+    older.id
+  );
+});
+
 test('lists draft outputs newest first and ignores other drafts', () => {
   const older = makeOutput('output-old', '2026-08-16T00:00:00.000Z');
   const newer = makeOutput('output-new', '2026-08-16T00:02:00.000Z');
diff --git a/src/core/beatcanvas/generation-history.ts b/src/core/beatcanvas/generation-history.ts
index 072dbdf..6cc7fbd 100644
--- a/src/core/beatcanvas/generation-history.ts
+++ b/src/core/beatcanvas/generation-history.ts
@@ -88,3 +88,20 @@ export const buildGenerationTakes = ({
     isPinned: output.id === resolvedPinnedId,
   }));
 };
+
+export const resolveConcreteCanvasMediaCard = ({
+  cards,
+  card,
+}: {
+  cards: Record<string, CanvasCard | undefined>;
+  card: CanvasCard | null | undefined;
+}): CanvasCard | null => {
+  if (!card) return null;
+  if (card.kind !== 'generation') return card;
+  const outputs = listGenerationOutputsForDraft(cards, card.id);
+  const outputId = resolvePinnedGenerationOutputId({
+    outputs,
+    pinnedOutputId: card.pinnedOutputId,
+  });
+  return (outputId ? cards[outputId] : null) ?? (card.url ? card : null);
+};
diff --git a/src/core/beatcanvas/project-asset-transfer.test.ts b/src/core/beatcanvas/project-asset-transfer.test.ts
index 9e7c131..107b5c5 100644
--- a/src/core/beatcanvas/project-asset-transfer.test.ts
+++ b/src/core/beatcanvas/project-asset-transfer.test.ts
@@ -28,10 +28,9 @@ test('parses a project image transfer and keeps its project scope', () => {
   assert.equal(parsed?.mediaType, 'image');
 });
 
-test('rejects malformed and unsupported project asset transfers', () => {
+test('accepts audio transfers and rejects malformed project asset transfers', () => {
   assert.equal(parseProjectAssetTransfer('not-json'), null);
-  assert.equal(
-    parseProjectAssetTransfer(
+  const audio = parseProjectAssetTransfer(
       JSON.stringify({
         id: 'asset-1',
         projectId: 'project-1',
@@ -39,10 +38,11 @@ test('rejects malformed and unsupported project asset transfers', () => {
         mediaType: 'audio',
         width: null,
         height: null,
+        mimeType: 'audio/mpeg',
       })
-    ),
-    null
   );
+  assert.equal(audio?.mediaType, 'audio');
+  assert.deepEqual(getProjectAssetCardSize(audio!), { w: 320, h: 104 });
 });
 
 test('recognizes the custom drag type and preserves media aspect ratio', () => {
diff --git a/src/core/beatcanvas/project-asset-transfer.ts b/src/core/beatcanvas/project-asset-transfer.ts
index d287e38..891790f 100644
--- a/src/core/beatcanvas/project-asset-transfer.ts
+++ b/src/core/beatcanvas/project-asset-transfer.ts
@@ -5,7 +5,7 @@ export const PROJECT_ASSET_DRAG_MIME =
 export const PROJECT_ASSET_INSERT_EVENT = 'beatapi:project-asset-insert';
 
 export type ProjectAssetTransfer = RecentAsset & {
-  mediaType: 'image' | 'video';
+  mediaType: 'image' | 'video' | 'audio';
   projectId: string;
 };
 
@@ -26,7 +26,9 @@ export function parseProjectAssetTransfer(
       typeof parsed.id !== 'string' ||
       typeof parsed.projectId !== 'string' ||
       typeof parsed.publicUrl !== 'string' ||
-      (parsed.mediaType !== 'image' && parsed.mediaType !== 'video') ||
+      (parsed.mediaType !== 'image' &&
+        parsed.mediaType !== 'video' &&
+        parsed.mediaType !== 'audio') ||
       !isFiniteNullableNumber(parsed.width) ||
       !isFiniteNullableNumber(parsed.height)
     ) {
@@ -52,6 +54,15 @@ export function parseProjectAssetTransfer(
         typeof parsed.createdAt === 'string' || parsed.createdAt instanceof Date
           ? parsed.createdAt
           : new Date(0).toISOString(),
+      mimeType:
+        typeof parsed.mimeType === 'string' || parsed.mimeType === null
+          ? parsed.mimeType
+          : null,
+      assetClass:
+        typeof parsed.assetClass === 'string' || parsed.assetClass === null
+          ? parsed.assetClass
+          : null,
+      metadata: parsed.metadata,
     };
   } catch {
     return null;
@@ -66,6 +77,9 @@ export function getProjectAssetCardSize(asset: RecentAsset): {
   w: number;
   h: number;
 } {
+  if (asset.mimeType?.startsWith('audio/')) {
+    return { w: 320, h: 104 };
+  }
   if (
     asset.width &&
     asset.height &&
diff --git a/src/core/beatcanvas/reference-mentions.ts b/src/core/beatcanvas/reference-mentions.ts
index a076e1e..81861e7 100644
--- a/src/core/beatcanvas/reference-mentions.ts
+++ b/src/core/beatcanvas/reference-mentions.ts
@@ -38,7 +38,7 @@ export const buildCanvasReferenceMentions = ({
 
   return referenceCardIds.flatMap((cardId) => {
     const card = cards[cardId];
-    if (!card) return [];
+    if (!card || (card.type !== 'image' && card.type !== 'video')) return [];
 
     counts[card.type] += 1;
     const index = counts[card.type];
diff --git a/src/core/beatcanvas/upload-layout.test.ts b/src/core/beatcanvas/upload-layout.test.ts
new file mode 100644
index 0000000..51ab31a
--- /dev/null
+++ b/src/core/beatcanvas/upload-layout.test.ts
@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { resolveNonOverlappingPlacement } from './upload-layout';
+
+test('shifts a new card off an occupied canvas frame', () => {
+  const next = resolveNonOverlappingPlacement({
+    x: 0,
+    y: 0,
+    w: 200,
+    h: 360,
+    occupied: [{ x: 0, y: 0, w: 200, h: 360 }],
+  });
+  assert.equal(next.y, 0);
+  assert.ok(next.x >= 200);
+});
+
+test('stacks later cards beside earlier occupied frames', () => {
+  const first = { x: 80, y: 80, w: 360, h: 260 };
+  const secondPoint = resolveNonOverlappingPlacement({
+    ...first,
+    occupied: [first],
+  });
+  const second = { ...first, ...secondPoint };
+  const thirdPoint = resolveNonOverlappingPlacement({
+    ...first,
+    occupied: [first, second],
+  });
+  assert.notEqual(secondPoint.x, first.x);
+  assert.notEqual(thirdPoint.x, first.x);
+  assert.notEqual(thirdPoint.x, secondPoint.x);
+});
diff --git a/src/core/beatcanvas/upload-layout.ts b/src/core/beatcanvas/upload-layout.ts
index 5972f06..f87a275 100644
--- a/src/core/beatcanvas/upload-layout.ts
+++ b/src/core/beatcanvas/upload-layout.ts
@@ -1,6 +1,57 @@
 export const CANVAS_BATCH_UPLOAD_GAP = 48;
 export const CANVAS_BATCH_UPLOAD_COLUMNS = 3;
 
+export type CanvasOccupiedFrame = {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+};
+
+const framesOverlap = (
+  left: CanvasOccupiedFrame,
+  right: CanvasOccupiedFrame,
+  gap: number
+) =>
+  left.x < right.x + right.w + gap &&
+  left.x + left.w + gap > right.x &&
+  left.y < right.y + right.h + gap &&
+  left.y + left.h + gap > right.y;
+
+export const resolveNonOverlappingPlacement = ({
+  x,
+  y,
+  w,
+  h,
+  occupied,
+  gap = CANVAS_BATCH_UPLOAD_GAP,
+}: {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  occupied: CanvasOccupiedFrame[];
+  gap?: number;
+}) => {
+  let next = { x, y, w, h };
+  for (let attempt = 0; attempt < 48; attempt += 1) {
+    if (!occupied.some((frame) => framesOverlap(next, frame, gap))) {
+      return { x: next.x, y: next.y };
+    }
+    next = {
+      ...next,
+      x: next.x + w + gap,
+      y: attempt > 0 && attempt % CANVAS_BATCH_UPLOAD_COLUMNS === 0
+        ? next.y + h + gap
+        : next.y,
+    };
+    if (attempt > 0 && attempt % CANVAS_BATCH_UPLOAD_COLUMNS === 0) {
+      next.x = x;
+    }
+  }
+  return { x: next.x, y: next.y };
+};
+
 export const resolveCanvasBatchOffset = (
   index: number,
   size: { w: number; h: number } = { w: 360, h: 360 }
diff --git a/src/core/commands/asset-boundary.ts b/src/core/commands/asset-boundary.ts
new file mode 100644
index 0000000..9c7a2c2
--- /dev/null
+++ b/src/core/commands/asset-boundary.ts
@@ -0,0 +1,160 @@
+import { getProjectAssetById } from '@/core/workspace-lib/assets/user-assets';
+
+import { BeatDesignCommandError } from './contracts';
+import type { BeatDesignCommand } from './executor';
+
+type ProjectAsset = NonNullable<
+  Awaited<ReturnType<typeof getProjectAssetById>>
+>;
+
+const loadCommandAsset = async ({
+  projectId,
+  assetId,
+  expectedType,
+}: {
+  projectId: string;
+  assetId: string;
+  expectedType?: 'image' | 'video' | 'audio';
+}): Promise<ProjectAsset> => {
+  const asset = await getProjectAssetById({ projectId, assetId });
+  if (!asset) {
+    throw new BeatDesignCommandError(
+      'NOT_FOUND',
+      `Asset ${assetId} does not belong to this project.`
+    );
+  }
+  if (expectedType && asset.type !== expectedType) {
+    throw new BeatDesignCommandError(
+      'INVALID_COMMAND',
+      `Asset ${assetId} is not a ${expectedType} asset.`
+    );
+  }
+  return asset;
+};
+
+export async function normalizeCommandAssetReferences({
+  projectId,
+  command,
+}: {
+  projectId: string;
+  command: BeatDesignCommand;
+}): Promise<BeatDesignCommand> {
+  if (command.type === 'editor.validate') return command;
+
+  if (command.type === 'canvas.apply') {
+    return {
+      ...command,
+      operations: await Promise.all(
+        command.operations.map(async (operation) => {
+          if (operation.type === 'upsert_card' && operation.card.assetId) {
+            const expectedType =
+              operation.card.type === 'timeline'
+                ? 'video'
+                : operation.card.type;
+            const asset = await loadCommandAsset({
+              projectId,
+              assetId: operation.card.assetId,
+              expectedType,
+            });
+            return {
+              ...operation,
+              card: { ...operation.card, url: asset.publicUrl },
+            };
+          }
+          if (
+            operation.type === 'upsert_timeline_node' &&
+            operation.lastRenderAssetId
+          ) {
+            const asset = await loadCommandAsset({
+              projectId,
+              assetId: operation.lastRenderAssetId,
+              expectedType: 'video',
+            });
+            return { ...operation, lastRenderUrl: asset.publicUrl };
+          }
+          return operation;
+        })
+      ),
+    };
+  }
+
+  if (command.type === 'editor.replace_document') {
+    const tracks = await Promise.all(
+      command.document.tracks.map(async (track) => ({
+        ...track,
+        clips: await Promise.all(
+          track.clips.map(async (clip) => {
+            const sourceAsset = await loadCommandAsset({
+              projectId,
+              assetId: clip.assetId,
+              expectedType: clip.sourceType,
+            });
+            return {
+              ...clip,
+              sourceUrl: sourceAsset.publicUrl,
+              takes: await Promise.all(
+                clip.takes.map(async (take) => {
+                  const takeAsset = await loadCommandAsset({
+                    projectId,
+                    assetId: take.assetId,
+                    expectedType: 'video',
+                  });
+                  return { ...take, sourceUrl: takeAsset.publicUrl };
+                })
+              ),
+            };
+          })
+        ),
+      }))
+    );
+    let lastRenderUrl = command.document.lastRenderUrl;
+    if (command.document.lastRenderAssetId) {
+      const renderAsset = await loadCommandAsset({
+        projectId,
+        assetId: command.document.lastRenderAssetId,
+        expectedType: 'video',
+      });
+      lastRenderUrl = renderAsset.publicUrl;
+    }
+    return {
+      ...command,
+      document: { ...command.document, tracks, lastRenderUrl },
+    };
+  }
+
+  return {
+    ...command,
+    operations: await Promise.all(
+      command.operations.map(async (operation) => {
+        if (operation.type === 'add_clip') {
+          const asset = await loadCommandAsset({
+            projectId,
+            assetId: operation.assetId,
+            expectedType: operation.sourceType,
+          });
+          return { ...operation, sourceUrl: asset.publicUrl };
+        }
+        if (operation.type === 'add_take') {
+          const asset = await loadCommandAsset({
+            projectId,
+            assetId: operation.take.assetId,
+            expectedType: 'video',
+          });
+          return {
+            ...operation,
+            take: { ...operation.take, sourceUrl: asset.publicUrl },
+          };
+        }
+        if (operation.type === 'set_render') {
+          const asset = await loadCommandAsset({
+            projectId,
+            assetId: operation.assetId,
+            expectedType: 'video',
+          });
+          return { ...operation, publicUrl: asset.publicUrl };
+        }
+        return operation;
+      })
+    ),
+  };
+}
diff --git a/src/core/commands/canvas-card-repair.ts b/src/core/commands/canvas-card-repair.ts
new file mode 100644
index 0000000..396a880
--- /dev/null
+++ b/src/core/commands/canvas-card-repair.ts
@@ -0,0 +1,143 @@
+import { normalizeProjectSnapshotCard } from '@/core/projects/project-snapshot';
+
+const ASPECT_RATIOS = new Set([
+  '16:9',
+  '21:9',
+  '4:3',
+  '5:4',
+  '9:16',
+  '9:21',
+  '3:4',
+  '1:1',
+  '1:2',
+  '2:1',
+  '1:3',
+  '3:1',
+  '2:3',
+  '3:2',
+  '4:5',
+  'auto',
+  'adaptive',
+  'landscape',
+  'portrait',
+]);
+const OUTPUT_QUALITIES = new Set([
+  '1k',
+  '2k',
+  '480p',
+  '720p',
+  '768p',
+  '1080p',
+  '4k',
+  'std',
+  'pro',
+]);
+const STATUSES = new Set([
+  'idle',
+  'pending',
+  'processing',
+  'succeeded',
+  'failed',
+]);
+const MODES = new Set(['quality', 'fast', 'lite']);
+const VARIANTS = new Set(['standard', 'pro']);
+const QUALITIES = new Set(['standard', 'high', 'low', 'medium']);
+const LANGUAGES = new Set(['zh', 'en']);
+
+const pick = (value: unknown, allowed: Set<string>, fallback: string) =>
+  typeof value === 'string' && allowed.has(value) ? value : fallback;
+
+const optionalPick = (value: unknown, allowed: Set<string>) =>
+  typeof value === 'string' && allowed.has(value) ? value : undefined;
+
+export const coerceCanvasDuration = (value: unknown) => {
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+    return `${value}s`;
+  }
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (/^\d+(?:\.\d+)?s$/.test(trimmed)) return trimmed;
+    const parsed = Number.parseFloat(trimmed);
+    if (Number.isFinite(parsed) && parsed > 0) return `${parsed}s`;
+  }
+  return '5s';
+};
+
+export function repairCanvasCardInput(value: unknown) {
+  const card = normalizeProjectSnapshotCard(value);
+  if (!card) return value;
+  const duration = coerceCanvasDuration(card.duration);
+  const name = card.name.trim() || 'Untitled';
+  const language = optionalPick(card.language, LANGUAGES);
+  const generationSnapshot = card.generationSnapshot
+    ? {
+        type: card.generationSnapshot.type === 'video' ? 'video' : 'image',
+        generationMode: card.generationSnapshot.generationMode,
+        analysisDepth: card.generationSnapshot.analysisDepth,
+        prompt: card.generationSnapshot.prompt,
+        referenceCardIds: card.generationSnapshot.referenceCardIds,
+        workflowTemplateId: card.generationSnapshot.workflowTemplateId,
+        modelId: card.generationSnapshot.modelId,
+        aspectRatio: pick(
+          card.generationSnapshot.aspectRatio,
+          ASPECT_RATIOS,
+          '1:1'
+        ),
+        outputQuality: pick(
+          card.generationSnapshot.outputQuality,
+          OUTPUT_QUALITIES,
+          '1k'
+        ),
+        duration: coerceCanvasDuration(card.generationSnapshot.duration),
+        language: optionalPick(card.generationSnapshot.language, LANGUAGES),
+        mode: pick(card.generationSnapshot.mode, MODES, 'quality'),
+        variant: pick(card.generationSnapshot.variant, VARIANTS, 'standard'),
+        quality: pick(card.generationSnapshot.quality, QUALITIES, 'standard'),
+        characterOrientation: card.generationSnapshot.characterOrientation,
+        backgroundSource: card.generationSnapshot.backgroundSource,
+        resultText: card.generationSnapshot.resultText,
+        capturedAt:
+          typeof card.generationSnapshot.capturedAt === 'string' &&
+          card.generationSnapshot.capturedAt.trim()
+            ? card.generationSnapshot.capturedAt
+            : new Date().toISOString(),
+      }
+    : card.kind === 'output'
+      ? {
+          type: card.type === 'video' ? 'video' : 'image',
+          prompt: card.prompt,
+          referenceCardIds: card.referenceCardIds,
+          workflowTemplateId: card.workflowTemplateId,
+          modelId: card.modelId,
+          aspectRatio: pick(card.aspectRatio, ASPECT_RATIOS, '1:1'),
+          outputQuality: pick(card.outputQuality, OUTPUT_QUALITIES, '1k'),
+          duration,
+          language,
+          mode: pick(card.mode, MODES, 'quality'),
+          variant: pick(card.variant, VARIANTS, 'standard'),
+          quality: pick(card.quality, QUALITIES, 'standard'),
+          capturedAt: new Date().toISOString(),
+        }
+      : card.generationSnapshot;
+  return {
+    ...card,
+    name,
+    duration,
+    language,
+    status: pick(card.status, STATUSES, 'idle'),
+    aspectRatio: pick(card.aspectRatio, ASPECT_RATIOS, '1:1'),
+    outputQuality: pick(card.outputQuality, OUTPUT_QUALITIES, '1k'),
+    mode: pick(card.mode, MODES, 'quality'),
+    variant: pick(card.variant, VARIANTS, 'standard'),
+    quality: pick(card.quality, QUALITIES, 'standard'),
+    generationSnapshot,
+    sourceConfigCardId:
+      card.kind === 'output'
+        ? card.sourceConfigCardId || card.id
+        : card.sourceConfigCardId,
+    generationRunId:
+      card.kind === 'output'
+        ? card.generationRunId || card.id
+        : card.generationRunId,
+  };
+}
diff --git a/src/core/commands/canvas-commands.ts b/src/core/commands/canvas-commands.ts
new file mode 100644
index 0000000..e704686
--- /dev/null
+++ b/src/core/commands/canvas-commands.ts
@@ -0,0 +1,194 @@
+import type { CanvasAssetCard, CanvasCard } from '@/core/beatcanvas/canvas-types';
+import {
+  normalizeProjectSnapshotDocument,
+  type ProjectSnapshotDocument,
+  type ProjectSnapshotShapeFrame,
+} from '@/core/projects/project-snapshot';
+
+export type CanvasOperation =
+  | {
+      type: 'upsert_card';
+      card: CanvasCard;
+      frame?: ProjectSnapshotShapeFrame;
+    }
+  | { type: 'remove_card'; cardId: string }
+  | {
+      type: 'move_card';
+      cardId: string;
+      frame: ProjectSnapshotShapeFrame;
+    }
+  | {
+      type: 'set_references';
+      cardId: string;
+      referenceCardIds: string[];
+    }
+  | {
+      type: 'upsert_timeline_node';
+      timelineId: string;
+      name: string;
+      durationSec: number;
+      clipCount: number;
+      lastRenderAssetId?: string | null;
+      lastRenderUrl?: string | null;
+      referenceCardIds?: string[];
+      frame?: ProjectSnapshotShapeFrame;
+    };
+
+export const timelineCanvasCardId = (timelineId: string) =>
+  `timeline:${timelineId}`;
+
+export function buildTimelineCanvasCard({
+  existing,
+  timelineId,
+  name,
+  durationSec,
+  clipCount,
+  lastRenderAssetId = null,
+  lastRenderUrl = null,
+  referenceCardIds = [],
+}: {
+  existing?: CanvasCard;
+  timelineId: string;
+  name: string;
+  durationSec: number;
+  clipCount: number;
+  lastRenderAssetId?: string | null;
+  lastRenderUrl?: string | null;
+  referenceCardIds?: string[];
+}): CanvasAssetCard {
+  const cardId = timelineCanvasCardId(timelineId);
+  const mergedRefs = Array.from(
+    new Set([
+      ...(existing?.referenceCardIds ?? []),
+      ...referenceCardIds,
+    ])
+  );
+  return {
+    id: cardId,
+    assetId: lastRenderAssetId ?? existing?.assetId ?? null,
+    kind: 'asset',
+    type: 'timeline',
+    name,
+    url: lastRenderUrl ?? existing?.url ?? null,
+    prompt: existing?.prompt ?? '',
+    referenceCardIds: mergedRefs,
+    workflowTemplateId: existing?.workflowTemplateId ?? null,
+    status: 'succeeded',
+    error: null,
+    modelId: existing?.modelId ?? '',
+    aspectRatio: existing?.aspectRatio ?? '16:9',
+    outputQuality: existing?.outputQuality ?? '1080p',
+    duration: existing?.duration ?? '5s',
+    mode: existing?.mode ?? 'quality',
+    variant: existing?.variant ?? 'standard',
+    quality: existing?.quality ?? 'standard',
+    sourceGenerationId: existing?.sourceGenerationId ?? null,
+    durationSec,
+    timelineId,
+    clipCount,
+    lastRenderAssetId: lastRenderAssetId ?? existing?.lastRenderAssetId ?? null,
+  };
+}
+export type CanvasCommandApplication = {
+  document: ProjectSnapshotDocument;
+  changedIds: string[];
+};
+
+export function applyCanvasOperations(
+  source: ProjectSnapshotDocument,
+  operations: readonly CanvasOperation[]
+): CanvasCommandApplication {
+  let cards = [...source.cards];
+  let frames = { ...source.frames };
+  const changedIds: string[] = [];
+
+  for (const operation of operations) {
+    if (operation.type === 'upsert_card') {
+      cards = [
+        ...cards.filter((card) => card.id !== operation.card.id),
+        operation.card,
+      ];
+      if (operation.frame) {
+        frames[operation.card.id] = operation.frame;
+      }
+      changedIds.push(operation.card.id);
+      continue;
+    }
+
+    if (operation.type === 'remove_card') {
+      if (!cards.some((card) => card.id === operation.cardId)) continue;
+      cards = cards.filter((card) => card.id !== operation.cardId);
+      delete frames[operation.cardId];
+      cards = cards.map((card) => ({
+        ...card,
+        referenceCardIds: card.referenceCardIds.filter(
+          (referenceCardId) => referenceCardId !== operation.cardId
+        ),
+      }));
+      changedIds.push(operation.cardId);
+      continue;
+    }
+
+    if (operation.type === 'move_card') {
+      if (!cards.some((card) => card.id === operation.cardId)) continue;
+      frames[operation.cardId] = operation.frame;
+      changedIds.push(operation.cardId);
+      continue;
+    }
+
+    if (operation.type === 'upsert_timeline_node') {
+      const cardId = timelineCanvasCardId(operation.timelineId);
+      const existing = cards.find((card) => card.id === cardId);
+      const card = buildTimelineCanvasCard({
+        existing,
+        timelineId: operation.timelineId,
+        name: operation.name,
+        durationSec: operation.durationSec,
+        clipCount: operation.clipCount,
+        lastRenderAssetId: operation.lastRenderAssetId,
+        lastRenderUrl: operation.lastRenderUrl,
+        referenceCardIds: operation.referenceCardIds,
+      });
+      cards = [...cards.filter((item) => item.id !== cardId), card];
+      const maxX = Object.values(frames).reduce(
+        (value, frame) => Math.max(value, frame.x + frame.w),
+        0
+      );
+      frames[cardId] =
+        operation.frame ??
+        frames[cardId] ?? {
+          x: maxX + 64,
+          y: 80,
+          w: 360,
+          h: 220,
+        };
+      changedIds.push(cardId);
+      continue;
+    }
+
+    const cardIndex = cards.findIndex((card) => card.id === operation.cardId);
+    if (cardIndex < 0) continue;
+    const knownIds = new Set(cards.map((card) => card.id));
+    cards[cardIndex] = {
+      ...cards[cardIndex],
+      referenceCardIds: Array.from(
+        new Set(
+          operation.referenceCardIds.filter(
+            (referenceCardId) =>
+              referenceCardId !== operation.cardId && knownIds.has(referenceCardId)
+          )
+        )
+      ),
+    } as CanvasCard;
+    changedIds.push(operation.cardId);
+  }
+
+  return {
+    document: normalizeProjectSnapshotDocument({
+      ...source,
+      cards,
+      frames,
+    }),
+    changedIds: Array.from(new Set(changedIds)),
+  };
+}
diff --git a/src/core/commands/client.ts b/src/core/commands/client.ts
new file mode 100644
index 0000000..9a9c11b
--- /dev/null
+++ b/src/core/commands/client.ts
@@ -0,0 +1,48 @@
+import { ApiError, apiJsonPost } from '@/lib/api-client';
+
+import {
+  createCommandId,
+  type BeatDesignCommandResult,
+} from './contracts';
+import type { BeatDesignCommand, BeatDesignCommandData } from './executor';
+
+const isCommandResult = (
+  value: unknown
+): value is BeatDesignCommandResult<BeatDesignCommandData> =>
+  Boolean(
+    value &&
+      typeof value === 'object' &&
+      typeof (value as { ok?: unknown }).ok === 'boolean' &&
+      typeof (value as { commandId?: unknown }).commandId === 'string'
+  );
+
+export async function executeProjectCommand({
+  projectId,
+  command,
+  expectedRevision,
+  commandId = createCommandId(),
+  idempotencyKey = commandId,
+}: {
+  projectId: string;
+  command: BeatDesignCommand;
+  expectedRevision?: number | null;
+  commandId?: string;
+  idempotencyKey?: string;
+}): Promise<BeatDesignCommandResult<BeatDesignCommandData>> {
+  try {
+    return await apiJsonPost<BeatDesignCommandResult<BeatDesignCommandData>>(
+      `/api/app/projects/${encodeURIComponent(projectId)}/commands`,
+      {
+        commandId,
+        expectedRevision,
+        idempotencyKey,
+        command,
+      }
+    );
+  } catch (error) {
+    if (error instanceof ApiError && isCommandResult(error.data)) {
+      return error.data;
+    }
+    throw error;
+  }
+}
diff --git a/src/core/commands/command-kernel.test.ts b/src/core/commands/command-kernel.test.ts
new file mode 100644
index 0000000..378c9fd
--- /dev/null
+++ b/src/core/commands/command-kernel.test.ts
@@ -0,0 +1,339 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import type { CanvasAssetCard } from '@/core/beatcanvas/canvas-types';
+import { createTimelineDocument } from '@/core/editor/timeline-document';
+import { validateLocalAssetImportCandidate } from '@/core/projects/import-local-asset';
+import { createEmptyProjectSnapshot } from '@/core/projects/project-snapshot';
+import {
+  applyCanvasOperations,
+  applyEditorOperations,
+  uiCommandRequestSchema,
+  createCommandFailure,
+  createCommandId,
+  executeBeatDesignCommand,
+  normalizeAssetFirstGenerationRequest,
+} from './index';
+import { validateExternalCommandAssetReferences } from './persist';
+
+test('revision conflict failures return the current revision for one-step retries', () => {
+  assert.deepEqual(
+    createCommandFailure({
+      commandId: 'command-1',
+      projectId: 'project-1',
+      origin: 'mcp',
+      code: 'REVISION_CONFLICT',
+      message: 'Project snapshot version conflict',
+      revision: 7,
+    }),
+    {
+      ok: false,
+      commandId: 'command-1',
+      projectId: 'project-1',
+      origin: 'mcp',
+      changedIds: [],
+      warnings: [],
+      code: 'REVISION_CONFLICT',
+      message: 'Project snapshot version conflict',
+      revision: 7,
+    }
+  );
+});
+
+test('command request schema rejects unknown commands and unstable editor ids', () => {
+  assert.equal(
+    uiCommandRequestSchema.safeParse({
+      command: { type: 'editor.erase_everything' },
+    }).success,
+    false
+  );
+  assert.equal(
+    uiCommandRequestSchema.safeParse({
+      command: {
+        type: 'editor.apply',
+        operations: [
+          {
+            type: 'add_clip',
+            assetId: 'asset-a',
+            name: 'A',
+            sourceType: 'video',
+            sourceDuration: 4,
+          },
+        ],
+      },
+    }).success,
+    false
+  );
+  assert.equal(
+    uiCommandRequestSchema.safeParse({
+      command: {
+        type: 'editor.apply',
+        operations: [
+          {
+            type: 'split_clip',
+            clipId: 'clip-a',
+            sourceTime: 2,
+          },
+        ],
+      },
+    }).success,
+    false
+  );
+});
+
+const assetCard: CanvasAssetCard = {
+  id: 'asset-card-1',
+  assetId: 'asset-1',
+  kind: 'asset',
+  type: 'video',
+  name: 'Scene A',
+  url: '/scene-a.mp4',
+  prompt: '',
+  referenceCardIds: [],
+  workflowTemplateId: null,
+  status: 'succeeded',
+  error: null,
+  modelId: '',
+  aspectRatio: '16:9',
+  outputQuality: '1080p',
+  duration: '5s',
+  mode: 'quality',
+  variant: 'standard',
+  quality: 'standard',
+  sourceGenerationId: null,
+};
+
+test('external Canvas commands require project assets instead of arbitrary URLs', () => {
+  const urlOnlyAssetCommand = {
+    type: 'canvas.apply' as const,
+    operations: [
+      {
+        type: 'upsert_card' as const,
+        card: { ...assetCard, assetId: null, url: 'https://example.com/a.mp4' },
+      },
+    ],
+  };
+
+  assert.throws(
+    () =>
+      validateExternalCommandAssetReferences({
+        origin: 'mcp',
+        command: urlOnlyAssetCommand,
+      }),
+    /assetId/i
+  );
+  assert.doesNotThrow(() =>
+    validateExternalCommandAssetReferences({
+      origin: 'ui',
+      command: urlOnlyAssetCommand,
+    })
+  );
+  assert.throws(
+    () =>
+      validateExternalCommandAssetReferences({
+        origin: 'mcp',
+        command: {
+          type: 'canvas.apply',
+          operations: [
+            {
+              type: 'upsert_timeline_node',
+              timelineId: 'timeline-1',
+              name: 'Timeline 1',
+              durationSec: 4,
+              clipCount: 1,
+              lastRenderUrl: 'https://example.com/render.mp4',
+            },
+          ],
+        },
+      }),
+    /lastRenderAssetId/i
+  );
+});
+
+test('local import validates file size before reading and accepts audio extensions', () => {
+  assert.deepEqual(
+    validateLocalAssetImportCandidate({ filename: 'music.mp3', size: 1024 }),
+    { mediaType: 'audio', mimeType: 'audio/mpeg' }
+  );
+  assert.throws(
+    () =>
+      validateLocalAssetImportCandidate({
+        filename: 'oversized.mp4',
+        size: Number.MAX_SAFE_INTEGER,
+      }),
+    /size is not supported/i
+  );
+});
+
+test('generation requests are asset-first and do not accept placement', () => {
+  assert.throws(() =>
+    normalizeAssetFirstGenerationRequest({
+      version: 1,
+      projectId: 'project-1',
+      mode: 'video',
+      modelId: 'model-1',
+      prompt: 'Continue the shot',
+      references: [{ assetId: 'asset-frame', role: 'first_frame' }],
+      parameters: {},
+      placement: 'canvas_node',
+    })
+  );
+
+  const request = normalizeAssetFirstGenerationRequest({
+    version: 1,
+    projectId: 'project-1',
+    mode: 'video',
+    modelId: 'model-1',
+    prompt: 'Continue the shot',
+    references: [{ assetId: 'asset-frame', role: 'first_frame' }],
+  });
+  assert.equal(request.references[0]?.assetId, 'asset-frame');
+});
+
+test('canvas operations update cards and frames atomically', () => {
+  const result = applyCanvasOperations(createEmptyProjectSnapshot(), [
+    {
+      type: 'upsert_card',
+      card: assetCard,
+      frame: { x: 20, y: 30, w: 320, h: 180 },
+    },
+    {
+      type: 'move_card',
+      cardId: assetCard.id,
+      frame: { x: 100, y: 120, w: 320, h: 180 },
+    },
+  ]);
+  assert.equal(result.document.cards.length, 1);
+  assert.equal(result.document.frames[assetCard.id]?.x, 100);
+  assert.deepEqual(result.changedIds, [assetCard.id]);
+});
+
+test('editor operations compose multiple clips in one document transaction', () => {
+  const timeline = createTimelineDocument({ projectId: 'project-1', name: 'Timeline 1' });
+  const result = applyEditorOperations(timeline, [
+    {
+      type: 'add_clip',
+      assetId: 'asset-a',
+      sourceUrl: '/a.mp4',
+      name: 'A',
+      sourceType: 'video',
+      sourceDuration: 4,
+    },
+    {
+      type: 'add_clip',
+      assetId: 'asset-b',
+      sourceUrl: '/b.mp4',
+      name: 'B',
+      sourceType: 'video',
+      sourceDuration: 3,
+    },
+  ]);
+  const clips = result.document.tracks.find((track) => track.kind === 'video')?.clips ?? [];
+  assert.equal(clips.length, 2);
+  assert.equal(clips[0]?.startTime, 0);
+  assert.equal(clips[1]?.startTime, 4);
+  assert.equal(result.document.duration, 7);
+});
+
+test('timeline node upsert preserves existing canvas references', () => {
+  const withVideo = applyCanvasOperations(createEmptyProjectSnapshot(), [
+    {
+      type: 'upsert_card',
+      card: assetCard,
+      frame: { x: 0, y: 0, w: 320, h: 180 },
+    },
+  ]).document;
+  const created = applyCanvasOperations(withVideo, [
+    {
+      type: 'upsert_timeline_node',
+      timelineId: 'timeline-1',
+      name: 'Timeline 1',
+      durationSec: 4,
+      clipCount: 1,
+      referenceCardIds: [assetCard.id],
+    },
+  ]);
+  const updated = applyCanvasOperations(created.document, [
+    {
+      type: 'upsert_timeline_node',
+      timelineId: 'timeline-1',
+      name: 'Timeline 1',
+      durationSec: 8,
+      clipCount: 2,
+      lastRenderAssetId: 'render-1',
+      lastRenderUrl: '/render.mp4',
+    },
+  ]);
+  const timelineCard = updated.document.cards.find(
+    (card) => card.id === 'timeline:timeline-1'
+  );
+  assert.deepEqual(timelineCard?.referenceCardIds, [assetCard.id]);
+  assert.equal(timelineCard?.lastRenderAssetId, 'render-1');
+  assert.equal(timelineCard?.durationSec, 8);
+});
+
+test('add_clip with a stable clip id is idempotent', () => {
+  const timeline = createTimelineDocument({
+    projectId: 'project-1',
+    name: 'Timeline 1',
+  });
+  const first = applyEditorOperations(timeline, [
+    {
+      type: 'add_clip',
+      clipId: 'clip:batch:asset-a:0',
+      assetId: 'asset-a',
+      sourceUrl: '/a.mp4',
+      name: 'A',
+      sourceType: 'video',
+      sourceDuration: 4,
+    },
+  ]);
+  const retry = applyEditorOperations(first.document, [
+    {
+      type: 'add_clip',
+      clipId: 'clip:batch:asset-a:0',
+      assetId: 'asset-a',
+      sourceUrl: '/a.mp4',
+      name: 'A',
+      sourceType: 'video',
+      sourceDuration: 4,
+    },
+  ]);
+  const clips =
+    retry.document.tracks.find((track) => track.kind === 'video')?.clips ?? [];
+  assert.equal(clips.length, 1);
+  assert.equal(clips[0]?.id, 'clip:batch:asset-a:0');
+});
+
+test('command executor returns a structured result for editor apply', () => {
+  const timeline = createTimelineDocument({
+    projectId: 'project-1',
+    name: 'Timeline 1',
+  });
+  const result = executeBeatDesignCommand({
+    envelope: {
+      commandId: createCommandId(),
+      projectId: 'project-1',
+      origin: 'ui',
+      command: {
+        type: 'editor.apply',
+        operations: [
+          {
+            type: 'add_clip',
+            assetId: 'asset-a',
+            sourceUrl: '/a.mp4',
+            name: 'A',
+            sourceType: 'video',
+            sourceDuration: 5,
+          },
+        ],
+      },
+    },
+    documents: { timeline },
+  });
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.data.timeline?.duration, 5);
+    assert.equal(result.changedIds.length, 1);
+  }
+});
diff --git a/src/core/commands/contracts.ts b/src/core/commands/contracts.ts
new file mode 100644
index 0000000..2cfcd8f
--- /dev/null
+++ b/src/core/commands/contracts.ts
@@ -0,0 +1,121 @@
+export type BeatDesignCommandOrigin = 'ui' | 'mcp' | 'cli' | 'system';
+
+export type BeatDesignCommandEnvelope<TCommand> = {
+  commandId: string;
+  projectId: string;
+  origin: BeatDesignCommandOrigin;
+  expectedRevision?: number | null;
+  idempotencyKey?: string | null;
+  command: TCommand;
+};
+
+export type BeatDesignCommandSuccess<TData = undefined> = {
+  ok: true;
+  commandId: string;
+  projectId: string;
+  origin: BeatDesignCommandOrigin;
+  changedIds: string[];
+  warnings: string[];
+  revision?: number;
+  jobId?: string;
+  editorUrl?: string;
+  data: TData;
+};
+
+export type BeatDesignCommandFailure = {
+  ok: false;
+  commandId: string;
+  projectId: string;
+  origin: BeatDesignCommandOrigin;
+  changedIds: [];
+  warnings: string[];
+  code:
+    | 'INVALID_COMMAND'
+    | 'NOT_FOUND'
+    | 'REVISION_CONFLICT'
+    | 'COMMAND_FAILED';
+  message: string;
+  revision?: number;
+};
+
+export type BeatDesignCommandResult<TData = undefined> =
+  | BeatDesignCommandSuccess<TData>
+  | BeatDesignCommandFailure;
+
+export class BeatDesignCommandError extends Error {
+  readonly code: BeatDesignCommandFailure['code'];
+
+  constructor(
+    code: BeatDesignCommandFailure['code'],
+    message: string
+  ) {
+    super(message);
+    this.name = 'BeatDesignCommandError';
+    this.code = code;
+  }
+}
+
+export const createCommandId = () =>
+  globalThis.crypto?.randomUUID?.() ??
+  `cmd-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+
+export const createCommandFailure = ({
+  commandId,
+  projectId,
+  origin,
+  code,
+  message,
+  revision,
+  warnings = [],
+}: {
+  commandId: string;
+  projectId: string;
+  origin: BeatDesignCommandOrigin;
+  code: BeatDesignCommandFailure['code'];
+  message: string;
+  revision?: number;
+  warnings?: string[];
+}): BeatDesignCommandFailure => ({
+  ok: false,
+  commandId,
+  projectId,
+  origin,
+  changedIds: [],
+  warnings,
+  code,
+  message,
+  ...(typeof revision === 'number' ? { revision } : {}),
+});
+
+export const createCommandSuccess = <TData>({
+  commandId,
+  projectId,
+  origin,
+  changedIds = [],
+  warnings = [],
+  revision,
+  jobId,
+  editorUrl,
+  data,
+}: {
+  commandId: string;
+  projectId: string;
+  origin: BeatDesignCommandOrigin;
+  changedIds?: string[];
+  warnings?: string[];
+  revision?: number;
+  jobId?: string;
+  editorUrl?: string;
+  data: TData;
+}): BeatDesignCommandSuccess<TData> => ({
+  ok: true,
+  commandId,
+  projectId,
+  origin,
+  changedIds: Array.from(new Set(changedIds)),
+  warnings,
+  ...(typeof revision === 'number' ? { revision } : {}),
+  ...(jobId ? { jobId } : {}),
+  ...(editorUrl ? { editorUrl } : {}),
+  data,
+});
diff --git a/src/core/commands/editor-commands.ts b/src/core/commands/editor-commands.ts
new file mode 100644
index 0000000..446cc35
--- /dev/null
+++ b/src/core/commands/editor-commands.ts
@@ -0,0 +1,173 @@
+import {
+  activateTimelineTake,
+  addSourceClip,
+  addTimelineTake,
+  findTimelineClip,
+  moveTimelineClip,
+  removeTimelineClip,
+  resizeTimelineClip,
+  rippleDeleteTimelineClip,
+  setTimelineRender,
+  splitTimelineClip,
+  trimTimelineClip,
+  updateTimelineAudioClip,
+  type TimelineAudioRole,
+  type TimelineDocument,
+  type TimelineTake,
+} from '@/core/editor/timeline-document';
+import { BeatDesignCommandError } from './contracts';
+
+export type EditorOperation =
+  | {
+      type: 'add_clip';
+      assetId: string;
+      sourceUrl: string;
+      name: string;
+      sourceType: 'image' | 'video' | 'audio';
+      sourceDuration: number;
+      startTime?: number;
+      audioRole?: TimelineAudioRole;
+      clipId?: string;
+    }
+  | { type: 'trim_clip'; clipId: string; inPoint: number; outPoint: number }
+  | {
+      type: 'split_clip';
+      clipId: string;
+      sourceTime: number;
+      rightClipId?: string;
+    }
+  | { type: 'move_clip'; clipId: string; startTime: number }
+  | { type: 'set_clip_duration'; clipId: string; duration: number }
+  | { type: 'remove_clip'; clipId: string; ripple?: boolean }
+  | {
+      type: 'update_audio';
+      clipId: string;
+      patch: {
+        volume?: number;
+        muted?: boolean;
+        fadeIn?: number;
+        fadeOut?: number;
+      };
+    }
+  | {
+      type: 'add_take';
+      clipId: string;
+      take: Omit<TimelineTake, 'id' | 'createdAt'> & {
+        id?: string;
+        createdAt?: string;
+      };
+    }
+  | { type: 'activate_take'; clipId: string; takeId: string | null }
+  | { type: 'set_render'; assetId: string; publicUrl: string };
+
+const listClipIds = (document: TimelineDocument) =>
+  new Set(document.tracks.flatMap((track) => track.clips.map((clip) => clip.id)));
+
+export function applyEditorOperations(
+  source: TimelineDocument,
+  operations: readonly EditorOperation[]
+) {
+  let document = source;
+  const changedIds = new Set<string>();
+
+  for (const [index, operation] of operations.entries()) {
+    const beforeClipIds = listClipIds(document);
+    let next = document;
+
+    if (operation.type === 'add_clip') {
+      if (!operation.assetId || !operation.sourceUrl || operation.sourceDuration <= 0) {
+        throw new BeatDesignCommandError(
+          'INVALID_COMMAND',
+          `Editor operation ${index} has an invalid clip source.`
+        );
+      }
+      next = addSourceClip(document, operation);
+      if (next === document && operation.clipId && beforeClipIds.has(operation.clipId)) {
+        continue;
+      }
+    } else if (operation.type === 'trim_clip') {
+      if (!findTimelineClip(document, operation.clipId)) {
+        throw new BeatDesignCommandError('NOT_FOUND', `Clip ${operation.clipId} was not found.`);
+      }
+      next = trimTimelineClip(
+        document,
+        operation.clipId,
+        operation.inPoint,
+        operation.outPoint
+      );
+    } else if (operation.type === 'split_clip') {
+      if (!findTimelineClip(document, operation.clipId)) {
+        throw new BeatDesignCommandError('NOT_FOUND', `Clip ${operation.clipId} was not found.`);
+      }
+      next = splitTimelineClip(
+        document,
+        operation.clipId,
+        operation.sourceTime,
+        operation.rightClipId
+      );
+    } else if (operation.type === 'move_clip') {
+      if (!findTimelineClip(document, operation.clipId)) {
+        throw new BeatDesignCommandError('NOT_FOUND', `Clip ${operation.clipId} was not found.`);
+      }
+      next = moveTimelineClip(document, operation.clipId, operation.startTime);
+    } else if (operation.type === 'set_clip_duration') {
+      const clip = findTimelineClip(document, operation.clipId);
+      if (!clip || clip.sourceType !== 'image') {
+        throw new BeatDesignCommandError(
+          'NOT_FOUND',
+          `Image clip ${operation.clipId} was not found.`
+        );
+      }
+      next = resizeTimelineClip(document, operation.clipId, operation.duration);
+    } else if (operation.type === 'remove_clip') {
+      if (!findTimelineClip(document, operation.clipId)) {
+        throw new BeatDesignCommandError('NOT_FOUND', `Clip ${operation.clipId} was not found.`);
+      }
+      next = operation.ripple
+        ? rippleDeleteTimelineClip(document, operation.clipId)
+        : removeTimelineClip(document, operation.clipId);
+    } else if (operation.type === 'update_audio') {
+      const clip = findTimelineClip(document, operation.clipId);
+      if (!clip || clip.sourceType !== 'audio') {
+        throw new BeatDesignCommandError('NOT_FOUND', `Audio clip ${operation.clipId} was not found.`);
+      }
+      next = updateTimelineAudioClip(document, operation.clipId, operation.patch);
+    } else if (operation.type === 'add_take') {
+      if (!findTimelineClip(document, operation.clipId)) {
+        throw new BeatDesignCommandError('NOT_FOUND', `Clip ${operation.clipId} was not found.`);
+      }
+      next = addTimelineTake(document, operation.clipId, operation.take);
+    } else if (operation.type === 'activate_take') {
+      if (!findTimelineClip(document, operation.clipId)) {
+        throw new BeatDesignCommandError('NOT_FOUND', `Clip ${operation.clipId} was not found.`);
+      }
+      next = activateTimelineTake(document, operation.clipId, operation.takeId);
+    } else {
+      next = setTimelineRender(document, {
+        id: operation.assetId,
+        publicUrl: operation.publicUrl,
+      });
+      changedIds.add(document.id);
+    }
+
+    if (next === document) {
+      throw new BeatDesignCommandError(
+        'INVALID_COMMAND',
+        `Editor operation ${index} (${operation.type}) could not be applied.`
+      );
+    }
+
+    const afterClipIds = listClipIds(next);
+    for (const clipId of new Set([...beforeClipIds, ...afterClipIds])) {
+      const before = findTimelineClip(document, clipId);
+      const after = findTimelineClip(next, clipId);
+      if (JSON.stringify(before) !== JSON.stringify(after)) changedIds.add(clipId);
+    }
+    if ('clipId' in operation && operation.clipId) {
+      changedIds.add(operation.clipId);
+    }
+    document = next;
+  }
+
+  return { document, changedIds: [...changedIds] };
+}
diff --git a/src/core/commands/executor.ts b/src/core/commands/executor.ts
new file mode 100644
index 0000000..6486cdb
--- /dev/null
+++ b/src/core/commands/executor.ts
@@ -0,0 +1,128 @@
+import { diagnoseTimeline } from '@/core/editor/timeline-diagnostics';
+import {
+  createTimelineDocument,
+  type TimelineDocument,
+} from '@/core/editor/timeline-document';
+import type { ProjectSnapshotDocument } from '@/core/projects/project-snapshot';
+
+import {
+  applyCanvasOperations,
+  type CanvasOperation,
+} from './canvas-commands';
+import {
+  applyEditorOperations,
+  type EditorOperation,
+} from './editor-commands';
+import {
+  BeatDesignCommandError,
+  createCommandFailure,
+  createCommandSuccess,
+  type BeatDesignCommandEnvelope,
+  type BeatDesignCommandResult,
+} from './contracts';
+
+export type BeatDesignCommand =
+  | { type: 'canvas.apply'; operations: CanvasOperation[] }
+  | { type: 'editor.apply'; operations: EditorOperation[] }
+  | { type: 'editor.replace_document'; document: TimelineDocument }
+  | { type: 'editor.validate' };
+
+export type BeatDesignCommandDocuments = {
+  canvas?: ProjectSnapshotDocument;
+  timeline?: TimelineDocument | null;
+};
+
+export type BeatDesignCommandData = BeatDesignCommandDocuments & {
+  diagnostics?: ReturnType<typeof diagnoseTimeline>;
+};
+
+export function executeBeatDesignCommand({
+  envelope,
+  documents,
+}: {
+  envelope: BeatDesignCommandEnvelope<BeatDesignCommand>;
+  documents: BeatDesignCommandDocuments;
+}): BeatDesignCommandResult<BeatDesignCommandData> {
+  const { commandId, projectId, origin, command } = envelope;
+
+  try {
+    if (command.type === 'canvas.apply') {
+      if (!documents.canvas) {
+        throw new BeatDesignCommandError(
+          'NOT_FOUND',
+          'Canvas document was not found.'
+        );
+      }
+      const applied = applyCanvasOperations(documents.canvas, command.operations);
+      return createCommandSuccess({
+        commandId,
+        projectId,
+        origin,
+        changedIds: applied.changedIds,
+        data: { canvas: applied.document },
+      });
+    }
+
+    if (command.type === 'editor.apply') {
+      const source =
+        documents.timeline ??
+        createTimelineDocument({
+          projectId,
+          name: 'Timeline 1',
+        });
+      const applied = applyEditorOperations(source, command.operations);
+      return createCommandSuccess({
+        commandId,
+        projectId,
+        origin,
+        changedIds: applied.changedIds,
+        data: { timeline: applied.document },
+      });
+    }
+
+    if (command.type === 'editor.replace_document') {
+      return createCommandSuccess({
+        commandId,
+        projectId,
+        origin,
+        changedIds: [command.document.id],
+        data: { timeline: command.document },
+      });
+    }
+
+    if (!documents.timeline) {
+      throw new BeatDesignCommandError(
+        'NOT_FOUND',
+        'Timeline document was not found.'
+      );
+    }
+    return createCommandSuccess({
+      commandId,
+      projectId,
+      origin,
+      changedIds: [documents.timeline.id],
+      data: {
+        timeline: documents.timeline,
+        diagnostics: diagnoseTimeline(documents.timeline),
+      },
+    });
+  } catch (error) {
+    if (error instanceof BeatDesignCommandError) {
+      return createCommandFailure({
+        commandId,
+        projectId,
+        origin,
+        code: error.code,
+        message: error.message,
+      });
+    }
+    return createCommandFailure({
+      commandId,
+      projectId,
+      origin,
+      code: 'COMMAND_FAILED',
+      message:
+        error instanceof Error ? error.message : 'The command could not be applied.',
+    });
+  }
+}
diff --git a/src/core/commands/generation-compiler.ts b/src/core/commands/generation-compiler.ts
new file mode 100644
index 0000000..0f82ea6
--- /dev/null
+++ b/src/core/commands/generation-compiler.ts
@@ -0,0 +1,104 @@
+import { getCompletedIntentUploads } from '@/core/effects/generation-upload-intent';
+import { getProjectAssetById } from '@/core/workspace-lib/assets/user-assets';
+
+import type { AssetFirstGenerationRequest } from './generation-contract';
+
+const MEDIA_PARAMETER_KEYS = new Set([
+  'prompt',
+  'placement',
+  'image_url',
+  'image_urls',
+  'video_url',
+  'video_urls',
+  'audio_url',
+  'audio_urls',
+  'first_frame',
+  'last_frame',
+  'callBackUrl',
+  'callbackUrl',
+]);
+
+export class GenerationReferenceError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'GenerationReferenceError';
+  }
+}
+
+export async function compileAssetFirstGenerationInput({
+  generation,
+  generationIntentId,
+}: {
+  generation: AssetFirstGenerationRequest;
+  generationIntentId: string;
+}) {
+  const uploads = (await getCompletedIntentUploads({
+    intentId: generationIntentId,
+  })) as Array<{ publicUrl: string | null }>;
+  const uploadedUrls = new Set(
+    uploads
+      .map((upload: { publicUrl: string | null }) => upload.publicUrl?.trim())
+      .filter((url: string | undefined): url is string => Boolean(url))
+  );
+  const imageUrls: string[] = [];
+  const videoUrls: string[] = [];
+  const audioUrls: string[] = [];
+  let firstFrame: string | null = null;
+  let lastFrame: string | null = null;
+
+  for (const reference of generation.references) {
+    const asset = await getProjectAssetById({
+      projectId: generation.projectId,
+      assetId: reference.assetId,
+    });
+    if (!asset) {
+      throw new GenerationReferenceError(
+        `Asset ${reference.assetId} does not belong to this project.`
+      );
+    }
+    const deliveryUrl = reference.deliveryUrl?.trim() || asset.publicUrl.trim();
+    if (
+      deliveryUrl !== asset.publicUrl.trim() &&
+      !uploadedUrls.has(deliveryUrl)
+    ) {
+      throw new GenerationReferenceError(
+        `Delivery URL for asset ${reference.assetId} is not authorized by this generation intent.`
+      );
+    }
+
+    if (reference.role === 'audio_track' || asset.type === 'audio') {
+      audioUrls.push(deliveryUrl);
+      continue;
+    }
+    if (asset.type === 'video') {
+      videoUrls.push(deliveryUrl);
+      continue;
+    }
+    if (asset.type !== 'image') {
+      throw new GenerationReferenceError(
+        `Asset ${reference.assetId} has an unsupported media type.`
+      );
+    }
+    imageUrls.push(deliveryUrl);
+    if (reference.role === 'first_frame') firstFrame = deliveryUrl;
+    if (reference.role === 'last_frame') lastFrame = deliveryUrl;
+  }
+
+  const parameters = Object.fromEntries(
+    Object.entries(generation.parameters).filter(
+      ([key]) => !MEDIA_PARAMETER_KEYS.has(key)
+    )
+  );
+  return {
+    ...parameters,
+    prompt: generation.prompt,
+    ...(imageUrls.length > 0 ? { image_urls: [...new Set(imageUrls)] } : {}),
+    ...(videoUrls.length > 0 ? { video_urls: [...new Set(videoUrls)] } : {}),
+    ...(audioUrls.length > 0 ? { audio_urls: [...new Set(audioUrls)] } : {}),
+    ...(firstFrame ? { first_frame: firstFrame } : {}),
+    ...(lastFrame ? { last_frame: lastFrame } : {}),
+    ...(generation.mode === 'analysis' && videoUrls[0]
+      ? { video_url: videoUrls[0] }
+      : {}),
+  };
+}
diff --git a/src/core/commands/generation-contract.ts b/src/core/commands/generation-contract.ts
new file mode 100644
index 0000000..f28ed70
--- /dev/null
+++ b/src/core/commands/generation-contract.ts
@@ -0,0 +1,121 @@
+import type { CanvasCard } from '@/core/beatcanvas/canvas-types';
+import { parseLocalProjectAssetUrl } from '@/core/projects/local-project-asset-url';
+import { z } from 'zod';
+
+export const GENERATION_REQUEST_VERSION = 1 as const;
+
+export const generationReferenceRoleSchema = z.enum([
+  'source',
+  'reference',
+  'style',
+  'subject',
+  'pose',
+  'first_frame',
+  'last_frame',
+  'audio_track',
+]);
+
+export type GenerationReferenceRole = z.infer<
+  typeof generationReferenceRoleSchema
+>;
+
+export const assetFirstGenerationRequestSchema = z
+  .object({
+    version: z.literal(GENERATION_REQUEST_VERSION),
+    projectId: z.string().min(1).max(160),
+    mode: z.enum(['image', 'video', 'analysis', 'audio']),
+    modelId: z.string().min(1).max(200),
+    prompt: z.string().max(20_000),
+    references: z
+      .array(
+        z.object({
+          assetId: z.string().min(1).max(200),
+          role: generationReferenceRoleSchema,
+          deliveryUrl: z.string().trim().min(1).max(4096).optional(),
+        })
+          .strict()
+      )
+      .max(20)
+      .default([]),
+    parameters: z.record(z.string(), z.unknown()).default({}),
+  })
+  .strict();
+
+export type AssetFirstGenerationRequest = z.infer<
+  typeof assetFirstGenerationRequestSchema
+>;
+
+export type GenerationAssetResult = {
+  generationId: string;
+  assetIds: string[];
+};
+
+/**
+ * Generation always produces Assets. Canvas and Editor placement is a separate
+ * command so one output can be reused by multiple views without regeneration.
+ */
+export const normalizeAssetFirstGenerationRequest = (value: unknown) =>
+  assetFirstGenerationRequestSchema.parse(value);
+
+const resolveCardAssetId = (card: CanvasCard) =>
+  card.assetId?.trim() || parseLocalProjectAssetUrl(card.url)?.assetId || null;
+
+export function buildAssetFirstReferencesFromCanvasCards({
+  cards,
+  referenceCardIds,
+  mode,
+  deliveryUrlsByCardId = {},
+}: {
+  cards: Record<string, CanvasCard | undefined>;
+  referenceCardIds: string[];
+  mode: AssetFirstGenerationRequest['mode'];
+  deliveryUrlsByCardId?: Record<string, string>;
+}) {
+  const mediaCards = referenceCardIds.flatMap((cardId) => {
+    const card = cards[cardId];
+    if (
+      !card?.url ||
+      (card.type !== 'image' && card.type !== 'video' && card.type !== 'audio')
+    ) {
+      return [];
+    }
+    return [card];
+  });
+
+  const imageCount = mediaCards.filter((card) => card.type === 'image').length;
+  let imageIndex = 0;
+
+  const references: Array<{
+    assetId: string;
+    role: GenerationReferenceRole;
+    deliveryUrl?: string;
+  }> = [];
+  for (const card of mediaCards) {
+    const assetId = resolveCardAssetId(card);
+    if (!assetId) {
+      if (parseLocalProjectAssetUrl(card.url)) {
+        throw new Error('Canvas generation references must be project assets.');
+      }
+      continue;
+    }
+    let role: GenerationReferenceRole = 'reference';
+    if (card.type === 'video') role = 'source';
+    else if (card.type === 'audio') role = 'audio_track';
+    else if (mode === 'video') {
+      role =
+        imageIndex === 0
+          ? 'first_frame'
+          : imageIndex === imageCount - 1 && imageCount > 1
+            ? 'last_frame'
+            : 'reference';
+      imageIndex += 1;
+    }
+    const deliveryUrl = deliveryUrlsByCardId[card.id]?.trim() || card.url?.trim();
+    references.push({
+      assetId,
+      role,
+      ...(deliveryUrl ? { deliveryUrl } : {}),
+    });
+  }
+  return references;
+}
diff --git a/src/core/commands/index.ts b/src/core/commands/index.ts
new file mode 100644
index 0000000..4caafa5
--- /dev/null
+++ b/src/core/commands/index.ts
@@ -0,0 +1,7 @@
+export * from './canvas-commands';
+export * from './client';
+export * from './contracts';
+export * from './editor-commands';
+export * from './executor';
+export * from './generation-contract';
+export * from './schema';
diff --git a/src/core/commands/persist.ts b/src/core/commands/persist.ts
new file mode 100644
index 0000000..95516d9
--- /dev/null
+++ b/src/core/commands/persist.ts
@@ -0,0 +1,357 @@
+import {
+  loadProjectTimeline,
+  saveProjectTimeline,
+} from '@/core/editor/timeline-state';
+import {
+  loadProjectWithLatestSnapshot,
+  saveProjectSnapshot,
+} from '@/core/projects/projects';
+
+import { normalizeCommandAssetReferences } from './asset-boundary';
+import {
+  BeatDesignCommandError,
+  createCommandFailure,
+  createCommandId,
+  type BeatDesignCommandEnvelope,
+  type BeatDesignCommandOrigin,
+  type BeatDesignCommandResult,
+} from './contracts';
+import {
+  executeBeatDesignCommand,
+  type BeatDesignCommand,
+  type BeatDesignCommandData,
+} from './executor';
+import {
+  loadCommandReceipt,
+  loadCommandReceiptRecord,
+  storeCommandReceipt,
+} from './receipts';
+
+const inFlightCommands = new Map<
+  string,
+  {
+    commandId: string;
+    commandType: BeatDesignCommand['type'];
+    promise: Promise<BeatDesignCommandResult<BeatDesignCommandData>>;
+  }
+>();
+
+const isVersionConflict = (error: unknown) =>
+  error instanceof Error &&
+  (error.name === 'TimelineVersionConflict' ||
+    error.name === 'ProjectSnapshotVersionConflict');
+
+const getConflictRevision = (error: unknown) => {
+  if (!error || typeof error !== 'object') return undefined;
+  const currentVersion = (error as { currentVersion?: unknown }).currentVersion;
+  return typeof currentVersion === 'number' && Number.isFinite(currentVersion)
+    ? currentVersion
+    : undefined;
+};
+
+type PersistCommandInput = {
+  projectId: string;
+  origin: BeatDesignCommandOrigin;
+  commandId: string;
+  expectedRevision?: number | null;
+  idempotencyKey: string;
+  command: BeatDesignCommand;
+};
+
+export function validateExternalCommandAssetReferences({
+  origin,
+  command,
+}: {
+  origin: BeatDesignCommandOrigin;
+  command: BeatDesignCommand;
+}) {
+  if (origin !== 'mcp' && origin !== 'cli') return;
+  if (command.type !== 'canvas.apply') return;
+
+  for (const operation of command.operations) {
+    if (operation.type === 'upsert_card') {
+      const { card } = operation;
+      if (
+        card.kind === 'asset' &&
+        card.type !== 'timeline' &&
+        !card.assetId
+      ) {
+        throw new BeatDesignCommandError(
+          'INVALID_COMMAND',
+          'External Canvas asset cards require a project assetId. Import or generate the asset first.'
+        );
+      }
+      if (card.url && !card.assetId) {
+        throw new BeatDesignCommandError(
+          'INVALID_COMMAND',
+          'External Canvas media URLs must be derived from a project assetId.'
+        );
+      }
+    }
+
+    if (
+      operation.type === 'upsert_timeline_node' &&
+      operation.lastRenderUrl &&
+      !operation.lastRenderAssetId
+    ) {
+      throw new BeatDesignCommandError(
+        'INVALID_COMMAND',
+        'External timeline renders require lastRenderAssetId; the server derives lastRenderUrl.'
+      );
+    }
+  }
+}
+
+async function persistBeatDesignCommandOnce({
+  projectId,
+  origin,
+  commandId,
+  expectedRevision,
+  idempotencyKey,
+  command,
+}: PersistCommandInput): Promise<
+  BeatDesignCommandResult<BeatDesignCommandData>
+> {
+  const cached = await loadCommandReceiptRecord({ projectId, idempotencyKey });
+  if (cached) {
+    if (
+      cached.commandId !== commandId ||
+      cached.commandType !== command.type
+    ) {
+      return createCommandFailure({
+        commandId,
+        projectId,
+        origin,
+        code: 'INVALID_COMMAND',
+        message: 'Idempotency key is already bound to a different command.',
+      });
+    }
+    return cached.result;
+  }
+
+  if (
+    command.type === 'editor.replace_document' &&
+    origin !== 'ui' &&
+    origin !== 'system'
+  ) {
+    return createCommandFailure({
+      commandId,
+      projectId,
+      origin,
+      code: 'INVALID_COMMAND',
+      message:
+        'External agents must use editor.apply operations instead of replacing the timeline document.',
+    });
+  }
+
+  try {
+    validateExternalCommandAssetReferences({ origin, command });
+    const normalizedCommand = await normalizeCommandAssetReferences({
+      projectId,
+      command,
+    });
+    const envelope: BeatDesignCommandEnvelope<BeatDesignCommand> = {
+      commandId,
+      projectId,
+      origin,
+      expectedRevision,
+      idempotencyKey,
+      command: normalizedCommand,
+    };
+
+    let result: BeatDesignCommandResult<BeatDesignCommandData>;
+    if (normalizedCommand.type === 'canvas.apply') {
+      const state = await loadProjectWithLatestSnapshot({ projectId });
+      if (!state) {
+        return createCommandFailure({
+          commandId,
+          projectId,
+          origin,
+          code: 'NOT_FOUND',
+          message: 'Project not found',
+        });
+      }
+      const executed = executeBeatDesignCommand({
+        envelope,
+        documents: { canvas: state.snapshot },
+      });
+      if (!executed.ok || !executed.data.canvas) return executed;
+      const saved = await saveProjectSnapshot({
+        projectId,
+        document: executed.data.canvas,
+        baseVersion:
+          typeof expectedRevision === 'number'
+            ? expectedRevision
+            : state.snapshotVersion,
+      });
+      result = { ...executed, revision: saved.version };
+    } else {
+      const timeline = await loadProjectTimeline(projectId);
+      const executed = executeBeatDesignCommand({
+        envelope,
+        documents: { timeline: timeline?.document ?? null },
+      });
+      if (!executed.ok) return executed;
+      if (normalizedCommand.type === 'editor.validate') {
+        return { ...executed, revision: timeline?.version };
+      }
+      if (!executed.data.timeline) return executed;
+      const saved = await saveProjectTimeline({
+        projectId,
+        document: executed.data.timeline,
+        baseVersion:
+          typeof expectedRevision === 'number'
+            ? expectedRevision
+            : (timeline?.version ?? null),
+      });
+      result = {
+        ...executed,
+        revision: saved.version,
+        editorUrl: `/editor/${encodeURIComponent(projectId)}`,
+        data: {
+          ...executed.data,
+          timeline: saved.document,
+        },
+      };
+    }
+
+    return storeCommandReceipt({
+      projectId,
+      idempotencyKey,
+      commandId,
+      origin,
+      commandType: normalizedCommand.type,
+      result,
+    });
+  } catch (error) {
+    if (error instanceof BeatDesignCommandError) {
+      return createCommandFailure({
+        commandId,
+        projectId,
+        origin,
+        code: error.code,
+        message: error.message,
+      });
+    }
+    if (isVersionConflict(error)) {
+      const cached = await loadCommandReceipt({ projectId, idempotencyKey });
+      if (cached) return cached;
+      return createCommandFailure({
+        commandId,
+        projectId,
+        origin,
+        code: 'REVISION_CONFLICT',
+        revision: getConflictRevision(error),
+        message:
+          command.type === 'canvas.apply'
+            ? 'Project snapshot version conflict'
+            : 'Timeline version conflict',
+      });
+    }
+    if (error instanceof Error && error.message === 'Project not found') {
+      return createCommandFailure({
+        commandId,
+        projectId,
+        origin,
+        code: 'NOT_FOUND',
+        message: 'Project not found',
+      });
+    }
+    return createCommandFailure({
+      commandId,
+      projectId,
+      origin,
+      code: 'COMMAND_FAILED',
+      message:
+        error instanceof Error ? error.message : 'The command could not be saved.',
+    });
+  }
+}
+
+export function persistBeatDesignCommand({
+  projectId,
+  origin,
+  commandId = createCommandId(),
+  expectedRevision,
+  idempotencyKey,
+  command,
+}: {
+  projectId: string;
+  origin: BeatDesignCommandOrigin;
+  commandId?: string;
+  expectedRevision?: number | null;
+  idempotencyKey?: string | null;
+  command: BeatDesignCommand;
+}): Promise<BeatDesignCommandResult<BeatDesignCommandData>> {
+  if (
+    command.type === 'editor.replace_document' &&
+    origin !== 'ui' &&
+    origin !== 'system'
+  ) {
+    return Promise.resolve(
+      createCommandFailure({
+        commandId,
+        projectId,
+        origin,
+        code: 'INVALID_COMMAND',
+        message:
+          'External agents must use editor.apply operations instead of replacing the timeline document.',
+      })
+    );
+  }
+  try {
+    validateExternalCommandAssetReferences({ origin, command });
+  } catch (error) {
+    if (error instanceof BeatDesignCommandError) {
+      return Promise.resolve(
+        createCommandFailure({
+          commandId,
+          projectId,
+          origin,
+          code: error.code,
+          message: error.message,
+        })
+      );
+    }
+    throw error;
+  }
+  const stableIdempotencyKey = idempotencyKey?.trim() || commandId;
+  const lockKey = `${projectId}:${stableIdempotencyKey}`;
+  const existing = inFlightCommands.get(lockKey);
+  if (existing) {
+    if (
+      existing.commandId !== commandId ||
+      existing.commandType !== command.type
+    ) {
+      return Promise.resolve(
+        createCommandFailure({
+          commandId,
+          projectId,
+          origin,
+          code: 'INVALID_COMMAND',
+          message: 'Idempotency key is already bound to a different command.',
+        })
+      );
+    }
+    return existing.promise;
+  }
+
+  const promise = persistBeatDesignCommandOnce({
+    projectId,
+    origin,
+    commandId,
+    expectedRevision,
+    idempotencyKey: stableIdempotencyKey,
+    command,
+  }).finally(() => {
+    if (inFlightCommands.get(lockKey)?.promise === promise) {
+      inFlightCommands.delete(lockKey);
+    }
+  });
+  inFlightCommands.set(lockKey, {
+    commandId,
+    commandType: command.type,
+    promise,
+  });
+  return promise;
+}
diff --git a/src/core/commands/receipts.ts b/src/core/commands/receipts.ts
new file mode 100644
index 0000000..cf44cc9
--- /dev/null
+++ b/src/core/commands/receipts.ts
@@ -0,0 +1,160 @@
+import { randomUUID } from 'node:crypto';
+import { and, desc, eq, inArray, lt, or } from 'drizzle-orm';
+
+import { projectCommandReceipt } from '@/config/db/schema';
+import { getDb } from '@/core/workspace-lib/db-adapter';
+
+import {
+  BeatDesignCommandError,
+  type BeatDesignCommandResult,
+} from './contracts';
+import type { BeatDesignCommandData } from './executor';
+
+export type StoredCommandResult = BeatDesignCommandResult<BeatDesignCommandData>;
+
+const RECEIPT_RETENTION_MS = 24 * 60 * 60 * 1000;
+const MAX_RECEIPTS_PER_PROJECT = 2_000;
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+const lastCleanupByProject = new Map<string, number>();
+
+async function cleanupCommandReceipts(projectId: string) {
+  const now = Date.now();
+  const lastCleanup = lastCleanupByProject.get(projectId) ?? 0;
+  if (now - lastCleanup < CLEANUP_INTERVAL_MS) return;
+  lastCleanupByProject.set(projectId, now);
+
+  const db = await getDb();
+  const overflow = await db
+    .select({ id: projectCommandReceipt.id })
+    .from(projectCommandReceipt)
+    .where(eq(projectCommandReceipt.projectId, projectId))
+    .orderBy(desc(projectCommandReceipt.createdAt))
+    .limit(500)
+    .offset(MAX_RECEIPTS_PER_PROJECT);
+  const overflowIds = overflow.map((receipt: { id: string }) => receipt.id);
+  await db
+    .delete(projectCommandReceipt)
+    .where(
+      and(
+        eq(projectCommandReceipt.projectId, projectId),
+        or(
+          lt(
+            projectCommandReceipt.createdAt,
+            new Date(now - RECEIPT_RETENTION_MS)
+          ),
+          overflowIds.length > 0
+            ? inArray(projectCommandReceipt.id, overflowIds)
+            : undefined
+        )
+      )
+    );
+}
+
+export async function loadCommandReceipt({
+  projectId,
+  idempotencyKey,
+}: {
+  projectId: string;
+  idempotencyKey: string;
+}) {
+  const record = await loadCommandReceiptRecord({ projectId, idempotencyKey });
+  return record?.result ?? null;
+}
+
+export async function listCommandReceipts({
+  projectId,
+  limit = 50,
+}: {
+  projectId: string;
+  limit?: number;
+}) {
+  const db = await getDb();
+  return db
+    .select({
+      commandId: projectCommandReceipt.commandId,
+      idempotencyKey: projectCommandReceipt.idempotencyKey,
+      origin: projectCommandReceipt.origin,
+      commandType: projectCommandReceipt.commandType,
+      result: projectCommandReceipt.resultJson,
+      createdAt: projectCommandReceipt.createdAt,
+    })
+    .from(projectCommandReceipt)
+    .where(eq(projectCommandReceipt.projectId, projectId))
+    .orderBy(desc(projectCommandReceipt.createdAt))
+    .limit(Math.max(1, Math.min(200, Math.floor(limit))));
+}
+
+export async function loadCommandReceiptRecord({
+  projectId,
+  idempotencyKey,
+}: {
+  projectId: string;
+  idempotencyKey: string;
+}) {
+  const db = await getDb();
+  const rows = await db
+    .select({
+      commandId: projectCommandReceipt.commandId,
+      commandType: projectCommandReceipt.commandType,
+      resultJson: projectCommandReceipt.resultJson,
+    })
+    .from(projectCommandReceipt)
+    .where(
+      and(
+        eq(projectCommandReceipt.projectId, projectId),
+        eq(projectCommandReceipt.idempotencyKey, idempotencyKey)
+      )
+    )
+    .limit(1);
+  const row = rows[0];
+  return row
+    ? {
+        commandId: row.commandId,
+        commandType: row.commandType,
+        result: row.resultJson as StoredCommandResult,
+      }
+    : null;
+}
+
+export async function storeCommandReceipt({
+  projectId,
+  idempotencyKey,
+  commandId,
+  origin,
+  commandType,
+  result,
+}: {
+  projectId: string;
+  idempotencyKey: string;
+  commandId: string;
+  origin: string;
+  commandType: string;
+  result: StoredCommandResult;
+}) {
+  const db = await getDb();
+  await db
+    .insert(projectCommandReceipt)
+    .values({
+      id: randomUUID(),
+      projectId,
+      idempotencyKey,
+      commandId,
+      origin,
+      commandType,
+      resultJson: result,
+      createdAt: new Date(),
+    })
+    .onConflictDoNothing();
+  await cleanupCommandReceipts(projectId);
+  const stored = await loadCommandReceiptRecord({ projectId, idempotencyKey });
+  if (
+    stored &&
+    (stored.commandId !== commandId || stored.commandType !== commandType)
+  ) {
+    throw new BeatDesignCommandError(
+      'INVALID_COMMAND',
+      'Idempotency key is already bound to a different command.'
+    );
+  }
+  return stored?.result ?? result;
+}
diff --git a/src/core/commands/schema.ts b/src/core/commands/schema.ts
new file mode 100644
index 0000000..0063521
--- /dev/null
+++ b/src/core/commands/schema.ts
@@ -0,0 +1,375 @@
+import { z } from 'zod';
+
+import type { CanvasCard } from '@/core/beatcanvas/canvas-types';
+import { normalizeTimelineDocument } from '@/core/editor/timeline-document';
+
+import { repairCanvasCardInput } from './canvas-card-repair';
+import type { BeatDesignCommand } from './executor';
+
+const commandIdSchema = z.string().trim().min(1).max(200);
+const finiteTimeSchema = z.number().finite().min(0).max(86_400);
+const positiveDurationSchema = z.number().finite().positive().max(86_400);
+
+const frameSchema = z
+  .object({
+    x: z.number().finite(),
+    y: z.number().finite(),
+    w: z.number().finite().positive(),
+    h: z.number().finite().positive(),
+  })
+  .strict();
+
+const canvasCardStatusSchema = z.enum([
+  'idle',
+  'pending',
+  'processing',
+  'succeeded',
+  'failed',
+]);
+const generationModeSchema = z.enum(['image', 'video', 'analysis']);
+const analysisDepthSchema = z.enum(['standard', 'deep']);
+const aspectRatioSchema = z.enum([
+  '16:9',
+  '21:9',
+  '4:3',
+  '5:4',
+  '9:16',
+  '9:21',
+  '3:4',
+  '1:1',
+  '1:2',
+  '2:1',
+  '1:3',
+  '3:1',
+  '2:3',
+  '3:2',
+  '4:5',
+  'auto',
+  'adaptive',
+  'landscape',
+  'portrait',
+]);
+const outputQualitySchema = z.enum([
+  '1k',
+  '2k',
+  '480p',
+  '720p',
+  '768p',
+  '1080p',
+  '4k',
+  'std',
+  'pro',
+]);
+const durationSchema = z
+  .string()
+  .trim()
+  .regex(/^\d+(?:\.\d+)?s$/, 'Duration must use a value such as 5s or 3.5s.')
+  .max(20);
+const languageSchema = z.enum(['zh', 'en']);
+const modelModeSchema = z.enum(['quality', 'fast', 'lite']);
+const modelVariantSchema = z.enum(['standard', 'pro']);
+const qualitySchema = z.enum(['standard', 'high', 'low', 'medium']);
+const characterOrientationSchema = z.enum(['image', 'video']);
+const backgroundSourceSchema = z.enum(['input_image', 'input_video']);
+const audioRoleSchema = z.enum([
+  'music',
+  'voice',
+  'sound_effect',
+  'source_audio',
+  'reference',
+]);
+
+const generationSnapshotSchema = z
+  .object({
+    type: z.enum(['image', 'video']),
+    generationMode: generationModeSchema.optional(),
+    analysisDepth: analysisDepthSchema.optional(),
+    prompt: z.string().max(20_000).default(''),
+    referenceCardIds: z.array(commandIdSchema).max(20).default([]),
+    workflowTemplateId: commandIdSchema.nullable().default(null),
+    modelId: z.string().trim().max(200).default(''),
+    aspectRatio: aspectRatioSchema.default('1:1'),
+    outputQuality: outputQualitySchema.default('1k'),
+    duration: durationSchema.default('5s'),
+    language: languageSchema.optional(),
+    mode: modelModeSchema.default('quality'),
+    variant: modelVariantSchema.default('standard'),
+    quality: qualitySchema.default('standard'),
+    characterOrientation: characterOrientationSchema.optional(),
+    backgroundSource: backgroundSourceSchema.optional(),
+    resultText: z.string().max(100_000).nullable().optional(),
+    capturedAt: z.string().trim().min(1).max(80),
+  })
+  .strict();
+
+const canvasCardCommonShape = {
+  id: commandIdSchema,
+  assetId: commandIdSchema.nullable().optional(),
+  generationMode: generationModeSchema.optional(),
+  analysisDepth: analysisDepthSchema.optional(),
+  name: z.string().trim().min(1).max(500),
+  url: z.string().trim().max(4096).nullable().default(null),
+  resultText: z.string().max(100_000).nullable().optional(),
+  prompt: z.string().max(20_000).default(''),
+  referenceCardIds: z.array(commandIdSchema).max(20).default([]),
+  workflowTemplateId: commandIdSchema.nullable().default(null),
+  status: canvasCardStatusSchema.default('idle'),
+  error: z.string().max(20_000).nullable().default(null),
+  modelId: z.string().trim().max(200).default(''),
+  aspectRatio: aspectRatioSchema.default('1:1'),
+  outputQuality: outputQualitySchema.default('1k'),
+  duration: durationSchema.default('5s'),
+  language: languageSchema.optional(),
+  mode: modelModeSchema.default('quality'),
+  variant: modelVariantSchema.default('standard'),
+  quality: qualitySchema.default('standard'),
+  characterOrientation: characterOrientationSchema.optional(),
+  backgroundSource: backgroundSourceSchema.optional(),
+  sourceGenerationId: commandIdSchema.nullable().default(null),
+  sourceConfigCardId: commandIdSchema.nullable().optional(),
+  generationRunId: commandIdSchema.nullable().optional(),
+  generationSnapshot: generationSnapshotSchema.nullable().optional(),
+  pinnedOutputId: commandIdSchema.nullable().optional(),
+  audioRole: audioRoleSchema.optional(),
+  durationSec: finiteTimeSchema.nullable().optional(),
+  waveformPeaks: z.array(z.number().finite().min(0).max(1)).max(256).optional(),
+  timelineId: commandIdSchema.nullable().optional(),
+  clipCount: z.number().int().min(0).max(10_000).nullable().optional(),
+  lastRenderAssetId: commandIdSchema.nullable().optional(),
+};
+
+/**
+ * Public Canvas card contract used by UI commands and MCP tool discovery.
+ * Keep this explicit: an opaque `unknown` schema makes the tool impossible for
+ * an Agent to call reliably even when runtime validation later succeeds.
+ */
+const canvasCardUnion = z.discriminatedUnion('kind', [
+  z
+    .object({
+      ...canvasCardCommonShape,
+      kind: z.literal('asset'),
+      type: z.enum(['image', 'video', 'audio', 'timeline']),
+    })
+    .strict(),
+  z
+    .object({
+      ...canvasCardCommonShape,
+      kind: z.literal('generation'),
+      type: z.enum(['image', 'video']),
+    })
+    .strict(),
+  z
+    .object({
+      ...canvasCardCommonShape,
+      kind: z.literal('output'),
+      type: z.enum(['image', 'video']),
+      sourceConfigCardId: commandIdSchema,
+      generationRunId: commandIdSchema,
+      generationSnapshot: generationSnapshotSchema,
+    })
+    .strict(),
+]);
+
+export const canvasCardSchema = z.preprocess(
+  repairCanvasCardInput,
+  canvasCardUnion
+) as z.ZodType<CanvasCard>;
+
+const timelineDocumentSchema = z.unknown().transform((value, context) => {
+  try {
+    return normalizeTimelineDocument(value);
+  } catch (error) {
+    context.addIssue({
+      code: 'custom',
+      message:
+        error instanceof Error ? error.message : 'Timeline document is invalid.',
+    });
+    return z.NEVER;
+  }
+});
+
+export const canvasOperationSchema = z.discriminatedUnion('type', [
+  z
+    .object({
+      type: z.literal('upsert_card'),
+      card: canvasCardSchema,
+      frame: frameSchema.optional(),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('remove_card'),
+      cardId: commandIdSchema,
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('move_card'),
+      cardId: commandIdSchema,
+      frame: frameSchema,
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('set_references'),
+      cardId: commandIdSchema,
+      referenceCardIds: z.array(commandIdSchema).max(20),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('upsert_timeline_node'),
+      timelineId: commandIdSchema,
+      name: z.string().trim().min(1).max(240),
+      durationSec: finiteTimeSchema,
+      clipCount: z.number().int().min(0).max(10_000),
+      lastRenderAssetId: commandIdSchema.nullable().optional(),
+      lastRenderUrl: z.string().trim().max(4096).nullable().optional(),
+      referenceCardIds: z.array(commandIdSchema).max(20).optional(),
+      frame: frameSchema.optional(),
+    })
+    .strict(),
+]);
+
+export const editorOperationSchema = z.discriminatedUnion('type', [
+  z
+    .object({
+      type: z.literal('add_clip'),
+      clipId: commandIdSchema,
+      assetId: commandIdSchema,
+      sourceUrl: z.string().trim().max(4096).optional().default(''),
+      name: z.string().trim().min(1).max(240),
+      sourceType: z.enum(['image', 'video', 'audio']),
+      sourceDuration: positiveDurationSchema,
+      startTime: finiteTimeSchema.optional(),
+      audioRole: z.enum(['music', 'voice', 'sfx', 'source']).optional(),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('trim_clip'),
+      clipId: commandIdSchema,
+      inPoint: finiteTimeSchema,
+      outPoint: positiveDurationSchema,
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('split_clip'),
+      clipId: commandIdSchema,
+      sourceTime: finiteTimeSchema,
+      rightClipId: commandIdSchema,
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('move_clip'),
+      clipId: commandIdSchema,
+      startTime: finiteTimeSchema,
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('set_clip_duration'),
+      clipId: commandIdSchema,
+      duration: positiveDurationSchema,
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('remove_clip'),
+      clipId: commandIdSchema,
+      ripple: z.boolean().optional(),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('update_audio'),
+      clipId: commandIdSchema,
+      patch: z
+        .object({
+          volume: z.number().finite().min(0).max(4).optional(),
+          muted: z.boolean().optional(),
+          fadeIn: finiteTimeSchema.optional(),
+          fadeOut: finiteTimeSchema.optional(),
+        })
+        .strict()
+        .refine((value) => Object.keys(value).length > 0, {
+          message: 'Audio update must include at least one field.',
+        }),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('add_take'),
+      clipId: commandIdSchema,
+      take: z
+        .object({
+          id: commandIdSchema,
+          assetId: commandIdSchema,
+          sourceUrl: z.string().trim().max(4096).optional().default(''),
+          name: z.string().trim().min(1).max(240),
+          sourceDuration: positiveDurationSchema,
+          sourceGenerationId: commandIdSchema.nullable(),
+          prompt: z.string().max(20_000),
+          createdAt: z.string().trim().min(1).max(80).optional(),
+        })
+        .strict(),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('activate_take'),
+      clipId: commandIdSchema,
+      takeId: commandIdSchema.nullable(),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('set_render'),
+      assetId: commandIdSchema,
+      publicUrl: z.string().trim().max(4096).optional().default(''),
+    })
+    .strict(),
+]);
+
+export const beatDesignCommandSchema: z.ZodType<BeatDesignCommand> =
+  z.discriminatedUnion('type', [
+    z
+      .object({
+        type: z.literal('canvas.apply'),
+        operations: z.array(canvasOperationSchema).min(1).max(500),
+      })
+      .strict(),
+    z
+      .object({
+        type: z.literal('editor.apply'),
+        operations: z.array(editorOperationSchema).min(1).max(500),
+      })
+      .strict(),
+    z
+      .object({
+        type: z.literal('editor.replace_document'),
+        document: timelineDocumentSchema,
+      })
+      .strict(),
+    z.object({ type: z.literal('editor.validate') }).strict(),
+  ]);
+
+const commandRequestBaseSchema = z
+  .object({
+    commandId: commandIdSchema.optional(),
+    expectedRevision: z.number().int().min(0).nullable().optional(),
+    idempotencyKey: commandIdSchema.nullable().optional(),
+    command: beatDesignCommandSchema,
+  })
+  .strict();
+
+/**
+ * Public UI requests never choose their own origin. The transport boundary
+ * assigns `ui`, while MCP/CLI callers invoke the kernel through their own
+ * trusted entrypoints.
+ */
+export const uiCommandRequestSchema = commandRequestBaseSchema;
+
+export type ParsedUiCommandRequest = z.infer<typeof uiCommandRequestSchema>;
diff --git a/src/core/editor/beatapi-redo.test.ts b/src/core/editor/beatapi-redo.test.ts
new file mode 100644
index 0000000..64cd0dc
--- /dev/null
+++ b/src/core/editor/beatapi-redo.test.ts
@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { redoTimelineSelection } from './beatapi-redo';
+
+test('selection redo uploads one derived clip and returns a localized Take', async () => {
+  const statuses: string[] = [];
+  let generatedInput: Record<string, unknown> | undefined;
+  const result = await redoTimelineSelection({
+    projectId: 'project-1',
+    file: new File(['video'], 'selection.mp4', { type: 'video/mp4' }),
+    prompt: '  Make the camera move slowly  ',
+    durationSec: 3.6,
+    onStatus: (status) => statuses.push(status),
+    precheckEffectImpl: (async (payload: {
+      expectedUploadCount?: number;
+      input: Record<string, unknown>;
+    }) => {
+      assert.equal(payload.expectedUploadCount, 1);
+      assert.equal(payload.input.wmDuration, '4s');
+      return {
+        ok: true,
+        status: 200,
+        data: { uploadIntentToken: 'intent-1' },
+      };
+    }) as never,
+    uploadFileImpl: (async () => ({
+      url: 'https://media.beatapi.io/inputs/selection.mp4',
+      key: 'selection.mp4',
+    })) as never,
+    generateEffectImpl: (async (payload: { input: Record<string, unknown> }) => {
+      generatedInput = payload.input;
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          status: 'processing',
+          wmTaskId: 'generation-1',
+        },
+      };
+    }) as never,
+    getEffectStatusImpl: (async () => ({
+      ok: true,
+      status: 200,
+      data: {
+        status: 'succeeded',
+        output: {
+          stored_result_url: '/api/app/projects/project-1/assets/asset-ai',
+          assetIds: ['asset-ai'],
+        },
+      },
+    })) as never,
+    sleepImpl: async () => undefined,
+  });
+
+  assert.deepEqual(generatedInput?.video_urls, [
+    'https://media.beatapi.io/inputs/selection.mp4',
+  ]);
+  assert.equal(result.resultUrl, '/api/app/projects/project-1/assets/asset-ai');
+  assert.equal(result.assetId, 'asset-ai');
+  assert.equal(result.generationId, 'generation-1');
+  assert.deepEqual(statuses, [
+    'validating',
+    'uploading',
+    'submitting',
+    'processing',
+    'succeeded',
+  ]);
+});
+
+test('selection redo failure does not return or mutate a Take', async () => {
+  await assert.rejects(
+    redoTimelineSelection({
+      projectId: 'project-1',
+      file: new File(['video'], 'selection.mp4', { type: 'video/mp4' }),
+      prompt: 'Redo',
+      durationSec: 5,
+      precheckEffectImpl: (async () => ({
+        ok: false,
+        status: 400,
+        data: { error: 'Insufficient credits' },
+      })) as never,
+    }),
+    /Insufficient credits/
+  );
+});
diff --git a/src/core/editor/beatapi-redo.ts b/src/core/editor/beatapi-redo.ts
new file mode 100644
index 0000000..931f920
--- /dev/null
+++ b/src/core/editor/beatapi-redo.ts
@@ -0,0 +1,118 @@
+import {
+  generateEffect,
+  getEffectStatus,
+  precheckEffect,
+  resolveWmTaskId,
+} from '@/core/effects/client-api';
+import { resolveOutputMedia } from '@/core/effects/output-media';
+import { uploadFileFromBrowser } from '@/core/workspace-storage/client';
+
+export const EDITOR_REDO_EFFECT_ID = 9;
+export const EDITOR_REDO_MODEL_ID = 'seedance-2';
+
+const readAssetId = (output: unknown) => {
+  if (!output || typeof output !== 'object') return null;
+  const value = (output as Record<string, unknown>).assetIds;
+  return Array.isArray(value) && typeof value[0] === 'string' ? value[0] : null;
+};
+
+const sleep = (ms: number) =>
+  new Promise<void>((resolve) => window.setTimeout(resolve, ms));
+
+export async function redoTimelineSelection({
+  projectId,
+  file,
+  prompt,
+  durationSec,
+  onStatus,
+  precheckEffectImpl = precheckEffect,
+  uploadFileImpl = uploadFileFromBrowser,
+  generateEffectImpl = generateEffect,
+  getEffectStatusImpl = getEffectStatus,
+  sleepImpl = sleep,
+  maxAttempts = 120,
+}: {
+  projectId: string;
+  file: File;
+  prompt: string;
+  durationSec: number;
+  onStatus?: (status: string) => void;
+  precheckEffectImpl?: typeof precheckEffect;
+  uploadFileImpl?: typeof uploadFileFromBrowser;
+  generateEffectImpl?: typeof generateEffect;
+  getEffectStatusImpl?: typeof getEffectStatus;
+  sleepImpl?: (ms: number) => Promise<void>;
+  maxAttempts?: number;
+}) {
+  const trimmedPrompt = prompt.trim();
+  if (!trimmedPrompt) throw new Error('Describe how the selected clip should change.');
+  const duration = `${Math.max(4, Math.min(15, Math.round(durationSec)))}s`;
+  const baseInput: Record<string, unknown> = {
+    prompt: trimmedPrompt,
+    aspect_ratio: 'adaptive',
+    wmDuration: duration,
+    wmOutputQuality: '720p',
+  };
+
+  onStatus?.('validating');
+  const precheck = await precheckEffectImpl({
+    effectId: EDITOR_REDO_EFFECT_ID,
+    input: baseInput,
+    projectId,
+    expectedUploadCount: 1,
+  });
+  if (!precheck.ok || !precheck.data.uploadIntentToken) {
+    throw new Error(precheck.data.error || 'BeatAPI request validation failed.');
+  }
+
+  onStatus?.('uploading');
+  const uploaded = await uploadFileImpl(file, 'beateditor/redo', {
+    projectId,
+    generationIntentToken: precheck.data.uploadIntentToken,
+  });
+  const input = { ...baseInput, video_urls: [uploaded.url] };
+
+  onStatus?.('submitting');
+  const created = await generateEffectImpl({
+    effectId: EDITOR_REDO_EFFECT_ID,
+    input,
+    projectId,
+    generationIntentToken: precheck.data.uploadIntentToken,
+  });
+  if (!created.ok || created.data.status === 'failed') {
+    throw new Error(created.data.error || 'BeatAPI generation failed.');
+  }
+
+  const generationId = resolveWmTaskId(created.data);
+  let output = created.data.output;
+  if (created.data.status !== 'succeeded') {
+    if (!generationId) throw new Error('BeatAPI task id is missing.');
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      onStatus?.('processing');
+      const status = await getEffectStatusImpl({
+        wmTaskId: generationId,
+        effectId: EDITOR_REDO_EFFECT_ID,
+        syncProvider: 1,
+      });
+      if (!status.ok || status.data.status === 'failed') {
+        throw new Error(status.data.error || 'BeatAPI generation failed.');
+      }
+      output = status.data.output ?? output;
+      if (status.data.status === 'succeeded') break;
+      if (attempt === maxAttempts - 1) {
+        throw new Error('BeatAPI generation timed out.');
+      }
+      await sleepImpl(5_000);
+    }
+  }
+
+  const resultUrl = resolveOutputMedia(output).resultUrl;
+  if (!resultUrl) throw new Error('BeatAPI completed without a video result.');
+  onStatus?.('succeeded');
+  return {
+    resultUrl,
+    assetId: readAssetId(output),
+    generationId,
+    output,
+  };
+}
diff --git a/src/core/editor/media-export.ts b/src/core/editor/media-export.ts
new file mode 100644
index 0000000..1a92162
--- /dev/null
+++ b/src/core/editor/media-export.ts
@@ -0,0 +1,433 @@
+import {
+  getTimelineClipSource,
+  type TimelineClip,
+  type TimelineDocument,
+} from './timeline-document';
+import { diagnoseTimeline } from './timeline-diagnostics';
+
+export type LocalMediaMetadata = {
+  duration: number;
+  width: number | null;
+  height: number | null;
+  hasVideo: boolean;
+  hasAudio: boolean;
+  videoCodec: string | null;
+  audioCodec: string | null;
+};
+
+export async function inspectLocalMedia(file: File): Promise<LocalMediaMetadata> {
+  const { ALL_FORMATS, BlobSource, Input } = await import('mediabunny');
+  const input = new Input({ source: new BlobSource(file), formats: ALL_FORMATS });
+
+  try {
+    const [duration, videoTrack, audioTrack] = await Promise.all([
+      input.computeDuration(),
+      input.getPrimaryVideoTrack(),
+      input.getPrimaryAudioTrack(),
+    ]);
+
+    return {
+      duration,
+      width: videoTrack?.displayWidth ?? null,
+      height: videoTrack?.displayHeight ?? null,
+      hasVideo: Boolean(videoTrack),
+      hasAudio: Boolean(audioTrack),
+      videoCodec: videoTrack?.codec ?? null,
+      audioCodec: audioTrack?.codec ?? null,
+    };
+  } finally {
+    input.dispose();
+  }
+}
+
+export async function exportTrimmedMp4({
+  file,
+  start,
+  end,
+  onProgress,
+}: {
+  file: File;
+  start: number;
+  end: number;
+  onProgress?: (progress: number) => void;
+}) {
+  if (!(end > start)) throw new Error('The export range is empty.');
+
+  const {
+    ALL_FORMATS,
+    BlobSource,
+    BufferTarget,
+    Conversion,
+    Input,
+    Mp4OutputFormat,
+    Output,
+    QUALITY_HIGH,
+  } = await import('mediabunny');
+
+  const input = new Input({ source: new BlobSource(file), formats: ALL_FORMATS });
+  const target = new BufferTarget();
+  const output = new Output({
+    format: new Mp4OutputFormat({ fastStart: 'in-memory' }),
+    target,
+  });
+
+  try {
+    const conversion = await Conversion.init({
+      input,
+      output,
+      trim: { start, end },
+      video: {
+        codec: 'avc',
+        bitrate: QUALITY_HIGH,
+        forceTranscode: true,
+        keyFrameInterval: 1,
+      },
+      showWarnings: false,
+    });
+
+    if (!conversion.isValid) {
+      const reasons = conversion.discardedTracks
+        .map(({ reason }) => reason.replaceAll('_', ' '))
+        .join(', ');
+      throw new Error(`This browser cannot export the selected media${reasons ? `: ${reasons}` : '.'}`);
+    }
+
+    conversion.onProgress = (progress) => onProgress?.(progress);
+    await conversion.execute();
+
+    if (!target.buffer) throw new Error('The encoder produced no MP4 data.');
+    onProgress?.(1);
+    return new Blob([target.buffer], { type: 'video/mp4' });
+  } finally {
+    input.dispose();
+  }
+}
+
+type TimelineMediaRecord = {
+  clip: TimelineClip;
+  source: ReturnType<typeof getTimelineClipSource>;
+  input: import('mediabunny').Input | null;
+  videoTrack: import('mediabunny').InputVideoTrack | null;
+  audioTrack: import('mediabunny').InputAudioTrack | null;
+  imageBitmap: ImageBitmap | null;
+};
+
+const throwIfAborted = (signal?: AbortSignal) => {
+  if (signal?.aborted) throw new DOMException('Export cancelled.', 'AbortError');
+};
+
+async function loadTimelineMedia(
+  document: TimelineDocument,
+  signal?: AbortSignal
+) {
+  const { ALL_FORMATS, BlobSource, Input } = await import('mediabunny');
+  const records: TimelineMediaRecord[] = [];
+  try {
+    for (const track of document.tracks) {
+      if (track.hidden || track.muted) continue;
+      for (const clip of track.clips) {
+        throwIfAborted(signal);
+        const source = getTimelineClipSource(clip);
+        const response = await fetch(source.sourceUrl, { signal });
+        if (!response.ok) {
+          throw new Error(`Timeline source is unavailable: ${source.name}`);
+        }
+        const blob = await response.blob();
+        if (clip.sourceType === 'image') {
+          const imageBitmap = await createImageBitmap(blob);
+          records.push({
+            clip,
+            source,
+            input: null,
+            videoTrack: null,
+            audioTrack: null,
+            imageBitmap,
+          });
+          continue;
+        }
+        const input = new Input({
+          source: new BlobSource(blob),
+          formats: ALL_FORMATS,
+        });
+        try {
+          const [videoTrack, audioTrack] = await Promise.all([
+            input.getPrimaryVideoTrack(),
+            input.getPrimaryAudioTrack(),
+          ]);
+          records.push({
+            clip,
+            source,
+            input,
+            videoTrack,
+            audioTrack,
+            imageBitmap: null,
+          });
+        } catch (error) {
+          input.dispose();
+          throw error;
+        }
+      }
+    }
+    return records;
+  } catch (error) {
+    disposeTimelineMediaRecords(records);
+    throw error;
+  }
+}
+
+function disposeTimelineMediaRecords(records: TimelineMediaRecord[]) {
+  for (const record of records) {
+    record.input?.dispose();
+    record.imageBitmap?.close();
+  }
+}
+
+function drawImageWithContain(
+  context: CanvasRenderingContext2D,
+  image: CanvasImageSource,
+  imageWidth: number,
+  imageHeight: number,
+  width: number,
+  height: number
+) {
+  const scale = Math.min(width / imageWidth, height / imageHeight);
+  const drawWidth = imageWidth * scale;
+  const drawHeight = imageHeight * scale;
+  context.drawImage(
+    image,
+    (width - drawWidth) / 2,
+    (height - drawHeight) / 2,
+    drawWidth,
+    drawHeight
+  );
+}
+
+function gainAt(clip: TimelineClip, clipOffset: number) {
+  if (clip.muted) return 0;
+  const fadeIn = clip.fadeIn > 0 ? Math.min(1, clipOffset / clip.fadeIn) : 1;
+  const fadeOut =
+    clip.fadeOut > 0
+      ? Math.min(1, (clip.duration - clipOffset) / clip.fadeOut)
+      : 1;
+  return Math.max(0, Math.min(1, clip.volume * Math.min(fadeIn, fadeOut)));
+}
+
+async function mixTimelineAudio(
+  records: TimelineMediaRecord[],
+  duration: number,
+  sampleRate: number,
+  signal?: AbortSignal
+) {
+  const { AudioBufferSink } = await import('mediabunny');
+  const context = new OfflineAudioContext({
+    numberOfChannels: 2,
+    length: Math.max(1, Math.ceil(duration * sampleRate)),
+    sampleRate,
+  });
+  let scheduled = false;
+
+  for (const record of records) {
+    if (!record.audioTrack || record.clip.muted) continue;
+    const sink = new AudioBufferSink(record.audioTrack);
+    for await (const wrapped of sink.buffers(
+      record.source.inPoint,
+      record.source.outPoint
+    )) {
+      throwIfAborted(signal);
+      const segmentStart = Math.max(record.source.inPoint, wrapped.timestamp);
+      const segmentEnd = Math.min(
+        record.source.outPoint,
+        wrapped.timestamp + wrapped.buffer.duration
+      );
+      const segmentDuration = segmentEnd - segmentStart;
+      if (segmentDuration <= 0) continue;
+
+      const timelineStart =
+        record.clip.startTime + (segmentStart - record.source.inPoint);
+      const timelineEnd = Math.min(duration, timelineStart + segmentDuration);
+      if (timelineStart >= duration || timelineEnd <= timelineStart) continue;
+
+      const source = context.createBufferSource();
+      const gain = context.createGain();
+      source.buffer = wrapped.buffer;
+      source.connect(gain);
+      gain.connect(context.destination);
+      const startOffset = timelineStart - record.clip.startTime;
+      const endOffset = timelineEnd - record.clip.startTime;
+      gain.gain.setValueAtTime(gainAt(record.clip, startOffset), timelineStart);
+      gain.gain.linearRampToValueAtTime(
+        gainAt(record.clip, endOffset),
+        timelineEnd
+      );
+      source.start(
+        timelineStart,
+        Math.max(0, segmentStart - wrapped.timestamp),
+        timelineEnd - timelineStart
+      );
+      scheduled = true;
+    }
+  }
+
+  return scheduled ? context.startRendering() : null;
+}
+
+export async function exportTimelineMp4({
+  document,
+  onProgress,
+  signal,
+}: {
+  document: TimelineDocument;
+  onProgress?: (progress: number) => void;
+  signal?: AbortSignal;
+}) {
+  if (document.duration <= 0) throw new Error('The timeline is empty.');
+  const blocking = diagnoseTimeline(document).filter(
+    (diagnostic) => diagnostic.severity === 'error'
+  );
+  if (blocking.length > 0) {
+    throw new Error(`Timeline diagnostics failed: ${blocking[0].code}`);
+  }
+
+  const {
+    AudioBufferSource,
+    BufferTarget,
+    CanvasSource,
+    Mp4OutputFormat,
+    Output,
+    QUALITY_HIGH,
+    VideoSampleSink,
+  } = await import('mediabunny');
+  const records = await loadTimelineMedia(document, signal);
+  const firstVisual = records.find(
+    (record) => record.videoTrack || record.imageBitmap
+  );
+  if (!firstVisual) {
+    disposeTimelineMediaRecords(records);
+    throw new Error('The timeline does not contain a readable visual track.');
+  }
+
+  const visualWidth =
+    firstVisual.videoTrack?.displayWidth ?? firstVisual.imageBitmap?.width ?? 1920;
+  const visualHeight =
+    firstVisual.videoTrack?.displayHeight ?? firstVisual.imageBitmap?.height ?? 1080;
+  const portrait =
+    visualHeight > visualWidth;
+  const width = portrait ? 1080 : 1920;
+  const height = portrait ? 1920 : 1080;
+  const frameRate = 30;
+  const frameDuration = 1 / frameRate;
+  const sampleRate = 48_000;
+  const canvas = globalThis.document.createElement('canvas');
+  canvas.width = width;
+  canvas.height = height;
+  const context = canvas.getContext('2d', { alpha: false });
+  if (!context) {
+    disposeTimelineMediaRecords(records);
+    throw new Error('Canvas2D is unavailable in this browser.');
+  }
+
+  const target = new BufferTarget();
+  const output = new Output({
+    format: new Mp4OutputFormat({ fastStart: 'in-memory' }),
+    target,
+  });
+  const videoSource = new CanvasSource(canvas, {
+    codec: 'avc',
+    bitrate: QUALITY_HIGH,
+    keyFrameInterval: 1,
+  });
+  let mixedAudio: AudioBuffer | null;
+  try {
+    mixedAudio = await mixTimelineAudio(
+      records,
+      document.duration,
+      sampleRate,
+      signal
+    );
+  } catch (error) {
+    disposeTimelineMediaRecords(records);
+    throw error;
+  }
+  const audioSource = mixedAudio
+    ? new AudioBufferSource({ codec: 'aac', bitrate: 192_000 })
+    : null;
+  output.addVideoTrack(videoSource, { frameRate });
+  if (audioSource) output.addAudioTrack(audioSource);
+
+  try {
+    throwIfAborted(signal);
+    await output.start();
+    const visualRecords = records
+      .filter((record) => record.videoTrack || record.imageBitmap)
+      .sort((left, right) => left.clip.startTime - right.clip.startTime);
+    const sinks = new Map(
+      visualRecords
+        .filter((record) => record.videoTrack)
+        .map((record) => [
+        record.clip.id,
+        new VideoSampleSink(record.videoTrack!),
+      ])
+    );
+    const frameCount = Math.max(1, Math.ceil(document.duration * frameRate));
+    const audioPromise = audioSource?.add(mixedAudio!);
+
+    for (let frame = 0; frame < frameCount; frame += 1) {
+      throwIfAborted(signal);
+      const timelineTime = Math.min(document.duration, frame * frameDuration);
+      context.fillStyle = '#000';
+      context.fillRect(0, 0, width, height);
+      const active = [...visualRecords]
+        .reverse()
+        .find(
+          (record) =>
+            timelineTime >= record.clip.startTime &&
+            timelineTime < record.clip.startTime + record.clip.duration
+        );
+      if (active?.imageBitmap) {
+        drawImageWithContain(
+          context,
+          active.imageBitmap,
+          active.imageBitmap.width,
+          active.imageBitmap.height,
+          width,
+          height
+        );
+      } else if (active?.videoTrack) {
+        const sourceTime = Math.min(
+          active.source.outPoint - 0.000_001,
+          active.source.inPoint + (timelineTime - active.clip.startTime)
+        );
+        const sample = await sinks.get(active.clip.id)!.getSample(sourceTime);
+        if (sample) {
+          sample.drawWithFit(context, { fit: 'contain' });
+          sample.close();
+        }
+      }
+      await videoSource.add(timelineTime, frameDuration, {
+        keyFrame: frame % frameRate === 0,
+      });
+      onProgress?.(((frame + 1) / frameCount) * 0.95);
+    }
+
+    await audioPromise;
+    throwIfAborted(signal);
+    await output.finalize();
+    if (!target.buffer) throw new Error('The encoder produced no MP4 data.');
+    onProgress?.(1);
+    return new Blob([target.buffer], { type: 'video/mp4' });
+  } catch (cause) {
+    if (output.state === 'started') await output.cancel().catch(() => undefined);
+    throw cause;
+  } finally {
+    disposeTimelineMediaRecords(records);
+  }
+}
+
+export function downloadBlob(blob: Blob, filename: string) {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = filename;
+  anchor.click();
+  window.setTimeout(() => URL.revokeObjectURL(url), 30_000);
+}
diff --git a/src/core/editor/timeline-client.ts b/src/core/editor/timeline-client.ts
new file mode 100644
index 0000000..7733cd6
--- /dev/null
+++ b/src/core/editor/timeline-client.ts
@@ -0,0 +1,133 @@
+import type { RecentAsset } from '@/core/workspace-lib/app/workspace-client-api';
+import { createCommandId } from '@/core/commands/contracts';
+import { executeProjectCommand } from '@/core/commands/client';
+import type { EditorOperation } from '@/core/commands/editor-commands';
+import type { TimelineDocument } from '@/core/editor/timeline-document';
+import { apiJsonGet } from '@/lib/api-client';
+
+type TimelineStatePayload = {
+  timeline: { document: TimelineDocument; version: number } | null;
+};
+
+export const loadBrowserMediaDuration = (
+  url: string,
+  mediaType: 'video' | 'audio'
+) =>
+  new Promise<number>((resolve, reject) => {
+    const element = document.createElement(mediaType);
+    const cleanup = () => {
+      element.removeAttribute('src');
+      element.load();
+    };
+    element.preload = 'metadata';
+    element.onloadedmetadata = () => {
+      const duration = element.duration;
+      cleanup();
+      if (Number.isFinite(duration) && duration > 0) resolve(duration);
+      else reject(new Error('Media duration is unavailable'));
+    };
+    element.onerror = () => {
+      cleanup();
+      reject(new Error('Media metadata could not be loaded'));
+    };
+    element.src = url;
+  });
+
+export const DEFAULT_IMAGE_CLIP_DURATION = 3;
+
+export async function addProjectAssetToTimeline({
+  projectId,
+  projectName,
+  asset,
+  mediaType,
+}: {
+  projectId: string;
+  projectName?: string;
+  asset: RecentAsset;
+  mediaType: 'image' | 'video' | 'audio';
+}) {
+  return addProjectAssetsToTimeline({
+    projectId,
+    projectName,
+    assets: [{ asset, mediaType }],
+  });
+}
+
+export async function addProjectAssetsToTimeline({
+  projectId,
+  projectName: _projectName,
+  assets,
+}: {
+  projectId: string;
+  projectName?: string;
+  assets: Array<{
+    asset: RecentAsset;
+    mediaType: 'image' | 'video' | 'audio';
+  }>;
+}) {
+  if (assets.length === 0) throw new Error('Select at least one timeline asset');
+  if (assets.some(({ asset }) => !asset.id?.trim())) {
+    throw new Error('Timeline clips must reference a project asset');
+  }
+  const uniqueAssets = Array.from(
+    new Map(assets.map((entry) => [entry.asset.id, entry])).values()
+  );
+  const prepared = await Promise.all(
+    uniqueAssets.map(async ({ asset, mediaType }) => ({
+      asset,
+      mediaType,
+      sourceDuration:
+        mediaType === 'image'
+          ? DEFAULT_IMAGE_CLIP_DURATION
+          : typeof asset.durationMs === 'number' && asset.durationMs > 0
+            ? asset.durationMs / 1000
+            : await loadBrowserMediaDuration(asset.publicUrl, mediaType),
+    }))
+  );
+  const batchId = createCommandId();
+  const operations: EditorOperation[] = prepared.map(
+    ({ asset, mediaType, sourceDuration }, index) => ({
+      type: 'add_clip' as const,
+      clipId: `clip:${batchId}:${asset.id}:${index}`,
+      assetId: asset.id,
+      sourceUrl: '',
+      name:
+        asset.filename?.trim() ||
+        (mediaType === 'audio'
+          ? 'Audio'
+          : mediaType === 'image'
+            ? 'Image'
+            : 'Video'),
+      sourceType: mediaType,
+      sourceDuration,
+      ...(mediaType === 'audio'
+        ? { startTime: 0, audioRole: 'music' as const }
+        : {}),
+    })
+  );
+
+  const endpoint = `/api/app/projects/${encodeURIComponent(projectId)}/timeline`;
+  const initial = await apiJsonGet<TimelineStatePayload>(endpoint);
+  const execute = (expectedRevision: number | null) =>
+    executeProjectCommand({
+      projectId,
+      commandId: batchId,
+      idempotencyKey: batchId,
+      expectedRevision,
+      command: { type: 'editor.apply', operations },
+    });
+  let result = await execute(initial.timeline?.version ?? null);
+  if (!result.ok && result.code === 'REVISION_CONFLICT') {
+    const latest = await apiJsonGet<TimelineStatePayload>(endpoint);
+    result = await execute(latest.timeline?.version ?? null);
+  }
+  if (!result.ok || !result.data.timeline || typeof result.revision !== 'number') {
+    throw new Error(result.ok ? 'Timeline command returned no document' : result.message);
+  }
+  return {
+    timeline: {
+      document: result.data.timeline,
+      version: result.revision,
+    },
+  };
+}
diff --git a/src/core/editor/timeline-diagnostics.test.ts b/src/core/editor/timeline-diagnostics.test.ts
new file mode 100644
index 0000000..b7281be
--- /dev/null
+++ b/src/core/editor/timeline-diagnostics.test.ts
@@ -0,0 +1,123 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  activateTimelineTake,
+  addTimelineTake,
+  addSourceClip,
+  createTimelineDocument,
+  type TimelineDocument,
+} from './timeline-document';
+import { diagnoseTimeline } from './timeline-diagnostics';
+
+test('a normal video-only timeline does not warn about its structural audio track', () => {
+  let document = createTimelineDocument({ projectId: 'p1', name: 'Timeline' });
+  document = addSourceClip(document, {
+    assetId: 'v1',
+    sourceUrl: '/v1.mp4',
+    name: 'One',
+    sourceType: 'video',
+    sourceDuration: 2,
+  });
+
+  assert.deepEqual(diagnoseTimeline(document), []);
+});
+
+test('timeline diagnostics report an unexplained video gap and a missing source', () => {
+    let document = createTimelineDocument({ projectId: 'p1', name: 'Timeline' });
+    document = addSourceClip(document, {
+      assetId: 'v1',
+      sourceUrl: '/v1.mp4',
+      name: 'One',
+      sourceType: 'video',
+      sourceDuration: 2,
+    });
+    document = addSourceClip(document, {
+      assetId: 'v2',
+      sourceUrl: '',
+      name: 'Two',
+      sourceType: 'video',
+      sourceDuration: 1,
+      startTime: 4,
+    });
+
+    const diagnostics = diagnoseTimeline(document);
+    assert.ok(
+      diagnostics.some(
+        (diagnostic) =>
+          diagnostic.code === 'timeline_gap' &&
+          diagnostic.severity === 'error' &&
+          diagnostic.startTime === 2 &&
+          diagnostic.endTime === 4
+      )
+    );
+    assert.ok(
+      diagnostics.some(
+        (diagnostic) =>
+          diagnostic.code === 'media_missing' && diagnostic.severity === 'error'
+      )
+    );
+});
+
+test('timeline diagnostics report overlap in a malformed persisted document', () => {
+    let document = createTimelineDocument({ projectId: 'p1', name: 'Timeline' });
+    document = addSourceClip(document, {
+      assetId: 'v1',
+      sourceUrl: '/v1.mp4',
+      name: 'One',
+      sourceType: 'video',
+      sourceDuration: 2,
+    });
+    document = addSourceClip(document, {
+      assetId: 'v2',
+      sourceUrl: '/v2.mp4',
+      name: 'Two',
+      sourceType: 'video',
+      sourceDuration: 2,
+    });
+    const [first, second] = document.tracks[0].clips;
+    const malformed: TimelineDocument = {
+      ...document,
+      tracks: document.tracks.map((track) =>
+        track.kind === 'video'
+          ? {
+              ...track,
+              clips: [first, { ...second, startTime: 1 }],
+            }
+          : track
+      ),
+    };
+
+    assert.ok(
+      diagnoseTimeline(malformed).some(
+        (diagnostic) =>
+          diagnostic.code === 'clip_overlap' && diagnostic.severity === 'error'
+      )
+    );
+});
+
+test('a take shorter than its clip cannot be activated', () => {
+  const document = createTimelineDocument({
+    projectId: 'project-1',
+    name: 'Timeline 1',
+  });
+  const withClip = addSourceClip(document, {
+    clipId: 'clip-1',
+    assetId: 'asset-1',
+    sourceUrl: '/video.mp4',
+    name: 'Video',
+    sourceType: 'video',
+    sourceDuration: 4,
+  });
+  const withShortTake = addTimelineTake(withClip, 'clip-1', {
+    id: 'take-1',
+    assetId: 'take-asset',
+    sourceUrl: '/take.mp4',
+    name: 'Short Take',
+    sourceDuration: 3,
+    sourceGenerationId: 'generation-1',
+    prompt: 'Redo',
+  });
+  assert.equal(withShortTake, withClip);
+  assert.equal(activateTimelineTake(withShortTake, 'clip-1', 'take-1'), withShortTake);
+});
diff --git a/src/core/editor/timeline-diagnostics.ts b/src/core/editor/timeline-diagnostics.ts
new file mode 100644
index 0000000..e70e065
--- /dev/null
+++ b/src/core/editor/timeline-diagnostics.ts
@@ -0,0 +1,117 @@
+import type { TimelineDocument, TimelineTrack } from './timeline-document';
+
+export type TimelineDiagnosticCode =
+  | 'timeline_gap'
+  | 'clip_overlap'
+  | 'media_missing'
+  | 'take_duration_mismatch'
+  | 'caption_overlap'
+  | 'caption_out_of_video'
+  | 'tiny_clip'
+  | 'empty_track';
+
+export type TimelineDiagnostic = {
+  code: TimelineDiagnosticCode;
+  severity: 'error' | 'warning';
+  trackId?: string;
+  clipId?: string;
+  startTime?: number;
+  endTime?: number;
+};
+
+const byStartTime = <T extends { startTime: number }>(left: T, right: T) =>
+  left.startTime - right.startTime;
+
+function diagnoseTrackOverlap(track: TimelineTrack) {
+  const diagnostics: TimelineDiagnostic[] = [];
+  const clips = [...track.clips].sort(byStartTime);
+  for (let index = 1; index < clips.length; index += 1) {
+    const previous = clips[index - 1];
+    const current = clips[index];
+    if (current.startTime < previous.startTime + previous.duration - 0.001) {
+      diagnostics.push({
+        code: 'clip_overlap',
+        severity: 'error',
+        trackId: track.id,
+        clipId: current.id,
+        startTime: current.startTime,
+        endTime: Math.min(
+          previous.startTime + previous.duration,
+          current.startTime + current.duration
+        ),
+      });
+    }
+  }
+  return diagnostics;
+}
+
+export function diagnoseTimeline(document: TimelineDocument) {
+  const diagnostics: TimelineDiagnostic[] = [];
+
+  for (const track of document.tracks) {
+    diagnostics.push(...diagnoseTrackOverlap(track));
+    for (const clip of track.clips) {
+      const source = clip.activeTakeId
+        ? clip.takes.find((take) => take.id === clip.activeTakeId)?.sourceUrl
+        : clip.sourceUrl;
+      if (!source) {
+        diagnostics.push({
+          code: 'media_missing',
+          severity: 'error',
+          trackId: track.id,
+          clipId: clip.id,
+        });
+      }
+      const activeTake = clip.activeTakeId
+        ? clip.takes.find((take) => take.id === clip.activeTakeId)
+        : null;
+      if (activeTake && activeTake.sourceDuration < clip.duration - 0.05) {
+        diagnostics.push({
+          code: 'take_duration_mismatch',
+          severity: 'error',
+          trackId: track.id,
+          clipId: clip.id,
+          startTime: clip.startTime,
+          endTime: clip.startTime + clip.duration,
+        });
+      }
+      if (clip.duration < 0.1) {
+        diagnostics.push({
+          code: 'tiny_clip',
+          severity: 'warning',
+          trackId: track.id,
+          clipId: clip.id,
+        });
+      }
+    }
+  }
+
+  const videoClips = document.tracks
+    .filter((track) => track.kind === 'video' && !track.hidden)
+    .flatMap((track) => track.clips)
+    .sort(byStartTime);
+  let visibleVideoEnd = 0;
+  for (const clip of videoClips) {
+    if (clip.startTime > visibleVideoEnd + 1 / 30) {
+      diagnostics.push({
+        code: 'timeline_gap',
+        severity: 'error',
+        trackId: clip.trackId,
+        clipId: clip.id,
+        startTime: visibleVideoEnd,
+        endTime: clip.startTime,
+      });
+    }
+    visibleVideoEnd = Math.max(visibleVideoEnd, clip.startTime + clip.duration);
+  }
+  if (videoClips.length > 0 && document.duration > visibleVideoEnd + 1 / 30) {
+    diagnostics.push({
+      code: 'timeline_gap',
+      severity: 'error',
+      startTime: visibleVideoEnd,
+      endTime: document.duration,
+    });
+  }
+
+  return diagnostics;
+}
diff --git a/src/core/editor/timeline-document.test.ts b/src/core/editor/timeline-document.test.ts
new file mode 100644
index 0000000..da70c76
--- /dev/null
+++ b/src/core/editor/timeline-document.test.ts
@@ -0,0 +1,253 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  addSourceClip,
+  activateTimelineTake,
+  addTimelineTake,
+  calculateTimelineDuration,
+  createTimelineDocument,
+  findTimelineClip,
+  getTimelineClipSource,
+  normalizeTimelineDocument,
+  moveTimelineClip,
+  rippleDeleteTimelineClip,
+  resizeTimelineClip,
+  updateTimelineAudioClip,
+  splitTimelineClip,
+  trimTimelineClip,
+} from './timeline-document';
+
+test('a ten-second source can be trimmed to a precise four-second clip', () => {
+  const empty = createTimelineDocument({
+    projectId: 'project-1',
+    name: 'Demo',
+  });
+  const imported = addSourceClip(empty, {
+    assetId: 'asset-1',
+    sourceUrl: '/media/asset-1.mp4',
+    name: 'ten-seconds.mp4',
+    sourceType: 'video',
+    sourceDuration: 10,
+  });
+  const clip = imported.tracks.flatMap((track) => track.clips)[0];
+  assert.ok(clip);
+
+  const trimmed = trimTimelineClip(imported, clip.id, 3, 7);
+  const result = findTimelineClip(trimmed, clip.id);
+
+  assert.equal(result?.inPoint, 3);
+  assert.equal(result?.outPoint, 7);
+  assert.equal(result?.duration, 4);
+  assert.equal(calculateTimelineDuration(trimmed.tracks), 4);
+});
+
+test('version 1 timelines migrate with empty Take and render state', () => {
+  const current = createTimelineDocument({ projectId: 'project-1', name: 'Demo' });
+  const legacy = {
+    ...current,
+    schemaVersion: 1,
+    tracks: current.tracks.map((track) => ({
+      ...track,
+      clips: track.clips.map(({ takes: _takes, activeTakeId: _active, ...clip }) => clip),
+    })),
+  };
+  delete (legacy as Partial<typeof current>).lastRenderAssetId;
+  delete (legacy as Partial<typeof current>).lastRenderUrl;
+
+  const migrated = normalizeTimelineDocument(legacy, 'project-1');
+  assert.equal(migrated.schemaVersion, 3);
+  assert.equal(migrated.lastRenderAssetId, null);
+});
+
+test('version 2 timelines migrate the visual track without losing clips', () => {
+  const withVideo = addSourceClip(
+    createTimelineDocument({ projectId: 'project-1', name: 'Demo' }),
+    {
+      assetId: 'video-1',
+      sourceUrl: '/video.mp4',
+      name: 'video.mp4',
+      sourceType: 'video',
+      sourceDuration: 4,
+    }
+  );
+  const legacy = {
+    ...withVideo,
+    schemaVersion: 2,
+    tracks: withVideo.tracks.map((track) => ({
+      ...track,
+      name: track.kind === 'video' ? 'Video 1' : track.name,
+    })),
+  };
+  const migrated = normalizeTimelineDocument(legacy, 'project-1');
+  assert.equal(migrated.schemaVersion, 3);
+  assert.equal(migrated.tracks[0]?.name, 'Visual 1');
+  assert.equal(migrated.tracks[0]?.clips.length, 1);
+});
+
+test('image clips share the visual track and can change still duration', () => {
+  const imported = addSourceClip(
+    createTimelineDocument({ projectId: 'project-1', name: 'Demo' }),
+    {
+      assetId: 'image-1',
+      sourceUrl: '/still.png',
+      name: 'still.png',
+      sourceType: 'image',
+      sourceDuration: 3,
+    }
+  );
+  const clip = imported.tracks.find((track) => track.kind === 'video')?.clips[0];
+  assert.ok(clip);
+  assert.equal(clip.sourceType, 'image');
+  const resized = resizeTimelineClip(imported, clip.id, 5.5);
+  const result = findTimelineClip(resized, clip.id);
+  assert.equal(result?.duration, 5.5);
+  assert.equal(result?.sourceDuration, 5.5);
+  assert.equal(calculateTimelineDuration(resized.tracks), 5.5);
+});
+
+test('a generated Take can replace a clip and roll back without changing the original', () => {
+  const imported = addSourceClip(
+    createTimelineDocument({ projectId: 'project-1', name: 'Demo' }),
+    {
+      assetId: 'asset-original',
+      sourceUrl: '/original.mp4',
+      name: 'original.mp4',
+      sourceType: 'video',
+      sourceDuration: 10,
+    }
+  );
+  const original = imported.tracks.flatMap((track) => track.clips)[0];
+  assert.ok(original);
+  const trimmed = trimTimelineClip(imported, original.id, 3, 7);
+  const withTake = addTimelineTake(trimmed, original.id, {
+    id: 'take-1',
+    assetId: 'asset-ai',
+    sourceUrl: '/ai.mp4',
+    name: 'AI Take',
+    sourceDuration: 4.1,
+    sourceGenerationId: 'generation-1',
+    prompt: 'Make it cinematic',
+  });
+  const active = activateTimelineTake(withTake, original.id, 'take-1');
+  const activeClip = findTimelineClip(active, original.id);
+  assert.ok(activeClip);
+  assert.equal(getTimelineClipSource(activeClip).sourceUrl, '/ai.mp4');
+  assert.equal(activeClip.assetId, 'asset-original');
+  assert.equal(activeClip.inPoint, 3);
+  assert.equal(activeClip.outPoint, 7);
+
+  const rolledBack = activateTimelineTake(active, original.id, null);
+  const rolledBackClip = findTimelineClip(rolledBack, original.id);
+  assert.ok(rolledBackClip);
+  assert.equal(getTimelineClipSource(rolledBackClip).sourceUrl, '/original.mp4');
+});
+
+test('splitting is non-destructive and preserves the selected source range', () => {
+  const empty = createTimelineDocument({ projectId: 'project-1', name: 'Demo' });
+  const imported = addSourceClip(empty, {
+    assetId: 'asset-1',
+    sourceUrl: '/media/asset-1.mp4',
+    name: 'ten-seconds.mp4',
+    sourceType: 'video',
+    sourceDuration: 10,
+  });
+  const original = imported.tracks.flatMap((track) => track.clips)[0];
+  assert.ok(original);
+  const trimmed = trimTimelineClip(imported, original.id, 3, 7);
+  const split = splitTimelineClip(trimmed, original.id, 5);
+  const clips = split.tracks.flatMap((track) => track.clips);
+
+  assert.equal(clips.length, 2);
+  assert.deepEqual(
+    clips.map(({ inPoint, outPoint, duration, startTime }) => ({
+      inPoint,
+      outPoint,
+      duration,
+      startTime,
+    })),
+    [
+      { inPoint: 3, outPoint: 5, duration: 2, startTime: 0 },
+      { inPoint: 5, outPoint: 7, duration: 2, startTime: 2 },
+    ]
+  );
+  assert.equal(calculateTimelineDuration(split.tracks), 4);
+});
+
+test('invalid trims and edge splits keep the original document unchanged', () => {
+  const empty = createTimelineDocument({ projectId: 'project-1', name: 'Demo' });
+  const imported = addSourceClip(empty, {
+    assetId: 'asset-1',
+    sourceUrl: '/media/asset-1.mp4',
+    name: 'ten-seconds.mp4',
+    sourceType: 'video',
+    sourceDuration: 10,
+  });
+  const clip = imported.tracks.flatMap((track) => track.clips)[0];
+  assert.ok(clip);
+
+  assert.equal(trimTimelineClip(imported, clip.id, 4, 4), imported);
+  assert.equal(splitTimelineClip(imported, clip.id, 0), imported);
+  assert.equal(splitTimelineClip(imported, clip.id, 10), imported);
+});
+
+test('video clips append on the video track instead of after a longer audio bed', () => {
+  const empty = createTimelineDocument({ projectId: 'project-1', name: 'Demo' });
+  const withAudio = addSourceClip(empty, {
+    assetId: 'audio-1',
+    sourceUrl: '/music.mp3',
+    name: 'music.mp3',
+    sourceType: 'audio',
+    sourceDuration: 30,
+    startTime: 0,
+  });
+  const withVideo = addSourceClip(withAudio, {
+    assetId: 'video-1',
+    sourceUrl: '/shot.mp4',
+    name: 'shot.mp4',
+    sourceType: 'video',
+    sourceDuration: 5,
+  });
+  const video = withVideo.tracks
+    .find((track) => track.kind === 'video')
+    ?.clips[0];
+  assert.equal(video?.startTime, 0);
+});
+
+test('move rejects overlap and ripple delete closes the removed gap', () => {
+  let timeline = createTimelineDocument({ projectId: 'project-1', name: 'Demo' });
+  timeline = addSourceClip(timeline, {
+    assetId: 'video-1', sourceUrl: '/1.mp4', name: '1', sourceType: 'video', sourceDuration: 3,
+  });
+  timeline = addSourceClip(timeline, {
+    assetId: 'video-2', sourceUrl: '/2.mp4', name: '2', sourceType: 'video', sourceDuration: 3,
+  });
+  const [first, second] = timeline.tracks.find((track) => track.kind === 'video')!.clips;
+  assert.ok(first && second);
+  assert.equal(moveTimelineClip(timeline, second.id, 2), timeline);
+  const moved = moveTimelineClip(timeline, second.id, 4);
+  assert.equal(findTimelineClip(moved, second.id)?.startTime, 4);
+  const deleted = rippleDeleteTimelineClip(moved, first.id);
+  assert.equal(findTimelineClip(deleted, second.id)?.startTime, 1);
+});
+
+test('audio volume, mute, and fades are non-destructive clip settings', () => {
+  const imported = addSourceClip(
+    createTimelineDocument({ projectId: 'project-1', name: 'Demo' }),
+    {
+      assetId: 'audio-1', sourceUrl: '/music.mp3', name: 'music', sourceType: 'audio', sourceDuration: 5,
+    }
+  );
+  const clip = imported.tracks.find((track) => track.kind === 'audio')!.clips[0]!;
+  const updated = updateTimelineAudioClip(imported, clip.id, {
+    volume: 0.5,
+    muted: true,
+    fadeIn: 1,
+    fadeOut: 1.5,
+  });
+  const result = findTimelineClip(updated, clip.id);
+  assert.equal(result?.volume, 0.5);
+  assert.equal(result?.muted, true);
+  assert.equal(result?.fadeIn, 1);
+  assert.equal(result?.fadeOut, 1.5);
+});
diff --git a/src/core/editor/timeline-document.ts b/src/core/editor/timeline-document.ts
new file mode 100644
index 0000000..74ab23a
--- /dev/null
+++ b/src/core/editor/timeline-document.ts
@@ -0,0 +1,706 @@
+/**
+ * BeatDesign's compact timeline contract is derived from OpenReel's MIT-licensed
+ * Timeline / Track / Clip model. It deliberately keeps only the fields needed by
+ * the local-first editing workflow so the host app owns persistence and UI.
+ *
+ * OpenReel source pin: 5f3c85e5fc223c86060bf4b12e1b4dec58e9b8a9
+ * Copyright (c) 2024-2026 Augustus Otu and Contributors
+ */
+
+import { z } from 'zod';
+
+export const TIMELINE_SCHEMA_VERSION = 3 as const;
+
+export type TimelineTrackKind = 'video' | 'audio' | 'caption';
+export type TimelineAudioRole = 'music' | 'voice' | 'sfx' | 'source';
+
+export type TimelineTake = {
+  id: string;
+  assetId: string;
+  sourceUrl: string;
+  name: string;
+  sourceDuration: number;
+  sourceGenerationId: string | null;
+  prompt: string;
+  createdAt: string;
+};
+
+export type TimelineClip = {
+  id: string;
+  assetId: string;
+  sourceUrl: string;
+  trackId: string;
+  name: string;
+  sourceType: 'image' | 'video' | 'audio';
+  startTime: number;
+  duration: number;
+  inPoint: number;
+  outPoint: number;
+  sourceDuration: number;
+  volume: number;
+  muted: boolean;
+  fadeIn: number;
+  fadeOut: number;
+  audioRole?: TimelineAudioRole;
+  takes: TimelineTake[];
+  activeTakeId: string | null;
+};
+
+export type TimelineTrack = {
+  id: string;
+  kind: TimelineTrackKind;
+  name: string;
+  locked: boolean;
+  hidden: boolean;
+  muted: boolean;
+  clips: TimelineClip[];
+};
+
+export type TimelineDocument = {
+  schemaVersion: typeof TIMELINE_SCHEMA_VERSION;
+  id: string;
+  projectId: string;
+  name: string;
+  createdAt: string;
+  updatedAt: string;
+  duration: number;
+  lastRenderAssetId: string | null;
+  lastRenderUrl: string | null;
+  tracks: TimelineTrack[];
+};
+
+export const MAX_TIMELINE_DOCUMENT_BYTES = 2 * 1024 * 1024;
+
+export class TimelineDocumentValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'TimelineDocumentValidationError';
+  }
+}
+
+const timelineClipSchema = z.object({
+  id: z.string().min(1).max(160),
+  assetId: z.string().min(1).max(160),
+  sourceUrl: z.string().min(1).max(4096),
+  trackId: z.string().min(1).max(160),
+  name: z.string().min(1).max(240),
+  sourceType: z.enum(['image', 'video', 'audio']),
+  startTime: z.number().finite().min(0).max(86_400),
+  duration: z.number().finite().positive().max(86_400),
+  inPoint: z.number().finite().min(0).max(86_400),
+  outPoint: z.number().finite().positive().max(86_400),
+  sourceDuration: z.number().finite().positive().max(86_400),
+  volume: z.number().finite().min(0).max(4),
+  muted: z.boolean(),
+  fadeIn: z.number().finite().min(0).max(86_400).default(0),
+  fadeOut: z.number().finite().min(0).max(86_400).default(0),
+  audioRole: z.enum(['music', 'voice', 'sfx', 'source']).optional(),
+  takes: z
+    .array(
+      z.object({
+        id: z.string().min(1).max(160),
+        assetId: z.string().min(1).max(160),
+        sourceUrl: z.string().min(1).max(4096),
+        name: z.string().min(1).max(240),
+        sourceDuration: z.number().finite().positive().max(86_400),
+        sourceGenerationId: z.string().min(1).max(200).nullable(),
+        prompt: z.string().max(20_000),
+        createdAt: z.string().min(1).max(80),
+      })
+    )
+    .max(100)
+    .default([]),
+  activeTakeId: z.string().min(1).max(160).nullable().default(null),
+});
+
+const timelineTrackSchema = z.object({
+  id: z.string().min(1).max(160),
+  kind: z.enum(['video', 'audio', 'caption']),
+  name: z.string().min(1).max(120),
+  locked: z.boolean(),
+  hidden: z.boolean(),
+  muted: z.boolean(),
+  clips: z.array(timelineClipSchema).max(1_000),
+});
+
+const timelineDocumentSchema = z.object({
+  schemaVersion: z.literal(TIMELINE_SCHEMA_VERSION),
+  id: z.string().min(1).max(160),
+  projectId: z.string().min(1).max(160),
+  name: z.string().min(1).max(240),
+  createdAt: z.string().min(1).max(80),
+  updatedAt: z.string().min(1).max(80),
+  duration: z.number().finite().min(0).max(86_400),
+  lastRenderAssetId: z.string().min(1).max(160).nullable().default(null),
+  lastRenderUrl: z.string().min(1).max(4096).nullable().default(null),
+  tracks: z.array(timelineTrackSchema).min(1).max(64),
+});
+
+const createId = (prefix: string) => `${prefix}-${crypto.randomUUID()}`;
+
+const finiteNonNegative = (value: number) =>
+  Number.isFinite(value) ? Math.max(0, value) : 0;
+
+const roundTime = (value: number) => Math.round(value * 1000) / 1000;
+
+export function calculateTimelineDuration(tracks: readonly TimelineTrack[]) {
+  return roundTime(
+    tracks.reduce(
+      (timelineEnd, track) =>
+        track.clips.reduce(
+          (trackEnd, clip) =>
+            Math.max(trackEnd, clip.startTime + clip.duration),
+          timelineEnd
+        ),
+      0
+    )
+  );
+}
+
+export function createTimelineDocument({
+  projectId,
+  name,
+}: {
+  projectId: string;
+  name: string;
+}): TimelineDocument {
+  const now = new Date().toISOString();
+  return {
+    schemaVersion: TIMELINE_SCHEMA_VERSION,
+    id: createId('timeline'),
+    projectId,
+    name,
+    createdAt: now,
+    updatedAt: now,
+    duration: 0,
+    lastRenderAssetId: null,
+    lastRenderUrl: null,
+    tracks: [
+      {
+        id: createId('video-track'),
+        kind: 'video',
+        name: 'Visual 1',
+        locked: false,
+        hidden: false,
+        muted: false,
+        clips: [],
+      },
+      {
+        id: createId('audio-track'),
+        kind: 'audio',
+        name: 'Audio 1',
+        locked: false,
+        hidden: false,
+        muted: false,
+        clips: [],
+      },
+    ],
+  };
+}
+
+function withUpdatedTracks(
+  document: TimelineDocument,
+  tracks: TimelineTrack[]
+): TimelineDocument {
+  return {
+    ...document,
+    tracks,
+    duration: calculateTimelineDuration(tracks),
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+export function addSourceClip(
+  document: TimelineDocument,
+  source: {
+    assetId: string;
+    sourceUrl?: string;
+    name: string;
+    sourceType: 'image' | 'video' | 'audio';
+    sourceDuration: number;
+    startTime?: number;
+    audioRole?: TimelineAudioRole;
+    clipId?: string;
+  }
+) {
+  const sourceDuration = roundTime(finiteNonNegative(source.sourceDuration));
+  if (sourceDuration <= 0) return document;
+
+  const targetKind = source.sourceType === 'audio' ? 'audio' : 'video';
+  const existingTrack = document.tracks.find((track) => track.kind === targetKind);
+  if (!existingTrack) return document;
+  if (
+    source.clipId &&
+    existingTrack.clips.some((clip) => clip.id === source.clipId)
+  ) {
+    return document;
+  }
+
+  const startTime = roundTime(
+    finiteNonNegative(
+      source.startTime ??
+        existingTrack.clips.reduce(
+          (end, candidate) =>
+            Math.max(end, candidate.startTime + candidate.duration),
+          0
+        )
+    )
+  );
+  const clip: TimelineClip = {
+    id: source.clipId?.trim() || createId('clip'),
+    assetId: source.assetId,
+    sourceUrl: source.sourceUrl ?? '',
+    trackId: existingTrack.id,
+    name: source.name,
+    sourceType: source.sourceType,
+    startTime,
+    duration: sourceDuration,
+    inPoint: 0,
+    outPoint: sourceDuration,
+    sourceDuration,
+    volume: 1,
+    muted: false,
+    fadeIn: 0,
+    fadeOut: 0,
+    audioRole: source.audioRole,
+    takes: [],
+    activeTakeId: null,
+  };
+
+  return withUpdatedTracks(
+    document,
+    document.tracks.map((track) =>
+      track.id === existingTrack.id
+        ? { ...track, clips: [...track.clips, clip] }
+        : track
+    )
+  );
+}
+
+export function normalizeTimelineDocument(
+  value: unknown,
+  expectedProjectId?: string
+): TimelineDocument {
+  const version =
+    value && typeof value === 'object'
+      ? (value as { schemaVersion?: unknown }).schemaVersion
+      : null;
+  const legacyDocument = value as Record<string, unknown>;
+  const migrated =
+    version === 1 || version === 2
+      ? {
+          ...legacyDocument,
+          schemaVersion: TIMELINE_SCHEMA_VERSION,
+          lastRenderAssetId:
+            version === 1 ? null : (legacyDocument.lastRenderAssetId ?? null),
+          lastRenderUrl:
+            version === 1 ? null : (legacyDocument.lastRenderUrl ?? null),
+          tracks: Array.isArray((value as { tracks?: unknown }).tracks)
+            ? ((value as { tracks: unknown[] }).tracks).map((track) =>
+                track && typeof track === 'object'
+                  ? {
+                      ...(track as Record<string, unknown>),
+                      name:
+                        (track as { name?: unknown }).name === 'Video 1'
+                          ? 'Visual 1'
+                          : (track as { name?: unknown }).name,
+                      clips: Array.isArray(
+                        (track as { clips?: unknown }).clips
+                      )
+                        ? ((track as { clips: unknown[] }).clips).map((clip) =>
+                            clip && typeof clip === 'object'
+                              ? {
+                                  ...(clip as Record<string, unknown>),
+                                  takes:
+                                    version === 1
+                                      ? []
+                                      : ((clip as { takes?: unknown }).takes ?? []),
+                                  activeTakeId:
+                                    version === 1
+                                      ? null
+                                      : ((clip as { activeTakeId?: unknown })
+                                          .activeTakeId ?? null),
+                                }
+                              : clip
+                          )
+                        : [],
+                    }
+                  : track
+              )
+            : [],
+        }
+      : value;
+  const parsedResult = timelineDocumentSchema.safeParse(migrated);
+  if (!parsedResult.success) {
+    throw new TimelineDocumentValidationError(
+      parsedResult.error.issues[0]?.message ?? 'Timeline document is invalid.'
+    );
+  }
+  const parsed = parsedResult.data;
+  if (expectedProjectId && parsed.projectId !== expectedProjectId) {
+    throw new TimelineDocumentValidationError(
+      'Timeline project id does not match the route project.'
+    );
+  }
+  for (const track of parsed.tracks) {
+    for (const clip of track.clips) {
+      if (clip.trackId !== track.id) {
+        throw new TimelineDocumentValidationError(
+          'Timeline clip points to a different track.'
+        );
+      }
+      if (clip.outPoint <= clip.inPoint || clip.outPoint > clip.sourceDuration) {
+        throw new TimelineDocumentValidationError(
+          'Timeline clip has an invalid source range.'
+        );
+      }
+      if (
+        clip.activeTakeId &&
+        !clip.takes.some((take) => take.id === clip.activeTakeId)
+      ) {
+        throw new TimelineDocumentValidationError(
+          'Timeline clip points to a missing take.'
+        );
+      }
+    }
+  }
+  return {
+    ...parsed,
+    duration: calculateTimelineDuration(parsed.tracks),
+  };
+}
+
+export function getTimelineClipSource(clip: TimelineClip) {
+  const take = clip.activeTakeId
+    ? clip.takes.find((candidate) => candidate.id === clip.activeTakeId)
+    : null;
+  return take
+    ? {
+        assetId: take.assetId,
+        sourceUrl: take.sourceUrl,
+        name: take.name,
+        sourceDuration: take.sourceDuration,
+        inPoint: 0,
+        outPoint: Math.min(take.sourceDuration, clip.duration),
+        take,
+      }
+    : {
+        assetId: clip.assetId,
+        sourceUrl: clip.sourceUrl,
+        name: clip.name,
+        sourceDuration: clip.sourceDuration,
+        inPoint: clip.inPoint,
+        outPoint: clip.outPoint,
+        take: null,
+      };
+}
+
+export function addTimelineTake(
+  document: TimelineDocument,
+  clipId: string,
+  input: Omit<TimelineTake, 'id' | 'createdAt'> & {
+    id?: string;
+    createdAt?: string;
+  }
+) {
+  const clip = findTimelineClip(document, clipId);
+  if (
+    !clip ||
+    clip.sourceType !== 'video' ||
+    input.sourceDuration < clip.duration - 0.05
+  ) {
+    return document;
+  }
+  const take: TimelineTake = {
+    ...input,
+    id: input.id ?? createId('take'),
+    createdAt: input.createdAt ?? new Date().toISOString(),
+    sourceDuration: roundTime(input.sourceDuration),
+  };
+  return withUpdatedTracks(
+    document,
+    document.tracks.map((track) => ({
+      ...track,
+      clips: track.clips.map((candidate) =>
+        candidate.id === clipId
+          ? {
+              ...candidate,
+              takes: [
+                ...candidate.takes.filter((item) => item.id !== take.id),
+                take,
+              ],
+            }
+          : candidate
+      ),
+    }))
+  );
+}
+
+export function activateTimelineTake(
+  document: TimelineDocument,
+  clipId: string,
+  takeId: string | null
+) {
+  const clip = findTimelineClip(document, clipId);
+  const take = takeId
+    ? clip?.takes.find((candidate) => candidate.id === takeId)
+    : null;
+  if (
+    !clip ||
+    (takeId && !take) ||
+    (take && take.sourceDuration < clip.duration - 0.05)
+  ) {
+    return document;
+  }
+  return withUpdatedTracks(
+    document,
+    document.tracks.map((track) => ({
+      ...track,
+      clips: track.clips.map((candidate) =>
+        candidate.id === clipId
+          ? { ...candidate, activeTakeId: takeId }
+          : candidate
+      ),
+    }))
+  );
+}
+
+export function setTimelineRender(
+  document: TimelineDocument,
+  asset: { id: string; publicUrl: string }
+): TimelineDocument {
+  return {
+    ...document,
+    lastRenderAssetId: asset.id,
+    lastRenderUrl: asset.publicUrl,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+export function findTimelineClip(
+  document: TimelineDocument,
+  clipId: string
+) {
+  return document.tracks
+    .flatMap((track) => track.clips)
+    .find((clip) => clip.id === clipId);
+}
+
+export function trimTimelineClip(
+  document: TimelineDocument,
+  clipId: string,
+  nextInPoint: number,
+  nextOutPoint: number
+) {
+  const clip = findTimelineClip(document, clipId);
+  if (!clip) return document;
+
+  const inPoint = roundTime(
+    Math.min(clip.sourceDuration, finiteNonNegative(nextInPoint))
+  );
+  const outPoint = roundTime(
+    Math.min(clip.sourceDuration, finiteNonNegative(nextOutPoint))
+  );
+  if (outPoint - inPoint < 0.04) return document;
+
+  return withUpdatedTracks(
+    document,
+    document.tracks.map((track) => ({
+      ...track,
+      clips: track.clips.map((candidate) =>
+        candidate.id === clipId
+          ? {
+              ...candidate,
+              inPoint,
+              outPoint,
+              duration: roundTime(outPoint - inPoint),
+            }
+          : candidate
+      ),
+    }))
+  );
+}
+
+export function resizeTimelineClip(
+  document: TimelineDocument,
+  clipId: string,
+  nextDuration: number
+) {
+  const clip = findTimelineClip(document, clipId);
+  if (!clip || clip.sourceType !== 'image') return document;
+  const duration = roundTime(finiteNonNegative(nextDuration));
+  if (duration < 0.04) return document;
+
+  return withUpdatedTracks(
+    document,
+    document.tracks.map((track) => ({
+      ...track,
+      clips: track.clips.map((candidate) =>
+        candidate.id === clipId
+          ? {
+              ...candidate,
+              duration,
+              inPoint: 0,
+              outPoint: duration,
+              sourceDuration: duration,
+            }
+          : candidate
+      ),
+    }))
+  );
+}
+
+export function splitTimelineClip(
+  document: TimelineDocument,
+  clipId: string,
+  sourceTime: number,
+  rightClipId?: string
+) {
+  const clip = findTimelineClip(document, clipId);
+  if (!clip || clip.activeTakeId) return document;
+  if (
+    rightClipId &&
+    document.tracks.some((track) =>
+      track.clips.some((candidate) => candidate.id === rightClipId)
+    )
+  ) {
+    return document;
+  }
+
+  const splitPoint = roundTime(sourceTime);
+  if (splitPoint - clip.inPoint < 0.04 || clip.outPoint - splitPoint < 0.04) {
+    return document;
+  }
+
+  const left: TimelineClip = {
+    ...clip,
+    outPoint: splitPoint,
+    duration: roundTime(splitPoint - clip.inPoint),
+  };
+  const right: TimelineClip = {
+    ...clip,
+    id: rightClipId?.trim() || createId('clip'),
+    startTime: roundTime(clip.startTime + left.duration),
+    inPoint: splitPoint,
+    duration: roundTime(clip.outPoint - splitPoint),
+  };
+
+  return withUpdatedTracks(
+    document,
+    document.tracks.map((track) => ({
+      ...track,
+      clips: track.clips.flatMap((candidate) =>
+        candidate.id === clipId ? [left, right] : [candidate]
+      ),
+    }))
+  );
+}
+
+export function removeTimelineClip(
+  document: TimelineDocument,
+  clipId: string
+) {
+  return withUpdatedTracks(
+    document,
+    document.tracks.map((track) => ({
+      ...track,
+      clips: track.clips.filter((clip) => clip.id !== clipId),
+    }))
+  );
+}
+
+export function moveTimelineClip(
+  document: TimelineDocument,
+  clipId: string,
+  nextStartTime: number
+) {
+  const clip = findTimelineClip(document, clipId);
+  if (!clip) return document;
+  const startTime = roundTime(finiteNonNegative(nextStartTime));
+  const endTime = startTime + clip.duration;
+  const track = document.tracks.find((candidate) => candidate.id === clip.trackId);
+  if (
+    track?.clips.some(
+      (candidate) =>
+        candidate.id !== clipId &&
+        startTime < candidate.startTime + candidate.duration &&
+        endTime > candidate.startTime
+    )
+  ) {
+    return document;
+  }
+  return withUpdatedTracks(
+    document,
+    document.tracks.map((candidate) => ({
+      ...candidate,
+      clips: candidate.clips.map((item) =>
+        item.id === clipId ? { ...item, startTime } : item
+      ),
+    }))
+  );
+}
+
+export function rippleDeleteTimelineClip(
+  document: TimelineDocument,
+  clipId: string
+) {
+  const clip = findTimelineClip(document, clipId);
+  if (!clip) return document;
+  return withUpdatedTracks(
+    document,
+    document.tracks.map((track) =>
+      track.id !== clip.trackId
+        ? track
+        : {
+            ...track,
+            clips: track.clips
+              .filter((candidate) => candidate.id !== clipId)
+              .map((candidate) =>
+                candidate.startTime > clip.startTime
+                  ? {
+                      ...candidate,
+                      startTime: roundTime(
+                        Math.max(clip.startTime, candidate.startTime - clip.duration)
+                      ),
+                    }
+                  : candidate
+              ),
+          }
+    )
+  );
+}
+
+export function updateTimelineAudioClip(
+  document: TimelineDocument,
+  clipId: string,
+  patch: Partial<Pick<TimelineClip, 'volume' | 'muted' | 'fadeIn' | 'fadeOut'>>
+) {
+  const clip = findTimelineClip(document, clipId);
+  if (!clip || clip.sourceType !== 'audio') return document;
+  return withUpdatedTracks(
+    document,
+    document.tracks.map((track) => ({
+      ...track,
+      clips: track.clips.map((candidate) =>
+        candidate.id === clipId
+          ? {
+              ...candidate,
+              volume:
+                typeof patch.volume === 'number'
+                  ? Math.max(0, Math.min(4, patch.volume))
+                  : candidate.volume,
+              muted: patch.muted ?? candidate.muted,
+              fadeIn:
+                typeof patch.fadeIn === 'number'
+                  ? Math.max(0, Math.min(candidate.duration, patch.fadeIn))
+                  : candidate.fadeIn,
+              fadeOut:
+                typeof patch.fadeOut === 'number'
+                  ? Math.max(0, Math.min(candidate.duration, patch.fadeOut))
+                  : candidate.fadeOut,
+            }
+          : candidate
+      ),
+    }))
+  );
+}
diff --git a/src/core/editor/timeline-interaction.test.ts b/src/core/editor/timeline-interaction.test.ts
new file mode 100644
index 0000000..feabfc7
--- /dev/null
+++ b/src/core/editor/timeline-interaction.test.ts
@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { addSourceClip, createTimelineDocument } from './timeline-document';
+import {
+  buildTimelineDragPreview,
+  timelineTimeFromClientX,
+} from './timeline-interaction';
+
+const makeTimeline = () => {
+  let document = createTimelineDocument({ projectId: 'project-1', name: 'Edit' });
+  document = addSourceClip(document, {
+    assetId: 'image-1',
+    sourceUrl: '/image-1.webp',
+    name: 'Image',
+    sourceType: 'image',
+    sourceDuration: 4,
+    startTime: 0,
+  });
+  document = addSourceClip(document, {
+    assetId: 'video-1',
+    sourceUrl: '/video-1.mp4',
+    name: 'Video',
+    sourceType: 'video',
+    sourceDuration: 8,
+    startTime: 4,
+  });
+  return document;
+};
+
+test('maps pointer coordinates to a clamped timeline time', () => {
+  assert.equal(
+    timelineTimeFromClientX({ clientX: 150, left: 100, width: 200, duration: 8 }),
+    2
+  );
+  assert.equal(
+    timelineTimeFromClientX({ clientX: 500, left: 100, width: 200, duration: 8 }),
+    8
+  );
+});
+
+test('resizes an image from either edge without crossing adjacent clips', () => {
+  const document = makeTimeline();
+  const image = document.tracks.flatMap((track) => track.clips)[0];
+
+  const shorter = buildTimelineDragPreview({
+    document,
+    clip: image,
+    mode: 'trim-end',
+    deltaTime: -2,
+  });
+  assert.equal(shorter.duration, 2);
+  assert.equal(shorter.outPoint, 2);
+
+  const blockedByVideo = buildTimelineDragPreview({
+    document,
+    clip: image,
+    mode: 'trim-end',
+    deltaTime: 3,
+  });
+  assert.equal(blockedByVideo.duration, 4);
+});
+
+test('left video trim advances source in point and preserves the right edge', () => {
+  const document = makeTimeline();
+  const video = document.tracks.flatMap((track) => track.clips)[1];
+  const preview = buildTimelineDragPreview({
+    document,
+    clip: video,
+    mode: 'trim-start',
+    deltaTime: 2,
+  });
+
+  assert.equal(preview.startTime, 6);
+  assert.equal(preview.inPoint, 2);
+  assert.equal(preview.duration, 6);
+  assert.equal(preview.startTime + preview.duration, 12);
+});
diff --git a/src/core/editor/timeline-interaction.ts b/src/core/editor/timeline-interaction.ts
new file mode 100644
index 0000000..d495328
--- /dev/null
+++ b/src/core/editor/timeline-interaction.ts
@@ -0,0 +1,128 @@
+import type { TimelineClip, TimelineDocument } from './timeline-document';
+
+export type TimelineDragMode = 'move' | 'trim-start' | 'trim-end';
+
+export type TimelineClipInteractionPreview = Pick<
+  TimelineClip,
+  'id' | 'startTime' | 'duration' | 'inPoint' | 'outPoint' | 'sourceDuration'
+>;
+
+const MIN_DURATION = 0.04;
+
+const roundTime = (value: number) => Math.round(value * 100) / 100;
+
+const clamp = (value: number, minimum: number, maximum: number) =>
+  Math.min(Math.max(value, minimum), Math.max(minimum, maximum));
+
+export function timelineTimeFromClientX({
+  clientX,
+  left,
+  width,
+  duration,
+}: {
+  clientX: number;
+  left: number;
+  width: number;
+  duration: number;
+}) {
+  if (!Number.isFinite(width) || width <= 0 || duration <= 0) return 0;
+  return roundTime(clamp((clientX - left) / width, 0, 1) * duration);
+}
+
+export function buildTimelineDragPreview({
+  document,
+  clip,
+  mode,
+  deltaTime,
+}: {
+  document: TimelineDocument;
+  clip: TimelineClip;
+  mode: TimelineDragMode;
+  deltaTime: number;
+}): TimelineClipInteractionPreview {
+  const track = document.tracks.find((candidate) => candidate.id === clip.trackId);
+  const otherClips = (track?.clips ?? [])
+    .filter((candidate) => candidate.id !== clip.id)
+    .sort((a, b) => a.startTime - b.startTime);
+  const previousEnd = otherClips
+    .filter((candidate) => candidate.startTime < clip.startTime)
+    .reduce(
+      (latest, candidate) =>
+        Math.max(latest, candidate.startTime + candidate.duration),
+      0
+    );
+  const nextStart =
+    otherClips.find((candidate) => candidate.startTime > clip.startTime)
+      ?.startTime ?? Number.POSITIVE_INFINITY;
+  const originalEnd = clip.startTime + clip.duration;
+
+  if (mode === 'move') {
+    const maximumStart = Number.isFinite(nextStart)
+      ? nextStart - clip.duration
+      : Number.POSITIVE_INFINITY;
+    const startTime = roundTime(
+      clamp(clip.startTime + deltaTime, previousEnd, maximumStart)
+    );
+    return {
+      id: clip.id,
+      startTime,
+      duration: clip.duration,
+      inPoint: clip.inPoint,
+      outPoint: clip.outPoint,
+      sourceDuration: clip.sourceDuration,
+    };
+  }
+
+  if (mode === 'trim-start') {
+    const sourceMinimumStart =
+      clip.sourceType === 'image'
+        ? 0
+        : clip.startTime - clip.inPoint;
+    const startTime = roundTime(
+      clamp(
+        clip.startTime + deltaTime,
+        Math.max(0, previousEnd, sourceMinimumStart),
+        originalEnd - MIN_DURATION
+      )
+    );
+    const duration = roundTime(originalEnd - startTime);
+    const inPoint =
+      clip.sourceType === 'image'
+        ? 0
+        : roundTime(clip.inPoint + (startTime - clip.startTime));
+    return {
+      id: clip.id,
+      startTime,
+      duration,
+      inPoint,
+      outPoint: clip.sourceType === 'image' ? duration : clip.outPoint,
+      sourceDuration:
+        clip.sourceType === 'image' ? duration : clip.sourceDuration,
+    };
+  }
+
+  const sourceMaximumEnd =
+    clip.sourceType === 'image'
+      ? Number.POSITIVE_INFINITY
+      : clip.startTime + (clip.sourceDuration - clip.inPoint);
+  const endTime = roundTime(
+    clamp(
+      originalEnd + deltaTime,
+      clip.startTime + MIN_DURATION,
+      Math.min(nextStart, sourceMaximumEnd)
+    )
+  );
+  const duration = roundTime(endTime - clip.startTime);
+  return {
+    id: clip.id,
+    startTime: clip.startTime,
+    duration,
+    inPoint: clip.inPoint,
+    outPoint:
+      clip.sourceType === 'image'
+        ? duration
+        : roundTime(clip.inPoint + duration),
+    sourceDuration:
+      clip.sourceType === 'image' ? duration : clip.sourceDuration,
+  };
+}
diff --git a/src/core/editor/timeline-merge.test.ts b/src/core/editor/timeline-merge.test.ts
new file mode 100644
index 0000000..8e64bea
--- /dev/null
+++ b/src/core/editor/timeline-merge.test.ts
@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { addSourceClip, createTimelineDocument } from './timeline-document';
+import { mergeTimelineDocuments } from './timeline-merge';
+
+test('timeline merge preserves disjoint local and remote clip additions', () => {
+  const base = createTimelineDocument({ projectId: 'project-1', name: 'Edit' });
+  const local = addSourceClip(base, {
+    clipId: 'local-clip',
+    assetId: 'local-asset',
+    sourceUrl: '/local.mp4',
+    name: 'Local',
+    sourceType: 'video',
+    sourceDuration: 2,
+  });
+  const remote = addSourceClip(base, {
+    clipId: 'remote-clip',
+    assetId: 'remote-asset',
+    sourceUrl: '/remote.mp3',
+    name: 'Remote',
+    sourceType: 'audio',
+    sourceDuration: 4,
+  });
+
+  const result = mergeTimelineDocuments({ base, local, remote });
+  assert.equal(result.conflicts.length, 0);
+  assert.deepEqual(
+    result.document.tracks.flatMap((track) => track.clips.map((clip) => clip.id)),
+    ['local-clip', 'remote-clip']
+  );
+});
+
+test('timeline merge reports two edits to the same clip field', () => {
+  const empty = createTimelineDocument({ projectId: 'project-1', name: 'Edit' });
+  const base = addSourceClip(empty, {
+    clipId: 'clip-1',
+    assetId: 'asset-1',
+    sourceUrl: '/video.mp4',
+    name: 'Video',
+    sourceType: 'video',
+    sourceDuration: 5,
+  });
+  const local = structuredClone(base);
+  const remote = structuredClone(base);
+  local.tracks[0].clips[0].name = 'Local name';
+  remote.tracks[0].clips[0].name = 'Remote name';
+
+  const result = mergeTimelineDocuments({ base, local, remote });
+  assert.equal(result.conflicts.length, 1);
+  assert.match(result.conflicts[0].path, /name$/);
+  assert.equal(result.document.tracks[0].clips[0].name, 'Local name');
+});
diff --git a/src/core/editor/timeline-merge.ts b/src/core/editor/timeline-merge.ts
new file mode 100644
index 0000000..dfb90f3
--- /dev/null
+++ b/src/core/editor/timeline-merge.ts
@@ -0,0 +1,138 @@
+import {
+  normalizeTimelineDocument,
+  type TimelineDocument,
+} from './timeline-document';
+
+export type TimelineMergeConflict = { path: string };
+
+const equal = (left: unknown, right: unknown) =>
+  JSON.stringify(left) === JSON.stringify(right);
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value && typeof value === 'object' && !Array.isArray(value));
+
+const isIdArray = (value: unknown[]): value is Array<Record<string, unknown>> =>
+  value.every(
+    (item) => isRecord(item) && typeof item.id === 'string' && item.id.length > 0
+  );
+
+function mergeValue({
+  base,
+  local,
+  remote,
+  path,
+  conflicts,
+}: {
+  base: unknown;
+  local: unknown;
+  remote: unknown;
+  path: string;
+  conflicts: TimelineMergeConflict[];
+}): unknown {
+  if (equal(local, remote)) return local;
+  if (equal(local, base)) return remote;
+  if (equal(remote, base)) return local;
+
+  if (Array.isArray(base) && Array.isArray(local) && Array.isArray(remote)) {
+    if (!isIdArray(base) || !isIdArray(local) || !isIdArray(remote)) {
+      conflicts.push({ path });
+      return local;
+    }
+    const baseMap = new Map(base.map((item) => [item.id as string, item]));
+    const localMap = new Map(local.map((item) => [item.id as string, item]));
+    const remoteMap = new Map(remote.map((item) => [item.id as string, item]));
+    const ids = Array.from(
+      new Set([
+        ...remote.map((item) => item.id as string),
+        ...local.map((item) => item.id as string),
+        ...base.map((item) => item.id as string),
+      ])
+    );
+    const merged: unknown[] = [];
+    for (const id of ids) {
+      const baseItem = baseMap.get(id);
+      const localItem = localMap.get(id);
+      const remoteItem = remoteMap.get(id);
+      if (!localItem && !remoteItem) continue;
+      if (!baseItem) {
+        if (localItem && remoteItem && !equal(localItem, remoteItem)) {
+          conflicts.push({ path: `${path}[${id}]` });
+        }
+        merged.push(localItem ?? remoteItem);
+        continue;
+      }
+      if (!localItem) {
+        if (!equal(remoteItem, baseItem)) {
+          conflicts.push({ path: `${path}[${id}]` });
+          merged.push(remoteItem);
+        }
+        continue;
+      }
+      if (!remoteItem) {
+        if (!equal(localItem, baseItem)) {
+          conflicts.push({ path: `${path}[${id}]` });
+          merged.push(localItem);
+        }
+        continue;
+      }
+      merged.push(
+        mergeValue({
+          base: baseItem,
+          local: localItem,
+          remote: remoteItem,
+          path: `${path}[${id}]`,
+          conflicts,
+        })
+      );
+    }
+    return merged;
+  }
+
+  if (isRecord(base) && isRecord(local) && isRecord(remote)) {
+    const merged: Record<string, unknown> = {};
+    const keys = new Set([
+      ...Object.keys(base),
+      ...Object.keys(local),
+      ...Object.keys(remote),
+    ]);
+    for (const key of keys) {
+      if (key === 'updatedAt' || key === 'duration') continue;
+      merged[key] = mergeValue({
+        base: base[key],
+        local: local[key],
+        remote: remote[key],
+        path: `${path}.${key}`,
+        conflicts,
+      });
+    }
+    if ('updatedAt' in local) merged.updatedAt = local.updatedAt;
+    if ('duration' in local) merged.duration = local.duration;
+    return merged;
+  }
+
+  conflicts.push({ path });
+  return local;
+}
+
+export function mergeTimelineDocuments({
+  base,
+  local,
+  remote,
+}: {
+  base: TimelineDocument;
+  local: TimelineDocument;
+  remote: TimelineDocument;
+}) {
+  const conflicts: TimelineMergeConflict[] = [];
+  const merged = mergeValue({
+    base,
+    local,
+    remote,
+    path: 'timeline',
+    conflicts,
+  });
+  return {
+    document: normalizeTimelineDocument(merged, local.projectId),
+    conflicts,
+  };
+}
diff --git a/src/core/editor/timeline-state.test.ts b/src/core/editor/timeline-state.test.ts
new file mode 100644
index 0000000..4cf39f5
--- /dev/null
+++ b/src/core/editor/timeline-state.test.ts
@@ -0,0 +1,31 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { hasTimelineVersionConflict } from './timeline-state';
+
+test('timeline CAS rejects stale writers but permits an unchanged retry', () => {
+  assert.equal(
+    hasTimelineVersionConflict({
+      currentVersion: 4,
+      baseVersion: 3,
+      documentChanged: true,
+    }),
+    true
+  );
+  assert.equal(
+    hasTimelineVersionConflict({
+      currentVersion: 4,
+      baseVersion: 4,
+      documentChanged: true,
+    }),
+    false
+  );
+  assert.equal(
+    hasTimelineVersionConflict({
+      currentVersion: 4,
+      baseVersion: null,
+      documentChanged: false,
+    }),
+    false
+  );
+});
diff --git a/src/core/editor/timeline-state.ts b/src/core/editor/timeline-state.ts
new file mode 100644
index 0000000..d659796
--- /dev/null
+++ b/src/core/editor/timeline-state.ts
@@ -0,0 +1,119 @@
+import { and, eq } from 'drizzle-orm';
+
+import { projectTimelineState } from '@/config/db/schema';
+import {
+  normalizeTimelineDocument,
+  type TimelineDocument,
+} from '@/core/editor/timeline-document';
+import {
+  getProject,
+} from '@/core/projects/projects';
+import { getDb } from '@/core/workspace-lib/db-adapter';
+
+export const hasTimelineVersionConflict = ({
+  currentVersion,
+  baseVersion,
+  documentChanged,
+}: {
+  currentVersion: number;
+  baseVersion: number | null | undefined;
+  documentChanged: boolean;
+}) =>
+  documentChanged &&
+  (typeof baseVersion !== 'number' || baseVersion !== currentVersion);
+
+export async function loadProjectTimeline(projectId: string) {
+  const db = await getDb();
+  const rows = await db
+    .select()
+    .from(projectTimelineState)
+    .where(eq(projectTimelineState.projectId, projectId))
+    .limit(1);
+  const state = rows[0];
+  if (!state) return null;
+
+  return {
+    document: normalizeTimelineDocument(state.documentJson, projectId),
+    version: state.version,
+    updatedAt: state.updatedAt,
+  };
+}
+
+export async function saveProjectTimeline({
+  projectId,
+  document,
+  baseVersion,
+}: {
+  projectId: string;
+  document: TimelineDocument;
+  baseVersion?: number | null;
+}) {
+  const currentProject = await getProject({ projectId });
+  if (!currentProject || currentProject.status !== 'active') {
+    throw new Error('Project not found');
+  }
+
+  const normalized = normalizeTimelineDocument(document, projectId);
+  const db = await getDb();
+  const previous = await loadProjectTimeline(projectId);
+  const previousSerialized = previous
+    ? JSON.stringify(previous.document)
+    : null;
+  const nextSerialized = JSON.stringify(normalized);
+  if (
+    previous &&
+    hasTimelineVersionConflict({
+      currentVersion: previous.version,
+      baseVersion,
+      documentChanged: previousSerialized !== nextSerialized,
+    })
+  ) {
+    const error = new Error('Timeline version conflict') as Error & {
+      currentVersion?: number;
+    };
+    error.name = 'TimelineVersionConflict';
+    error.currentVersion = previous.version;
+    throw error;
+  }
+  if (previousSerialized === nextSerialized && previous) {
+    return previous;
+  }
+  const nextVersion = (previous?.version ?? 0) + 1;
+  const now = new Date();
+
+  if (previous) {
+    const updated = await db
+      .update(projectTimelineState)
+      .set({ documentJson: normalized, version: nextVersion, updatedAt: now })
+      .where(
+        and(
+          eq(projectTimelineState.projectId, projectId),
+          eq(projectTimelineState.version, baseVersion as number)
+        )
+      )
+      .returning({ version: projectTimelineState.version });
+    if (updated.length === 0) {
+      const error = new Error('Timeline version conflict');
+      error.name = 'TimelineVersionConflict';
+      throw error;
+    }
+  } else {
+    const inserted = await db
+      .insert(projectTimelineState)
+      .values({
+        projectId,
+        documentJson: normalized,
+        version: nextVersion,
+        updatedAt: now,
+      })
+      .onConflictDoNothing()
+      .returning({ version: projectTimelineState.version });
+    if (inserted.length === 0) {
+      const error = new Error('Timeline version conflict');
+      error.name = 'TimelineVersionConflict';
+      throw error;
+    }
+  }
+
+  return { document: normalized, version: nextVersion, updatedAt: now };
+}
diff --git a/src/core/effects/client-api.ts b/src/core/effects/client-api.ts
index 674fe35..1faa14c 100644
--- a/src/core/effects/client-api.ts
+++ b/src/core/effects/client-api.ts
@@ -26,6 +26,7 @@ type BaseEffectPayload = {
   projectId?: string;
   expectedUploadCount?: number;
   generationIntentToken?: string;
+  generation?: unknown;
 };
 
 export type PrecheckResponse = {
diff --git a/src/core/effects/effect-registry.ts b/src/core/effects/effect-registry.ts
index 2f96537..b00975a 100644
--- a/src/core/effects/effect-registry.ts
+++ b/src/core/effects/effect-registry.ts
@@ -1,3 +1,8 @@
+import {
+  getGenerationModelBindingByEffectId,
+  resolveProviderUpstreamModel,
+} from '@/core/generation-providers/registry';
+
 export type WorkspaceRegistryType = 'ai-video' | 'ai-image';
 
 type WorkspaceRegistryModelMode = 'quality' | 'fast' | 'lite';
@@ -57,10 +62,7 @@ export type WorkspaceEffectRegistryAliasDefaults = {
 export type WorkspaceEffectRegistryEntry = {
   id: string;
   name: string;
-  effectId: number;
   workspaceType: WorkspaceRegistryType;
-  uploadPath: string;
-  imageBucketName: string;
   routeSlug: string | null;
   routeAliases?: string[];
   routeOrder?: number;
@@ -86,9 +88,6 @@ export type WorkspaceEffectRegistryEntry = {
   defaultBackgroundSource?: WorkspaceRegistryBackgroundSource;
   backgroundSourceOptions?: WorkspaceRegistryBackgroundSource[];
   requiresSourceVideoDuration?: boolean;
-  providerModelVariantByVariant?: Partial<
-    Record<WorkspaceRegistryModelVariant, string>
-  >;
   referenceInputDefaultsByType?: Partial<
     Record<
       WorkspaceRegistryReferenceType,
@@ -123,10 +122,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'nano-banana-pro',
       name: 'Nano Banana Pro',
-      effectId: 6,
       workspaceType: 'ai-image',
-      uploadPath: 'effects/nano-banana-pro',
-      imageBucketName: 'image',
       routeSlug: 'nano-banana-pro',
       routeOrder: 10,
       defaultAspectRatio: '1:1',
@@ -150,10 +146,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'nano-banana',
       name: 'Nano Banana',
-      effectId: 5,
       workspaceType: 'ai-image',
-      uploadPath: 'effects/nano-banana',
-      imageBucketName: 'image',
       routeSlug: 'nano-banana',
       routeOrder: 20,
       defaultAspectRatio: '1:1',
@@ -175,10 +168,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'gpt-image-2',
       name: 'GPT Image 2',
-      effectId: 12,
       workspaceType: 'ai-image',
-      uploadPath: 'effects/gpt-image-2',
-      imageBucketName: 'image',
       routeSlug: 'gpt-image-2',
       routeOrder: 30,
       defaultAspectRatio: 'auto',
@@ -206,10 +196,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'seedream-5-pro',
       name: 'Seedream 5 Pro',
-      effectId: 16,
       workspaceType: 'ai-image',
-      uploadPath: 'effects/seedream-5-pro',
-      imageBucketName: 'image',
       routeSlug: 'seedream-5-pro',
       routeOrder: 40,
       defaultAspectRatio: '1:1',
@@ -230,10 +217,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'grok-imagine-image-2.0',
       name: 'Grok Imagine Image 2.0',
-      effectId: 23,
       workspaceType: 'ai-image',
-      uploadPath: 'effects/grok-imagine-image-2-0',
-      imageBucketName: 'image',
       routeSlug: 'grok-imagine-image-2-0',
       routeAliases: ['grok-imagine-image-2.0'],
       routeOrder: 50,
@@ -244,10 +228,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'seedance-2',
       name: 'Seedance 2',
-      effectId: 9,
       workspaceType: 'ai-video',
-      uploadPath: 'effects/seedance-2',
-      imageBucketName: 'image',
       routeSlug: 'seedance-2',
       routeAliases: ['seedance-2-0', 'seedance2-0'],
       routeOrder: 10,
@@ -262,10 +243,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'seedance-2-fast',
       name: 'Seedance 2 Fast',
-      effectId: 21,
       workspaceType: 'ai-video',
-      uploadPath: 'effects/seedance-2-fast',
-      imageBucketName: 'image',
       routeSlug: 'seedance-2-fast',
       routeAliases: ['seedance-2.0-fast', 'seedance20-fast'],
       routeOrder: 12,
@@ -280,10 +258,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'seedance-2-mini',
       name: 'Seedance 2 Mini',
-      effectId: 22,
       workspaceType: 'ai-video',
-      uploadPath: 'effects/seedance-2-mini',
-      imageBucketName: 'image',
       routeSlug: 'seedance-2-mini',
       routeAliases: ['seedance-2.0-mini', 'seedance20-mini'],
       routeOrder: 14,
@@ -298,10 +273,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'seedance-2.5',
       name: 'Seedance 2.5',
-      effectId: 18,
       workspaceType: 'ai-video',
-      uploadPath: 'effects/seedance-2-5',
-      imageBucketName: 'image',
       routeSlug: 'seedance-2-5',
       routeOrder: 20,
       defaultDuration: '5s',
@@ -314,10 +286,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'minimax-h3',
       name: 'MiniMax H3',
-      effectId: 17,
       workspaceType: 'ai-video',
-      uploadPath: 'effects/minimax-h3',
-      imageBucketName: 'image',
       routeSlug: 'minimax-h3',
       routeOrder: 30,
       defaultDuration: '5s',
@@ -330,10 +299,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'veo-3.1',
       name: 'Veo 3.1',
-      effectId: 1,
       workspaceType: 'ai-video',
-      uploadPath: 'effects/veo-3-1',
-      imageBucketName: 'image',
       routeSlug: 'veo-3-1',
       routeAliases: ['veo3-1'],
       routeOrder: 40,
@@ -354,10 +320,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'kling-3',
       name: 'Kling 3',
-      effectId: 10,
       workspaceType: 'ai-video',
-      uploadPath: 'effects/kling-3',
-      imageBucketName: 'image',
       routeSlug: 'kling-3',
       routeAliases: ['kling-3-0', 'kling3-0'],
       routeOrder: 50,
@@ -372,10 +335,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'grok-imagine-video-1.5',
       name: 'Grok Imagine Video 1.5',
-      effectId: 24,
       workspaceType: 'ai-video',
-      uploadPath: 'effects/grok-imagine-video-1-5',
-      imageBucketName: 'image',
       routeSlug: 'grok-imagine-video-1-5',
       routeAliases: ['grok-imagine-video-1.5'],
       routeOrder: 55,
@@ -389,10 +349,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'kling-2.6-motion-control',
       name: 'Kling 2.6 Motion Control',
-      effectId: 19,
       workspaceType: 'ai-video',
-      uploadPath: 'effects/kling-2-6-motion-control',
-      imageBucketName: 'image',
       routeSlug: 'kling-2-6-motion-control',
       routeAliases: ['kling-2.6-motion-control', 'kling26-motion-control'],
       routeOrder: 60,
@@ -409,10 +366,7 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
     {
       id: 'kling-3-motion-control',
       name: 'Kling 3.0 Motion Control',
-      effectId: 20,
       workspaceType: 'ai-video',
-      uploadPath: 'effects/kling-3-motion-control',
-      imageBucketName: 'image',
       routeSlug: 'kling-3-motion-control',
       routeAliases: ['kling-3.0-motion-control', 'kling30-motion-control'],
       routeOrder: 70,
@@ -443,10 +397,6 @@ const WORKSPACE_EFFECT_REGISTRY_BY_ALIAS = new Map(
   )
 );
 
-const WORKSPACE_EFFECT_REGISTRY_BY_EFFECT_ID = new Map(
-  WORKSPACE_EFFECT_REGISTRY.map((entry) => [entry.effectId, entry])
-);
-
 export const getWorkspaceEffectRegistryEntry = (
   modelId: string
 ): WorkspaceEffectRegistryEntry | null =>
@@ -455,9 +405,12 @@ export const getWorkspaceEffectRegistryEntry = (
   null;
 
 export const getWorkspaceEffectRegistryEntryByEffectId = (
-  effectId: number
-): WorkspaceEffectRegistryEntry | null =>
-  WORKSPACE_EFFECT_REGISTRY_BY_EFFECT_ID.get(effectId) ?? null;
+  effectId: number,
+  providerId?: string
+): WorkspaceEffectRegistryEntry | null => {
+  const binding = getGenerationModelBindingByEffectId({ effectId, providerId });
+  return binding ? getWorkspaceEffectRegistryEntry(binding.modelId) : null;
+};
 
 export const resolveWorkspaceEffectProviderModelVariant = ({
   modelId,
@@ -466,12 +419,7 @@ export const resolveWorkspaceEffectProviderModelVariant = ({
   modelId: string;
   variant?: WorkspaceRegistryModelVariant | null;
 }): string => {
-  const entry = getWorkspaceEffectRegistryEntry(modelId);
-  if (!entry || !variant) {
-    return modelId;
-  }
-
-  return entry.providerModelVariantByVariant?.[variant] ?? modelId;
+  return resolveProviderUpstreamModel({ modelId, variant });
 };
 
 export const getWorkspaceEffectReferenceInputDefaults = ({
diff --git a/src/core/effects/effects.ts b/src/core/effects/effects.ts
index 87614a1..2a48afd 100644
--- a/src/core/effects/effects.ts
+++ b/src/core/effects/effects.ts
@@ -3,8 +3,8 @@ import {
   getRegisteredEffectsByIds,
 } from './registered-effects';
 
-export const getEffectById = async (id: number) =>
-  getRegisteredEffectById(id);
+export const getEffectById = async (id: number, providerId?: string) =>
+  getRegisteredEffectById(id, providerId);
 
 export const getEffectsByIds = async (ids: number[]) =>
   getRegisteredEffectsByIds(ids);
diff --git a/src/core/effects/generation-provider-client-boundary.test.ts b/src/core/effects/generation-provider-client-boundary.test.ts
new file mode 100644
index 0000000..aadc001
--- /dev/null
+++ b/src/core/effects/generation-provider-client-boundary.test.ts
@@ -0,0 +1,15 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+
+for (const clientModule of ['./effect-registry.ts', './workspace-models.ts']) {
+  test(`${clientModule} does not load the server generation barrel`, () => {
+    const source = readFileSync(new URL(clientModule, import.meta.url), 'utf8');
+
+    assert.match(source, /@\/core\/generation-providers\/registry/);
+    assert.doesNotMatch(
+      source,
+      /from ['"]@\/core\/generation-providers['"]/
+    );
+  });
+}
diff --git a/src/core/effects/generation-sync.ts b/src/core/effects/generation-sync.ts
index eb7af27..38d915a 100644
--- a/src/core/effects/generation-sync.ts
+++ b/src/core/effects/generation-sync.ts
@@ -10,6 +10,9 @@ import {
 const asObject = (value: unknown): Record<string, unknown> =>
   value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
 
+const readString = (value: unknown) =>
+  typeof value === 'string' && value.trim() ? value.trim() : null;
+
 export async function syncGeneration({
   wmTaskId,
   effectId,
@@ -22,7 +25,11 @@ export async function syncGeneration({
   if (generation.status === 'succeeded' || generation.status === 'failed') {
     return { ok: true as const, generation };
   }
-  const effect = await getEffectById(effectId);
+  const providerIdentity = asObject(asObject(generation.input)._provider);
+  const effect = await getEffectById(
+    effectId,
+    readString(providerIdentity.id) ?? undefined
+  );
   if (!effect) return { ok: false as const, status: 404, error: 'Model not found' };
   if (!generation.providerTaskId) {
     return { ok: true as const, generation };
diff --git a/src/core/effects/project-generations.ts b/src/core/effects/project-generations.ts
index 98daf12..3c6baed 100644
--- a/src/core/effects/project-generations.ts
+++ b/src/core/effects/project-generations.ts
@@ -1,7 +1,10 @@
 import { desc, eq } from 'drizzle-orm';
 
 import { generationHistory } from '@/config/db/schema';
-import { getWorkspaceEffectRegistryEntryByEffectId } from '@/core/effects/effect-registry';
+import {
+  getWorkspaceEffectRegistryEntry,
+  getWorkspaceEffectRegistryEntryByEffectId,
+} from '@/core/effects/effect-registry';
 import { resolveOutputMedia } from '@/core/effects/output-media';
 import {
   isVideoAnalysisEffectId,
@@ -93,9 +96,14 @@ type ProjectGenerationRow = {
 export const toProjectGenerationItem = (
   row: ProjectGenerationRow
 ): ProjectGenerationItem => {
-  const entry = getWorkspaceEffectRegistryEntryByEffectId(row.effectId);
-  const isAnalysis = isVideoAnalysisEffectId(row.effectId);
   const input = asRecord(row.input);
+  const providerIdentity = asRecord(input?._provider);
+  const recordedModelId = readString(providerIdentity?.modelId);
+  const entry = recordedModelId
+    ? getWorkspaceEffectRegistryEntry(recordedModelId)
+    : getWorkspaceEffectRegistryEntryByEffectId(row.effectId);
+  const isAnalysis =
+    recordedModelId === 'video-analysis' || isVideoAnalysisEffectId(row.effectId);
   const media = resolveOutputMedia(row.output);
   const analysisModelName =
     input?.analysis_depth === 'deep'
@@ -111,7 +119,10 @@ export const toProjectGenerationItem = (
     status: row.status as GenerationStatus,
     prompt: row.submittedPrompt,
     modelId:
-      readString(input?.model) ?? entry?.id ?? (isAnalysis ? 'video-analysis' : null),
+      recordedModelId ??
+      readString(input?.model) ??
+      entry?.id ??
+      (isAnalysis ? 'video-analysis' : null),
     modelName: entry?.name ?? (isAnalysis ? analysisModelName : null),
     mediaType: isAnalysis
       ? 'analysis'
diff --git a/src/core/effects/registered-effects.test.ts b/src/core/effects/registered-effects.test.ts
index 2b87bc9..2858ac0 100644
--- a/src/core/effects/registered-effects.test.ts
+++ b/src/core/effects/registered-effects.test.ts
@@ -24,7 +24,8 @@ test('video analysis is a separate registered workflow with two depths', () => {
 
   assert.equal(analysis?.model, 'video-analysis');
   assert.equal(analysis?.type, 3);
-  assert.equal(analysis?.api, 'https://api.beatapi.io/v1/video-analysis/tasks');
+  assert.equal(analysis?.provider, 'beatapi');
+  assert.equal(analysis?.api, null);
   assert.deepEqual(
     (schema.analysis_depth as { values?: string[] }).values,
     ['standard', 'deep']
diff --git a/src/core/effects/registered-effects.ts b/src/core/effects/registered-effects.ts
index 93eb376..0e73e96 100644
--- a/src/core/effects/registered-effects.ts
+++ b/src/core/effects/registered-effects.ts
@@ -1,4 +1,11 @@
 import type { EffectRecord } from '@/core/adapters/base-adapter';
+import {
+  getActiveGenerationProvider,
+  getActiveGenerationProviderId,
+  getGenerationProvider,
+  getGenerationModelBindingByEffectId,
+  type GenerationProviderModelBinding,
+} from '@/core/generation-providers';
 
 import {
   type WorkspaceEffectRegistryEntry,
@@ -7,34 +14,38 @@ import {
 } from './effect-registry';
 import { getWorkspaceMediaSchema } from './workspace-media';
 import {
-  isVideoAnalysisEffectId,
-  VIDEO_ANALYSIS_EFFECT_ID,
   VIDEO_ANALYSIS_MODEL_ID,
 } from './video-analysis';
 
 export type RegisteredEffect = EffectRecord;
 
-const VIDEO_ANALYSIS_EFFECT: RegisteredEffect = {
-  id: VIDEO_ANALYSIS_EFFECT_ID,
-  name: 'Video Analysis',
-  type: 3,
-  model: VIDEO_ANALYSIS_MODEL_ID,
-  version: null,
-  linkName: VIDEO_ANALYSIS_MODEL_ID,
-  description: 'BeatAPI asynchronous video analysis',
-  platform: 'beatapi',
-  api: 'https://api.beatapi.io/v1/video-analysis/tasks',
-  provider: 'beatapi',
-  inputSchema: {
-    prompt: { type: 'string', required: true },
-    video_url: { type: 'string', required: true },
-    analysis_depth: {
-      type: 'enum',
-      required: false,
-      values: ['standard', 'deep'],
+const buildVideoAnalysisEffect = (
+  binding: GenerationProviderModelBinding,
+  providerId = getActiveGenerationProviderId()
+): RegisteredEffect => {
+  const provider = getGenerationProvider(providerId);
+  return {
+    id: binding.effectId,
+    name: 'Video Analysis',
+    type: 3,
+    model: binding.upstreamModelId,
+    version: null,
+    linkName: VIDEO_ANALYSIS_MODEL_ID,
+    description: `${provider?.label ?? providerId} asynchronous video analysis`,
+    platform: binding.modelId,
+    api: null,
+    provider: providerId,
+    inputSchema: {
+      prompt: { type: 'string', required: true },
+      video_url: { type: 'string', required: true },
+      analysis_depth: {
+        type: 'enum',
+        required: false,
+        values: ['standard', 'deep'],
+      },
+      max_output_tokens: { type: 'number', required: false },
     },
-    max_output_tokens: { type: 'number', required: false },
-  },
+  };
 };
 
 const optionalAnyField = { type: 'any', required: false } as const;
@@ -118,36 +129,51 @@ const buildInputSchema = (entry: WorkspaceEffectRegistryEntry) => {
 };
 
 export const toRegisteredEffect = (
-  entry: WorkspaceEffectRegistryEntry
+  entry: WorkspaceEffectRegistryEntry,
+  binding: GenerationProviderModelBinding,
+  providerId = getActiveGenerationProviderId()
 ): RegisteredEffect => {
   const isImage = entry.workspaceType === 'ai-image';
+  const provider = getGenerationProvider(providerId);
+  if (!provider) throw new Error(`Generation provider ${providerId} is not registered.`);
 
   return {
-    id: entry.effectId,
+    id: binding.effectId,
     name: entry.name,
     type: isImage ? 2 : 1,
-    model: entry.id,
+    model: binding.upstreamModelId,
     version: null,
     linkName: entry.routeSlug ?? entry.id,
-    description: `BeatAPI ${entry.name}`,
-    platform: 'beatapi',
-    api: isImage
-      ? 'https://api.beatapi.io/v1/images/tasks'
-      : 'https://api.beatapi.io/v1/videos/tasks',
-    provider: 'beatapi',
+    description: `${provider.label} ${entry.name}`,
+    platform: provider.id,
+    api: null,
+    provider: provider.id,
     inputSchema: buildInputSchema(entry),
   };
 };
 
 export const listRegisteredEffects = (): RegisteredEffect[] =>
-  [...WORKSPACE_EFFECT_REGISTRY.map(toRegisteredEffect), VIDEO_ANALYSIS_EFFECT];
+  getActiveGenerationProvider().modelBindings.flatMap((binding) => {
+    if (binding.modelId === VIDEO_ANALYSIS_MODEL_ID) {
+      return [buildVideoAnalysisEffect(binding)];
+    }
+    const entry = WORKSPACE_EFFECT_REGISTRY.find(
+      (candidate) => candidate.id === binding.modelId
+    );
+    return entry ? [toRegisteredEffect(entry, binding)] : [];
+  });
 
 export const getRegisteredEffectById = (
-  id: number
+  id: number,
+  providerId = getActiveGenerationProviderId()
 ): RegisteredEffect | null => {
-  if (isVideoAnalysisEffectId(id)) return VIDEO_ANALYSIS_EFFECT;
-  const entry = getWorkspaceEffectRegistryEntryByEffectId(id);
-  return entry ? toRegisteredEffect(entry) : null;
+  const binding = getGenerationModelBindingByEffectId({ effectId: id, providerId });
+  if (!binding) return null;
+  if (binding.modelId === VIDEO_ANALYSIS_MODEL_ID) {
+    return buildVideoAnalysisEffect(binding, providerId);
+  }
+  const entry = getWorkspaceEffectRegistryEntryByEffectId(id, providerId);
+  return entry ? toRegisteredEffect(entry, binding, providerId) : null;
 };
 
 export const getRegisteredEffectsByIds = (ids: number[]): RegisteredEffect[] => {
diff --git a/src/core/effects/submit-generation.ts b/src/core/effects/submit-generation.ts
index d3f5d97..daee7fb 100644
--- a/src/core/effects/submit-generation.ts
+++ b/src/core/effects/submit-generation.ts
@@ -1,7 +1,8 @@
 import { createAdapter } from '@/core/adapters/adapter-factory';
 import { getEffectById } from '@/core/effects/effects';
 import { getWorkspaceEffectRegistryEntryByEffectId } from '@/core/effects/effect-registry';
-import { isVideoAnalysisEffectId } from '@/core/effects/video-analysis';
+import { VIDEO_ANALYSIS_MODEL_ID } from '@/core/effects/video-analysis';
+import { getGenerationModelBindingByEffectId } from '@/core/generation-providers';
 import {
   getGenerationConcurrencyErrorMessage,
   resolveGenerationConcurrencyGate,
@@ -140,10 +141,17 @@ export async function submitEffectGeneration({
     return { status: 400, body: { error: 'effectId is required' } };
   }
   const effect = await getEffectById(effectId);
+  const binding = effect
+    ? getGenerationModelBindingByEffectId({
+        effectId,
+        providerId: effect.provider,
+      })
+    : null;
   if (
     !effect ||
-    (!getWorkspaceEffectRegistryEntryByEffectId(effectId) &&
-      !isVideoAnalysisEffectId(effectId))
+    !binding ||
+    (!getWorkspaceEffectRegistryEntryByEffectId(effectId, effect.provider) &&
+      binding.modelId !== VIDEO_ANALYSIS_MODEL_ID)
   ) {
     return { status: 404, body: { error: 'Model not found' } };
   }
@@ -189,9 +197,16 @@ export async function submitEffectGeneration({
       body: { error: 'A generation intent is required.' },
     };
   }
-  const recordedInput = metadata
-    ? { ...adapterInput, _source: metadata }
-    : adapterInput;
+  const recordedInput = {
+    ...adapterInput,
+    ...(metadata ? { _source: metadata } : {}),
+    _provider: {
+      id: effect.provider,
+      modelId: binding?.modelId ?? effect.model,
+      upstreamModelId: effect.model,
+      effectId,
+    },
+  };
   const admission = await withGenerationSubmissionLock<
     | { result: SubmitEffectGenerationResult }
     | { generationId: string; intentId: string }
diff --git a/src/core/effects/validation.ts b/src/core/effects/validation.ts
index 36dbe96..da27db1 100644
--- a/src/core/effects/validation.ts
+++ b/src/core/effects/validation.ts
@@ -89,6 +89,10 @@ const ALLOWED_AUDIO_MIME_TYPES = [
   'audio/mpeg',
   'audio/wav',
   'audio/x-wav',
+  'audio/mp4',
+  'audio/x-m4a',
+  'audio/aac',
+  'audio/ogg',
 ] as const;
 
 export {
@@ -107,7 +111,10 @@ const hasAllowedImageExtension = (fileName?: string) =>
 const hasAllowedVideoExtension = (fileName?: string) =>
   Boolean(fileName && /\.(mp4|webm|mov)$/i.test(fileName));
 
-export type UploadedMediaType = 'image' | 'video';
+const hasAllowedAudioExtension = (fileName?: string) =>
+  Boolean(fileName && /\.(mp3|wav|m4a|aac|ogg)$/i.test(fileName));
+
+export type UploadedMediaType = 'image' | 'video' | 'audio';
 
 const mediaTypeFromMime = (mimeType: string): UploadedMediaType | null => {
   if (
@@ -124,6 +131,13 @@ const mediaTypeFromMime = (mimeType: string): UploadedMediaType | null => {
   ) {
     return 'video';
   }
+  if (
+    ALLOWED_AUDIO_MIME_TYPES.includes(
+      mimeType as (typeof ALLOWED_AUDIO_MIME_TYPES)[number]
+    )
+  ) {
+    return 'audio';
+  }
   return null;
 };
 
@@ -132,7 +146,9 @@ const mediaTypeFromExtension = (fileName?: string): UploadedMediaType | null =>
     ? 'image'
     : hasAllowedVideoExtension(fileName)
       ? 'video'
-      : null;
+      : hasAllowedAudioExtension(fileName)
+        ? 'audio'
+        : null;
 
 const isGenericUploadMimeType = (mimeType: string) =>
   !mimeType || mimeType === 'application/octet-stream';
@@ -173,6 +189,13 @@ export const getCanonicalUploadedMediaMimeType = (file: {
   }
   if (name.endsWith('.webm')) return 'video/webm';
   if (name.endsWith('.mov')) return 'video/quicktime';
+  if (mediaType === 'audio') {
+    if (name.endsWith('.wav')) return 'audio/wav';
+    if (name.endsWith('.m4a')) return 'audio/mp4';
+    if (name.endsWith('.aac')) return 'audio/aac';
+    if (name.endsWith('.ogg')) return 'audio/ogg';
+    return 'audio/mpeg';
+  }
   return 'video/mp4';
 };
 
diff --git a/src/core/effects/workspace-models.ts b/src/core/effects/workspace-models.ts
index 78fe44b..2aebeba 100644
--- a/src/core/effects/workspace-models.ts
+++ b/src/core/effects/workspace-models.ts
@@ -1,4 +1,8 @@
 import { buildCreateProjectPath } from '@/core/projects/project-entry';
+import {
+  getActiveGenerationProviderId,
+  getGenerationModelBinding,
+} from '@/core/generation-providers/registry';
 import {
   WORKSPACE_EFFECT_REGISTRY,
   type WorkspaceAspectRatio,
@@ -89,16 +93,19 @@ const withMediaSchema = (
 const toWorkspaceModelOption = (
   workspaceType: WorkspaceType,
   entry: (typeof WORKSPACE_EFFECT_REGISTRY)[number]
-): WorkspaceModelOption => {
+): WorkspaceModelOption | null => {
   const mediaSchema = withMediaSchema(workspaceType, entry.id);
+  const providerId = getActiveGenerationProviderId();
+  const binding = getGenerationModelBinding({ modelId: entry.id, providerId });
+  if (!binding) return null;
 
   return {
     id: entry.id,
     name: entry.name,
-    effectId: entry.effectId,
+    effectId: binding.effectId,
     mediaSchema,
-    uploadPath: entry.uploadPath,
-    imageBucketName: entry.imageBucketName,
+    uploadPath: binding.uploadPath,
+    imageBucketName: binding.imageBucketName,
     defaultMode: entry.defaultMode,
     modeOptions: entry.modeOptions ? [...entry.modeOptions] : undefined,
     defaultVariant: entry.defaultVariant,
@@ -152,14 +159,16 @@ const toWorkspaceModelOption = (
 };
 
 const VIDEO_MODELS: WorkspaceModelOption[] =
-  getWorkspaceEffectRegistryEntriesByType('ai-video').map((entry) =>
-    toWorkspaceModelOption('ai-video', entry)
-  );
+  getWorkspaceEffectRegistryEntriesByType('ai-video').flatMap((entry) => {
+    const model = toWorkspaceModelOption('ai-video', entry);
+    return model ? [model] : [];
+  });
 
 const IMAGE_MODELS: WorkspaceModelOption[] =
-  getWorkspaceEffectRegistryEntriesByType('ai-image').map((entry) =>
-    toWorkspaceModelOption('ai-image', entry)
-  );
+  getWorkspaceEffectRegistryEntriesByType('ai-image').flatMap((entry) => {
+    const model = toWorkspaceModelOption('ai-image', entry);
+    return model ? [model] : [];
+  });
 
 const WORKSPACE_LAUNCH_TARGET: Record<WorkspaceType, string> = {
   'ai-video': 'video',
diff --git a/src/core/generation-providers/beatapi-provider.ts b/src/core/generation-providers/beatapi-provider.ts
new file mode 100644
index 0000000..a19d792
--- /dev/null
+++ b/src/core/generation-providers/beatapi-provider.ts
@@ -0,0 +1,56 @@
+import {
+  BeatApiAdapter,
+  validateBeatApiTaskInput,
+} from '@/core/adapters/beatapi-adapter';
+import { getConfig } from '@/modules/config/service';
+
+import type { GenerationProviderDefinition } from './contracts';
+
+export const BEATAPI_PROVIDER_ID = 'beatapi';
+
+export const BEATAPI_MODEL_BINDINGS = [
+  ['nano-banana-pro', 6, 'effects/nano-banana-pro', 'image'],
+  ['nano-banana', 5, 'effects/nano-banana', 'image'],
+  ['gpt-image-2', 12, 'effects/gpt-image-2', 'image'],
+  ['seedream-5-pro', 16, 'effects/seedream-5-pro', 'image'],
+  ['grok-imagine-image-2.0', 23, 'effects/grok-imagine-image-2-0', 'image'],
+  ['seedance-2', 9, 'effects/seedance-2', 'image'],
+  ['seedance-2-fast', 21, 'effects/seedance-2-fast', 'image'],
+  ['seedance-2-mini', 22, 'effects/seedance-2-mini', 'image'],
+  ['seedance-2.5', 18, 'effects/seedance-2-5', 'image'],
+  ['minimax-h3', 17, 'effects/minimax-h3', 'image'],
+  ['veo-3.1', 1, 'effects/veo-3-1', 'image'],
+  ['kling-3', 10, 'effects/kling-3', 'image'],
+  ['grok-imagine-video-1.5', 24, 'effects/grok-imagine-video-1-5', 'image'],
+  ['kling-2.6-motion-control', 19, 'effects/kling-2-6-motion-control', 'image'],
+  ['kling-3-motion-control', 20, 'effects/kling-3-motion-control', 'image'],
+  ['video-analysis', 1001, 'effects/video-analysis', 'video'],
+] as const;
+
+export const beatApiGenerationProvider: GenerationProviderDefinition = {
+  id: BEATAPI_PROVIDER_ID,
+  label: 'BeatAPI',
+  supports: ['image', 'video', 'analysis'],
+  modelBindings: BEATAPI_MODEL_BINDINGS.map(
+    ([modelId, effectId, uploadPath, imageBucketName]) => ({
+      modelId,
+      effectId,
+      upstreamModelId: modelId,
+      uploadPath,
+      imageBucketName,
+    })
+  ),
+  createAdapter: (effect) => new BeatApiAdapter(effect),
+  assertConfigured: async () => {
+    if (!(await getConfig('BEATAPI_API_KEY'))) {
+      throw new Error('Connect a BeatAPI API key before generating.');
+    }
+  },
+  validateInput: (effect, input) => {
+    validateBeatApiTaskInput({
+      effectType: effect.type,
+      model: effect.model,
+      input,
+    });
+  },
+};
diff --git a/src/core/generation-providers/contracts.ts b/src/core/generation-providers/contracts.ts
new file mode 100644
index 0000000..40c22a5
--- /dev/null
+++ b/src/core/generation-providers/contracts.ts
@@ -0,0 +1,29 @@
+import type { BaseAdapter, EffectRecord } from '@/core/adapters/base-adapter';
+
+export type GenerationMediaCapability = 'image' | 'video' | 'audio' | 'analysis';
+
+export type GenerationProviderModelBinding = {
+  /** Stable BeatDesign product model id. */
+  modelId: string;
+  /** Provider-local numeric id retained for existing DB/API compatibility. */
+  effectId: number;
+  /** Provider model name sent upstream. */
+  upstreamModelId: string;
+  uploadPath: string;
+  imageBucketName: string;
+  upstreamModelByVariant?: Readonly<Record<string, string>>;
+};
+
+export type GenerationProviderDefinition = {
+  id: string;
+  label: string;
+  supports: readonly GenerationMediaCapability[];
+  modelBindings: readonly GenerationProviderModelBinding[];
+  createAdapter: (effect: EffectRecord) => BaseAdapter;
+  assertConfigured?: () => Promise<void>;
+  validateInput?: (effect: EffectRecord, input: Record<string, unknown>) => void;
+};
+
+export type GenerationProviderRegistrar = (
+  provider: GenerationProviderDefinition
+) => void;
diff --git a/src/core/generation-providers/index.ts b/src/core/generation-providers/index.ts
new file mode 100644
index 0000000..b5b9803
--- /dev/null
+++ b/src/core/generation-providers/index.ts
@@ -0,0 +1,4 @@
+export * from './contracts';
+export * from './model-catalog';
+export * from './registry';
+export * from './submit';
diff --git a/src/core/generation-providers/model-catalog.ts b/src/core/generation-providers/model-catalog.ts
new file mode 100644
index 0000000..3948e48
--- /dev/null
+++ b/src/core/generation-providers/model-catalog.ts
@@ -0,0 +1,110 @@
+import {
+  getWorkspaceEffectRegistryEntry,
+  type WorkspaceEffectRegistryEntry,
+} from '@/core/effects/effect-registry';
+import { getRegisteredEffectById } from '@/core/effects/registered-effects';
+import { getWorkspaceMediaSchema } from '@/core/effects/workspace-media';
+import {
+  VIDEO_ANALYSIS_MODEL_ID,
+} from '@/core/effects/video-analysis';
+
+import {
+  getActiveGenerationProvider,
+  getGenerationModelBinding,
+} from './registry';
+
+const defaultsFromEntry = (entry: WorkspaceEffectRegistryEntry) => ({
+  ...(entry.defaultAspectRatio
+    ? { aspect_ratio: entry.defaultAspectRatio }
+    : {}),
+  ...(entry.defaultDuration ? { wmDuration: entry.defaultDuration } : {}),
+  ...(entry.defaultOutputQuality
+    ? { wmOutputQuality: entry.defaultOutputQuality }
+    : {}),
+  ...(entry.defaultQuality ? { quality: entry.defaultQuality } : {}),
+  ...(entry.defaultMode ? { mode: entry.defaultMode } : {}),
+  ...(entry.defaultLanguage ? { language: entry.defaultLanguage } : {}),
+  ...(entry.defaultCharacterOrientation
+    ? { characterOrientation: entry.defaultCharacterOrientation }
+    : {}),
+  ...(entry.defaultBackgroundSource
+    ? { backgroundSource: entry.defaultBackgroundSource }
+    : {}),
+});
+
+export type GenerationModelDescriptor = {
+  id: string;
+  name: string;
+  providerId: string;
+  kind: 'image' | 'video' | 'analysis';
+  available: boolean;
+  parameterSchema: unknown;
+  defaultParameters: Record<string, unknown>;
+  referenceSchema: unknown;
+};
+
+export function listGenerationModelDescriptors(): GenerationModelDescriptor[] {
+  const provider = getActiveGenerationProvider();
+  return provider.modelBindings.flatMap<GenerationModelDescriptor>((binding) => {
+    const effect = getRegisteredEffectById(binding.effectId);
+    if (!effect) return [];
+    if (binding.modelId === VIDEO_ANALYSIS_MODEL_ID) {
+      return [
+        {
+          id: VIDEO_ANALYSIS_MODEL_ID,
+          name: 'Video Analysis',
+          providerId: provider.id,
+          kind: 'analysis' as const,
+          available: true,
+          parameterSchema: effect.inputSchema,
+          defaultParameters: {
+            analysis_depth: 'standard',
+            max_output_tokens: 2048,
+          },
+          referenceSchema: {
+            image: { min: 0, max: 0 },
+            video: { min: 1, max: 1 },
+            audio: { min: 0, max: 0 },
+          },
+        },
+      ];
+    }
+    const entry = getWorkspaceEffectRegistryEntry(binding.modelId);
+    if (!entry) return [];
+    return [
+      {
+        id: entry.id,
+        name: entry.name,
+        providerId: provider.id,
+        kind: entry.workspaceType === 'ai-image' ? ('image' as const) : ('video' as const),
+        available: true,
+        parameterSchema: effect.inputSchema,
+        defaultParameters: defaultsFromEntry(entry),
+        referenceSchema: getWorkspaceMediaSchema(entry.id),
+      },
+    ];
+  });
+}
+
+export function getGenerationModelDescriptor(modelId: string) {
+  return (
+    listGenerationModelDescriptors().find((model) => model.id === modelId) ??
+    null
+  );
+}
+
+export function validateGenerationModelInput({
+  modelId,
+  input,
+}: {
+  modelId: string;
+  input: Record<string, unknown>;
+}) {
+  const provider = getActiveGenerationProvider();
+  const binding = getGenerationModelBinding({ modelId, providerId: provider.id });
+  if (!binding) throw new Error(`Model ${modelId} is not available from ${provider.label}.`);
+  const effect = getRegisteredEffectById(binding.effectId);
+  if (!effect) throw new Error(`Model ${modelId} is not registered.`);
+  provider.validateInput?.(effect, input);
+  return { provider, binding, effect };
+}
diff --git a/src/core/generation-providers/registry.test.ts b/src/core/generation-providers/registry.test.ts
new file mode 100644
index 0000000..ededd8c
--- /dev/null
+++ b/src/core/generation-providers/registry.test.ts
@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+
+import {
+  getActiveGenerationProvider,
+  getGenerationModelBinding,
+  getGenerationModelDescriptor,
+  listGenerationModelDescriptors,
+} from './index';
+
+test('BeatAPI is the default provider behind stable logical model ids', () => {
+  const provider = getActiveGenerationProvider();
+  const binding = getGenerationModelBinding({ modelId: 'seedance-2' });
+
+  assert.equal(provider.id, 'beatapi');
+  assert.equal(binding?.effectId, 9);
+  assert.equal(binding?.upstreamModelId, 'seedance-2');
+});
+
+test('model discovery exposes parameters and references without upstream URLs', () => {
+  const models = listGenerationModelDescriptors();
+  const seedance = getGenerationModelDescriptor('seedance-2');
+
+  assert.ok(models.length >= 10);
+  assert.equal(seedance?.providerId, 'beatapi');
+  assert.equal(seedance?.kind, 'video');
+  assert.ok(seedance?.parameterSchema);
+  assert.ok(seedance?.referenceSchema);
+  assert.equal('effectId' in (seedance ?? {}), false);
+  assert.equal('api' in (seedance ?? {}), false);
+});
+
+test('the product catalog no longer owns provider ids or upload paths', () => {
+  const source = readFileSync(
+    new URL('../effects/effect-registry.ts', import.meta.url),
+    'utf8'
+  );
+
+  assert.doesNotMatch(source, /^\s+effectId:\s*\d/m);
+  assert.doesNotMatch(source, /^\s+uploadPath:\s*['"]/m);
+  assert.doesNotMatch(source, /^\s+imageBucketName:\s*['"]/m);
+});
diff --git a/src/core/generation-providers/registry.ts b/src/core/generation-providers/registry.ts
new file mode 100644
index 0000000..cfa4839
--- /dev/null
+++ b/src/core/generation-providers/registry.ts
@@ -0,0 +1,113 @@
+import { envConfigs } from '@/config';
+import { registerProjectGenerationProviders } from '@/config/generation-providers';
+import { MockAdapter } from '@/core/adapters/mock-adapter';
+
+import { beatApiGenerationProvider, BEATAPI_PROVIDER_ID } from './beatapi-provider';
+import type {
+  GenerationProviderDefinition,
+  GenerationProviderModelBinding,
+} from './contracts';
+
+const providers = new Map<string, GenerationProviderDefinition>();
+let initialized = false;
+
+function addProvider(provider: GenerationProviderDefinition) {
+  const id = provider.id.trim();
+  if (!id) throw new Error('Generation provider id is required.');
+  if (providers.has(id)) {
+    throw new Error(`Generation provider ${id} is already registered.`);
+  }
+  const modelIds = new Set<string>();
+  const effectIds = new Set<number>();
+  for (const binding of provider.modelBindings) {
+    if (modelIds.has(binding.modelId)) {
+      throw new Error(`Provider ${id} has duplicate model ${binding.modelId}.`);
+    }
+    if (effectIds.has(binding.effectId)) {
+      throw new Error(`Provider ${id} has duplicate effect id ${binding.effectId}.`);
+    }
+    modelIds.add(binding.modelId);
+    effectIds.add(binding.effectId);
+  }
+  providers.set(id, { ...provider, id });
+}
+
+function ensureProvidersRegistered() {
+  if (initialized) return;
+  initialized = true;
+  addProvider(beatApiGenerationProvider);
+  addProvider({
+    id: 'mock',
+    label: 'Mock',
+    supports: ['image', 'video'],
+    modelBindings: [],
+    createAdapter: (effect) => new MockAdapter(effect),
+  });
+  registerProjectGenerationProviders(addProvider);
+}
+
+export const registerGenerationProvider = addProvider;
+
+export function listGenerationProviders() {
+  ensureProvidersRegistered();
+  return [...providers.values()];
+}
+
+export function getGenerationProvider(providerId: string) {
+  ensureProvidersRegistered();
+  return providers.get(providerId) ?? null;
+}
+
+export function getActiveGenerationProviderId() {
+  ensureProvidersRegistered();
+  const requested = envConfigs.generation_provider?.trim() || BEATAPI_PROVIDER_ID;
+  if (!providers.has(requested)) {
+    throw new Error(
+      `Generation provider ${requested} is not registered. Register it in src/config/generation-providers.ts or set GENERATION_PROVIDER=${BEATAPI_PROVIDER_ID}.`
+    );
+  }
+  return requested;
+}
+
+export function getActiveGenerationProvider() {
+  const providerId = getActiveGenerationProviderId();
+  const provider = getGenerationProvider(providerId);
+  if (!provider) throw new Error(`Generation provider ${providerId} is not registered.`);
+  return provider;
+}
+
+export function getGenerationModelBinding({
+  modelId,
+  providerId = getActiveGenerationProviderId(),
+}: {
+  modelId: string;
+  providerId?: string;
+}): GenerationProviderModelBinding | null {
+  const provider = getGenerationProvider(providerId);
+  return provider?.modelBindings.find((binding) => binding.modelId === modelId) ?? null;
+}
+
+export function getGenerationModelBindingByEffectId({
+  effectId,
+  providerId = getActiveGenerationProviderId(),
+}: {
+  effectId: number;
+  providerId?: string;
+}): GenerationProviderModelBinding | null {
+  const provider = getGenerationProvider(providerId);
+  return provider?.modelBindings.find((binding) => binding.effectId === effectId) ?? null;
+}
+
+export function resolveProviderUpstreamModel({
+  modelId,
+  variant,
+  providerId,
+}: {
+  modelId: string;
+  variant?: string | null;
+  providerId?: string;
+}) {
+  const binding = getGenerationModelBinding({ modelId, providerId });
+  if (!binding) return modelId;
+  return (variant && binding.upstreamModelByVariant?.[variant]) || binding.upstreamModelId;
+}
diff --git a/src/core/generation-providers/submit.ts b/src/core/generation-providers/submit.ts
new file mode 100644
index 0000000..b9cf4f2
--- /dev/null
+++ b/src/core/generation-providers/submit.ts
@@ -0,0 +1,72 @@
+import {
+  normalizeAssetFirstGenerationRequest,
+  type AssetFirstGenerationRequest,
+} from '@/core/commands/generation-contract';
+import { compileAssetFirstGenerationInput } from '@/core/commands/generation-compiler';
+import {
+  failGenerationUploadIntent,
+  issueGenerationUploadIntent,
+} from '@/core/effects/generation-upload-intent';
+import { submitEffectGeneration } from '@/core/effects/submit-generation';
+
+import {
+  getGenerationModelDescriptor,
+  validateGenerationModelInput,
+} from './model-catalog';
+import {
+  getActiveGenerationProvider,
+  getGenerationModelBinding,
+} from './registry';
+
+export async function submitAssetFirstGeneration({
+  generation: source,
+  origin,
+}: {
+  generation: AssetFirstGenerationRequest | unknown;
+  origin: 'ui' | 'mcp' | 'cli' | 'system';
+}) {
+  const generation = normalizeAssetFirstGenerationRequest(source);
+  const provider = getActiveGenerationProvider();
+  const binding = getGenerationModelBinding({
+    modelId: generation.modelId,
+    providerId: provider.id,
+  });
+  if (!binding) {
+    throw new Error(
+      `Model ${generation.modelId} is not available from ${provider.label}.`
+    );
+  }
+  const descriptor = getGenerationModelDescriptor(generation.modelId);
+  if (!descriptor || descriptor.kind !== generation.mode) {
+    throw new Error(
+      `Model ${generation.modelId} does not support ${generation.mode} generation.`
+    );
+  }
+  await provider.assertConfigured?.();
+  const intentId = await issueGenerationUploadIntent({
+    projectId: generation.projectId,
+    effectId: binding.effectId,
+    expectedUploadCount: 0,
+  });
+  try {
+    const input = await compileAssetFirstGenerationInput({
+      generation,
+      generationIntentId: intentId,
+    });
+    validateGenerationModelInput({ modelId: generation.modelId, input });
+    return await submitEffectGeneration({
+      effectId: binding.effectId,
+      input,
+      projectId: generation.projectId,
+      generationIntentId: intentId,
+      metadata: {
+        origin,
+        requestVersion: generation.version,
+        logicalModelId: generation.modelId,
+      },
+    });
+  } catch (error) {
+    await failGenerationUploadIntent({ intentId });
+    throw error;
+  }
+}
diff --git a/src/core/media/media-load-queue.ts b/src/core/media/media-load-queue.ts
new file mode 100644
index 0000000..31d47d9
--- /dev/null
+++ b/src/core/media/media-load-queue.ts
@@ -0,0 +1,57 @@
+const MAX_CONCURRENT_LOADS = 2;
+const LOAD_TIMEOUT_MS = 15_000;
+
+type QueueEntry = {
+  element: HTMLMediaElement;
+  src: string;
+  cancelled: boolean;
+};
+
+const pending: QueueEntry[] = [];
+let activeCount = 0;
+
+const startNext = () => {
+  while (activeCount < MAX_CONCURRENT_LOADS && pending.length > 0) {
+    const entry = pending.shift();
+    if (!entry || entry.cancelled) continue;
+
+    activeCount += 1;
+    let finished = false;
+    const finish = () => {
+      if (finished) return;
+      finished = true;
+      window.clearTimeout(timeoutId);
+      entry.element.removeEventListener('loadedmetadata', finish);
+      entry.element.removeEventListener('error', finish);
+      activeCount -= 1;
+      startNext();
+    };
+    const timeoutId = window.setTimeout(finish, LOAD_TIMEOUT_MS);
+    entry.element.addEventListener('loadedmetadata', finish, { once: true });
+    entry.element.addEventListener('error', finish, { once: true });
+
+    if (
+      entry.element.getAttribute('src') === entry.src &&
+      entry.element.readyState >= 1
+    ) {
+      finish();
+      continue;
+    }
+    entry.element.src = entry.src;
+  }
+};
+
+export function enqueueMediaMetadataLoad(
+  element: HTMLMediaElement,
+  src: string
+) {
+  const entry: QueueEntry = { element, src, cancelled: false };
+  if (!src) return () => undefined;
+  pending.push(entry);
+  startNext();
+  return () => {
+    entry.cancelled = true;
+    const index = pending.indexOf(entry);
+    if (index >= 0) pending.splice(index, 1);
+  };
+}
diff --git a/src/core/media/video-frame.test.ts b/src/core/media/video-frame.test.ts
new file mode 100644
index 0000000..34753c7
--- /dev/null
+++ b/src/core/media/video-frame.test.ts
@@ -0,0 +1,12 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { resolveVideoFrameTimestamp } from './video-frame';
+
+test('tail frame extraction seeks to the last decodable frame', () => {
+  assert.equal(resolveVideoFrameTimestamp({ durationSeconds: 10, position: 'last' }), 10 - 1 / 30);
+});
+test('explicit frame extraction clamps to the source duration', () => {
+  assert.equal(resolveVideoFrameTimestamp({ durationSeconds: 5, position: 9 }), 5 - 1 / 30);
+  assert.equal(resolveVideoFrameTimestamp({ durationSeconds: 5, position: -1 }), 0);
+});
diff --git a/src/core/media/video-frame.ts b/src/core/media/video-frame.ts
new file mode 100644
index 0000000..babddad
--- /dev/null
+++ b/src/core/media/video-frame.ts
@@ -0,0 +1,113 @@
+export type ExtractedVideoFrame = {
+  file: File;
+  width: number;
+  height: number;
+  timeSeconds: number;
+  durationSeconds: number;
+};
+
+const FRAME_EPSILON_SECONDS = 1 / 30;
+
+export const resolveVideoFrameTimestamp = ({
+  durationSeconds,
+  position,
+}: {
+  durationSeconds: number;
+  position: 'first' | 'last' | number;
+}) => {
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+    throw new Error('Video duration is unavailable');
+  }
+  if (position === 'first') return Math.min(0.05, durationSeconds / 2);
+  if (position === 'last') {
+    return Math.max(0, durationSeconds - FRAME_EPSILON_SECONDS);
+  }
+  if (!Number.isFinite(position)) throw new Error('Frame time is invalid');
+  return Math.max(0, Math.min(durationSeconds - FRAME_EPSILON_SECONDS, position));
+};
+
+const waitForVideoEvent = (
+  video: HTMLVideoElement,
+  eventName: 'loadedmetadata' | 'seeked'
+) =>
+  new Promise<void>((resolve, reject) => {
+    const cleanup = () => {
+      video.removeEventListener(eventName, handleSuccess);
+      video.removeEventListener('error', handleError);
+    };
+    const handleSuccess = () => {
+      cleanup();
+      resolve();
+    };
+    const handleError = () => {
+      cleanup();
+      reject(new Error('Video frame could not be decoded'));
+    };
+    video.addEventListener(eventName, handleSuccess, { once: true });
+    video.addEventListener('error', handleError, { once: true });
+  });
+
+const canvasToPngBlob = (canvas: HTMLCanvasElement) =>
+  new Promise<Blob>((resolve, reject) => {
+    canvas.toBlob((blob) => {
+      if (blob) resolve(blob);
+      else reject(new Error('Video frame could not be encoded'));
+    }, 'image/png');
+  });
+
+export async function extractVideoFrame({
+  url,
+  position = 'last',
+  filename = 'video-tail-frame.png',
+}: {
+  url: string;
+  position?: 'first' | 'last' | number;
+  filename?: string;
+}): Promise<ExtractedVideoFrame> {
+  if (typeof document === 'undefined') {
+    throw new Error('Video frame extraction requires the local browser runtime');
+  }
+  const video = document.createElement('video');
+  video.preload = 'auto';
+  video.muted = true;
+  video.playsInline = true;
+  const cleanup = () => {
+    video.pause();
+    video.removeAttribute('src');
+    video.load();
+  };
+
+  try {
+    const metadataReady = waitForVideoEvent(video, 'loadedmetadata');
+    video.src = url;
+    video.load();
+    await metadataReady;
+    if (video.videoWidth <= 0 || video.videoHeight <= 0) {
+      throw new Error('Video dimensions are unavailable');
+    }
+    const timeSeconds = resolveVideoFrameTimestamp({
+      durationSeconds: video.duration,
+      position,
+    });
+    const seekReady = waitForVideoEvent(video, 'seeked');
+    video.currentTime = timeSeconds;
+    await seekReady;
+
+    const canvas = document.createElement('canvas');
+    canvas.width = video.videoWidth;
+    canvas.height = video.videoHeight;
+    const context = canvas.getContext('2d');
+    if (!context) throw new Error('Canvas rendering is unavailable');
+    context.drawImage(video, 0, 0, canvas.width, canvas.height);
+    const blob = await canvasToPngBlob(canvas);
+    return {
+      file: new File([blob], filename, { type: 'image/png' }),
+      width: canvas.width,
+      height: canvas.height,
+      timeSeconds,
+      durationSeconds: video.duration,
+    };
+  } finally {
+    cleanup();
+  }
+}
diff --git a/src/core/projects/import-local-asset.test.ts b/src/core/projects/import-local-asset.test.ts
new file mode 100644
index 0000000..b5ffc88
--- /dev/null
+++ b/src/core/projects/import-local-asset.test.ts
@@ -0,0 +1,26 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { importLocalProjectAsset } from './import-local-asset';
+
+test('asset import rejects a relative file path', async () => {
+  await assert.rejects(
+    () =>
+      importLocalProjectAsset({
+        projectId: 'project-1',
+        filePath: 'clip.mp4',
+      }),
+    /absolute file path/i
+  );
+});
+
+test('asset import rejects a missing file path', async () => {
+  await assert.rejects(
+    () =>
+      importLocalProjectAsset({
+        projectId: 'project-1',
+        filePath: '/tmp/beatdesign-missing-asset-file.mp4',
+      }),
+    /not found/i
+  );
+});
diff --git a/src/core/projects/import-local-asset.ts b/src/core/projects/import-local-asset.ts
new file mode 100644
index 0000000..eb71d32
--- /dev/null
+++ b/src/core/projects/import-local-asset.ts
@@ -0,0 +1,134 @@
+import { readFile, stat } from 'node:fs/promises';
+import { basename, isAbsolute, resolve } from 'node:path';
+
+import { envConfigs } from '@/config';
+import {
+  detectUploadedMediaType,
+  getCanonicalUploadedMediaMimeType,
+  validateUploadedAudioFile,
+  validateUploadedImageFile,
+  validateUploadedVideoFile,
+} from '@/core/effects/validation';
+import { isSupportedRasterImage } from '@/lib/image-upload-validation';
+import { getProject } from '@/core/projects/projects';
+import {
+  LOCAL_PROJECT_ASSET_BUCKET,
+  LOCAL_PROJECT_ASSET_PROVIDER,
+  persistLocalProjectAsset,
+  removePersistedLocalProjectAsset,
+} from '@/core/projects/local-project-assets';
+import {
+  deleteUserAssetById,
+  linkProjectAsset,
+  recordUserAsset,
+} from '@/core/workspace-lib/assets/user-assets';
+
+export function validateLocalAssetImportCandidate({
+  filename,
+  size,
+}: {
+  filename: string;
+  size: number;
+}) {
+  const detectedFile = { name: filename, type: '', size };
+  const mediaType = detectUploadedMediaType(detectedFile);
+  if (!mediaType) throw new Error('Unsupported project asset type.');
+
+  const mimeType = getCanonicalUploadedMediaMimeType(detectedFile);
+  if (!mimeType) throw new Error('Unsupported project asset type.');
+  const file = { ...detectedFile, type: mimeType };
+  const validation =
+    mediaType === 'image'
+      ? validateUploadedImageFile(file)
+      : mediaType === 'video'
+        ? validateUploadedVideoFile(file)
+        : validateUploadedAudioFile(file);
+  if (!validation.ok) {
+    throw new Error('Project asset type or size is not supported.');
+  }
+
+  return { mediaType, mimeType };
+}
+
+export async function importLocalProjectAsset({
+  projectId,
+  filePath,
+}: {
+  projectId: string;
+  filePath: string;
+}) {
+  if (envConfigs.database_provider !== 'sqlite') {
+    throw new Error('Local asset import is only available in SQLite mode.');
+  }
+  const trimmedPath = filePath.trim();
+  if (!isAbsolute(trimmedPath)) {
+    throw new Error('Asset import requires an absolute file path.');
+  }
+  const absolutePath = resolve(trimmedPath);
+  const fileStat = await stat(absolutePath).catch(() => null);
+  if (!fileStat?.isFile()) {
+    throw new Error('Asset file was not found.');
+  }
+  const filename = basename(absolutePath);
+  let candidate = validateLocalAssetImportCandidate({
+    filename,
+    size: fileStat.size,
+  });
+  const currentProject = await getProject({ projectId });
+  if (!currentProject || currentProject.status !== 'active') {
+    throw new Error('Project not found.');
+  }
+
+  const bytes = new Uint8Array(await readFile(absolutePath));
+  if (bytes.byteLength !== fileStat.size) {
+    candidate = validateLocalAssetImportCandidate({
+      filename,
+      size: bytes.byteLength,
+    });
+  }
+  const { mediaType, mimeType } = candidate;
+  if (mediaType === 'image' && !isSupportedRasterImage(mimeType, bytes)) {
+    throw new Error('Image contents do not match a supported raster format.');
+  }
+
+  const persisted = await persistLocalProjectAsset({
+    projectId,
+    filename,
+    mimeType,
+    bytes,
+  });
+  try {
+    const assetId = await recordUserAsset({
+      id: persisted.assetId,
+      type: mediaType,
+      source: 'upload',
+      bucket: LOCAL_PROJECT_ASSET_BUCKET,
+      objectKey: persisted.objectKey,
+      publicUrl: persisted.publicUrl,
+      mimeType,
+      sizeBytes: persisted.sizeBytes,
+      sha256: persisted.sha256,
+      filename: persisted.filename,
+      storageProvider: LOCAL_PROJECT_ASSET_PROVIDER,
+      assetClass: 'original',
+      originProjectId: projectId,
+    });
+    await linkProjectAsset({
+      projectId,
+      assetId,
+      role: 'upload',
+    });
+    return {
+      id: assetId,
+      type: mediaType,
+      publicUrl: persisted.publicUrl,
+      filename: persisted.filename,
+      mimeType,
+      sizeBytes: persisted.sizeBytes,
+    };
+  } catch (error) {
+    await deleteUserAssetById(persisted.assetId).catch(() => undefined);
+    await removePersistedLocalProjectAsset(persisted.filePath);
+    throw error;
+  }
+}
diff --git a/src/core/projects/local-project-asset-url.test.ts b/src/core/projects/local-project-asset-url.test.ts
new file mode 100644
index 0000000..c520a17
--- /dev/null
+++ b/src/core/projects/local-project-asset-url.test.ts
@@ -0,0 +1,20 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { parseLocalProjectAssetUrl } from './local-project-asset-url';
+
+test('parses durable local project asset ids from relative and absolute urls', () => {
+  assert.deepEqual(
+    parseLocalProjectAssetUrl('/api/app/projects/project-1/assets/asset-2'),
+    { projectId: 'project-1', assetId: 'asset-2' }
+  );
+  assert.deepEqual(
+    parseLocalProjectAssetUrl(
+      'http://127.0.0.1:3020/api/app/projects/project-1/assets/asset-2'
+    ),
+    { projectId: 'project-1', assetId: 'asset-2' }
+  );
+});
+test('does not invent asset ids for provider urls', () => {
+  assert.equal(parseLocalProjectAssetUrl('https://cdn.example.com/video.mp4'), null);
+});
diff --git a/src/core/projects/local-project-asset-url.ts b/src/core/projects/local-project-asset-url.ts
new file mode 100644
index 0000000..9a5b91b
--- /dev/null
+++ b/src/core/projects/local-project-asset-url.ts
@@ -0,0 +1,18 @@
+const LOCAL_PROJECT_ASSET_PATH =
+  /^\/api\/app\/projects\/([^/]+)\/assets\/([^/?#]+)(?:[/?#]|$)/;
+
+export const parseLocalProjectAssetUrl = (url: string | null | undefined) => {
+  if (!url) return null;
+  let pathname = url;
+  try {
+    pathname = new URL(url, 'http://127.0.0.1').pathname;
+  } catch {
+    return null;
+  }
+  const match = LOCAL_PROJECT_ASSET_PATH.exec(pathname);
+  if (!match) return null;
+  return {
+    projectId: decodeURIComponent(match[1]),
+    assetId: decodeURIComponent(match[2]),
+  };
+};
diff --git a/src/core/projects/local-project-assets.ts b/src/core/projects/local-project-assets.ts
index 24edb64..f10b184 100644
--- a/src/core/projects/local-project-assets.ts
+++ b/src/core/projects/local-project-assets.ts
@@ -16,6 +16,11 @@ const extensionForMimeType = (mimeType: string) => {
   if (normalized.includes('quicktime')) return '.mov';
   if (normalized.includes('webm')) return '.webm';
   if (normalized.includes('mp4')) return '.mp4';
+  if (normalized.includes('mpeg')) return '.mp3';
+  if (normalized.includes('wav')) return '.wav';
+  if (normalized.includes('m4a')) return '.m4a';
+  if (normalized.includes('aac')) return '.aac';
+  if (normalized.includes('ogg')) return '.ogg';
   return '';
 };
 
diff --git a/src/core/projects/project-canvas-document.ts b/src/core/projects/project-canvas-document.ts
index c5e96df..6637e39 100644
--- a/src/core/projects/project-canvas-document.ts
+++ b/src/core/projects/project-canvas-document.ts
@@ -18,7 +18,6 @@ import type {
 type SnapshotFramesById = Record<string, ProjectSnapshotShapeFrame>;
 type NonDraftCanvasCard = CanvasCard & {
   kind: 'asset';
-  url: string;
 };
 
 export const mergeCanvasRuntimeCardsIntoHistoryDocument = ({
@@ -157,8 +156,8 @@ export const createProjectSnapshotRestorePlan = (
     .filter(
       (card): card is NonDraftCanvasCard =>
         card.kind === 'asset' &&
-        typeof card.url === 'string' &&
-        card.url.length > 0
+        (card.type === 'timeline' ||
+          (typeof card.url === 'string' && card.url.length > 0))
     )
     .sort((left, right) => left.id.localeCompare(right.id))
     .map((card) => ({
diff --git a/src/core/projects/project-snapshot.test.ts b/src/core/projects/project-snapshot.test.ts
index 52aae34..5696707 100644
--- a/src/core/projects/project-snapshot.test.ts
+++ b/src/core/projects/project-snapshot.test.ts
@@ -177,3 +177,40 @@ test('persists Canvas video analysis mode, depth, and text output', () => {
     '00:00 The subject enters frame.'
   );
 });
+
+test('persists Audio Asset and Timeline nodes across Canvas reloads', () => {
+  const normalized = normalizeProjectSnapshotDocument({
+    version: 3,
+    cards: [
+      {
+        id: 'audio-1',
+        kind: 'asset',
+        type: 'audio',
+        name: 'Background music',
+        url: '/api/app/projects/project-1/assets/audio-1',
+        audioRole: 'music',
+        durationSec: 5,
+      },
+      {
+        id: 'timeline:one',
+        kind: 'asset',
+        type: 'timeline',
+        name: 'Timeline 1',
+        url: null,
+        timelineId: 'one',
+        durationSec: 4,
+        clipCount: 2,
+      },
+    ],
+    frames: {
+      'audio-1': { x: 0, y: 0, w: 320, h: 104 },
+      'timeline:one': { x: 380, y: 0, w: 360, h: 220 },
+    },
+  });
+
+  assert.equal(normalized.cards[0]?.type, 'audio');
+  assert.equal(normalized.cards[0]?.audioRole, 'music');
+  assert.equal(normalized.cards[1]?.type, 'timeline');
+  assert.equal(normalized.cards[1]?.clipCount, 2);
+  assert.ok(normalized.frames['timeline:one']);
+});
diff --git a/src/core/projects/project-snapshot.ts b/src/core/projects/project-snapshot.ts
index f10abcb..68c4ec1 100644
--- a/src/core/projects/project-snapshot.ts
+++ b/src/core/projects/project-snapshot.ts
@@ -88,7 +88,6 @@ const normalizeFrame = (value: unknown): ProjectSnapshotShapeFrame | null => {
   ) {
     return null;
   }
-
   return { x, y, w, h };
 };
 
@@ -170,7 +169,7 @@ const normalizeCard = (value: unknown): CanvasCard | null => {
     !id ||
     id.length > MAX_ID_CHARS ||
     !['asset', 'generation', 'output'].includes(kind || '') ||
-    !['image', 'video'].includes(type || '') ||
+    !['image', 'video', 'audio', 'timeline'].includes(type || '') ||
     !name ||
     name.length > MAX_NAME_CHARS
   ) {
@@ -194,6 +193,9 @@ const normalizeCard = (value: unknown): CanvasCard | null => {
   ) {
     return null;
   }
+  if (kind !== 'asset' && (type === 'audio' || type === 'timeline')) {
+    return null;
+  }
 
   return {
     id,
@@ -275,9 +277,40 @@ const normalizeCard = (value: unknown): CanvasCard | null => {
     generationSnapshot,
     pinnedOutputId:
       typeof value.pinnedOutputId === 'string' ? value.pinnedOutputId : null,
-  };
+    audioRole:
+      value.audioRole === 'music' ||
+      value.audioRole === 'voice' ||
+      value.audioRole === 'sound_effect' ||
+      value.audioRole === 'source_audio' ||
+      value.audioRole === 'reference'
+        ? value.audioRole
+        : undefined,
+    durationSec: isFiniteNumber(value.durationSec)
+      ? Math.max(0, value.durationSec)
+      : null,
+    waveformPeaks: Array.isArray(value.waveformPeaks)
+      ? value.waveformPeaks
+          .filter(isFiniteNumber)
+          .slice(0, 256)
+          .map((peak) => Math.max(0, Math.min(1, peak)))
+      : undefined,
+    timelineId:
+      typeof value.timelineId === 'string'
+        ? value.timelineId.slice(0, MAX_ID_CHARS)
+        : null,
+    clipCount: isFiniteNumber(value.clipCount)
+      ? Math.max(0, Math.floor(value.clipCount))
+      : null,
+    lastRenderAssetId:
+      typeof value.lastRenderAssetId === 'string'
+        ? value.lastRenderAssetId.slice(0, MAX_ID_CHARS)
+        : null,
+  } as CanvasCard;
 };
 
+export const normalizeProjectSnapshotCard = (value: unknown) =>
+  normalizeCard(value);
+
 export const createEmptyProjectSnapshot = (): ProjectSnapshotDocument => ({
   version: 3,
   cards: [],
diff --git a/src/core/workspace-lib/app/local-project-asset-client.test.ts b/src/core/workspace-lib/app/local-project-asset-client.test.ts
index dfb8672..dcedbce 100644
--- a/src/core/workspace-lib/app/local-project-asset-client.test.ts
+++ b/src/core/workspace-lib/app/local-project-asset-client.test.ts
@@ -15,6 +15,11 @@ test('uploads imported media immediately with trusted multipart request headers'
   const asset = await uploadLocalProjectAsset({
     projectId: 'project 1',
     file,
+    assetClass: 'derived',
+    width: 1920,
+    height: 1080,
+    durationMs: 3600,
+    metadata: { operation: 'timeline_extract', sourceInSec: 3.2 },
     fetchImpl: (async (url, init) => {
       capturedUrl = String(url);
       capturedInit = init;
@@ -39,5 +44,14 @@ test('uploads imported media immediately with trusted multipart request headers'
   );
   assert.equal(new Headers(capturedInit?.headers).has('content-type'), false);
   assert.ok(capturedInit?.body instanceof FormData);
+  const body = capturedInit?.body as FormData;
+  assert.equal(body.get('assetClass'), 'derived');
+  assert.equal(body.get('width'), '1920');
+  assert.equal(body.get('height'), '1080');
+  assert.equal(body.get('durationMs'), '3600');
+  assert.equal(
+    body.get('metadata'),
+    JSON.stringify({ operation: 'timeline_extract', sourceInSec: 3.2 })
+  );
   assert.equal(asset.id, 'asset-1');
 });
diff --git a/src/core/workspace-lib/app/local-project-asset-client.ts b/src/core/workspace-lib/app/local-project-asset-client.ts
index db76cbe..af47cae 100644
--- a/src/core/workspace-lib/app/local-project-asset-client.ts
+++ b/src/core/workspace-lib/app/local-project-asset-client.ts
@@ -5,24 +5,42 @@ import {
 
 export type PersistedLocalProjectAsset = {
   id: string;
-  type: 'image' | 'video';
+  type: 'image' | 'video' | 'audio';
   publicUrl: string;
   filename: string;
   mimeType: string;
   sizeBytes: number;
+  width?: number;
+  height?: number;
+  durationMs?: number;
 };
 
 export const uploadLocalProjectAsset = async ({
   projectId,
   file,
+  assetClass = 'original',
+  metadata,
+  width,
+  height,
+  durationMs,
   fetchImpl = fetch,
 }: {
   projectId: string;
   file: File;
+  assetClass?: 'original' | 'derived';
+  metadata?: Record<string, unknown>;
+  width?: number;
+  height?: number;
+  durationMs?: number;
   fetchImpl?: typeof fetch;
 }): Promise<PersistedLocalProjectAsset> => {
   const formData = new FormData();
   formData.set('file', file, file.name);
+  formData.set('assetClass', assetClass);
+  if (metadata) formData.set('metadata', JSON.stringify(metadata));
+  if (Number.isFinite(width)) formData.set('width', String(width));
+  if (Number.isFinite(height)) formData.set('height', String(height));
+  if (Number.isFinite(durationMs)) formData.set('durationMs', String(durationMs));
   const response = await fetchImpl(
     `/api/app/projects/${encodeURIComponent(projectId)}/assets`,
     {
diff --git a/src/core/workspace-lib/app/workspace-client-api.ts b/src/core/workspace-lib/app/workspace-client-api.ts
index bdf0745..d07ebea 100644
--- a/src/core/workspace-lib/app/workspace-client-api.ts
+++ b/src/core/workspace-lib/app/workspace-client-api.ts
@@ -9,12 +9,16 @@ export type RecentAsset = {
   width: number | null;
   height: number | null;
   durationMs?: number | null;
+  mimeType?: string | null;
+  assetClass?: string | null;
+  metadata?: unknown;
   createdAt: string | Date;
 };
 
 export type RecentAssetsResponse = {
   images: RecentAsset[];
   videos: RecentAsset[];
+  audios: RecentAsset[];
 };
 
 export async function fetchRecentAssets(
diff --git a/src/core/workspace-lib/assets/user-assets.ts b/src/core/workspace-lib/assets/user-assets.ts
index d5ebbd4..50567a0 100644
--- a/src/core/workspace-lib/assets/user-assets.ts
+++ b/src/core/workspace-lib/assets/user-assets.ts
@@ -164,6 +164,37 @@ export const getProjectAssetById = async ({
   return rows[0] ?? null;
 };
 
+export const listProjectAssets = async ({
+  projectId,
+  limit = 100,
+}: {
+  projectId: string;
+  limit?: number;
+}) => {
+  const db = await getDb();
+  return db
+    .select({
+      id: userAsset.id,
+      type: userAsset.type,
+      source: userAsset.source,
+      assetClass: userAsset.assetClass,
+      publicUrl: userAsset.publicUrl,
+      filename: userAsset.filename,
+      mimeType: userAsset.mimeType,
+      sizeBytes: userAsset.sizeBytes,
+      width: userAsset.width,
+      height: userAsset.height,
+      durationMs: userAsset.durationMs,
+      category: projectAssetMembership.category,
+      createdAt: projectAssetMembership.createdAt,
+    })
+    .from(projectAssetMembership)
+    .innerJoin(userAsset, eq(userAsset.id, projectAssetMembership.assetId))
+    .where(eq(projectAssetMembership.projectId, projectId))
+    .orderBy(projectAssetMembership.createdAt)
+    .limit(Math.max(1, Math.min(500, Math.floor(limit))));
+};
+
 export const deleteUserAssetById = async (assetId: string) => {
   const db = await getDb();
   await db.delete(userAsset).where(eq(userAsset.id, assetId));
diff --git a/src/lib/project-asset-media-request.test.ts b/src/lib/project-asset-media-request.test.ts
new file mode 100644
index 0000000..32ba6ac
--- /dev/null
+++ b/src/lib/project-asset-media-request.test.ts
@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  normalizeProjectAssetMediaRequest,
+  shouldNormalizeProjectAssetMediaRequest,
+} from './project-asset-media-request';
+
+test('normalizes browser media destinations for dynamic project assets', () => {
+  const request = new Request(
+    'http://127.0.0.1:3020/api/app/projects/project-1/assets/asset-1',
+    { headers: { range: 'bytes=0-', 'sec-fetch-dest': 'video' } }
+  );
+  const normalized = normalizeProjectAssetMediaRequest(request);
+
+  assert.equal(normalized.headers.get('sec-fetch-dest'), null);
+  assert.equal(normalized.headers.get('range'), 'bytes=0-');
+  assert.equal(normalized.url, request.url);
+});
+
+test('leaves ordinary routes and non-media requests unchanged', () => {
+  const pageImage = new Request('http://127.0.0.1:3020/logo.png', {
+    headers: { 'sec-fetch-dest': 'image' },
+  });
+  const assetFetch = new Request(
+    'http://127.0.0.1:3020/api/app/projects/project-1/assets/asset-1',
+    { headers: { 'sec-fetch-dest': 'empty' } }
+  );
+
+  assert.equal(normalizeProjectAssetMediaRequest(pageImage), pageImage);
+  assert.equal(normalizeProjectAssetMediaRequest(assetFetch), assetFetch);
+});
+
+test('recognizes the dev-server project media route before Fetch conversion', () => {
+  assert.equal(
+    shouldNormalizeProjectAssetMediaRequest({
+      method: 'GET',
+      url: '/api/app/projects/project-1/assets/asset-1',
+      destination: 'video',
+    }),
+    true
+  );
+  assert.equal(
+    shouldNormalizeProjectAssetMediaRequest({
+      method: 'POST',
+      url: '/api/app/projects/project-1/assets/asset-1',
+      destination: 'video',
+    }),
+    false
+  );
+  assert.equal(
+    shouldNormalizeProjectAssetMediaRequest({
+      method: 'HEAD',
+      url: '/api/app/projects/project-1/assets/asset-1',
+      destination: 'video',
+    }),
+    true
+  );
+});
diff --git a/src/lib/project-asset-media-request.ts b/src/lib/project-asset-media-request.ts
new file mode 100644
index 0000000..c222ee6
--- /dev/null
+++ b/src/lib/project-asset-media-request.ts
@@ -0,0 +1,45 @@
+const PROJECT_ASSET_MEDIA_PATH =
+  /^\/api\/app\/projects\/[^/]+\/assets\/[^/]+\/?$/;
+
+const MEDIA_FETCH_DESTINATIONS = new Set(['audio', 'image', 'video']);
+
+export function shouldNormalizeProjectAssetMediaRequest({
+  method,
+  url,
+  destination,
+}: {
+  method: string | undefined;
+  url: string | undefined;
+  destination: string | undefined;
+}) {
+  if ((method !== 'GET' && method !== 'HEAD') || !url || !destination) {
+    return false;
+  }
+  if (!MEDIA_FETCH_DESTINATIONS.has(destination.toLowerCase())) return false;
+  return PROJECT_ASSET_MEDIA_PATH.test(new URL(url, 'http://localhost').pathname);
+}
+
+/**
+ * TanStack Start treats browser media destinations as static asset requests
+ * before file-route handlers run. Project assets are dynamic API resources, so
+ * normalize only this route back to an ordinary fetch destination.
+ */
+export function normalizeProjectAssetMediaRequest(request: Request) {
+  if (
+    !shouldNormalizeProjectAssetMediaRequest({
+      method: request.method,
+      url: request.url,
+      destination: request.headers.get('sec-fetch-dest') ?? undefined,
+    })
+  ) {
+    return request;
+  }
+
+  const headers = new Headers(request.headers);
+  headers.delete('sec-fetch-dest');
+  return new Request(request.url, {
+    method: request.method,
+    headers,
+    signal: request.signal,
+  });
+}
diff --git a/src/mcp/server.contract.test.ts b/src/mcp/server.contract.test.ts
new file mode 100644
index 0000000..f73a3c3
--- /dev/null
+++ b/src/mcp/server.contract.test.ts
@@ -0,0 +1,33 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+
+import { BEATDESIGN_MCP_TOOL_NAMES } from './tools';
+
+const source = readFileSync(new URL('./server.ts', import.meta.url), 'utf8');
+
+test('MCP registers Canvas, Generation, and Editor tool groups', () => {
+  for (const tool of BEATDESIGN_MCP_TOOL_NAMES) {
+    assert.match(source, new RegExp(`['"]${tool}['"]`));
+  }
+});
+
+test('MCP writes use a fixed origin and never expose document replacement', () => {
+  assert.match(source, /origin: 'mcp'/);
+  assert.doesNotMatch(source, /editor\.replace_document/);
+  assert.doesNotMatch(source, /saveProjectSnapshot/);
+  assert.doesNotMatch(source, /saveProjectTimeline/);
+});
+
+test('external generation submits directly and leaves API policy to BeatAPI', () => {
+  assert.match(source, /submitAssetFirstGeneration/);
+  assert.doesNotMatch(source, /confirmedExternalGeneration/);
+  assert.doesNotMatch(source, /CONFIRMATION_REQUIRED/);
+  assert.doesNotMatch(source, /generation-confirm/);
+});
+
+test('MCP advertises concrete Canvas and Editor operation schemas', () => {
+  assert.match(source, /z\.array\(canvasOperationSchema\)/);
+  assert.match(source, /z\.array\(editorOperationSchema\)/);
+  assert.doesNotMatch(source, /operations:\s*z\.array\(z\.unknown\(\)\)/);
+});
diff --git a/src/mcp/server.runtime.test.ts b/src/mcp/server.runtime.test.ts
new file mode 100644
index 0000000..721c6e7
--- /dev/null
+++ b/src/mcp/server.runtime.test.ts
@@ -0,0 +1,122 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+import { z } from 'zod';
+
+import { persistBeatDesignCommand } from '@/core/commands/persist';
+import {
+  canvasOperationSchema,
+  editorOperationSchema,
+} from '@/core/commands/schema';
+import { createTimelineDocument } from '@/core/editor/timeline-document';
+import { listGenerationModelDescriptors } from '@/core/generation-providers';
+
+import { BEATDESIGN_MCP_TOOL_NAMES } from './tools';
+
+test('MCP tool catalog is exactly 20 named tools', () => {
+  const source = readFileSync(new URL('./server.ts', import.meta.url), 'utf8');
+  const registered = [...source.matchAll(/server\.registerTool\(\s*'([^']+)'/g)].map(
+    (match) => match[1]
+  );
+  assert.equal(BEATDESIGN_MCP_TOOL_NAMES.length, 20);
+  assert.deepEqual(registered, [...BEATDESIGN_MCP_TOOL_NAMES]);
+});
+
+test('MCP origin cannot replace a timeline document', async () => {
+  const result = await persistBeatDesignCommand({
+    projectId: 'project-mcp-guard',
+    origin: 'mcp',
+    commandId: 'cmd-replace',
+    idempotencyKey: 'idem-replace',
+    command: {
+      type: 'editor.replace_document',
+      document: createTimelineDocument({
+        projectId: 'project-mcp-guard',
+        name: 'Blocked',
+      }),
+    },
+  });
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.equal(result.code, 'INVALID_COMMAND');
+    assert.match(result.message, /editor\.apply/);
+  }
+});
+
+test('Canvas and Editor operations expose concrete JSON Schemas to MCP hosts', () => {
+  const canvasJson = JSON.stringify(z.toJSONSchema(canvasOperationSchema));
+  const editorJson = JSON.stringify(z.toJSONSchema(editorOperationSchema));
+
+  for (const operation of [
+    'upsert_card',
+    'remove_card',
+    'move_card',
+    'set_references',
+    'upsert_timeline_node',
+  ]) {
+    assert.match(canvasJson, new RegExp(operation));
+  }
+  for (const operation of [
+    'add_clip',
+    'trim_clip',
+    'split_clip',
+    'move_clip',
+    'set_clip_duration',
+    'remove_clip',
+    'update_audio',
+    'add_take',
+    'activate_take',
+    'set_render',
+  ]) {
+    assert.match(editorJson, new RegExp(operation));
+  }
+  assert.match(canvasJson, /modelId/);
+  assert.match(canvasJson, /referenceCardIds/);
+  assert.match(editorJson, /rightClipId/);
+  assert.match(editorJson, /image/);
+});
+
+test('Canvas upsert accepts a minimal explicit generation card', () => {
+  const operation = canvasOperationSchema.parse({
+    type: 'upsert_card',
+    card: {
+      id: 'generation-1',
+      kind: 'generation',
+      type: 'video',
+      name: 'Continue shot',
+      modelId: 'seedance-2',
+      prompt: 'Continue the shot',
+    },
+  });
+  assert.equal(operation.type, 'upsert_card');
+  assert.equal(operation.card.status, 'idle');
+  assert.equal(operation.card.duration, '5s');
+});
+
+test('Canvas get cards can be applied back through upsert_card', () => {
+  const operation = canvasOperationSchema.parse({
+    type: 'upsert_card',
+    card: {
+      id: 'shape:legacy',
+      kind: 'asset',
+      type: 'video',
+      name: '  clip  ',
+      duration: '5',
+      aspectRatio: 'not-a-ratio',
+      extraField: 'drop-me',
+      url: '/api/app/projects/p/assets/a',
+      assetId: 'asset-1',
+    },
+  });
+  assert.equal(operation.type, 'upsert_card');
+  assert.equal(operation.card.name, 'clip');
+  assert.equal(operation.card.duration, '5s');
+  assert.equal(operation.card.aspectRatio, '1:1');
+  assert.equal(operation.card.assetId, 'asset-1');
+});
+
+test('model discovery used by MCP returns a live catalog', () => {
+  const models = listGenerationModelDescriptors();
+  assert.ok(models.length >= 10);
+  assert.ok(models.every((model) => typeof model.id === 'string' && model.id.length > 0));
+});
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
new file mode 100644
index 0000000..25266db
--- /dev/null
+++ b/src/mcp/server.ts
@@ -0,0 +1,517 @@
+import { McpServer } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import * as z from 'zod/v4';
+
+import { envConfigs } from '@/config';
+import {
+  beatDesignCommandSchema,
+  canvasCardSchema,
+  canvasOperationSchema,
+  editorOperationSchema,
+} from '@/core/commands/schema';
+import { importLocalProjectAsset } from '@/core/projects/import-local-asset';
+import { createCommandId } from '@/core/commands/contracts';
+import { persistBeatDesignCommand } from '@/core/commands/persist';
+import { listCommandReceipts } from '@/core/commands/receipts';
+import { diagnoseTimeline } from '@/core/editor/timeline-diagnostics';
+import { loadProjectTimeline } from '@/core/editor/timeline-state';
+import { syncGeneration } from '@/core/effects/generation-sync';
+import { listProjectGenerations } from '@/core/effects/project-generations';
+import { getGenerationById } from '@/core/effects/record-generation';
+import {
+  getGenerationModelDescriptor,
+  listGenerationModelDescriptors,
+  submitAssetFirstGeneration,
+} from '@/core/generation-providers';
+import {
+  createProject,
+  getProject,
+  loadProjects,
+  loadProjectWithLatestSnapshot,
+} from '@/core/projects/projects';
+import {
+  getProjectAssetById,
+  listProjectAssets,
+} from '@/core/workspace-lib/assets/user-assets';
+
+const VERSION = '0.2.0';
+const idSchema = z.string().trim().min(1).max(200);
+
+const toCommandCanvasCards = (cards: unknown[]) =>
+  cards.flatMap((card) => {
+    const parsed = canvasCardSchema.safeParse(card);
+    return parsed.success ? [parsed.data] : [];
+  });
+const commandMetadataSchema = z.object({
+  expectedRevision: z.number().int().min(0).nullable().optional(),
+  commandId: idSchema.optional(),
+  idempotencyKey: idSchema.optional(),
+});
+
+const generationReferenceSchema = z.object({
+  assetId: idSchema,
+  role: z.enum([
+    'source',
+    'reference',
+    'style',
+    'subject',
+    'pose',
+    'first_frame',
+    'last_frame',
+    'audio_track',
+  ]),
+  deliveryUrl: z.string().trim().min(1).max(4096).optional(),
+});
+
+const jsonResult = (result: unknown) => ({
+  content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+  structuredContent: { result },
+});
+
+class BeatDesignMcpToolError extends Error {
+  readonly status: number;
+  readonly details: Record<string, unknown>;
+
+  constructor(status: number, details: Record<string, unknown>) {
+    super(
+      typeof details.error === 'string'
+        ? details.error
+        : `BeatAPI request failed with status ${status}.`
+    );
+    this.name = 'BeatDesignMcpToolError';
+    this.status = status;
+    this.details = details;
+  }
+}
+
+const errorResult = (error: unknown) => ({
+  content: [
+    {
+      type: 'text' as const,
+      text: error instanceof Error ? error.message : 'BeatDesign tool failed.',
+    },
+  ],
+  isError: true,
+  structuredContent: {
+    error:
+      error instanceof BeatDesignMcpToolError
+        ? {
+            message: error.message,
+            status: error.status,
+            details: error.details,
+          }
+        : {
+            message:
+              error instanceof Error ? error.message : 'BeatDesign tool failed.',
+          },
+  },
+});
+
+const withToolErrors = <TArgs, TResult>(
+  handler: (args: TArgs) => Promise<TResult> | TResult
+) => async (args: TArgs) => {
+  try {
+    return jsonResult(await handler(args));
+  } catch (error) {
+    return errorResult(error);
+  }
+};
+
+async function executeExternalCommand({
+  projectId,
+  command,
+  expectedRevision,
+  commandId = createCommandId(),
+  idempotencyKey = commandId,
+}: {
+  projectId: string;
+  command: unknown;
+  expectedRevision?: number | null;
+  commandId?: string;
+  idempotencyKey?: string;
+}) {
+  const parsed = beatDesignCommandSchema.parse(command);
+  return persistBeatDesignCommand({
+    projectId,
+    origin: 'mcp',
+    commandId,
+    idempotencyKey,
+    expectedRevision,
+    command: parsed,
+  });
+}
+
+function semanticTimelineSnapshot(
+  timeline: Awaited<ReturnType<typeof loadProjectTimeline>>,
+  time: number
+) {
+  if (!timeline) return null;
+  const clampedTime = Math.max(0, Math.min(timeline.document.duration, time));
+  const activeClips = timeline.document.tracks.flatMap((track) =>
+    track.clips.flatMap((clip) => {
+      if (
+        clampedTime < clip.startTime ||
+        clampedTime >= clip.startTime + clip.duration
+      ) {
+        return [];
+      }
+      const take = clip.activeTakeId
+        ? clip.takes.find((candidate) => candidate.id === clip.activeTakeId)
+        : null;
+      return [
+        {
+          trackId: track.id,
+          trackKind: track.kind,
+          clipId: clip.id,
+          assetId: take?.assetId ?? clip.assetId,
+          sourceUrl: take?.sourceUrl ?? clip.sourceUrl,
+          sourceTime: clip.inPoint + (clampedTime - clip.startTime),
+          muted: track.muted || clip.muted,
+          volume: clip.volume,
+        },
+      ];
+    })
+  );
+  return {
+    projectId: timeline.document.projectId,
+    timelineId: timeline.document.id,
+    revision: timeline.version,
+    time: clampedTime,
+    activeClips,
+    note: 'Semantic snapshot only; pixel rendering is not available in the local MCP server yet.',
+  };
+}
+
+export function createBeatDesignMcpServer() {
+  const server = new McpServer({ name: 'beatdesign', version: VERSION });
+
+  server.registerTool(
+    'bdesign_project_list',
+    {
+      description: 'List local BeatDesign projects.',
+      inputSchema: z.object({ limit: z.number().int().min(1).max(100).default(24) }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(async ({ limit }) => loadProjects({ limit }))
+  );
+
+  server.registerTool(
+    'bdesign_project_get',
+    {
+      description: 'Read one project with its Canvas and Editor documents.',
+      inputSchema: z.object({ projectId: idSchema, includeAssets: z.boolean().default(false) }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(async ({ projectId, includeAssets }) => {
+      const [canvas, timeline, assets] = await Promise.all([
+        loadProjectWithLatestSnapshot({ projectId }),
+        loadProjectTimeline(projectId),
+        includeAssets ? listProjectAssets({ projectId }) : Promise.resolve(undefined),
+      ]);
+      if (!canvas) throw new Error('Project not found.');
+      return {
+        project: canvas.project,
+        canvas: {
+          ...canvas,
+          snapshot: {
+            ...canvas.snapshot,
+            cards: toCommandCanvasCards(canvas.snapshot.cards),
+          },
+        },
+        timeline,
+        assets,
+      };
+    })
+  );
+
+  server.registerTool(
+    'bdesign_project_create',
+    {
+      description: 'Create a new local BeatDesign project.',
+      inputSchema: z.object({ name: z.string().trim().min(1).max(240) }),
+      annotations: { destructiveHint: false, idempotentHint: false },
+    },
+    withToolErrors(async ({ name }) => createProject({ name }))
+  );
+
+  server.registerTool(
+    'bdesign_asset_list',
+    {
+      description: 'List Assets that belong to a project.',
+      inputSchema: z.object({ projectId: idSchema, limit: z.number().int().min(1).max(500).default(100) }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(async ({ projectId, limit }) => listProjectAssets({ projectId, limit }))
+  );
+
+  server.registerTool(
+    'bdesign_asset_get',
+    {
+      description: 'Read one project Asset by stable assetId.',
+      inputSchema: z.object({ projectId: idSchema, assetId: idSchema }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(async ({ projectId, assetId }) => {
+      const asset = await getProjectAssetById({ projectId, assetId });
+      if (!asset) throw new Error('Asset not found in this project.');
+      return asset;
+    })
+  );
+
+  server.registerTool(
+    'bdesign_asset_import',
+    {
+      description:
+        'Import a local image, video, or audio file into the project Asset library from an absolute path.',
+      inputSchema: z.object({
+        projectId: idSchema,
+        filePath: z.string().trim().min(1).max(4096),
+      }),
+      annotations: { destructiveHint: false, idempotentHint: false },
+    },
+    withToolErrors(async ({ projectId, filePath }) =>
+      importLocalProjectAsset({ projectId, filePath })
+    )
+  );
+
+  server.registerTool(
+    'bdesign_canvas_get',
+    {
+      description: 'Read the Canvas document and revision for a project.',
+      inputSchema: z.object({ projectId: idSchema }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(async ({ projectId }) => {
+      const state = await loadProjectWithLatestSnapshot({ projectId });
+      if (!state) throw new Error('Project not found.');
+      return {
+        revision: state.snapshotVersion,
+        document: {
+          ...state.snapshot,
+          cards: toCommandCanvasCards(state.snapshot.cards),
+        },
+      };
+    })
+  );
+
+  server.registerTool(
+    'bdesign_canvas_search',
+    {
+      description: 'Search Canvas nodes by name, prompt, result text, model, kind, or media type.',
+      inputSchema: z.object({
+        projectId: idSchema,
+        query: z.string().trim().max(500).default(''),
+        kind: z.enum(['asset', 'generation', 'output']).optional(),
+        type: z.enum(['image', 'video', 'audio', 'timeline']).optional(),
+      }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(async ({ projectId, query, kind, type }) => {
+      const state = await loadProjectWithLatestSnapshot({ projectId });
+      if (!state) throw new Error('Project not found.');
+      const needle = query.toLocaleLowerCase();
+      return toCommandCanvasCards(state.snapshot.cards).filter((card) => {
+        if (kind && card.kind !== kind) return false;
+        if (type && card.type !== type) return false;
+        if (!needle) return true;
+        return [card.id, card.name, card.prompt, card.resultText, card.modelId]
+          .filter((value): value is string => typeof value === 'string')
+          .some((value) => value.toLocaleLowerCase().includes(needle));
+      });
+    })
+  );
+
+  server.registerTool(
+    'bdesign_canvas_apply',
+    {
+      description: 'Apply incremental Canvas operations. Raw document replacement is not exposed.',
+      inputSchema: commandMetadataSchema.extend({
+        projectId: idSchema,
+        operations: z.array(canvasOperationSchema).min(1).max(500),
+      }),
+      annotations: { destructiveHint: true, idempotentHint: true },
+    },
+    withToolErrors(async ({ projectId, operations, ...metadata }) =>
+      executeExternalCommand({
+        projectId,
+        ...metadata,
+        command: { type: 'canvas.apply', operations },
+      })
+    )
+  );
+
+  server.registerTool(
+    'bdesign_generation_models',
+    {
+      description: 'List logical generation models and their current parameter/reference capabilities.',
+      inputSchema: z.object({ kind: z.enum(['image', 'video', 'analysis']).optional() }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(({ kind }) =>
+      listGenerationModelDescriptors().filter((model) => !kind || model.kind === kind)
+    )
+  );
+
+  server.registerTool(
+    'bdesign_generation_model_get',
+    {
+      description: 'Read one logical model, including defaults and accepted parameters.',
+      inputSchema: z.object({ modelId: idSchema }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(({ modelId }) => {
+      const model = getGenerationModelDescriptor(modelId);
+      if (!model) throw new Error('Generation model not found.');
+      return model;
+    })
+  );
+
+  server.registerTool(
+    'bdesign_generation_submit',
+    {
+      description: 'Submit an asset-first image, video, or analysis generation. Outputs are recorded as reusable Assets.',
+      inputSchema: z.object({
+        projectId: idSchema,
+        mode: z.enum(['image', 'video', 'analysis']),
+        modelId: idSchema,
+        prompt: z.string().max(20_000),
+        references: z.array(generationReferenceSchema).max(20).default([]),
+        parameters: z.record(z.string(), z.unknown()).default({}),
+      }),
+      annotations: { destructiveHint: false, idempotentHint: false },
+    },
+    withToolErrors(async (input) => {
+      const result = await submitAssetFirstGeneration({
+        origin: 'mcp',
+        generation: { version: 1, ...input },
+      });
+      if (result.status >= 400) {
+        throw new BeatDesignMcpToolError(result.status, result.body);
+      }
+      return result.body;
+    })
+  );
+
+  server.registerTool(
+    'bdesign_generation_status',
+    {
+      description: 'Read and, when possible, refresh one generation task.',
+      inputSchema: z.object({ generationId: idSchema, refresh: z.boolean().default(true) }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(async ({ generationId, refresh }) => {
+      const generation = await getGenerationById({ id: generationId });
+      if (!generation) throw new Error('Generation not found.');
+      if (
+        refresh &&
+        (generation.status === 'pending' || generation.status === 'processing')
+      ) {
+        return syncGeneration({ wmTaskId: generationId, effectId: generation.effectId });
+      }
+      return generation;
+    })
+  );
+
+  server.registerTool(
+    'bdesign_generation_history',
+    {
+      description: 'List generation history for a project.',
+      inputSchema: z.object({ projectId: idSchema, limit: z.number().int().min(1).max(200).default(80) }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(async ({ projectId, limit }) => listProjectGenerations(projectId, limit))
+  );
+
+  server.registerTool(
+    'bdesign_editor_get',
+    {
+      description: 'Read the current Editor timeline and revision.',
+      inputSchema: z.object({ projectId: idSchema }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(async ({ projectId }) => {
+      const project = await getProject({ projectId });
+      if (!project) throw new Error('Project not found.');
+      return loadProjectTimeline(projectId);
+    })
+  );
+
+  server.registerTool(
+    'bdesign_editor_edit',
+    {
+      description: 'Apply incremental timeline operations such as add, trim, split, move, remove, audio updates, and Takes.',
+      inputSchema: commandMetadataSchema.extend({
+        projectId: idSchema,
+        operations: z.array(editorOperationSchema).min(1).max(500),
+      }),
+      annotations: { destructiveHint: true, idempotentHint: true },
+    },
+    withToolErrors(async ({ projectId, operations, ...metadata }) =>
+      executeExternalCommand({
+        projectId,
+        ...metadata,
+        command: { type: 'editor.apply', operations },
+      })
+    )
+  );
+
+  server.registerTool(
+    'bdesign_editor_snapshot',
+    {
+      description: 'Resolve the active timeline clips at a time. This is semantic inspection, not a pixel screenshot.',
+      inputSchema: z.object({ projectId: idSchema, time: z.number().finite().min(0) }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(async ({ projectId, time }) =>
+      semanticTimelineSnapshot(await loadProjectTimeline(projectId), time)
+    )
+  );
+
+  server.registerTool(
+    'bdesign_editor_diagnostics',
+    {
+      description: 'Diagnose gaps, overlaps, missing media, duration mismatches, and tiny clips.',
+      inputSchema: z.object({ projectId: idSchema }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(async ({ projectId }) => {
+      const timeline = await loadProjectTimeline(projectId);
+      if (!timeline) return { diagnostics: [], revision: null };
+      return {
+        diagnostics: diagnoseTimeline(timeline.document),
+        revision: timeline.version,
+      };
+    })
+  );
+
+  server.registerTool(
+    'bdesign_editor_view',
+    {
+      description: 'Build an Editor deep link for a time and return its semantic snapshot.',
+      inputSchema: z.object({ projectId: idSchema, time: z.number().finite().min(0).default(0) }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(async ({ projectId, time }) => ({
+      editorUrl: `${envConfigs.app_url.replace(/\/$/, '')}/editor/${encodeURIComponent(projectId)}?t=${time}`,
+      snapshot: semanticTimelineSnapshot(await loadProjectTimeline(projectId), time),
+    }))
+  );
+
+  server.registerTool(
+    'bdesign_editor_history',
+    {
+      description: 'Read persisted command receipts for timeline and Canvas changes.',
+      inputSchema: z.object({ projectId: idSchema, limit: z.number().int().min(1).max(200).default(50) }),
+      annotations: { readOnlyHint: true },
+    },
+    withToolErrors(async ({ projectId, limit }) => listCommandReceipts({ projectId, limit }))
+  );
+
+  return server;
+}
+
+export function startBeatDesignMcpServer() {
+  return serveStdio(createBeatDesignMcpServer, {
+    onerror: (error) => console.error('[BeatDesign MCP]', error),
+  });
+}
diff --git a/src/mcp/stdio-probe.test.ts b/src/mcp/stdio-probe.test.ts
new file mode 100644
index 0000000..b70e924
--- /dev/null
+++ b/src/mcp/stdio-probe.test.ts
@@ -0,0 +1,101 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import test from 'node:test';
+
+import { BEATDESIGN_MCP_TOOL_NAMES } from './tools';
+
+const send = (
+  child: ReturnType<typeof spawn>,
+  message: Record<string, unknown>
+) => {
+  child.stdin?.write(`${JSON.stringify(message)}\n`);
+};
+
+const readJsonLine = async (
+  child: ReturnType<typeof spawn>,
+  timeoutMs = 12_000
+) =>
+  new Promise<Record<string, unknown>>((resolveLine, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error('Timed out waiting for MCP stdio response'));
+    }, timeoutMs);
+    let buffer = '';
+    const onData = (chunk: Buffer) => {
+      buffer += chunk.toString('utf8');
+      const newline = buffer.indexOf('\n');
+      if (newline < 0) return;
+      child.stdout?.off('data', onData);
+      clearTimeout(timer);
+      resolveLine(JSON.parse(buffer.slice(0, newline)) as Record<string, unknown>);
+    };
+    child.stdout?.on('data', onData);
+  });
+
+test('MCP stdio handshake lists the catalogued tools and can list projects', async () => {
+  const child = spawn(
+    resolve('node_modules/.bin/tsx'),
+    ['scripts/mcp-server.ts'],
+    {
+      cwd: resolve('.'),
+      env: { ...process.env, NODE_ENV: 'development' },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }
+  );
+
+  try {
+    send(child, {
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'beatdesign-stdio-probe', version: '0.0.1' },
+      },
+    });
+    const initialized = await readJsonLine(child);
+    const initResult = initialized.result as {
+      serverInfo?: { name?: string; version?: string };
+    };
+    const packageVersion = (
+      JSON.parse(readFileSync(resolve('package.json'), 'utf8')) as {
+        version: string;
+      }
+    ).version;
+    const pluginVersion = (
+      JSON.parse(
+        readFileSync(
+          resolve('integrations/codex/beatdesign/.codex-plugin/plugin.json'),
+          'utf8'
+        )
+      ) as { version: string }
+    ).version;
+    assert.equal(initResult.serverInfo?.name, 'beatdesign');
+    assert.equal(initResult.serverInfo?.version, packageVersion);
+    assert.equal(pluginVersion, packageVersion);
+
+    send(child, { jsonrpc: '2.0', method: 'notifications/initialized' });
+    send(child, { jsonrpc: '2.0', id: 2, method: 'tools/list' });
+    const listed = await readJsonLine(child);
+    const tools = (
+      listed.result as { tools?: Array<{ name: string }> }
+    ).tools?.map((tool) => tool.name);
+    assert.deepEqual(tools, [...BEATDESIGN_MCP_TOOL_NAMES]);
+
+    send(child, {
+      jsonrpc: '2.0',
+      id: 3,
+      method: 'tools/call',
+      params: { name: 'bdesign_project_list', arguments: { limit: 5 } },
+    });
+    const listedProjects = await readJsonLine(child, 15_000);
+    const payload = listedProjects.result as {
+      structuredContent?: { result?: unknown };
+    };
+    assert.ok(Array.isArray(payload.structuredContent?.result));
+  } finally {
+    child.kill();
+  }
+});
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
new file mode 100644
index 0000000..4f1449a
--- /dev/null
+++ b/src/mcp/tools.ts
@@ -0,0 +1,24 @@
+export const BEATDESIGN_MCP_TOOL_NAMES = [
+  'bdesign_project_list',
+  'bdesign_project_get',
+  'bdesign_project_create',
+  'bdesign_asset_list',
+  'bdesign_asset_get',
+  'bdesign_asset_import',
+  'bdesign_canvas_get',
+  'bdesign_canvas_search',
+  'bdesign_canvas_apply',
+  'bdesign_generation_models',
+  'bdesign_generation_model_get',
+  'bdesign_generation_submit',
+  'bdesign_generation_status',
+  'bdesign_generation_history',
+  'bdesign_editor_get',
+  'bdesign_editor_edit',
+  'bdesign_editor_snapshot',
+  'bdesign_editor_diagnostics',
+  'bdesign_editor_view',
+  'bdesign_editor_history',
+] as const;
+
+export type BeatDesignMcpToolName = (typeof BEATDESIGN_MCP_TOOL_NAMES)[number];
diff --git a/src/routes/-workspace-project-route.client-boundary.test.ts b/src/routes/-workspace-project-route.client-boundary.test.ts
index 19d0731..bb36a85 100644
--- a/src/routes/-workspace-project-route.client-boundary.test.ts
+++ b/src/routes/-workspace-project-route.client-boundary.test.ts
@@ -5,6 +5,7 @@ import test from 'node:test';
 for (const routeFile of [
   './studio/$projectId.tsx',
   './canvas/$projectId.tsx',
+  './editor/$projectId.tsx',
   './assets/$projectId.tsx',
 ]) {
   test(`keeps ${routeFile} data-loaded but client rendered`, () => {
diff --git a/src/routes/api/-trusted-mutations.contract.test.ts b/src/routes/api/-trusted-mutations.contract.test.ts
index adbabcc..4642f34 100644
--- a/src/routes/api/-trusted-mutations.contract.test.ts
+++ b/src/routes/api/-trusted-mutations.contract.test.ts
@@ -6,6 +6,8 @@ const mutationRoutes = [
   './app/projects/index.ts',
   './app/projects/$projectId.ts',
   './app/projects/$projectId/snapshot.ts',
+  './app/projects/$projectId/commands.ts',
+  './app/projects/$projectId/timeline.ts',
   './effects/precheck.ts',
   './effects/generate.ts',
 ];
@@ -33,6 +35,26 @@ test('workspace JSON mutation routes enforce the same-origin request contract',
   }
 });
 
+test('the UI command route assigns origin server-side', () => {
+  const route = readFileSync(
+    new URL('./app/projects/$projectId/commands.ts', import.meta.url),
+    'utf8'
+  );
+  const schema = readFileSync(
+    new URL('../../core/commands/schema.ts', import.meta.url),
+    'utf8'
+  );
+  const client = readFileSync(
+    new URL('../../core/commands/client.ts', import.meta.url),
+    'utf8'
+  );
+
+  assert.match(route, /origin: 'ui'/);
+  assert.doesNotMatch(route, /payload\.origin/);
+  assert.doesNotMatch(schema, /origin: z\.enum/);
+  assert.doesNotMatch(client, /origin,/);
+});
+
 test('workspace multipart mutation routes enforce the same-origin request contract', () => {
   for (const route of multipartMutationRoutes) {
     const source = readFileSync(new URL(route, import.meta.url), 'utf8');
diff --git a/src/routes/api/app/projects/$projectId/assets/$assetId.ts b/src/routes/api/app/projects/$projectId/assets/$assetId.ts
index af8c9d2..901c785 100644
--- a/src/routes/api/app/projects/$projectId/assets/$assetId.ts
+++ b/src/routes/api/app/projects/$projectId/assets/$assetId.ts
@@ -1,5 +1,7 @@
 import { createFileRoute } from '@tanstack/react-router';
-import { readFile } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { Readable } from 'node:stream';
 
 import {
   LOCAL_PROJECT_ASSET_BUCKET,
@@ -57,11 +59,10 @@ async function GET({
     return Response.json({ error: 'Project asset not found' }, { status: 404 });
   }
 
-  let bytes: Uint8Array;
+  const filePath = resolveLocalProjectAssetPath({ objectKey: asset.objectKey });
+  let fileStat: Awaited<ReturnType<typeof stat>>;
   try {
-    bytes = await readFile(
-      resolveLocalProjectAssetPath({ objectKey: asset.objectKey })
-    );
+    fileStat = await stat(filePath);
   } catch {
     return Response.json({ error: 'Project asset file is missing' }, { status: 404 });
   }
@@ -79,23 +80,24 @@ async function GET({
     headers.set('content-disposition', 'attachment');
   }
   const rangeHeader = request.headers.get('range');
-  const range = parseByteRange(rangeHeader, bytes.byteLength);
+  const range = parseByteRange(rangeHeader, fileStat.size);
   if (rangeHeader && !range) {
-    headers.set('content-range', `bytes */${bytes.byteLength}`);
+    headers.set('content-range', `bytes */${fileStat.size}`);
     return new Response(null, { status: 416, headers });
   }
+  const start = range?.start ?? 0;
+  const end = range?.end ?? fileStat.size - 1;
+  headers.set('content-length', String(end - start + 1));
   if (range) {
-    const body = Uint8Array.from(bytes.subarray(range.start, range.end + 1));
-    headers.set('content-length', String(body.byteLength));
-    headers.set(
-      'content-range',
-      `bytes ${range.start}-${range.end}/${bytes.byteLength}`
-    );
-    return new Response(body.buffer, { status: 206, headers });
+    headers.set('content-range', `bytes ${start}-${end}/${fileStat.size}`);
   }
-
-  headers.set('content-length', String(bytes.byteLength));
-  return new Response(Uint8Array.from(bytes).buffer, { status: 200, headers });
+  const stream = Readable.toWeb(
+    createReadStream(filePath, { start, end })
+  ) as ReadableStream<Uint8Array>;
+  return new Response(stream, {
+    status: range ? 206 : 200,
+    headers,
+  });
 }
 
 export const Route = createFileRoute(
diff --git a/src/routes/api/app/projects/$projectId/assets/index.ts b/src/routes/api/app/projects/$projectId/assets/index.ts
index d26bd38..da4ff0c 100644
--- a/src/routes/api/app/projects/$projectId/assets/index.ts
+++ b/src/routes/api/app/projects/$projectId/assets/index.ts
@@ -5,7 +5,9 @@ import {
   detectUploadedMediaType,
   getCanonicalUploadedMediaMimeType,
   validateUploadedImageFile,
+  validateUploadedAudioFile,
   validateUploadedVideoFile,
+  REFERENCE_AUDIO_MAX_FILE_SIZE,
   REFERENCE_VIDEO_MAX_FILE_SIZE,
 } from '@/core/effects/validation';
 import {
@@ -66,9 +68,37 @@ async function POST({
   try {
     const formData = await readRequestFormDataWithLimit(
       request,
-      REFERENCE_VIDEO_MAX_FILE_SIZE + MAX_MULTIPART_OVERHEAD_BYTES
+      Math.max(REFERENCE_VIDEO_MAX_FILE_SIZE, REFERENCE_AUDIO_MAX_FILE_SIZE) +
+        MAX_MULTIPART_OVERHEAD_BYTES
     );
     const file = formData.get('file');
+    const requestedAssetClass = formData.get('assetClass');
+    const assetClass = requestedAssetClass === 'derived' ? 'derived' : 'original';
+    const parseDimension = (value: FormDataEntryValue | null) => {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) && parsed > 0
+        ? Math.min(Math.round(parsed), 32_768)
+        : undefined;
+    };
+    const width = parseDimension(formData.get('width'));
+    const height = parseDimension(formData.get('height'));
+    const rawDurationMs = Number(formData.get('durationMs'));
+    const durationMs =
+      Number.isFinite(rawDurationMs) && rawDurationMs > 0
+        ? Math.min(Math.round(rawDurationMs), 86_400_000)
+        : undefined;
+    let assetMetadata: Record<string, unknown> | undefined;
+    const rawMetadata = formData.get('metadata');
+    if (typeof rawMetadata === 'string' && rawMetadata.length <= 16_384) {
+      try {
+        const parsed = JSON.parse(rawMetadata) as unknown;
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+          assetMetadata = parsed as Record<string, unknown>;
+        }
+      } catch {
+        return Response.json({ error: 'Invalid project asset metadata' }, { status: 400 });
+      }
+    }
     if (!(file instanceof File) || file.size <= 0) {
       return Response.json({ error: 'A non-empty file is required' }, { status: 400 });
     }
@@ -80,7 +110,9 @@ async function POST({
     const validation =
       mediaType === 'image'
         ? validateUploadedImageFile(file)
-        : validateUploadedVideoFile(file);
+        : mediaType === 'video'
+          ? validateUploadedVideoFile(file)
+          : validateUploadedAudioFile(file);
     if (!validation.ok) {
       return Response.json(
         { error: 'Project asset type or size is not supported' },
@@ -114,7 +146,7 @@ async function POST({
       const assetId = await recordUserAsset({
         id: persisted.assetId,
         type: mediaType,
-        source: 'upload',
+        source: assetClass === 'derived' ? 'derived' : 'upload',
         bucket: LOCAL_PROJECT_ASSET_BUCKET,
         objectKey: persisted.objectKey,
         publicUrl: persisted.publicUrl,
@@ -123,13 +155,27 @@ async function POST({
         sha256: persisted.sha256,
         filename: persisted.filename,
         storageProvider: LOCAL_PROJECT_ASSET_PROVIDER,
-        assetClass: 'original',
+        assetClass,
         originProjectId: projectId,
+        width,
+        height,
+        durationMs,
+        metadata: assetMetadata,
       });
       await linkProjectAsset({
         projectId,
         assetId,
-        role: 'upload',
+        role: assetClass === 'derived' ? 'generated' : 'upload',
+        assetRole:
+          assetMetadata &&
+          typeof assetMetadata === 'object' &&
+          typeof (assetMetadata as { operation?: unknown }).operation ===
+            'string'
+            ? (assetMetadata as { operation: string }).operation
+            : assetClass === 'derived'
+              ? 'derived'
+              : null,
+        metadata: assetMetadata,
       });
 
       return Response.json({
@@ -140,6 +186,9 @@ async function POST({
           filename: persisted.filename,
           mimeType: persistedMimeType,
           sizeBytes: persisted.sizeBytes,
+          ...(width ? { width } : {}),
+          ...(height ? { height } : {}),
+          ...(durationMs ? { durationMs } : {}),
         },
       });
     } catch (error) {
diff --git a/src/routes/api/app/projects/$projectId/commands.ts b/src/routes/api/app/projects/$projectId/commands.ts
new file mode 100644
index 0000000..619f5b8
--- /dev/null
+++ b/src/routes/api/app/projects/$projectId/commands.ts
@@ -0,0 +1,89 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+import { persistBeatDesignCommand } from '@/core/commands/persist';
+import {
+  createCommandFailure,
+  createCommandId,
+} from '@/core/commands/contracts';
+import { uiCommandRequestSchema } from '@/core/commands/schema';
+import { MAX_PROJECT_SNAPSHOT_BYTES } from '@/core/projects/project-snapshot';
+import {
+  readRequestJsonWithLimit,
+  RequestBodyTooLargeError,
+} from '@/lib/request-body-limit';
+import { validateTrustedWorkspaceJsonMutation } from '@/lib/trusted-local-request';
+
+async function POST({
+  request,
+  params,
+}: {
+  request: Request;
+  params: { projectId: string };
+}) {
+  const trust = validateTrustedWorkspaceJsonMutation(request);
+  if (!trust.ok) {
+    return Response.json({ error: trust.message }, { status: trust.status });
+  }
+
+  let input: unknown;
+  try {
+    input = await readRequestJsonWithLimit<unknown>(
+      request,
+      MAX_PROJECT_SNAPSHOT_BYTES
+    );
+  } catch (error) {
+    if (error instanceof RequestBodyTooLargeError) {
+      return Response.json({ error: 'Request body is too large' }, { status: 413 });
+    }
+    return Response.json({ error: 'Invalid JSON' }, { status: 400 });
+  }
+
+  const parsed = uiCommandRequestSchema.safeParse(input);
+  if (!parsed.success) {
+    const source =
+      input && typeof input === 'object'
+        ? (input as { commandId?: unknown })
+        : null;
+    const commandId =
+      typeof source?.commandId === 'string' && source.commandId.trim()
+        ? source.commandId.trim()
+        : createCommandId();
+    return Response.json(
+      createCommandFailure({
+        commandId,
+        projectId: params.projectId,
+        origin: 'ui',
+        code: 'INVALID_COMMAND',
+        message: parsed.error.issues[0]?.message ?? 'Command is invalid.',
+      }),
+      { status: 400 }
+    );
+  }
+
+  const payload = parsed.data;
+  const commandId = payload.commandId ?? createCommandId();
+
+  const result = await persistBeatDesignCommand({
+    projectId: params.projectId,
+    origin: 'ui',
+    commandId,
+    expectedRevision: payload.expectedRevision,
+    idempotencyKey: payload.idempotencyKey ?? commandId,
+    command: payload.command,
+  });
+
+  const status = result.ok
+    ? 200
+    : result.code === 'NOT_FOUND'
+      ? 404
+      : result.code === 'REVISION_CONFLICT'
+        ? 409
+        : 400;
+  return Response.json(result, { status });
+}
+
+export const Route = createFileRoute(
+  '/api/app/projects/$projectId/commands'
+)({
+  server: { handlers: { POST } },
+});
diff --git a/src/routes/api/app/projects/$projectId/snapshot.ts b/src/routes/api/app/projects/$projectId/snapshot.ts
index 574b891..bafde96 100644
--- a/src/routes/api/app/projects/$projectId/snapshot.ts
+++ b/src/routes/api/app/projects/$projectId/snapshot.ts
@@ -7,6 +7,7 @@ import {
 } from '@/core/projects/project-snapshot';
 import {
   getProject,
+  loadProjectWithLatestSnapshot,
   saveProjectSnapshot,
 } from '@/core/projects/projects';
 import { validateTrustedWorkspaceJsonMutation } from '@/lib/trusted-local-request';
@@ -21,6 +22,18 @@ type SaveProjectSnapshotRequest = {
   allowEmpty?: boolean;
 };
 
+async function GET({ params }: { params: { projectId: string } }) {
+  const state = await loadProjectWithLatestSnapshot({ projectId: params.projectId });
+  if (!state) {
+    return Response.json({ error: 'Project not found' }, { status: 404 });
+  }
+  return Response.json({
+    projectId: params.projectId,
+    version: state.snapshotVersion,
+    document: state.snapshot,
+  });
+}
+
 async function PUT({
   request,
   params,
@@ -136,6 +149,6 @@ async function PUT({
 
 export const Route = createFileRoute('/api/app/projects/$projectId/snapshot')({
   server: {
-    handlers: { PUT },
+    handlers: { GET, PUT },
   },
 });
diff --git a/src/routes/api/app/projects/$projectId/timeline.ts b/src/routes/api/app/projects/$projectId/timeline.ts
new file mode 100644
index 0000000..31c8884
--- /dev/null
+++ b/src/routes/api/app/projects/$projectId/timeline.ts
@@ -0,0 +1,195 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+import {
+  MAX_TIMELINE_DOCUMENT_BYTES,
+  normalizeTimelineDocument,
+  TimelineDocumentValidationError,
+  type TimelineDocument,
+} from '@/core/editor/timeline-document';
+import {
+  loadProjectTimeline,
+  saveProjectTimeline,
+} from '@/core/editor/timeline-state';
+import { createCommandId } from '@/core/commands/contracts';
+import { persistBeatDesignCommand } from '@/core/commands/persist';
+import { getProject } from '@/core/projects/projects';
+import {
+  readRequestTextWithLimit,
+  RequestBodyTooLargeError,
+} from '@/lib/request-body-limit';
+import { validateTrustedWorkspaceJsonMutation } from '@/lib/trusted-local-request';
+
+async function GET({ params }: { params: { projectId: string } }) {
+  const currentProject = await getProject({ projectId: params.projectId });
+  if (!currentProject || currentProject.status !== 'active') {
+    return Response.json({ error: 'Project not found' }, { status: 404 });
+  }
+  const state = await loadProjectTimeline(params.projectId);
+  return Response.json({ timeline: state });
+}
+
+async function PUT({
+  request,
+  params,
+}: {
+  request: Request;
+  params: { projectId: string };
+}) {
+  const trust = validateTrustedWorkspaceJsonMutation(request);
+  if (!trust.ok) {
+    return Response.json({ error: trust.message }, { status: trust.status });
+  }
+
+  try {
+    const body = await readRequestTextWithLimit(
+      request,
+      MAX_TIMELINE_DOCUMENT_BYTES
+    );
+    const payload = JSON.parse(body) as {
+      document?: TimelineDocument;
+      baseVersion?: number | null;
+    };
+    if (!payload.document) {
+      return Response.json(
+        { error: 'Timeline document is required' },
+        { status: 400 }
+      );
+    }
+    const document = normalizeTimelineDocument(
+      payload.document,
+      params.projectId
+    );
+    const saved = await saveProjectTimeline({
+      projectId: params.projectId,
+      document,
+      baseVersion:
+        typeof payload.baseVersion === 'number' ? payload.baseVersion : null,
+    });
+    return Response.json({ timeline: saved });
+  } catch (error) {
+    if (error instanceof RequestBodyTooLargeError) {
+      return Response.json({ error: 'Timeline is too large' }, { status: 413 });
+    }
+    if (
+      error instanceof SyntaxError ||
+      error instanceof TimelineDocumentValidationError
+    ) {
+      return Response.json({ error: 'Invalid timeline document' }, { status: 400 });
+    }
+    if (error instanceof Error && error.message === 'Project not found') {
+      return Response.json({ error: 'Project not found' }, { status: 404 });
+    }
+    if (error instanceof Error && error.name === 'TimelineVersionConflict') {
+      return Response.json({ error: 'Timeline version conflict' }, { status: 409 });
+    }
+    console.error('save project timeline failed:', error);
+    return Response.json({ error: 'Failed to save timeline' }, { status: 500 });
+  }
+}
+
+async function POST({
+  request,
+  params,
+}: {
+  request: Request;
+  params: { projectId: string };
+}) {
+  const trust = validateTrustedWorkspaceJsonMutation(request);
+  if (!trust.ok) {
+    return Response.json({ error: trust.message }, { status: trust.status });
+  }
+  try {
+    let referenceCardIds: string[] | undefined;
+    try {
+      const body = await readRequestTextWithLimit(
+        request,
+        MAX_TIMELINE_DOCUMENT_BYTES
+      );
+      if (body.trim()) {
+        const payload = JSON.parse(body) as { referenceCardIds?: string[] };
+        if (Array.isArray(payload.referenceCardIds)) {
+          referenceCardIds = payload.referenceCardIds.filter(
+            (value): value is string =>
+              typeof value === 'string' && value.trim().length > 0
+          );
+        }
+      }
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        return Response.json({ error: 'Invalid JSON' }, { status: 400 });
+      }
+      throw error;
+    }
+    const timeline = await loadProjectTimeline(params.projectId);
+    if (!timeline) {
+      return Response.json({ error: 'Timeline not found' }, { status: 404 });
+    }
+    const clipCount = timeline.document.tracks.reduce(
+      (count, track) => count + track.clips.length,
+      0
+    );
+    const commandId = createCommandId();
+    const command = {
+      type: 'canvas.apply' as const,
+      operations: [
+        {
+          type: 'upsert_timeline_node' as const,
+          timelineId: timeline.document.id,
+          name: timeline.document.name,
+          durationSec: timeline.document.duration,
+          clipCount,
+          lastRenderAssetId: timeline.document.lastRenderAssetId,
+          lastRenderUrl: timeline.document.lastRenderUrl,
+          referenceCardIds,
+        },
+      ],
+    };
+    let result = await persistBeatDesignCommand({
+      projectId: params.projectId,
+      origin: 'ui',
+      commandId,
+      idempotencyKey: commandId,
+      command,
+    });
+    if (!result.ok && result.code === 'REVISION_CONFLICT') {
+      result = await persistBeatDesignCommand({
+        projectId: params.projectId,
+        origin: 'ui',
+        commandId,
+        idempotencyKey: commandId,
+        command,
+      });
+    }
+    if (!result.ok) {
+      return Response.json(
+        { error: result.message },
+        {
+          status:
+            result.code === 'NOT_FOUND'
+              ? 404
+              : result.code === 'REVISION_CONFLICT'
+                ? 409
+                : 400,
+        }
+      );
+    }
+    return Response.json({
+      timelineNode: {
+        cardId: result.changedIds[0],
+        version: result.revision,
+      },
+    });
+  } catch (error) {
+    if (error instanceof Error && error.message === 'Timeline not found') {
+      return Response.json({ error: 'Timeline not found' }, { status: 404 });
+    }
+    console.error('add timeline canvas node failed:', error);
+    return Response.json({ error: 'Failed to add timeline to Canvas' }, { status: 500 });
+  }
+}
+
+export const Route = createFileRoute(
+  '/api/app/projects/$projectId/timeline'
+)({
+  server: { handlers: { GET, PUT, POST } },
+});
diff --git a/src/routes/api/app/recent-assets.ts b/src/routes/api/app/recent-assets.ts
index 4fcca1f..1296dca 100644
--- a/src/routes/api/app/recent-assets.ts
+++ b/src/routes/api/app/recent-assets.ts
@@ -23,6 +23,9 @@ async function GET({ request }: { request: Request }) {
       width: userAsset.width,
       height: userAsset.height,
       createdAt: userAsset.createdAt,
+      mimeType: userAsset.mimeType,
+      assetClass: userAsset.assetClass,
+      metadata: userAsset.metadata,
     };
     const videoFields = {
       ...imageFields,
@@ -87,9 +90,42 @@ async function GET({ request }: { request: Request }) {
           .orderBy(desc(userAsset.createdAt))
           .limit(30);
 
-    const [images, videos] = await Promise.all([imageQuery, videoQuery]);
+    const audioQuery = projectId
+      ? db
+          .selectDistinct(videoFields)
+          .from(userAsset)
+          .innerJoin(
+            projectAssetMembership,
+            eq(projectAssetMembership.assetId, userAsset.id)
+          )
+          .where(
+            and(
+              eq(projectAssetMembership.projectId, projectId),
+              eq(userAsset.type, 'audio'),
+              isNotNull(userAsset.publicUrl)
+            )
+          )
+          .orderBy(desc(userAsset.createdAt))
+          .limit(30)
+      : db
+          .select(videoFields)
+          .from(userAsset)
+          .where(
+            and(
+              eq(userAsset.type, 'audio'),
+              isNotNull(userAsset.publicUrl)
+            )
+          )
+          .orderBy(desc(userAsset.createdAt))
+          .limit(30);
+
+    const [images, videos, audios] = await Promise.all([
+      imageQuery,
+      videoQuery,
+      audioQuery,
+    ]);
 
-    return Response.json({ images, videos });
+    return Response.json({ images, videos, audios });
 }
 
 export const Route = createFileRoute('/api/app/recent-assets')({
diff --git a/src/routes/api/effects/generate.ts b/src/routes/api/effects/generate.ts
index b0c8956..ac37f27 100644
--- a/src/routes/api/effects/generate.ts
+++ b/src/routes/api/effects/generate.ts
@@ -1,4 +1,9 @@
 import { createFileRoute } from '@tanstack/react-router';
+import { normalizeAssetFirstGenerationRequest } from '@/core/commands/generation-contract';
+import {
+  compileAssetFirstGenerationInput,
+  GenerationReferenceError,
+} from '@/core/commands/generation-compiler';
 import { submitEffectGeneration } from '@/core/effects/submit-generation';
 import { validateTrustedWorkspaceJsonMutation } from '@/lib/trusted-local-request';
 import {
@@ -12,6 +17,7 @@ type GenerateRequest = {
   input?: unknown;
   projectId?: string;
   generationIntentToken?: string;
+  generation?: unknown;
 };
 
 async function POST({ request }: { request: Request }) {
@@ -32,9 +38,44 @@ async function POST({ request }: { request: Request }) {
     }
     return Response.json({ error: 'Invalid JSON' }, { status: 400 });
   }
+  let authoritativeInput = payload.input;
+  if (payload.projectId) {
+    if (!payload.generation || !payload.generationIntentToken) {
+      return Response.json(
+        { error: 'Project generations require an asset-first request.' },
+        { status: 400 }
+      );
+    }
+    try {
+      const generation = normalizeAssetFirstGenerationRequest(payload.generation);
+      if (
+        generation.projectId &&
+        generation.projectId !== payload.projectId
+      ) {
+        return Response.json(
+          { error: 'Generation project does not match the request.' },
+          { status: 400 }
+        );
+      }
+      authoritativeInput = await compileAssetFirstGenerationInput({
+        generation,
+        generationIntentId: payload.generationIntentToken,
+      });
+    } catch (error) {
+      return Response.json(
+        {
+          error:
+            error instanceof GenerationReferenceError
+              ? error.message
+              : 'Generation request must be asset-first.',
+        },
+        { status: 400 }
+      );
+    }
+  }
   const result = await submitEffectGeneration({
     effectId: payload.effectId ?? Number.NaN,
-    input: payload.input,
+    input: authoritativeInput,
     projectId: payload.projectId,
     generationIntentId: payload.generationIntentToken,
   });
diff --git a/src/routes/api/effects/precheck.ts b/src/routes/api/effects/precheck.ts
index 49eeb88..cf1b3fc 100644
--- a/src/routes/api/effects/precheck.ts
+++ b/src/routes/api/effects/precheck.ts
@@ -1,5 +1,4 @@
 import { createFileRoute } from '@tanstack/react-router';
-import { buildBeatApiTaskRequest } from '@/core/adapters/beatapi-adapter';
 import { getEffectById } from '@/core/effects/effects';
 import { getWorkspaceEffectRegistryEntryByEffectId } from '@/core/effects/effect-registry';
 import { isVideoAnalysisEffectId } from '@/core/effects/video-analysis';
@@ -13,13 +12,13 @@ import {
 } from '@/core/effects/record-generation';
 import { getGenerationPromptConstraints, validateGenerationPrompt } from '@/core/effects/validation';
 import { getProject } from '@/core/projects/projects';
+import { getGenerationProvider } from '@/core/generation-providers';
 import {
   expireGenerationUploadIntents,
   GenerationIntentQuotaError,
   issueGenerationUploadIntent,
   normalizeExpectedUploadCount,
 } from '@/core/effects/generation-upload-intent';
-import { getConfig } from '@/modules/config/service';
 import { enforceMinIntervalRateLimit } from '@/lib/rate-limit';
 import { validateTrustedWorkspaceJsonMutation } from '@/lib/trusted-local-request';
 import {
@@ -105,10 +104,18 @@ async function POST({ request }: { request: Request }) {
       ? `Prompt must be ${prompt.maxChars} characters or fewer.`
       : 'Prompt is required.' }, { status: 400 });
   }
-  const apiKey = await getConfig('BEATAPI_API_KEY');
-  if (!apiKey) {
+  const provider = getGenerationProvider(effect.provider);
+  if (!provider) {
     return Response.json(
-      { error: 'Connect a BeatAPI API key before generating.' },
+      { error: `Generation provider ${effect.provider} is not registered.` },
+      { status: 400 }
+    );
+  }
+  try {
+    await provider.assertConfigured?.();
+  } catch (error) {
+    return Response.json(
+      { error: error instanceof Error ? error.message : 'Generation provider is not configured.' },
       { status: 400 }
     );
   }
@@ -121,15 +128,11 @@ async function POST({ request }: { request: Request }) {
       { status: 400 }
     );
   }
-  if (expectedUploadCount === 0 && effect.provider === 'beatapi') {
+  if (expectedUploadCount === 0) {
     try {
-      buildBeatApiTaskRequest({
-        effectType: effect.type,
-        model: effect.model,
-        input: {
-          ...input,
-          prompt: prompt.trimmedPrompt,
-        } as Parameters<typeof buildBeatApiTaskRequest>[0]['input'],
+      provider.validateInput?.(effect, {
+        ...input,
+        prompt: prompt.trimmedPrompt,
       });
     } catch (error) {
       return Response.json(
@@ -137,7 +140,7 @@ async function POST({ request }: { request: Request }) {
           error:
             error instanceof Error
               ? error.message
-              : 'Invalid BeatAPI model parameters.',
+              : 'Invalid generation model parameters.',
         },
         { status: 400 }
       );
diff --git a/src/routes/editor/$projectId.tsx b/src/routes/editor/$projectId.tsx
new file mode 100644
index 0000000..529abad
--- /dev/null
+++ b/src/routes/editor/$projectId.tsx
@@ -0,0 +1,19 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+import { WorkspaceProjectRoutePage } from '@/components/app/workspace-project-route-page';
+import { loadWorkspaceProjectRoute } from '@/core/projects/workspace-project-route-loader';
+
+export const Route = createFileRoute('/editor/$projectId')({
+  ssr: 'data-only',
+  loader: ({ params }) =>
+    loadWorkspaceProjectRoute({
+      projectId: params.projectId,
+      search: {},
+      workspaceMode: 'editor',
+    }),
+  component: EditorProjectRouteComponent,
+});
+
+function EditorProjectRouteComponent() {
+  return <WorkspaceProjectRoutePage data={Route.useLoaderData()} />;
+}
diff --git a/src/server.ts b/src/server.ts
index 75eb062..da36125 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -3,6 +3,7 @@ import handler from '@tanstack/react-start/server-entry';
 import { runDueGenerationStatusPasses } from './core/effects/server-poller';
 import { cleanupStaleGenerations } from './core/effects/stale-generations';
 import { getWwwRedirectLocation } from './lib/canonical-url';
+import { normalizeProjectAssetMediaRequest } from './lib/project-asset-media-request';
 import { paraglideMiddleware } from './paraglide/server.js';
 
 // On Cloudflare Workers, stash the binding env (D1, ASSETS, …) on globalThis
@@ -41,7 +42,8 @@ export default {
     }
 
     await ensureCloudflareEnv();
-    return paraglideMiddleware(req, () => handler.fetch(req));
+    const routedRequest = normalizeProjectAssetMediaRequest(req);
+    return paraglideMiddleware(routedRequest, () => handler.fetch(routedRequest));
   },
   async scheduled(
     _controller: unknown,
diff --git a/third_party/README.md b/third_party/README.md
new file mode 100644
index 0000000..3855d9d
--- /dev/null
+++ b/third_party/README.md
@@ -0,0 +1,31 @@
+# Third-party notices
+
+BeatDesign remains Apache-2.0. The local Edit workspace intentionally reuses
+small, well-defined open-source layers instead of bundling another product's
+application shell.
+
+## OpenReel
+
+- Repository: <https://github.com/Augani/openreel-video>
+- Pinned commit: `5f3c85e5fc223c86060bf4b12e1b4dec58e9b8a9`
+- License: MIT
+- Use: timeline terminology, document shape, and non-destructive editing behavior
+- Not bundled: Agent/chat, cloud accounts, provider integrations, desktop shell,
+  project manager, image editor, or OpenReel UI/branding
+
+The preserved license is in [`openreel/LICENSE`](./openreel/LICENSE), and the
+machine-readable pin is in
+[`openreel/PINNED_VERSION.json`](./openreel/PINNED_VERSION.json).
+
+## Mediabunny
+
+- Repository: <https://github.com/Vanilagy/mediabunny>
+- Package version: `1.25.3` (exactly pinned in `package.json`)
+- License: Mozilla Public License 2.0
+- Use: browser-side media inspection, precise range conversion, WebCodecs
+  encoding, and MP4 muxing
+
+The preserved license is in [`mediabunny/LICENSE`](./mediabunny/LICENSE).
+Mediabunny is consumed as an unmodified npm dependency. BeatDesign does not
+bundle a native FFmpeg executable and does not require a system FFmpeg
+installation.
diff --git a/third_party/mediabunny/LICENSE b/third_party/mediabunny/LICENSE
new file mode 100644
index 0000000..d0a1fa1
--- /dev/null
+++ b/third_party/mediabunny/LICENSE
@@ -0,0 +1,373 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.
diff --git a/third_party/openreel/LICENSE b/third_party/openreel/LICENSE
new file mode 100644
index 0000000..1e114f1
--- /dev/null
+++ b/third_party/openreel/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Augustus Otu and Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/third_party/openreel/PINNED_VERSION.json b/third_party/openreel/PINNED_VERSION.json
new file mode 100644
index 0000000..db50218
--- /dev/null
+++ b/third_party/openreel/PINNED_VERSION.json
@@ -0,0 +1,7 @@
+{
+  "name": "OpenReel",
+  "repository": "https://github.com/Augani/openreel-video",
+  "commit": "5f3c85e5fc223c86060bf4b12e1b4dec58e9b8a9",
+  "license": "MIT",
+  "integration": "BeatDesign timeline contract and editing behavior derived from OpenReel core; OpenReel application shell and cloud features are not bundled."
+}
diff --git a/vite.config.ts b/vite.config.ts
index 9ee625e..0786d98 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -8,6 +8,7 @@ import { defineConfig } from 'vite';
 
 import { paraglideCompilerOptions } from './src/config/paraglide';
 import { loadEnvFiles } from './src/lib/env';
+import { shouldNormalizeProjectAssetMediaRequest } from './src/lib/project-asset-media-request';
 
 // Populate process.env from .env.local / .env.{NODE_ENV} / .env for the
 // dev server and build process (Vite only exposes VITE_* via import.meta.env;
@@ -24,6 +25,26 @@ export default defineConfig({
     tsconfigPaths: true,
   },
   plugins: [
+    {
+      name: 'beatdesign-project-asset-media-routes',
+      enforce: 'pre',
+      configureServer(server) {
+        server.middlewares.use((request, _response, next) => {
+          const destination = request.headers['sec-fetch-dest'];
+          if (
+            shouldNormalizeProjectAssetMediaRequest({
+              method: request.method,
+              url: request.url,
+              destination:
+                typeof destination === 'string' ? destination : undefined,
+            })
+          ) {
+            delete request.headers['sec-fetch-dest'];
+          }
+          next();
+        });
+      },
+    },
     // MDX must run before the react plugin so JSX in compiled MDX gets transformed.
     { enforce: 'pre', ...mdx({ providerImportSource: '@mdx-js/react' }) },
     tailwindcss(),