@ametie/vue-muza-use 1.0.0 → 1.2.0

package/README.md

@@ -41,6 +41,7 @@ A production-ready composable that eliminates boilerplate and solves the hard pr
 - 🔐 **JWT Token Management** — Automatic token refresh with request queueing on 401 responses
 - 🎛️ **Flexible Architecture** — Bring your own Axios instance with full configuration control
 - 🍪 **withCredentials** — Per-request cookie and cross-origin credential control
+- 🔭 **DevTools Panel** — Inspect live requests, payloads, and instance state via `@ametie/vue-muza-devtools`
 
 ---
 
@@ -63,11 +64,11 @@ A production-ready composable that eliminates boilerplate and solves the hard pr
 | **Response caching** | ✅ | ❌ | ✅ | ✅ |
 | **TypeScript** | ✅ | ✅ | ✅ | ✅ |
 | **SSR / Nuxt** | ❌ | ✅ | ✅ | ✅ |
-| **DevTools** | ❌ | ❌ | ✅ | ❌ |
+| **DevTools** | ✅ | ❌ | ✅ | ❌ |
 
 **Choose vue-muza-use if:** you build Vue 3 SPAs with Axios, need JWT token refresh out of the box, and want reactive request management without a heavyweight server-state solution.
 
-**Choose TanStack Query if:** you need SSR, DevTools, or advanced server-state normalization.
+**Choose TanStack Query if:** you need SSR or advanced server-state normalization.
 
 **Choose @vueuse/useFetch if:** you want a minimal fetch wrapper with no opinions.
 
