@arronqzy/vue-view 0.1.10 → 0.1.11

package/README.md

@@ -29,7 +29,21 @@ createApp(VueViewPanel).use(Antd).mount("#app");
 import { VueViewOnlinePreview, parseOnlinePreviewSearchParams } from "@arronqzy/vue-view";
 ```
 
-URL 参数：`?preview=online&projectId=<id>&pid=<instanceId>`
+URL 参数：`?preview=online&projectId=<id>&pid=<instanceId>`。也可传入 `workspace` 直接预览宿主数据（优先于 `projectId`）。
+
+### 宿主集成
+
+```ts
+import {
+  addEventSubscription,
+  AbuilderEvents,
+  parseWorkspaceData,
+  createEmptyWorkspace,
+  createWorkspaceProjectId,
+} from "@arronqzy/vue-view";
+```
+
+创建 / 同步工作区会发出 `workspace:add` / `workspace:sync`。`parseWorkspaceData` 的 `value` 可作 `initialWorkspace`。IndexedDB CRUD 与 `getPreviewSnapshot` **不导出**（后者仅 React 实现）。
 
 ## 依赖
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arronqzy/vue-view",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Vue 3 visual view editor for Abuilder (Ant Design Vue)",
   "license": "MIT",
   "type": "module",
@@ -23,12 +23,12 @@
     "selecto": "^1.26.3",
     "uuid": "^13.0.0",
     "vue": "^3.5.13",
-    "@arronqzy/blueprint-dsl": "1.0.10",
-    "@arronqzy/rx-store": "1.0.5",
-    "@arronqzy/view-table": "0.1.5",
-    "@arronqzy/vue-blueprint": "0.1.8",
     "@arronqzy/i18n": "0.1.8",
+    "@arronqzy/blueprint-dsl": "1.0.11",
+    "@arronqzy/rx-store": "1.0.5",
     "@arronqzy/view-scene3d": "0.1.2",
+    "@arronqzy/view-table": "0.1.5",
+    "@arronqzy/vue-blueprint": "0.1.9",
     "@arronqzy/vue-rx-store": "0.1.3"
   },
   "peerDependencies": {

package/src/index.ts

@@ -1,4 +1,30 @@
 export { default as VueViewPanel } from "./panel/VueViewPanel.vue";
 export { default as VueViewOnlinePreview } from "./panel/VueViewOnlinePreview.vue";
 export { parseOnlinePreviewSearchParams } from "./panel/parseOnlinePreviewSearchParams";
+export type { WorkspaceProjectRecord } from "./panel/library/workspace-project-db";
 export type * from "./panel/types";
+export {
+  parseViewData,
+  validateViewData,
+  parseBlueprintData,
+  validateBlueprintData,
+  validateWorkspaceData,
+  parseWorkspaceData,
+  createEmptyWorkspace,
+} from "./panel/library/parse-workspace-data";
+export { createWorkspaceProjectId } from "./panel/library/workspace-project-db";
+export {
+  addEventSubscription,
+  AbuilderEvents,
+} from "./panel/library/event-subscription";
+export type {
+  AbuilderEventName,
+  AbuilderEventPayloadMap,
+  WorkspaceAddEventPayload,
+  WorkspaceSyncEventPayload,
+  WorkspaceData,
+} from "./panel/library/event-subscription";
+export type {
+  ParseCheckResult,
+  WorkspaceParseCheckResult,
+} from "./panel/library/parse-workspace-data";

package/src/panel/VueViewOnlinePreview.vue

@@ -22,7 +22,10 @@ import {
   useViewScopeStoreVersion,
 } from "./scope/view-scope-store";
 import { resolvePanelElementScope } from "./utils/scope-template";
-import { getWorkspaceProject } from "./library/workspace-project-db";
+import {
+  getWorkspaceProject,
+  type WorkspaceProjectRecord,
+} from "./library/workspace-project-db";
 import { readWorkspacePreviewCache } from "./library/workspace-project-cache";
 import { subscribeWorkspaceProjectUpdates } from "./library/workspace-project-sync";
 import {
@@ -41,8 +44,12 @@ const { t, locale } = useI18n();
 const PREVIEW_BOOT_PHASES: PageLifecyclePhase[] = ["mounted"];
 
 const props = defineProps<{
-  projectId: string;
+  /** 从 IndexedDB / 缓存按 ID 加载；与 `workspace` 二选一，优先 `workspace` */
+  projectId?: string;
   previewInstanceId?: string;
+  nameSpace?: string | null;
+  /** 直接传入完整工作区，用于宿主后端加载后预览 */
+  workspace?: WorkspaceProjectRecord | null;
 }>();
 
 const loadError = ref<string | null>(null);
@@ -53,7 +60,7 @@ const blueprintLibraryItems = ref<BlueprintLibraryListItem[]>([]);
 const layoutRevision = ref(0);
 const layoutReady = ref(false);
 const sceneRef = ref<HTMLDivElement | null>(null);
-const outputScale = ref(readOutputScale());
+const outputScale = ref(readOutputScale(props.nameSpace));
 const fillScale = ref({ scaleX: 1, scaleY: 1 });
 
 const layers = computed(() => (panelState.value ? parsePanelLayers(panelState.value) : []));
@@ -64,10 +71,19 @@ const allElements = computed(() =>
   panelState.value ? parseAllPanelElements(panelState.value) : []
 );
 
+const resolvedProjectId = computed(
+  () => props.workspace?.id ?? props.projectId ?? ""
+);
+
+function workspaceTitle(record: WorkspaceProjectRecord) {
+  const product = typeof record.productName === "string" ? record.productName : "";
+  return product.trim() || record.name || t("panel.workspace.previewDocTitle");
+}
+
 async function loadWorkspaceRecord(projectId: string) {
-  const fromDb = await getWorkspaceProject(projectId);
+  const fromDb = await getWorkspaceProject(projectId, props.nameSpace);
   if (fromDb) return fromDb;
-  return readWorkspacePreviewCache(projectId);
+  return readWorkspacePreviewCache(projectId, props.nameSpace);
 }
 
 function applyTitleIcon(titleIconDataUrl?: string) {
@@ -82,13 +98,7 @@ function applyTitleIcon(titleIconDataUrl?: string) {
   }
 }
 
-async function loadProject() {
-  const record = await loadWorkspaceRecord(props.projectId);
-  if (!record) {
-    loadError.value = t("panel.messages.workspaceNotFound");
-    panelState.value = null;
-    return;
-  }
+function applyWorkspaceRecord(record: WorkspaceProjectRecord) {
   const normalized = normalizeImportedPanelState(record.panelState);
   if (!normalized) {
     loadError.value = t("panel.messages.workspaceDataInvalid");
@@ -99,24 +109,56 @@ async function loadProject() {
   clearViewElementScopes();
   panelState.value = normalized;
   blueprintGraph.value = BlueprintGraph.fromDocument(record.blueprintDocument);
-  document.title = record.productName.trim() || record.name || t("panel.workspace.previewDocTitle");
+  document.title = workspaceTitle(record);
   applyTitleIcon(record.titleIconDataUrl);
   projectRevision.value += 1;
 }
 
-onMounted(() => {
-  void loadProject();
-});
+async function loadProject() {
+  if (props.workspace) {
+    applyWorkspaceRecord(props.workspace);
+    return;
+  }
+  if (!props.projectId) {
+    loadError.value = t("panel.messages.workspaceNotFound");
+    panelState.value = null;
+    return;
+  }
+  const record = await loadWorkspaceRecord(props.projectId);
+  if (!record) {
+    loadError.value = t("panel.messages.workspaceNotFound");
+    panelState.value = null;
+    return;
+  }
+  applyWorkspaceRecord(record);
+}
 
-onMounted(() => {
-  const unsub = subscribeWorkspaceProjectUpdates(props.projectId, () => {
+watch(
+  () => [props.workspace, props.projectId, props.nameSpace] as const,
+  () => {
     void loadProject();
-  });
-  onUnmounted(unsub);
-});
+  },
+  { immediate: true }
+);
+
+watch(
+  () => [props.workspace, props.projectId, props.nameSpace] as const,
+  ([workspace, projectId, nameSpace], _prev, onCleanup) => {
+    if (workspace || !projectId) return;
+    const unsub = subscribeWorkspaceProjectUpdates(
+      projectId,
+      () => {
+        void loadProject();
+      },
+      nameSpace
+    );
+    onCleanup(unsub);
+  },
+  { immediate: true }
+);
 
 watch(projectRevision, () => {
-  void listBlueprintLibrary().then((items) => {
+  void listBlueprintLibrary(props.nameSpace).then((items) => {
     blueprintLibraryItems.value = items;
   });
 });
@@ -126,9 +168,9 @@ const blueprintLibraryNameById = computed(
 );
 
 const resolveLibraryBlueprint: LibraryBlueprintResolver = async (libraryBlueprintId) => {
-  const record = await getBlueprintLibraryRecord(libraryBlueprintId);
+  const record = await getBlueprintLibraryRecord(libraryBlueprintId, props.nameSpace);
   if (!record) return null;
-  const items = await listBlueprintLibrary();
+  const items = await listBlueprintLibrary(props.nameSpace);
   const nameById = new Map(items.map((item) => [item.id, item.name]));
   return documentToRunnableGraph(record.document, { libraryNameById: nameById });
 };
@@ -167,7 +209,7 @@ const displayElements = computed(() =>
 );
 
 function applySceneFit() {
-  const enabled = readOutputScale();
+  const enabled = readOutputScale(props.nameSpace);
   outputScale.value = enabled;
   const fill = applyPreviewSceneFill(
     sceneRef.value,
@@ -277,7 +319,7 @@ function noopSelect() {}
     v-else
     class="min-h-screen 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/VueViewPanel.vue

@@ -78,8 +78,10 @@ const props = withDefaults(
   defineProps<{
     class?: string;
     initialZoom?: number;
+    nameSpace?: string | null;
+    initialWorkspace?: WorkspaceProjectRecord | null;
   }>(),
-  { initialZoom: 1 }
+  { initialZoom: 1, nameSpace: null, initialWorkspace: null }
 );
 
 const {
@@ -296,9 +298,9 @@ const {
 } = useBlueprintNodeSelectionGuard(selectedBlueprintNodeId, applyBlueprintNodeSelection);
 
 const resolveLibraryBlueprint: LibraryBlueprintResolver = async (libraryBlueprintId) => {
-  const record = await getBlueprintLibraryRecord(libraryBlueprintId);
+  const record = await getBlueprintLibraryRecord(libraryBlueprintId, props.nameSpace);
   if (!record) return null;
-  const items = await listBlueprintLibrary();
+  const items = await listBlueprintLibrary(props.nameSpace);
   const nameById = new Map(items.map((item) => [item.id, item.name]));
   return documentToRunnableGraph(record.document, { libraryNameById: nameById });
 };
@@ -319,6 +321,7 @@ const blueprintDebugSession = useBlueprintDebugSession({
   libraryNameById: blueprintLibraryNameById,
   onExecutionBlocked: handleBlueprintExecutionBlocked,
   onViewScopeUpdate: handleViewScopeUpdate,
+  nameSpace: () => props.nameSpace,
 });
 
 const blueprintDebugToolbar = computed(() => ({
@@ -359,7 +362,7 @@ function handleUpdateAllowFalseSignalPropagation(value: boolean) {
 }
 
 async function refreshBlueprintLibrary() {
-  blueprintLibraryItems.value = await listBlueprintLibrary();
+  blueprintLibraryItems.value = await listBlueprintLibrary(props.nameSpace);
 }
 
 onMounted(() => {
@@ -402,6 +405,8 @@ const workspaceProjects = useWorkspaceProjects({
   },
   panelRevision: computed(() => `${historyCursor.value}|${allElements.value.length}`),
   onProjectApplied: handleWorkspaceProjectApplied,
+  initialWorkspace: () => props.initialWorkspace,
+  nameSpace: () => props.nameSpace,
 });
 
 const { triggerBlueprintNode, emitViewEvent, firedLifecyclePhases } = useBlueprintPageLifecycle({
@@ -440,7 +445,7 @@ const blueprintNodeOptions = computed(() =>
 );
 async function loadBlueprintFromLibrary(id: string) {
   await runBusyTask(t("common.loadingBlueprint"), async () => {
-    const record = await getBlueprintLibraryRecord(id);
+    const record = await getBlueprintLibraryRecord(id, props.nameSpace);
     if (!record) {
       message.error(panelMessages().blueprintNotFound);
       void refreshBlueprintLibrary();
@@ -487,14 +492,14 @@ async function syncBlueprintToLibrary() {
   const libraryId = activeBlueprintLibraryId.value;
   if (!libraryId) return;
   await runBusyTask(t("common.syncingBlueprint"), async () => {
-    const record = await getBlueprintLibraryRecord(libraryId);
+    const record = await getBlueprintLibraryRecord(libraryId, props.nameSpace);
     if (!record) return;
     await putBlueprintLibraryRecord({
       ...record,
       document: blueprintGraph.value.document,
       name: blueprintMeta.value.name,
       remark: blueprintMeta.value.remark,
-    });
+    }, props.nameSpace);
     blueprintSyncedDocument.value = blueprintGraph.value.document;
     message.success(panelMessages().blueprintSyncedToLibrary);
     await refreshBlueprintLibrary();
@@ -510,7 +515,7 @@ async function saveBlueprintToLibrary(meta: BlueprintMetaDraft) {
       meta,
       source: "saved",
     });
-    await putBlueprintLibraryRecord(record);
+    await putBlueprintLibraryRecord(record, props.nameSpace);
     activeBlueprintLibraryId.value = id;
     blueprintSyncedDocument.value = blueprintGraph.value.document;
     blueprintMeta.value = meta;
@@ -526,7 +531,7 @@ function handleExport() {
     const url = URL.createObjectURL(blob);
     const a = document.createElement("a");
     a.href = url;
-    const safeName = (productName.value.trim() || "panel")
+    const safeName = ((productName.value ?? "").trim() || "panel")
       .replace(/[\\/:*?"<>|]/g, "-")
       .replace(/\s+/g, "-");
     a.download = `${safeName}-${Date.now()}.json`;
@@ -566,7 +571,7 @@ async function handleBlueprintImportFile(file: File) {
       const text = await file.text();
       const payload = parseBlueprintImportFile(await parseJsonText(text));
       const record = libraryRecordFromImport(payload);
-      await putBlueprintLibraryRecord(record);
+      await putBlueprintLibraryRecord(record, props.nameSpace);
       await refreshBlueprintLibrary();
       if (!activeBlueprintLibraryId.value) snapshotWorkspaceBlueprint();
       await loadBlueprintFromLibrary(record.id);

package/src/panel/hooks/useWorkspaceProjects.ts

@@ -1,6 +1,7 @@
 import { computed, onMounted, onUnmounted, ref, shallowRef, toValue, watch, type MaybeRefOrGetter } from "vue";
 import {
   BlueprintGraph,
+  parseBlueprintData,
   type BlueprintDocument,
   type BlueprintMetaDraft,
 } from "@arronqzy/vue-blueprint";
@@ -23,6 +24,8 @@ import {
   type WorkspaceSnapshot,
 } from "../library/workspace-snapshot";
 import { runBusyTask } from "../utils/async-work";
+import { createEmptyPanelState, normalizeImportedPanelState } from "../utils/panelStateIO";
+import { AbuilderEvents, emitAbuilderEvent } from "../library/event-subscription";
 
 export type UseWorkspaceProjectsOptions = {
   exportPanelData: () => State;
@@ -39,13 +42,21 @@ export type UseWorkspaceProjectsOptions = {
   panelRevision: MaybeRefOrGetter<unknown>;
   /** 工作区记录应用到编辑器后的回调（用于恢复蓝图面板等 UI 状态） */
   onProjectApplied?: (record: WorkspaceProjectRecord) => void;
+  /** 外部传入的初始工作区，挂载后自动加载（不触发 onProjectApplied） */
+  initialWorkspace?: MaybeRefOrGetter<WorkspaceProjectRecord | null | undefined>;
+  nameSpace?: MaybeRefOrGetter<string | null | undefined>;
 };
 
-export function buildOnlinePreviewUrl(projectId: string): string {
+export function buildOnlinePreviewUrl(
+  projectId: string,
+  nameSpace?: string | null
+): string {
   const url = new URL(window.location.href);
   url.search = "";
   url.searchParams.set("preview", "online");
   url.searchParams.set("projectId", projectId);
+  const ns = (nameSpace ?? "").trim();
+  if (ns) url.searchParams.set("ns", ns);
   const previewInstanceId =
     typeof crypto !== "undefined" && "randomUUID" in crypto
       ? crypto.randomUUID()
@@ -54,8 +65,31 @@ export function buildOnlinePreviewUrl(projectId: string): string {
   return url.toString();
 }
 
+function previewWindowName(projectId: string, nameSpace?: string | null): string {
+  const ns = (nameSpace ?? "").trim();
+  return ns ? `abuilder-preview-${ns}-${projectId}` : `abuilder-preview-${projectId}`;
+}
+
+function hasWorkspacePayload(
+  record?: WorkspaceProjectRecord | null
+): record is WorkspaceProjectRecord {
+  if (!record || typeof record !== "object") return false;
+  return Boolean(
+    record.panelState ||
+      record.blueprintDocument ||
+      record.id ||
+      record.productName ||
+      record.titleIconDataUrl
+  );
+}
+
+function workspaceApplyKey(record: WorkspaceProjectRecord): string {
+  return `${record.id ?? "anon"}:${record.updatedAt ?? 0}`;
+}
+
 export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
   const { t, locale } = useI18nOptional();
+  const nameSpace = () => toValue(options.nameSpace) ?? null;
   const projects = ref<WorkspaceProjectListItem[]>([]);
   const activeProjectId = ref<string | null>(null);
   const activeProjectName = ref<string | null>(null);
@@ -77,7 +111,8 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
 
   function resolveProjectName() {
     void locale.value;
-    return toValue(options.productName).trim() || t("panel.defaults.unnamedProduct");
+    const name = toValue(options.productName);
+    return (typeof name === "string" ? name : "").trim() || t("panel.defaults.unnamedProduct");
   }
 
   function buildCurrentSnapshot(): WorkspaceSnapshot {
@@ -90,13 +125,15 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
   }
 
   async function refreshProjects() {
-    projects.value = await listWorkspaceProjects();
+    projects.value = await listWorkspaceProjects(nameSpace());
   }
 
-  onMounted(() => {
-    void refreshProjects();
-    previewPollTimer = window.setInterval(refreshPreviewing, 2000);
-  });
+  watch(
+    () => nameSpace(),
+    () => {
+      void refreshProjects();
+    }
+  );
 
   onUnmounted(() => {
     if (previewPollTimer !== undefined) window.clearInterval(previewPollTimer);
@@ -122,36 +159,104 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     return !workspaceSnapshotsEqual(buildCurrentSnapshot(), syncedSnapshotRef.value);
   });
 
-  function applyProjectRecord(record: WorkspaceProjectRecord) {
+  function applyProjectRecord(
+    record: WorkspaceProjectRecord,
+    applyOptions?: { notifyApplied?: boolean }
+  ) {
+    const parsedBlueprint = parseBlueprintData(record.blueprintDocument);
     const blueprintDocument =
-      record.blueprintDocument ?? BlueprintGraph.empty().document;
+      parsedBlueprint.value ?? BlueprintGraph.empty().document;
     const blueprintMeta: BlueprintMetaDraft = {
       name: record.blueprintMeta?.name ?? t("panel.defaults.unnamedBlueprint"),
       remark: record.blueprintMeta?.remark ?? "",
     };
+    const panelState =
+      normalizeImportedPanelState(record.panelState) ?? createEmptyPanelState();
+    const productName =
+      typeof record.productName === "string" && record.productName.trim()
+        ? record.productName
+        : t("panel.defaults.unnamedProduct");
+    const titleIconDataUrl = record.titleIconDataUrl ?? "";
 
-    options.importPanelData(record.panelState);
+    options.importPanelData(panelState);
     options.setBlueprintGraph(BlueprintGraph.fromDocument(blueprintDocument));
     options.setBlueprintMeta(blueprintMeta);
-    options.setProductName(record.productName);
-    options.setTitleIconDataUrl(record.titleIconDataUrl ?? "");
-    activeProjectId.value = record.id;
-    activeProjectName.value = record.name;
+    options.setProductName(productName);
+    options.setTitleIconDataUrl(titleIconDataUrl);
+    activeProjectId.value = record.id || null;
+    activeProjectName.value = record.name ?? null;
     syncedSnapshotRef.value = cloneWorkspaceSnapshot({
       blueprintDocument,
       blueprintMeta,
-      productName: record.productName,
-      titleIconDataUrl: record.titleIconDataUrl ?? "",
+      productName,
+      titleIconDataUrl,
     });
     syncedPanelRevision = toValue(options.panelRevision);
     pendingRevisionSync = true;
-    options.onProjectApplied?.({
-      ...record,
-      blueprintDocument,
-      blueprintMeta,
+    if (applyOptions?.notifyApplied !== false) {
+      options.onProjectApplied?.({
+        ...record,
+        blueprintDocument,
+        blueprintMeta,
+        panelState,
+        productName,
+        titleIconDataUrl: titleIconDataUrl || undefined,
+      });
+    }
+  }
+
+  function applyEmptyWorkspace() {
+    options.importPanelData(createEmptyPanelState());
+    options.setBlueprintGraph(BlueprintGraph.empty());
+    options.setBlueprintMeta({
+      name: t("panel.defaults.unnamedBlueprint"),
+      remark: "",
     });
+    options.setProductName(t("panel.defaults.unnamedProduct"));
+    options.setTitleIconDataUrl("");
+    activeProjectId.value = null;
+    activeProjectName.value = null;
+    syncedSnapshotRef.value = null;
   }
 
+  let bootstrapped = false;
+  let appliedWorkspaceKey: string | null = null;
+
+  function bootstrapInitialWorkspace() {
+    const initialWorkspace = toValue(options.initialWorkspace) ?? null;
+    if (!bootstrapped) {
+      bootstrapped = true;
+      if (hasWorkspacePayload(initialWorkspace)) {
+        applyProjectRecord(initialWorkspace, { notifyApplied: false });
+        appliedWorkspaceKey = workspaceApplyKey(initialWorkspace);
+      } else {
+        applyEmptyWorkspace();
+      }
+      return;
+    }
+    if (!hasWorkspacePayload(initialWorkspace)) return;
+    const key = workspaceApplyKey(initialWorkspace);
+    if (appliedWorkspaceKey === key) return;
+    appliedWorkspaceKey = key;
+    applyProjectRecord(initialWorkspace, { notifyApplied: false });
+  }
+
+  onMounted(() => {
+    bootstrapInitialWorkspace();
+    void refreshProjects();
+    previewPollTimer = window.setInterval(refreshPreviewing, 2000);
+  });
+
+  watch(
+    () => {
+      const record = toValue(options.initialWorkspace);
+      return record ? workspaceApplyKey(record) : "";
+    },
+    () => {
+      bootstrapInitialWorkspace();
+    }
+  );
+
   async function persistProject(persistOptions: {
     id?: string;
     name: string;
@@ -161,7 +266,7 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     const now = Date.now();
     const id = persistOptions.id ?? createWorkspaceProjectId();
     const createdAt = persistOptions.createdAt ?? now;
-    const name = persistOptions.name.trim() || resolveProjectName();
+    const name = (persistOptions.name ?? "").trim() || resolveProjectName();
 
     const record: WorkspaceProjectRecord = {
       id,
@@ -171,13 +276,14 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
       panelState: options.exportPanelData(),
       blueprintDocument: snapshot.blueprintDocument,
       blueprintMeta: snapshot.blueprintMeta,
-      productName: snapshot.productName,
+      productName:
+        typeof snapshot.productName === "string" ? snapshot.productName : resolveProjectName(),
       titleIconDataUrl: snapshot.titleIconDataUrl || undefined,
     };
 
-    await putWorkspaceProject(record);
-    writeWorkspacePreviewCache(record);
-    broadcastWorkspaceProjectUpdate(id, now);
+    await putWorkspaceProject(record, nameSpace());
+    writeWorkspacePreviewCache(record, nameSpace());
+    broadcastWorkspaceProjectUpdate(id, now, nameSpace());
     activeProjectId.value = id;
     activeProjectName.value = name;
     syncedSnapshotRef.value = snapshot;
@@ -191,6 +297,7 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     return runBusyTask(t("common.savingWorkspace"), async () => {
       const name = resolveProjectName();
       const record = await persistProject({ name });
+      emitAbuilderEvent(AbuilderEvents.workspaceAdd, record);
       return { name, id: record.id };
     });
   }
@@ -201,7 +308,7 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
       return handleCreateProject();
     }
     return runBusyTask(t("common.savingWorkspace"), async () => {
-      const existing = await getWorkspaceProject(projectId);
+      const existing = await getWorkspaceProject(projectId, nameSpace());
       const name = resolveProjectName();
       const record = await persistProject({
         id: projectId,
@@ -214,7 +321,7 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
 
   async function handleOpenProject(id: string) {
     await runBusyTask(t("common.loadingWorkspace"), async () => {
-      const record = await getWorkspaceProject(id);
+      const record = await getWorkspaceProject(id, nameSpace());
       if (!record) {
         await refreshProjects();
         throw new Error(t("panel.messages.workspaceNotFound"));
@@ -228,7 +335,7 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
       if (!activeProjectId.value) {
         throw new Error(t("panel.messages.saveWorkspaceFirst"));
       }
-      const existing = await getWorkspaceProject(activeProjectId.value);
+      const existing = await getWorkspaceProject(activeProjectId.value, nameSpace());
       if (!existing) {
         activeProjectId.value = null;
         activeProjectName.value = null;
@@ -237,18 +344,19 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
         throw new Error(t("panel.messages.workspaceNotFound"));
       }
       const name = resolveProjectName() || existing.name;
-      await persistProject({
+      const record = await persistProject({
         id: activeProjectId.value,
         name,
         createdAt: existing.createdAt,
       });
+      emitAbuilderEvent(AbuilderEvents.workspaceSync, record);
       return name;
     });
   }
 
   async function handleDeleteProject(id: string) {
     await runBusyTask(t("common.deletingWorkspace"), async () => {
-      await deleteWorkspaceProject(id);
+      await deleteWorkspaceProject(id, nameSpace());
       if (activeProjectId.value === id) {
         activeProjectId.value = null;
         activeProjectName.value = null;
@@ -266,9 +374,10 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
         await handleSyncProject();
       }
       const record =
-        (await getWorkspaceProject(id)) ?? readWorkspacePreviewCache(id);
+        (await getWorkspaceProject(id, nameSpace())) ??
+        readWorkspacePreviewCache(id, nameSpace());
       if (record) {
-        writeWorkspacePreviewCache(record);
+        writeWorkspacePreviewCache(record, nameSpace());
       }
       const existing = previewWindows.get(id);
       if (existing && !existing.closed) {
@@ -280,9 +389,10 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
         refreshPreviewing();
         return;
       }
+      const ns = nameSpace();
       const win = window.open(
-        buildOnlinePreviewUrl(id),
-        `abuilder-preview-${id}`
+        buildOnlinePreviewUrl(id, ns),
+        previewWindowName(id, ns)
       );
       if (win) {
         previewWindows.set(id, win);

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/parse-workspace-data.ts

@@ -0,0 +1,142 @@
+import {
+  BlueprintGraph,
+  parseBlueprintData,
+  validateBlueprintData,
+  type BlueprintDocument,
+  type BlueprintMetaDraft,
+  type ParseCheckResult,
+} from "@arronqzy/vue-blueprint";
+import type { State } from "@arronqzy/rx-store";
+import { createEmptyPanelState, normalizeImportedPanelState } from "../utils/panelStateIO";
+import {
+  createWorkspaceProjectId,
+  type WorkspaceProjectRecord,
+} from "./workspace-project-db";
+
+export type { ParseCheckResult };
+
+export type WorkspaceParseCheckResult = ParseCheckResult & {
+  view: ParseCheckResult;
+  blueprint: ParseCheckResult;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function extractPanelState(data: unknown): unknown {
+  if (isRecord(data) && data.panelState !== undefined) return data.panelState;
+  return data;
+}
+
+function readBlueprintMeta(raw: unknown): BlueprintMetaDraft {
+  if (!isRecord(raw)) return { name: "", remark: "" };
+  return {
+    name: typeof raw.name === "string" ? raw.name : "",
+    remark: typeof raw.remark === "string" ? raw.remark : "",
+  };
+}
+
+/**
+ * 校验数据能否被视图解析（工作区 `panelState` 或裸面板状态均可）。
+ */
+export function parseViewData(
+  data: unknown
+): ParseCheckResult & { value?: State } {
+  if (data == null) {
+    return { ok: false, error: "empty" };
+  }
+  const normalized = normalizeImportedPanelState(extractPanelState(data));
+  if (!normalized) {
+    return { ok: false, error: "invalid-view-data" };
+  }
+  return { ok: true, value: normalized };
+}
+
+export function validateViewData(data: unknown): ParseCheckResult {
+  const parsed = parseViewData(data);
+  return parsed.ok ? { ok: true } : { ok: false, error: parsed.error };
+}
+
+export { parseBlueprintData, validateBlueprintData };
+
+/**
+ * 构造一份可交给 `initialWorkspace` 的空工作区。
+ */
+export function createEmptyWorkspace(
+  init?: Partial<WorkspaceProjectRecord>
+): WorkspaceProjectRecord {
+  const now = Date.now();
+  return {
+    id: init?.id || createWorkspaceProjectId(),
+    name: init?.name ?? "",
+    createdAt: init?.createdAt ?? now,
+    updatedAt: init?.updatedAt ?? now,
+    panelState: init?.panelState ?? createEmptyPanelState(),
+    blueprintDocument: init?.blueprintDocument ?? BlueprintGraph.empty().document,
+    blueprintMeta: init?.blueprintMeta ?? { name: "", remark: "" },
+    productName: init?.productName ?? "",
+    titleIconDataUrl: init?.titleIconDataUrl,
+  };
+}
+
+/**
+ * 校验完整工作区数据：视图 `panelState` 与蓝图 `blueprintDocument` 都要能解析。
+ */
+export function validateWorkspaceData(data: unknown): WorkspaceParseCheckResult {
+  if (data == null) {
+    const empty = { ok: false, error: "empty" } satisfies ParseCheckResult;
+    return { ok: false, error: "empty", view: empty, blueprint: empty };
+  }
+  if (!isRecord(data)) {
+    const invalid = { ok: false, error: "invalid-workspace-data" } satisfies ParseCheckResult;
+    return {
+      ok: false,
+      error: "invalid-workspace-data",
+      view: invalid,
+      blueprint: invalid,
+    };
+  }
+  const view = validateViewData(data);
+  const blueprint = validateBlueprintData(data);
+  const ok = view.ok && blueprint.ok;
+  return {
+    ok,
+    error: ok ? undefined : "invalid-workspace-data",
+    view,
+    blueprint,
+  };
+}
+
+/**
+ * 解析并规范化工作区。成功时 `value` 可直接作为 `initialWorkspace`。
+ */
+export function parseWorkspaceData(
+  data: unknown
+): WorkspaceParseCheckResult & { value?: WorkspaceProjectRecord } {
+  const check = validateWorkspaceData(data);
+  if (!check.ok || !isRecord(data)) {
+    return check;
+  }
+  const view = parseViewData(data);
+  const blueprint = parseBlueprintData(data);
+  if (!view.value || !blueprint.value) {
+    return check;
+  }
+  const now = Date.now();
+  return {
+    ...check,
+    value: {
+      id: typeof data.id === "string" && data.id ? data.id : createWorkspaceProjectId(),
+      name: typeof data.name === "string" ? data.name : "",
+      createdAt: typeof data.createdAt === "number" ? data.createdAt : now,
+      updatedAt: typeof data.updatedAt === "number" ? data.updatedAt : now,
+      panelState: view.value,
+      blueprintDocument: blueprint.value as BlueprintDocument,
+      blueprintMeta: readBlueprintMeta(data.blueprintMeta),
+      productName: typeof data.productName === "string" ? data.productName : "",
+      titleIconDataUrl:
+        typeof data.titleIconDataUrl === "string" ? data.titleIconDataUrl : undefined,
+    },
+  };
+}

package/src/panel/library/workspace-project-cache.ts

@@ -1,11 +1,19 @@
+import { appStorageKey } from "@arronqzy/blueprint-dsl";
 import type { WorkspaceProjectRecord } from "./workspace-project-db";
 
 const CACHE_PREFIX = "arronqzy-workspace-preview:";
 
-export function writeWorkspacePreviewCache(record: WorkspaceProjectRecord): void {
+function previewCacheKey(projectId: string, nameSpace?: string | null): string {
+  return appStorageKey(CACHE_PREFIX + projectId, nameSpace);
+}
+
+export function writeWorkspacePreviewCache(
+  record: WorkspaceProjectRecord,
+  nameSpace?: string | null
+): void {
   try {
     localStorage.setItem(
-      CACHE_PREFIX + record.id,
+      previewCacheKey(record.id, nameSpace),
       JSON.stringify({ id: record.id, updatedAt: record.updatedAt })
     );
   } catch {
@@ -14,10 +22,11 @@ export function writeWorkspacePreviewCache(record: WorkspaceProjectRecord): void
 }
 
 export function readWorkspacePreviewCache(
-  projectId: string
+  projectId: string,
+  nameSpace?: string | null
 ): WorkspaceProjectRecord | null {
   try {
-    const raw = localStorage.getItem(CACHE_PREFIX + projectId);
+    const raw = localStorage.getItem(previewCacheKey(projectId, nameSpace));
     if (!raw) return null;
     const parsed = JSON.parse(raw) as Partial<WorkspaceProjectRecord> | null;
     if (!parsed || typeof parsed !== "object" || !parsed.panelState) return null;

package/src/panel/library/workspace-project-db.ts

@@ -1,5 +1,6 @@
 import type { BlueprintDocument, BlueprintMetaDraft } from "@arronqzy/vue-blueprint";
 import type { State } from "@arronqzy/rx-store";
+import { appStorageKey } from "@arronqzy/blueprint-dsl";
 
 const DB_NAME = "arronqzy-workspace-projects";
 const DB_VERSION = 1;
@@ -24,9 +25,9 @@ export type WorkspaceProjectRecord = {
   titleIconDataUrl?: string;
 };
 
-function openDb(): Promise<IDBDatabase> {
+function openDb(nameSpace?: string | null): Promise<IDBDatabase> {
   return new Promise((resolve, reject) => {
-    const request = indexedDB.open(DB_NAME, DB_VERSION);
+    const request = indexedDB.open(appStorageKey(DB_NAME, nameSpace), DB_VERSION);
     request.onerror = () => reject(request.error ?? new Error("indexeddb-open-failed"));
     request.onupgradeneeded = () => {
       const db = request.result;
@@ -41,9 +42,10 @@ function openDb(): Promise<IDBDatabase> {
 
 function runTransaction<T>(
   mode: IDBTransactionMode,
-  runner: (store: IDBObjectStore) => IDBRequest<T>
+  runner: (store: IDBObjectStore) => IDBRequest<T>,
+  nameSpace?: string | null
 ): Promise<T> {
-  return openDb().then(
+  return openDb(nameSpace).then(
     (db) =>
       new Promise<T>((resolve, reject) => {
         const tx = db.transaction(STORE_NAME, mode);
@@ -76,8 +78,10 @@ export function createWorkspaceProjectId(): string {
   return `ws-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
 }
 
