@kyro-cms/admin 0.9.0 → 0.9.2

package/src/hooks/useAutoFormState.ts

@@ -1,8 +1,12 @@
 import { useEffect, useRef, useCallback } from "react";
 import { useAutoFormStore } from "../lib/autoform-store";
+import { getLastChangeSource, setChangeSource } from "../lib/change-source";
 import { slugifyText } from "../lib/slugify";
 import { resolveUrl, fetchWithAuth } from "../lib/api";
+import { normalizeUploadFields } from "../lib/normalize-upload-fields";
 import { useUIStore } from "../lib/stores";
+import { resolveFieldValue } from "../lib/resolve-field-value";
+import { useQueue } from "./useQueue";
 
 interface UseAutoFormStateProps {
   config: Record<string, unknown>;
@@ -24,7 +28,7 @@ export function useAutoFormState({
   onActionError,
 }: UseAutoFormStateProps) {
   const store = useAutoFormStore();
-  const { confirm, alert } = useUIStore();
+  const { confirm } = useUIStore();
   const {
     formData,
     setFormData,
@@ -43,15 +47,46 @@ export function useAutoFormState({
     getDraftCache,
     setDraftCache,
     clearDraftCache,
+    resetForm,
   } = store;
 
   const versionsEnabled = !!config.versions;
 
+  // Guard: clear stale formData from a previous page context.
+  // For collections, if the loaded document's id doesn't match the expected
+  // context key, the singleton zustand store is holding stale data.
+  // Globals have no id field and are singleton per slug, so skip this check.
+  // Must run in useEffect — calling resetForm() during render triggers
+  // "Cannot update a component while rendering" React error.
+  const currentContextKey = globalSlug || (initialData?.id as string | undefined) || collectionSlug;
+  const needsResetRef = useRef(false);
+  if (
+    !globalSlug &&
+    currentContextKey &&
+    formData &&
+    Object.keys(formData).length > 0 &&
+    formData.id !== currentContextKey
+  ) {
+    needsResetRef.current = true;
+  }
+
+  useEffect(() => {
+    if (needsResetRef.current) {
+      needsResetRef.current = false;
+      resetForm();
+    }
+  }, [resetForm]);
+
   const localSaveTimerRef = useRef<NodeJS.Timeout | null>(null);
   const serverSaveTimerRef = useRef<NodeJS.Timeout | null>(null);
+  const retryTimerRef = useRef<NodeJS.Timeout | null>(null);
+  const isOnlineRef = useRef(typeof navigator !== 'undefined' ? navigator.onLine : true);
   const lastAutoSaveTimeRef = useRef<number>(0);
   const autoSaveSkipRef = useRef<boolean>(false);
   const restorePromptedRef = useRef<string | null>(null);
+  const previousFormDataRef = useRef<string>("");
+  const astroSyncDataRef = useRef<string>("");
+  const { queueTask } = useQueue();
 
   const getDocumentKey = useCallback(
     (id?: string) => {
@@ -78,30 +113,6 @@ const persistBrowserDraft = useCallback(
     [lastSavedData.updatedAt, setDraftCache],
   );
 
-  const clearDraftArtifacts = useCallback(async () => {
-    const state = useAutoFormStore.getState();
-    const documentKey = getDocumentKey(state.formData.id);
-    if (documentKey) {
-      clearDraftCache(documentKey);
-    }
-
-    const draftUrl = globalSlug 
-      ? resolveUrl(`/api/globals/${globalSlug}/draft`)
-      : collectionSlug && state.formData.id 
-        ? resolveUrl(`/api/${collectionSlug}/${state.formData.id}/draft`)
-        : null;
-
-    if (draftUrl && versionsEnabled) {
-      try {
-        await fetchWithAuth(draftUrl, {
-          method: "DELETE",
-        });
-      } catch (err) {
-        console.error("Failed to clear draft snapshot:", err);
-      }
-    }
-  }, [clearDraftCache, collectionSlug, globalSlug, getDocumentKey]);
-
   const fetchVersions = useCallback(async () => {
     const url = globalSlug 
       ? resolveUrl(`/api/globals/${globalSlug}/versions`)
@@ -125,89 +136,124 @@ const persistBrowserDraft = useCallback(
   const performLocalAutoSave = useCallback(() => {
     const state = useAutoFormStore.getState();
     const latestFormData = state.formData;
-    const currentLastSaved = state.lastSavedData;
     if (autoSaveSkipRef.current || !collectionSlug || !latestFormData.id) return;
-    if (JSON.stringify(latestFormData) === JSON.stringify(currentLastSaved)) return;
+    if (!state.hasDirtyFields()) return;
     const documentKey = getDocumentKey(latestFormData.id);
     if (documentKey) {
       persistBrowserDraft(documentKey, latestFormData);
     }
   }, [collectionSlug, getDocumentKey, persistBrowserDraft]);
 
-  const performServerAutoSave = useCallback(async (options?: { keepalive?: boolean }) => {
+  const doAutosaveFetch = useCallback(async (options?: { keepalive?: boolean }) => {
     const state = useAutoFormStore.getState();
     const latestFormData = state.formData;
     const currentLastSaved = state.lastSavedData;
-    
+
     if (autoSaveSkipRef.current || (!versionsEnabled && !!globalSlug)) return;
     if (!globalSlug && (!collectionSlug || !latestFormData.id)) return;
-    if (JSON.stringify(latestFormData) === JSON.stringify(currentLastSaved)) return;
-    
+    if (!state.hasDirtyFields()) return;
+
     const documentKey = getDocumentKey(latestFormData.id);
     if (documentKey) {
       persistBrowserDraft(documentKey, latestFormData);
     }
 
+    if (!isOnlineRef.current) {
+      setAutoSaveStatus("offline");
+      return;
+    }
+
     setIsAutoSaving(true);
     setAutoSaveStatus("saving");
+    state.setBackgroundProcessing(true);
 
     try {
-      const draftUpdatedAt = new Date().toISOString();
-      const draftUrl = globalSlug 
-        ? resolveUrl(`/api/globals/${globalSlug}/draft`)
-        : resolveUrl(`/api/${collectionSlug}/${latestFormData.id}/draft`);
-
-      const response = await fetchWithAuth(
-        draftUrl,
-        {
-          method: "PUT",
-          headers: { "Content-Type": "application/json" },
-          keepalive: options?.keepalive,
-          body: JSON.stringify({
-            data: latestFormData,
-            baseUpdatedAt: currentLastSaved.updatedAt ?? null,
-            draftUpdatedAt,
-          }),
+      const url = globalSlug
+        ? resolveUrl(`/api/globals/${globalSlug}?autosave=true`)
+        : resolveUrl(`/api/${collectionSlug}/${latestFormData.id}?autosave=true`);
+
+      const response = await fetchWithAuth(url, {
+        method: "PATCH",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Draft": "true",
         },
-      );
+        keepalive: options?.keepalive,
+        body: JSON.stringify({
+          ...normalizeUploadFields(latestFormData),
+          baseUpdatedAt: currentLastSaved.updatedAt ?? null,
+        }),
+      });
 
       if (response.ok) {
-        const result = await response.json();
         lastAutoSaveTimeRef.current = Date.now();
+        state.setRetryCount(0);
+        state.setLastSavedAt(Date.now());
+        if (retryTimerRef.current) clearTimeout(retryTimerRef.current);
+
         if (documentKey) {
           setDraftCache(documentKey, {
             data: latestFormData,
             baseUpdatedAt: currentLastSaved.updatedAt ?? null,
-            draftUpdatedAt: result.data?.draftUpdatedAt || draftUpdatedAt,
-            lastSyncedAt: result.data?.updatedAt || new Date().toISOString(),
+            draftUpdatedAt: new Date().toISOString(),
+            lastSyncedAt: (await response.clone().json()).data?.updatedAt || new Date().toISOString(),
           });
         }
         setAutoSaveStatus("success");
-        setTimeout(() => setAutoSaveStatus("idle"), 2000);
+        setTimeout(() => {
+          if (useAutoFormStore.getState().autoSaveStatus === "success") {
+            setAutoSaveStatus("idle");
+          }
+        }, 2000);
+      } else if (response.status === 409) {
+        setAutoSaveStatus("conflict");
       } else {
-        const error = await response.json().catch(() => ({}));
-        console.error("Draft auto-save failed:", error);
-        setAutoSaveStatus("error");
-        setTimeout(() => setAutoSaveStatus("idle"), 5000);
+        throw new Error(`Draft auto-save failed with status ${response.status}`);
       }
     } catch (err) {
       console.error("Auto-save failed:", err);
-      setAutoSaveStatus("error");
-      setTimeout(() => setAutoSaveStatus("idle"), 5000);
+      const currentState = useAutoFormStore.getState();
+      const currentRetryCount = currentState.retryCount;
+      if (currentRetryCount < 5) {
+        currentState.setRetryCount(currentRetryCount + 1);
+        setAutoSaveStatus("retrying");
+        const delay = Math.min(1000 * Math.pow(2, currentRetryCount), 60000);
+        if (retryTimerRef.current) clearTimeout(retryTimerRef.current);
+        retryTimerRef.current = setTimeout(() => performAutosave(options), delay);
+      } else {
+        setAutoSaveStatus("offline");
+      }
     } finally {
       setIsAutoSaving(false);
+      useAutoFormStore.getState().setBackgroundProcessing(false);
     }
   }, [
     collectionSlug,
     getDocumentKey,
+    globalSlug,
     persistBrowserDraft,
     setAutoSaveStatus,
     setDraftCache,
     setIsAutoSaving,
+    versionsEnabled,
   ]);
 
-const saveDocument = useCallback(
-     async (dataOverride?: Record<string, unknown>) => {
+  const performAutosave = useCallback((options?: { keepalive?: boolean }) => {
+    queueTask(
+      () => doAutosaveFetch(options),
+      {
+        beforeProcess: () => {
+          return true;
+        },
+        afterProcess: () => {
+          // Background processing complete
+        },
+      },
+    );
+  }, [doAutosaveFetch, queueTask]);
+
+  const saveDocument = useCallback(
+     async (dataOverride?: Record<string, unknown>, isDraft = true) => {
       const state = useAutoFormStore.getState();
       const payload = dataOverride || state.formData;
       
@@ -219,9 +265,12 @@ const saveDocument = useCallback(
         url,
         {
           method: "PATCH",
-          headers: { "Content-Type": "application/json" },
+          headers: { 
+            "Content-Type": "application/json",
+            "X-Draft": String(isDraft),
+          },
           body: JSON.stringify({
-            ...payload,
+            ...normalizeUploadFields(payload) as Record<string, unknown>,
             baseUpdatedAt: state.lastSavedData.updatedAt ?? null,
           }),
         },
@@ -236,46 +285,6 @@ const saveDocument = useCallback(
     [collectionSlug, globalSlug, setAutoSaveStatus],
   );
 
-  const publishDocument = useCallback(async () => {
-    const state = useAutoFormStore.getState();
-    const url = globalSlug 
-      ? resolveUrl(`/api/globals/${globalSlug}/publish`)
-      : resolveUrl(`/api/${collectionSlug}/${state.formData.id}/publish`);
-
-    const response = await fetchWithAuth(
-      url,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          baseUpdatedAt: state.lastSavedData.updatedAt ?? null,
-        }),
-      },
-    );
-
-    if (response.status === 409) {
-      setAutoSaveStatus("conflict");
-    }
-
-    return response;
-  }, [collectionSlug, globalSlug, setAutoSaveStatus]);
-
-  const unpublishDocument = useCallback(async () => {
-    const state = useAutoFormStore.getState();
-    const url = globalSlug 
-      ? resolveUrl(`/api/globals/${globalSlug}/unpublish`)
-      : resolveUrl(`/api/${collectionSlug}/${state.formData.id}/unpublish`);
-
-    const response = await fetchWithAuth(
-      url,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-      },
-    );
-    return response;
-  }, [collectionSlug, globalSlug]);
-
   // Track sidebar toggle
   useEffect(() => {
     const handleToggle = () => {
@@ -285,24 +294,22 @@ const saveDocument = useCallback(
     return () => window.removeEventListener("toggle-sidebar", handleToggle);
   }, [sidebarCollapsed, setSidebarCollapsed]);
 
-  // Track unsaved changes
-  useEffect(() => {
-    const isDifferent = JSON.stringify(formData) !== JSON.stringify(lastSavedData);
-    setHasUnsavedChanges(isDifferent);
-  }, [formData, lastSavedData, setHasUnsavedChanges]);
+  // Track unsaved changes (handled by setField / dirtyFields now)
 
   // Initial data load
   const lastLoadedSlugRef = useRef<string | null>(null);
+  const lastInitialDataRef = useRef<string>("");
   const initialDataLoadedRef = useRef(false);
   useEffect(() => {
     const currentSlug = globalSlug || initialData?.id;
-    if (initialDataLoadedRef.current && lastLoadedSlugRef.current === currentSlug) return;
+    const serialized = JSON.stringify(initialData);
+    if (initialDataLoadedRef.current && lastLoadedSlugRef.current === currentSlug && lastInitialDataRef.current === serialized) return;
 
-    setFormData(initialData || {});
     loadDocument(initialData || {}, initialData || {});
     initialDataLoadedRef.current = true;
     lastLoadedSlugRef.current = currentSlug;
-  }, [formData.id, globalSlug, initialData, loadDocument, setFormData]);
+    lastInitialDataRef.current = serialized;
+  }, [collectionSlug, formData.id, globalSlug, initialData, loadDocument]);
 
   useEffect(() => {
     if (!collectionSlug || !initialData?.id) return;
@@ -316,33 +323,10 @@ const saveDocument = useCallback(
     const maybeRestoreDraft = async () => {
       if (!versionsEnabled) return;
       const browserDraft = getDraftCache(documentKey);
-      let serverDraft: Record<string, unknown> | null = null;
-
-try {
-         const response = await fetchWithAuth(
-           resolveUrl(`/api/${collectionSlug}/${initialData.id}/draft`),
-         );
-         if (response.ok) {
-           const result: { data?: Record<string, unknown> } = await response.json();
-           serverDraft = result.data || null;
-        }
-      } catch (err) {
-        console.error("Failed to fetch server draft:", err);
-      }
-
-const drafts = [browserDraft, serverDraft].filter(Boolean) as Array<{
-         data: Record<string, unknown>;
-         draftUpdatedAt: string;
-       }>;
-
-      const candidate = drafts.sort(
-        (a, b) =>
-          new Date(b.draftUpdatedAt).getTime() -
-          new Date(a.draftUpdatedAt).getTime(),
-      )[0];
 
-      if (!candidate) return;
-      if (JSON.stringify(candidate.data) === JSON.stringify(initialData)) {
+      if (!browserDraft) return;
+      if (JSON.stringify(browserDraft.data) === JSON.stringify(initialData)) {
+        clearDraftCache(documentKey);
         return;
       }
 
@@ -356,19 +340,13 @@ const drafts = [browserDraft, serverDraft].filter(Boolean) as Array<{
         cancelLabel: "Discard draft",
         onConfirm: async () => {
           if (cancelled) return;
-          setFormData(candidate.data);
+          const currentFormData = useAutoFormStore.getState().formData;
+          const mergedData = { ...currentFormData, ...browserDraft.data };
+          setFormData(mergedData);
           onActionSuccess?.("Recovered autosaved draft");
         },
         onCancel: async () => {
           clearDraftCache(documentKey);
-          try {
-            await fetchWithAuth(
-              resolveUrl(`/api/${collectionSlug}/${initialData.id}/draft`),
-              { method: "DELETE" },
-            );
-          } catch (err) {
-            console.error("Failed to discard server draft:", err);
-          }
         },
       });
     };
@@ -387,6 +365,7 @@ const drafts = [browserDraft, serverDraft].filter(Boolean) as Array<{
     initialData,
     onActionSuccess,
     setFormData,
+    versionsEnabled,
   ]);
 
   // Recursively find a field by name inside tabs/group/collapsible
@@ -409,45 +388,28 @@ const drafts = [browserDraft, serverDraft].filter(Boolean) as Array<{
 
   // Auto-generate metaTitle
   useEffect(() => {
-    const metaTitleField = findFieldDeep(config.fields, "metaTitle");
+    const fields = config.fields as Record<string, unknown>[];
+    const metaTitleField = findFieldDeep(fields, "metaTitle");
     if (!metaTitleField) return;
 
-    let titleValue = "";
-    for (const field of config.fields) {
-      if (field.type === "tabs" && "tabs" in field && field.name) {
-        const tabData = formData[field.name as string];
-        if (tabData && typeof tabData === "object" && tabData.title) {
-          titleValue = tabData.title;
-          break;
-        }
-      }
-    }
+    const titleValue = resolveFieldValue(fields, formData, "title");
+    const titleStr = titleValue ? String(titleValue) : "";
 
-    if (titleValue && (!formData.metaTitle || formData.metaTitle === formData._lastMetaTitle)) {
-      setField("metaTitle", titleValue);
+    if (titleStr && (!formData.metaTitle || formData.metaTitle === formData._lastMetaTitle)) {
+      setField("metaTitle", titleStr);
     }
   }, [formData, config.fields, setField]);
 
   // Auto-generate slug
   useEffect(() => {
-const slugField = config.fields.find(
-       (f: Record<string, unknown>) => f.name === "slug" && f.admin?.autoGenerate,
-     );
+    const fields = config.fields as Record<string, unknown>[];
+    const slugField = fields.find(
+      (f: Record<string, unknown>) => f.name === "slug" && f.admin?.autoGenerate,
+    );
     if (!slugField?.admin?.autoGenerate) return;
     const sourceField: string = slugField.admin.autoGenerate;
 
-    let sourceValue = formData[sourceField];
-    if (!sourceValue) {
-      for (const field of config.fields) {
-        if (field.type === "tabs" && "tabs" in field && field.name) {
-          const tabData = formData[field.name as string];
-          if (tabData && typeof tabData === "object" && tabData[sourceField]) {
-            sourceValue = tabData[sourceField];
-            break;
-          }
-        }
-      }
-    }
+    const sourceValue = resolveFieldValue(fields, formData, sourceField);
 
     if (isSlugLocked && sourceValue) {
       const newSlug = slugifyText(sourceValue);
@@ -457,29 +419,43 @@ const slugField = config.fields.find(
     }
   }, [formData, isSlugLocked, config.fields, setField]);
 
-  // Auto-save effect (Split-timer: 1.5s local, 10s server)
+  // Auto-save effect — only starts timers on keystroke-originated changes.
+  // Local save fires after 1.5s of inactivity, server save after 8s.
+  // Non-keystroke changes (block add/drag, select, checkbox, etc.) do NOT restart auto-save.
   useEffect(() => {
     if (sidebarCollapsed) return;
     if (!globalSlug && (!collectionSlug || !formData.id)) return;
 
-    if (localSaveTimerRef.current) clearTimeout(localSaveTimerRef.current);
-    if (serverSaveTimerRef.current) clearTimeout(serverSaveTimerRef.current);
+    const state = useAutoFormStore.getState();
+    if (!state.hasDirtyFields()) return;
+
+    // Only schedule/reschedule on keystroke-originated changes
+    if (getLastChangeSource() !== "keystroke") return;
+    setChangeSource("other");
+
+    // Compare serialized form data to avoid scheduling for unchanged metadata
+    const serialized = JSON.stringify(formData);
+    if (serialized === previousFormDataRef.current) return;
 
+    if (localSaveTimerRef.current) clearTimeout(localSaveTimerRef.current);
     localSaveTimerRef.current = setTimeout(performLocalAutoSave, 1500);
-    serverSaveTimerRef.current = setTimeout(performServerAutoSave, 10000);
 
-    return () => {
-      if (localSaveTimerRef.current) clearTimeout(localSaveTimerRef.current);
-      if (serverSaveTimerRef.current) clearTimeout(serverSaveTimerRef.current);
-    };
-  }, [formData, sidebarCollapsed, collectionSlug, globalSlug, performLocalAutoSave, performServerAutoSave]);
+    // Queue autosave via the queue (debounced at 8s)
+    if (serverSaveTimerRef.current) clearTimeout(serverSaveTimerRef.current);
+    serverSaveTimerRef.current = setTimeout(() => {
+      previousFormDataRef.current = serialized;
+      performAutosave();
+    }, 8000);
+  }, [formData, sidebarCollapsed, collectionSlug, globalSlug, performLocalAutoSave, performAutosave]);
 
   useEffect(() => {
     if (!globalSlug && (!collectionSlug || !formData.id)) return;
 
     const flushDraft = () => {
       if (autoSaveSkipRef.current) return;
-      void performServerAutoSave({ keepalive: true });
+      const state = useAutoFormStore.getState();
+      if (!state.hasDirtyFields()) return;
+      void performAutosave({ keepalive: true });
     };
 
     const handleVisibilityChange = () => {
@@ -488,22 +464,43 @@ const slugField = config.fields.find(
       }
     };
 
+    const handleOnline = () => {
+      isOnlineRef.current = true;
+      flushDraft();
+    };
+
+    const handleOffline = () => {
+      isOnlineRef.current = false;
+      const state = useAutoFormStore.getState();
+      if (state.hasDirtyFields()) {
+         state.setAutoSaveStatus("offline");
+      }
+    };
+
     window.addEventListener("blur", flushDraft);
     window.addEventListener("pagehide", flushDraft);
+    window.addEventListener("online", handleOnline);
+    window.addEventListener("offline", handleOffline);
     document.addEventListener("visibilitychange", handleVisibilityChange);
 
     return () => {
       window.removeEventListener("blur", flushDraft);
       window.removeEventListener("pagehide", flushDraft);
+      window.removeEventListener("online", handleOnline);
+      window.removeEventListener("offline", handleOffline);
       document.removeEventListener("visibilitychange", handleVisibilityChange);
     };
-  }, [collectionSlug, globalSlug, formData.id, performServerAutoSave]);
+  }, [collectionSlug, globalSlug, formData.id, performAutosave]);
 
-  // Astro sync
+  // Astro sync — avoid ping-pong loop with DetailView's setData
   useEffect(() => {
+    const serialized = JSON.stringify(formData);
+    if (serialized === astroSyncDataRef.current) return;
+    astroSyncDataRef.current = serialized;
+
     const hiddenInput = document.getElementById("form-data") as HTMLInputElement;
     if (hiddenInput) {
-      hiddenInput.value = JSON.stringify(formData);
+      hiddenInput.value = serialized;
     }
     onChange?.(formData);
   }, [formData, onChange]);
@@ -515,27 +512,21 @@ const slugField = config.fields.find(
 
   // Derived status values the UI can use for badges and button state
   const documentStatus: 'draft' | 'published' | 'archived' | undefined = (() => {
-    if (!versionsEnabled) return 'published';
     if (!formData.id && !globalSlug) return 'draft';
-    // If it has a pending draft version, effectively it's in a draft state for the editor
-    if (formData._has_draft) return 'draft';
-    return formData._status || 'published';
+    if (!versionsEnabled) return 'published';
+    return (formData.status as 'draft' | 'published' | undefined) || 'published';
   })();
 
   const hasUnpublishedChanges =
-    (!!formData.id || !!globalSlug) && (documentStatus !== 'published' || !!formData._has_draft);
+    (!!formData.id || !!globalSlug) && documentStatus === 'draft';
 
   return {
     ...store,
     fetchVersions,
-    performAutoSave: performServerAutoSave,
+    performAutoSave: performAutosave,
     saveDocument,
-    publishDocument,
-    unpublishDocument,
-    clearDraftArtifacts,
     autoSaveSkipRef,
     lastAutoSaveTimeRef,
-    alert,
     documentStatus,
     hasUnpublishedChanges,
     versionsEnabled,

package/src/hooks/useQueue.ts

@@ -0,0 +1,60 @@
+import { useCallback, useRef } from "react";
+
+type QueuedFunction = () => Promise<void>;
+
+type QueueTaskOptions = {
+  afterProcess?: () => void;
+  beforeProcess?: () => boolean;
+};
+
+type QueueTask = (fn: QueuedFunction, options?: QueueTaskOptions) => void;
+
+/**
+ * A hook that queues async tasks for sequential execution.
+ * Only the last task in the queue is ever processed; all prior pending tasks are discarded.
+ * This prevents race conditions where multiple autosave fetches could run in parallel.
+ *
+ * Inspired by Payload's useQueues hook.
+ *
+ * @returns {queueTask} A function used to queue a task for execution.
+ */
+export function useQueue(): { queueTask: QueueTask } {
+  const queue = useRef<QueuedFunction[]>([]);
+  const isProcessing = useRef(false);
+
+  const queueTask = useCallback<QueueTask>((fn, options) => {
+    queue.current.push(fn);
+
+    async function processQueue() {
+      if (isProcessing.current) return;
+
+      if (typeof options?.beforeProcess === "function") {
+        const shouldContinue = options.beforeProcess();
+        if (shouldContinue === false) return;
+      }
+
+      while (queue.current.length > 0) {
+        const latestTask = queue.current.pop();
+        queue.current = [];
+
+        isProcessing.current = true;
+
+        try {
+          await latestTask();
+        } catch (err) {
+          console.error("Error in queued function:", err);
+        } finally {
+          isProcessing.current = false;
+
+          if (typeof options?.afterProcess === "function") {
+            options.afterProcess();
+          }
+        }
+      }
+    }
+
+    processQueue();
+  }, []);
+
+  return { queueTask };
+}