@@ -97,9 +98,12 @@ A production-ready composable that eliminates boilerplate and solves the hard pr
 - [Data Table with Pagination](#data-table-with-pagination--sorting)
 - [Request Cancellation](#request-cancellation)
 - [Batch Requests](#batch-requests)
+  - [Reactive Requests (Auto-tracking)](#reactive-requests--auto-tracking)
+  - [Batch Polling](#batch-polling)
 
 **Advanced:**
 - [Advanced Configuration](#️-advanced-configuration)
+- [DevTools Panel](#-devtools-panel)
 - [Authentication & Token Management](#-authentication--token-management)
 - [Error Handling Reference](#-error-handling-reference)
 - [Utilities & Standalone Composables](#-utilities--standalone-composables)
@@ -798,13 +802,15 @@ const { data } = useApi('/messages', {
 Apply to all `useApi` instances at once:
 
 ```typescript
-createApiClient({
-  axios,
+const api = createApiClient({ baseURL: 'https://api.example.com' })
+
+app.use(createApi({
+  axios: api,
   globalOptions: {
     refetchOnFocus: true,
     refetchOnReconnect: true,
   },
-})
+}))
 ```
 
 Opt individual requests out with `refetchOnFocus: false`:
@@ -1403,6 +1409,77 @@ const { loading, progress, execute } = useApiBatch(urls, {
 </template>
 ```
 
+#### Reactive Requests — Auto-tracking
+
+**TL;DR: Pass a getter function as `requests` — the batch re-executes automatically when the getter's reactive dependencies change.**
+
+This mirrors `useApi`'s auto-tracking behavior. No explicit `watch` option needed.
+
+```typescript
+import { ref } from 'vue'
+import { useApiBatch } from '@ametie/vue-muza-use'
+
+interface User { id: number; name: string }
+
+const pages = ref([1, 2, 3])
+
+// Getter is auto-tracked — re-executes when pages.value changes
+const { successfulData, loading } = useApiBatch<User>(
+  () => pages.value.map(page => ({ url: '/users', params: { page } }))
+)
+
+pages.value = [4, 5, 6]  // → new batch fires automatically
+```
+
+Set `lazy: true` to disable auto-tracking and keep full manual control:
+
+```typescript
+const { execute } = useApiBatch(
+  () => ids.value.map(id => `/items/${id}`),
+  { lazy: true }  // reactive changes to ids do NOT trigger re-execution
+)
+
+// You control when it runs
+await execute()
+```
+
+#### Batch Polling
+
+**TL;DR: Re-execute the batch on a fixed interval — useful for dashboards and status monitoring.**
+
+Same semantics as `useApi`'s `poll` option.
+
+```typescript
+import { useApiBatch } from '@ametie/vue-muza-use'
+
+const { data, loading } = useApiBatch(
+  ['/stats/cpu', '/stats/memory', '/stats/disk'],
+  {
+    immediate: true,
+    poll: 5000  // re-execute every 5 seconds
+  }
+)
+```
+
+With `whenHidden` control:
+
+```typescript
+import { ref } from 'vue'
+import { useApiBatch } from '@ametie/vue-muza-use'
+
+const interval = ref(10000)
+
+const { data, abort } = useApiBatch(
+  ['/queue/jobs', '/queue/workers'],
+  {
+    immediate: true,
+    poll: { interval, whenHidden: false }  // pauses when tab is hidden
+  }
+)
+
+interval.value = 0  // stop polling
+```
+
 ---
 
 ## ⚙️ Advanced Configuration
@@ -1494,6 +1571,44 @@ createApp(App).use(createApi({
 
 ---
 
+## 🔭 DevTools Panel
+
+**TL;DR: Enable it in the plugin and get a live network inspector in your browser. No extra packages to install.**
+
+The devtools panel is included with `@ametie/vue-muza-use`. It loads on demand and has zero impact on production bundles when disabled.
+
+### Setup
+
+Pass `devtools` to `createApi`. Gate it on `NODE_ENV` to keep production builds clean:
+
+```typescript
+import { createApp } from 'vue'
+import { createApi, createApiClient } from '@ametie/vue-muza-use'
+import App from './App.vue'
+
+const api = createApiClient({ baseURL: 'https://api.example.com' })
+
+createApp(App).use(createApi({
+  axios: api,
+  devtools: {
+    enabled: process.env.NODE_ENV !== 'production'
+  }
+}))
+```
+
+The panel loads asynchronously — it has zero impact on startup time.
+
+### DevTools Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | — | Required. Set `true` to mount the panel |
+| `maxHistory` | `number` | `300` | Maximum number of requests kept in the Network tab history |
+| `maxPayloadSize` | `number` | `200_000` | Maximum bytes per payload/response before truncation in the viewer |
+| `tabs` | `DevtoolsTab[]` | `[]` | Additional custom tabs to register in the panel |
+
+---
+
 ## 🔐 Authentication & Token Management
 
 > **Note:** Authentication setup is optional. Only add this if your API requires JWT tokens.
@@ -2139,15 +2254,17 @@ type BatchInput = string | BatchRequestConfig
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `settled` | `boolean` | `true` | When `true`, all requests run even if some fail. When `false`, the first error stops the batch |
+| `settled` | `boolean` | `true` | When `true`, all requests run even if some fail. When `false`, the first error aborts remaining requests |
 | `concurrency` | `number` | unlimited | Maximum number of requests that run in parallel at once |
 | `immediate` | `boolean` | `false` | Execute the batch automatically when the composable is created |
+| `lazy` | `boolean` | `false` | Disable auto-tracking. When `false`, a getter passed as `requests` re-executes the batch automatically when its reactive deps change. Set `true` for full manual control via `execute()` |
+| `poll` | `number \| { interval: MaybeRefOrGetter<number>, whenHidden?: MaybeRefOrGetter<boolean> }` | `0` | Polling interval in ms. After each execution, schedules the next one after `interval` ms. `0` disables polling. `whenHidden: false` (default) pauses when the tab is hidden |
 | `skipErrorNotification` | `boolean` | `true` | Suppress global error handler for individual item failures |
-| `watch` | `WatchSource \| WatchSource[]` | `undefined` | Re-execute the batch when these sources change |
+| `watch` | `WatchSource \| WatchSource[]` | `undefined` | **Deprecated** — use a reactive getter with `lazy: false` instead. Will be removed in v2.0 |
 | `onItemSuccess` | `(item: BatchResultItem<T>, index: number) => void` | `undefined` | Called each time a single request in the batch succeeds |
 | `onItemError` | `(item: BatchResultItem<T>, index: number) => void` | `undefined` | Called each time a single request in the batch fails |
 | `onProgress` | `(progress: BatchProgress) => void` | `undefined` | Called after each request completes with updated progress |
-| `onFinish` | `(results: BatchResultItem<T>[]) => void` | `undefined` | Called once when all requests have completed |
+| `onFinish` | `(results: BatchResultItem<T>[]) => void` | `undefined` | Called once when all requests have completed (even on `settled: false` rejection) |
 
 **UseApiBatchReturn:**
 

package/dist/index.cjs

@@ -53,6 +53,48 @@ module.exports = __toCommonJS(index_exports);
 
 // src/plugin.ts
 var import_vue = require("vue");
+
+// src/devtools.ts
+var bridge = null;
+var requestCounter = 0;
+var pendingCalls = [];
+function nextRequestId() {
+  return `req_${++requestCounter}`;
+}
+async function initDevtools(options, app) {
+  if (!options.enabled) return;
+  try {
+    const { createBridge } = await import("@ametie/vue-muza-devtools");
+    bridge = createBridge(options, app);
+    for (const fn of pendingCalls) fn();
+    pendingCalls.length = 0;
+  } catch {
+    console.warn("[vue-muza-use] devtools enabled but @ametie/vue-muza-devtools is not installed");
+  }
+}
+var devtoolsBridge = {
+  onInstanceCreated(id, url, options) {
+    if (bridge) {
+      bridge.onInstanceCreated(id, url, options);
+    } else {
+      pendingCalls.push(() => bridge?.onInstanceCreated(id, url, options));
+    }
+  },
+  onInstanceDestroyed(id) {
+    bridge?.onInstanceDestroyed(id);
+  },
+  onStateUpdate(id, state) {
+    bridge?.onStateUpdate(id, state);
+  },
+  onRequestStart(record) {
+    bridge?.onRequestStart(record);
+  },
+  onRequestEnd(id, result) {
+    bridge?.onRequestEnd(id, result);
+  }
+};
+
+// src/plugin.ts
 var API_INJECTION_KEY = /* @__PURE__ */ Symbol("use-api-config");
 var globalConfig = null;
 function createApi(options) {
@@ -60,6 +102,9 @@ function createApi(options) {
   return {
     install(app) {
       app.provide(API_INJECTION_KEY, options);
+      if (options.devtools) {
+        void initDevtools(options.devtools, app);
+      }
     }
   };
 }
@@ -110,6 +155,18 @@ function debounceFn(fn, delay) {
   };
 }
 
+// src/utils/urlUtils.ts
+function parseUrlQueryParams(url) {
+  if (!url) return null;
+  const qIndex = url.indexOf("?");
+  if (qIndex === -1) return null;
+  const params = {};
+  for (const [k, v] of new URLSearchParams(url.slice(qIndex + 1))) {
+    params[k] = v;
+  }
+  return Object.keys(params).length > 0 ? params : null;
+}
+
 // src/useApi.ts
 var import_axios2 = require("axios");
 var import_vue5 = require("vue");
@@ -339,6 +396,30 @@ function useApi(url, options = {}) {
   const startLoading = initialLoading ?? immediate;
   const state = useApiState(initialData, { initialLoading: startLoading });
   const revalidating = (0, import_vue5.ref)(false);
+  const instanceId = (0, import_vue5.getCurrentInstance)() != null ? (0, import_vue5.useId)() : nextRequestId();
+  devtoolsBridge.onInstanceCreated(instanceId, (0, import_vue5.toValue)(url), {
+    authMode: options.authMode ?? "default",
+    cache: options.cache,
+    retry: options.retry ?? false,
+    poll: (() => {
+      const v = (0, import_vue5.toValue)(options.poll);
+      return typeof v === "number" ? v : 0;
+    })(),
+    immediate: options.immediate ?? false,
+    lazy: options.lazy ?? false
+  });
+  if ((0, import_vue5.getCurrentScope)()) {
+    (0, import_vue5.watch)(
+      () => ({
+        loading: state.loading.value,
+        error: state.error.value,
+        statusCode: state.statusCode.value,
+        data: state.data.value
+      }),
+      (s) => devtoolsBridge.onStateUpdate(instanceId, s),
+      { deep: true }
+    );
+  }
   const abortController2 = (0, import_vue5.ref)(null);
   const globalAbort = useGlobalAbort ? useAbortController() : null;
   let pollTimer = null;
@@ -374,6 +455,16 @@ function useApi(url, options = {}) {
     if (abortController2.value) abortController2.value.abort("Cancelled by new request");
     const controller = new AbortController();
     abortController2.value = controller;
+    if (config?.signal) {
+      const signal = config.signal;
+      if (signal.aborted) {
+        controller.abort(signal.reason);
+      } else {
+        signal.addEventListener("abort", () => {
+          controller.abort(signal.reason);
+        }, { once: true });
+      }
+    }
     let globalAbortHandler = null;
     let subscribedSignal = null;
     if (globalAbort) {
@@ -393,6 +484,9 @@ function useApi(url, options = {}) {
     state.setError(null);
     let wasCancelled = false;
     let retryCount = 0;
+    let devtoolsRequestId = null;
+    let devtoolsRequestStartedAt = 0;
+    let devtoolsRequestEndResult = null;
     try {
       if (!requestUrl) {
         throw new Error("Request URL is missing");
@@ -401,6 +495,21 @@ function useApi(url, options = {}) {
       const resolvedData = (0, import_vue5.toValue)(rawData);
       const rawParams = config?.params !== void 0 ? config.params : axiosConfig.params;
       const resolvedParams = (0, import_vue5.toValue)(rawParams);
+      const devtoolsQueryParams = resolvedParams ?? parseUrlQueryParams(requestUrl);
+      devtoolsRequestId = nextRequestId();
+      devtoolsRequestStartedAt = Date.now();
+      devtoolsBridge.onRequestStart({
+        id: devtoolsRequestId,
+        instanceId,
+        url: requestUrl,
+        method,
+        startedAt: devtoolsRequestStartedAt,
+        status: "pending",
+        statusCode: null,
+        requestHeaders: {},
+        payload: resolvedData ?? null,
+        queryParams: devtoolsQueryParams
+      });
       while (true) {
         try {
           const response = await axios2.request({
@@ -424,6 +533,12 @@ function useApi(url, options = {}) {
           }
           onSuccess?.(response);
           notifyFetched();
+          devtoolsRequestEndResult = {
+            status: "success",
+            statusCode: response.status,
+            response: response.data,
+            duration: Date.now() - devtoolsRequestStartedAt
+          };
           return selected;
         } catch (err) {
           if (controller.signal.aborted || (0, import_axios2.isAxiosError)(err) && err.code === "ERR_CANCELED") {
@@ -442,6 +557,12 @@ function useApi(url, options = {}) {
             }
             continue;
           }
+          devtoolsRequestEndResult = {
+            status: "error",
+            error: apiError,
+            statusCode: apiError.status ?? null,
+            duration: Date.now() - devtoolsRequestStartedAt
+          };
           if (!skipErrorNotification && globalErrorHandler) {
             globalErrorHandler(apiError, err);
           }
@@ -457,6 +578,12 @@ function useApi(url, options = {}) {
         return null;
       }
       const apiError = errorParser ? errorParser(err) : parseApiError(err);
+      devtoolsRequestEndResult = {
+        status: "error",
+        error: apiError,
+        statusCode: null,
+        duration: Date.now() - devtoolsRequestStartedAt
+      };
       if (!skipErrorNotification && globalErrorHandler) {
         globalErrorHandler(apiError, err);
       }
@@ -465,6 +592,12 @@ function useApi(url, options = {}) {
       onError?.(apiError);
       return null;
     } finally {
+      if (devtoolsRequestId !== null) {
+        devtoolsBridge.onRequestEnd(
+          devtoolsRequestId,
+          devtoolsRequestEndResult ?? { status: "aborted", duration: Date.now() - devtoolsRequestStartedAt }
+        );
+      }
       if (globalAbortHandler && subscribedSignal) subscribedSignal.removeEventListener("abort", globalAbortHandler);
       revalidating.value = false;
       if (!wasCancelled) {
@@ -541,7 +674,10 @@ function useApi(url, options = {}) {
     }
   };
   if ((0, import_vue5.getCurrentScope)()) {
-    (0, import_vue5.onScopeDispose)(() => abort("Scope disposed"));
+    (0, import_vue5.onScopeDispose)(() => {
+      abort("Scope disposed");
+      devtoolsBridge.onInstanceDestroyed(instanceId);
+    });
   }
   if (immediate) execute();
   if (typeof document !== "undefined") {
@@ -608,6 +744,8 @@ function useApiBatch(requests, options = {}) {
     concurrency,
     immediate = false,
     skipErrorNotification = true,
+    lazy = false,
+    poll = 0,
     watch: watchSource,
     onItemSuccess,
     onItemError,
@@ -632,13 +770,21 @@ function useApiBatch(requests, options = {}) {
   );
   const abortControllers = (0, import_vue6.ref)([]);
   let isAborted = false;
-  const updateProgress = (succeeded, failed) => {
-    const currentRequests = getRequests();
+  let pollTimer = null;
+  const getPollConfig = () => {
+    const val = (0, import_vue6.toValue)(poll);
+    if (typeof val === "number") return { interval: val, whenHidden: false };
+    return {
+      interval: (0, import_vue6.toValue)(val.interval),
+      whenHidden: (0, import_vue6.toValue)(val.whenHidden) ?? false
+    };
+  };
+  const updateProgress = (succeeded, failed, total) => {
     const completed = succeeded + failed;
     const newProgress = {
       completed,
-      total: currentRequests.length,
-      percentage: currentRequests.length > 0 ? Math.round(completed / currentRequests.length * 100) : 0,
+      total,
+      percentage: total > 0 ? Math.round(completed / total * 100) : 0,
       succeeded,
       failed
     };
@@ -655,7 +801,8 @@ function useApiBatch(requests, options = {}) {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       ...config.headers && { headers: config.headers },
       useGlobalAbort: false,
-      skipErrorNotification
+      skipErrorNotification,
+      lazy: true
     }));
     const { execute: execute2, error: reqError, statusCode, response } = api;
     try {
@@ -710,7 +857,7 @@ function useApiBatch(requests, options = {}) {
       scope.stop();
     }
   };
-  const executeWithConcurrency = async (requests2, limit) => {
+  const executeWithConcurrency = async (requests2, limit, total) => {
     const results = new Array(requests2.length);
     let succeededCount = 0;
     let failedCount = 0;
@@ -728,8 +875,9 @@ function useApiBatch(requests, options = {}) {
               errors.value.push(result.error);
             }
           }
-          updateProgress(succeededCount, failedCount);
+          updateProgress(succeededCount, failedCount, total);
           if (!settled && !result.success && result.error) {
+            abort("First request failed in non-settled mode");
             throw result.error;
           }
           return result;
@@ -758,7 +906,7 @@ function useApiBatch(requests, options = {}) {
               errors.value.push(result.error);
             }
           }
-          updateProgress(succeededCount, failedCount);
+          updateProgress(succeededCount, failedCount, total);
           if (!settled && !result.success && result.error) {
             abort("First request failed in non-settled mode");
             throw result.error;
@@ -775,6 +923,9 @@ function useApiBatch(requests, options = {}) {
     return results;
   };
   const execute = async () => {
+    if (loading.value) {
+      abort("Replaced by new execution");
+    }
     const currentRequests = getRequests();
     isAborted = false;
     loading.value = true;
@@ -782,20 +933,21 @@ function useApiBatch(requests, options = {}) {
     errors.value = [];
     data.value = [];
     abortControllers.value = [];
-    updateProgress(0, 0);
+    const total = currentRequests.length;
+    updateProgress(0, 0, total);
+    let finalResults = [];
     try {
-      const results = await executeWithConcurrency(currentRequests, concurrency);
-      data.value = results;
-      const allFailed = results.every((r) => !r.success);
-      if (allFailed && results.length > 0) {
+      finalResults = await executeWithConcurrency(currentRequests, concurrency, total);
+      data.value = finalResults;
+      const allFailed = finalResults.every((r) => !r.success);
+      if (allFailed && finalResults.length > 0) {
         error.value = {
-          message: `All ${results.length} requests failed`,
+          message: `All ${finalResults.length} requests failed`,
           status: 0,
           code: "BATCH_ALL_FAILED"
         };
       }
-      onFinish?.(results);
-      return results;
+      return finalResults;
     } catch (err) {
       if (!settled) {
         error.value = err;
@@ -804,10 +956,27 @@ function useApiBatch(requests, options = {}) {
     } finally {
       loading.value = false;
       abortControllers.value = [];
+      onFinish?.(finalResults);
+      if (!isAborted) {
+        const { interval, whenHidden } = getPollConfig();
+        if (interval > 0) {
+          const hidden = typeof document !== "undefined" && document.hidden;
+          if (whenHidden || !hidden) {
+            pollTimer = setTimeout(() => {
+              pollTimer = null;
+              execute();
+            }, interval);
+          }
+        }
+      }
     }
   };
   const abort = (message = "Batch aborted") => {
     isAborted = true;
+    if (pollTimer) {
+      clearTimeout(pollTimer);
+      pollTimer = null;
+    }
     for (const controller of abortControllers.value) {
       controller.abort(message);
     }
@@ -830,14 +999,26 @@ function useApiBatch(requests, options = {}) {
   if ((0, import_vue6.getCurrentScope)()) {
     (0, import_vue6.onScopeDispose)(() => abort("Scope disposed"));
   }
+  if (!lazy && typeof requests === "function") {
+    const trackingScope = (0, import_vue6.effectScope)();
+    trackingScope.run(() => {
+      const requestsComputed = (0, import_vue6.computed)(
+        () => requests().map(normalizeRequest)
+      );
+      (0, import_vue6.watch)(requestsComputed, () => {
+        execute();
+      }, { deep: true });
+    });
+    if ((0, import_vue6.getCurrentScope)()) (0, import_vue6.onScopeDispose)(() => trackingScope.stop());
+    execute();
+  } else if (immediate) {
+    execute();
+  }
   if (watchSource) {
     (0, import_vue6.watch)(watchSource, () => {
       execute();
     }, { deep: true });
   }
-  if (immediate) {
-    execute();
-  }
   return {
     data,
     successfulData,

package/dist/index.d.cts

@@ -139,7 +139,7 @@ interface UseApiOptions<T = unknown, D = unknown, TSelected = T> extends ApiRequ
      * Compatible with `lazy: true` — focus is a browser trigger, not a reactive dep.
      * Compatible with `poll` — both register separate listeners; `!loading` guard prevents duplicates.
      *
-     * Can be set globally via `createApiClient({ globalOptions: { refetchOnFocus: true } })`.
+     * Can be set globally via `createApi({ axios, globalOptions: { refetchOnFocus: true } })`.
      * Per-request value takes precedence over global (including `false` to opt-out).
      */
     refetchOnFocus?: boolean | {
@@ -151,7 +151,7 @@ interface UseApiOptions<T = unknown, D = unknown, TSelected = T> extends ApiRequ
      * No throttle is applied — reconnect is already a rare event.
      * No refetch fires if a request is already in-flight (`loading: true`).
      *
-     * Can be set globally via `createApiClient({ globalOptions: { refetchOnReconnect: true } })`.
+     * Can be set globally via `createApi({ axios, globalOptions: { refetchOnReconnect: true } })`.
      * Per-request value takes precedence over global (including `false` to opt-out).
      */
     refetchOnReconnect?: boolean;
@@ -244,6 +244,8 @@ interface ApiPluginOptions {
      * Useful if your backend has a different error structure.
      */
     errorParser?: (error: unknown) => ApiError;
+    /** Devtools panel configuration. Panel is disabled by default. */
+    devtools?: DevtoolsOptions;
     globalOptions?: {
         retry?: number | boolean;
         retryDelay?: number;
@@ -336,7 +338,34 @@ interface UseApiBatchOptions<T = unknown, D = unknown> extends Omit<ApiRequestCo
     immediate?: boolean;
     /** Skip individual error notifications */
     skipErrorNotification?: boolean;
-    /** Watch sources to trigger re-execution */
+    /**
+     * Disable auto-tracking. When true, reactive changes to the `requests` getter
+     * will NOT trigger re-execution. Use when you want full manual control via execute().
+     * Default: false — auto-tracks when `requests` is a function.
+     */
+    lazy?: boolean;
+    /**
+     * Polling interval in ms, or advanced config object.
+     * - Pass a number: `poll: 5000` — re-execute every 5 seconds.
+     * - Pass an object: `poll: { interval: 5000, whenHidden: false }` — skip polling when tab is hidden.
+     * Properties inside the object can also be Refs.
+     */
+    poll?: MaybeRefOrGetter<number | {
+        interval: MaybeRefOrGetter<number>;
+        whenHidden?: MaybeRefOrGetter<boolean>;
+    }>;
+    /**
+     * @deprecated Use a reactive getter for `requests` with `lazy: false` (default).
+     * Auto-tracking will re-execute when the getter's dependencies change.
+     * Will be removed in v2.0.
+     *
+     * @example
+     * // Before (deprecated):
+     * useApiBatch(() => ids.value.map(id => `/items/${id}`), { watch: ids })
+     *
+     * // After (preferred):
+     * useApiBatch(() => ids.value.map(id => `/items/${id}`))
+     */
     watch?: WatchSource | WatchSource[];
     /** Callback when a single request succeeds */
     onItemSuccess?: (item: BatchResultItem<T>, index: number) => void;
@@ -370,6 +399,92 @@ interface UseApiBatchReturn<T = unknown> {
     /** Reset state to initial */
     reset: () => void;
 }
+/** Lifecycle status of an HTTP request tracked by devtools. */
+type RequestStatus = "pending" | "success" | "error" | "aborted";
+/** Current reactive state of a useApi instance as seen by devtools. */
+interface DevtoolsInstanceState {
+    loading: boolean;
+    error: ApiError | null;
+    statusCode: number | null;
+    data: unknown;
+}
+/** Configuration options of a useApi instance as seen by devtools. */
+interface DevtoolsInstanceOptions {
+    authMode: AuthMode;
+    cache: CacheOptions | string | undefined;
+    retry: boolean | number;
+    poll: number;
+    immediate: boolean;
+    lazy: boolean;
+}
+/** An outgoing HTTP request record sent to devtools on request start. */
+interface DevtoolsRequestRecord {
+    id: string;
+    instanceId: string | null;
+    url: string;
+    method: string;
+    startedAt: number;
+    status: RequestStatus;
+    statusCode: null;
+    requestHeaders: Record<string, string>;
+    payload: unknown;
+    queryParams: unknown;
+}
+/** Result of a completed HTTP request, sent to devtools on request end. */
+type RequestEndResult = {
+    status: "success";
+    statusCode: number;
+    response: unknown;
+    duration: number;
+} | {
+    status: "error";
+    error: ApiError;
+    statusCode: number | null;
+    duration: number;
+} | {
+    status: "aborted";
+    duration: number;
+};
+/** Event callbacks implemented by the devtools panel, called by useApi instrumentation. */
+interface DevtoolsBridge {
+    /** Fired when a useApi instance is created. */
+    onInstanceCreated: (id: string, url: string | undefined, options: DevtoolsInstanceOptions) => void;
+    /** Fired when a useApi instance is destroyed (scope disposed). */
+    onInstanceDestroyed: (id: string) => void;
+    /** Fired when instance state (loading, error, statusCode, data) changes. */
+    onStateUpdate: (id: string, state: Partial<DevtoolsInstanceState>) => void;
+    /** Fired when an HTTP request starts. */
+    onRequestStart: (record: DevtoolsRequestRecord) => void;
+    /** Fired when an HTTP request completes (success, error, or abort). */
+    onRequestEnd: (id: string, result: RequestEndResult) => void;
+}
+/**
+ * Options for the `@ametie/vue-muza-devtools` panel.
+ *
+ * @example
+ * ```ts
+ * app.use(createApi({
+ *   axios: apiClient,
+ *   devtools: { enabled: process.env.NODE_ENV !== 'production' },
+ * }))
+ * ```
+ */
+interface DevtoolsOptions {
+    /** Enable the devtools panel. Default: false. */
+    enabled: boolean;
+    /** Maximum number of network requests kept in history. Default: 300. */
+    maxHistory?: number;
+    /** Maximum payload/response size in bytes before truncation. Default: 200_000. */
+    maxPayloadSize?: number;
+    /** Custom tabs appended after built-in tabs. */
+    tabs?: Array<{
+        id: string;
+        label: string;
+        component: unknown;
+        icon?: unknown;
+        order?: number;
+    }>;
+}
 
 declare function createApi(options: ApiPluginOptions): {
     install(app: App): void;
@@ -448,7 +563,7 @@ declare function useApiDelete<T = unknown, TSelected = T>(url: MaybeRefOrGetter<
  * - Abort support for all pending requests
  * - Detailed per-request results with URL mapping
  * - Progress tracking
- * - Watch option for auto re-execution
+ * - Auto-tracking for reactive getter requests (lazy: false default)
  *
  * @example
  * ```ts
@@ -466,11 +581,10 @@ declare function useApiDelete<T = unknown, TSelected = T>(url: MaybeRefOrGetter<
  * const ids = [1, 2, 3]
  * useApiBatch(ids.map(id => ({ url: `/users/${id}`, method: 'DELETE' })))
  *
- * // Reactive getter with object configs
+ * // Reactive getter — auto-tracks deps, re-executes when pages changes
  * const pages = ref([1, 2, 3])
  * const { successfulData } = useApiBatch(
- *   () => pages.value.map(page => ({ url: '/users', params: { page } })),
- *   { watch: pages, immediate: true }
+ *   () => pages.value.map(page => ({ url: '/users', params: { page } }))
  * )
  * ```
  */
@@ -756,4 +870,4 @@ declare function invalidateCache(id: string | string[]): void;
  */
 declare function clearAllCache(): void;
 
-export { type ApiError, type ApiPluginOptions, type ApiRequestConfig, type ApiState, type AuthEventPayload, AuthEventType, type AuthMode, type AuthMonitorFn, type AuthTokens$1 as AuthTokens, type BatchProgress, type BatchRequestConfig, type BatchResultItem, type CacheOptions, type SetDataInput, type UseApiBatchOptions, type UseApiBatchReturn, type UseApiOptions, type UseApiReturn, clearAllCache, createApi, createApiClient, invalidateCache, setAuthMonitor, setupInterceptors, tokenManager, useAbortController, useApi, useApiBatch, useApiConfig, useApiDelete, useApiGet, useApiPatch, useApiPost, useApiPut, useApiState };
+export { type ApiError, type ApiPluginOptions, type ApiRequestConfig, type ApiState, type AuthEventPayload, AuthEventType, type AuthMode, type AuthMonitorFn, type AuthTokens$1 as AuthTokens, type BatchProgress, type BatchRequestConfig, type BatchResultItem, type CacheOptions, type DevtoolsBridge, type DevtoolsInstanceOptions, type DevtoolsInstanceState, type DevtoolsOptions, type DevtoolsRequestRecord, type RequestEndResult, type RequestStatus, type SetDataInput, type UseApiBatchOptions, type UseApiBatchReturn, type UseApiOptions, type UseApiReturn, clearAllCache, createApi, createApiClient, invalidateCache, setAuthMonitor, setupInterceptors, tokenManager, useAbortController, useApi, useApiBatch, useApiConfig, useApiDelete, useApiGet, useApiPatch, useApiPost, useApiPut, useApiState };

package/dist/index.d.ts

@@ -139,7 +139,7 @@ interface UseApiOptions<T = unknown, D = unknown, TSelected = T> extends ApiRequ
      * Compatible with `lazy: true` — focus is a browser trigger, not a reactive dep.
      * Compatible with `poll` — both register separate listeners; `!loading` guard prevents duplicates.
      *
-     * Can be set globally via `createApiClient({ globalOptions: { refetchOnFocus: true } })`.
+     * Can be set globally via `createApi({ axios, globalOptions: { refetchOnFocus: true } })`.
      * Per-request value takes precedence over global (including `false` to opt-out).
      */
     refetchOnFocus?: boolean | {
@@ -151,7 +151,7 @@ interface UseApiOptions<T = unknown, D = unknown, TSelected = T> extends ApiRequ
      * No throttle is applied — reconnect is already a rare event.
      * No refetch fires if a request is already in-flight (`loading: true`).
      *
-     * Can be set globally via `createApiClient({ globalOptions: { refetchOnReconnect: true } })`.
+     * Can be set globally via `createApi({ axios, globalOptions: { refetchOnReconnect: true } })`.
      * Per-request value takes precedence over global (including `false` to opt-out).
      */
     refetchOnReconnect?: boolean;
@@ -244,6 +244,8 @@ interface ApiPluginOptions {
      * Useful if your backend has a different error structure.
      */
     errorParser?: (error: unknown) => ApiError;
+    /** Devtools panel configuration. Panel is disabled by default. */
+    devtools?: DevtoolsOptions;
     globalOptions?: {
         retry?: number | boolean;
         retryDelay?: number;
@@ -336,7 +338,34 @@ interface UseApiBatchOptions<T = unknown, D = unknown> extends Omit<ApiRequestCo
     immediate?: boolean;
     /** Skip individual error notifications */
     skipErrorNotification?: boolean;
-    /** Watch sources to trigger re-execution */
+    /**
+     * Disable auto-tracking. When true, reactive changes to the `requests` getter
+     * will NOT trigger re-execution. Use when you want full manual control via execute().
+     * Default: false — auto-tracks when `requests` is a function.
+     */
+    lazy?: boolean;
+    /**
+     * Polling interval in ms, or advanced config object.
+     * - Pass a number: `poll: 5000` — re-execute every 5 seconds.
+     * - Pass an object: `poll: { interval: 5000, whenHidden: false }` — skip polling when tab is hidden.
+     * Properties inside the object can also be Refs.
+     */
+    poll?: MaybeRefOrGetter<number | {
+        interval: MaybeRefOrGetter<number>;
+        whenHidden?: MaybeRefOrGetter<boolean>;
+    }>;
+    /**
+     * @deprecated Use a reactive getter for `requests` with `lazy: false` (default).
+     * Auto-tracking will re-execute when the getter's dependencies change.
+     * Will be removed in v2.0.
+     *
+     * @example
+     * // Before (deprecated):
+     * useApiBatch(() => ids.value.map(id => `/items/${id}`), { watch: ids })
+     *
+     * // After (preferred):
+     * useApiBatch(() => ids.value.map(id => `/items/${id}`))
+     */
     watch?: WatchSource | WatchSource[];
     /** Callback when a single request succeeds */
     onItemSuccess?: (item: BatchResultItem<T>, index: number) => void;
@@ -370,6 +399,92 @@ interface UseApiBatchReturn<T = unknown> {
     /** Reset state to initial */
     reset: () => void;
 }
+/** Lifecycle status of an HTTP request tracked by devtools. */
+type RequestStatus = "pending" | "success" | "error" | "aborted";
+/** Current reactive state of a useApi instance as seen by devtools. */
+interface DevtoolsInstanceState {
+    loading: boolean;
+    error: ApiError | null;
+    statusCode: number | null;
+    data: unknown;
+}
+/** Configuration options of a useApi instance as seen by devtools. */
+interface DevtoolsInstanceOptions {
+    authMode: AuthMode;
+    cache: CacheOptions | string | undefined;
+    retry: boolean | number;
+    poll: number;
+    immediate: boolean;
+    lazy: boolean;
+}
+/** An outgoing HTTP request record sent to devtools on request start. */
+interface DevtoolsRequestRecord {
+    id: string;
+    instanceId: string | null;
+    url: string;
+    method: string;
+    startedAt: number;
+    status: RequestStatus;
+    statusCode: null;
+    requestHeaders: Record<string, string>;
+    payload: unknown;
+    queryParams: unknown;
+}
+/** Result of a completed HTTP request, sent to devtools on request end. */
+type RequestEndResult = {
+    status: "success";
+    statusCode: number;
+    response: unknown;
+    duration: number;
+} | {
+    status: "error";
+    error: ApiError;
+    statusCode: number | null;
+    duration: number;
+} | {
+    status: "aborted";
+    duration: number;
+};
+/** Event callbacks implemented by the devtools panel, called by useApi instrumentation. */
+interface DevtoolsBridge {
+    /** Fired when a useApi instance is created. */
+    onInstanceCreated: (id: string, url: string | undefined, options: DevtoolsInstanceOptions) => void;
+    /** Fired when a useApi instance is destroyed (scope disposed). */
+    onInstanceDestroyed: (id: string) => void;
+    /** Fired when instance state (loading, error, statusCode, data) changes. */
+    onStateUpdate: (id: string, state: Partial<DevtoolsInstanceState>) => void;
+    /** Fired when an HTTP request starts. */
+    onRequestStart: (record: DevtoolsRequestRecord) => void;
+    /** Fired when an HTTP request completes (success, error, or abort). */
+    onRequestEnd: (id: string, result: RequestEndResult) => void;
+}
+/**
+ * Options for the `@ametie/vue-muza-devtools` panel.
+ *
+ * @example
+ * ```ts
+ * app.use(createApi({
+ *   axios: apiClient,
+ *   devtools: { enabled: process.env.NODE_ENV !== 'production' },
+ * }))
+ * ```
+ */
+interface DevtoolsOptions {
+    /** Enable the devtools panel. Default: false. */
+    enabled: boolean;
+    /** Maximum number of network requests kept in history. Default: 300. */
+    maxHistory?: number;
+    /** Maximum payload/response size in bytes before truncation. Default: 200_000. */
+    maxPayloadSize?: number;
+    /** Custom tabs appended after built-in tabs. */
+    tabs?: Array<{
+        id: string;
+        label: string;
+        component: unknown;
+        icon?: unknown;
+        order?: number;
+    }>;
+}
 
 declare function createApi(options: ApiPluginOptions): {
     install(app: App): void;
@@ -448,7 +563,7 @@ declare function useApiDelete<T = unknown, TSelected = T>(url: MaybeRefOrGetter<
  * - Abort support for all pending requests
  * - Detailed per-request results with URL mapping
  * - Progress tracking
- * - Watch option for auto re-execution
+ * - Auto-tracking for reactive getter requests (lazy: false default)
  *
  * @example
  * ```ts
@@ -466,11 +581,10 @@ declare function useApiDelete<T = unknown, TSelected = T>(url: MaybeRefOrGetter<
  * const ids = [1, 2, 3]
  * useApiBatch(ids.map(id => ({ url: `/users/${id}`, method: 'DELETE' })))
  *
- * // Reactive getter with object configs
+ * // Reactive getter — auto-tracks deps, re-executes when pages changes
  * const pages = ref([1, 2, 3])
  * const { successfulData } = useApiBatch(
- *   () => pages.value.map(page => ({ url: '/users', params: { page } })),
- *   { watch: pages, immediate: true }
+ *   () => pages.value.map(page => ({ url: '/users', params: { page } }))
  * )
  * ```
  */
@@ -756,4 +870,4 @@ declare function invalidateCache(id: string | string[]): void;
  */
 declare function clearAllCache(): void;
 
-export { type ApiError, type ApiPluginOptions, type ApiRequestConfig, type ApiState, type AuthEventPayload, AuthEventType, type AuthMode, type AuthMonitorFn, type AuthTokens$1 as AuthTokens, type BatchProgress, type BatchRequestConfig, type BatchResultItem, type CacheOptions, type SetDataInput, type UseApiBatchOptions, type UseApiBatchReturn, type UseApiOptions, type UseApiReturn, clearAllCache, createApi, createApiClient, invalidateCache, setAuthMonitor, setupInterceptors, tokenManager, useAbortController, useApi, useApiBatch, useApiConfig, useApiDelete, useApiGet, useApiPatch, useApiPost, useApiPut, useApiState };
+export { type ApiError, type ApiPluginOptions, type ApiRequestConfig, type ApiState, type AuthEventPayload, AuthEventType, type AuthMode, type AuthMonitorFn, type AuthTokens$1 as AuthTokens, type BatchProgress, type BatchRequestConfig, type BatchResultItem, type CacheOptions, type DevtoolsBridge, type DevtoolsInstanceOptions, type DevtoolsInstanceState, type DevtoolsOptions, type DevtoolsRequestRecord, type RequestEndResult, type RequestStatus, type SetDataInput, type UseApiBatchOptions, type UseApiBatchReturn, type UseApiOptions, type UseApiReturn, clearAllCache, createApi, createApiClient, invalidateCache, setAuthMonitor, setupInterceptors, tokenManager, useAbortController, useApi, useApiBatch, useApiConfig, useApiDelete, useApiGet, useApiPatch, useApiPost, useApiPut, useApiState };

package/dist/index.mjs

@@ -1,5 +1,47 @@
 // src/plugin.ts
 import { inject } from "vue";
+
+// src/devtools.ts
+var bridge = null;
+var requestCounter = 0;
+var pendingCalls = [];
+function nextRequestId() {
+  return `req_${++requestCounter}`;
+}
+async function initDevtools(options, app) {
+  if (!options.enabled) return;
+  try {
+    const { createBridge } = await import("@ametie/vue-muza-devtools");
+    bridge = createBridge(options, app);
+    for (const fn of pendingCalls) fn();
+    pendingCalls.length = 0;
+  } catch {
+    console.warn("[vue-muza-use] devtools enabled but @ametie/vue-muza-devtools is not installed");
+  }
+}
+var devtoolsBridge = {
+  onInstanceCreated(id, url, options) {
+    if (bridge) {
+      bridge.onInstanceCreated(id, url, options);
+    } else {
+      pendingCalls.push(() => bridge?.onInstanceCreated(id, url, options));
+    }
+  },
+  onInstanceDestroyed(id) {
+    bridge?.onInstanceDestroyed(id);
+  },
+  onStateUpdate(id, state) {
+    bridge?.onStateUpdate(id, state);
+  },
+  onRequestStart(record) {
+    bridge?.onRequestStart(record);
+  },
+  onRequestEnd(id, result) {
+    bridge?.onRequestEnd(id, result);
+  }
+};
+
+// src/plugin.ts
 var API_INJECTION_KEY = /* @__PURE__ */ Symbol("use-api-config");
 var globalConfig = null;
 function createApi(options) {
@@ -7,6 +49,9 @@ function createApi(options) {
   return {
     install(app) {
       app.provide(API_INJECTION_KEY, options);
+      if (options.devtools) {
+        void initDevtools(options.devtools, app);
+      }
     }
   };
 }
@@ -57,9 +102,21 @@ function debounceFn(fn, delay) {
   };
 }
 
+// src/utils/urlUtils.ts
+function parseUrlQueryParams(url) {
+  if (!url) return null;
+  const qIndex = url.indexOf("?");
+  if (qIndex === -1) return null;
+  const params = {};
+  for (const [k, v] of new URLSearchParams(url.slice(qIndex + 1))) {
+    params[k] = v;
+  }
+  return Object.keys(params).length > 0 ? params : null;
+}
+
 // src/useApi.ts
 import { isAxiosError as isAxiosError2 } from "axios";
-import { ref as ref3, computed, effectScope, getCurrentScope as getCurrentScope2, onScopeDispose as onScopeDispose2, toValue, watch } from "vue";
+import { ref as ref3, computed, effectScope, getCurrentInstance, getCurrentScope as getCurrentScope2, onScopeDispose as onScopeDispose2, toValue, watch, useId } from "vue";
 
 // src/utils/errorParser.ts
 import { isAxiosError } from "axios";
@@ -286,6 +343,30 @@ function useApi(url, options = {}) {
   const startLoading = initialLoading ?? immediate;
   const state = useApiState(initialData, { initialLoading: startLoading });
   const revalidating = ref3(false);
+  const instanceId = getCurrentInstance() != null ? useId() : nextRequestId();
+  devtoolsBridge.onInstanceCreated(instanceId, toValue(url), {
+    authMode: options.authMode ?? "default",
+    cache: options.cache,
+    retry: options.retry ?? false,
+    poll: (() => {
+      const v = toValue(options.poll);
+      return typeof v === "number" ? v : 0;
+    })(),
+    immediate: options.immediate ?? false,
+    lazy: options.lazy ?? false
+  });
+  if (getCurrentScope2()) {
+    watch(
+      () => ({
+        loading: state.loading.value,
+        error: state.error.value,
+        statusCode: state.statusCode.value,
+        data: state.data.value
+      }),
+      (s) => devtoolsBridge.onStateUpdate(instanceId, s),
+      { deep: true }
+    );
+  }
   const abortController2 = ref3(null);
   const globalAbort = useGlobalAbort ? useAbortController() : null;
   let pollTimer = null;
@@ -321,6 +402,16 @@ function useApi(url, options = {}) {
     if (abortController2.value) abortController2.value.abort("Cancelled by new request");
     const controller = new AbortController();
     abortController2.value = controller;
+    if (config?.signal) {
+      const signal = config.signal;
+      if (signal.aborted) {
+        controller.abort(signal.reason);
+      } else {
+        signal.addEventListener("abort", () => {
+          controller.abort(signal.reason);
+        }, { once: true });
+      }
+    }
     let globalAbortHandler = null;
     let subscribedSignal = null;
     if (globalAbort) {
@@ -340,6 +431,9 @@ function useApi(url, options = {}) {
     state.setError(null);
     let wasCancelled = false;
     let retryCount = 0;
+    let devtoolsRequestId = null;
+    let devtoolsRequestStartedAt = 0;
+    let devtoolsRequestEndResult = null;
     try {
       if (!requestUrl) {
         throw new Error("Request URL is missing");
@@ -348,6 +442,21 @@ function useApi(url, options = {}) {
       const resolvedData = toValue(rawData);
       const rawParams = config?.params !== void 0 ? config.params : axiosConfig.params;
       const resolvedParams = toValue(rawParams);
+      const devtoolsQueryParams = resolvedParams ?? parseUrlQueryParams(requestUrl);
+      devtoolsRequestId = nextRequestId();
+      devtoolsRequestStartedAt = Date.now();
+      devtoolsBridge.onRequestStart({
+        id: devtoolsRequestId,
+        instanceId,
+        url: requestUrl,
+        method,
+        startedAt: devtoolsRequestStartedAt,
+        status: "pending",
+        statusCode: null,
+        requestHeaders: {},
+        payload: resolvedData ?? null,
+        queryParams: devtoolsQueryParams
+      });
       while (true) {
         try {
           const response = await axios2.request({
@@ -371,6 +480,12 @@ function useApi(url, options = {}) {
           }
           onSuccess?.(response);
           notifyFetched();
+          devtoolsRequestEndResult = {
+            status: "success",
+            statusCode: response.status,
+            response: response.data,
+            duration: Date.now() - devtoolsRequestStartedAt
+          };
           return selected;
         } catch (err) {
           if (controller.signal.aborted || isAxiosError2(err) && err.code === "ERR_CANCELED") {
@@ -389,6 +504,12 @@ function useApi(url, options = {}) {
             }
             continue;
           }
+          devtoolsRequestEndResult = {
+            status: "error",
+            error: apiError,
+            statusCode: apiError.status ?? null,
+            duration: Date.now() - devtoolsRequestStartedAt
+          };
           if (!skipErrorNotification && globalErrorHandler) {
             globalErrorHandler(apiError, err);
           }
@@ -404,6 +525,12 @@ function useApi(url, options = {}) {
         return null;
       }
       const apiError = errorParser ? errorParser(err) : parseApiError(err);
+      devtoolsRequestEndResult = {
+        status: "error",
+        error: apiError,
+        statusCode: null,
+        duration: Date.now() - devtoolsRequestStartedAt
+      };
       if (!skipErrorNotification && globalErrorHandler) {
         globalErrorHandler(apiError, err);
       }
@@ -412,6 +539,12 @@ function useApi(url, options = {}) {
       onError?.(apiError);
       return null;
     } finally {
+      if (devtoolsRequestId !== null) {
+        devtoolsBridge.onRequestEnd(
+          devtoolsRequestId,
+          devtoolsRequestEndResult ?? { status: "aborted", duration: Date.now() - devtoolsRequestStartedAt }
+        );
+      }
       if (globalAbortHandler && subscribedSignal) subscribedSignal.removeEventListener("abort", globalAbortHandler);
       revalidating.value = false;
       if (!wasCancelled) {
@@ -488,7 +621,10 @@ function useApi(url, options = {}) {
     }
   };
   if (getCurrentScope2()) {
-    onScopeDispose2(() => abort("Scope disposed"));
+    onScopeDispose2(() => {
+      abort("Scope disposed");
+      devtoolsBridge.onInstanceDestroyed(instanceId);
+    });
   }
   if (immediate) execute();
   if (typeof document !== "undefined") {
@@ -555,6 +691,8 @@ function useApiBatch(requests, options = {}) {
     concurrency,
     immediate = false,
     skipErrorNotification = true,
+    lazy = false,
+    poll = 0,
     watch: watchSource,
     onItemSuccess,
     onItemError,
@@ -579,13 +717,21 @@ function useApiBatch(requests, options = {}) {
   );
   const abortControllers = ref4([]);
   let isAborted = false;
-  const updateProgress = (succeeded, failed) => {
-    const currentRequests = getRequests();
+  let pollTimer = null;
+  const getPollConfig = () => {
+    const val = toValue2(poll);
+    if (typeof val === "number") return { interval: val, whenHidden: false };
+    return {
+      interval: toValue2(val.interval),
+      whenHidden: toValue2(val.whenHidden) ?? false
+    };
+  };
+  const updateProgress = (succeeded, failed, total) => {
     const completed = succeeded + failed;
     const newProgress = {
       completed,
-      total: currentRequests.length,
-      percentage: currentRequests.length > 0 ? Math.round(completed / currentRequests.length * 100) : 0,
+      total,
+      percentage: total > 0 ? Math.round(completed / total * 100) : 0,
       succeeded,
       failed
     };
@@ -602,7 +748,8 @@ function useApiBatch(requests, options = {}) {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       ...config.headers && { headers: config.headers },
       useGlobalAbort: false,
-      skipErrorNotification
+      skipErrorNotification,
+      lazy: true
     }));
     const { execute: execute2, error: reqError, statusCode, response } = api;
     try {
@@ -657,7 +804,7 @@ function useApiBatch(requests, options = {}) {
       scope.stop();
     }
   };
-  const executeWithConcurrency = async (requests2, limit) => {
+  const executeWithConcurrency = async (requests2, limit, total) => {
     const results = new Array(requests2.length);
     let succeededCount = 0;
     let failedCount = 0;
@@ -675,8 +822,9 @@ function useApiBatch(requests, options = {}) {
               errors.value.push(result.error);
             }
           }
-          updateProgress(succeededCount, failedCount);
+          updateProgress(succeededCount, failedCount, total);
           if (!settled && !result.success && result.error) {
+            abort("First request failed in non-settled mode");
             throw result.error;
           }
           return result;
@@ -705,7 +853,7 @@ function useApiBatch(requests, options = {}) {
               errors.value.push(result.error);
             }
           }
-          updateProgress(succeededCount, failedCount);
+          updateProgress(succeededCount, failedCount, total);
           if (!settled && !result.success && result.error) {
             abort("First request failed in non-settled mode");
             throw result.error;
@@ -722,6 +870,9 @@ function useApiBatch(requests, options = {}) {
     return results;
   };
   const execute = async () => {
+    if (loading.value) {
+      abort("Replaced by new execution");
+    }
     const currentRequests = getRequests();
     isAborted = false;
     loading.value = true;
@@ -729,20 +880,21 @@ function useApiBatch(requests, options = {}) {
     errors.value = [];
     data.value = [];
     abortControllers.value = [];
-    updateProgress(0, 0);
+    const total = currentRequests.length;
+    updateProgress(0, 0, total);
+    let finalResults = [];
     try {
-      const results = await executeWithConcurrency(currentRequests, concurrency);
-      data.value = results;
-      const allFailed = results.every((r) => !r.success);
-      if (allFailed && results.length > 0) {
+      finalResults = await executeWithConcurrency(currentRequests, concurrency, total);
+      data.value = finalResults;
+      const allFailed = finalResults.every((r) => !r.success);
+      if (allFailed && finalResults.length > 0) {
         error.value = {
-          message: `All ${results.length} requests failed`,
+          message: `All ${finalResults.length} requests failed`,
           status: 0,
           code: "BATCH_ALL_FAILED"
         };
       }
-      onFinish?.(results);
-      return results;
+      return finalResults;
     } catch (err) {
       if (!settled) {
         error.value = err;
@@ -751,10 +903,27 @@ function useApiBatch(requests, options = {}) {
     } finally {
       loading.value = false;
       abortControllers.value = [];
+      onFinish?.(finalResults);
+      if (!isAborted) {
+        const { interval, whenHidden } = getPollConfig();
+        if (interval > 0) {
+          const hidden = typeof document !== "undefined" && document.hidden;
+          if (whenHidden || !hidden) {
+            pollTimer = setTimeout(() => {
+              pollTimer = null;
+              execute();
+            }, interval);
+          }
+        }
+      }
     }
   };
   const abort = (message = "Batch aborted") => {
     isAborted = true;
+    if (pollTimer) {
+      clearTimeout(pollTimer);
+      pollTimer = null;
+    }
     for (const controller of abortControllers.value) {
       controller.abort(message);
     }
@@ -777,14 +946,26 @@ function useApiBatch(requests, options = {}) {
   if (getCurrentScope3()) {
     onScopeDispose3(() => abort("Scope disposed"));
   }
+  if (!lazy && typeof requests === "function") {
+    const trackingScope = effectScope2();
+    trackingScope.run(() => {
+      const requestsComputed = computed2(
+        () => requests().map(normalizeRequest)
+      );
+      watch2(requestsComputed, () => {
+        execute();
+      }, { deep: true });
+    });
+    if (getCurrentScope3()) onScopeDispose3(() => trackingScope.stop());
+    execute();
+  } else if (immediate) {
+    execute();
+  }
   if (watchSource) {
     watch2(watchSource, () => {
       execute();
     }, { deep: true });
   }
-  if (immediate) {
-    execute();
-  }
   return {
     data,
     successfulData,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ametie/vue-muza-use",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Powerful Vue 3 API composable (Muza) with Axios, Auto-Refresh & TypeScript",
   "author": "MortyQ",
   "license": "MIT",