-export async function listWorkspaceProjects(): Promise<WorkspaceProjectListItem[]> {
-  const db = await openDb();
+export async function listWorkspaceProjects(
+  nameSpace?: string | null
+): Promise<WorkspaceProjectListItem[]> {
+  const db = await openDb(nameSpace);
   return new Promise((resolve, reject) => {
     const tx = db.transaction(STORE_NAME, "readonly");
     const store = tx.objectStore(STORE_NAME);
@@ -109,21 +113,28 @@ export async function listWorkspaceProjects(): Promise<WorkspaceProjectListItem[
 }
 
 export async function getWorkspaceProject(
-  id: string
+  id: string,
+  nameSpace?: string | null
 ): Promise<WorkspaceProjectRecord | null> {
-  const record = await runTransaction<WorkspaceProjectRecord | undefined>("readonly", (store) =>
-    store.get(id)
+  const record = await runTransaction<WorkspaceProjectRecord | undefined>(
+    "readonly",
+    (store) => store.get(id),
+    nameSpace
   );
   return record ?? null;
 }
 
 export async function putWorkspaceProject(
-  record: WorkspaceProjectRecord
+  record: WorkspaceProjectRecord,
+  nameSpace?: string | null
 ): Promise<WorkspaceProjectRecord> {
-  await runTransaction<IDBValidKey>("readwrite", (store) => store.put(record));
+  await runTransaction<IDBValidKey>("readwrite", (store) => store.put(record), nameSpace);
   return record;
 }
 
-export async function deleteWorkspaceProject(id: string): Promise<void> {
-  await runTransaction<undefined>("readwrite", (store) => store.delete(id));
+export async function deleteWorkspaceProject(
+  id: string,
+  nameSpace?: string | null
+): Promise<void> {
+  await runTransaction<undefined>("readwrite", (store) => store.delete(id), nameSpace);
 }

package/src/panel/library/workspace-project-sync.ts

@@ -1,3 +1,5 @@
+import { appStorageKey } from "@arronqzy/blueprint-dsl";
+
 const CHANNEL_PREFIX = "arronqzy-workspace-project";
 
 export type WorkspaceProjectSyncMessage = {
@@ -6,16 +8,22 @@ export type WorkspaceProjectSyncMessage = {
   updatedAt: number;
 };
 
-export function getWorkspaceProjectChannelName(projectId: string): string {
-  return `${CHANNEL_PREFIX}:${projectId}`;
+export function getWorkspaceProjectChannelName(
+  projectId: string,
+  nameSpace?: string | null
+): string {
+  return appStorageKey(`${CHANNEL_PREFIX}:${projectId}`, nameSpace);
 }
 
 export function broadcastWorkspaceProjectUpdate(
   projectId: string,
-  updatedAt: number
+  updatedAt: number,
+  nameSpace?: string | null
 ): void {
   if (typeof BroadcastChannel === "undefined") return;
-  const channel = new BroadcastChannel(getWorkspaceProjectChannelName(projectId));
+  const channel = new BroadcastChannel(
+    getWorkspaceProjectChannelName(projectId, nameSpace)
+  );
   channel.postMessage({
     type: "updated",
     projectId,
@@ -26,12 +34,15 @@ export function broadcastWorkspaceProjectUpdate(
 
 export function subscribeWorkspaceProjectUpdates(
   projectId: string,
-  onUpdate: (message: WorkspaceProjectSyncMessage) => void
+  onUpdate: (message: WorkspaceProjectSyncMessage) => void,
+  nameSpace?: string | null
 ): () => void {
   if (typeof BroadcastChannel === "undefined") {
     return () => {};
   }
-  const channel = new BroadcastChannel(getWorkspaceProjectChannelName(projectId));
+  const channel = new BroadcastChannel(
+    getWorkspaceProjectChannelName(projectId, nameSpace)
+  );
   channel.onmessage = (event: MessageEvent<WorkspaceProjectSyncMessage>) => {
     const data = event.data;
     if (!data || data.type !== "updated" || data.projectId !== projectId) return;

package/src/panel/parseOnlinePreviewSearchParams.ts

@@ -1,13 +1,16 @@
 export function parseOnlinePreviewSearchParams(search: string): {
   projectId: string;
   previewInstanceId?: string;
+  nameSpace?: string;
 } | null {
   const params = new URLSearchParams(search);
   if (params.get("preview") !== "online") return null;
   const projectId = params.get("projectId") ?? params.get("id");
   if (!projectId) return null;
+  const nameSpace = (params.get("ns") ?? params.get("nameSpace") ?? "").trim();
   return {
     projectId,
     previewInstanceId: params.get("pid") ?? undefined,
+    nameSpace: nameSpace || undefined,
   };
 }

package/src/panel/utils/outputScale.ts

@@ -1,14 +1,27 @@
 /** 产物预览是否缩放内部内容（字体等）。默认 false：块仍按视口撑满，内容保持原尺寸以免失真。 */
+import { appStorageKey } from "@arronqzy/blueprint-dsl";
+
 export const OUTPUT_SCALE_STORAGE_KEY = "panel:outputScale";
 
-export function readOutputScale(): boolean {
+export function readOutputScale(nameSpace?: string | null): boolean {
   try {
-    return localStorage.getItem(OUTPUT_SCALE_STORAGE_KEY) === "1";
+    return localStorage.getItem(appStorageKey(OUTPUT_SCALE_STORAGE_KEY, nameSpace)) === "1";
   } catch {
     return false;
   }
 }
 
+export function writeOutputScale(enabled: boolean, nameSpace?: string | null) {
+  try {
+    localStorage.setItem(
+      appStorageKey(OUTPUT_SCALE_STORAGE_KEY, nameSpace),
+      enabled ? "1" : "0"
+    );
+  } catch {
+    // ignore storage errors
+  }
+}
+
 export type PreviewFillScale = {
   vw: number;
   vh: number;

package/src/panel/utils/panelStateIO.ts

@@ -26,6 +26,24 @@ export function normalizeImportedPanelState(state: unknown): State | null {
   return next;
 }
 
+export function createEmptyPanelState(): State {
+  return {
+    root: {
+      id: "root",
+      type: "root",
+      props: {},
+      children: [],
+    },
+    selectedIds: [],
+    variables: {
+      counter: 0,
+      isOpen: false,
+      layers: [DEFAULT_LAYER],
+      activeLayerId: DEFAULT_LAYER_ID,
+    },
+  };
+}
+
 export function parseAllPanelElements(state: State): PanelElement[] {
   return (state.root.children ?? [])
     .filter((node) => {