@arronqzy/react-view 1.0.15 → 1.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arronqzy/react-view",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "files": [
     "src",
     "dist",
@@ -34,10 +34,10 @@
     "@arronqzy/blueprint-dsl": "1.0.8",
     "@arronqzy/i18n": "0.1.7",
     "@arronqzy/react-blueprint": "1.0.9",
-    "@arronqzy/view-scene3d": "0.1.2",
     "@arronqzy/rx-store": "1.0.5",
+    "@arronqzy/webllm-assistant": "0.1.9",
     "@arronqzy/view-table": "0.1.5",
-    "@arronqzy/webllm-assistant": "0.1.9"
+    "@arronqzy/view-scene3d": "0.1.2"
   },
   "devDependencies": {
     "@types/react": "^19.0.1",

package/readme.md

@@ -10,6 +10,7 @@ Abuilder 的**视图编辑器** React 包，提供可视化画布、图层、物
 - **Scope 模版**：节点属性支持 `{scope.xxx}` 表达式与解析预览
 - **工作区**：IndexedDB 持久化、多项目切换、同步与在线预览
 - **蓝图联动**：与 `@arronqzy/react-blueprint` 分屏编辑，运行时 Scope 回写视图
+- **宿主集成**：工作区事件订阅、预览快照、外部工作区数据加载
 
 ## 安装
 
@@ -29,21 +30,42 @@ import "@arronqzy/react-view/styles.css";
 
 ```tsx
 import { ReactViewPanel } from "@arronqzy/react-view";
+import type { WorkspaceProjectRecord } from "@arronqzy/react-view";
 import "@arronqzy/react-view/styles.css";
 
-export function Editor() {
-  return <ReactViewPanel className="h-screen" initialZoom={1} />;
+export function Editor({ workspace }: { workspace?: WorkspaceProjectRecord | null }) {
+  return (
+    <ReactViewPanel
+      className="h-screen"
+      initialZoom={1}
+      initialWorkspace={workspace}
+    />
+  );
 }
 ```
 
+| `ReactViewPanel` 参数 | 说明 | 默认值 |
+|----------------------|------|--------|
+| `className` | 根节点 class | — |
+| `initialZoom` | 初始缩放 | `1` |
+| `initialWorkspace` | 外部传入的完整工作区，挂载后自动加载 | — |
+
 ### 在线预览
 
+按工作区 ID 从 IndexedDB / 缓存加载：
+
 ```tsx
 import { ReactViewOnlinePreview } from "@arronqzy/react-view";
 
 <ReactViewOnlinePreview projectId="your-project-id" />
 ```
 
+直接传入工作区数据（无需 IndexedDB）：
+
+```tsx
+<ReactViewOnlinePreview workspace={savedWorkspace} />
+```
+
 URL 参数解析：
 
 ```ts
@@ -52,6 +74,70 @@ import { parseOnlinePreviewSearchParams } from "@arronqzy/react-view";
 const params = parseOnlinePreviewSearchParams("?preview=online&projectId=xxx");
 ```
 
+| `ReactViewOnlinePreview` 参数 | 说明 |
+|------------------------------|------|
+| `projectId` | 从 IndexedDB 加载的工作区 ID |
+| `workspace` | 直接传入的完整工作区数据（优先于 `projectId`） |
+| `previewInstanceId` | 预览实例 ID（可选） |
+
+### 工作区事件订阅
+
+监听工作区创建与同步，回调携带**完整工作区数据**（面板 + 蓝图），便于持久化到自有后端：
+
+```ts
+import {
+  addEventSubscription,
+  AbuilderEvents,
+  type WorkspaceData,
+} from "@arronqzy/react-view";
+
+const addSub = addEventSubscription(
+  AbuilderEvents.workspaceAdd,
+  async (workspace: WorkspaceData) => {
+    await saveToServer(workspace);
+  }
+);
+
+const syncSub = addEventSubscription(
+  AbuilderEvents.workspaceSync,
+  async (workspace) => {
+    await saveToServer(workspace);
+  }
+);
+
+addSub.unsubscribe();
+syncSub.unsubscribe();
+```
+
+| 事件 | 常量 | 触发时机 |
+|------|------|----------|
+| `workspace:add` | `AbuilderEvents.workspaceAdd` | 创建工作区成功 |
+| `workspace:sync` | `AbuilderEvents.workspaceSync` | 同步工作区成功 |
+
+回调参数类型为 `WorkspaceData`（即 `WorkspaceProjectRecord`），字段包括：`id`、`name`、`createdAt`、`updatedAt`、`panelState`、`blueprintDocument`、`blueprintMeta`、`productName`、`titleIconDataUrl`。
+
+### 获取预览快照
+
+在编辑器或在线预览页已挂载时，截取当前预览画面为 base64（data URL），可用于缩略图：
+
+```ts
+import { getPreviewSnapshot } from "@arronqzy/react-view";
+
+const dataUrl = await getPreviewSnapshot({
+  maxWidth: 320,
+  maxHeight: 180,
+  mimeType: "image/jpeg",
+  quality: 0.85,
+});
+```
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `maxWidth` / `maxHeight` | 等比缩放上限 | 不限制 |
+| `mimeType` | `"image/png"` 或 `"image/jpeg"` | `"image/png"` |
+| `quality` | JPEG 质量 0–1 | `0.92` |
+| `backgroundColor` | 背景色 | `"#ffffff"` |
+
 ## 核心导出
 
 | 导出 | 说明 |
@@ -59,8 +145,14 @@ const params = parseOnlinePreviewSearchParams("?preview=online&projectId=xxx");
 | `ReactViewPanel` | 主编辑面板（画布 + 配置侧栏 + 蓝图分屏） |
 | `ReactViewOnlinePreview` | 只读在线预览页 |
 | `parseOnlinePreviewSearchParams` | 解析预览 URL 参数 |
+| `addEventSubscription` | 订阅工作区事件，返回 `{ unsubscribe }` |
+| `AbuilderEvents` | 工作区事件名常量 |
+| `getPreviewSnapshot` | 获取预览画面 base64 缩略图 |
+| `WorkspaceData` / `WorkspaceProjectRecord` | 完整工作区数据类型 |
 | `createView` / `createAction` 等 | 视图 DSL 与指令扩展（`src/core`） |
 
+相关类型：`AbuilderEventName`、`AbuilderEventPayloadMap`、`WorkspaceAddEventPayload`、`WorkspaceSyncEventPayload`、`GetPreviewSnapshotOptions`。
+
 ## 样式与 Tailwind
 
 本包内置 Tailwind 配置，构建产物为 `dist/styles.css`：

package/src/index.ts

@@ -4,4 +4,18 @@ export * from "./core/instructions";
 export * from "./core/nodePool";
 export * from "./core/signal";
 export * from "./core/template";
-export * from "./panel";
+export * from "./panel";
+export {
+  addEventSubscription,
+  AbuilderEvents,
+} from "./panel/library/event-subscription";
+export type {
+  AbuilderEventName,
+  AbuilderEventPayloadMap,
+  WorkspaceAddEventPayload,
+  WorkspaceSyncEventPayload,
+  WorkspaceData,
+} from "./panel/library/event-subscription";
+export type { WorkspaceProjectRecord } from "./panel/library/workspace-project-db";
+export { getPreviewSnapshot } from "./panel/library/preview-snapshot";
+export type { GetPreviewSnapshotOptions } from "./panel/library/preview-snapshot";

package/src/panel/ReactViewOnlinePreview.tsx

@@ -39,12 +39,17 @@ import {
   resolvePreviewLayerElements,
 } from "./utils/panelStateIO";
 import { applyPreviewSceneFill, readOutputScale } from "./utils/outputScale";
+import { capturePreviewSceneElement } from "./library/capture-preview-snapshot";
+import { registerPreviewSnapshotProvider } from "./library/preview-snapshot";
 
 const PREVIEW_BOOT_PHASES: PageLifecyclePhase[] = ["mounted"];
 
 export type ReactViewOnlinePreviewProps = {
-  projectId: string;
+  /** 从 IndexedDB / 缓存按 ID 加载工作区；与 `workspace` 二选一，优先使用 `workspace` */
+  projectId?: string;
   previewInstanceId?: string;
+  /** 直接传入完整工作区数据，用于外部持久化后预览 */
+  workspace?: WorkspaceProjectRecord | null;
 };
 
 function applyTitleIcon(titleIconDataUrl?: string) {
@@ -68,6 +73,7 @@ async function loadWorkspaceRecord(projectId: string): Promise<WorkspaceProjectR
 export function ReactViewOnlinePreview({
   projectId,
   previewInstanceId,
+  workspace = null,
 }: ReactViewOnlinePreviewProps) {
   const { t } = useI18n();
 
@@ -84,53 +90,74 @@ export function ReactViewOnlinePreview({
   const [fillScale, setFillScale] = useState({ scaleX: 1, scaleY: 1 });
 
   const sceneRef = useRef<HTMLDivElement | null>(null);
-
-  const layers = useMemo(
-    () => (panelState ? parsePanelLayers(panelState) : []),
-    [panelState]
-  );
-  const activeLayerId = useMemo(
-    () => (panelState ? getActiveLayerId(panelState) : "layer-1"),
-    [panelState]
-  );
-  const allElements = useMemo(
-    () => (panelState ? parseAllPanelElements(panelState) : []),
-    [panelState]
+  const resolvedProjectId = workspace?.id ?? projectId ?? "";
+
+  const applyWorkspaceRecord = useCallback(
+    (record: WorkspaceProjectRecord) => {
+      const normalized = normalizeImportedPanelState(record.panelState);
+      if (!normalized) {
+        setLoadError(t("panel.messages.workspaceDataInvalid"));
+        setPanelState(null);
+        return false;
+      }
+
+      setLoadError(null);
+      clearViewElementScopes();
+      setPanelState(normalized);
+      setBlueprintGraph(BlueprintGraph.fromDocument(record.blueprintDocument));
+      document.title =
+        record.productName.trim() || record.name || t("panel.workspace.previewDocTitle");
+      applyTitleIcon(record.titleIconDataUrl);
+      setProjectRevision((v) => v + 1);
+      return true;
+    },
+    [t]
   );
 
   const loadProject = useCallback(async () => {
-    const record = await loadWorkspaceRecord(projectId);
-    if (!record) {
+    if (workspace) {
+      applyWorkspaceRecord(workspace);
+      return;
+    }
+    if (!projectId) {
       setLoadError(t("panel.messages.workspaceNotFound"));
       setPanelState(null);
       return;
     }
 
-    const normalized = normalizeImportedPanelState(record.panelState);
-    if (!normalized) {
-      setLoadError(t("panel.messages.workspaceDataInvalid"));
+    const record = await loadWorkspaceRecord(projectId);
+    if (!record) {
+      setLoadError(t("panel.messages.workspaceNotFound"));
       setPanelState(null);
       return;
     }
 
-    setLoadError(null);
-    clearViewElementScopes();
-    setPanelState(normalized);
-    setBlueprintGraph(BlueprintGraph.fromDocument(record.blueprintDocument));
-    document.title = record.productName.trim() || record.name || t("panel.workspace.previewDocTitle");
-    applyTitleIcon(record.titleIconDataUrl);
-    setProjectRevision((v) => v + 1);
-  }, [projectId]);
+    applyWorkspaceRecord(record);
+  }, [applyWorkspaceRecord, projectId, t, workspace]);
 
   useEffect(() => {
     void loadProject();
   }, [loadProject]);
 
   useEffect(() => {
+    if (workspace || !projectId) return;
     return subscribeWorkspaceProjectUpdates(projectId, () => {
       void loadProject();
     });
-  }, [loadProject, projectId]);
+  }, [loadProject, projectId, workspace]);
+
+  const layers = useMemo(
+    () => (panelState ? parsePanelLayers(panelState) : []),
+    [panelState]
+  );
+  const activeLayerId = useMemo(
+    () => (panelState ? getActiveLayerId(panelState) : "layer-1"),
+    [panelState]
+  );
+  const allElements = useMemo(
+    () => (panelState ? parseAllPanelElements(panelState) : []),
+    [panelState]
+  );
 
   useEffect(() => {
     let cancelled = false;
@@ -270,6 +297,33 @@ export function ReactViewOnlinePreview({
     return () => window.removeEventListener("resize", applySceneFit);
   }, [applySceneFit]);
 
+  useEffect(() => {
+    if (!layoutReady || !sceneRef.current) {
+      registerPreviewSnapshotProvider(null);
+      return;
+    }
+    registerPreviewSnapshotProvider(async () => {
+      const scene = sceneRef.current;
+      if (!scene) return null;
+      const width = outputScale
+        ? sceneBounds.width
+        : sceneBounds.width * fillScale.scaleX;
+      const height = outputScale
+        ? sceneBounds.height
+        : sceneBounds.height * fillScale.scaleY;
+      return capturePreviewSceneElement(scene, width, height);
+    });
+    return () => registerPreviewSnapshotProvider(null);
+  }, [
+    fillScale.scaleX,
+    fillScale.scaleY,
+    layoutReady,
+    layoutRevision,
+    outputScale,
+    sceneBounds.height,
+    sceneBounds.width,
+  ]);
+
   const noopUpdate = useCallback((_id: string, _patch: Partial<PanelElement>) => {}, []);
   const noopSelect = useCallback((_ids: string[]) => {}, []);
   const onTableCellAction = useCallback<TableCellActionHandler>(
@@ -333,7 +387,7 @@ export function ReactViewOnlinePreview({
     <div
       className="min-h-[100vh] w-full overflow-hidden bg-white text-gray-900"
       data-preview-mode="online"
-      data-project-id={projectId}
+      data-project-id={resolvedProjectId}
       data-preview-instance-id={previewInstanceId ?? ""}
       data-preview-node-count={String(displayElements.length)}
     >

package/src/panel/ReactViewPanel.tsx

@@ -16,6 +16,10 @@ import { SelectLayer } from "./components/SelectLayer";
 import { MoveableLayer } from "./components/MoveableLayer";
 import { buildChartOption, CHART_TYPES } from "./utils/chartOptionBuilder";
 import { readOutputScale, writeOutputScale } from "./utils/outputScale";
+import {
+  captureEditorPreviewSnapshot,
+  registerPreviewSnapshotProvider,
+} from "./library/preview-snapshot";
 import {
   assertFileSize,
   parseJsonText,
@@ -356,11 +360,14 @@ function shouldClearSelectionOnBlank(target: HTMLElement | null) {
 export type ReactViewPanelProps = {
   initialZoom?: number;
   className?: string;
+  /** 外部传入的完整工作区数据，挂载后自动渲染 */
+  initialWorkspace?: WorkspaceProjectRecord | null;
 };
 
 export function ReactViewPanel({
   initialZoom = 1,
   className,
+  initialWorkspace = null,
 }: ReactViewPanelProps) {
   const { t, locale, setLocale } = useI18n();
   const messages = useMemo(() => getPanelMessages(t), [t]);
@@ -1253,8 +1260,22 @@ export function ReactViewPanel({
     setTitleIconDataUrl,
     panelRevision: `${historyCursor}|${allElements.length}`,
     onProjectApplied: handleWorkspaceProjectApplied,
+    initialWorkspace,
   });
 
+  useEffect(() => {
+    registerPreviewSnapshotProvider(async () => {
+      return captureEditorPreviewSnapshot({
+        canvasRoot: canvasRef.current,
+        allElements,
+        layers,
+        activeLayerId,
+        outputScale: readOutputScale(),
+      });
+    });
+    return () => registerPreviewSnapshotProvider(null);
+  }, [activeLayerId, allElements, canvasEl, layers]);
+
   const { triggerBlueprintNode, emitViewEvent, firedLifecyclePhases } = useBlueprintPageLifecycle({
     graph: blueprintGraph,
     active: blueprintOpen,

package/src/panel/hooks/useWorkspaceProjects.ts

@@ -20,6 +20,7 @@ import {
   type WorkspaceSnapshot,
 } from "../library/workspace-snapshot";
 import { runBusyTask } from "../utils/async-work";
+import { AbuilderEvents, emitAbuilderEvent } from "../library/event-subscription";
 
 export type UseWorkspaceProjectsOptions = {
   exportPanelData: () => State;
@@ -36,6 +37,8 @@ export type UseWorkspaceProjectsOptions = {
   panelRevision: unknown;
   /** 工作区记录应用到编辑器后的回调（用于恢复蓝图面板等 UI 状态） */
   onProjectApplied?: (record: WorkspaceProjectRecord) => void;
+  /** 外部传入的初始工作区，挂载后自动加载（不触发 onProjectApplied） */
+  initialWorkspace?: WorkspaceProjectRecord | null;
 };
 
 export function buildOnlinePreviewUrl(projectId: string): string {
@@ -64,6 +67,7 @@ export function useWorkspaceProjects({
   setTitleIconDataUrl,
   panelRevision,
   onProjectApplied,
+  initialWorkspace,
 }: UseWorkspaceProjectsOptions) {
   const { t } = useI18nOptional();
   const [projects, setProjects] = useState<WorkspaceProjectListItem[]>([]);
@@ -138,7 +142,7 @@ export function useWorkspaceProjects({
   ]);
 
   const applyProjectRecord = useCallback(
-    (record: WorkspaceProjectRecord) => {
+    (record: WorkspaceProjectRecord, options?: { notifyApplied?: boolean }) => {
       const blueprintDocument =
         record.blueprintDocument ?? BlueprintGraph.empty().document;
       const blueprintMeta: BlueprintMetaDraft = {
@@ -161,11 +165,13 @@ export function useWorkspaceProjects({
       });
       syncedPanelRevisionRef.current = panelRevision;
       pendingRevisionSyncRef.current = true;
-      onProjectApplied?.({
-        ...record,
-        blueprintDocument,
-        blueprintMeta,
-      });
+      if (options?.notifyApplied !== false) {
+        onProjectApplied?.({
+          ...record,
+          blueprintDocument,
+          blueprintMeta,
+        });
+      }
     },
     [
       importPanelData,
@@ -179,6 +185,15 @@ export function useWorkspaceProjects({
     ]
   );
 
+  const initialWorkspaceAppliedKeyRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (!initialWorkspace?.id) return;
+    const key = `${initialWorkspace.id}:${initialWorkspace.updatedAt}`;
+    if (initialWorkspaceAppliedKeyRef.current === key) return;
+    initialWorkspaceAppliedKeyRef.current = key;
+    applyProjectRecord(initialWorkspace, { notifyApplied: false });
+  }, [applyProjectRecord, initialWorkspace]);
+
   const persistProject = useCallback(
     async (options: { id?: string; name: string; createdAt?: number }) => {
       const snapshot = cloneWorkspaceSnapshot(buildCurrentSnapshot());
@@ -217,6 +232,7 @@ export function useWorkspaceProjects({
     return runBusyTask(t("common.savingWorkspace"), async () => {
       const name = resolveProjectName();
       const record = await persistProject({ name });
+      emitAbuilderEvent(AbuilderEvents.workspaceAdd, record);
       return { name, id: record.id };
     });
   }, [persistProject, resolveProjectName, t]);
@@ -265,11 +281,12 @@ export function useWorkspaceProjects({
         throw new Error(t("panel.messages.workspaceNotFound"));
       }
       const name = resolveProjectName() || existing.name;
-      await persistProject({
+      const record = await persistProject({
         id: activeProjectId,
         name,
         createdAt: existing.createdAt,
       });
+      emitAbuilderEvent(AbuilderEvents.workspaceSync, record);
       return name;
     });
   }, [activeProjectId, persistProject, refreshProjects, resolveProjectName, t]);

package/src/panel/library/capture-preview-snapshot.ts

@@ -0,0 +1,300 @@
+const STYLE_PROPS = [
+  "display",
+  "position",
+  "left",
+  "top",
+  "width",
+  "height",
+  "margin",
+  "padding",
+  "border",
+  "borderRadius",
+  "background",
+  "backgroundColor",
+  "backgroundImage",
+  "backgroundSize",
+  "backgroundPosition",
+  "backgroundRepeat",
+  "color",
+  "fontFamily",
+  "fontSize",
+  "fontWeight",
+  "fontStyle",
+  "lineHeight",
+  "textAlign",
+  "textDecoration",
+  "letterSpacing",
+  "wordBreak",
+  "overflow",
+  "opacity",
+  "boxSizing",
+  "flexDirection",
+  "alignItems",
+  "justifyContent",
+  "gap",
+  "gridTemplateColumns",
+  "gridTemplateRows",
+  "objectFit",
+  "filter",
+  "boxShadow",
+  "transform",
+  "transformOrigin",
+  "zIndex",
+] as const;
+
+function loadImage(src: string): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => resolve(img);
+    img.onerror = () => reject(new Error("image-load-failed"));
+    img.src = src;
+  });
+}
+
+function inlineComputedStyles(source: Element, target: Element) {
+  if (!(source instanceof HTMLElement) || !(target instanceof HTMLElement)) return;
+  const computed = window.getComputedStyle(source);
+  for (const prop of STYLE_PROPS) {
+    const value = computed.getPropertyValue(
+      prop.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`)
+    );
+    if (value) {
+      target.style.setProperty(
+        prop.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`),
+        value
+      );
+    }
+  }
+  const sourceChildren = Array.from(source.children);
+  const targetChildren = Array.from(target.children);
+  sourceChildren.forEach((child, index) => {
+    const targetChild = targetChildren[index];
+    if (child && targetChild) inlineComputedStyles(child, targetChild);
+  });
+}
+
+function replaceCanvasesInClone(source: Element, clone: Element) {
+  const sourceCanvases = Array.from(source.querySelectorAll("canvas"));
+  const cloneCanvases = Array.from(clone.querySelectorAll("canvas"));
+  sourceCanvases.forEach((srcCanvas, index) => {
+    const clonedCanvas = cloneCanvases[index];
+    if (!clonedCanvas) return;
+    try {
+      const dataUrl = srcCanvas.toDataURL("image/png");
+      const img = document.createElement("img");
+      img.src = dataUrl;
+      img.style.width = "100%";
+      img.style.height = "100%";
+      img.style.objectFit = "fill";
+      img.style.display = "block";
+      clonedCanvas.replaceWith(img);
+    } catch {
+      clonedCanvas.remove();
+    }
+  });
+}
+
+async function nodeToDataUrlViaSvg(node: HTMLElement, width: number, height: number): Promise<string> {
+  const clone = node.cloneNode(true) as HTMLElement;
+  inlineComputedStyles(node, clone);
+  replaceCanvasesInClone(node, clone);
+  clone.style.width = `${width}px`;
+  clone.style.height = `${height}px`;
+  clone.style.margin = "0";
+  clone.style.position = "relative";
+  clone.style.left = "0";
+  clone.style.top = "0";
+  clone.style.transform = "none";
+
+  const wrapper = document.createElement("div");
+  wrapper.setAttribute("xmlns", "http://www.w3.org/1999/xhtml");
+  wrapper.style.width = `${width}px`;
+  wrapper.style.height = `${height}px`;
+  wrapper.style.overflow = "hidden";
+  wrapper.style.background = "#ffffff";
+  wrapper.appendChild(clone);
+
+  const serialized = new XMLSerializer().serializeToString(wrapper);
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+    <foreignObject width="100%" height="100%">
+      ${serialized}
+    </foreignObject>
+  </svg>`;
+  const blob = new Blob([svg], { type: "image/svg+xml;charset=utf-8" });
+  const url = URL.createObjectURL(blob);
+  try {
+    const img = await loadImage(url);
+    const canvas = document.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) throw new Error("canvas-context-failed");
+    ctx.drawImage(img, 0, 0);
+    return canvas.toDataURL("image/png");
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+async function drawNodeOntoCanvas(
+  ctx: CanvasRenderingContext2D,
+  node: HTMLElement,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  rotateDeg: number
+) {
+  const w = Math.max(1, width);
+  const h = Math.max(1, height);
+  let source: CanvasImageSource | null = null;
+
+  const canvases = Array.from(node.querySelectorAll("canvas"));
+  if (canvases.length === 1) {
+    source = canvases[0]!;
+  } else if (canvases.length > 1) {
+    const merged = document.createElement("canvas");
+    merged.width = w;
+    merged.height = h;
+    const mctx = merged.getContext("2d");
+    if (mctx) {
+      for (const canvas of canvases) {
+        try {
+          mctx.drawImage(canvas, 0, 0, w, h);
+        } catch {
+          // ignore tainted canvas
+        }
+      }
+      source = merged;
+    }
+  } else {
+    const imgs = Array.from(node.querySelectorAll("img"));
+    if (imgs.length === 1) {
+      source = imgs[0]!;
+    } else if (imgs.length > 1) {
+      const merged = document.createElement("canvas");
+      merged.width = w;
+      merged.height = h;
+      const mctx = merged.getContext("2d");
+      if (mctx) {
+        for (const img of imgs) {
+          try {
+            mctx.drawImage(img, 0, 0, w, h);
+          } catch {
+            // ignore
+          }
+        }
+        source = merged;
+      }
+    }
+  }
+
+  let image: HTMLImageElement;
+  if (source) {
+    if (source instanceof HTMLImageElement) {
+      image = source;
+      if (!image.complete) await loadImage(image.src);
+    } else {
+      const dataUrl =
+        source instanceof HTMLCanvasElement
+          ? source.toDataURL("image/png")
+          : "";
+      image = await loadImage(dataUrl);
+    }
+  } else {
+    const dataUrl = await nodeToDataUrlViaSvg(node, w, h);
+    image = await loadImage(dataUrl);
+  }
+
+  ctx.save();
+  ctx.translate(x + w / 2, y + h / 2);
+  ctx.rotate((rotateDeg * Math.PI) / 180);
+  ctx.drawImage(image, -w / 2, -h / 2, w, h);
+  ctx.restore();
+}
+
+export type CapturePreviewSceneOptions = {
+  backgroundColor?: string;
+  maxWidth?: number;
+  maxHeight?: number;
+  mimeType?: "image/png" | "image/jpeg";
+  quality?: number;
+};
+
+export async function capturePreviewSceneElement(
+  scene: HTMLElement,
+  sceneWidth: number,
+  sceneHeight: number,
+  options?: CapturePreviewSceneOptions
+): Promise<string> {
+  const width = Math.max(1, Math.round(sceneWidth));
+  const height = Math.max(1, Math.round(sceneHeight));
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("canvas-context-failed");
+
+  ctx.fillStyle = options?.backgroundColor ?? "#ffffff";
+  ctx.fillRect(0, 0, width, height);
+
+  const nodes = Array.from(scene.querySelectorAll<HTMLElement>("[data-element-id]"));
+  const sorted = nodes
+    .map((node) => {
+      const zIndex = Number.parseInt(window.getComputedStyle(node).zIndex || "1", 10);
+      return { node, zIndex: Number.isFinite(zIndex) ? zIndex : 1 };
+    })
+    .sort((a, b) => a.zIndex - b.zIndex);
+
+  for (const { node } of sorted) {
+    const left = Number.parseFloat(node.style.left || "0") || 0;
+    const top = Number.parseFloat(node.style.top || "0") || 0;
+    const nodeWidth = Number.parseFloat(node.style.width || "") || node.offsetWidth || 1;
+    const nodeHeight = Number.parseFloat(node.style.height || "") || node.offsetHeight || 1;
+    const transform = node.style.transform || "";
+    const rotateMatch = /rotate\(([-\d.]+)deg\)/.exec(transform);
+    const rotateDeg = rotateMatch ? Number.parseFloat(rotateMatch[1]!) : 0;
+    await drawNodeOntoCanvas(ctx, node, left, top, nodeWidth, nodeHeight, rotateDeg);
+  }
+
+  const mimeType = options?.mimeType ?? "image/png";
+  const quality = options?.quality ?? 0.92;
+  let dataUrl = canvas.toDataURL(mimeType, quality);
+
+  const maxWidth = options?.maxWidth;
+  const maxHeight = options?.maxHeight;
+  if (maxWidth || maxHeight) {
+    dataUrl = await scaleDataUrl(dataUrl, maxWidth, maxHeight, mimeType, quality);
+  }
+  return dataUrl;
+}
+
+export async function scaleDataUrl(
+  dataUrl: string,
+  maxWidth?: number,
+  maxHeight?: number,
+  mimeType: "image/png" | "image/jpeg" = "image/png",
+  quality = 0.92
+): Promise<string> {
+  if (!maxWidth && !maxHeight) return dataUrl;
+  const img = await loadImage(dataUrl);
+  const ratio = img.width / img.height;
+  let targetWidth = img.width;
+  let targetHeight = img.height;
+  if (maxWidth && targetWidth > maxWidth) {
+    targetWidth = maxWidth;
+    targetHeight = Math.round(targetWidth / ratio);
+  }
+  if (maxHeight && targetHeight > maxHeight) {
+    targetHeight = maxHeight;
+    targetWidth = Math.round(targetHeight * ratio);
+  }
+  if (targetWidth === img.width && targetHeight === img.height) return dataUrl;
+  const canvas = document.createElement("canvas");
+  canvas.width = targetWidth;
+  canvas.height = targetHeight;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return dataUrl;
+  ctx.drawImage(img, 0, 0, targetWidth, targetHeight);
+  return canvas.toDataURL(mimeType, quality);
+}

package/src/panel/library/event-subscription.ts

@@ -0,0 +1,60 @@
+import type { WorkspaceProjectRecord } from "./workspace-project-db";
+
+export const AbuilderEvents = {
+  /** 添加工作区 */
+  workspaceAdd: "workspace:add",
+  /** 同步工作区 */
+  workspaceSync: "workspace:sync",
+} as const;
+
+export type AbuilderEventName = (typeof AbuilderEvents)[keyof typeof AbuilderEvents];
+
+/** 工作区完整数据（面板 + 蓝图），可用于外部持久化与再次加载 */
+export type WorkspaceData = WorkspaceProjectRecord;
+
+export type WorkspaceAddEventPayload = WorkspaceData;
+export type WorkspaceSyncEventPayload = WorkspaceData;
+
+export type AbuilderEventPayloadMap = {
+  [AbuilderEvents.workspaceAdd]: WorkspaceAddEventPayload;
+  [AbuilderEvents.workspaceSync]: WorkspaceSyncEventPayload;
+};
+
+type EventCallback = (payload: unknown) => void;
+
+const listeners = new Map<string, Set<EventCallback>>();
+
+export function emitAbuilderEvent<T extends AbuilderEventName>(
+  eventName: T,
+  payload: AbuilderEventPayloadMap[T]
+): void {
+  const set = listeners.get(eventName);
+  if (!set) return;
+  for (const callback of set) {
+    try {
+      callback(payload);
+    } catch (error) {
+      console.error(`[abuilder] event handler error (${eventName}):`, error);
+    }
+  }
+}
+
+export function addEventSubscription<T extends AbuilderEventName>(
+  eventName: T,
+  callback: (payload: AbuilderEventPayloadMap[T]) => void
+): { unsubscribe: () => void } {
+  let set = listeners.get(eventName);
+  if (!set) {
+    set = new Set();
+    listeners.set(eventName, set);
+  }
+  set.add(callback as EventCallback);
+  return {
+    unsubscribe: () => {
+      set.delete(callback as EventCallback);
+      if (set.size === 0) {
+        listeners.delete(eventName);
+      }
+    },
+  };
+}

package/src/panel/library/preview-snapshot.ts

@@ -0,0 +1,238 @@
+import type { PanelElement, PanelLayer } from "../types";
+import { CHART_TYPES, buildChartOption } from "../utils/chartOptionBuilder";
+import {
+  computePanelSceneBounds,
+  resolvePreviewLayerElements,
+} from "../utils/panelStateIO";
+import {
+  capturePreviewSceneElement,
+  scaleDataUrl,
+  type CapturePreviewSceneOptions,
+} from "./capture-preview-snapshot";
+
+export type GetPreviewSnapshotOptions = CapturePreviewSceneOptions;
+
+type PreviewSnapshotProvider = () => Promise<string | null>;
+
+let previewSnapshotProvider: PreviewSnapshotProvider | null = null;
+
+export function registerPreviewSnapshotProvider(provider: PreviewSnapshotProvider | null) {
+  previewSnapshotProvider = provider;
+}
+
+function serializeNodeDom(
+  sourceNode: HTMLElement,
+  sourceElement: PanelElement,
+  minX: number,
+  minY: number,
+  isChartNode: boolean
+): string {
+  const clone = sourceNode.cloneNode(true) as HTMLElement;
+  clone.className = clone.className
+    .split(/\s+/)
+    .filter((cls) => cls && !cls.startsWith("ring-"))
+    .join(" ");
+  clone.removeAttribute("data-moveable-target");
+  clone.style.left = `${sourceElement.x - minX}px`;
+  clone.style.top = `${sourceElement.y - minY}px`;
+  const sourceCanvases = Array.from(sourceNode.querySelectorAll("canvas"));
+  const cloneCanvases = Array.from(clone.querySelectorAll("canvas"));
+  if (isChartNode) return clone.outerHTML;
+  sourceCanvases.forEach((srcCanvas, idx) => {
+    const clonedCanvas = cloneCanvases[idx];
+    if (!clonedCanvas) return;
+    try {
+      const dataUrl = srcCanvas.toDataURL("image/png");
+      const img = document.createElement("img");
+      img.src = dataUrl;
+      img.style.width = "100%";
+      img.style.height = "100%";
+      img.style.objectFit = "fill";
+      img.style.display = "block";
+      clonedCanvas.replaceWith(img);
+    } catch {
+      // ignore tainted canvas
+    }
+  });
+  return clone.outerHTML;
+}
+
+function waitFrames(count = 2): Promise<void> {
+  return new Promise((resolve) => {
+    let remaining = count;
+    const step = () => {
+      remaining -= 1;
+      if (remaining <= 0) resolve();
+      else requestAnimationFrame(step);
+    };
+    requestAnimationFrame(step);
+  });
+}
+
+export type BuildEditorPreviewSnapshotSceneOptions = {
+  canvasRoot: HTMLElement | null;
+  allElements: PanelElement[];
+  layers: PanelLayer[];
+  activeLayerId: string;
+  outputScale: boolean;
+  retryCount?: number;
+};
+
+export async function buildEditorPreviewSnapshotScene(
+  options: BuildEditorPreviewSnapshotSceneOptions
+): Promise<{ scene: HTMLElement; width: number; height: number } | null> {
+  const retryCount = options.retryCount ?? 0;
+  const layerElements = resolvePreviewLayerElements(
+    options.allElements,
+    options.layers,
+    options.activeLayerId
+  );
+  if (!layerElements.length) return null;
+
+  const sceneBounds = computePanelSceneBounds(layerElements);
+  const mountedNodes = layerElements.map((el) => ({
+    el,
+    node:
+      options.canvasRoot?.querySelector<HTMLElement>(`[data-element-id="${el.id}"]`) ??
+      null,
+  }));
+  const mountedCount = mountedNodes.filter((item) => !!item.node).length;
+  if (mountedCount < layerElements.length && retryCount < 20) {
+    await new Promise((resolve) => window.setTimeout(resolve, 80));
+    return buildEditorPreviewSnapshotScene({ ...options, retryCount: retryCount + 1 });
+  }
+
+  const previewNodesHtml = mountedNodes
+    .map((item) => {
+      if (!item.node) return "";
+      return serializeNodeDom(
+        item.node,
+        item.el,
+        sceneBounds.minX,
+        sceneBounds.minY,
+        CHART_TYPES.has(item.el.materialType ?? "")
+      );
+    })
+    .filter(Boolean)
+    .join("");
+  if (!previewNodesHtml && retryCount < 20) {
+    await new Promise((resolve) => window.setTimeout(resolve, 80));
+    return buildEditorPreviewSnapshotScene({ ...options, retryCount: retryCount + 1 });
+  }
+  if (!previewNodesHtml) return null;
+
+  const host = document.createElement("div");
+  host.setAttribute("data-preview-snapshot-host", "true");
+  host.style.position = "fixed";
+  host.style.left = "-100000px";
+  host.style.top = "0";
+  host.style.width = `${sceneBounds.width}px`;
+  host.style.height = `${sceneBounds.height}px`;
+  host.style.overflow = "hidden";
+  host.style.pointerEvents = "none";
+  host.style.background = "#ffffff";
+
+  const scene = document.createElement("div");
+  scene.id = "preview-scene";
+  scene.className = "relative shrink-0 origin-top-left";
+  scene.style.width = `${sceneBounds.width}px`;
+  scene.style.height = `${sceneBounds.height}px`;
+  scene.style.transformOrigin = "left top";
+  scene.innerHTML = previewNodesHtml;
+  host.appendChild(scene);
+  document.body.appendChild(host);
+
+  const gridNodeIds = layerElements
+    .filter((el) => el.materialType === "grid")
+    .map((el) => el.id);
+  for (const id of gridNodeIds) {
+    const gridNode = scene.querySelector<HTMLElement>(`[data-element-id="${id}"]`);
+    const content = gridNode?.firstElementChild as HTMLElement | null;
+    if (content) {
+      content.innerHTML = "";
+      content.removeAttribute("style");
+    }
+  }
+
+  const chartNodes = layerElements.filter((el) =>
+    CHART_TYPES.has(el.materialType ?? "")
+  );
+  for (const el of chartNodes) {
+    const hostEl = scene.querySelector<HTMLElement>(`[data-element-id="${el.id}"] > div`);
+    if (!hostEl) continue;
+    hostEl.innerHTML = "";
+    const chart = (
+      await import("echarts")
+    ).init(hostEl, null, { renderer: el.chart?.renderMode ?? "canvas" });
+    chart.setOption(buildChartOption(el) ?? {}, true);
+    chart.resize();
+  }
+
+  await waitFrames(2);
+  return { scene, width: sceneBounds.width, height: sceneBounds.height };
+}
+
+export function disposePreviewSnapshotScene(scene: HTMLElement) {
+  const host = scene.parentElement;
+  host?.remove();
+}
+
+async function finalizePreviewSnapshot(
+  dataUrl: string,
+  options?: GetPreviewSnapshotOptions
+): Promise<string> {
+  if (!options) return dataUrl;
+  const mimeType = options.mimeType ?? "image/png";
+  const quality = options.quality ?? 0.92;
+  if (options.maxWidth || options.maxHeight) {
+    return scaleDataUrl(dataUrl, options.maxWidth, options.maxHeight, mimeType, quality);
+  }
+  if (mimeType === "image/jpeg" && !dataUrl.startsWith("data:image/jpeg")) {
+    return scaleDataUrl(dataUrl, undefined, undefined, mimeType, quality);
+  }
+  return dataUrl;
+}
+
+/**
+ * 获取当前预览画面的 base64 图片（data URL），可用于工作区缩略图等场景。
+ * 优先使用编辑器或在线预览页注册的截图提供者，其次尝试页面上的 `#preview-scene`。
+ */
+export async function getPreviewSnapshot(
+  options?: GetPreviewSnapshotOptions
+): Promise<string> {
+  let dataUrl: string | null = null;
+  if (previewSnapshotProvider) {
+    dataUrl = await previewSnapshotProvider();
+  }
+
+  if (!dataUrl) {
+    const scene = document.getElementById("preview-scene");
+    if (scene instanceof HTMLElement) {
+      const width = scene.offsetWidth || Number.parseFloat(scene.style.width) || 1;
+      const height = scene.offsetHeight || Number.parseFloat(scene.style.height) || 1;
+      return capturePreviewSceneElement(scene, width, height, options);
+    }
+    throw new Error(
+      "Preview snapshot is unavailable. Mount the editor or open online preview first."
+    );
+  }
+
+  return finalizePreviewSnapshot(dataUrl, options);
+}
+
+export async function captureEditorPreviewSnapshot(
+  options: BuildEditorPreviewSnapshotSceneOptions & GetPreviewSnapshotOptions
+): Promise<string | null> {
+  const built = await buildEditorPreviewSnapshotScene(options);
+  if (!built) return null;
+  try {
+    return await capturePreviewSceneElement(
+      built.scene,
+      built.width,
+      built.height,
+      options
+    );
+  } finally {
+    disposePreviewSnapshotScene(built.scene);
+  }
+}