feat(canvas): persist local assets and harden snapshots

Author: erickkkyt

README.md

@@ -37,16 +37,21 @@ Open `http://localhost:3020`. Home is the default route. Opening Studio or Canva
 ```text
 Studio / Canvas
   -> local server routes
+  -> imported files saved under data/project-assets and indexed in SQLite
   -> generation precheck and a one-time SQLite generation intent
-  -> just-in-time reference upload (only when Generate is confirmed)
+  -> just-in-time provider upload of the durable local reference
   -> BeatAPI image or video task API
   -> provider status polling
   -> local generation history and asset index
 ```
 
-The API key and storage credentials remain server-side. Project state and history live in the local SQLite database. Generated files remain at the public URLs returned by the provider and are indexed locally instead of being copied again.
+The API key and storage credentials remain server-side. Project state and history live in the local SQLite database. In local SQLite mode, imported image and video files are copied immediately into the project-owned `data/project-assets/<project-id>/` directory and indexed in SQLite before a card is added to the Canvas. Generated files remain at the public URLs returned by the provider and are indexed locally instead of being copied again.
 
-Selecting a local file creates a browser-local preview only. It does not upload anything. When the user confirms Generate, the server validates the project, model, prompt, concurrency, and BeatAPI connection, then creates a short-lived, one-time generation intent in SQLite. The intent fixes the project, model, and exact upload count. Uploaded URLs must be referenced by the same generation request, and the intent is consumed when the billable task is submitted. Uploaded inputs enter the project asset index only after BeatAPI accepts the task.
+Canvas state is saved as a complete project snapshot after changes, checked again every five seconds while dirty, and flushed when the page is hidden, refreshed, or closed. A populated snapshot cannot be replaced by an unconfirmed empty snapshot.
+
+Selecting or dragging in a local file does not send it to a provider, but it is persisted immediately on the user's own machine so a refresh, restart, or development hot reload cannot lose it. When the user confirms Generate, the server validates the project, model, prompt, concurrency, and BeatAPI connection, then creates a short-lived, one-time generation intent in SQLite. The durable local reference is uploaded to the configured provider storage only for that confirmed generation. The intent fixes the project, model, and exact upload count, and is consumed when the billable task is submitted.
+
+The `data/` directory is gitignored and contains both the SQLite database and local project assets. Back up or move the directory as one unit when migrating a workspace to another machine.
 
 Storage entitlement follows BeatAPI billing. The built-in provider is fixed to the official `https://api.beatapi.io` endpoint and uses the user's BeatAPI API key. Supported image, audio, and subtitle inputs go through BeatAPI Files; an official hosted deployment can preconfigure managed R2 for video inputs that Files does not accept through the separate `BEATAPI_MANAGED_R2_*` secrets. Self-hosters may instead provide their own Cloudflare R2 or other S3-compatible endpoint, bucket, credentials, and public URL through `R2_*`. The two credential sets never fall through to each other.
 

README.zh-CN.md

@@ -35,16 +35,21 @@ pnpm dev
 ```text
 Studio / Canvas
   -> 本地服务端接口
+  -> 导入文件立即保存到 data/project-assets，并写入 SQLite 素材索引
   -> 生成预检与 SQLite 一次性生成意图
-  -> 仅在确认生成后即时上传引用素材
+  -> 仅在确认生成后，把已持久化的本地引用上传到 Provider
   -> BeatAPI 图片或视频任务接口
   -> 轮询 Provider 状态
   -> 写入本地生成历史与素材索引
 ```
 
-API Key 与存储密钥只保留在服务端。项目和历史数据保存在本地 SQLite。Provider 返回的公开结果地址会直接进入本地素材索引，不强制重复复制。
+API Key 与存储密钥只保留在服务端。项目和历史数据保存在本地 SQLite。在本地 SQLite 模式下，导入的图片和视频会先复制到项目自己的 `data/project-assets/<project-id>/` 目录，并写入 SQLite 素材索引，然后才加入 Canvas。Provider 返回的公开结果地址会直接进入本地素材索引，不强制重复复制。
 
