From 2af67ea155baafb6eeb212b84346d46c57e38779 Mon Sep 17 00:00:00 2001
From: KKKK <kh844257437@gmail.com>
Date: Fri, 21 Aug 2026 12:28:44 +0800
Subject: [PATCH 1/2] feat: improve canvas media workflow

---
 messages/en.json                              | 10 +-
 messages/zh.json                              | 10 +-
 src/components/app/product-page-shell.test.ts |  7 ++
 src/components/app/product-page-shell.tsx     | 11 +++
 ...tcanvas-composer-reference-picker.test.tsx | 41 +++++++++
 .../beatcanvas-composer-reference-picker.tsx  | 28 +++++-
 .../beatcanvas-media-preview-overlay.test.tsx | 19 ++++
 .../beatcanvas-media-preview-overlay.tsx      | 27 ++++--
 .../beatcanvas-media-preview.test.ts          |  4 +-
 .../beatcanvas/beatcanvas-media-preview.ts    |  5 +-
 .../beatcanvas/beatcanvas-shell.tsx           | 42 ++++++---
 .../beatcanvas/beatcanvas-sidebar-panels.tsx  | 73 ---------------
 .../beatcanvas-sidebar.lazy-panels.test.ts    |  8 +-
 .../beatcanvas/beatcanvas-sidebar.tsx         | 33 +++----
 .../nodes/asset-card-node-preview.test.ts     | 15 +++
 .../beatcanvas/nodes/asset-card-node.tsx      | 92 ++++++++++++++++---
 .../beatcanvas/nodes/beatcanvas-node-copy.ts  | 10 ++
 .../use-beatcanvas-upload-actions.test.ts     |  7 ++
 .../use-beatcanvas-upload-actions.ts          | 84 +++++++++++++----
 .../effects/media-upload-detection.test.ts    | 44 +++++++++
 src/core/effects/validation.ts                | 40 +++++++-
 21 files changed, 451 insertions(+), 159 deletions(-)
 create mode 100644 src/core/effects/media-upload-detection.test.ts

