@arronqzy/react-view 1.0.38 → 1.0.40

package/src/panel/hooks/useWorkspaceProjects.ts

@@ -7,16 +7,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,
@@ -45,6 +45,11 @@ export type UseWorkspaceProjectsOptions = {
   onProjectApplied?: (record: WorkspaceProjectRecord) => void;
   /** 外部传入的初始工作区，挂载后自动加载（不触发 onProjectApplied） */
   initialWorkspace?: WorkspaceProjectRecord | null;
+  /**
+   * 按 IndexedDB id 打开工作区。与 `initialWorkspace` 同时存在时：
+   * 首次优先 `initialWorkspace`；之后 `workspaceId` 变化会从 IndexedDB 打开。
+   */
+  workspaceId?: string | null;
   /** 隔离 IndexedDB / 预览缓存 / 同步频道 */
   nameSpace?: string | null;
 };
@@ -103,17 +108,20 @@ export function useWorkspaceProjects({
   panelRevision,
   onProjectApplied,
   initialWorkspace,
+  workspaceId = null,
   nameSpace = null,
 }: UseWorkspaceProjectsOptions) {
   const { t } = useI18nOptional();
   const [projects, setProjects] = useState<WorkspaceProjectListItem[]>([]);
   const [activeProjectId, setActiveProjectId] = useState<string | null>(null);
   const [activeProjectName, setActiveProjectName] = useState<string | null>(null);
+  const activeCreatedAtRef = useRef<number | null>(null);
   const syncedSnapshotRef = useRef<WorkspaceSnapshot | null>(null);
   const syncedPanelRevisionRef = useRef<unknown>(null);
   const pendingRevisionSyncRef = useRef(false);
   const previewWindowsRef = useRef(new Map<string, Window>());
   const [previewingProjectIds, setPreviewingProjectIds] = useState<string[]>([]);
+  const eventNameSpace = normalizeAppNameSpace(nameSpace) || null;
 
   const refreshPreviewing = useCallback(() => {
     const ids: string[] = [];
@@ -166,7 +174,9 @@ export function useWorkspaceProjects({
     return subscribeWorkspaceProjectsChanged((message) => {
       const removedActive =
         message.type === "cleared" ||
-        (activeProjectId !== null && message.projectIds.includes(activeProjectId));
+        (message.type === "deleted" &&
+          activeProjectId !== null &&
+          message.projectIds.includes(activeProjectId));
       if (removedActive) {
         setActiveProjectId(null);
         setActiveProjectName(null);
@@ -197,8 +207,67 @@ export function useWorkspaceProjects({
     buildCurrentSnapshot,
   ]);
 
+  const ensureWorkspaceInIndexedDb = useCallback(
+    async (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);
+      }
+    },
+    [nameSpace, refreshProjects, t]
+  );
+
   const applyProjectRecord = useCallback(
-    (record: WorkspaceProjectRecord, options?: { notifyApplied?: boolean }) => {
+    (
+      record: WorkspaceProjectRecord,
+      options?: { notifyApplied?: boolean; persistToIndexedDb?: boolean }
+    ) => {
       const parsedBlueprint = parseBlueprintData(record.blueprintDocument);
       const blueprintDocument =
         parsedBlueprint.value ?? BlueprintGraph.empty().document;
@@ -221,6 +290,10 @@ export function useWorkspaceProjects({
       setTitleIconDataUrl(titleIconDataUrl);
       setActiveProjectId(record.id || null);
       setActiveProjectName(record.name ?? null);
+      activeCreatedAtRef.current =
+        typeof record.createdAt === "number" && Number.isFinite(record.createdAt)
+          ? record.createdAt
+          : Date.now();
       syncedSnapshotRef.current = cloneWorkspaceSnapshot({
         blueprintDocument,
         blueprintMeta,
@@ -229,18 +302,27 @@ export function useWorkspaceProjects({
       });
       syncedPanelRevisionRef.current = panelRevision;
       pendingRevisionSyncRef.current = true;
+      const normalized: WorkspaceProjectRecord = {
+        ...record,
+        id: record.id,
+        name: record.name ?? productName,
+        createdAt: activeCreatedAtRef.current,
+        updatedAt: record.updatedAt ?? Date.now(),
+        blueprintDocument,
+        blueprintMeta,
+        panelState,
+        productName,
+        titleIconDataUrl: titleIconDataUrl || undefined,
+      };
       if (options?.notifyApplied !== false) {
-        onProjectApplied?.({
-          ...record,
-          blueprintDocument,
-          blueprintMeta,
-          panelState,
-          productName,
-          titleIconDataUrl: titleIconDataUrl || undefined,
-        });
+        onProjectApplied?.(normalized);
+      }
+      if (options?.persistToIndexedDb) {
+        void ensureWorkspaceInIndexedDb(normalized);
       }
     },
     [
+      ensureWorkspaceInIndexedDb,
       importPanelData,
       onProjectApplied,
       setBlueprintGraph,
@@ -263,6 +345,7 @@ export function useWorkspaceProjects({
     setTitleIconDataUrl("");
     setActiveProjectId(null);
     setActiveProjectName(null);
+    activeCreatedAtRef.current = null;
     syncedSnapshotRef.current = null;
   }, [
     importPanelData,
@@ -275,23 +358,7 @@ export function useWorkspaceProjects({
 
   const initialWorkspaceAppliedKeyRef = useRef<string | null>(null);
   const bootstrappedRef = useRef(false);
-  useEffect(() => {
-    if (!bootstrappedRef.current) {
-      bootstrappedRef.current = true;
-      if (hasWorkspacePayload(initialWorkspace)) {
-        applyProjectRecord(initialWorkspace, { notifyApplied: false });
-        initialWorkspaceAppliedKeyRef.current = workspaceApplyKey(initialWorkspace);
-      } else {
-        applyEmptyWorkspace();
-      }
-      return;
-    }
-    if (!hasWorkspacePayload(initialWorkspace)) return;
-    const key = workspaceApplyKey(initialWorkspace);
-    if (initialWorkspaceAppliedKeyRef.current === key) return;
-    initialWorkspaceAppliedKeyRef.current = key;
-    applyProjectRecord(initialWorkspace, { notifyApplied: false });
-  }, [applyEmptyWorkspace, applyProjectRecord, initialWorkspace]);
+  const workspaceIdAppliedRef = useRef<string | null>(null);
 
   const persistProject = useCallback(
     async (options: { id?: string; name: string; createdAt?: number }) => {
@@ -299,7 +366,7 @@ export function useWorkspaceProjects({
         const snapshot = cloneWorkspaceSnapshot(buildCurrentSnapshot());
         const now = Date.now();
         const id = options.id ?? createWorkspaceProjectId();
-        const createdAt = options.createdAt ?? now;
+        const createdAt = options.createdAt ?? activeCreatedAtRef.current ?? now;
         const name = (options.name ?? "").trim() || resolveProjectName();
 
         let panelState: State;
@@ -325,10 +392,9 @@ export function useWorkspaceProjects({
         };
 
         await putWorkspaceProject(record, nameSpace);
-        writeWorkspacePreviewCache(record, nameSpace);
-        broadcastWorkspaceProjectUpdate(id, now, nameSpace);
         setActiveProjectId(id);
         setActiveProjectName(name);
+        activeCreatedAtRef.current = createdAt;
         syncedSnapshotRef.current = snapshot;
         syncedPanelRevisionRef.current = panelRevision;
         pendingRevisionSyncRef.current = false;
@@ -349,14 +415,49 @@ export function useWorkspaceProjects({
     ]
   );
 
+  const getCurrentWorkspaceRecord = useCallback((): WorkspaceProjectRecord | null => {
+    if (!activeProjectId) return null;
+    try {
+      const snapshot = buildCurrentSnapshot();
+      const panelState = exportPanelData();
+      const now = Date.now();
+      return {
+        id: activeProjectId,
+        name: activeProjectName || resolveProjectName(),
+        createdAt: activeCreatedAtRef.current ?? 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;
+    }
+  }, [
+    activeProjectId,
+    activeProjectName,
+    buildCurrentSnapshot,
+    exportPanelData,
+    resolveProjectName,
+  ]);
+
   const handleCreateProject = useCallback(async () => {
     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 };
     });
-  }, [persistProject, resolveProjectName, t]);
+  }, [eventNameSpace, persistProject, resolveProjectName, t]);
 
   const handleSaveProject = useCallback(async () => {
     if (!activeProjectId) {
@@ -368,17 +469,33 @@ export function useWorkspaceProjects({
       const record = await persistProject({
         id: activeProjectId,
         name,
-        createdAt: existing?.createdAt,
+        createdAt: existing?.createdAt ?? activeCreatedAtRef.current ?? undefined,
+      });
+      emitAbuilderEvent(AbuilderEvents.workspaceSync, {
+        ...record,
+        nameSpace: eventNameSpace,
       });
       return { name, id: record.id };
     });
-  }, [activeProjectId, handleCreateProject, nameSpace, persistProject, resolveProjectName, t]);
+  }, [
+    activeProjectId,
+    eventNameSpace,
+    handleCreateProject,
+    nameSpace,
+    persistProject,
+    resolveProjectName,
+    t,
+  ]);
 
   const handleOpenProject = useCallback(
-    async (id: string) => {
+    async (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"));
@@ -397,24 +514,29 @@ export function useWorkspaceProjects({
       if (!activeProjectId) {
         throw new Error(t("panel.messages.saveWorkspaceFirst"));
       }
+      // 本地无记录时 upsert，避免宿主 initialWorkspace 未落盘后同步报错
       const existing = await getWorkspaceProject(activeProjectId, nameSpace);
-      if (!existing) {
-        setActiveProjectId(null);
-        setActiveProjectName(null);
-        syncedSnapshotRef.current = null;
-        await refreshProjects();
-        throw new Error(t("panel.messages.workspaceNotFound"));
-      }
-      const name = resolveProjectName() || existing.name;
+      const name = resolveProjectName() || existing?.name || activeProjectName || "";
       const record = await persistProject({
         id: activeProjectId,
         name,
-        createdAt: existing.createdAt,
+        createdAt: existing?.createdAt ?? activeCreatedAtRef.current ?? undefined,
+      });
+      emitAbuilderEvent(AbuilderEvents.workspaceSync, {
+        ...record,
+        nameSpace: eventNameSpace,
       });
-      emitAbuilderEvent(AbuilderEvents.workspaceSync, record);
       return name;
     });
-  }, [activeProjectId, nameSpace, persistProject, refreshProjects, resolveProjectName, t]);
+  }, [
+    activeProjectId,
+    activeProjectName,
+    eventNameSpace,
+    nameSpace,
+    persistProject,
+    resolveProjectName,
+    t,
+  ]);
 
   const handleDeleteProject = useCallback(
     async (id: string) => {
@@ -424,6 +546,7 @@ export function useWorkspaceProjects({
           if (activeProjectId === id) {
             setActiveProjectId(null);
             setActiveProjectName(null);
+            activeCreatedAtRef.current = null;
             syncedSnapshotRef.current = null;
           }
           previewWindowsRef.current.delete(id);
@@ -478,6 +601,58 @@ export function useWorkspaceProjects({
     [activeProjectId, dirty, handleSyncProject, nameSpace, refreshPreviewing, t]
   );
 
+  useEffect(() => {
+    if (!bootstrappedRef.current) {
+      bootstrappedRef.current = true;
+      if (hasWorkspacePayload(initialWorkspace)) {
+        applyProjectRecord(initialWorkspace, {
+          notifyApplied: false,
+          persistToIndexedDb: true,
+        });
+        initialWorkspaceAppliedKeyRef.current = workspaceApplyKey(initialWorkspace);
+        if (initialWorkspace.id) {
+          workspaceIdAppliedRef.current = initialWorkspace.id;
+        }
+      } else if (typeof workspaceId === "string" && workspaceId.trim()) {
+        workspaceIdAppliedRef.current = workspaceId.trim();
+        void handleOpenProject(workspaceId.trim());
+      } else {
+        applyEmptyWorkspace();
+      }
+      return;
+    }
+    if (!hasWorkspacePayload(initialWorkspace)) return;
+    const key = workspaceApplyKey(initialWorkspace);
+    if (initialWorkspaceAppliedKeyRef.current === key) return;
+    initialWorkspaceAppliedKeyRef.current = key;
+    if (initialWorkspace.id) {
+      workspaceIdAppliedRef.current = initialWorkspace.id;
+    }
+    applyProjectRecord(initialWorkspace, {
+      notifyApplied: false,
+      persistToIndexedDb: true,
+    });
+  }, [
+    applyEmptyWorkspace,
+    applyProjectRecord,
+    handleOpenProject,
+    initialWorkspace,
+    workspaceId,
+  ]);
+
+  useEffect(() => {
+    if (!bootstrappedRef.current) return;
+    const id = typeof workspaceId === "string" ? workspaceId.trim() : "";
+    if (!id) return;
+    if (workspaceIdAppliedRef.current === id) return;
+    if (activeProjectId === id) {
+      workspaceIdAppliedRef.current = id;
+      return;
+    }
+    workspaceIdAppliedRef.current = id;
+    void handleOpenProject(id);
+  }, [activeProjectId, handleOpenProject, workspaceId]);
+
   return {
     projects,
     activeProjectId,
@@ -490,6 +665,7 @@ export function useWorkspaceProjects({
     handleSyncProject,
     handleDeleteProject,
     handlePreviewProject,
+    getCurrentWorkspaceRecord,
     refreshProjects,
   };
 }

package/src/panel/icons.tsx

@@ -158,3 +158,120 @@ export function IconImage() {
     </svg>
   );
 }
+
+export function IconFolder() {
+  return (
+    <svg viewBox="0 0 24 24" className="h-3.5 w-3.5" fill="none" stroke="currentColor" strokeWidth="2">
+      <path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V7Z" />
+    </svg>
+  );
+}
+
+export function IconGrid() {
+  return (
+    <svg viewBox="0 0 24 24" className="h-3.5 w-3.5" fill="none" stroke="currentColor" strokeWidth="2">
+      <rect x="3" y="3" width="7" height="7" rx="1" />
+      <rect x="14" y="3" width="7" height="7" rx="1" />
+      <rect x="3" y="14" width="7" height="7" rx="1" />
+      <rect x="14" y="14" width="7" height="7" rx="1" />
+    </svg>
+  );
+}
+
+export function IconTree() {
+  return (
+    <svg viewBox="0 0 24 24" className="h-3.5 w-3.5" fill="none" stroke="currentColor" strokeWidth="2">
+      <path d="M12 4v8" />
+      <path d="M6 20v-4a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v4" />
+      <circle cx="12" cy="4" r="2" />
+      <circle cx="6" cy="20" r="2" />
+      <circle cx="18" cy="20" r="2" />
+    </svg>
+  );
+}
+
+export function IconSearch() {
+  return (
+    <svg viewBox="0 0 24 24" className="h-3.5 w-3.5" fill="none" stroke="currentColor" strokeWidth="2">
+      <circle cx="11" cy="11" r="7" />
+      <path d="m20 20-3.5-3.5" />
+    </svg>
+  );
+}
+
+export function IconStar({ filled }: { filled?: boolean }) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      className="h-3.5 w-3.5"
+      fill={filled ? "currentColor" : "none"}
+      stroke="currentColor"
+      strokeWidth="2"
+    >
+      <path d="m12 3 2.7 5.5 6 .9-4.4 4.3 1 6L12 16.8 6.7 19.7l1-6L3.3 9.4l6-.9L12 3Z" />
+    </svg>
+  );
+}
+
+export function IconEyeOff() {
+  return (
+    <svg viewBox="0 0 24 24" className="h-3.5 w-3.5" fill="none" stroke="currentColor" strokeWidth="2">
+      <path d="M3 3l18 18" />
+      <path d="M10.6 10.6a2 2 0 0 0 2.8 2.8" />
+      <path d="M9.9 5.1A10.6 10.6 0 0 1 12 5c5 0 9.3 3.1 11 7-.5 1.2-1.2 2.3-2.1 3.2" />
+      <path d="M6.1 6.1C4.2 7.3 2.7 9 1.9 11c1.7 3.9 6 7 10.1 7 1.4 0 2.7-.3 3.9-.7" />
+    </svg>
+  );
+}
+
+/** 仅看引用子树 */
+export function IconRefFilter({ active }: { active?: boolean }) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      className="h-3.5 w-3.5"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={active ? 2.2 : 2}
+    >
+      <path d="M4 5h16l-5.5 6.5V18l-5 2.5v-9L4 5Z" fill={active ? "currentColor" : "none"} fillOpacity={active ? 0.2 : 0} />
+      <circle cx="16.5" cy="16.5" r="2.2" />
+      <path d="M14.8 15.2 12 12.5" />
+    </svg>
+  );
+}
+
+export function IconBlueprint({ active }: { active?: boolean }) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      className="h-3.5 w-3.5"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={active ? 2.2 : 2}
+    >
+      <rect x="3" y="4" width="18" height="16" rx="2" />
+      <circle cx="8" cy="10" r="1.5" fill={active ? "currentColor" : "none"} />
+      <circle cx="16" cy="10" r="1.5" fill={active ? "currentColor" : "none"} />
+      <circle cx="12" cy="16" r="1.5" fill={active ? "currentColor" : "none"} />
+      <path d="M9.2 10.8 10.8 14.2M14.8 10.8 13.2 14.2" />
+    </svg>
+  );
+}
+
+export function IconSun() {
+  return (
+    <svg viewBox="0 0 24 24" className="h-3.5 w-3.5" fill="none" stroke="currentColor" strokeWidth="2">
+      <circle cx="12" cy="12" r="4" />
+      <path d="M12 2v2.5M12 19.5V22M4.93 4.93l1.77 1.77M17.3 17.3l1.77 1.77M2 12h2.5M19.5 12H22M4.93 19.07 6.7 17.3M17.3 6.7l1.77-1.77" />
+    </svg>
+  );
+}
+
+export function IconMoon() {
+  return (
+    <svg viewBox="0 0 24 24" className="h-3.5 w-3.5" fill="none" stroke="currentColor" strokeWidth="2">
+      <path d="M21 12.79A9 9 0 1 1 11.21 3c0 .66.08 1.3.22 1.92A7 7 0 0 0 19.08 12c.62.14 1.26.22 1.92.22Z" />
+    </svg>
+  );
+}

package/src/panel/library/abuilder-storage.ts

@@ -1,10 +1,22 @@
+import { normalizeAppNameSpace } from "@arronqzy/blueprint-dsl";
 import {
   clearAllExecutionRunRecords,
-  clearApiCollections,
+  clearApiCollections as clearApiCollectionsRaw,
   clearBlueprintLibrary as clearBlueprintLibraryRecords,
+  deleteApiCollection as deleteApiCollectionRaw,
   deleteBlueprintLibraryRecord as deleteBlueprintLibraryRecordRaw,
+  putApiCollection as putApiCollectionRaw,
+  putBlueprintLibraryRecord as putBlueprintLibraryRecordRaw,
+  putExecutionRunRecord as putExecutionRunRecordRaw,
+  upsertApiCollectionFromJson as upsertApiCollectionFromJsonRaw,
+  type BlueprintLibraryRecord,
+  type ExecutionRunRecord,
+  type UpsertApiCollectionInput,
+  type UpsertApiCollectionResult,
 } from "@arronqzy/react-blueprint";
+import type { ApiCollectionRecord } from "@arronqzy/blueprint-dsl";
 import { broadcastBlueprintLibraryChanged } from "./blueprint-library-sync";
+import { AbuilderEvents, emitAbuilderEvent } from "./event-subscription";
 import { clearWorkspaceProjects } from "./workspace-storage";
 
 export {
@@ -19,17 +31,36 @@ export {
   readExecutionLogSettings,
   writeExecutionLogSettings,
   listApiCollectionRecords,
-  deleteApiCollection,
-  clearApiCollections,
 } from "@arronqzy/react-blueprint";
 export type {
   BlueprintLibraryListItem,
   BlueprintLibraryRecord,
   ExecutionRunRecord,
   ExecutionLogSettings,
+  UpsertApiCollectionInput,
+  UpsertApiCollectionResult,
 } from "@arronqzy/react-blueprint";
 export type { ApiCollectionRecord } from "@arronqzy/blueprint-dsl";
 
+function resolvedNameSpace(nameSpace?: string | null): string | null {
+  return normalizeAppNameSpace(nameSpace) || null;
+}
+
+/** 写入 / 覆盖蓝图库记录；已挂载的编辑器会刷新蓝图库列表 */
+export async function putBlueprintLibraryRecord(
+  record: BlueprintLibraryRecord,
+  nameSpace?: string | null
+): Promise<BlueprintLibraryRecord> {
+  const saved = await putBlueprintLibraryRecordRaw(record, nameSpace);
+  broadcastBlueprintLibraryChanged(nameSpace);
+  emitAbuilderEvent(AbuilderEvents.blueprintLibraryChanged, {
+    nameSpace: resolvedNameSpace(nameSpace),
+    action: "put",
+    ids: [saved.id],
+  });
+  return saved;
+}
+
 /** 删除蓝图库中的一条蓝图；已挂载的编辑器会刷新蓝图库列表 */
 export async function deleteBlueprintLibraryRecord(
   id: string,
@@ -37,12 +68,79 @@ export async function deleteBlueprintLibraryRecord(
 ): Promise<void> {
   await deleteBlueprintLibraryRecordRaw(id, nameSpace);
   broadcastBlueprintLibraryChanged(nameSpace);
+  emitAbuilderEvent(AbuilderEvents.blueprintLibraryChanged, {
+    nameSpace: resolvedNameSpace(nameSpace),
+    action: "delete",
+    ids: [id],
+  });
 }
 
 /** 清空该 nameSpace 下的蓝图库，返回删除数量；已挂载的编辑器会刷新蓝图库列表 */
 export async function clearBlueprintLibrary(nameSpace?: string | null): Promise<number> {
   const count = await clearBlueprintLibraryRecords(nameSpace);
   broadcastBlueprintLibraryChanged(nameSpace);
+  emitAbuilderEvent(AbuilderEvents.blueprintLibraryChanged, {
+    nameSpace: resolvedNameSpace(nameSpace),
+    action: "clear",
+  });
+  return count;
+}
+
+/** 写入一条蓝图执行日志 */
+export async function putExecutionRunRecord(
+  record: ExecutionRunRecord,
+  nameSpace?: string | null
+): Promise<ExecutionRunRecord> {
+  return putExecutionRunRecordRaw(record, nameSpace);
+}
+
+/** 写入接口集合；persistLocal 时落 IndexedDB，并同步已挂载编辑器的内存列表 */
+export async function putApiCollection(
+  record: ApiCollectionRecord,
+  nameSpace?: string | null
+): Promise<ApiCollectionRecord> {
+  const saved = await putApiCollectionRaw(record, nameSpace);
+  emitAbuilderEvent(AbuilderEvents.apiCollectionChanged, {
+    nameSpace: resolvedNameSpace(nameSpace),
+    action: "put",
+    ids: [saved.id],
+  });
+  return saved;
+}
+
+/** 从 JSON 文本 upsert 接口集合；可传 nameSpace */
+export async function upsertApiCollectionFromJson(
+  input: UpsertApiCollectionInput
+): Promise<UpsertApiCollectionResult> {
+  const result = await upsertApiCollectionFromJsonRaw(input);
+  if (result.ok) {
+    emitAbuilderEvent(AbuilderEvents.apiCollectionChanged, {
+      nameSpace: resolvedNameSpace(input.nameSpace),
+      action: "put",
+      ids: [result.record.id],
+    });
+  }
+  return result;
+}
+
+export async function deleteApiCollection(
+  id: string,
+  nameSpace?: string | null
+): Promise<void> {
+  await deleteApiCollectionRaw(id, nameSpace);
+  emitAbuilderEvent(AbuilderEvents.apiCollectionChanged, {
+    nameSpace: resolvedNameSpace(nameSpace),
+    action: "delete",
+    ids: [id],
+  });
+}
+
+export async function clearApiCollections(nameSpace?: string | null): Promise<number> {
+  const count = await clearApiCollectionsRaw(nameSpace);
+  emitAbuilderEvent(AbuilderEvents.apiCollectionChanged, {
+    nameSpace: resolvedNameSpace(nameSpace),
+    action: "clear",
+  });
   return count;
 }