-用户选择本地文件时只会创建浏览器本地预览，不会上传。用户确认“生成”后，服务端先检查项目、模型、提示词、并发限制和 BeatAPI 连接，再在 SQLite 中创建短时、一次性的生成意图。意图会绑定项目、模型和准确上传数量；已上传地址必须出现在同一次生成请求中，并在提交付费任务时被消费。只有 BeatAPI 接受任务后，输入素材才会进入项目素材索引。
+Canvas 内容变化后会保存一份完整项目快照；存在未保存变化时，每 5 秒再检查一次，并在页面切到后台、刷新或关闭时强制落盘。已有内容的快照不会被未经确认的空快照覆盖。
+
+用户选择文件或从 Finder 拖入文件时，不会立刻发送给 Provider，但会立即持久化在用户自己的电脑上，因此刷新、重启或开发热更新都不会丢失。用户确认“生成”后，服务端先检查项目、模型、提示词、并发限制和 BeatAPI 连接，再在 SQLite 中创建短时、一次性的生成意图；只有这时，已经持久化的本地引用才会上传到配置好的 Provider 存储。意图会绑定项目、模型和准确上传数量，并在提交付费任务时被消费。
+
+`data/` 目录已被 Git 忽略，其中同时包含 SQLite 数据库和本地项目素材。把工作台迁移到另一台电脑时，应将整个目录一起备份或复制。
 
 存储权益跟随 BeatAPI 计费：内置 Provider 固定通过官方 `https://api.beatapi.io` 接口，并使用用户自己的 BeatAPI API Key。图片、音频和字幕通过 BeatAPI Files 进入托管存储；官方部署通过独立的 `BEATAPI_MANAGED_R2_*` Secret 预配置 R2，处理 Files 暂不支持的视频输入。源码用户也可以通过 `R2_*` 配置自己的 Cloudflare R2 或其他 S3 兼容存储。两组凭据不会互相回退。
 

messages/en.json