diff --git a/messages/en.json b/messages/en.json
index 87b7b2b..2c5905f 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -124,7 +124,7 @@
       "toolbar": {
         "addNode": "Add node",
         "generationNode": "Generation node",
-        "uploadNode": "Upload node",
+        "uploadNode": "Upload media",
         "upload": "Upload",
         "assets": "Assets",
         "batchScenes": "Batch scenes"
@@ -133,7 +133,7 @@
         "templates": "Templates",
         "historyAssets": "History assets",
         "addNodeTitle": "Add node",
-        "uploadNodeTitle": "Upload node",
+        "uploadNodeTitle": "Upload media",
         "recentAssetsTitle": "Recent assets",
         "recentImages": "Recent images",
         "recentVideos": "Recent videos",
@@ -190,6 +190,7 @@
         "promptPlaceholder": "Describe the image or video you want to generate. When you select a canvas node, it becomes the current reference or branch anchor."
       },
       "actions": {
+        "uploadMedia": "Upload media",
         "uploadImage": "Upload image",
         "uploadVideo": "Upload video",
         "combine": "Combine cards",
@@ -275,6 +276,8 @@
         "addNodeSuccess": "Prompt node added to the canvas.",
         "uploadImageInvalid": "Images must be JPG, PNG, or WebP and smaller than {maxSizeMb}MB.",
         "uploadVideoInvalid": "Videos must be MP4, WebM, or MOV and smaller than {maxSizeMb}MB.",
+        "uploadMediaInvalid": "{fileName} is not a supported image or video.",
+        "openingMediaPicker": "Opening media picker...",
         "openingImagePicker": "Opening image picker...",
         "openingVideoPicker": "Opening video picker...",
         "uploading": "Uploading asset...",
@@ -402,6 +405,8 @@
           "videoGeneration": "Video generation",
           "image": "Image",
           "video": "Video",
+          "previewLoading": "Loading preview...",
+          "previewUnavailable": "Preview unavailable",
           "processing": "Processing...",
           "pending": "Pending...",
           "generationFailed": "Generation failed",
@@ -511,6 +516,7 @@
       "workspaceNameLabel": "Workspace name",
       "projects": "Projects",
       "projectsLabel": "Open projects",
+      "githubRepository": "Open BeatAPI Workspace on GitHub",
       "projectAssets": {
         "triggerLabel": "Project assets",
         "title": "Project assets",
diff --git a/messages/zh.json b/messages/zh.json
index cf2d508..e3ec00a 100644
--- a/messages/zh.json
+++ b/messages/zh.json
@@ -125,7 +125,7 @@
       "toolbar": {
         "addNode": "新增节点",
         "generationNode": "生成节点",
-        "uploadNode": "上传节点",
+        "uploadNode": "上传素材",
         "upload": "上传",
         "assets": "资产库",
         "batchScenes": "批量场景"
@@ -134,7 +134,7 @@
         "templates": "模板库",
         "historyAssets": "历史素材",
         "addNodeTitle": "新增节点",
-        "uploadNodeTitle": "上传节点",
+        "uploadNodeTitle": "上传素材",
         "recentAssetsTitle": "最近素材",
         "recentImages": "最近图片",
         "recentVideos": "最近视频",
@@ -191,6 +191,7 @@
         "promptPlaceholder": "描述你想生成的图片或视频。选中画布节点后，它会成为当前参考素材或分支锚点。"
       },
       "actions": {
+        "uploadMedia": "上传素材",
         "uploadImage": "上传图片",
         "uploadVideo": "上传视频",
         "combine": "合并卡片",
@@ -276,6 +277,8 @@
         "addNodeSuccess": "提示节点已加入画布。",
         "uploadImageInvalid": "图片需为 JPG、PNG 或 WebP，且小于 {maxSizeMb}MB。",
         "uploadVideoInvalid": "视频需为 MP4、WebM 或 MOV，且小于 {maxSizeMb}MB。",
+        "uploadMediaInvalid": "{fileName} 不是支持的图片或视频格式。",
+        "openingMediaPicker": "正在打开素材选择器...",
         "openingImagePicker": "正在打开图片选择器...",
         "openingVideoPicker": "正在打开视频选择器...",
         "uploading": "上传素材中...",
@@ -403,6 +406,8 @@
           "videoGeneration": "视频生成",
           "image": "图片",
           "video": "视频",
+          "previewLoading": "正在加载预览...",
+          "previewUnavailable": "暂时无法预览",
           "processing": "处理中...",
           "pending": "等待中...",
           "generationFailed": "生成失败",
@@ -512,6 +517,7 @@
       "workspaceNameLabel": "空间名称",
       "projects": "项目",
       "projectsLabel": "打开项目列表",
+      "githubRepository": "在 GitHub 打开 BeatAPI Workspace",
       "projectAssets": {
         "triggerLabel": "项目素材",
         "title": "项目素材",
diff --git a/src/components/app/product-page-shell.test.ts b/src/components/app/product-page-shell.test.ts
index a0bd751..bc68aa7 100644
--- a/src/components/app/product-page-shell.test.ts
+++ b/src/components/app/product-page-shell.test.ts
@@ -19,6 +19,13 @@ const apiConfigSource = readFileSync(
 test('workspace header keeps mode switching, shared assets, and API configuration actions', () => {
   assert.match(shellSource, /WorkspaceApiConfigDialog/);
   assert.match(shellSource, /ProjectAssetsDialog/);
+  assert.match(shellSource, /GitHubIcon/);
+  assert.match(
+    shellSource,
+    /https:\/\/github\.com\/BeatAPI\/beatapi-workspace/
+  );
+  assert.match(shellSource, /target="_blank"/);
+  assert.match(shellSource, /rel="noreferrer"/);
   assert.match(shellSource, />Studio<\/span>/);
   assert.match(shellSource, />Canvas<\/span>/);
   assert.match(shellSource, /\{ workspaceMode \}/);
diff --git a/src/components/app/product-page-shell.tsx b/src/components/app/product-page-shell.tsx
index 40919ae..b635a6d 100644
--- a/src/components/app/product-page-shell.tsx
+++ b/src/components/app/product-page-shell.tsx
@@ -6,6 +6,7 @@ import { LayoutPanelTop, Workflow } from 'lucide-react';
 
 import { WorkspaceApiConfigDialog } from '@/components/app/workspace-api-config-dialog';
 import { ProjectAssetsDialog } from '@/components/app/project-assets-dialog';
+import { GitHubIcon } from '@/components/icons/github';
 import { Link } from '@/core/i18n/navigation';
 import { useTranslations } from '@/core/workspace-lib/shims/next-intl';
 import { apiJsonPatch, apiJsonPost } from '@/lib/api-client';
@@ -159,6 +160,16 @@ export function ProductPageShell({
               <WorkspaceApiConfigDialog
                 providerId={envConfigs.generation_provider}
               />
+              <a
+                href="https://github.com/BeatAPI/beatapi-workspace"
+                target="_blank"
+                rel="noreferrer"
+                aria-label={t('header.githubRepository')}
+                title={t('header.githubRepository')}
+                className="inline-flex size-9 shrink-0 items-center justify-center rounded-xl border border-white/[0.09] bg-white/[0.035] text-[var(--beat-text-2)] transition hover:border-white/[0.16] hover:bg-white/[0.075] hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--beat-graph)]/70"
+              >
+                <GitHubIcon className="size-[17px]" aria-hidden="true" />
+              </a>
             </div>
           </div>
         </header>
diff --git a/src/components/beatcanvas/beatcanvas-composer-reference-picker.test.tsx b/src/components/beatcanvas/beatcanvas-composer-reference-picker.test.tsx
index a08e54b..30212bd 100644
--- a/src/components/beatcanvas/beatcanvas-composer-reference-picker.test.tsx
+++ b/src/components/beatcanvas/beatcanvas-composer-reference-picker.test.tsx
@@ -77,3 +77,44 @@ test('open picker lists attached and canvas reference cards', () => {
   assert.match(html, /Beach/);
   assert.match(html, /aria-label="Remove reference"/);
 });
+
+test('open picker renders video references with video elements instead of images', () => {
+  const html = renderToStaticMarkup(
+    <BeatCanvasComposerReferencePicker
+      activeDraftId="draft-1"
+      canvasReferenceCards={[
+        {
+          id: 'video-2',
+          name: 'Canvas motion',
+          type: 'video',
+          thumbnailUrl: 'blob:canvas-motion',
+        },
+      ]}
+      currentReferenceCards={[
+        {
+          id: 'video-1',
+          name: 'Attached motion',
+          type: 'video',
+          thumbnailUrl: 'blob:attached-motion',
+        },
+      ]}
+      isDraftBusy={false}
+      isOpen={true}
+      labels={{
+        ...labels,
+        currentReferencesLabel: 'Attached',
+        fromCanvasLabel: 'From canvas',
+        removeReferenceLabel: 'Remove reference',
+      }}
+      onAttachCanvasReference={() => {}}
+      onOpenChange={() => {}}
+      onOpenReferencePicker={() => {}}
+      onRemoveCanvasReference={() => {}}
+      options={[{ intent: 'video', remaining: 2 }]}
+      primaryIntent="video"
+    />
+  );
+
+  assert.equal((html.match(/<video/g) ?? []).length, 2);
+  assert.doesNotMatch(html, /<img[^>]+blob:(?:attached|canvas)-motion/);
+});
diff --git a/src/components/beatcanvas/beatcanvas-composer-reference-picker.tsx b/src/components/beatcanvas/beatcanvas-composer-reference-picker.tsx
index 9cce337..cb18b72 100644
--- a/src/components/beatcanvas/beatcanvas-composer-reference-picker.tsx
+++ b/src/components/beatcanvas/beatcanvas-composer-reference-picker.tsx
@@ -164,7 +164,19 @@ export function BeatCanvasComposerReferencePicker({
                     className="flex w-full items-center justify-between gap-2 rounded-[8px] px-2 py-1.5 transition-colors duration-150 hover:bg-white/[0.06]"
                   >
                     <span className="flex min-w-0 items-center gap-2.5 text-[var(--beat-text-1)]">
-                      {card.thumbnailUrl ? (
+                      {card.thumbnailUrl && card.type === 'video' ? (
+                        <span className="relative inline-flex size-8 shrink-0 overflow-hidden rounded-md bg-black">
+                          <video
+                            src={card.thumbnailUrl}
+                            aria-label={card.name}
+                            muted
+                            playsInline
+                            preload="metadata"
+                            className="size-full object-cover"
+                          />
+                          <Video className="pointer-events-none absolute inset-0 m-auto size-3.5 text-white drop-shadow" />
+                        </span>
+                      ) : card.thumbnailUrl ? (
                         <img
                           src={card.thumbnailUrl}
                           alt=""
@@ -221,7 +233,19 @@ export function BeatCanvasComposerReferencePicker({
                       title={card.name}
                       className="relative aspect-square overflow-hidden rounded-lg border border-white/[0.08] transition hover:border-[var(--beat-graph)] disabled:cursor-not-allowed disabled:opacity-60"
                     >
-                      {card.thumbnailUrl ? (
+                      {card.thumbnailUrl && card.type === 'video' ? (
+                        <span className="relative inline-flex size-full bg-black">
+                          <video
+                            src={card.thumbnailUrl}
+                            aria-label={card.name}
+                            muted
+                            playsInline
+                            preload="metadata"
+                            className="size-full object-cover"
+                          />
+                          <Video className="pointer-events-none absolute inset-0 m-auto size-4 text-white drop-shadow" />
+                        </span>
+                      ) : card.thumbnailUrl ? (
                         <img
                           src={card.thumbnailUrl}
                           alt={card.name}
diff --git a/src/components/beatcanvas/beatcanvas-media-preview-overlay.test.tsx b/src/components/beatcanvas/beatcanvas-media-preview-overlay.test.tsx
index edf077c..2345ef9 100644
--- a/src/components/beatcanvas/beatcanvas-media-preview-overlay.test.tsx
+++ b/src/components/beatcanvas/beatcanvas-media-preview-overlay.test.tsx
@@ -23,3 +23,22 @@ test('media preview overlay renders the selected image at a larger size', () =>
   assert.match(html, /关闭/);
   assert.match(html, /max-h-\[calc\(100vh-140px\)\]/);
 });
+
+test('media preview overlay renders video playback controls', () => {
+  const html = renderToStaticMarkup(
+    <BeatCanvasMediaPreviewOverlay
+      media={{
+        type: 'video',
+        url: 'blob:local-video-preview',
+        title: 'Motion reference',
+      }}
+      closeLabel="Close"
+      onClose={() => {}}
+    />
+  );
+
+  assert.match(html, /<video/);
+  assert.match(html, /blob:local-video-preview/);
+  assert.match(html, /controls=""/);
+  assert.match(html, /Motion reference/);
+});
diff --git a/src/components/beatcanvas/beatcanvas-media-preview-overlay.tsx b/src/components/beatcanvas/beatcanvas-media-preview-overlay.tsx
index df23e78..b1e2b11 100644
--- a/src/components/beatcanvas/beatcanvas-media-preview-overlay.tsx
+++ b/src/components/beatcanvas/beatcanvas-media-preview-overlay.tsx
@@ -2,7 +2,7 @@ import { cn } from '@/lib/utils';
 import { X } from 'lucide-react';
 
 export type BeatCanvasPreviewMedia = {
-  type: 'image';
+  type: 'image' | 'video';
   url: string;
   title: string;
 };
@@ -39,12 +39,25 @@ export function BeatCanvasMediaPreviewOverlay({
           <X className="size-4" strokeWidth={2.2} />
           <span className="sr-only">{closeLabel}</span>
         </button>
-        <img
-          src={media.url}
-          alt={media.title}
-          className="max-h-[calc(100vh-140px)] max-w-full rounded-[10px] bg-white object-contain shadow-2xl"
-          draggable={false}
-        />
+        {media.type === 'video' ? (
+          <video
+            src={media.url}
+            aria-label={media.title}
+            controls
+            autoPlay
+            muted
+            playsInline
+            preload="metadata"
+            className="max-h-[calc(100vh-140px)] max-w-full rounded-[10px] bg-black object-contain shadow-2xl"
+          />
+        ) : (
+          <img
+            src={media.url}
+            alt={media.title}
+            className="max-h-[calc(100vh-140px)] max-w-full rounded-[10px] bg-white object-contain shadow-2xl"
+            draggable={false}
+          />
+        )}
         <div className="mt-3 max-w-full truncate rounded-full bg-black/65 px-3 py-1.5 text-[12px] font-medium text-white">
           {media.title}
         </div>
diff --git a/src/components/beatcanvas/beatcanvas-media-preview.test.ts b/src/components/beatcanvas/beatcanvas-media-preview.test.ts
index e0b94f2..854ce80 100644
--- a/src/components/beatcanvas/beatcanvas-media-preview.test.ts
+++ b/src/components/beatcanvas/beatcanvas-media-preview.test.ts
@@ -31,7 +31,7 @@ const makeCard = (overrides: Partial<CanvasCard>): CanvasCard => ({
   ...overrides,
 });
 
-test('recognizes only real image asset cards as previewable', () => {
+test('recognizes real image and video asset cards as previewable', () => {
   assert.equal(isPreviewableCanvasCard(makeCard({})), true);
   assert.equal(
     isPreviewableCanvasCard(
@@ -39,7 +39,7 @@ test('recognizes only real image asset cards as previewable', () => {
     ),
     false
   );
-  assert.equal(isPreviewableCanvasCard(makeCard({ type: 'video' })), false);
+  assert.equal(isPreviewableCanvasCard(makeCard({ type: 'video' })), true);
   assert.equal(
     isPreviewableCanvasCard(makeCard({ kind: 'generation' })),
     false
diff --git a/src/components/beatcanvas/beatcanvas-media-preview.ts b/src/components/beatcanvas/beatcanvas-media-preview.ts
index 2dd93f0..71d8926 100644
--- a/src/components/beatcanvas/beatcanvas-media-preview.ts
+++ b/src/components/beatcanvas/beatcanvas-media-preview.ts
@@ -6,8 +6,9 @@ export const isPreviewableCanvasCard = (
   Boolean(
     card?.url &&
       card.kind === 'asset' &&
-      card.type === 'image' &&
-      !card.url.startsWith('data:image/svg+xml')
+      (card.type === 'video' ||
+        (card.type === 'image' &&
+          !card.url.startsWith('data:image/svg+xml')))
   );
 
 export const getPreviewableCanvasCardFromSelection = ({
diff --git a/src/components/beatcanvas/beatcanvas-shell.tsx b/src/components/beatcanvas/beatcanvas-shell.tsx
index cd17d2c..d20e772 100644
--- a/src/components/beatcanvas/beatcanvas-shell.tsx
+++ b/src/components/beatcanvas/beatcanvas-shell.tsx
@@ -261,9 +261,12 @@ export function BeatCanvasShell({
   }, [errorMessage]);
 
   const {
+    handleMediaUpload,
     handleUpload,
+    mediaFileInputRef,
     imageFileInputRef,
     getPendingUploadCountForDraft,
+    openMediaUploadPicker,
     openUploadPicker,
     promotePendingUploadsForDraft,
     uploadIntent,
@@ -862,25 +865,39 @@ export function BeatCanvasShell({
 
     setActiveComposerCardId(null);
     setPreviewMedia({
-      type: 'image',
+      type: previewableSelectedCard.type,
       url: previewableSelectedCard.url,
       title:
-        previewableSelectedCard.name || studioT('canvas.frame.imageTitle'),
+        previewableSelectedCard.name ||
+        studioT(
+          previewableSelectedCard.type === 'video'
+            ? 'canvas.frame.videoTitle'
+            : 'canvas.frame.imageTitle'
+        ),
     });
   }, [previewableSelectedCard, setActiveComposerCardId, studioT]);
 
   useEffect(() => {
     const handlePreviewMediaEvent = (event: Event) => {
       const detail = (event as CustomEvent<BeatCanvasPreviewMedia>).detail;
-      if (detail?.type !== 'image' || !detail.url) {
+      if (
+        (detail?.type !== 'image' && detail?.type !== 'video') ||
+        !detail.url
+      ) {
         return;
       }
 
       setActiveComposerCardId(null);
       setPreviewMedia({
-        type: 'image',
+        type: detail.type,
         url: detail.url,
-        title: detail.title || studioT('canvas.frame.imageTitle'),
+        title:
+          detail.title ||
+          studioT(
+            detail.type === 'video'
+              ? 'canvas.frame.videoTitle'
+              : 'canvas.frame.imageTitle'
+          ),
       });
     };
 
@@ -1166,6 +1183,14 @@ export function BeatCanvasShell({
 
   return (
     <div className="relative flex min-h-0 flex-1 overflow-hidden bg-[var(--beatcanvas-canvas-bg)]">
+      <input
+        ref={mediaFileInputRef}
+        type="file"
+        accept="image/jpeg,image/png,image/webp,video/mp4,video/webm,video/quicktime,.jpg,.jpeg,.png,.webp,.mp4,.webm,.mov"
+        multiple
+        className="pointer-events-none absolute -left-[9999px] top-0 h-px w-px opacity-0"
+        onChange={handleMediaUpload}
+      />
       <input
         ref={imageFileInputRef}
         type="file"
@@ -1200,12 +1225,7 @@ export function BeatCanvasShell({
           {/* Floating Left Toolbar */}
           <BeatCanvasSidebar
             projectId={projectId}
-            onUploadImage={() =>
-              openUploadPicker({ intent: 'image', mode: 'global' })
-            }
-            onUploadVideo={() =>
-              openUploadPicker({ intent: 'video', mode: 'global' })
-            }
+            onUploadMedia={openMediaUploadPicker}
             onCreateImageDraft={() => handleCreatePromptDraft('image')}
             onInsertHistoryAsset={(asset) => {
               const sizeFromDimensions = ():
diff --git a/src/components/beatcanvas/beatcanvas-sidebar-panels.tsx b/src/components/beatcanvas/beatcanvas-sidebar-panels.tsx
index 350160d..d3c38e1 100644
--- a/src/components/beatcanvas/beatcanvas-sidebar-panels.tsx
+++ b/src/components/beatcanvas/beatcanvas-sidebar-panels.tsx
@@ -8,8 +8,6 @@ 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 {
-  ChevronRight,
-  ImagePlus,
   Loader2,
   Video,
 } from 'lucide-react';
@@ -18,45 +16,6 @@ import type { ReactNode } from 'react';
 import { beatPanelLabelClassName } from '@/components/app/composer-styles';
 import { cn } from '@/lib/utils';
 
-export function UploadNodePanel({
-  isUploadDisabled,
-  onUploadImage,
-  onUploadVideo,
-  onClose,
-}: {
-  isUploadDisabled: boolean;
-  onUploadImage: () => void;
-  onUploadVideo: () => void;
-  onClose: () => void;
-}) {
-  const t = useTranslations('AppShell.studio');
-  const handleAction = (fn: () => void) => {
-    fn();
-    onClose();
-  };
-
-  return (
-    <div className="flex flex-col gap-0.5 p-2">
-      <div className={cn(beatPanelLabelClassName, 'px-2 pb-1.5 pt-1')}>
-        {t('sidebar.uploadNodeTitle')}
-      </div>
-
-      <PanelButton
-        icon={<ImagePlus className="size-3.5" />}
-        label={t('actions.uploadImage')}
-        onClick={() => handleAction(onUploadImage)}
-        disabled={isUploadDisabled}
-      />
-      <PanelButton
-        icon={<Video className="size-3.5" />}
-        label={t('actions.uploadVideo')}
-        onClick={() => handleAction(onUploadVideo)}
-        disabled={isUploadDisabled}
-      />
-    </div>
-  );
-}
-
 export function HistoryPanel({
   onSelectAsset,
   projectId,
@@ -133,38 +92,6 @@ export function HistoryPanel({
   );
 }
 
-function PanelButton({
-  icon,
-  label,
-  onClick,
-  disabled = false,
-}: {
-  icon: ReactNode;
-  label: string;
-  onClick: () => void;
-  disabled?: boolean;
-}) {
-  return (
-    <button
-      type="button"
-      onClick={onClick}
-      disabled={disabled}
-      className="group flex w-full items-center gap-2.5 rounded-[10px] px-2 py-1.5 text-left transition-colors duration-150 hover:bg-white/[0.06] disabled:pointer-events-none disabled:opacity-40"
-    >
-      <span className="grid size-6 shrink-0 place-items-center text-[var(--beat-text-2)] transition-colors group-hover:text-[var(--beat-text-1)]">
-        {icon}
-      </span>
-      <span className="flex-1 text-[13px] font-medium text-[var(--beat-text-1)]">
-        {label}
-      </span>
-      <ChevronRight
-        size={14}
-        className="text-white/25 transition-colors group-hover:text-white/45"
-      />
-    </button>
-  );
-}
-
 function AssetSection({
   label,
   children,
diff --git a/src/components/beatcanvas/beatcanvas-sidebar.lazy-panels.test.ts b/src/components/beatcanvas/beatcanvas-sidebar.lazy-panels.test.ts
index 4a6563a..f0b2548 100644
--- a/src/components/beatcanvas/beatcanvas-sidebar.lazy-panels.test.ts
+++ b/src/components/beatcanvas/beatcanvas-sidebar.lazy-panels.test.ts
@@ -20,18 +20,14 @@ test('keeps sidebar panel-only data and template code out of the toolbar module'
   assert.doesNotMatch(source, /workflows\.ecommerceVideo\.title/);
   assert.doesNotMatch(source, /onOpenEcommerceVideoAd/);
 
-  assert.match(
-    source,
-    /const UploadNodePanel = lazy\(\(\) =>\s+import\(['"]\.\/beatcanvas-sidebar-panels['"]\)/
-  );
   assert.match(
     source,
     /const HistoryPanel = lazy\(\(\) =>\s+import\(['"]\.\/beatcanvas-sidebar-panels['"]\)/
   );
-  assert.match(source, /UploadNodePanel/);
+  assert.match(source, /onUploadMedia/);
   assert.match(source, /onCreateImageDraft/);
   assert.doesNotMatch(source, /onCreateVideoDraft/);
-  assert.match(source, /handleTogglePanel\('upload'\)/);
+  assert.doesNotMatch(source, /handleTogglePanel\('upload'\)/);
   assert.match(source, /toolbar\.generationNode/);
   assert.match(source, /toolbar\.uploadNode/);
   assert.doesNotMatch(source, /onOpenGenerationComposer/);
diff --git a/src/components/beatcanvas/beatcanvas-sidebar.tsx b/src/components/beatcanvas/beatcanvas-sidebar.tsx
index 0fe5327..848d948 100644
--- a/src/components/beatcanvas/beatcanvas-sidebar.tsx
+++ b/src/components/beatcanvas/beatcanvas-sidebar.tsx
@@ -13,14 +13,9 @@ import {
 } from 'react';
 import type { ReactNode } from 'react';
 
-type SidebarUploadIntent = 'image' | 'video';
-type ActivePanel = 'upload' | 'history';
+type SidebarUploadIntent = 'image' | 'video' | 'media';
+type ActivePanel = 'history';
 
-const UploadNodePanel = lazy(() =>
-  import('./beatcanvas-sidebar-panels').then((mod) => ({
-    default: mod.UploadNodePanel,
-  }))
-);
 const HistoryPanel = lazy(() =>
   import('./beatcanvas-sidebar-panels').then((mod) => ({
     default: mod.HistoryPanel,
@@ -29,8 +24,7 @@ const HistoryPanel = lazy(() =>
 
 export type BeatCanvasSidebarProps = {
   projectId?: string | null;
-  onUploadImage: () => void;
-  onUploadVideo: () => void;
+  onUploadMedia: () => void;
   onCreateImageDraft: () => void;
   onInsertHistoryAsset: (
     asset: RecentAsset & { mediaType: 'image' | 'video' }
@@ -40,8 +34,7 @@ export type BeatCanvasSidebarProps = {
 
 export default function BeatCanvasSidebar({
   projectId,
-  onUploadImage,
-  onUploadVideo,
+  onUploadMedia,
   onCreateImageDraft,
   onInsertHistoryAsset,
   uploadIntent,
@@ -76,8 +69,9 @@ export default function BeatCanvasSidebar({
         <ToolBtn
           icon={<ImagePlus size={17} />}
           title={t('toolbar.uploadNode')}
-          active={activePanel === 'upload'}
-          onClick={() => handleTogglePanel('upload')}
+          active={uploadIntent !== null}
+          disabled={uploadIntent !== null}
+          onClick={onUploadMedia}
         />
         <ToolSeparator />
         <ToolBtn
@@ -91,14 +85,6 @@ export default function BeatCanvasSidebar({
       {activePanel ? (
         <SlidePanel onClose={handleClosePanel}>
           <Suspense fallback={<SidebarPanelLoading />}>
-            {activePanel === 'upload' ? (
-              <UploadNodePanel
-                isUploadDisabled={uploadIntent !== null}
-                onUploadImage={onUploadImage}
-                onUploadVideo={onUploadVideo}
-                onClose={handleClosePanel}
-              />
-            ) : null}
             {activePanel === 'history' ? (
               <HistoryPanel
                 projectId={projectId}
@@ -116,12 +102,14 @@ function ToolBtn({
   icon,
   title,
   active,
+  disabled = false,
   tone = 'default',
   onClick,
 }: {
   icon: ReactNode;
   title: string;
   active: boolean;
+  disabled?: boolean;
   tone?: 'default' | 'danger';
   onClick: () => void;
 }) {
@@ -135,11 +123,12 @@ function ToolBtn({
       type="button"
       title={title}
       onClick={onClick}
+      disabled={disabled}
       className={`group relative flex h-10 w-10 items-center justify-center rounded-xl border border-transparent transition-[color,background-color,border-color,box-shadow,transform] duration-150 ease-out active:scale-[0.94] ${
         active
           ? 'border-white/[0.12] bg-white/[0.08] text-[var(--beat-text-1)] shadow-[inset_0_1px_0_rgba(255,255,255,0.07),0_8px_22px_rgba(0,0,0,0.4)]'
           : idleTone
-      }`}
+      } disabled:cursor-wait disabled:opacity-55`}
       aria-pressed={active}
     >
       {icon}
diff --git a/src/components/beatcanvas/nodes/asset-card-node-preview.test.ts b/src/components/beatcanvas/nodes/asset-card-node-preview.test.ts
index e55caa0..8c3f163 100644
--- a/src/components/beatcanvas/nodes/asset-card-node-preview.test.ts
+++ b/src/components/beatcanvas/nodes/asset-card-node-preview.test.ts
@@ -12,3 +12,18 @@ test('asset image cards expose a double-click preview event without previewing s
   assert.match(source, /beatcanvas:preview-media/);
   assert.match(source, /!thumbnailUrl\.startsWith\('data:image\/svg\+xml'\)/);
 });
+
+test('asset cards render videos as draggable video surfaces', () => {
+  const source = readFileSync(
+    new URL('./asset-card-node.tsx', import.meta.url),
+    'utf8'
+  );
+
+  assert.match(source, /cardMediaType === 'video'/);
+  assert.match(source, /<video/);
+  assert.match(source, /muted/);
+  assert.match(source, /playsInline/);
+  assert.match(source, /className="nowheel"/);
+  assert.doesNotMatch(source, /className="nodrag nowheel"/);
+  assert.match(source, /cursor-grab active:cursor-grabbing/);
+});
diff --git a/src/components/beatcanvas/nodes/asset-card-node.tsx b/src/components/beatcanvas/nodes/asset-card-node.tsx
index 3c44129..b08fa0f 100644
--- a/src/components/beatcanvas/nodes/asset-card-node.tsx
+++ b/src/components/beatcanvas/nodes/asset-card-node.tsx
@@ -6,7 +6,7 @@ import {
   Position,
   type NodeProps,
 } from '@xyflow/react';
-import type { MouseEvent } from 'react';
+import { useEffect, useState, type MouseEvent } from 'react';
 
 import { getBeatCanvasNodeCopy } from './beatcanvas-node-copy';
 import type { BeatCanvasFlowNode } from '../react-flow/beatcanvas-react-flow-types';
@@ -27,21 +27,30 @@ export function AssetCardNode({
   const isContain = fitMode === 'contain';
   const isFrameless = chromeMode === 'frameless';
   const hasOuterChrome = !isFrameless;
-  const canPreviewImage =
-    cardMediaType === 'image' &&
+  const [mediaStatus, setMediaStatus] = useState<
+    'idle' | 'loading' | 'ready' | 'error'
+  >(thumbnailUrl ? 'loading' : 'idle');
+
+  useEffect(() => {
+    setMediaStatus(thumbnailUrl ? 'loading' : 'idle');
+  }, [cardMediaType, thumbnailUrl]);
+  const canPreviewMedia =
     Boolean(thumbnailUrl) &&
-    !thumbnailUrl.startsWith('data:image/svg+xml');
+    (cardMediaType === 'video' ||
+      !thumbnailUrl.startsWith('data:image/svg+xml'));
 
-  const handlePreviewImage = (event: MouseEvent<HTMLImageElement>) => {
-    if (!canPreviewImage || typeof window === 'undefined') return;
+  const handlePreviewMedia = (event: MouseEvent<HTMLElement>) => {
+    if (!canPreviewMedia || typeof window === 'undefined') return;
     event.preventDefault();
     event.stopPropagation();
     window.dispatchEvent(
       new CustomEvent('beatcanvas:preview-media', {
         detail: {
-          type: 'image',
+          type: cardMediaType,
           url: thumbnailUrl,
-          title: title || shapeCopy.image,
+          title:
+            title ||
+            (cardMediaType === 'video' ? shapeCopy.video : shapeCopy.image),
         },
       })
     );
@@ -63,6 +72,7 @@ export function AssetCardNode({
       />
       <div
         data-card-id={id}
+        className="group cursor-grab active:cursor-grabbing"
         style={{
           width: w,
           height: h,
@@ -104,19 +114,69 @@ export function AssetCardNode({
               (cardMediaType === 'video' ? shapeCopy.video : shapeCopy.image)}
           </div>
         )}
-        {thumbnailUrl ? (
+        {thumbnailUrl && mediaStatus === 'error' ? (
+          <div
+            className="grid size-full place-items-center px-4 text-center text-xs text-[var(--beat-text-3)]"
+            role="status"
+          >
+            {shapeCopy.previewUnavailable}
+          </div>
+        ) : thumbnailUrl && cardMediaType === 'video' ? (
+          <>
+            <video
+              src={thumbnailUrl}
+              aria-label={title}
+              muted
+              playsInline
+              preload="metadata"
+              draggable={false}
+              onLoadedMetadata={(event) => {
+                const video = event.currentTarget;
+                if (video.duration > 0 && video.currentTime === 0) {
+                  video.currentTime = Math.min(0.05, video.duration / 2);
+                }
+              }}
+              onLoadedData={() => setMediaStatus('ready')}
+              onError={() => setMediaStatus('error')}
+              onDoubleClick={handlePreviewMedia}
+              className="nowheel"
+              style={{
+                width: '100%',
+                height: '100%',
+                objectFit: isContain ? 'contain' : 'cover',
+                display: 'block',
+                cursor: 'zoom-in',
+                borderRadius: CARD_RADIUS - 1,
+                padding: 0,
+                boxSizing: 'border-box',
+              }}
+            />
+            {mediaStatus === 'ready' ? (
+              <div
+                aria-hidden="true"
+                className="pointer-events-none absolute inset-0 grid place-items-center bg-black/10 opacity-80 transition-opacity group-hover:opacity-100"
+              >
+                <span className="grid size-10 place-items-center rounded-full bg-black/65 text-lg text-white shadow-lg">
+                  ▶
+                </span>
+              </div>
+            ) : null}
+          </>
+        ) : thumbnailUrl ? (
           <img
             src={thumbnailUrl}
             alt={title}
             draggable={false}
-            onDoubleClick={handlePreviewImage}
-            className="nodrag nowheel"
+            onLoad={() => setMediaStatus('ready')}
+            onError={() => setMediaStatus('error')}
+            onDoubleClick={handlePreviewMedia}
+            className="nowheel"
             style={{
               width: '100%',
               height: '100%',
               objectFit: isContain ? 'contain' : 'cover',
               display: 'block',
-              cursor: canPreviewImage ? 'zoom-in' : 'default',
+              cursor: canPreviewMedia ? 'zoom-in' : 'default',
               borderRadius: CARD_RADIUS - 1,
               padding: 0,
               boxSizing: 'border-box',
@@ -139,6 +199,14 @@ export function AssetCardNode({
               : `🖼 ${shapeCopy.image}`}
           </div>
         )}
+        {thumbnailUrl && mediaStatus === 'loading' ? (
+          <div
+            className="pointer-events-none absolute inset-0 grid place-items-center bg-black/25 px-3 text-center text-[11px] text-white/80"
+            role="status"
+          >
+            {shapeCopy.previewLoading}
+          </div>
+        ) : null}
       </div>
       <Handle
         type="source"
diff --git a/src/components/beatcanvas/nodes/beatcanvas-node-copy.ts b/src/components/beatcanvas/nodes/beatcanvas-node-copy.ts
index 7383964..0b2c1a0 100644
--- a/src/components/beatcanvas/nodes/beatcanvas-node-copy.ts
+++ b/src/components/beatcanvas/nodes/beatcanvas-node-copy.ts
@@ -8,6 +8,8 @@ type BeatCanvasNodeCopy = {
   videoGeneration: string;
   image: string;
   video: string;
+  previewLoading: string;
+  previewUnavailable: string;
   pending: string;
   processing: string;
   generationFailed: string;
@@ -52,6 +54,14 @@ const getNodeCopyForLocale = (locale: BeatCanvasNodeLocale): BeatCanvasNodeCopy
   ),
   image: m['AppShell.studio.canvas.shapes.image']({}, { locale }),
   video: m['AppShell.studio.canvas.shapes.video']({}, { locale }),
+  previewLoading: m['AppShell.studio.canvas.shapes.previewLoading'](
+    {},
+    { locale }
+  ),
+  previewUnavailable: m['AppShell.studio.canvas.shapes.previewUnavailable'](
+    {},
+    { locale }
+  ),
   pending: m['AppShell.studio.canvas.shapes.pending']({}, { locale }),
   processing: m['AppShell.studio.canvas.shapes.processing']({}, { locale }),
   generationFailed: m['AppShell.studio.canvas.shapes.generationFailed'](
diff --git a/src/components/beatcanvas/use-beatcanvas-upload-actions.test.ts b/src/components/beatcanvas/use-beatcanvas-upload-actions.test.ts
index 3176557..ea836fb 100644
--- a/src/components/beatcanvas/use-beatcanvas-upload-actions.test.ts
+++ b/src/components/beatcanvas/use-beatcanvas-upload-actions.test.ts
@@ -33,6 +33,13 @@ test('does not change non-image uploads through the image-only policy', () => {
     }),
     false
   );
+  assert.equal(
+    shouldUploadImmediatelyAfterCanvasInsert({
+      request: { intent: 'media', mode: 'global' },
+      hasResolvedFrame: true,
+    }),
+    false
+  );
 });
 
 test('materializes local image references without uploading them', () => {
diff --git a/src/components/beatcanvas/use-beatcanvas-upload-actions.ts b/src/components/beatcanvas/use-beatcanvas-upload-actions.ts
index 865d500..5c07901 100644
--- a/src/components/beatcanvas/use-beatcanvas-upload-actions.ts
+++ b/src/components/beatcanvas/use-beatcanvas-upload-actions.ts
@@ -1,6 +1,7 @@
 'use client';
 
 import {
+  detectUploadedMediaType,
   validateUploadedImageFile,
   validateUploadedVideoFile,
 } from '@/core/effects/validation';
@@ -42,8 +43,13 @@ type TranslateFn = (
 ) => string;
 
 export type UploadIntent = CanvasCardMediaType;
+export type UploadActivityIntent = UploadIntent | 'media';
 
 export type UploadRequest =
+  | {
+      intent: 'media';
+      mode: 'global';
+    }
   | {
       intent: UploadIntent;
       mode: 'global';
@@ -195,7 +201,9 @@ export function useBeatCanvasUploadActions({
   setActiveComposerCardId: (cardId: string | null) => void;
   onWorkspaceAssetsMayChange?: () => void;
 }) {
-  const [uploadIntent, setUploadIntent] = useState<UploadIntent | null>(null);
+  const [uploadIntent, setUploadIntent] =
+    useState<UploadActivityIntent | null>(null);
+  const mediaFileInputRef = useRef<HTMLInputElement | null>(null);
   const imageFileInputRef = useRef<HTMLInputElement | null>(null);
   const videoFileInputRef = useRef<HTMLInputElement | null>(null);
   const uploadRequestRef = useRef<UploadRequest | null>(null);
@@ -288,6 +296,19 @@ export function useBeatCanvasUploadActions({
     ]
   );
 
+  const openMediaUploadPicker = useCallback(() => {
+    const input = mediaFileInputRef.current;
+    if (!input) {
+      return;
+    }
+
+    input.value = '';
+    uploadRequestRef.current = { intent: 'media', mode: 'global' };
+    setErrorMessage(null);
+    setStatusMessage(studioT('messages.openingMediaPicker'));
+    input.click();
+  }, [setErrorMessage, setStatusMessage, studioT]);
+
   function resolveUploadNaturalSize(
     objectUrl: string,
     intent: UploadIntent
@@ -316,8 +337,7 @@ export function useBeatCanvasUploadActions({
 
   const uploadFiles = useCallback(
     async (request: UploadRequest, allFiles: File[]) => {
-      const intent = request.intent;
-      setUploadIntent(intent);
+      setUploadIntent(request.intent);
 
       if (allFiles.length === 0) {
         uploadRequestRef.current = null;
@@ -325,21 +345,35 @@ export function useBeatCanvasUploadActions({
         setStatusMessage('');
         return;
       }
-      const files =
-        request.mode === 'global' && intent === 'image'
-          ? allFiles
-          : allFiles.slice(0, 1);
+      const files = request.mode === 'global' ? allFiles : allFiles.slice(0, 1);
+      const uploads = files.map((file) => ({
+        file,
+        intent:
+          request.intent === 'media'
+            ? detectUploadedMediaType(file)
+            : request.intent,
+      }));
+
+      for (const upload of uploads) {
+        if (!upload.intent) {
+          const message = studioT('messages.uploadMediaInvalid', {
+            fileName: upload.file.name,
+          });
+          setErrorMessage(message);
+          setUploadIntent(null);
+          toast.error(message);
+          return;
+        }
 
-      for (const file of files) {
         const validation =
-          intent === 'image'
-            ? validateUploadedImageFile(file)
-            : validateUploadedVideoFile(file);
+          upload.intent === 'image'
+            ? validateUploadedImageFile(upload.file)
+            : validateUploadedVideoFile(upload.file);
 
         if (!validation.ok) {
           const maxSizeMb = Math.floor(validation.maxBytes / (1024 * 1024));
           const message =
-            intent === 'image'
+            upload.intent === 'image'
               ? studioT('messages.uploadImageInvalid', { maxSizeMb })
               : studioT('messages.uploadVideoInvalid', { maxSizeMb });
           setErrorMessage(message);
@@ -355,7 +389,11 @@ export function useBeatCanvasUploadActions({
       try {
         const insertedAssetCardIds: string[] = [];
 
-        for (const [index, file] of files.entries()) {
+        for (const [index, upload] of uploads.entries()) {
+          const { file, intent } = upload;
+          if (!intent) {
+            continue;
+          }
           const localObjectUrl = URL.createObjectURL(file);
 
           const naturalSize = await resolveUploadNaturalSize(
@@ -370,8 +408,7 @@ export function useBeatCanvasUploadActions({
             anchorCardIds:
               request.mode === 'reference' ? [request.draftId] : undefined,
             placementSide: request.mode === 'reference' ? 'left' : 'right',
-            placementOffsetIndex:
-              request.mode === 'global' && intent === 'image' ? index : 0,
+            placementOffsetIndex: request.mode === 'global' ? index : 0,
             activateOnInsert: request.mode !== 'reference',
             ...(naturalSize ? { size: naturalSize } : {}),
           });
@@ -448,7 +485,6 @@ export function useBeatCanvasUploadActions({
 
         if (
           request.mode === 'global' &&
-          intent === 'image' &&
           insertedAssetCardIds.length > 1
         ) {
           handleSelectShape(
@@ -508,6 +544,19 @@ export function useBeatCanvasUploadActions({
     [uploadFiles]
   );
 
+  const handleMediaUpload = useCallback(
+    async (event: ChangeEvent<HTMLInputElement>) => {
+      const request: UploadRequest =
+        uploadRequestRef.current?.intent === 'media'
+          ? uploadRequestRef.current
+          : { intent: 'media', mode: 'global' };
+      const allFiles = Array.from(event.target.files ?? []);
+      event.target.value = '';
+      await uploadFiles(request, allFiles);
+    },
+    [uploadFiles]
+  );
+
   const promotePendingUploadsForDraft = useCallback(
     async (draftId: string, generationIntentToken: string) => {
       const draftCard = canvasCardsRef.current[draftId];
@@ -572,10 +621,13 @@ export function useBeatCanvasUploadActions({
   );
 
   return {
+    handleMediaUpload,
     handleUpload,
+    mediaFileInputRef,
     imageFileInputRef,
     getPendingUploadCountForDraft,
     materializePendingImageReferences,
+    openMediaUploadPicker,
     openUploadPicker,
     promotePendingUploadsForDraft,
     uploadFiles,
diff --git a/src/core/effects/media-upload-detection.test.ts b/src/core/effects/media-upload-detection.test.ts
new file mode 100644
index 0000000..2b3717d
--- /dev/null
+++ b/src/core/effects/media-upload-detection.test.ts
@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  detectUploadedMediaType,
+  validateUploadedVideoFile,
+} from './validation';
+
+test('detects supported images and videos from MIME types', () => {
+  assert.equal(
+    detectUploadedMediaType({ name: 'portrait.png', type: 'image/png' }),
+    'image'
+  );
+  assert.equal(
+    detectUploadedMediaType({ name: 'motion.mp4', type: 'video/mp4' }),
+    'video'
+  );
+});
+
+test('falls back to supported file extensions when browsers omit MIME types', () => {
+  assert.equal(
+    detectUploadedMediaType({ name: 'portrait.WEBP', type: '' }),
+    'image'
+  );
+  assert.equal(
+    detectUploadedMediaType({ name: 'motion.MOV', type: '' }),
+    'video'
+  );
+  assert.equal(
+    detectUploadedMediaType({ name: 'notes.txt', type: 'text/plain' }),
+    null
+  );
+});
+
+test('accepts a supported video extension when MIME type is missing', () => {
+  assert.deepEqual(
+    validateUploadedVideoFile({
+      name: 'reference.mov',
+      type: '',
+      size: 1024,
+    }),
+    { ok: true }
+  );
+});
diff --git a/src/core/effects/validation.ts b/src/core/effects/validation.ts
index b2f2085..726469d 100644
--- a/src/core/effects/validation.ts
+++ b/src/core/effects/validation.ts
@@ -99,6 +99,38 @@ const getNormalizedMimeType = (fileType: string) =>
 const hasAllowedImageExtension = (fileName?: string) =>
   Boolean(fileName && /\.(jpe?g|png|webp)$/i.test(fileName));
 
+const hasAllowedVideoExtension = (fileName?: string) =>
+  Boolean(fileName && /\.(mp4|webm|mov)$/i.test(fileName));
+
+export type UploadedMediaType = 'image' | 'video';
+
+export const detectUploadedMediaType = (file: {
+  type: string;
+  name?: string;
+}): UploadedMediaType | null => {
+  const mimeType = getNormalizedMimeType(file.type);
+
+  if (
+    ALLOWED_IMAGE_MIME_TYPES.includes(
+      mimeType as (typeof ALLOWED_IMAGE_MIME_TYPES)[number]
+    ) ||
+    hasAllowedImageExtension(file.name)
+  ) {
+    return 'image';
+  }
+
+  if (
+    ALLOWED_VIDEO_MIME_TYPES.includes(
+      mimeType as (typeof ALLOWED_VIDEO_MIME_TYPES)[number]
+    ) ||
+    hasAllowedVideoExtension(file.name)
+  ) {
+    return 'video';
+  }
+
+  return null;
+};
+
 export const countPromptCharacters = (prompt: string) =>
   Array.from(prompt).length;
 
@@ -193,6 +225,7 @@ export const validateUploadedImageFile = (file: {
 export const validateUploadedVideoFile = (file: {
   size: number;
   type: string;
+  name?: string;
 }): UploadedVideoValidationSuccess | UploadedVideoValidationFailure => {
   if (file.size > REFERENCE_VIDEO_MAX_FILE_SIZE) {
     return {
@@ -204,8 +237,11 @@ export const validateUploadedVideoFile = (file: {
 
   if (
     !ALLOWED_VIDEO_MIME_TYPES.includes(
-      file.type as (typeof ALLOWED_VIDEO_MIME_TYPES)[number]
-    )
+      getNormalizedMimeType(
+        file.type
+      ) as (typeof ALLOWED_VIDEO_MIME_TYPES)[number]
+    ) &&
+    !hasAllowedVideoExtension(file.name)
   ) {
     return {
       ok: false,

From 8068a0eae063e8244de54e4082ac295b7e251cb0 Mon Sep 17 00:00:00 2001
From: KKKK <kh844257437@gmail.com>
Date: Fri, 21 Aug 2026 15:51:32 +0800
Subject: [PATCH 2/2] feat: add semantic media references and motion control

---
 .env.example                                  |   2 +-
 PROVIDERS.md                                  |   2 +
 README.md                                     |   2 +-
 messages/en.json                              |   8 +-
 messages/zh.json                              |   8 +-
 .../beatcanvas-composer-parameter-picker.tsx  |  69 ++++++
 ...tcanvas-composer-reference-picker.test.tsx |  40 ++++
 .../beatcanvas-composer-reference-picker.tsx  | 197 +++++++++++-----
 .../beatcanvas-composer-shell.test.tsx        |   6 +
 .../beatcanvas/beatcanvas-composer-shell.tsx  | 211 ++++++++++++++++--
 .../beatcanvas/beatcanvas-composer-utils.ts   |  12 +
 .../beatcanvas-front-layer-context.tsx        |  21 ++
 .../beatcanvas/beatcanvas-front-layer.tsx     |  76 ++++++-
 .../beatcanvas/beatcanvas-shell.tsx           | 111 ++++++++-
 .../use-beatcanvas-draft-actions.ts           |  25 +++
 .../use-beatcanvas-react-flow-adapter.ts      |  12 +
 src/components/pricing/pricing-catalog.json   |  16 ++
 .../pricing/pricing-comparison-data.test.ts   |  37 ++-
 src/core/adapters/beatapi-adapter.test.ts     | 115 ++++++++++
 src/core/adapters/beatapi-adapter.ts          |  61 +++++
 src/core/beatcanvas/canvas-types.ts           |   6 +
 src/core/beatcanvas/canvas-workflows.ts       |   4 +-
 .../beatcanvas/composer-references.test.ts    |  69 ++++++
 src/core/beatcanvas/composer.ts               |  65 +++++-
 src/core/beatcanvas/draft-defaults.ts         |   2 +
 .../generation-controller-language.test.ts    |  52 +++++
 ...neration-controller-motion-control.test.ts | 114 ++++++++++
 src/core/beatcanvas/generation-controller.ts  |  17 +-
 .../beatcanvas/reference-mentions.test.ts     | 125 +++++++++++
 src/core/beatcanvas/reference-mentions.ts     | 184 +++++++++++++++
 src/core/effects/effect-registry.ts           |  54 ++++-
 src/core/effects/generation-upload-intent.ts  |  24 ++
 src/core/effects/registered-effects.test.ts   |  18 ++
 src/core/effects/registered-effects.ts        |  17 ++
 src/core/effects/workspace-media.ts           |  10 +
 src/core/effects/workspace-models.test.ts     |  30 +++
 src/core/effects/workspace-models.ts          |  16 ++
 src/core/projects/project-snapshot.ts         |  10 +
 src/core/workspace-lib/constants.ts           |   2 +-
 src/core/workspace-lib/model-icons.test.ts    |  17 ++
 src/core/workspace-lib/model-icons.ts         |   2 +
 src/routes/api/storage/upload.ts              |  56 ++++-
 42 files changed, 1802 insertions(+), 123 deletions(-)
 create mode 100644 src/core/beatcanvas/generation-controller-motion-control.test.ts
 create mode 100644 src/core/beatcanvas/reference-mentions.test.ts
 create mode 100644 src/core/beatcanvas/reference-mentions.ts
 create mode 100644 src/core/workspace-lib/model-icons.test.ts

diff --git a/.env.example b/.env.example
index 5ca98a5..e918428 100644
--- a/.env.example
+++ b/.env.example
@@ -33,7 +33,7 @@ EFFECTS_GENERATION_TIMEOUT_MS=1800000
 WORKSPACE_STORAGE_MODE=beatapi
 
 # Official hosted deployments only: BeatAPI-managed fallback for generation
-# input types that /v1/files does not accept, such as reference video.
+# input types that /v1/files does not accept.
 BEATAPI_MANAGED_R2_REGION=auto
 BEATAPI_MANAGED_R2_ENDPOINT=
 BEATAPI_MANAGED_R2_ACCESS_KEY_ID=
diff --git a/PROVIDERS.md b/PROVIDERS.md
index 1bec26e..7b0a1bb 100644
--- a/PROVIDERS.md
+++ b/PROVIDERS.md
@@ -18,6 +18,8 @@ The adapter uses:
 
 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.
 
+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.
+
 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.
 
 ## Storage
diff --git a/README.md b/README.md
index 6e50363..c43e7d4 100644
--- a/README.md
+++ b/README.md
@@ -54,7 +54,7 @@ No shared R2 secret is committed to this repository. “Preconfigured” means t
 
 ## Supported model catalog
 
-The canonical catalog lives in `src/core/effects/effect-registry.ts`. The current workspace exposes four image models and five video models through one BeatAPI adapter. Update the registry and adapter together when BeatAPI's public contract changes.
+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.
 
 ## Commands
 
diff --git a/messages/en.json b/messages/en.json
index 2c5905f..7510668 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -361,6 +361,8 @@
           "variant": "Variant",
           "quality": "Quality",
           "language": "Language",
+          "characterOrientation": "Character orientation",
+          "backgroundSource": "Background source",
           "tokens": {
             "quality": "Quality",
             "fast": "Fast",
@@ -374,7 +376,11 @@
             "landscape": "Landscape",
             "portrait": "Portrait",
             "chinese": "Chinese",
-            "english": "English"
+            "english": "English",
+            "imageOrientation": "Follow image",
+            "videoOrientation": "Follow video",
+            "inputImage": "Image background",
+            "inputVideo": "Video background"
           },
           "status": {
             "queued": "Queued",
diff --git a/messages/zh.json b/messages/zh.json
index e3ec00a..5ac6eff 100644
--- a/messages/zh.json
+++ b/messages/zh.json
@@ -362,6 +362,8 @@
           "variant": "版本",
           "quality": "质量",
           "language": "语种",
+          "characterOrientation": "角色朝向",
+          "backgroundSource": "背景来源",
           "tokens": {
             "quality": "质量",
             "fast": "快速",
@@ -375,7 +377,11 @@
             "landscape": "横向",
             "portrait": "纵向",
             "chinese": "中文",
-            "english": "英文"
+            "english": "英文",
+            "imageOrientation": "跟随图片",
+            "videoOrientation": "跟随视频",
+            "inputImage": "图片背景",
+            "inputVideo": "视频背景"
           },
           "status": {
             "queued": "排队中",
diff --git a/src/components/beatcanvas/beatcanvas-composer-parameter-picker.tsx b/src/components/beatcanvas/beatcanvas-composer-parameter-picker.tsx
index 2ecbd38..abd2015 100644
--- a/src/components/beatcanvas/beatcanvas-composer-parameter-picker.tsx
+++ b/src/components/beatcanvas/beatcanvas-composer-parameter-picker.tsx
@@ -2,6 +2,8 @@
 
 import type {
   WorkspaceAspectRatio,
+  WorkspaceBackgroundSource,
+  WorkspaceCharacterOrientation,
   WorkspaceDuration,
   WorkspaceLanguage,
   WorkspaceModelMode,
@@ -33,6 +35,8 @@ export function BeatCanvasComposerParameterPicker({
   isOpen,
   labels,
   onDraftAspectRatioChange,
+  onDraftBackgroundSourceChange,
+  onDraftCharacterOrientationChange,
   onDraftDurationChange,
   onDraftLanguageChange,
   onDraftModeChange,
@@ -42,6 +46,8 @@ export function BeatCanvasComposerParameterPicker({
   onOpenChange,
   parameterSummaryLabel,
   selectedAspectRatioOptions,
+  selectedBackgroundSourceOptions,
+  selectedCharacterOrientationOptions,
   selectedDurationOptions,
   selectedLanguageOptions,
   selectedModeOptions,
@@ -60,6 +66,14 @@ export function BeatCanvasComposerParameterPicker({
     draftId: string,
     aspectRatio: WorkspaceAspectRatio
   ) => void;
+  onDraftBackgroundSourceChange: (
+    draftId: string,
+    backgroundSource: WorkspaceBackgroundSource
+  ) => void;
+  onDraftCharacterOrientationChange: (
+    draftId: string,
+    characterOrientation: WorkspaceCharacterOrientation
+  ) => void;
   onDraftDurationChange: (draftId: string, duration: WorkspaceDuration) => void;
   onDraftLanguageChange: (draftId: string, language: WorkspaceLanguage) => void;
   onDraftModeChange: (draftId: string, mode: WorkspaceModelMode) => void;
@@ -78,6 +92,8 @@ export function BeatCanvasComposerParameterPicker({
   onOpenChange: (nextOpen: boolean) => void;
   parameterSummaryLabel: string;
   selectedAspectRatioOptions: WorkspaceAspectRatio[];
+  selectedBackgroundSourceOptions: WorkspaceBackgroundSource[];
+  selectedCharacterOrientationOptions: WorkspaceCharacterOrientation[];
   selectedDurationOptions: WorkspaceDuration[];
   selectedLanguageOptions: WorkspaceLanguage[];
   selectedModeOptions: WorkspaceModelMode[];
@@ -236,6 +252,59 @@ export function BeatCanvasComposerParameterPicker({
               </section>
             ) : null}
 
+            {selectedCharacterOrientationOptions.length > 0 ? (
+              <section className="space-y-1.5">
+                <p className={composerSectionLabelClassName}>
+                  {labels.characterOrientationLabel}
+                </p>
+                <div className="grid grid-cols-2 gap-1.5">
+                  {selectedCharacterOrientationOptions.map((item) => (
+                    <button
+                      key={item}
+                      type="button"
+                      disabled={isDraftBusy}
+                      onClick={() =>
+                        onDraftCharacterOrientationChange(
+                          activeDraftCard.id,
+                          item
+                        )
+                      }
+                      className={getParameterChipClassName(
+                        activeDraftCard.characterOrientation === item
+                      )}
+                    >
+                      {normalizeComposerToken(item, labels)}
+                    </button>
+                  ))}
+                </div>
+              </section>
+            ) : null}
+
+            {selectedBackgroundSourceOptions.length > 0 ? (
+              <section className="space-y-1.5">
+                <p className={composerSectionLabelClassName}>
+                  {labels.backgroundSourceLabel}
+                </p>
+                <div className="grid grid-cols-2 gap-1.5">
+                  {selectedBackgroundSourceOptions.map((item) => (
+                    <button
+                      key={item}
+                      type="button"
+                      disabled={isDraftBusy}
+                      onClick={() =>
+                        onDraftBackgroundSourceChange(activeDraftCard.id, item)
+                      }
+                      className={getParameterChipClassName(
+                        activeDraftCard.backgroundSource === item
+                      )}
+                    >
+                      {normalizeComposerToken(item, labels)}
+                    </button>
+                  ))}
+                </div>
+              </section>
+            ) : null}
+
             {selectedLanguageOptions.length > 0 ? (
               <section className="space-y-1.5">
                 <p className={composerSectionLabelClassName}>
diff --git a/src/components/beatcanvas/beatcanvas-composer-reference-picker.test.tsx b/src/components/beatcanvas/beatcanvas-composer-reference-picker.test.tsx
index 30212bd..b0264db 100644
--- a/src/components/beatcanvas/beatcanvas-composer-reference-picker.test.tsx
+++ b/src/components/beatcanvas/beatcanvas-composer-reference-picker.test.tsx
@@ -118,3 +118,43 @@ test('open picker renders video references with video elements instead of images
   assert.equal((html.match(/<video/g) ?? []).length, 2);
   assert.doesNotMatch(html, /<img[^>]+blob:(?:attached|canvas)-motion/);
 });
+
+test('row variant exposes independently numbered image and video mention chips', () => {
+  const html = renderToStaticMarkup(
+    <BeatCanvasComposerReferencePicker
+      activeDraftId="draft-1"
+      currentReferenceCards={[
+        {
+          id: 'image-1',
+          name: 'Character',
+          type: 'image',
+          alias: '@Image1',
+          thumbnailUrl: 'https://example.com/character.png',
+        },
+        {
+          id: 'video-1',
+          name: 'Dance motion',
+          type: 'video',
+          alias: '@Video1',
+          thumbnailUrl: 'https://example.com/motion.mp4',
+        },
+      ]}
+      isDraftBusy={false}
+      isOpen={false}
+      labels={labels}
+      onOpenChange={() => {}}
+      onOpenReferencePicker={() => {}}
+      options={[
+        { intent: 'image', remaining: null },
+        { intent: 'video', remaining: 2 },
+      ]}
+      primaryIntent="image"
+      variant="row"
+    />
+  );
+
+  assert.match(html, /@Image1/);
+  assert.match(html, /@Video1/);
+  assert.match(html, /draggable="true"/);
+  assert.equal((html.match(/<video/g) ?? []).length, 1);
+});
diff --git a/src/components/beatcanvas/beatcanvas-composer-reference-picker.tsx b/src/components/beatcanvas/beatcanvas-composer-reference-picker.tsx
index cb18b72..4664078 100644
--- a/src/components/beatcanvas/beatcanvas-composer-reference-picker.tsx
+++ b/src/components/beatcanvas/beatcanvas-composer-reference-picker.tsx
@@ -2,8 +2,8 @@
 
 import { cn } from '@/lib/utils';
 import type { CanvasGenerationCard } from '@/core/beatcanvas/canvas-types';
-import { ChevronDown, ImagePlus, Video, X } from 'lucide-react';
-import type { RefObject } from 'react';
+import { ChevronDown, GripVertical, ImagePlus, Video, X } from 'lucide-react';
+import { useState, type RefObject } from 'react';
 
 import {
   composerFloatingPanelClassName,
@@ -23,6 +23,7 @@ export type CanvasReferenceCardOption = {
   name: string;
   type: CanvasGenerationCard['type'];
   thumbnailUrl: string | null;
+  alias?: string;
 };
 
 export function BeatCanvasComposerReferencePicker({
@@ -36,6 +37,8 @@ export function BeatCanvasComposerReferencePicker({
   onAttachCanvasReference = () => {},
   onOpenChange,
   onOpenReferencePicker,
+  onInsertReferenceMention = () => {},
+  onReorderCanvasReferences = () => {},
   onRemoveCanvasReference = () => {},
   options,
   primaryIntent,
@@ -54,11 +57,20 @@ export function BeatCanvasComposerReferencePicker({
     draftId: string,
     intent: CanvasGenerationCard['type']
   ) => void;
+  onInsertReferenceMention?: (alias: string) => void;
+  onReorderCanvasReferences?: (
+    draftId: string,
+    activeCardId: string,
+    overCardId: string
+  ) => void;
   onRemoveCanvasReference?: (draftId: string, cardId: string) => void;
   options: ReferenceOption[];
   primaryIntent: CanvasGenerationCard['type'];
   variant?: 'icon' | 'row';
 }) {
+  const [draggedReferenceId, setDraggedReferenceId] = useState<string | null>(
+    null
+  );
   const isRow = variant === 'row';
   const primaryLabel =
     primaryIntent === 'video'
@@ -67,56 +79,133 @@ export function BeatCanvasComposerReferencePicker({
   const attachedCount = currentReferenceCards.length;
 
   return (
-    <div
-      ref={containerRef}
-      className={cn('relative shrink-0', isRow && 'inline-flex')}
-    >
-      <button
-        type="button"
-        disabled={isDraftBusy || options.length === 0}
-        onClick={() => {
-          onOpenChange(!isOpen);
-        }}
-        onPointerDownCapture={stopComposerEvent}
-        className={cn(
-          'relative inline-flex shrink-0 items-center justify-center text-[var(--beat-text-3)] transition-all duration-200 hover:bg-white/[0.06] hover:text-white disabled:cursor-not-allowed disabled:opacity-60',
-          isRow
-            ? 'h-7 w-7 rounded-lg border border-dashed border-white/[0.12] bg-white/[0.025]'
-            : 'h-8 w-8 rounded-lg'
-        )}
-        aria-label={primaryLabel}
-        aria-expanded={isOpen}
-      >
-        {primaryIntent === 'video' ? (
-          <Video className="size-4" />
-        ) : (
-          <ImagePlus className="size-4" />
-        )}
-        {attachedCount > 0 ? (
-          <span className="absolute -right-1 -top-1 inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-[var(--beat-graph)] px-1 text-[9px] font-bold leading-none text-white">
-            {attachedCount}
-          </span>
-        ) : null}
-        {!isRow && options.length > 1 ? (
-          <ChevronDown
-            className={cn(
-              'pointer-events-none size-3 text-[var(--beatcanvas-ink-faint)] transition-transform duration-200',
-              'absolute bottom-2 right-2',
-              isOpen ? 'rotate-180' : ''
-            )}
-          />
+    <div ref={containerRef} className={cn('shrink-0', isRow && 'min-w-0')}>
+      <div className={cn('relative', isRow && 'flex min-w-0 items-center gap-1')}>
+        {isRow && attachedCount > 0 ? (
+          <div className="flex min-w-0 max-w-[392px] items-center gap-1 overflow-x-auto pr-0.5 [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">
+            {currentReferenceCards.map((card) => (
+              <button
+                key={card.id}
+                type="button"
+                draggable={!isDraftBusy}
+                disabled={isDraftBusy}
+                onClick={() => {
+                  if (card.alias) onInsertReferenceMention(card.alias);
+                }}
+                onDragStart={(event) => {
+                  setDraggedReferenceId(card.id);
+                  event.dataTransfer.effectAllowed = 'move';
+                  event.dataTransfer.setData('text/plain', card.id);
+                }}
+                onDragOver={(event) => {
+                  if (draggedReferenceId && draggedReferenceId !== card.id) {
+                    event.preventDefault();
+                    event.dataTransfer.dropEffect = 'move';
+                  }
+                }}
+                onDrop={(event) => {
+                  event.preventDefault();
+                  const activeCardId =
+                    draggedReferenceId || event.dataTransfer.getData('text/plain');
+                  if (activeCardId && activeCardId !== card.id) {
+                    onReorderCanvasReferences(
+                      activeDraftId,
+                      activeCardId,
+                      card.id
+                    );
+                  }
+                  setDraggedReferenceId(null);
+                }}
+                onDragEnd={() => setDraggedReferenceId(null)}
+                onPointerDownCapture={stopComposerEvent}
+                title={`${card.alias ?? ''} · ${card.name}`}
+                className={cn(
+                  'group/reference inline-flex h-7 shrink-0 items-center gap-1 rounded-lg border bg-white/[0.035] pl-1 pr-1.5 text-[11px] font-semibold text-[var(--beat-text-1)] transition',
+                  draggedReferenceId === card.id
+                    ? 'border-[var(--beat-graph)] opacity-55'
+                    : 'border-white/[0.09] hover:border-white/[0.18] hover:bg-white/[0.07]'
+                )}
+              >
+                <span className="relative inline-flex size-5 shrink-0 overflow-hidden rounded-[5px] bg-black/50">
+                  {card.thumbnailUrl && card.type === 'video' ? (
+                    <video
+                      src={card.thumbnailUrl}
+                      muted
+                      playsInline
+                      preload="metadata"
+                      className="size-full object-cover"
+                    />
+                  ) : card.thumbnailUrl ? (
+                    <img
+                      src={card.thumbnailUrl}
+                      alt=""
+                      draggable={false}
+                      className="size-full object-cover"
+                    />
+                  ) : card.type === 'video' ? (
+                    <Video className="m-auto size-3 text-white/70" />
+                  ) : (
+                    <ImagePlus className="m-auto size-3 text-white/70" />
+                  )}
+                  {card.type === 'video' ? (
+                    <Video className="pointer-events-none absolute bottom-0 right-0 size-2.5 rounded-sm bg-black/65 p-0.5 text-white" />
+                  ) : null}
+                </span>
+                <span className="whitespace-nowrap font-mono tracking-[-0.02em] text-[var(--beat-graph)]">
+                  {card.alias}
+                </span>
+                <GripVertical className="size-3 text-white/20 transition group-hover/reference:text-white/45" />
+              </button>
+            ))}
+          </div>
         ) : null}
-      </button>
 
-      {isOpen ? (
-        <div
+        <button
+          type="button"
+          disabled={isDraftBusy || options.length === 0}
+          onClick={() => {
+            onOpenChange(!isOpen);
+          }}
+          onPointerDownCapture={stopComposerEvent}
           className={cn(
-            composerFloatingPanelClassName,
-            'left-0 w-[min(300px,calc(100vw-48px))]'
+            'relative inline-flex shrink-0 items-center justify-center text-[var(--beat-text-3)] transition-all duration-200 hover:bg-white/[0.06] hover:text-white disabled:cursor-not-allowed disabled:opacity-60',
+            isRow
+              ? 'h-7 w-7 rounded-lg border border-dashed border-white/[0.12] bg-white/[0.025]'
+              : 'h-8 w-8 rounded-lg'
           )}
-          onPointerDownCapture={stopComposerEvent}
+          aria-label={primaryLabel}
+          aria-expanded={isOpen}
         >
-          <div className="max-h-[320px] space-y-2.5 overflow-y-auto">
+          {primaryIntent === 'video' ? (
+            <Video className="size-4" />
+          ) : (
+            <ImagePlus className="size-4" />
+          )}
+          {!isRow && attachedCount > 0 ? (
+            <span className="absolute -right-1 -top-1 inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-[var(--beat-graph)] px-1 text-[9px] font-bold leading-none text-white">
+              {attachedCount}
+            </span>
+          ) : null}
+          {!isRow && options.length > 1 ? (
+            <ChevronDown
+              className={cn(
+                'pointer-events-none size-3 text-[var(--beatcanvas-ink-faint)] transition-transform duration-200',
+                'absolute bottom-2 right-2',
+                isOpen ? 'rotate-180' : ''
+              )}
+            />
+          ) : null}
+        </button>
+
+        {isOpen ? (
+          <div
+            className={cn(
+              composerFloatingPanelClassName,
+              'left-0 w-[min(300px,calc(100vw-48px))]'
+            )}
+            onPointerDownCapture={stopComposerEvent}
+          >
+            <div className="max-h-[320px] space-y-2.5 overflow-y-auto">
             <div className="space-y-0.5">
               {options.map((option) => (
                 <button
@@ -192,8 +281,13 @@ export function BeatCanvasComposerReferencePicker({
                           )}
                         </span>
                       )}
-                      <span className="truncate text-[13px] font-medium">
-                        {card.name}
+                      <span className="min-w-0">
+                        <span className="block font-mono text-[11px] font-semibold text-[var(--beat-graph)]">
+                          {card.alias}
+                        </span>
+                        <span className="block truncate text-[12px] font-medium">
+                          {card.name}
+                        </span>
                       </span>
                     </span>
                     <button
@@ -266,9 +360,10 @@ export function BeatCanvasComposerReferencePicker({
                 </div>
               )}
             </div>
+            </div>
           </div>
-        </div>
-      ) : null}
+        ) : null}
+      </div>
     </div>
   );
 }
diff --git a/src/components/beatcanvas/beatcanvas-composer-shell.test.tsx b/src/components/beatcanvas/beatcanvas-composer-shell.test.tsx
index a08281b..579d446 100644
--- a/src/components/beatcanvas/beatcanvas-composer-shell.test.tsx
+++ b/src/components/beatcanvas/beatcanvas-composer-shell.test.tsx
@@ -75,6 +75,8 @@ const labels = {
   aspectRatioLabel: 'Aspect ratio',
   outputQualityLabel: 'Output quality',
   durationLabel: 'Duration',
+  characterOrientationLabel: 'Character orientation',
+  backgroundSourceLabel: 'Background source',
   languageLabel: 'Language',
   uploadImageLabel: 'Upload image',
   uploadVideoLabel: 'Upload video',
@@ -99,6 +101,10 @@ const labels = {
   tokenPortraitLabel: 'Portrait',
   tokenChineseLabel: 'Chinese',
   tokenEnglishLabel: 'English',
+  tokenImageOrientationLabel: 'Follow image',
+  tokenVideoOrientationLabel: 'Follow video',
+  tokenInputImageLabel: 'Image background',
+  tokenInputVideoLabel: 'Video background',
   queuedStatusLabel: 'Queued',
   generatingStatusLabel: 'Generating',
   readyStatusLabel: 'Ready',
diff --git a/src/components/beatcanvas/beatcanvas-composer-shell.tsx b/src/components/beatcanvas/beatcanvas-composer-shell.tsx
index ce5ab58..7ffd421 100644
--- a/src/components/beatcanvas/beatcanvas-composer-shell.tsx
+++ b/src/components/beatcanvas/beatcanvas-composer-shell.tsx
@@ -3,8 +3,15 @@
 import { Textarea } from '@/components/ui/textarea';
 import { cn } from '@/lib/utils';
 import type { CanvasGenerationCard } from '@/core/beatcanvas/canvas-types';
-import { ArrowUp, Loader2, RotateCw, X } from 'lucide-react';
-import type { ReactNode, RefObject } from 'react';
+import {
+  filterCanvasReferenceMentions,
+  findActiveCanvasReferenceMention,
+  insertCanvasReferenceMention,
+  type ActiveCanvasReferenceMention,
+  type CanvasReferenceMention,
+} from '@/core/beatcanvas/reference-mentions';
+import { ArrowUp, Image, Loader2, RotateCw, Video, X } from 'lucide-react';
+import { useRef, useState, type ReactNode, type RefObject } from 'react';
 
 import {
   stopComposerEvent,
@@ -37,6 +44,7 @@ export function BeatCanvasComposerShell({
   promptPlaceholder,
   presentation,
   promptAccessory,
+  promptReferences = [],
   position,
   takeCount = 0,
 }: {
@@ -56,10 +64,19 @@ export function BeatCanvasComposerShell({
   promptInputValue: string;
   promptPlaceholder: string;
   presentation?: BeatCanvasComposerPresentation | null;
-  promptAccessory?: ReactNode;
+  promptAccessory?:
+    | ReactNode
+    | ((insertReferenceMention: (alias: string) => void) => ReactNode);
+  promptReferences?: Array<
+    CanvasReferenceMention & { thumbnailUrl: string | null }
+  >;
   position?: { left: number; top: number } | null;
   takeCount?: number;
 }) {
+  const promptInputRef = useRef<HTMLTextAreaElement | null>(null);
+  const [activeMention, setActiveMention] =
+    useState<ActiveCanvasReferenceMention | null>(null);
+  const [selectedMentionIndex, setSelectedMentionIndex] = useState(0);
   const hasExistingTakes = takeCount > 0;
   const primaryButtonLabel = isDraftBusy
     ? labels.generatingLabel
@@ -67,6 +84,41 @@ export function BeatCanvasComposerShell({
       ? labels.regenerateLabel
       : labels.generateLabel;
   const isPrimaryDisabled = isDraftBusy || isPromptComposing;
+  const mentionOptions = activeMention
+    ? filterCanvasReferenceMentions({
+        mentions: promptReferences,
+        query: activeMention.query,
+      })
+    : [];
+
+  const selectReferenceMention = (
+    alias: string,
+    mentionOverride?: ActiveCanvasReferenceMention | null
+  ) => {
+    const input = promptInputRef.current;
+    const selectionStart = input?.selectionStart ?? promptInputValue.length;
+    const selectionEnd = input?.selectionEnd ?? selectionStart;
+    const result = insertCanvasReferenceMention({
+      prompt: promptInputValue,
+      alias,
+      selectionStart,
+      selectionEnd,
+      activeMention: mentionOverride ?? activeMention,
+    });
+
+    onPromptChange(result.prompt);
+    setActiveMention(null);
+    setSelectedMentionIndex(0);
+    window.requestAnimationFrame(() => {
+      promptInputRef.current?.focus();
+      promptInputRef.current?.setSelectionRange(result.caret, result.caret);
+    });
+  };
+
+  const renderedPromptAccessory =
+    typeof promptAccessory === 'function'
+      ? promptAccessory((alias) => selectReferenceMention(alias, null))
+      : promptAccessory;
 
   return (
     <section
@@ -92,32 +144,145 @@ export function BeatCanvasComposerShell({
       >
         <div className="flex min-w-0 flex-1 items-start gap-3">
           <div suppressHydrationWarning className="min-w-0 flex-1">
-            {promptAccessory ? (
+            {renderedPromptAccessory ? (
               <div
                 data-composer-reference-row
-                className="mb-1.5 flex min-h-7 items-center pl-2"
+                className="mb-1.5 flex min-h-7 min-w-0 items-center pl-2"
               >
-                {promptAccessory}
+                {renderedPromptAccessory}
               </div>
             ) : null}
-            <Textarea
-              value={promptInputValue}
-              onChange={(event) => onPromptChange(event.target.value)}
-              onCompositionStart={() => {
-                onPromptCompositionChange(true);
-              }}
-              onCompositionEnd={(event) => {
-                if (!activeDraftCard || isDraftBusy) {
-                  return;
-                }
+            <div className="relative">
+              <Textarea
+                ref={promptInputRef}
+                value={promptInputValue}
+                onChange={(event) => {
+                  const nextPrompt = event.target.value;
+                  onPromptChange(nextPrompt);
+                  setActiveMention(
+                    findActiveCanvasReferenceMention({
+                      prompt: nextPrompt,
+                      caret: event.target.selectionStart ?? nextPrompt.length,
+                    })
+                  );
+                  setSelectedMentionIndex(0);
+                }}
+                onClick={(event) => {
+                  setActiveMention(
+                    findActiveCanvasReferenceMention({
+                      prompt: event.currentTarget.value,
+                      caret:
+                        event.currentTarget.selectionStart ??
+                        event.currentTarget.value.length,
+                    })
+                  );
+                }}
+                onKeyDown={(event) => {
+                  if (!activeMention || mentionOptions.length === 0) return;
 
-                onPromptCompositionChange(false);
-                onPromptCommit(event.currentTarget.value);
-              }}
-              placeholder={promptPlaceholder}
-              readOnly={isDraftBusy}
-              className="min-h-[56px] max-h-[180px] resize-none overflow-y-auto border-0 bg-transparent pl-2 pr-0 py-0 text-[14px] font-medium leading-[1.6] shadow-none outline-none placeholder:text-[14px] placeholder:font-normal focus:border-transparent focus:outline-none"
-            />
+                  if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+                    event.preventDefault();
+                    const direction = event.key === 'ArrowDown' ? 1 : -1;
+                    setSelectedMentionIndex((current) =>
+                      (current + direction + mentionOptions.length) %
+                      mentionOptions.length
+                    );
+                    return;
+                  }
+
+                  if (event.key === 'Enter' || event.key === 'Tab') {
+                    event.preventDefault();
+                    const mention = mentionOptions[selectedMentionIndex];
+                    if (mention) {
+                      selectReferenceMention(mention.alias, activeMention);
+                    }
+                    return;
+                  }
+
+                  if (event.key === 'Escape') {
+                    event.preventDefault();
+                    setActiveMention(null);
+                  }
+                }}
+                onBlur={() => {
+                  window.requestAnimationFrame(() => setActiveMention(null));
+                }}
+                onCompositionStart={() => {
+                  onPromptCompositionChange(true);
+                }}
+                onCompositionEnd={(event) => {
+                  if (!activeDraftCard || isDraftBusy) {
+                    return;
+                  }
+
+                  onPromptCompositionChange(false);
+                  onPromptCommit(event.currentTarget.value);
+                }}
+                placeholder={promptPlaceholder}
+                readOnly={isDraftBusy}
+                className="min-h-[56px] max-h-[180px] resize-none overflow-y-auto border-0 bg-transparent pl-2 pr-0 py-0 text-[14px] font-medium leading-[1.6] shadow-none outline-none placeholder:text-[14px] placeholder:font-normal focus:border-transparent focus:outline-none"
+              />
+
+              {activeMention && mentionOptions.length > 0 ? (
+                <div className="beat-pop-in absolute left-2 top-full z-50 mt-1.5 w-[min(340px,calc(100vw-72px))] overflow-hidden rounded-xl border border-white/10 bg-[var(--beat-surface-2)] p-1.5 shadow-[0_22px_54px_rgba(0,0,0,0.58),inset_0_1px_0_rgba(255,255,255,0.04)]">
+                  {mentionOptions.slice(0, 8).map((mention, index) => {
+                    const reference = promptReferences.find(
+                      (item) => item.cardId === mention.cardId
+                    );
+                    return (
+                      <button
+                        key={mention.cardId}
+                        type="button"
+                        onMouseDown={(event) => event.preventDefault()}
+                        onClick={() =>
+                          selectReferenceMention(mention.alias, activeMention)
+                        }
+                        className={cn(
+                          'flex w-full items-center gap-2.5 rounded-lg px-2 py-1.5 text-left transition',
+                          index === selectedMentionIndex
+                            ? 'bg-white/[0.09] text-white'
+                            : 'text-[var(--beat-text-2)] hover:bg-white/[0.06] hover:text-white'
+                        )}
+                      >
+                        <span className="relative inline-flex size-8 shrink-0 overflow-hidden rounded-md bg-black/45">
+                          {reference?.thumbnailUrl && mention.type === 'video' ? (
+                            <video
+                              src={reference.thumbnailUrl}
+                              muted
+                              playsInline
+                              preload="metadata"
+                              className="size-full object-cover"
+                            />
+                          ) : reference?.thumbnailUrl ? (
+                            <img
+                              src={reference.thumbnailUrl}
+                              alt=""
+                              draggable={false}
+                              className="size-full object-cover"
+                            />
+                          ) : mention.type === 'video' ? (
+                            <Video className="m-auto size-3.5" />
+                          ) : (
+                            <Image className="m-auto size-3.5" />
+                          )}
+                        </span>
+                        <span className="min-w-0 flex-1">
+                          <span className="block font-mono text-[11px] font-semibold text-[var(--beat-graph)]">
+                            {mention.alias}
+                          </span>
+                          <span className="block truncate text-[12px] font-medium">
+                            {mention.name}
+                          </span>
+                        </span>
+                        <span className="text-[10px] font-medium uppercase tracking-[0.08em] text-white/30">
+                          {mention.type}
+                        </span>
+                      </button>
+                    );
+                  })}
+                </div>
+              ) : null}
+            </div>
           </div>
 
           <div className="flex shrink-0 items-center gap-2 pt-0.5">
diff --git a/src/components/beatcanvas/beatcanvas-composer-utils.ts b/src/components/beatcanvas/beatcanvas-composer-utils.ts
index 95d8f71..057cf7c 100644
--- a/src/components/beatcanvas/beatcanvas-composer-utils.ts
+++ b/src/components/beatcanvas/beatcanvas-composer-utils.ts
@@ -45,6 +45,10 @@ export const normalizeComposerToken = (
     | 'tokenPortraitLabel'
     | 'tokenChineseLabel'
     | 'tokenEnglishLabel'
+    | 'tokenImageOrientationLabel'
+    | 'tokenVideoOrientationLabel'
+    | 'tokenInputImageLabel'
+    | 'tokenInputVideoLabel'
   >
 ) => {
   switch (value) {
@@ -74,6 +78,14 @@ export const normalizeComposerToken = (
       return labels?.tokenChineseLabel ?? 'Chinese';
     case 'en':
       return labels?.tokenEnglishLabel ?? 'English';
+    case 'image':
+      return labels?.tokenImageOrientationLabel ?? 'Image orientation';
+    case 'video':
+      return labels?.tokenVideoOrientationLabel ?? 'Video orientation';
+    case 'input_image':
+      return labels?.tokenInputImageLabel ?? 'Image background';
+    case 'input_video':
+      return labels?.tokenInputVideoLabel ?? 'Video background';
     default:
       if (/^\d+(?:k|p)$/i.test(value)) {
         return value.toUpperCase();
diff --git a/src/components/beatcanvas/beatcanvas-front-layer-context.tsx b/src/components/beatcanvas/beatcanvas-front-layer-context.tsx
index c2da688..b5f9311 100644
--- a/src/components/beatcanvas/beatcanvas-front-layer-context.tsx
+++ b/src/components/beatcanvas/beatcanvas-front-layer-context.tsx
@@ -1,6 +1,8 @@
 import type { EffectMetadata } from '@/core/effects/client-api';
 import type {
   WorkspaceAspectRatio,
+  WorkspaceBackgroundSource,
+  WorkspaceCharacterOrientation,
   WorkspaceDuration,
   WorkspaceLanguage,
   WorkspaceModelMode,
@@ -58,6 +60,8 @@ type CanvasLabels = {
   aspectRatioLabel: string;
   outputQualityLabel: string;
   durationLabel: string;
+  characterOrientationLabel: string;
+  backgroundSourceLabel: string;
   languageLabel: string;
   uploadImageLabel: string;
   uploadVideoLabel: string;
@@ -86,6 +90,10 @@ type CanvasLabels = {
   tokenPortraitLabel: string;
   tokenChineseLabel: string;
   tokenEnglishLabel: string;
+  tokenImageOrientationLabel: string;
+  tokenVideoOrientationLabel: string;
+  tokenInputImageLabel: string;
+  tokenInputVideoLabel: string;
   queuedStatusLabel: string;
   generatingStatusLabel: string;
   readyStatusLabel: string;
@@ -155,6 +163,14 @@ export type BeatCanvasFrontLayerValue = {
   ) => void;
   onDraftQualityChange: (draftId: string, quality: WorkspaceQualityOption) => void;
   onDraftDurationChange: (draftId: string, duration: WorkspaceDuration) => void;
+  onDraftCharacterOrientationChange: (
+    draftId: string,
+    characterOrientation: WorkspaceCharacterOrientation
+  ) => void;
+  onDraftBackgroundSourceChange: (
+    draftId: string,
+    backgroundSource: WorkspaceBackgroundSource
+  ) => void;
   onDraftLanguageChange: (draftId: string, language: WorkspaceLanguage) => void;
   onDraftModeChange: (draftId: string, mode: WorkspaceModelMode) => void;
   onDraftVariantChange: (
@@ -167,6 +183,11 @@ export type BeatCanvasFrontLayerValue = {
   ) => void;
   onAttachCanvasReference: (draftId: string, sourceCardId: string) => void;
   onDetachCanvasReference: (draftId: string, sourceCardId: string) => void;
+  onReorderCanvasReferences: (
+    draftId: string,
+    activeCardId: string,
+    overCardId: string
+  ) => void;
   onPinGenerationOutput: (draftId: string, outputId: string) => void;
   onGenerateDraft: (draftId: string) => void;
 };
diff --git a/src/components/beatcanvas/beatcanvas-front-layer.tsx b/src/components/beatcanvas/beatcanvas-front-layer.tsx
index 5b24717..25357d6 100644
--- a/src/components/beatcanvas/beatcanvas-front-layer.tsx
+++ b/src/components/beatcanvas/beatcanvas-front-layer.tsx
@@ -12,6 +12,7 @@ import {
   isDraftBusyStatus,
   listCompatibleCanvasReferenceCards,
 } from '@/core/beatcanvas/composer';
+import { buildCanvasReferenceMentions } from '@/core/beatcanvas/reference-mentions';
 
 import {
   listGenerationOutputsForDraft,
@@ -102,6 +103,8 @@ export function BeatCanvasFrontLayer() {
     onCanvasShapeIdsChange,
     onSelectedShapeIdsChange,
     onDraftAspectRatioChange,
+    onDraftBackgroundSourceChange,
+    onDraftCharacterOrientationChange,
     onDraftDurationChange,
     onDraftLanguageChange,
     onDraftModeChange,
@@ -114,6 +117,7 @@ export function BeatCanvasFrontLayer() {
     onOpenReferencePicker,
     onAttachCanvasReference,
     onDetachCanvasReference,
+    onReorderCanvasReferences,
     onPinGenerationOutput,
     onGenerateDraft,
     onSelectedCanvasCardIdsChange,
@@ -354,6 +358,10 @@ export function BeatCanvasFrontLayer() {
   const selectedLanguageOptions = selectedModel?.supportedLanguages ?? [];
   const selectedAspectRatioOptions = selectedModel?.supportedAspectRatios ?? [];
   const selectedOutputQualities = selectedModel?.supportedOutputQualities ?? [];
+  const selectedCharacterOrientationOptions =
+    selectedModel?.characterOrientationOptions ?? [];
+  const selectedBackgroundSourceOptions =
+    selectedModel?.backgroundSourceOptions ?? [];
   const isDraftBusy = activeDraftCard
     ? isDraftBusyStatus(activeDraftCard.status)
     : false;
@@ -381,6 +389,22 @@ export function BeatCanvasFrontLayer() {
     if (selectedDurationOptions.length > 0) {
       tokens.push(activeDraftCard.duration);
     }
+    if (
+      selectedCharacterOrientationOptions.length > 0 &&
+      activeDraftCard.characterOrientation
+    ) {
+      tokens.push(
+        normalizeComposerToken(activeDraftCard.characterOrientation, labels)
+      );
+    }
+    if (
+      selectedBackgroundSourceOptions.length > 0 &&
+      activeDraftCard.backgroundSource
+    ) {
+      tokens.push(
+        normalizeComposerToken(activeDraftCard.backgroundSource, labels)
+      );
+    }
     if (selectedLanguageOptions.length > 0 && activeDraftCard.language) {
       tokens.push(
         normalizeComposerToken(activeDraftCard.language, labels)
@@ -404,6 +428,8 @@ export function BeatCanvasFrontLayer() {
   }, [
     labels,
     selectedAspectRatioOptions,
+    selectedBackgroundSourceOptions,
+    selectedCharacterOrientationOptions,
     selectedDurationOptions,
     selectedLanguageOptions,
     selectedModeOptions,
@@ -459,16 +485,31 @@ export function BeatCanvasFrontLayer() {
       return [];
     }
 
-    return activeDraftCard.referenceCardIds
-      .map((cardId) => cards[cardId])
-      .filter((card): card is NonNullable<typeof card> => Boolean(card))
-      .map((card) => ({
-        id: card.id,
-        name: card.name,
-        type: card.type,
-        thumbnailUrl: card.url,
-      }));
+    const mentions = buildCanvasReferenceMentions({
+      referenceCardIds: activeDraftCard.referenceCardIds,
+      cards,
+    });
+
+    return mentions.map((mention) => ({
+      id: mention.cardId,
+      name: mention.name,
+      type: mention.type,
+      alias: mention.alias,
+      thumbnailUrl: cards[mention.cardId]?.url ?? null,
+    }));
   }, [activeDraftCard, cards]);
+  const promptReferences = useMemo(
+    () =>
+      currentReferenceCards.map((card) => ({
+        cardId: card.id,
+        type: card.type,
+        index: Number.parseInt(card.alias.replace(/\D/g, ''), 10),
+        alias: card.alias,
+        name: card.name,
+        thumbnailUrl: card.thumbnailUrl,
+      })),
+    [currentReferenceCards]
+  );
   const canvasReferenceCards = useMemo(() => {
     if (!activeDraftCard) {
       return [];
@@ -789,10 +830,11 @@ export function BeatCanvasFrontLayer() {
           promptCharacterLimit={promptCharacterLimit}
           promptInputValue={promptInputValue}
           promptPlaceholder={activePromptPlaceholder}
+          promptReferences={promptReferences}
           presentation={composerPresentation}
           position={activeDraftComposerPosition}
           takeCount={generationOutputs.length}
-          promptAccessory={
+          promptAccessory={(insertReferenceMention) => (
             <>
               <BeatCanvasComposerReferencePicker
                 activeDraftId={activeDraftCard.id}
@@ -811,6 +853,8 @@ export function BeatCanvasFrontLayer() {
                   setIsReferencePickerOpen(nextOpen);
                 }}
                 onOpenReferencePicker={onOpenReferencePicker}
+                onInsertReferenceMention={insertReferenceMention}
+                onReorderCanvasReferences={onReorderCanvasReferences}
                 onRemoveCanvasReference={onDetachCanvasReference}
                 options={referencePickerOptions}
                 primaryIntent={primaryReferenceIntent}
@@ -834,7 +878,7 @@ export function BeatCanvasFrontLayer() {
                 pinnedOutputId={pinnedOutputId}
               />
             </>
-          }
+          )}
         >
           <div className="flex min-w-0 flex-1 flex-nowrap items-center gap-2">
             <BeatCanvasComposerTypePicker
@@ -884,6 +928,10 @@ export function BeatCanvasFrontLayer() {
                   isOpen={isParameterPopoverOpen}
                   labels={labels}
                   onDraftAspectRatioChange={onDraftAspectRatioChange}
+                  onDraftBackgroundSourceChange={onDraftBackgroundSourceChange}
+                  onDraftCharacterOrientationChange={
+                    onDraftCharacterOrientationChange
+                  }
                   onDraftDurationChange={onDraftDurationChange}
                   onDraftLanguageChange={onDraftLanguageChange}
                   onDraftModeChange={onDraftModeChange}
@@ -899,6 +947,12 @@ export function BeatCanvasFrontLayer() {
                   }}
                   parameterSummaryLabel={parameterSummaryLabel}
                   selectedAspectRatioOptions={selectedAspectRatioOptions}
+                  selectedBackgroundSourceOptions={
+                    selectedBackgroundSourceOptions
+                  }
+                  selectedCharacterOrientationOptions={
+                    selectedCharacterOrientationOptions
+                  }
                   selectedDurationOptions={selectedDurationOptions}
                   selectedLanguageOptions={selectedLanguageOptions}
                   selectedModeOptions={selectedModeOptions}
diff --git a/src/components/beatcanvas/beatcanvas-shell.tsx b/src/components/beatcanvas/beatcanvas-shell.tsx
index d20e772..550ab0c 100644
--- a/src/components/beatcanvas/beatcanvas-shell.tsx
+++ b/src/components/beatcanvas/beatcanvas-shell.tsx
@@ -25,6 +25,11 @@ import {
   shouldIgnoreCanvasModifierShortcut,
   shouldIgnoreCanvasShortcut,
 } from '@/core/beatcanvas/composer';
+import {
+  buildCanvasReferenceMentions,
+  moveCanvasReferenceCardId,
+  rewriteCanvasReferenceAliases,
+} from '@/core/beatcanvas/reference-mentions';
 import { getSelectableModel } from '@/core/beatcanvas/generation-controller';
 import { useQueryClient } from '@tanstack/react-query';
 import { useTranslations } from '@/core/workspace-lib/shims/next-intl';
@@ -294,6 +299,8 @@ export function BeatCanvasShell({
   const {
     handleCreatePromptDraft,
     handleDraftAspectRatioChange,
+    handleDraftBackgroundSourceChange,
+    handleDraftCharacterOrientationChange,
     handleDraftDurationChange,
     handleDraftLanguageChange,
     handleDraftModeChange,
@@ -445,16 +452,70 @@ export function BeatCanvasShell({
       removeConnectorBetweenCards(sourceCardId, draftId, {
         recordHistory: true,
       });
-      updateDraftCard(draftId, {
-        referenceCardIds: removeReferenceCardId(
-          draftCard.referenceCardIds,
+      updateDraftCard(draftId, (current) => {
+        const nextReferenceCardIds = removeReferenceCardId(
+          current.referenceCardIds,
           sourceCardId
-        ),
+        );
+        const previousMentions = buildCanvasReferenceMentions({
+          referenceCardIds: current.referenceCardIds,
+          cards: canvasCardsRef.current,
+        });
+        const nextMentions = buildCanvasReferenceMentions({
+          referenceCardIds: nextReferenceCardIds,
+          cards: canvasCardsRef.current,
+        });
+
+        return {
+          ...current,
+          prompt: rewriteCanvasReferenceAliases({
+            prompt: current.prompt,
+            previousMentions,
+            nextMentions,
+          }),
+          referenceCardIds: nextReferenceCardIds,
+        };
       });
     },
     [canvasCardsRef, removeConnectorBetweenCards, updateDraftCard]
   );
 
+  const handleReorderCanvasReferences = useCallback(
+    (draftId: string, activeCardId: string, overCardId: string) => {
+      const draftCard = canvasCardsRef.current[draftId];
+      if (draftCard?.kind !== 'generation') return;
+
+      const nextReferenceCardIds = moveCanvasReferenceCardId({
+        referenceCardIds: draftCard.referenceCardIds,
+        activeCardId,
+        overCardId,
+      });
+      if (nextReferenceCardIds === draftCard.referenceCardIds) return;
+
+      const previousMentions = buildCanvasReferenceMentions({
+        referenceCardIds: draftCard.referenceCardIds,
+        cards: canvasCardsRef.current,
+      });
+      const nextMentions = buildCanvasReferenceMentions({
+        referenceCardIds: nextReferenceCardIds,
+        cards: canvasCardsRef.current,
+      });
+
+      recordCanvasHistory();
+      updateDraftCard(draftId, {
+        prompt: rewriteCanvasReferenceAliases({
+          prompt: draftCard.prompt,
+          previousMentions,
+          nextMentions,
+        }),
+        referenceCardIds: nextReferenceCardIds,
+        status: 'idle',
+        error: null,
+      });
+    },
+    [canvasCardsRef, recordCanvasHistory, updateDraftCard]
+  );
+
   const handleReferenceEdgesRemoved = useCallback(
     (edges: Array<{ source: string; target: string }>) => {
       for (const edge of edges) {
@@ -463,11 +524,26 @@ export function BeatCanvasShell({
           continue;
         }
 
-        updateDraftCard(draftCard.id, {
-          referenceCardIds: removeReferenceCardId(
-            draftCard.referenceCardIds,
+        updateDraftCard(draftCard.id, (current) => {
+          const nextReferenceCardIds = removeReferenceCardId(
+            current.referenceCardIds,
             edge.source
-          ),
+          );
+          return {
+            ...current,
+            prompt: rewriteCanvasReferenceAliases({
+              prompt: current.prompt,
+              previousMentions: buildCanvasReferenceMentions({
+                referenceCardIds: current.referenceCardIds,
+                cards: canvasCardsRef.current,
+              }),
+              nextMentions: buildCanvasReferenceMentions({
+                referenceCardIds: nextReferenceCardIds,
+                cards: canvasCardsRef.current,
+              }),
+            }),
+            referenceCardIds: nextReferenceCardIds,
+          };
         });
       }
     },
@@ -540,6 +616,10 @@ export function BeatCanvasShell({
       aspectRatioLabel: studioT('single.labels.aspectRatio'),
       outputQualityLabel: studioT('single.labels.outputQuality'),
       durationLabel: studioT('single.labels.duration'),
+      characterOrientationLabel: studioT(
+        'canvas.composer.characterOrientation'
+      ),
+      backgroundSourceLabel: studioT('canvas.composer.backgroundSource'),
       languageLabel: studioT('canvas.composer.language'),
       uploadImageLabel: studioT('actions.uploadImage'),
       uploadVideoLabel: studioT('actions.uploadVideo'),
@@ -568,6 +648,14 @@ export function BeatCanvasShell({
       tokenPortraitLabel: studioT('canvas.composer.tokens.portrait'),
       tokenChineseLabel: studioT('canvas.composer.tokens.chinese'),
       tokenEnglishLabel: studioT('canvas.composer.tokens.english'),
+      tokenImageOrientationLabel: studioT(
+        'canvas.composer.tokens.imageOrientation'
+      ),
+      tokenVideoOrientationLabel: studioT(
+        'canvas.composer.tokens.videoOrientation'
+      ),
+      tokenInputImageLabel: studioT('canvas.composer.tokens.inputImage'),
+      tokenInputVideoLabel: studioT('canvas.composer.tokens.inputVideo'),
       queuedStatusLabel: studioT('canvas.composer.status.queued'),
       generatingStatusLabel: studioT('canvas.composer.status.generating'),
       readyStatusLabel: studioT('canvas.composer.status.ready'),
@@ -612,6 +700,9 @@ export function BeatCanvasShell({
       onDraftTaskTypeChange: handleDraftTaskTypeChange,
       onDraftModelChange: handleDraftModelChange,
       onDraftAspectRatioChange: handleDraftAspectRatioChange,
+      onDraftBackgroundSourceChange: handleDraftBackgroundSourceChange,
+      onDraftCharacterOrientationChange:
+        handleDraftCharacterOrientationChange,
       onDraftOutputQualityChange: handleDraftOutputQualityChange,
       onDraftModeChange: handleDraftModeChange,
       onDraftVariantChange: handleDraftVariantChange,
@@ -622,6 +713,7 @@ export function BeatCanvasShell({
         openUploadPicker({ draftId, intent, mode: 'reference' }),
       onAttachCanvasReference: handleAttachCanvasReference,
       onDetachCanvasReference: handleDetachCanvasReference,
+      onReorderCanvasReferences: handleReorderCanvasReferences,
       onPinGenerationOutput: handlePinGenerationOutput,
       onGenerateDraft: handleGenerateDraft,
     }),
@@ -633,6 +725,8 @@ export function BeatCanvasShell({
       canvasCopy,
       handleCanvasShapeIdsChange,
       handleDraftAspectRatioChange,
+      handleDraftBackgroundSourceChange,
+      handleDraftCharacterOrientationChange,
       handleDraftDurationChange,
       handleDraftLanguageChange,
       handleDraftModeChange,
@@ -648,6 +742,7 @@ export function BeatCanvasShell({
       handleCreateGenerationFromConnector,
       handleCreateGenerationAtPoint,
       handleDetachCanvasReference,
+      handleReorderCanvasReferences,
       handlePinGenerationOutput,
       handleSelectedShapeIdsChange,
       handleSelectedCanvasCardIdsChange,
diff --git a/src/components/beatcanvas/use-beatcanvas-draft-actions.ts b/src/components/beatcanvas/use-beatcanvas-draft-actions.ts
index 8969033..ac88d0a 100644
--- a/src/components/beatcanvas/use-beatcanvas-draft-actions.ts
+++ b/src/components/beatcanvas/use-beatcanvas-draft-actions.ts
@@ -2,6 +2,8 @@
 
 import type {
   WorkspaceAspectRatio,
+  WorkspaceBackgroundSource,
+  WorkspaceCharacterOrientation,
   WorkspaceDuration,
   WorkspaceLanguage,
   WorkspaceModelMode,
@@ -134,6 +136,8 @@ export function useBeatCanvasDraftActions({
         mode: defaults.mode,
         variant: defaults.variant,
         quality: defaults.quality,
+        characterOrientation: defaults.characterOrientation,
+        backgroundSource: defaults.backgroundSource,
         status: 'idle',
         error: null,
       }));
@@ -272,9 +276,30 @@ export function useBeatCanvasDraftActions({
     [updateEditableDraft]
   );
 
+  const handleDraftCharacterOrientationChange = useCallback(
+    (draftId: string, characterOrientation: WorkspaceCharacterOrientation) =>
+      updateEditableDraft(
+        draftId,
+        (value: WorkspaceCharacterOrientation) => ({
+          characterOrientation: value,
+        })
+      )(characterOrientation),
+    [updateEditableDraft]
+  );
+
+  const handleDraftBackgroundSourceChange = useCallback(
+    (draftId: string, backgroundSource: WorkspaceBackgroundSource) =>
+      updateEditableDraft(draftId, (value: WorkspaceBackgroundSource) => ({
+        backgroundSource: value,
+      }))(backgroundSource),
+    [updateEditableDraft]
+  );
+
   return {
     handleCreatePromptDraft,
+    handleDraftBackgroundSourceChange,
     handleDraftAspectRatioChange,
+    handleDraftCharacterOrientationChange,
     handleDraftDurationChange,
     handleDraftLanguageChange,
     handleDraftModeChange,
diff --git a/src/components/beatcanvas/use-beatcanvas-react-flow-adapter.ts b/src/components/beatcanvas/use-beatcanvas-react-flow-adapter.ts
index 07dfb0b..aa4cb1b 100644
--- a/src/components/beatcanvas/use-beatcanvas-react-flow-adapter.ts
+++ b/src/components/beatcanvas/use-beatcanvas-react-flow-adapter.ts
@@ -975,6 +975,12 @@ export function useBeatCanvasReactFlowAdapter({
           mode: draftCard.mode,
           variant: draftCard.variant,
           quality: draftCard.quality,
+          ...(draftCard.characterOrientation
+            ? { characterOrientation: draftCard.characterOrientation }
+            : {}),
+          ...(draftCard.backgroundSource
+            ? { backgroundSource: draftCard.backgroundSource }
+            : {}),
           capturedAt: new Date().toISOString(),
         },
       };
@@ -1114,6 +1120,12 @@ export function useBeatCanvasReactFlowAdapter({
         mode: defaults.mode,
         variant: defaults.variant,
         quality: defaults.quality,
+        ...(defaults.characterOrientation
+          ? { characterOrientation: defaults.characterOrientation }
+          : {}),
+        ...(defaults.backgroundSource
+          ? { backgroundSource: defaults.backgroundSource }
+          : {}),
         sourceGenerationId: null,
       };
       const size = frame
diff --git a/src/components/pricing/pricing-catalog.json b/src/components/pricing/pricing-catalog.json
index 463f46c..a59109a 100644
--- a/src/components/pricing/pricing-catalog.json
+++ b/src/components/pricing/pricing-catalog.json
@@ -80,6 +80,22 @@
         { "id": "kling-3-pro-no-audio", "spec": "5 sec · 1080p Pro · no audio", "specZh": "5 秒 · 1080p Pro · 无音频", "beatapi": 0.65, "competitor": 1.12, "higgsfieldCredits": 10 }
       ]
     },
+    {
+      "model": "Kling 2.6 Motion Control",
+      "category": "video",
+      "specs": [
+        { "id": "kling-2.6-motion-control-720p", "spec": "5 sec · 720p", "specZh": "5 秒 · 720p", "beatapi": 0.3, "competitor": 0.35 },
+        { "id": "kling-2.6-motion-control-1080p", "spec": "5 sec · 1080p", "specZh": "5 秒 · 1080p", "beatapi": 0.5, "competitor": 0.56 }
+      ]
+    },
+    {
+      "model": "Kling 3.0 Motion Control",
+      "category": "video",
+      "specs": [
+        { "id": "kling-3-motion-control-720p", "spec": "5 sec · 720p", "specZh": "5 秒 · 720p", "beatapi": 0.55, "competitor": 0.63 },
+        { "id": "kling-3-motion-control-1080p", "spec": "5 sec · 1080p", "specZh": "5 秒 · 1080p", "beatapi": 0.7, "competitor": 0.84 }
+      ]
+    },
     {
       "model": "Nano Banana",
       "category": "image",
diff --git a/src/components/pricing/pricing-comparison-data.test.ts b/src/components/pricing/pricing-comparison-data.test.ts
index 31dd103..94f4b7c 100644
--- a/src/components/pricing/pricing-comparison-data.test.ts
+++ b/src/components/pricing/pricing-comparison-data.test.ts
@@ -33,8 +33,8 @@ test('catalog keeps one card per model and groups the Seedance family together',
 });
 
 test('pricing filters count selectable model families rather than variant cards', () => {
-  assert.equal(countPricingModelFamilies(), 9);
-  assert.equal(countPricingModelFamilies('video'), 5);
+  assert.equal(countPricingModelFamilies(), 11);
+  assert.equal(countPricingModelFamilies('video'), 7);
   assert.equal(countPricingModelFamilies('image'), 4);
 });
 
@@ -71,9 +71,40 @@ test('Higgsfield fills matched video and image specs from the live generate UI',
   assert.ok(withHiggsfield.length >= 20);
 });
 
+test('Kling motion control cards match the official BeatAPI list prices', () => {
+  const kling26 = comparisonGroups.find(
+    (group) => group.model === 'Kling 2.6 Motion Control'
+  );
+  const kling3mc = comparisonGroups.find(
+    (group) => group.model === 'Kling 3.0 Motion Control'
+  );
+  assert.ok(kling26);
+  assert.ok(kling3mc);
+  assert.equal(
+    kling26.specs.find((spec) => spec.id === 'kling-2.6-motion-control-720p')
+      ?.beatapi,
+    0.3
+  );
+  assert.equal(
+    kling26.specs.find((spec) => spec.id === 'kling-2.6-motion-control-1080p')
+      ?.beatapi,
+    0.5
+  );
+  assert.equal(
+    kling3mc.specs.find((spec) => spec.id === 'kling-3-motion-control-720p')
+      ?.beatapi,
+    0.55
+  );
+  assert.equal(
+    kling3mc.specs.find((spec) => spec.id === 'kling-3-motion-control-1080p')
+      ?.beatapi,
+    0.7
+  );
+});
+
 test('headline savings match the official BeatAPI comparison', () => {
   assert.equal(maxSavingsPercent(), 81);
-  assert.equal(avgSavingsPercent(), 46);
+  assert.equal(avgSavingsPercent(), 44);
   assert.ok(maxHiggsfieldSavingsPercent() >= 80);
   const gpt1k = comparisonGroups
     .flatMap((group) => group.specs)
diff --git a/src/core/adapters/beatapi-adapter.test.ts b/src/core/adapters/beatapi-adapter.test.ts
index e5973eb..9036bd7 100644
--- a/src/core/adapters/beatapi-adapter.test.ts
+++ b/src/core/adapters/beatapi-adapter.test.ts
@@ -64,6 +64,25 @@ test('maps a canvas video request to BeatAPI video tasks', () => {
   );
 });
 
+test('keeps multiple @Video references in BeatAPI array order', () => {
+  const request = buildBeatApiTaskRequest({
+    effectType: 1,
+    model: 'seedance-2',
+    input: {
+      prompt: 'Use @Video1 for motion and @Video2 for camera movement',
+      video_urls: [
+        'https://example.com/motion.mp4',
+        'https://example.com/camera.mp4',
+      ],
+    },
+  });
+
+  assert.deepEqual(request.body.reference_videos, [
+    'https://example.com/motion.mp4',
+    'https://example.com/camera.mp4',
+  ]);
+});
+
 test('passes image references to every BeatAPI image model', () => {
   const request = buildBeatApiTaskRequest({
     effectType: 2,
@@ -114,6 +133,102 @@ test('maps MiniMax and Kling quality values to official BeatAPI resolutions', ()
   );
 });
 
+test('maps Kling 2.6 and 3.0 Motion Control to the dedicated BeatAPI contract', () => {
+  assert.deepEqual(
+    buildBeatApiTaskRequest({
+      effectType: 1,
+      model: 'kling-2.6-motion-control',
+      input: {
+        prompt: 'Follow the dance motion precisely',
+        image_urls: ['https://media.beatapi.io/inputs/character.png'],
+        video_urls: ['https://media.beatapi.io/inputs/motion.mp4'],
+        wmOutputQuality: '1080p',
+        sourceVideoDurationSeconds: 15,
+        characterOrientation: 'video',
+      },
+    }),
+    {
+      path: '/v1/videos/tasks',
+      body: {
+        model: 'kling-2.6-motion-control',
+        prompt: 'Follow the dance motion precisely',
+        images: ['https://media.beatapi.io/inputs/character.png'],
+        reference_videos: ['https://media.beatapi.io/inputs/motion.mp4'],
+        resolution: '1080p',
+        character_orientation: 'video',
+      },
+    }
+  );
+
+  const kling3 = buildBeatApiTaskRequest({
+    effectType: 1,
+    model: 'kling-3-motion-control',
+    input: {
+      prompt: 'Keep the character identity stable',
+      image_urls: ['https://media.beatapi.io/inputs/character.png'],
+      video_urls: ['https://media.beatapi.io/inputs/motion.mov'],
+      wmOutputQuality: '720p',
+      sourceVideoDurationSeconds: 8,
+      characterOrientation: 'image',
+      backgroundSource: 'input_image',
+    },
+  });
+
+  assert.deepEqual(kling3.body, {
+    model: 'kling-3-motion-control',
+    prompt: 'Keep the character identity stable',
+    images: ['https://media.beatapi.io/inputs/character.png'],
+    reference_videos: ['https://media.beatapi.io/inputs/motion.mov'],
+    resolution: '720p',
+    character_orientation: 'image',
+    background_source: 'input_image',
+  });
+});
+
+test('validates Motion Control media counts and orientation duration', () => {
+  assert.throws(
+    () =>
+      buildBeatApiTaskRequest({
+        effectType: 1,
+        model: 'kling-2.6-motion-control',
+        input: {
+          prompt: 'Dance',
+          image_urls: [],
+          video_urls: ['https://media.beatapi.io/inputs/motion.mp4'],
+        },
+      }),
+    /exactly one image/
+  );
+  assert.throws(
+    () =>
+      buildBeatApiTaskRequest({
+        effectType: 1,
+        model: 'kling-3-motion-control',
+        input: {
+          prompt: 'Dance',
+          image_urls: ['https://media.beatapi.io/inputs/character.png'],
+          video_urls: ['https://media.beatapi.io/inputs/motion.mp4'],
+          sourceVideoDurationSeconds: 11,
+          characterOrientation: 'image',
+        },
+      }),
+    /up to 10 seconds/
+  );
+  assert.throws(
+    () =>
+      buildBeatApiTaskRequest({
+        effectType: 1,
+        model: 'kling-3-motion-control',
+        input: {
+          prompt: 'Dance',
+          image_urls: ['https://example.com/character.png'],
+          video_urls: ['https://example.com/motion.mp4'],
+        },
+      }),
+    /connected BeatAPI account/
+  );
+});
+
 test('rejects models outside the public BeatAPI media catalog', () => {
   assert.throws(
     () =>
diff --git a/src/core/adapters/beatapi-adapter.ts b/src/core/adapters/beatapi-adapter.ts
index 36357c2..14154d8 100644
--- a/src/core/adapters/beatapi-adapter.ts
+++ b/src/core/adapters/beatapi-adapter.ts
@@ -18,6 +18,8 @@ const VIDEO_MODELS = new Set([
   'veo-3.1',
   'seedance-2.5',
   'kling-3',
+  'kling-2.6-motion-control',
+  'kling-3-motion-control',
 ]);
 
 const BEATAPI_REQUEST_TIMEOUT_MS = 30_000;
@@ -33,6 +35,9 @@ const inputSchema = z.object({
   image_url: z.string().url().optional(),
   video_urls: z.array(z.string().url()).optional(),
   audio_urls: z.array(z.string().url()).optional(),
+  sourceVideoDurationSeconds: z.number().positive().optional(),
+  characterOrientation: z.enum(['image', 'video']).optional(),
+  backgroundSource: z.enum(['input_image', 'input_video']).optional(),
 });
 
 type BeatApiMedia = {
@@ -91,6 +96,11 @@ const mapKlingResolution = (value: string | undefined) => {
   return 'std';
 };
 
+const mapMotionControlResolution = (value: string | undefined) =>
+  value?.toLowerCase() === '1080p' || value?.toLowerCase() === 'pro'
+    ? '1080p'
+    : '720p';
+
 export const buildBeatApiTaskRequest = ({
   effectType,
   model,
@@ -128,6 +138,57 @@ export const buildBeatApiTaskRequest = ({
     throw new Error(`Unsupported BeatAPI video model: ${model}`);
   }
 
+  if (
+    model === 'kling-2.6-motion-control' ||
+    model === 'kling-3-motion-control'
+  ) {
+    if (images.length !== 1) {
+      throw new Error('Kling Motion Control requires exactly one image');
+    }
+    if (input.video_urls?.length !== 1) {
+      throw new Error('Kling Motion Control requires exactly one motion video');
+    }
+    if (
+      !isOfficialBeatApiMediaUrl(images[0]) ||
+      !isOfficialBeatApiMediaUrl(input.video_urls[0])
+    ) {
+      throw new Error(
+        'Kling Motion Control inputs must be uploaded through the connected BeatAPI account'
+      );
+    }
+    if (
+      input.sourceVideoDurationSeconds !== undefined &&
+      (input.sourceVideoDurationSeconds < 3 ||
+        input.sourceVideoDurationSeconds > 30)
+    ) {
+      throw new Error('Kling Motion Control video must be between 3 and 30 seconds');
+    }
+    const characterOrientation = input.characterOrientation ?? 'video';
+    if (
+      characterOrientation === 'image' &&
+      (input.sourceVideoDurationSeconds ?? 0) > 10
+    ) {
+      throw new Error(
+        'Image orientation supports motion videos up to 10 seconds'
+      );
+    }
+
+    return {
+      path: '/v1/videos/tasks',
+      body: {
+        model,
+        prompt,
+        images,
+        reference_videos: input.video_urls,
+        resolution: mapMotionControlResolution(input.wmOutputQuality),
+        character_orientation: characterOrientation,
+        ...(model === 'kling-3-motion-control'
+          ? { background_source: input.backgroundSource ?? 'input_video' }
+          : {}),
+      },
+    };
+  }
+
   const duration = parseDuration(input.wmDuration);
   const body: Record<string, unknown> = {
     model,
diff --git a/src/core/beatcanvas/canvas-types.ts b/src/core/beatcanvas/canvas-types.ts
index 3d22555..0475a44 100644
--- a/src/core/beatcanvas/canvas-types.ts
+++ b/src/core/beatcanvas/canvas-types.ts
@@ -1,5 +1,7 @@
 import type {
   WorkspaceAspectRatio,
+  WorkspaceBackgroundSource,
+  WorkspaceCharacterOrientation,
   WorkspaceDuration,
   WorkspaceLanguage,
   WorkspaceModelMode,
@@ -37,6 +39,8 @@ export type CanvasCard = {
   mode: WorkspaceModelMode;
   variant: WorkspaceModelVariant;
   quality: WorkspaceQualityOption;
+  characterOrientation?: WorkspaceCharacterOrientation;
+  backgroundSource?: WorkspaceBackgroundSource;
   sourceGenerationId: string | null;
   sourceConfigCardId?: string | null;
   generationRunId?: string | null;
@@ -59,6 +63,8 @@ export type CanvasGenerationSnapshot = Pick<
   | 'mode'
   | 'variant'
   | 'quality'
+  | 'characterOrientation'
+  | 'backgroundSource'
 > & {
   capturedAt: string;
 };
diff --git a/src/core/beatcanvas/canvas-workflows.ts b/src/core/beatcanvas/canvas-workflows.ts
index b978911..a91cffd 100644
--- a/src/core/beatcanvas/canvas-workflows.ts
+++ b/src/core/beatcanvas/canvas-workflows.ts
@@ -53,12 +53,12 @@ export const resolveReferencePayload = ({
   if (taskType === 'video') {
     return {
       imageUrls,
-      videoUrl: videoCards[0]?.url ?? null,
+      videoUrls: videoCards.map((card) => card.url),
     };
   }
 
   return {
     imageUrls,
-    videoUrl: null,
+    videoUrls: [],
   };
 };
diff --git a/src/core/beatcanvas/composer-references.test.ts b/src/core/beatcanvas/composer-references.test.ts
index bd0ff6b..0089120 100644
--- a/src/core/beatcanvas/composer-references.test.ts
+++ b/src/core/beatcanvas/composer-references.test.ts
@@ -10,6 +10,7 @@ import {
   removeReferenceCardId,
   shouldIgnoreCanvasModifierShortcut,
 } from './composer';
+import { resolveReferencePayload } from './canvas-workflows';
 
 const makeModel = (
   overrides: Partial<WorkspaceModelOption> = {}
@@ -70,6 +71,36 @@ test('keeps image references available before model-specific limits are configur
   );
 });
 
+test('Motion Control stops offering references after one image and one video', () => {
+  const draft = {
+    ...makeDraft(),
+    modelId: 'kling-3-motion-control',
+    referenceCardIds: ['image-1', 'video-1'],
+  };
+  const cards = {
+    'image-1': makeCard({ id: 'image-1', type: 'image' }),
+    'video-1': makeCard({
+      id: 'video-1',
+      type: 'video',
+      url: 'https://example.com/motion.mp4',
+    }),
+  };
+
+  assert.deepEqual(
+    getDraftReferencePickerOptions({
+      draftCard: draft,
+      cards,
+      model: makeModel({
+        id: 'kling-3-motion-control',
+        maxReferenceImages: 1,
+        maxSourceVideos: 1,
+        supportsSourceVideo: true,
+      }),
+    }),
+    []
+  );
+});
+
 test('allows upstream images for image and video generation', () => {
   const sourceCard = makeCard();
 
@@ -148,3 +179,41 @@ test('modifier shortcuts still work outside text fields', () => {
     true
   );
 });
+
+test('preserves every compatible reference video in attachment order', () => {
+  assert.deepEqual(
+    resolveReferencePayload({
+      taskType: 'video',
+      cards: [
+        {
+          id: 'video-1',
+          name: 'Motion one',
+          type: 'video',
+          url: 'https://example.com/one.mp4',
+          role: 'asset',
+        },
+        {
+          id: 'image-1',
+          name: 'Character',
+          type: 'image',
+          url: 'https://example.com/person.png',
+          role: 'asset',
+        },
+        {
+          id: 'video-2',
+          name: 'Motion two',
+          type: 'video',
+          url: 'https://example.com/two.mp4',
+          role: 'asset',
+        },
+      ],
+    }),
+    {
+      imageUrls: ['https://example.com/person.png'],
+      videoUrls: [
+        'https://example.com/one.mp4',
+        'https://example.com/two.mp4',
+      ],
+    }
+  );
+});
diff --git a/src/core/beatcanvas/composer.ts b/src/core/beatcanvas/composer.ts
index 70862b7..a9235fb 100644
--- a/src/core/beatcanvas/composer.ts
+++ b/src/core/beatcanvas/composer.ts
@@ -1,5 +1,7 @@
 import type {
   WorkspaceAspectRatio,
+  WorkspaceBackgroundSource,
+  WorkspaceCharacterOrientation,
   WorkspaceDuration,
   WorkspaceLanguage,
   WorkspaceModelMode,
@@ -25,6 +27,8 @@ type DraftModelSettings = Pick<
   | 'mode'
   | 'variant'
   | 'quality'
+  | 'characterOrientation'
+  | 'backgroundSource'
 >;
 
 export type CanvasShortcutContext = {
@@ -51,6 +55,11 @@ const INTERACTIVE_SHORTCUT_TAGS = new Set([
   'TEXTAREA',
 ]);
 
+const STRICT_REFERENCE_LIMIT_MODEL_IDS = new Set([
+  'kling-2.6-motion-control',
+  'kling-3-motion-control',
+]);
+
 const resolveSupportedValue = <T extends string>({
   current,
   supported,
@@ -136,14 +145,21 @@ export const getDraftReferencePickerOptions = ({
   }
 
   const referenceCounts = getReferenceCounts({ draftCard, cards });
+  const strictReferenceLimits = STRICT_REFERENCE_LIMIT_MODEL_IDS.has(model.id);
+  const imageLimit = strictReferenceLimits
+    ? Math.max(model.maxReferenceImages ?? 0, 0)
+    : Number.POSITIVE_INFINITY;
+  const imageRemaining = Math.max(imageLimit - referenceCounts.image, 0);
   const videoLimit = Math.max(model.maxSourceVideos ?? 0, 0);
   const videoRemaining = Math.max(videoLimit - referenceCounts.video, 0);
-  const options: DraftReferencePickerOption[] = [
-    {
+  const options: DraftReferencePickerOption[] = [];
+
+  if (imageRemaining > 0) {
+    options.push({
       intent: 'image',
-      remaining: null,
-    },
-  ];
+      remaining: Number.isFinite(imageRemaining) ? imageRemaining : null,
+    });
+  }
 
   if (videoRemaining > 0) {
     options.push({
@@ -182,6 +198,15 @@ export const listCompatibleCanvasReferenceCards = ({
 }) => {
   const attachedIds = new Set(draftCard.referenceCardIds);
   const referenceCounts = getReferenceCounts({ draftCard, cards });
+  const strictReferenceLimits = Boolean(
+    model && STRICT_REFERENCE_LIMIT_MODEL_IDS.has(model.id)
+  );
+  const imageRemaining = strictReferenceLimits
+    ? Math.max(
+        (model?.maxReferenceImages ?? 0) - referenceCounts.image,
+        0
+      )
+    : Number.POSITIVE_INFINITY;
   const videoRemaining = Math.max(
     (model?.maxSourceVideos ?? 0) - referenceCounts.video,
     0
@@ -196,6 +221,13 @@ export const listCompatibleCanvasReferenceCards = ({
       return false;
     }
 
+    if (
+      card.type === 'image' &&
+      imageRemaining <= 0
+    ) {
+      return false;
+    }
+
     if (
       card.type === 'video' &&
       (videoRemaining <= 0 || !model?.supportsSourceVideo)
@@ -286,4 +318,27 @@ export const getCompatibleDraftModelSettings = ({
     supported: model.qualityOptions,
     fallback: model.defaultQuality,
   }),
+  characterOrientation:
+    model.characterOrientationOptions &&
+    model.characterOrientationOptions.length > 0
+      ? resolveSupportedValue<WorkspaceCharacterOrientation>({
+          current:
+            draftCard.characterOrientation ??
+            model.defaultCharacterOrientation ??
+            'video',
+          supported: model.characterOrientationOptions,
+          fallback: model.defaultCharacterOrientation,
+        })
+      : undefined,
+  backgroundSource:
+    model.backgroundSourceOptions && model.backgroundSourceOptions.length > 0
+      ? resolveSupportedValue<WorkspaceBackgroundSource>({
+          current:
+            draftCard.backgroundSource ??
+            model.defaultBackgroundSource ??
+            'input_video',
+          supported: model.backgroundSourceOptions,
+          fallback: model.defaultBackgroundSource,
+        })
+      : undefined,
 });
diff --git a/src/core/beatcanvas/draft-defaults.ts b/src/core/beatcanvas/draft-defaults.ts
index 096ae64..c481c2d 100644
--- a/src/core/beatcanvas/draft-defaults.ts
+++ b/src/core/beatcanvas/draft-defaults.ts
@@ -24,4 +24,6 @@ export const getDraftDefaultsFromModel = (
   mode: model?.defaultMode ?? 'quality',
   variant: model?.defaultVariant ?? 'standard',
   quality: model?.defaultQuality ?? 'standard',
+  characterOrientation: model?.defaultCharacterOrientation,
+  backgroundSource: model?.defaultBackgroundSource,
 });
diff --git a/src/core/beatcanvas/generation-controller-language.test.ts b/src/core/beatcanvas/generation-controller-language.test.ts
index 715dcb6..6293d68 100644
--- a/src/core/beatcanvas/generation-controller-language.test.ts
+++ b/src/core/beatcanvas/generation-controller-language.test.ts
@@ -131,6 +131,58 @@ test('passes every connected upstream image even before model limits are configu
   ]);
 });
 
+test('passes every connected reference video in @Video order', async () => {
+  const videoModel: WorkspaceModelOption = {
+    ...ecommerceVideoModel,
+    supportsSourceVideo: true,
+    maxSourceVideos: 3,
+  };
+  const videoMetadata: EffectMetadata = {
+    ...ecommerceVideoMetadata,
+    inputSchema: {
+      prompt: { type: 'string' },
+      wmDuration: { type: 'string' },
+      aspect_ratio: { type: 'string' },
+      language: { type: 'string' },
+      video_urls: { type: 'array' },
+    },
+  };
+  const makeVideoReference = (id: string, url: string): CanvasCard => ({
+    ...makeDraft({ id, type: 'video', url, status: 'succeeded' }),
+    kind: 'asset',
+  });
+
+  const result = await buildGenerationEffectInput({
+    draftCard: makeDraft({
+      referenceCardIds: ['motion-1', 'motion-2'],
+    }),
+    canvasCards: {
+      'motion-1': makeVideoReference(
+        'motion-1',
+        'https://example.com/motion-1.mp4'
+      ),
+      'motion-2': makeVideoReference(
+        'motion-2',
+        'https://example.com/motion-2.mp4'
+      ),
+    },
+    imageModels: [],
+    videoModels: [videoModel],
+    metadataMap: { 15: videoMetadata },
+    runtimeMessages: {
+      missingVideoUrl: 'Missing video URL',
+      readVideoDurationFailed: 'Unable to read video duration',
+      videoMetadataLoadFailed: 'Unable to load video metadata',
+    },
+    translate: (key) => key,
+  });
+
+  assert.deepEqual(result.input.video_urls, [
+    'https://example.com/motion-1.mp4',
+    'https://example.com/motion-2.mp4',
+  ]);
+});
+
 test('blocks downstream generation until a connected upstream image is ready', async () => {
   await assert.rejects(
     buildGenerationEffectInput({
diff --git a/src/core/beatcanvas/generation-controller-motion-control.test.ts b/src/core/beatcanvas/generation-controller-motion-control.test.ts
new file mode 100644
index 0000000..f626954
--- /dev/null
+++ b/src/core/beatcanvas/generation-controller-motion-control.test.ts
@@ -0,0 +1,114 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { buildBeatApiTaskRequest } from '@/core/adapters/beatapi-adapter';
+import { getRegisteredEffectById } from '@/core/effects/registered-effects';
+import {
+  findWorkspaceModelOption,
+  getWorkspaceModelsByType,
+} from '@/core/effects/workspace-models';
+import type { CanvasCard, CanvasDraftCard } from './canvas-types';
+import { buildGenerationEffectInput } from './generation-controller';
+
+const makeCard = (overrides: Partial<CanvasCard>): CanvasCard => ({
+  id: 'card',
+  kind: 'asset',
+  type: 'image',
+  name: 'Reference',
+  url: 'https://media.beatapi.io/inputs/reference.png',
+  prompt: '',
+  referenceCardIds: [],
+  workflowTemplateId: null,
+  status: 'succeeded',
+  error: null,
+  modelId: '',
+  aspectRatio: '9:16',
+  outputQuality: '720p',
+  duration: '5s',
+  mode: 'quality',
+  variant: 'standard',
+  quality: 'standard',
+  sourceGenerationId: null,
+  ...overrides,
+});
+
+test('Canvas Motion Control controls reach the BeatAPI provider request', async () => {
+  const model = findWorkspaceModelOption(
+    getWorkspaceModelsByType('ai-video'),
+    'kling-3-motion-control'
+  );
+  const effect = getRegisteredEffectById(20);
+  assert.ok(model);
+  assert.ok(effect);
+
+  const draft = makeCard({
+    id: 'draft',
+    kind: 'generation',
+    type: 'video',
+    name: 'Kling Motion Control',
+    url: null,
+    prompt: 'Keep the identity and follow the motion.',
+    referenceCardIds: ['character', 'motion'],
+    modelId: model.id,
+    outputQuality: '1080p',
+    characterOrientation: 'video',
+    backgroundSource: 'input_image',
+    status: 'idle',
+  }) as CanvasDraftCard;
+  const canvasCards = {
+    character: makeCard({
+      id: 'character',
+      type: 'image',
+      url: 'https://media.beatapi.io/inputs/character.png',
+    }),
+    motion: makeCard({
+      id: 'motion',
+      type: 'video',
+      url: 'https://media.beatapi.io/inputs/motion.mp4',
+    }),
+  };
+
+  const built = await buildGenerationEffectInput({
+    draftCard: draft,
+    canvasCards,
+    imageModels: [],
+    videoModels: [model],
+    metadataMap: { [effect.id]: effect },
+    runtimeMessages: {
+      missingVideoUrl: 'Missing video URL',
+      readVideoDurationFailed: 'Unable to read video duration',
+      videoMetadataLoadFailed: 'Unable to load video metadata',
+    },
+    translate: (key) => key,
+    loadVideoDurationSecondsImpl: async () => 15.25,
+  });
+
+  assert.deepEqual(built.input, {
+    prompt: 'Keep the identity and follow the motion.',
+    generationType: undefined,
+    wmOutputQuality: '1080p',
+    image_urls: ['https://media.beatapi.io/inputs/character.png'],
+    video_urls: ['https://media.beatapi.io/inputs/motion.mp4'],
+    sourceVideoDurationSeconds: 15.25,
+    wmHasVideoInput: true,
+    characterOrientation: 'video',
+    backgroundSource: 'input_image',
+  });
+
+  assert.deepEqual(
+    buildBeatApiTaskRequest({
+      effectType: effect.type,
+      model: effect.model,
+      input: built.input as Parameters<typeof buildBeatApiTaskRequest>[0]['input'],
+    }).body,
+    {
+      model: 'kling-3-motion-control',
+      prompt: 'Keep the identity and follow the motion.',
+      images: ['https://media.beatapi.io/inputs/character.png'],
+      reference_videos: ['https://media.beatapi.io/inputs/motion.mp4'],
+      resolution: '1080p',
+      character_orientation: 'video',
+      background_source: 'input_image',
+    }
+  );
+});
diff --git a/src/core/beatcanvas/generation-controller.ts b/src/core/beatcanvas/generation-controller.ts
index 96bd2e1..30f13a1 100644
--- a/src/core/beatcanvas/generation-controller.ts
+++ b/src/core/beatcanvas/generation-controller.ts
@@ -258,7 +258,7 @@ export const buildGenerationEffectInput = async ({
     if (referencePayload.imageUrls.length > 0) {
       input.image_urls = referencePayload.imageUrls;
     }
-    if (referencePayload.videoUrl) {
+    if (referencePayload.videoUrls.length > 0) {
       notify?.(translate('messages.imageModelOnlySupportsImageReference'));
     }
 
@@ -314,25 +314,25 @@ export const buildGenerationEffectInput = async ({
       referencePayload.imageUrls[referencePayload.imageUrls.length - 1];
   }
 
-  if (referencePayload.videoUrl) {
+  if (referencePayload.videoUrls.length > 0) {
     if (!hasInputSchemaField(metadata.inputSchema, 'video_urls')) {
       throw new Error(translate('messages.videoContinuationUnsupported'));
     }
 
-    input.video_urls = [referencePayload.videoUrl];
+    input.video_urls = referencePayload.videoUrls;
     input.generationType = undefined;
 
     if (
       hasInputSchemaField(metadata.inputSchema, 'sourceVideoDurationSeconds')
     ) {
       input.sourceVideoDurationSeconds = await loadVideoDurationSecondsImpl(
-        referencePayload.videoUrl,
+        referencePayload.videoUrls[0],
         runtimeMessages
       );
     }
   }
 
-  input.wmHasVideoInput = referencePayload.videoUrl !== null;
+  input.wmHasVideoInput = referencePayload.videoUrls.length > 0;
 
   const referenceInputDefaults = getWorkspaceEffectReferenceInputDefaults({
     modelId: model.id,
@@ -340,10 +340,13 @@ export const buildGenerationEffectInput = async ({
   });
   if (referenceInputDefaults) {
     if (hasInputSchemaField(metadata.inputSchema, 'characterOrientation')) {
-      input.characterOrientation = referenceInputDefaults.characterOrientation;
+      input.characterOrientation =
+        draftCard.characterOrientation ??
+        referenceInputDefaults.characterOrientation;
     }
     if (hasInputSchemaField(metadata.inputSchema, 'backgroundSource')) {
-      input.backgroundSource = referenceInputDefaults.backgroundSource;
+      input.backgroundSource =
+        draftCard.backgroundSource ?? referenceInputDefaults.backgroundSource;
     }
   }
 
diff --git a/src/core/beatcanvas/reference-mentions.test.ts b/src/core/beatcanvas/reference-mentions.test.ts
new file mode 100644
index 0000000..6a651de
--- /dev/null
+++ b/src/core/beatcanvas/reference-mentions.test.ts
@@ -0,0 +1,125 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import type { CanvasCard } from './canvas-types';
+import {
+  buildCanvasReferenceMentions,
+  filterCanvasReferenceMentions,
+  findActiveCanvasReferenceMention,
+  insertCanvasReferenceMention,
+  moveCanvasReferenceCardId,
+  rewriteCanvasReferenceAliases,
+} from './reference-mentions';
+
+const makeCard = (
+  id: string,
+  type: CanvasCard['type'],
+  name: string
+): CanvasCard => ({
+  id,
+  kind: 'asset',
+  type,
+  name,
+  url: `https://example.com/${id}`,
+  prompt: '',
+  referenceCardIds: [],
+  workflowTemplateId: null,
+  status: 'succeeded',
+  error: null,
+  modelId: '',
+  aspectRatio: '1:1',
+  outputQuality: '1k',
+  duration: '5s',
+  mode: 'quality',
+  variant: 'standard',
+  quality: 'standard',
+  sourceGenerationId: null,
+});
+
+const cards = {
+  person: makeCard('person', 'image', 'Portrait'),
+  motion: makeCard('motion', 'video', 'Dance motion'),
+  outfit: makeCard('outfit', 'image', 'Couture dress'),
+  camera: makeCard('camera', 'video', 'Camera move'),
+};
+
+test('numbers images and videos independently in API order', () => {
+  assert.deepEqual(
+    buildCanvasReferenceMentions({
+      referenceCardIds: ['person', 'motion', 'outfit', 'camera'],
+      cards,
+    }).map(({ cardId, alias }) => ({ cardId, alias })),
+    [
+      { cardId: 'person', alias: '@Image1' },
+      { cardId: 'motion', alias: '@Video1' },
+      { cardId: 'outfit', alias: '@Image2' },
+      { cardId: 'camera', alias: '@Video2' },
+    ]
+  );
+});
+
+test('finds and replaces the active @ query at the caret', () => {
+  const prompt = 'Keep @Im';
+  const activeMention = findActiveCanvasReferenceMention({
+    prompt,
+    caret: prompt.length,
+  });
+  assert.deepEqual(activeMention, {
+    start: 5,
+    end: 8,
+    query: 'Im',
+  });
+  assert.deepEqual(
+    insertCanvasReferenceMention({
+      prompt,
+      alias: '@Image1',
+      selectionStart: prompt.length,
+      selectionEnd: prompt.length,
+      activeMention,
+    }),
+    { prompt: 'Keep @Image1', caret: 12 }
+  );
+});
+
+test('filters references by alias, type, and card name', () => {
+  const mentions = buildCanvasReferenceMentions({
+    referenceCardIds: ['person', 'motion'],
+    cards,
+  });
+  assert.deepEqual(
+    filterCanvasReferenceMentions({ mentions, query: 'dance' }).map(
+      (mention) => mention.alias
+    ),
+    ['@Video1']
+  );
+});
+
+test('rewrites aliases atomically when same-type references reorder', () => {
+  const previousMentions = buildCanvasReferenceMentions({
+    referenceCardIds: ['person', 'outfit'],
+    cards,
+  });
+  const nextMentions = buildCanvasReferenceMentions({
+    referenceCardIds: ['outfit', 'person'],
+    cards,
+  });
+  assert.equal(
+    rewriteCanvasReferenceAliases({
+      prompt: 'Keep @Image1 identity and use @Image2 clothing.',
+      previousMentions,
+      nextMentions,
+    }),
+    'Keep @Image2 identity and use @Image1 clothing.'
+  );
+});
+
+test('moves a reference without dropping mixed media entries', () => {
+  assert.deepEqual(
+    moveCanvasReferenceCardId({
+      referenceCardIds: ['person', 'motion', 'outfit'],
+      activeCardId: 'outfit',
+      overCardId: 'person',
+    }),
+    ['outfit', 'person', 'motion']
+  );
+});
diff --git a/src/core/beatcanvas/reference-mentions.ts b/src/core/beatcanvas/reference-mentions.ts
new file mode 100644
index 0000000..a076e1e
--- /dev/null
+++ b/src/core/beatcanvas/reference-mentions.ts
@@ -0,0 +1,184 @@
+import type {
+  CanvasCard,
+  CanvasCardMediaType,
+} from './canvas-types';
+
+export type CanvasReferenceMention = {
+  cardId: string;
+  type: CanvasCardMediaType;
+  index: number;
+  alias: string;
+  name: string;
+};
+
+export type ActiveCanvasReferenceMention = {
+  start: number;
+  end: number;
+  query: string;
+};
+
+const REFERENCE_MENTION_PATTERN = /@(?:Image|Video)\d+/g;
+
+export const getCanvasReferenceAlias = (
+  type: CanvasCardMediaType,
+  index: number
+) => `@${type === 'video' ? 'Video' : 'Image'}${index}`;
+
+export const buildCanvasReferenceMentions = ({
+  referenceCardIds,
+  cards,
+}: {
+  referenceCardIds: string[];
+  cards: Record<string, CanvasCard | undefined>;
+}): CanvasReferenceMention[] => {
+  const counts: Record<CanvasCardMediaType, number> = {
+    image: 0,
+    video: 0,
+  };
+
+  return referenceCardIds.flatMap((cardId) => {
+    const card = cards[cardId];
+    if (!card) return [];
+
+    counts[card.type] += 1;
+    const index = counts[card.type];
+    return [
+      {
+        cardId,
+        type: card.type,
+        index,
+        alias: getCanvasReferenceAlias(card.type, index),
+        name: card.name,
+      },
+    ];
+  });
+};
+
+export const findActiveCanvasReferenceMention = ({
+  prompt,
+  caret,
+}: {
+  prompt: string;
+  caret: number;
+}): ActiveCanvasReferenceMention | null => {
+  const safeCaret = Math.max(0, Math.min(caret, prompt.length));
+  const beforeCaret = prompt.slice(0, safeCaret);
+  const match = /(?:^|[\s([{，。,:;；：])@([^\s@]*)$/u.exec(beforeCaret);
+  if (!match) return null;
+
+  const query = match[1] ?? '';
+  const start = safeCaret - query.length - 1;
+  return {
+    start,
+    end: safeCaret,
+    query,
+  };
+};
+
+export const filterCanvasReferenceMentions = ({
+  mentions,
+  query,
+}: {
+  mentions: CanvasReferenceMention[];
+  query: string;
+}) => {
+  const normalizedQuery = query.trim().toLocaleLowerCase();
+  if (!normalizedQuery) return mentions;
+
+  return mentions.filter((mention) =>
+    `${mention.alias} ${mention.name} ${mention.type}`
+      .toLocaleLowerCase()
+      .includes(normalizedQuery)
+  );
+};
+
+export const insertCanvasReferenceMention = ({
+  prompt,
+  alias,
+  selectionStart,
+  selectionEnd,
+  activeMention,
+}: {
+  prompt: string;
+  alias: string;
+  selectionStart: number;
+  selectionEnd: number;
+  activeMention?: ActiveCanvasReferenceMention | null;
+}) => {
+  const start = activeMention?.start ?? selectionStart;
+  const end = activeMention?.end ?? selectionEnd;
+  const before = prompt.slice(0, start);
+  const after = prompt.slice(end);
+  const leadingSpace = before && !/[\s([{，。,:;；：]$/u.test(before) ? ' ' : '';
+  const trailingSpace = after && !/^[\s)\]}，。,:;；：]/u.test(after) ? ' ' : '';
+  const insertion = `${leadingSpace}${alias}${trailingSpace}`;
+
+  return {
+    prompt: `${before}${insertion}${after}`,
+    caret: start + insertion.length,
+  };
+};
+
+export const rewriteCanvasReferenceAliases = ({
+  prompt,
+  previousMentions,
+  nextMentions,
+}: {
+  prompt: string;
+  previousMentions: CanvasReferenceMention[];
+  nextMentions: CanvasReferenceMention[];
+}) => {
+  const previousByAlias = new Map(
+    previousMentions.map((mention) => [mention.alias, mention])
+  );
+  const nextByCardId = new Map(
+    nextMentions.map((mention) => [mention.cardId, mention])
+  );
+  const placeholders = new Map<string, string>();
+
+  const withPlaceholders = prompt.replace(
+    REFERENCE_MENTION_PATTERN,
+    (alias) => {
+      const previous = previousByAlias.get(alias);
+      if (!previous) return alias;
+      const placeholder = `\u0000beat-ref-${previous.cardId}\u0000`;
+      placeholders.set(placeholder, previous.cardId);
+      return placeholder;
+    }
+  );
+
+  let nextPrompt = withPlaceholders;
+  for (const [placeholder, cardId] of placeholders) {
+    const previous = previousMentions.find(
+      (mention) => mention.cardId === cardId
+    );
+    const next = nextByCardId.get(cardId);
+    nextPrompt = nextPrompt.split(placeholder).join(
+      next?.alias ?? `@Removed${previous?.type === 'video' ? 'Video' : 'Image'}`
+    );
+  }
+
+  return nextPrompt;
+};
+
+export const moveCanvasReferenceCardId = ({
+  referenceCardIds,
+  activeCardId,
+  overCardId,
+}: {
+  referenceCardIds: string[];
+  activeCardId: string;
+  overCardId: string;
+}) => {
+  const fromIndex = referenceCardIds.indexOf(activeCardId);
+  const toIndex = referenceCardIds.indexOf(overCardId);
+  if (fromIndex < 0 || toIndex < 0 || fromIndex === toIndex) {
+    return referenceCardIds;
+  }
+
+  const next = [...referenceCardIds];
+  const [moved] = next.splice(fromIndex, 1);
+  if (!moved) return referenceCardIds;
+  next.splice(toIndex, 0, moved);
+  return next;
+};
diff --git a/src/core/effects/effect-registry.ts b/src/core/effects/effect-registry.ts
index 14cbdbb..afdaef4 100644
--- a/src/core/effects/effect-registry.ts
+++ b/src/core/effects/effect-registry.ts
@@ -37,8 +37,8 @@ type WorkspaceRegistryOutputQuality =
   | 'std'
   | 'pro';
 type WorkspaceRegistryReferenceType = 'image' | 'video';
-type WorkspaceRegistryBackgroundSource = 'input_image' | 'input_video';
-type WorkspaceRegistryCharacterOrientation = 'image' | 'video';
+export type WorkspaceRegistryBackgroundSource = 'input_image' | 'input_video';
+export type WorkspaceRegistryCharacterOrientation = 'image' | 'video';
 
 export type WorkspaceModelMode = WorkspaceRegistryModelMode;
 export type WorkspaceModelVariant = WorkspaceRegistryModelVariant;
@@ -80,6 +80,11 @@ export type WorkspaceEffectRegistryEntry = {
   audioSettingOptions?: WorkspaceRegistryAudioSetting[];
   defaultLanguage?: WorkspaceRegistryLanguage;
   supportedLanguages?: WorkspaceRegistryLanguage[];
+  defaultCharacterOrientation?: WorkspaceRegistryCharacterOrientation;
+  characterOrientationOptions?: WorkspaceRegistryCharacterOrientation[];
+  defaultBackgroundSource?: WorkspaceRegistryBackgroundSource;
+  backgroundSourceOptions?: WorkspaceRegistryBackgroundSource[];
+  requiresSourceVideoDuration?: boolean;
   providerModelVariantByVariant?: Partial<
     Record<WorkspaceRegistryModelVariant, string>
   >;
@@ -303,6 +308,51 @@ export const WORKSPACE_EFFECT_REGISTRY: readonly WorkspaceEffectRegistryEntry[]
       supportedOutputQualities: ['std', 'pro', '4k'],
       modelAliases: ['kling30'],
     },
+    {
+      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,
+      defaultOutputQuality: '720p',
+      supportedOutputQualities: ['720p', '1080p'],
+      defaultCharacterOrientation: 'video',
+      characterOrientationOptions: ['image', 'video'],
+      requiresSourceVideoDuration: true,
+      referenceInputDefaultsByType: {
+        video: { characterOrientation: 'video' },
+      },
+      modelAliases: ['kling26motioncontrol'],
+    },
+    {
+      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,
+      defaultOutputQuality: '720p',
+      supportedOutputQualities: ['720p', '1080p'],
+      defaultCharacterOrientation: 'video',
+      characterOrientationOptions: ['image', 'video'],
+      defaultBackgroundSource: 'input_video',
+      backgroundSourceOptions: ['input_video', 'input_image'],
+      requiresSourceVideoDuration: true,
+      referenceInputDefaultsByType: {
+        video: {
+          characterOrientation: 'video',
+          backgroundSource: 'input_video',
+        },
+      },
+      modelAliases: ['kling3motioncontrol', 'kling30motioncontrol'],
+    },
   ] as const;
 
 const WORKSPACE_EFFECT_REGISTRY_BY_ID = new Map(
diff --git a/src/core/effects/generation-upload-intent.ts b/src/core/effects/generation-upload-intent.ts
index 94e69d3..29d43bd 100644
--- a/src/core/effects/generation-upload-intent.ts
+++ b/src/core/effects/generation-upload-intent.ts
@@ -168,6 +168,30 @@ export async function claimGenerationUploadSlot({
   return slotId;
 }
 
+export async function getGenerationUploadIntentEffectId({
+  intentId,
+  projectId,
+  dbClient,
+}: {
+  intentId: string;
+  projectId: string;
+  dbClient?: DbClient;
+}) {
+  const db = await resolveDb(dbClient);
+  const [intent] = await db
+    .select({ effectId: generationUploadIntent.effectId })
+    .from(generationUploadIntent)
+    .where(
+      and(
+        eq(generationUploadIntent.id, intentId),
+        eq(generationUploadIntent.projectId, projectId)
+      )
+    )
+    .limit(1);
+
+  return intent?.effectId ?? null;
+}
+
 export async function releaseGenerationUploadSlot({
   intentId,
   slotId,
diff --git a/src/core/effects/registered-effects.test.ts b/src/core/effects/registered-effects.test.ts
index 0365ecd..cb54d5a 100644
--- a/src/core/effects/registered-effects.test.ts
+++ b/src/core/effects/registered-effects.test.ts
@@ -37,3 +37,21 @@ test('batch lookup only returns official registry models', async () => {
     ['minimax-h3', 'nano-banana-pro']
   );
 });
+
+test('Motion Control registry schemas expose provider controls', () => {
+  const kling26 = getRegisteredEffectById(19)?.inputSchema as Record<
+    string,
+    unknown
+  >;
+  const kling3 = getRegisteredEffectById(20)?.inputSchema as Record<
+    string,
+    unknown
+  >;
+
+  assert.ok(kling26.image_urls);
+  assert.ok(kling26.video_urls);
+  assert.ok(kling26.wmOutputQuality);
+  assert.ok(kling26.sourceVideoDurationSeconds);
+  assert.ok(kling26.characterOrientation);
+  assert.ok(kling3.backgroundSource);
+});
diff --git a/src/core/effects/registered-effects.ts b/src/core/effects/registered-effects.ts
index 145c6a1..32e8239 100644
--- a/src/core/effects/registered-effects.ts
+++ b/src/core/effects/registered-effects.ts
@@ -59,6 +59,23 @@ const buildInputSchema = (entry: WorkspaceEffectRegistryEntry) => {
       values: entry.supportedLanguages,
     };
   }
+  if (entry.characterOrientationOptions?.length) {
+    schema.characterOrientation = {
+      type: 'enum',
+      required: false,
+      values: entry.characterOrientationOptions,
+    };
+  }
+  if (entry.backgroundSourceOptions?.length) {
+    schema.backgroundSource = {
+      type: 'enum',
+      required: false,
+      values: entry.backgroundSourceOptions,
+    };
+  }
+  if (entry.requiresSourceVideoDuration) {
+    schema.sourceVideoDurationSeconds = optionalAnyField;
+  }
   if (mediaSchema && mediaSchema.image.max > 0) {
     schema.image_urls = optionalAnyField;
   }
diff --git a/src/core/effects/workspace-media.ts b/src/core/effects/workspace-media.ts
index fae0a64..db23475 100644
--- a/src/core/effects/workspace-media.ts
+++ b/src/core/effects/workspace-media.ts
@@ -114,6 +114,16 @@ export const WORKSPACE_MEDIA_SCHEMAS = {
     video: emptySection,
     audio: emptySection,
   },
+  'kling-2.6-motion-control': {
+    image: createGenericSection('reference-image', 1),
+    video: createGenericSection('reference-video', 1),
+    audio: emptySection,
+  },
+  'kling-3-motion-control': {
+    image: createGenericSection('reference-image', 1),
+    video: createGenericSection('reference-video', 1),
+    audio: emptySection,
+  },
 } as const satisfies Record<string, WorkspaceMediaSchema>;
 
 export const isAppendMediaSection = (section: WorkspaceMediaSection) =>
diff --git a/src/core/effects/workspace-models.test.ts b/src/core/effects/workspace-models.test.ts
index 98d2396..e2d38c8 100644
--- a/src/core/effects/workspace-models.test.ts
+++ b/src/core/effects/workspace-models.test.ts
@@ -24,6 +24,8 @@ test('workspace exposes the official BeatAPI image and video catalog', () => {
     'minimax-h3',
     'veo-3.1',
     'kling-3',
+    'kling-2.6-motion-control',
+    'kling-3-motion-control',
   ]);
   assert.equal(videoIds.includes('wan27'), false);
   assert.equal(imageIds.includes('nanobanana2'), false);
@@ -37,6 +39,14 @@ test('legacy canvas model ids resolve to official BeatAPI slugs', () => {
   assert.equal(getCanonicalWorkspaceModelId('seedance20'), 'seedance-2');
   assert.equal(getCanonicalWorkspaceModelId('veo31'), 'veo-3.1');
   assert.equal(getCanonicalWorkspaceModelId('kling30'), 'kling-3');
+  assert.equal(
+    getCanonicalWorkspaceModelId('kling26motioncontrol'),
+    'kling-2.6-motion-control'
+  );
+  assert.equal(
+    getCanonicalWorkspaceModelId('kling30motioncontrol'),
+    'kling-3-motion-control'
+  );
   assert.equal(
     findWorkspaceModelOption(imageModels, 'nanobananapro')?.id,
     'nano-banana-pro'
@@ -47,6 +57,26 @@ test('legacy canvas model ids resolve to official BeatAPI slugs', () => {
   );
 });
 
+test('Kling Motion Control exposes one image, one motion video, and its controls', () => {
+  const videoModels = getWorkspaceModelsByType('ai-video');
+  const kling26 = findWorkspaceModelOption(
+    videoModels,
+    'kling-2.6-motion-control'
+  );
+  const kling3 = findWorkspaceModelOption(videoModels, 'kling-3-motion-control');
+
+  assert.equal(kling26?.maxReferenceImages, 1);
+  assert.equal(kling26?.maxSourceVideos, 1);
+  assert.deepEqual(kling26?.supportedOutputQualities, ['720p', '1080p']);
+  assert.deepEqual(kling26?.characterOrientationOptions, ['image', 'video']);
+  assert.equal(kling3?.maxReferenceImages, 1);
+  assert.equal(kling3?.maxSourceVideos, 1);
+  assert.deepEqual(kling3?.backgroundSourceOptions, [
+    'input_video',
+    'input_image',
+  ]);
+});
+
 test('BeatAPI-backed models are the default image and video canvas choices', () => {
   assert.equal(
     getDefaultSelectableWorkspaceModel('ai-image')?.id,
diff --git a/src/core/effects/workspace-models.ts b/src/core/effects/workspace-models.ts
index 41b61c7..8937790 100644
--- a/src/core/effects/workspace-models.ts
+++ b/src/core/effects/workspace-models.ts
@@ -3,6 +3,8 @@ import {
   WORKSPACE_EFFECT_REGISTRY,
   type WorkspaceAspectRatio,
   type WorkspaceAudioSetting,
+  type WorkspaceRegistryBackgroundSource,
+  type WorkspaceRegistryCharacterOrientation,
   type WorkspaceDuration,
   type WorkspaceLanguage,
   type WorkspaceModelMode,
@@ -19,6 +21,8 @@ import {
 } from './workspace-media';
 
 export type WorkspaceType = WorkspaceRegistryType;
+export type WorkspaceBackgroundSource = WorkspaceRegistryBackgroundSource;
+export type WorkspaceCharacterOrientation = WorkspaceRegistryCharacterOrientation;
 export type {
   WorkspaceAspectRatio,
   WorkspaceAudioSetting,
@@ -54,6 +58,10 @@ export type WorkspaceModelOption = {
   audioSettingOptions?: WorkspaceAudioSetting[];
   defaultLanguage?: WorkspaceLanguage;
   supportedLanguages?: WorkspaceLanguage[];
+  defaultCharacterOrientation?: WorkspaceCharacterOrientation;
+  characterOrientationOptions?: WorkspaceCharacterOrientation[];
+  defaultBackgroundSource?: WorkspaceBackgroundSource;
+  backgroundSourceOptions?: WorkspaceBackgroundSource[];
   available?: boolean;
   supportsFramePair?: boolean;
   supportsSourceVideo?: boolean;
@@ -120,6 +128,14 @@ const toWorkspaceModelOption = (
     supportedLanguages: entry.supportedLanguages
       ? [...entry.supportedLanguages]
       : undefined,
+    defaultCharacterOrientation: entry.defaultCharacterOrientation,
+    characterOrientationOptions: entry.characterOrientationOptions
+      ? [...entry.characterOrientationOptions]
+      : undefined,
+    defaultBackgroundSource: entry.defaultBackgroundSource,
+    backgroundSourceOptions: entry.backgroundSourceOptions
+      ? [...entry.backgroundSourceOptions]
+      : undefined,
     supportsFramePair: mediaSchema.image.slots.some(
       (slot) => slot.kind === 'last-frame'
     ),
diff --git a/src/core/projects/project-snapshot.ts b/src/core/projects/project-snapshot.ts
index f7b29da..b8835fe 100644
--- a/src/core/projects/project-snapshot.ts
+++ b/src/core/projects/project-snapshot.ts
@@ -201,6 +201,16 @@ const normalizeCard = (value: unknown): CanvasCard | null => {
       typeof value.quality === 'string'
         ? (value.quality as CanvasCard['quality'])
         : 'standard',
+    characterOrientation:
+      value.characterOrientation === 'image' ||
+      value.characterOrientation === 'video'
+        ? value.characterOrientation
+        : undefined,
+    backgroundSource:
+      value.backgroundSource === 'input_image' ||
+      value.backgroundSource === 'input_video'
+        ? value.backgroundSource
+        : undefined,
     sourceGenerationId:
       typeof value.sourceGenerationId === 'string'
         ? value.sourceGenerationId
diff --git a/src/core/workspace-lib/constants.ts b/src/core/workspace-lib/constants.ts
index c7b8aa9..2aba84b 100644
--- a/src/core/workspace-lib/constants.ts
+++ b/src/core/workspace-lib/constants.ts
@@ -1,4 +1,4 @@
 export const AVATAR_MAX_FILE_SIZE = 2 * 1024 * 1024;
 export const REFERENCE_IMAGE_MAX_FILE_SIZE = 50 * 1024 * 1024;
-export const REFERENCE_VIDEO_MAX_FILE_SIZE = 50 * 1024 * 1024;
+export const REFERENCE_VIDEO_MAX_FILE_SIZE = 100 * 1024 * 1024;
 export const REFERENCE_AUDIO_MAX_FILE_SIZE = 15 * 1024 * 1024;
diff --git a/src/core/workspace-lib/model-icons.test.ts b/src/core/workspace-lib/model-icons.test.ts
new file mode 100644
index 0000000..0b45782
--- /dev/null
+++ b/src/core/workspace-lib/model-icons.test.ts
@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { getModelIconPathByModelId } from './model-icons';
+
+test('all Kling models reuse the verified Kling SVG', () => {
+  for (const modelId of [
+    'kling-3',
+    'kling-2.6-motion-control',
+    'kling-3-motion-control',
+  ]) {
+    assert.equal(
+      getModelIconPathByModelId(modelId),
+      '/model-icons/kling-color.svg'
+    );
+  }
+});
diff --git a/src/core/workspace-lib/model-icons.ts b/src/core/workspace-lib/model-icons.ts
index 5b3703d..c4faa8b 100644
--- a/src/core/workspace-lib/model-icons.ts
+++ b/src/core/workspace-lib/model-icons.ts
@@ -12,6 +12,8 @@ const MODEL_ICON_PATHS = {
 const MODEL_ICON_PATH_BY_MODEL_ID: Record<string, string> = {
   'gpt-image-2': MODEL_ICON_PATHS.openai,
   'kling-3': MODEL_ICON_PATHS.kling,
+  'kling-2.6-motion-control': MODEL_ICON_PATHS.kling,
+  'kling-3-motion-control': MODEL_ICON_PATHS.kling,
   'minimax-h3': MODEL_ICON_PATHS.minimax,
   'nano-banana': MODEL_ICON_PATHS.nanobanana,
   'nano-banana-pro': MODEL_ICON_PATHS.nanobanana,
diff --git a/src/routes/api/storage/upload.ts b/src/routes/api/storage/upload.ts
index 5c0256a..4467f17 100644
--- a/src/routes/api/storage/upload.ts
+++ b/src/routes/api/storage/upload.ts
@@ -4,8 +4,10 @@ import { getConfig } from '@/modules/config/service';
 import {
   claimGenerationUploadSlot,
   completeGenerationUploadSlot,
+  getGenerationUploadIntentEffectId,
   releaseGenerationUploadSlot,
 } from '@/core/effects/generation-upload-intent';
+import { getWorkspaceEffectRegistryEntryByEffectId } from '@/core/effects/effect-registry';
 import { S3Provider } from '@/core/workspace-storage/provider/s3';
 import type { StorageConfig } from '@/core/workspace-storage/types';
 import { DEFAULT_BEATAPI_BASE_URL } from '@/core/beatcanvas/providers/provider-config';
@@ -15,7 +17,9 @@ import {
   RequestBodyTooLargeError,
 } from '@/lib/request-body-limit';
 
-const MAX_FILE_BYTES = 50 * 1024 * 1024;
+const MAX_DEFAULT_FILE_BYTES = 50 * 1024 * 1024;
+const MAX_MOTION_IMAGE_BYTES = 10 * 1024 * 1024;
+const MAX_VIDEO_FILE_BYTES = 100 * 1024 * 1024;
 const MAX_MULTIPART_OVERHEAD_BYTES = 1024 * 1024;
 const BEATAPI_UPLOAD_TYPES = new Set([
   'image/png',
@@ -26,6 +30,13 @@ const BEATAPI_UPLOAD_TYPES = new Set([
   'audio/aac',
   'audio/mp4',
   'application/x-subrip',
+  'video/mp4',
+  'video/quicktime',
+]);
+
+const MOTION_CONTROL_MODELS = new Set([
+  'kling-2.6-motion-control',
+  'kling-3-motion-control',
 ]);
 
 const CUSTOM_STORAGE_TYPES = new Set([
@@ -197,7 +208,7 @@ async function POST({ request }: { request: Request }) {
     }
     const formData = await readRequestFormDataWithLimit(
       request,
-      MAX_FILE_BYTES + MAX_MULTIPART_OVERHEAD_BYTES
+      MAX_VIDEO_FILE_BYTES + MAX_MULTIPART_OVERHEAD_BYTES
     );
     const file = formData.get('file');
     const projectId = formData.get('projectId');
@@ -205,9 +216,18 @@ async function POST({ request }: { request: Request }) {
     if (!(file instanceof File)) {
       return Response.json({ error: 'file is required' }, { status: 400 });
     }
-    if (file.size <= 0 || file.size > MAX_FILE_BYTES) {
+    const isVideo =
+      file.type.startsWith('video/') || /\.(mp4|mov|webm)$/i.test(file.name);
+    const defaultMaxFileBytes = isVideo
+      ? MAX_VIDEO_FILE_BYTES
+      : MAX_DEFAULT_FILE_BYTES;
+    if (file.size <= 0 || file.size > defaultMaxFileBytes) {
       return Response.json(
-        { error: 'File must be between 1 byte and 50 MB' },
+        {
+          error: `File must be between 1 byte and ${
+            defaultMaxFileBytes / (1024 * 1024)
+          } MB`,
+        },
         { status: 413 }
       );
     }
@@ -232,6 +252,26 @@ async function POST({ request }: { request: Request }) {
     }
 
     const normalizedProjectId = authorizedProjectId;
+    const intentEffectId = await getGenerationUploadIntentEffectId({
+      intentId: authorizedIntent,
+      projectId: normalizedProjectId,
+    });
+    const intentModel = intentEffectId
+      ? getWorkspaceEffectRegistryEntryByEffectId(intentEffectId)?.id
+      : null;
+    const isMotionControl = Boolean(
+      intentModel && MOTION_CONTROL_MODELS.has(intentModel)
+    );
+    if (
+      isMotionControl &&
+      !isVideo &&
+      file.size > MAX_MOTION_IMAGE_BYTES
+    ) {
+      return Response.json(
+        { error: 'Kling Motion Control images must be 10 MB or smaller' },
+        { status: 413 }
+      );
+    }
     const slotId = await claimGenerationUploadSlot({
       intentId: authorizedIntent,
       projectId: normalizedProjectId,
@@ -256,7 +296,11 @@ async function POST({ request }: { request: Request }) {
     } | null = null;
     try {
       result =
-        storageMode === 's3'
+        isMotionControl
+          ? canUseBeatApi
+            ? await uploadToBeatApi(file)
+            : null
+          : storageMode === 's3'
           ? canUseCustomStorage
             ? await uploadToS3Storage({
                 file,
@@ -313,7 +357,7 @@ async function POST({ request }: { request: Request }) {
   } catch (error) {
     if (error instanceof RequestBodyTooLargeError) {
       return Response.json(
-        { error: 'Upload request exceeds the 50 MB file limit' },
+        { error: 'Upload request exceeds the 100 MB video limit' },
         { status: 413 }
       );
     }