@arronqzy/vue-view 0.1.24 → 0.1.25

package/README.md

@@ -49,17 +49,7 @@ import {
 } from "@arronqzy/vue-view";
 ```
 
-创建 / 同步发出 `workspace:add` / `workspace:sync`，删除工作区发出 `workspace:delete`（参数 `{ ids, nameSpace }`）。`parseWorkspaceData` 的 `value` 可作 `initialWorkspace`。
-
-浏览器里的本地数据可以读取和清理，最后一个参数都是 `nameSpace`：
-
-- 工作区：`listWorkspaceProjects` / `getWorkspaceProject` / `deleteWorkspaceProject` / `clearWorkspaceProjects`
-- 蓝图库：`listBlueprintLibrary` / `getBlueprintLibraryRecord` / `deleteBlueprintLibraryRecord` / `clearBlueprintLibrary`
-- 蓝图执行日志：`listExecutionRunRecords` / `getExecutionRunRecord` / `deleteExecutionRunRecord` / `clearAllExecutionRunRecords` / `purgeExecutionRunsOlderThan` / `trimExecutionRunRecordsToMax`，保留策略用 `readExecutionLogSettings` / `writeExecutionLogSettings`
-- 接口集合：`listApiCollectionRecords` / `deleteApiCollection` / `clearApiCollections`
-- `clearAbuilderStorage`：一次清空以上四类，返回各自删除数量
-
-工作区、蓝图库的写入接口不导出（由编辑器自己维护）。`getPreviewSnapshot` 只在 React 包实现。
+创建 / 同步发出 `workspace:add` / `workspace:sync`（载荷含 `nameSpace`），删除发出 `workspace:delete`。另有 `blueprint-library:changed` / `api-collection:changed`。`parseWorkspaceData` 的 `value` 可作 `initialWorkspace`；带 `id` 时默认同步进 IndexedDB。也支持 `workspaceId` prop、`ref`（`AbuilderViewHandle`）以及 `put*` / `openWorkspace` / `getCurrentWorkspace` / `getPreviewSnapshot` 等与 React 对齐的公开 API。
 
 ## 和 React 版的差别
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arronqzy/vue-view",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Vue 3 visual view editor for Abuilder (Ant Design Vue)",
   "license": "MIT",
   "type": "module",
@@ -23,13 +23,13 @@
     "selecto": "^1.26.3",
     "uuid": "^13.0.0",
     "vue": "^3.5.13",
-    "@arronqzy/i18n": "0.1.17",
-    "@arronqzy/rx-store": "1.0.8",
     "@arronqzy/blueprint-dsl": "1.0.17",
+    "@arronqzy/i18n": "0.1.17",
     "@arronqzy/view-scene3d": "0.1.5",
-    "@arronqzy/view-table": "0.1.8",
     "@arronqzy/vue-rx-store": "0.1.6",
-    "@arronqzy/vue-blueprint": "0.1.18"
+    "@arronqzy/view-table": "0.1.8",
+    "@arronqzy/vue-blueprint": "0.1.19",
+    "@arronqzy/rx-store": "1.0.8"
   },
   "peerDependencies": {
     "vue": "^3.4.0"
@@ -39,8 +39,8 @@
     "eslint": "^8.57.0",
     "typescript": "^5.5.4",
     "vue-tsc": "^2.2.0",
-    "@arronqzy/eslint-config": "0.0.0",
-    "@arronqzy/typescript-config": "1.0.0"
+    "@arronqzy/typescript-config": "1.0.0",
+    "@arronqzy/eslint-config": "0.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -16,17 +16,24 @@ export { createWorkspaceProjectId } from "./panel/library/workspace-project-db";
 export {
   listWorkspaceProjects,
   getWorkspaceProject,
+  putWorkspaceProject,
+  upsertWorkspaceProject,
   deleteWorkspaceProject,
   clearWorkspaceProjects,
 } from "./panel/library/workspace-storage";
-export type { WorkspaceProjectListItem } from "./panel/library/workspace-storage";
+export type {
+  WorkspaceProjectListItem,
+  PutWorkspaceProjectOptions,
+} from "./panel/library/workspace-storage";
 export {
   listBlueprintLibrary,
   getBlueprintLibraryRecord,
+  putBlueprintLibraryRecord,
   deleteBlueprintLibraryRecord,
   clearBlueprintLibrary,
   listExecutionRunRecords,
   getExecutionRunRecord,
+  putExecutionRunRecord,
   deleteExecutionRunRecord,
   clearAllExecutionRunRecords,
   purgeExecutionRunsOlderThan,
@@ -34,6 +41,8 @@ export {
   readExecutionLogSettings,
   writeExecutionLogSettings,
   listApiCollectionRecords,
+  putApiCollection,
+  upsertApiCollectionFromJson,
   deleteApiCollection,
   clearApiCollections,
   clearAbuilderStorage,
@@ -45,6 +54,8 @@ export type {
   ExecutionRunRecord,
   ExecutionLogSettings,
   ApiCollectionRecord,
+  UpsertApiCollectionInput,
+  UpsertApiCollectionResult,
 } from "./panel/library/abuilder-storage";
 export {
   addEventSubscription,
@@ -53,14 +64,27 @@ export {
 export type {
   AbuilderEventName,
   AbuilderEventPayloadMap,
+  AddEventSubscriptionOptions,
   WorkspaceAddEventPayload,
   WorkspaceSyncEventPayload,
   WorkspaceDeleteEventPayload,
+  BlueprintLibraryChangedEventPayload,
   ApiCollectionUploadStartEventPayload,
   ApiCollectionUploadSuccessEventPayload,
+  ApiCollectionChangedEventPayload,
   WorkspaceData,
 } from "./panel/library/event-subscription";
+export {
+  getCurrentWorkspace,
+  openWorkspace,
+  createWorkspace,
+  saveWorkspace,
+  syncWorkspace,
+} from "./panel/library/abuilder-view-handle";
+export type { AbuilderViewHandle } from "./panel/library/abuilder-view-handle";
 export type {
   ParseCheckResult,
   WorkspaceParseCheckResult,
 } from "./panel/library/parse-workspace-data";
+export { getPreviewSnapshot } from "./panel/library/preview-snapshot";
+export type { GetPreviewSnapshotOptions } from "./panel/library/preview-snapshot";

package/src/panel/VueViewOnlinePreview.vue

@@ -40,6 +40,8 @@ import {
   resolvePreviewLayerElements,
 } from "./utils/panelStateIO";
 import { applyPreviewSceneFill, readOutputScale } from "./utils/outputScale";
+import { registerPreviewSnapshotProvider } from "./library/preview-snapshot";
+import { capturePreviewSceneElement } from "./library/capture-preview-snapshot";
 
 const { t, locale } = useI18n();
 useBlueprintDslLocaleSync();
@@ -292,6 +294,29 @@ onMounted(() => {
   onUnmounted(() => window.removeEventListener("resize", onResize));
 });
 
+watch(
+  [layoutReady, sceneRef, sceneBounds, fillScale, outputScale],
+  () => {
+    if (!layoutReady.value || !sceneRef.value) {
+      registerPreviewSnapshotProvider(null);
+      return;
+    }
+    registerPreviewSnapshotProvider(async () => {
+      const scene = sceneRef.value;
+      if (!scene) return null;
+      const width = outputScale.value
+        ? sceneBounds.value.width
+        : sceneBounds.value.width * fillScale.value.scaleX;
+      const height = outputScale.value
+        ? sceneBounds.value.height
+        : sceneBounds.value.height * fillScale.value.scaleY;
+      return capturePreviewSceneElement(scene, width, height);
+    });
+  },
+  { immediate: true }
+);
+onUnmounted(() => registerPreviewSnapshotProvider(null));
+
 function noopUpdate() {}
 function noopSelect() {}
 </script>

package/src/panel/VueViewPanel.vue

@@ -1,5 +1,14 @@
 <script setup lang="ts">
 import { computed, onMounted, onUnmounted, ref, shallowRef, watch } from "vue";
+import {
+  registerAbuilderViewHandle,
+  type AbuilderViewHandle,
+} from "./library/abuilder-view-handle";
+import {
+  captureEditorPreviewSnapshot,
+  registerPreviewSnapshotProvider,
+} from "./library/preview-snapshot";
+import { readOutputScale } from "./utils/outputScale";
 import type { State } from "@arronqzy/rx-store";
 import {
   useBlueprintDslLocaleSync,
@@ -90,6 +99,11 @@ const props = withDefaults(
     initialZoom?: number;
     nameSpace?: string | null;
     initialWorkspace?: WorkspaceProjectRecord | null;
+    /**
+     * 按 IndexedDB id 打开工作区（不 remount）。
+     * 与 initialWorkspace 同时存在时：首次优先完整记录；之后 id 变化从 IndexedDB 打开。
+     */
+    workspaceId?: string | null;
     /** 顶栏「设置 → 关于」展示的 npm 包名 */
     packageName?: string | null;
     /** 顶栏「设置 → 关于」展示的包版本号 */
@@ -99,6 +113,7 @@ const props = withDefaults(
     initialZoom: 1,
     nameSpace: null,
     initialWorkspace: null,
+    workspaceId: null,
     packageName: null,
     packageVersion: null,
   }
@@ -470,9 +485,39 @@ const workspaceProjects = useWorkspaceProjects({
   panelRevision: computed(() => `${historyCursor.value}|${allElements.value.length}`),
   onProjectApplied: handleWorkspaceProjectApplied,
   initialWorkspace: () => props.initialWorkspace,
+  workspaceId: () => props.workspaceId,
   nameSpace: () => props.nameSpace,
 });
 
+const viewHandle: AbuilderViewHandle = {
+  getNameSpace: () => props.nameSpace ?? null,
+  getCurrentWorkspace: () => workspaceProjects.getCurrentWorkspaceRecord(),
+  openWorkspace: (idOrRecord) => workspaceProjects.handleOpenProject(idOrRecord),
+  createWorkspace: () => workspaceProjects.handleCreateProject(),
+  saveWorkspace: () => workspaceProjects.handleSaveProject(),
+  syncWorkspace: () => workspaceProjects.handleSyncProject(),
+};
+
+defineExpose(viewHandle);
+onUnmounted(registerAbuilderViewHandle(viewHandle));
+
+watch(
+  [canvasEl, allElements, layers, activeLayerId, () => props.nameSpace],
+  () => {
+    registerPreviewSnapshotProvider(async () =>
+      captureEditorPreviewSnapshot({
+        canvasRoot: canvasEl.value,
+        allElements: allElements.value,
+        layers: layers.value,
+        activeLayerId: activeLayerId.value,
+        outputScale: readOutputScale(props.nameSpace),
+      })
+    );
+  },
+  { immediate: true }
+);
+onUnmounted(() => registerPreviewSnapshotProvider(null));
+
 const blueprintLifecycleToken = computed(() => {
   const doc = blueprintGraph.value.document;
   const nodes = doc.nodes;
@@ -646,7 +691,10 @@ function handleApiCollectionUploadStart(info: {
   fileNames: string[];
   count: number;
 }) {
-  emitAbuilderEvent(AbuilderEvents.apiCollectionUploadStart, info);
+  emitAbuilderEvent(AbuilderEvents.apiCollectionUploadStart, {
+    ...info,
+    nameSpace: props.nameSpace ?? null,
+  });
 }
 
 function handleApiCollectionUploadSuccess(info: {
@@ -657,7 +705,10 @@ function handleApiCollectionUploadSuccess(info: {
     persistLocal: boolean;
   }>;
 }) {
-  emitAbuilderEvent(AbuilderEvents.apiCollectionUploadSuccess, info);
+  emitAbuilderEvent(AbuilderEvents.apiCollectionUploadSuccess, {
+    ...info,
+    nameSpace: props.nameSpace ?? null,
+  });
 }
 
 function handleApiCollectionSync(record: {

package/src/panel/hooks/useWorkspaceProjects.ts

@@ -11,16 +11,16 @@ import {
   createWorkspaceProjectId,
   getWorkspaceProject,
   listWorkspaceProjects,
-  putWorkspaceProject,
   type WorkspaceProjectListItem,
   type WorkspaceProjectRecord,
 } from "../library/workspace-project-db";
-import { deleteWorkspaceProject } from "../library/workspace-storage";
 import {
-  broadcastWorkspaceProjectUpdate,
-  subscribeWorkspaceProjectsChanged,
-} from "../library/workspace-project-sync";
+  deleteWorkspaceProject,
+  putWorkspaceProject,
+} from "../library/workspace-storage";
+import { subscribeWorkspaceProjectsChanged } from "../library/workspace-project-sync";
 import { writeWorkspacePreviewCache, readWorkspacePreviewCache } from "../library/workspace-project-cache";
+import { normalizeAppNameSpace } from "@arronqzy/blueprint-dsl";
 import {
   cloneWorkspaceSnapshot,
   workspaceSnapshotsEqual,
@@ -48,6 +48,11 @@ export type UseWorkspaceProjectsOptions = {
   onProjectApplied?: (record: WorkspaceProjectRecord) => void;
   /** 外部传入的初始工作区，挂载后自动加载（不触发 onProjectApplied） */
   initialWorkspace?: MaybeRefOrGetter<WorkspaceProjectRecord | null | undefined>;
+  /**
+   * 按 IndexedDB id 打开工作区。与 initialWorkspace 同时存在时：
+   * 首次优先 initialWorkspace；之后 workspaceId 变化会从 IndexedDB 打开。
+   */
+  workspaceId?: MaybeRefOrGetter<string | null | undefined>;
   nameSpace?: MaybeRefOrGetter<string | null | undefined>;
 };
 
@@ -94,9 +99,11 @@ function workspaceApplyKey(record: WorkspaceProjectRecord): string {
 export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
   const { t, locale } = useI18nOptional();
   const nameSpace = () => toValue(options.nameSpace) ?? null;
+  const eventNameSpace = () => normalizeAppNameSpace(nameSpace()) || null;
   const projects = ref<WorkspaceProjectListItem[]>([]);
   const activeProjectId = ref<string | null>(null);
   const activeProjectName = ref<string | null>(null);
+  let activeCreatedAt: number | null = null;
   const syncedSnapshotRef = shallowRef<WorkspaceSnapshot | null>(null);
   let syncedPanelRevision: unknown = null;
   let pendingRevisionSync = false;
@@ -150,7 +157,9 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
         const active = activeProjectId.value;
         const removedActive =
           message.type === "cleared" ||
-          (active !== null && message.projectIds.includes(active));
+          (message.type === "deleted" &&
+            active !== null &&
+            message.projectIds.includes(active));
         if (removedActive) {
           activeProjectId.value = null;
           activeProjectName.value = null;
@@ -187,9 +196,61 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     return !workspaceSnapshotsEqual(buildCurrentSnapshot(), syncedSnapshotRef.value);
   });
 
+  async function ensureWorkspaceInIndexedDb(record: WorkspaceProjectRecord) {
+    const id = typeof record.id === "string" ? record.id.trim() : "";
+    if (!id) return;
+    try {
+      const existing = await getWorkspaceProject(id, nameSpace());
+      const incomingUpdatedAt =
+        typeof record.updatedAt === "number" && Number.isFinite(record.updatedAt)
+          ? record.updatedAt
+          : 0;
+      if (existing && existing.updatedAt >= incomingUpdatedAt) {
+        return;
+      }
+      const now = Date.now();
+      const name =
+        (typeof record.name === "string" && record.name.trim()) ||
+        (typeof record.productName === "string" && record.productName.trim()) ||
+        t("panel.defaults.unnamedProduct");
+      const toStore: WorkspaceProjectRecord = {
+        ...record,
+        id,
+        name,
+        createdAt: existing?.createdAt ?? record.createdAt ?? now,
+        updatedAt: incomingUpdatedAt || now,
+        panelState:
+          normalizeImportedPanelState(record.panelState) ??
+          existing?.panelState ??
+          createEmptyPanelState(),
+        blueprintDocument:
+          parseBlueprintData(record.blueprintDocument).value ??
+          existing?.blueprintDocument ??
+          BlueprintGraph.empty().document,
+        blueprintMeta: {
+          name:
+            record.blueprintMeta?.name ??
+            existing?.blueprintMeta?.name ??
+            t("panel.defaults.unnamedBlueprint"),
+          remark:
+            record.blueprintMeta?.remark ?? existing?.blueprintMeta?.remark ?? "",
+        },
+        productName:
+          typeof record.productName === "string" && record.productName.trim()
+            ? record.productName
+            : existing?.productName ?? t("panel.defaults.unnamedProduct"),
+        titleIconDataUrl: record.titleIconDataUrl ?? existing?.titleIconDataUrl,
+      };
+      await putWorkspaceProject(toStore, nameSpace());
+      await refreshProjects();
+    } catch (error) {
+      console.warn("[abuilder] ensureWorkspaceInIndexedDb failed", error);
+    }
+  }
+
   function applyProjectRecord(
     record: WorkspaceProjectRecord,
-    applyOptions?: { notifyApplied?: boolean }
+    applyOptions?: { notifyApplied?: boolean; persistToIndexedDb?: boolean }
   ) {
     const parsedBlueprint = parseBlueprintData(record.blueprintDocument);
     const blueprintDocument =
@@ -213,6 +274,10 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     options.setTitleIconDataUrl(titleIconDataUrl);
     activeProjectId.value = record.id || null;
     activeProjectName.value = record.name ?? null;
+    activeCreatedAt =
+      typeof record.createdAt === "number" && Number.isFinite(record.createdAt)
+        ? record.createdAt
+        : Date.now();
     syncedSnapshotRef.value = cloneWorkspaceSnapshot({
       blueprintDocument,
       blueprintMeta,
@@ -221,15 +286,23 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     });
     syncedPanelRevision = toValue(options.panelRevision);
     pendingRevisionSync = true;
+    const normalized: WorkspaceProjectRecord = {
+      ...record,
+      id: record.id,
+      name: record.name ?? productName,
+      createdAt: activeCreatedAt,
+      updatedAt: record.updatedAt ?? Date.now(),
+      blueprintDocument,
+      blueprintMeta,
+      panelState,
+      productName,
+      titleIconDataUrl: titleIconDataUrl || undefined,
+    };
     if (applyOptions?.notifyApplied !== false) {
-      options.onProjectApplied?.({
-        ...record,
-        blueprintDocument,
-        blueprintMeta,
-        panelState,
-        productName,
-        titleIconDataUrl: titleIconDataUrl || undefined,
-      });
+      options.onProjectApplied?.(normalized);
+    }
+    if (applyOptions?.persistToIndexedDb) {
+      void ensureWorkspaceInIndexedDb(normalized);
     }
   }
 
@@ -244,46 +317,13 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     options.setTitleIconDataUrl("");
     activeProjectId.value = null;
     activeProjectName.value = null;
+    activeCreatedAt = 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();
-    }
-  );
+  let workspaceIdApplied: string | null = null;
 
   async function persistProject(persistOptions: {
     id?: string;
@@ -294,7 +334,7 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
       const snapshot = cloneWorkspaceSnapshot(buildCurrentSnapshot());
       const now = Date.now();
       const id = persistOptions.id ?? createWorkspaceProjectId();
-      const createdAt = persistOptions.createdAt ?? now;
+      const createdAt = persistOptions.createdAt ?? activeCreatedAt ?? now;
       const name = (persistOptions.name ?? "").trim() || resolveProjectName();
 
       let panelState: State;
@@ -320,10 +360,9 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
       };
 
       await putWorkspaceProject(record, nameSpace());
-      writeWorkspacePreviewCache(record, nameSpace());
-      broadcastWorkspaceProjectUpdate(id, now, nameSpace());
       activeProjectId.value = id;
       activeProjectName.value = name;
+      activeCreatedAt = createdAt;
       syncedSnapshotRef.value = snapshot;
       syncedPanelRevision = toValue(options.panelRevision);
       pendingRevisionSync = false;
@@ -334,11 +373,40 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     }
   }
 
+  function getCurrentWorkspaceRecord(): WorkspaceProjectRecord | null {
+    if (!activeProjectId.value) return null;
+    try {
+      const snapshot = buildCurrentSnapshot();
+      const panelState = options.exportPanelData();
+      const now = Date.now();
+      return {
+        id: activeProjectId.value,
+        name: activeProjectName.value || resolveProjectName(),
+        createdAt: activeCreatedAt ?? now,
+        updatedAt: now,
+        panelState,
+        blueprintDocument: snapshot.blueprintDocument,
+        blueprintMeta: snapshot.blueprintMeta,
+        productName:
+          typeof snapshot.productName === "string"
+            ? snapshot.productName
+            : resolveProjectName(),
+        titleIconDataUrl: snapshot.titleIconDataUrl || undefined,
+      };
+    } catch (error) {
+      console.warn("[abuilder] getCurrentWorkspace failed", error);
+      return null;
+    }
+  }
+
   async function handleCreateProject() {
     return runBusyTask(t("common.savingWorkspace"), async () => {
       const name = resolveProjectName();
       const record = await persistProject({ name });
-      emitAbuilderEvent(AbuilderEvents.workspaceAdd, record);
+      emitAbuilderEvent(AbuilderEvents.workspaceAdd, {
+        ...record,
+        nameSpace: eventNameSpace(),
+      });
       return { name, id: record.id };
     });
   }
@@ -354,16 +422,24 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
       const record = await persistProject({
         id: projectId,
         name,
-        createdAt: existing?.createdAt,
+        createdAt: existing?.createdAt ?? activeCreatedAt ?? undefined,
+      });
+      emitAbuilderEvent(AbuilderEvents.workspaceSync, {
+        ...record,
+        nameSpace: eventNameSpace(),
       });
       return { name, id: record.id };
     });
   }
 
-  async function handleOpenProject(id: string) {
+  async function handleOpenProject(idOrRecord: string | WorkspaceProjectRecord) {
     try {
       await runBusyTask(t("common.loadingWorkspace"), async () => {
-        const record = await getWorkspaceProject(id, nameSpace());
+        if (typeof idOrRecord !== "string") {
+          applyProjectRecord(idOrRecord, { persistToIndexedDb: true });
+          return;
+        }
+        const record = await getWorkspaceProject(idOrRecord, nameSpace());
         if (!record) {
           await refreshProjects();
           throw new Error(t("panel.messages.workspaceNotFound"));
@@ -381,20 +457,17 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
         throw new Error(t("panel.messages.saveWorkspaceFirst"));
       }
       const existing = await getWorkspaceProject(activeProjectId.value, nameSpace());
-      if (!existing) {
-        activeProjectId.value = null;
-        activeProjectName.value = null;
-        syncedSnapshotRef.value = null;
-        await refreshProjects();
-        throw new Error(t("panel.messages.workspaceNotFound"));
-      }
-      const name = resolveProjectName() || existing.name;
+      const name =
+        resolveProjectName() || existing?.name || activeProjectName.value || "";
       const record = await persistProject({
         id: activeProjectId.value,
         name,
-        createdAt: existing.createdAt,
+        createdAt: existing?.createdAt ?? activeCreatedAt ?? undefined,
+      });
+      emitAbuilderEvent(AbuilderEvents.workspaceSync, {
+        ...record,
+        nameSpace: eventNameSpace(),
       });
-      emitAbuilderEvent(AbuilderEvents.workspaceSync, record);
       return name;
     });
   }
@@ -406,6 +479,7 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
         if (activeProjectId.value === id) {
           activeProjectId.value = null;
           activeProjectName.value = null;
+          activeCreatedAt = null;
           syncedSnapshotRef.value = null;
         }
         previewWindows.delete(id);
@@ -456,6 +530,73 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     });
   }
 
+  function bootstrapInitialWorkspace() {
+    const initialWorkspace = toValue(options.initialWorkspace) ?? null;
+    const workspaceIdRaw = toValue(options.workspaceId);
+    const workspaceId =
+      typeof workspaceIdRaw === "string" ? workspaceIdRaw.trim() : "";
+    if (!bootstrapped) {
+      bootstrapped = true;
+      if (hasWorkspacePayload(initialWorkspace)) {
+        applyProjectRecord(initialWorkspace, {
+          notifyApplied: false,
+          persistToIndexedDb: true,
+        });
+        appliedWorkspaceKey = workspaceApplyKey(initialWorkspace);
+        if (initialWorkspace.id) workspaceIdApplied = initialWorkspace.id;
+      } else if (workspaceId) {
+        workspaceIdApplied = workspaceId;
+        void handleOpenProject(workspaceId);
+      } else {
+        applyEmptyWorkspace();
+      }
+      return;
+    }
+    if (!hasWorkspacePayload(initialWorkspace)) return;
+    const key = workspaceApplyKey(initialWorkspace);
+    if (appliedWorkspaceKey === key) return;
+    appliedWorkspaceKey = key;
+    if (initialWorkspace.id) workspaceIdApplied = initialWorkspace.id;
+    applyProjectRecord(initialWorkspace, {
+      notifyApplied: false,
+      persistToIndexedDb: true,
+    });
+  }
+
+  onMounted(() => {
+    bootstrapInitialWorkspace();
+    void refreshProjects();
+    previewPollTimer = window.setInterval(refreshPreviewing, 2000);
+  });
+
+  watch(
+    () => {
+      const record = toValue(options.initialWorkspace);
+      return record ? workspaceApplyKey(record) : "";
+    },
+    () => {
+      bootstrapInitialWorkspace();
+    }
+  );
+
+  watch(
+    () => {
+      const raw = toValue(options.workspaceId);
+      return typeof raw === "string" ? raw.trim() : "";
+    },
+    (id) => {
+      if (!bootstrapped) return;
+      if (!id) return;
+      if (workspaceIdApplied === id) return;
+      if (activeProjectId.value === id) {
+        workspaceIdApplied = id;
+        return;
+      }
+      workspaceIdApplied = id;
+      void handleOpenProject(id);
+    }
+  );
+
   return {
     projects,
     activeProjectId,
@@ -468,6 +609,7 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     handleSyncProject,
     handleDeleteProject,
     handlePreviewProject,
+    getCurrentWorkspaceRecord,
     refreshProjects,
   };
 }