@@ -367,6 +367,7 @@
           "tokens": {
             "quality": "Quality",
             "fast": "Fast",
+            "lite": "Lite",
             "low": "Low",
             "medium": "Medium",
             "standard": "Standard",
@@ -528,6 +529,12 @@
         "triggerLabel": "Project assets",
         "title": "Project assets",
         "description": "Studio and Canvas share this same collection. Every completed generation and project upload appears here.",
+        "canvasHint": "Click an asset to add it, or drag it anywhere onto the canvas.",
+        "addToCanvas": "Add to canvas",
+        "openOriginal": "Open original",
+        "addedToCanvas": "Added to canvas",
+        "imageName": "Project image",
+        "videoName": "Project video",
         "loading": "Loading project assets...",
         "loadFailed": "Project assets could not be loaded.",
         "empty": "Generate or upload an asset to start this project collection.",

messages/zh.json

@@ -368,6 +368,7 @@
           "tokens": {
             "quality": "质量",
             "fast": "快速",
+            "lite": "轻量",
             "low": "低",
             "medium": "中",
             "standard": "标准",
@@ -529,6 +530,12 @@
         "triggerLabel": "项目素材",
         "title": "项目素材",
         "description": "Studio 与 Canvas 共用这组素材，项目内完成的生成结果和上传文件都会出现在这里。",
+        "canvasHint": "点击素材即可加入，或直接拖到画布上的任意位置。",
+        "addToCanvas": "加入画布",
+        "openOriginal": "查看原文件",
+        "addedToCanvas": "已加入画布",
+        "imageName": "项目图片",
+        "videoName": "项目视频",
         "loading": "正在加载项目素材...",
         "loadFailed": "暂时无法加载项目素材。",
         "empty": "生成或上传第一个素材，开始建立这个项目的素材集合。",

src/components/app/product-page-shell.tsx

@@ -156,7 +156,12 @@ export function ProductPageShell({
                   </Link>
                 </div>
               ) : null}
-              {projectId ? <ProjectAssetsDialog projectId={projectId} /> : null}
+              {projectId ? (
+                <ProjectAssetsDialog
+                  projectId={projectId}
+                  canAddToCanvas={workspaceMode === 'canvas'}
+                />
+              ) : null}
               <WorkspaceApiConfigDialog
                 providerId={envConfigs.generation_provider}
               />

src/components/app/project-assets-dialog.tsx

@@ -1,7 +1,16 @@
 'use client';
 
 import { useQuery } from '@tanstack/react-query';
-import { FolderOpen, Images, Loader2, Video } from 'lucide-react';
+import {
+  ExternalLink,
+  FolderOpen,
+  Images,
+  Loader2,
+  MousePointer2,
+  Plus,
+  Video,
+} from 'lucide-react';
+import { useState } from 'react';
 
 import {
   Dialog,
@@ -17,21 +26,67 @@ import {
 } from '@/core/workspace-lib/app/workspace-client-api';
 import { recentAssetsKeys } from '@/core/workspace-lib/app/workspace-query-keys';
 import { useTranslations } from '@/core/workspace-lib/shims/next-intl';
+import {
+  PROJECT_ASSET_DRAG_MIME,
+  PROJECT_ASSET_INSERT_EVENT,
+  type ProjectAssetInsertDetail,
+  type ProjectAssetTransfer,
+} from '@/core/beatcanvas/project-asset-transfer';
 
 function AssetTile({
   asset,
   mediaType,
+  projectId,
+  canAddToCanvas,
+  onAdded,
+  addLabel,
+  openLabel,
 }: {
   asset: RecentAsset;
   mediaType: 'image' | 'video';
+  projectId: string;
+  canAddToCanvas: boolean;
+  onAdded: () => void;
+  addLabel: string;
+  openLabel: string;
 }) {
+  const transfer: ProjectAssetTransfer = {
+    ...asset,
+    projectId,
+    mediaType,
+  };
+
+  const addToCanvas = () => {
+    if (!canAddToCanvas) return;
+    window.dispatchEvent(
+      new CustomEvent<ProjectAssetInsertDetail>(PROJECT_ASSET_INSERT_EVENT, {
+        detail: { asset: transfer },
+      })
+    );
+    onAdded();
+  };
+
   return (
-    <a
-      href={asset.publicUrl}
-      target="_blank"
-      rel="noreferrer"
-      className="group relative aspect-square overflow-hidden rounded-[14px] border border-white/[0.08] bg-[#09090b] transition hover:-translate-y-0.5 hover:border-white/[0.22]"
-      title={asset.filename || undefined}
+    <div
+      draggable={canAddToCanvas}
+      onDragStart={(event) => {
+        if (!canAddToCanvas) {
+          event.preventDefault();
+          return;
+        }
+        event.dataTransfer.effectAllowed = 'copy';
+        event.dataTransfer.setData(
+          PROJECT_ASSET_DRAG_MIME,
+          JSON.stringify(transfer)
+        );
+      }}
+      onDragEnd={(event) => {
+        if (event.dataTransfer.dropEffect === 'copy') onAdded();
+      }}
+      className={`group relative aspect-square overflow-hidden rounded-[14px] border border-white/[0.08] bg-[#09090b] transition hover:-translate-y-0.5 hover:border-white/[0.22] ${
+        canAddToCanvas ? 'cursor-grab active:cursor-grabbing' : ''
+      }`}
+      title={asset.filename || addLabel}
     >
       {mediaType === 'video' ? (
         <video
@@ -49,16 +104,59 @@ function AssetTile({
         />
       )}
       {mediaType === 'video' ? (
-        <span className="absolute bottom-2 right-2 grid size-7 place-items-center rounded-full border border-white/15 bg-black/65 text-white backdrop-blur">
+        <span className="pointer-events-none absolute bottom-2 left-2 grid size-7 place-items-center rounded-full border border-white/15 bg-black/65 text-white backdrop-blur">
           <Video className="size-3.5" />
         </span>
       ) : null}
-    </a>
+
+      {canAddToCanvas ? (
+        <button
+          type="button"
+          onClick={addToCanvas}
+          className="absolute inset-0 flex items-end justify-center bg-gradient-to-t from-black/80 via-black/5 to-transparent px-2 pb-2 opacity-0 transition duration-200 group-hover:opacity-100 group-focus-within:opacity-100"
+          aria-label={`${addLabel}: ${asset.filename || asset.id}`}
+        >
+          <span className="inline-flex h-7 items-center gap-1 rounded-full border border-white/15 bg-white/12 px-2.5 text-[10px] font-semibold text-white shadow-lg backdrop-blur-md">
+            <Plus className="size-3" />
+            {addLabel}
+          </span>
+        </button>
+      ) : (
+        <a
+          href={asset.publicUrl}
+          target="_blank"
+          rel="noreferrer"
+          className="absolute inset-0"
+          aria-label={`${openLabel}: ${asset.filename || asset.id}`}
+        />
+      )}
+
+      {canAddToCanvas ? (
+        <a
+          href={asset.publicUrl}
+          target="_blank"
+          rel="noreferrer"
+          onClick={(event) => event.stopPropagation()}
+          className="absolute right-2 top-2 z-10 grid size-7 place-items-center rounded-full border border-white/15 bg-black/65 text-white/75 opacity-0 backdrop-blur transition hover:text-white group-hover:opacity-100 group-focus-within:opacity-100"
+          aria-label={`${openLabel}: ${asset.filename || asset.id}`}
+          title={openLabel}
+        >
+          <ExternalLink className="size-3.5" />
+        </a>
+      ) : null}
+    </div>
   );
 }
 
-export function ProjectAssetsDialog({ projectId }: { projectId: string }) {
+export function ProjectAssetsDialog({
+  projectId,
+  canAddToCanvas = false,
+}: {
+  projectId: string;
+  canAddToCanvas?: boolean;
+}) {
   const t = useTranslations('AppShell.header.projectAssets');
+  const [open, setOpen] = useState(false);
   const assetsQuery = useQuery({
     queryKey: recentAssetsKeys.lists(projectId),
     queryFn: () => fetchRecentAssets(projectId),
@@ -69,7 +167,7 @@ export function ProjectAssetsDialog({ projectId }: { projectId: string }) {
   const total = images.length + videos.length;
 
   return (
-    <Dialog>
+    <Dialog modal={false} open={open} onOpenChange={setOpen}>
       <DialogTrigger
         aria-label={t('triggerLabel')}
         title={t('triggerLabel')}
@@ -86,7 +184,10 @@ export function ProjectAssetsDialog({ projectId }: { projectId: string }) {
         ) : null}
       </DialogTrigger>
 
-      <DialogContent className="max-h-[82vh] overflow-hidden rounded-[28px] border border-white/10 bg-[#111214] p-0 text-[#f5f5f7] shadow-[0_34px_110px_rgba(0,0,0,0.62)] ring-0 sm:max-w-[760px] [&_[data-slot=dialog-close]]:right-4 [&_[data-slot=dialog-close]]:top-4 [&_[data-slot=dialog-close]]:text-white/45 [&_[data-slot=dialog-close]]:hover:bg-white/[0.07] [&_[data-slot=dialog-close]]:hover:text-white">
+      <DialogContent
+        showOverlay={false}
+        className="max-h-[82vh] overflow-hidden rounded-[28px] border border-white/10 bg-[#111214] p-0 text-[#f5f5f7] shadow-[0_34px_110px_rgba(0,0,0,0.62)] ring-0 sm:max-w-[760px] [&_[data-slot=dialog-close]]:right-4 [&_[data-slot=dialog-close]]:top-4 [&_[data-slot=dialog-close]]:text-white/45 [&_[data-slot=dialog-close]]:hover:bg-white/[0.07] [&_[data-slot=dialog-close]]:hover:text-white"
+      >
         <DialogHeader className="border-b border-white/[0.08] px-6 pb-5 pt-6 text-left">
           <span className="mb-2 grid size-10 place-items-center rounded-[13px] border border-[#ff7a33]/25 bg-[#ff7a33]/10 text-[#ff8b4d]">
             <FolderOpen className="size-[18px]" />
@@ -97,6 +198,12 @@ export function ProjectAssetsDialog({ projectId }: { projectId: string }) {
           <DialogDescription className="max-w-xl text-[13px] leading-5 text-white/48">
             {t('description')}
           </DialogDescription>
+          {canAddToCanvas ? (
+            <div className="mt-2 inline-flex w-fit items-center gap-2 rounded-full border border-[#ff7a33]/18 bg-[#ff7a33]/[0.07] px-3 py-1.5 text-[11px] font-medium text-[#ffad7e]">
+              <MousePointer2 className="size-3.5" />
+              {t('canvasHint')}
+            </div>
+          ) : null}
         </DialogHeader>
 
         <div className="max-h-[60vh] overflow-y-auto px-5 py-5 sm:px-6">
@@ -137,6 +244,11 @@ export function ProjectAssetsDialog({ projectId }: { projectId: string }) {
                         key={asset.id}
                         asset={asset}
                         mediaType="image"
+                        projectId={projectId}
+                        canAddToCanvas={canAddToCanvas}
+                        onAdded={() => setOpen(false)}
+                        addLabel={t('addToCanvas')}
+                        openLabel={t('openOriginal')}
                       />
                     ))}
                   </div>
@@ -154,6 +266,11 @@ export function ProjectAssetsDialog({ projectId }: { projectId: string }) {
                         key={asset.id}
                         asset={asset}
                         mediaType="video"
+                        projectId={projectId}
+                        canAddToCanvas={canAddToCanvas}
+                        onAdded={() => setOpen(false)}
+                        addLabel={t('addToCanvas')}
+                        openLabel={t('openOriginal')}
                       />
                     ))}
                   </div>

src/components/beatcanvas/beatcanvas-composer-shell.test.tsx

@@ -90,6 +90,7 @@ const labels = {
   qualityOptionLabel: 'Quality',
   tokenQualityLabel: 'Quality',
   tokenFastLabel: 'Fast',
+  tokenLiteLabel: 'Lite',
   tokenLowLabel: 'Low',
   tokenMediumLabel: 'Medium',
   tokenStandardLabel: 'Standard',

src/components/beatcanvas/beatcanvas-composer-utils.ts

@@ -34,6 +34,7 @@ export const normalizeComposerToken = (
     CanvasLabels,
     | 'tokenQualityLabel'
     | 'tokenFastLabel'
+    | 'tokenLiteLabel'
     | 'tokenLowLabel'
     | 'tokenMediumLabel'
     | 'tokenStandardLabel'
@@ -56,6 +57,8 @@ export const normalizeComposerToken = (
       return labels?.tokenQualityLabel ?? 'Quality';
     case 'fast':
       return labels?.tokenFastLabel ?? 'Fast';
+    case 'lite':
+      return labels?.tokenLiteLabel ?? 'Lite';
     case 'low':
       return labels?.tokenLowLabel ?? 'Low';
     case 'medium':

src/components/beatcanvas/beatcanvas-front-layer-context.tsx

@@ -79,6 +79,7 @@ type CanvasLabels = {
   qualityOptionLabel: string;
   tokenQualityLabel: string;
   tokenFastLabel: string;
+  tokenLiteLabel: string;
   tokenLowLabel: string;
   tokenMediumLabel: string;
   tokenStandardLabel: string;
@@ -141,7 +142,6 @@ export type BeatCanvasFrontLayerValue = {
   }) => void;
   onSelectedShapeIdsChange: (shapeIds: string[]) => void;
   onSelectedCanvasCardIdsChange: (shapeIds: string[]) => void;
-  onCanvasShapeIdsChange: (shapeIds: string[]) => void;
   onActiveComposerCardIdChange: (cardId: string | null) => void;
   onDraftPromptChange: (draftId: string, prompt: string) => void;
   onDraftTaskTypeChange: (

src/components/beatcanvas/beatcanvas-front-layer.tsx

@@ -100,7 +100,6 @@ export function BeatCanvasFrontLayer() {
     onUndoCanvas,
     onRedoCanvas,
     onActiveComposerCardIdChange,
-    onCanvasShapeIdsChange,
     onSelectedShapeIdsChange,
     onDraftAspectRatioChange,
     onDraftBackgroundSourceChange,
@@ -154,11 +153,6 @@ export function BeatCanvasFrontLayer() {
     [cards, selectedShapeIds]
   );
   const selectedCardIdsKey = selectedCardIds.join(',');
-  const currentShapeIds = useCanvasEngineValue(
-    (currentEditor) =>
-      currentEditor.getCurrentPageShapes().map((shape) => shape.id),
-    [cards]
-  );
   const zoomLevel = useCanvasEngineValue(
     (currentEditor) =>
       Math.round(
@@ -197,10 +191,6 @@ export function BeatCanvasFrontLayer() {
     // eslint-disable-next-line react-hooks/exhaustive-deps -- only fire when the actual card IDs change, not on every cards object update
   }, [onSelectedCanvasCardIdsChange, selectedCardIdsKey]);
 
-  useEffect(() => {
-    onCanvasShapeIdsChange(currentShapeIds);
-  }, [currentShapeIds, onCanvasShapeIdsChange]);
-
   useEffect(() => {
     if (
       typeof editor.getCameraOptions !== 'function' ||
@@ -808,7 +798,7 @@ export function BeatCanvasFrontLayer() {
         </button>
       </div>
 
-      {currentShapeIds.length === 0 ? (
+      {Object.keys(cards).length === 0 ? (
         <div className="absolute inset-x-0 top-[46%] z-10 flex -translate-y-1/2 justify-center px-6">
           <StudioStartHere />
         </div>