@ametie/vue-muza-use 0.10.0 → 0.11.0

package/README.md

@@ -5,7 +5,7 @@
 [![Vue 3](https://img.shields.io/badge/Vue-3.x-green.svg?style=flat-square)](https://vuejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Included-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
 
-**Type-safe, feature-rich Axios wrapper for Vue 3 Composition API. Built for real-world business logic.**
+**TypeScript-first, feature-rich Axios wrapper for Vue 3 Composition API. Built for real-world business logic.**
 
 A production-ready composable that eliminates boilerplate and solves the hard problems: race conditions, token refresh queues, automatic retries, and reactive request management. Write less code, ship faster, sleep better.
 
@@ -15,21 +15,23 @@ A production-ready composable that eliminates boilerplate and solves the hard pr
 > This library ships with a skill that teaches Claude the feature wrapper pattern, naming conventions, and all `UseApiOptions`.
 > Claude will generate correct, architecture-consistent API layer code out of the box — no extra prompting needed.
 >
-> 📄 **[View skill file →](https://github.com/MortyQ/vue-useApi/blob/main/.claude/skills/use-api/SKILL.md)**
+> 📄 **[View skill file →](https://github.com/MortyQ/vue-muza-use/blob/main/.claude/skills/use-api/SKILL.md)**
 
 ---
 
+> **Using v0.x?** The legacy documentation is available at [v0.10.0 README](https://github.com/MortyQ/vue-muza-use/blob/v0.10.0/packages/use-api/README.md).
+
 ## ✨ Features
 
 **Core Features** (Get started in minutes):
-- 🎯 **Fully Type-Safe** — End-to-end TypeScript support with strict typing for requests and responses
-- 🔄 **Smart Reactivity** — Watch refs and automatically refetch when dependencies change
+- 🎯 **TypeScript-first** — Full TypeScript support with strict typing for requests and responses
+- 🔄 **Smart Reactivity** — Auto-tracks reactive deps in `url`, `params`, and `data` — refetches automatically when they change
 - ⏱️ **Built-in Debouncing** — Perfect for search inputs and auto-save forms
 - 🛡️ **Race Condition Protection** — Global abort controller cancels stale requests automatically
 - 📊 **Auto-Polling** — Built-in interval fetching with smart tab visibility detection
 - 🚀 **Batch Requests** — Execute multiple requests in parallel with progress tracking
 - 🧹 **Zero Memory Leaks** — Automatic cleanup of pending requests on component unmount
-- 🔕 **ignoreUpdates** — Atomic updates without triggering intermediate requests
+- 🔕 **ignoreUpdates** — Update reactive deps silently without triggering a re-fetch
 - 🗄️ **Response Caching** — In-memory cache with configurable TTL and manual invalidation
 - ⚡ **Stale-While-Revalidate** — Serve cached data instantly while refreshing silently in the background
 - 🔬 **select** — Transform or filter response data declaratively; re-applied on every fetch automatically
@@ -42,6 +44,35 @@ A production-ready composable that eliminates boilerplate and solves the hard pr
 
 ---
 
+## 🆚 How it compares
+
+> Honest comparison. ✅ built-in · ⚠️ partial or plugin needed · ❌ not supported
+
+| Feature | vue-muza-use | @vueuse/useFetch | TanStack Query | swrv |
+|---------|:---:|:---:|:---:|:---:|
+| **Axios-first** | ✅ | ❌ fetch | ⚠️ adapter | ❌ fetch |
+| **JWT auto-refresh + queue** | ✅ | ❌ | ❌ | ❌ |
+| **Race condition protection** | ✅ | ❌ | ✅ | ❌ |
+| **ignoreUpdates** | ✅ | ❌ | ❌ | ❌ |
+| **Built-in debounce** | ✅ | ❌ | ❌ | ❌ |
+| **Batch requests** | ✅ | ❌ | ❌ | ❌ |
+| **Built-in retry** | ✅ | ❌ | ✅ | ❌ |
+| **Auto-polling** | ✅ | ❌ | ✅ | ✅ |
+| **SWR (stale-while-revalidate)** | ✅ | ❌ | ✅ | ✅ |
+| **select / transform** | ✅ | ❌ | ✅ | ❌ |
+| **Response caching** | ✅ | ❌ | ✅ | ✅ |
+| **TypeScript** | ✅ | ✅ | ✅ | ✅ |
+| **SSR / Nuxt** | ❌ | ✅ | ✅ | ✅ |
+| **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 @vueuse/useFetch if:** you want a minimal fetch wrapper with no opinions.
+
+---
+
 ## 📖 Table of Contents
 
 **Getting Started:**
@@ -51,7 +82,7 @@ A production-ready composable that eliminates boilerplate and solves the hard pr
 
 **Core Features:**
 - [Watch & Auto-Refetch](#watch--auto-refetch)
-  - [ignoreUpdates — Atomic Updates Without Refetch](#ignoreupdates--atomic-updates-without-refetch)
+  - [ignoreUpdates — Update Without Re-fetching](#ignoreupdates--update-without-re-fetching)
 - [Response Caching](#response-caching)
   - [Stale-While-Revalidate (SWR)](#stale-while-revalidate-swr)
 - [Polling (Background Updates)](#polling-background-updates)
@@ -167,7 +198,6 @@ const searchQuery = ref('')
 const { data, loading } = useApi<Product[]>(
   () => `/products/search?q=${searchQuery.value}`,
   {
-    watch: searchQuery,
     debounce: 500
   }
 )
@@ -270,7 +300,6 @@ const filters = ref({
 
 const { data } = useApi('/users', {
   params: filters,
-  watch: filters,
   immediate: true
 })
 ```
@@ -292,7 +321,6 @@ const id = ref<number | null>(null)
 
 const { data } = useApi<User>(
   () => id.value ? `/users/${id.value}` : undefined,
-  { watch: id }
 )
 
 // No request fires until id.value is set
@@ -355,162 +383,130 @@ const { execute, loading, error } = useApi<LoginResponse>(
 
 ### Watch & Auto-Refetch
 
-Watch refs and automatically refetch when they change. Perfect for filters, search, and dynamic content.
+**TL;DR: Pass reactive refs or getters to `url`, `params`, or `data` — the request re-fires automatically when they change.**
+
+Any reactive dependency accessed inside a getter is tracked automatically. No explicit `watch` option needed.
 
-#### Single Dependency
 ```typescript
 import { ref } from 'vue'
 import { useApi } from '@ametie/vue-muza-use'
 
-interface User {
-  id: number
-  name: string
-}
-
-const userId = ref(1)
+const search = ref('')
+const page = ref(1)
 
-const { data } = useApi<User>(
-  () => `/users/${userId.value}`,
-  { watch: userId, immediate: true }
-)
+// Reactive params getter — both search and page are tracked automatically
+const { data, loading } = useApi('/products', {
+  params: () => ({ q: search.value, page: page.value }),
+  immediate: true,
+})
 
-userId.value = 2  // → automatic refetch
+// Change any dep → request re-fires automatically
+search.value = 'shoes'
+page.value = 2
 ```
 
-#### Multiple Dependencies
+**Reactive URL:**
 ```typescript
-import { ref } from 'vue'
-import { useApi } from '@ametie/vue-muza-use'
+const userId = ref(1)
 
-const searchQuery = ref('')
-const category = ref('all')
+const { data } = useApi(() => `/users/${userId.value}`, {
+  immediate: true,
+})
 
-const { data } = useApi(
-  () => `/products?q=${searchQuery.value}&category=${category.value}`,
-  {
-    watch: [searchQuery, category],
-    debounce: 500
-  }
-)
+userId.value = 2  // → re-fetches /users/2 automatically
 ```
 
-#### Auto-Save Form
+**Opt-out with `lazy: true`:**
+
+For forms and manual mutations where you control when `execute()` is called:
+
 ```typescript
-import { ref } from 'vue'
-import { useApi } from '@ametie/vue-muza-use'
+const form = ref({ name: '', email: '' })
 
-const settings = ref({
-  theme: 'dark',
-  notifications: true
+const { execute, loading } = useApi('/users', {
+  method: 'POST',
+  data: form,
+  lazy: true,  // form changes do NOT trigger re-fetch
+  onSuccess: () => router.push('/users'),
 })
 
-useApi('/user/settings', {
-  method: 'PUT',
-  data: settings,
-  watch: settings,
-  debounce: 1000,
-  onSuccess: () => console.log('Saved!')
-})
+// Only fires when you call it
+async function submit() {
+  await execute()
+}
 ```
 
----
-
-### ignoreUpdates — Atomic Updates Without Refetch
-
-**TL;DR: Change multiple reactive values at once without triggering a request between each change.**
-
-When `watch` is active, every change to a watched ref triggers a new request. If you need to update three filter fields at once, you'd get three requests instead of one. `ignoreUpdates` wraps your changes so the watcher stays silent while you update all fields, then you call `execute()` once.
-
-#### ❌ Without ignoreUpdates — 2 requests fire
+**`immediate` works independently of auto-tracking:**
 
 ```typescript
-import { ref } from 'vue'
-import { useApi } from '@ametie/vue-muza-use'
-
-const page = ref(1)
-const search = ref('')
-
-const { execute } = useApi('/users', {
-  params: { page, search },
-  watch: [page, search]
+// Fetch on mount + re-fetch on dep change
+useApi('/products', {
+  params: () => ({ q: search.value }),
+  immediate: true,
 })
 
-// BAD: each assignment triggers a separate request
-page.value = 1    // → request 1: page=1, search=''
-search.value = 'john'  // → request 2: page=1, search=john
+// No fetch on mount, but re-fetch on dep change
+useApi('/products', {
+  params: () => ({ q: search.value }),
+  // immediate: false is the default
+})
 ```
 
-#### ✅ With ignoreUpdates — 1 request fires
+**Batching:** Vue batches synchronous reactive changes before triggering auto-tracking — two synchronous ref changes fire only one request.
 
 ```typescript
-import { ref } from 'vue'
-import { useApi } from '@ametie/vue-muza-use'
+// Only one request fires (Vue batches sync changes)
+status.value = 'active'
+page.value = 1
+```
 
-const page = ref(1)
-const search = ref('')
+---
 
-const { execute, ignoreUpdates } = useApi('/users', {
-  params: { page, search },
-  watch: [page, search]
-})
+### ignoreUpdates — Update Without Re-fetching
 
-// GOOD: all changes are batched, only one request fires
-ignoreUpdates(() => {
-  page.value = 1
-  search.value = 'john'
-})
-await execute()  // → single request: page=1, search=john
-```
+**TL;DR: Update a reactive dep without triggering auto-tracking.**
 
-#### Reset filters without auto-fetching
+When auto-tracking is active, any reactive dep change fires a new request. `ignoreUpdates` pauses the tracking scope for the duration of the callback — changes inside do not trigger a re-fetch.
 
-Use `ignoreUpdates` to reset all filters to their defaults, then manually trigger a single request.
+#### Example — clear search input without fetching
 
 ```typescript
 import { ref } from 'vue'
 import { useApi } from '@ametie/vue-muza-use'
 
-const page = ref(1)
 const search = ref('')
-const status = ref('all')
 
-const { execute, ignoreUpdates } = useApi('/users', {
-  params: { page, search, status },
-  watch: [page, search, status]
+const { data, ignoreUpdates } = useApi('/products', {
+  params: () => ({ q: search.value }),
+  debounce: 300,
 })
 
-function resetFilters() {
+function clearSearch() {
   ignoreUpdates(() => {
-    page.value = 1
     search.value = ''
-    status.value = 'all'
   })
-  execute()  // single request with reset values
+  // auto-tracking is paused — no request fires
 }
 ```
 
-#### Safe to call without a watch option
+The user types → auto-tracking fires → debounced request. Clicking "Clear" resets the input without triggering a fetch.
 
-If no `watch` option is configured, `ignoreUpdates` still runs the updater — it just has nothing to suppress.
+#### Safe to call when `lazy: true`
 
-```typescript
-import { ref } from 'vue'
-import { useApi } from '@ametie/vue-muza-use'
+If `lazy: true`, `ignoreUpdates` still runs the updater — it just has nothing to suppress.
 
-const counter = ref(0)
+```typescript
 const { ignoreUpdates } = useApi('/data')
 
-// Safe — no error thrown, updater still runs
 ignoreUpdates(() => {
-  counter.value = 42
+  someRef.value = 42  // runs normally, nothing to suppress
 })
 ```
 
 > [!NOTE]
 > `ignoreUpdates` is synchronous only. Changes made after an `await` inside the
 > updater function will NOT be suppressed — the flag resets after the synchronous
-> portion completes. If you need to update async values, update them outside
-> `ignoreUpdates` and call `execute()` manually.
+> portion completes.
 
 ---
 
@@ -623,9 +619,9 @@ invalidateCache(['products', 'categories'])
 clearAllCache()
 ```
 
-#### cache + watch
+#### cache + auto-tracking
 
-When `watch` is configured, each watch-triggered `execute()` still checks the cache first:
+When auto-tracking is active, each dep-change-triggered `execute()` still checks the cache first:
 
 ```vue
 <script setup lang="ts">
@@ -636,7 +632,7 @@ const categoryId = ref<number>(1)
 
 const { data } = useApi<Product[]>(() => `/categories/${categoryId.value}/products`, {
   cache: { id: `products-cat-${categoryId.value}`, staleTime: 30_000 },
-  watch: categoryId,
+  params: () => ({ category: categoryId.value }),
   immediate: true,
 })
 </script>
@@ -673,6 +669,7 @@ const { data } = useApi('/reports', {
 |-------|------|---------|-------------|
 | `id` | `string` | — | Unique cache key |
 | `staleTime` | `number` | `300_000` | TTL in milliseconds. Entry is deleted on next read after this time |
+| `swr` | `boolean` | `false` | Stale-while-revalidate: serve cached data instantly while revalidating in the background. See [SWR](#stale-while-revalidate-swr) |
 
 #### Out of Scope (by design)
 
@@ -709,8 +706,7 @@ import { useApi } from '@ametie/vue-muza-use'
 interface User { id: number; name: string }
 
 const { data, revalidating } = useApi<User[]>('/users', {
-  cache: 'users',
-  staleWhileRevalidate: true,
+  cache: { id: 'users', swr: true },
   immediate: true,
 })
 </script>
@@ -747,8 +743,7 @@ If the background revalidation request fails:
 
 ```typescript
 const { data, revalidating, error } = useApi('/dashboard', {
-  cache: 'dashboard',
-  staleWhileRevalidate: true,
+  cache: { id: 'dashboard', swr: true },
   immediate: true,
 })
 // data.value stays the cached value even after a failed revalidation
@@ -999,7 +994,10 @@ const toggleTodo = (id: number) => {
 }
 ```
 
-#### Transform in `onSuccess`
+#### Transform after fetch
+
+Use `mutate` from the **same** `useApi` call to post-process data after it arrives:
+
 ```typescript
 import { useApi } from '@ametie/vue-muza-use'
 
@@ -1010,7 +1008,7 @@ interface User {
   fullName?: string
 }
 
-const { data } = useApi<User[]>('/users', {
+const { data, mutate } = useApi<User[]>('/users', {
   immediate: true,
   onSuccess: ({ data: users }) => {
     mutate(users.map(u => ({
@@ -1019,10 +1017,13 @@ const { data } = useApi<User[]>('/users', {
     })))
   }
 })
-
-const { mutate } = useApi<User[]>('/users', { immediate: true })
 ```
 
+> [!TIP]
+> If the same transformation runs on every fetch (including polling or watch re-triggers),
+> use [`select`](#select--declarative-data-transformation) instead — it's applied automatically
+> and keeps your options object clean.
+
 ---
 
 ### select — Declarative Data Transformation
@@ -1124,7 +1125,6 @@ const params = computed(() => ({
 
 const { data, loading } = useApi<OrdersResponse>('/orders', {
   params,
-  watch: params,
   immediate: true
 })
 </script>
@@ -1421,6 +1421,8 @@ createApp(App).use(createApi({
 | `retryDelay` | `number` | `1000` | How many milliseconds to wait between retry attempts for all requests |
 | `retryStatusCodes` | `number[]` | `[408,429,500,502,503,504]` | Default HTTP status codes that trigger a retry across all requests |
 | `useGlobalAbort` | `boolean` | `true` | When `true`, all requests subscribe to the global abort controller |
+| `refetchOnFocus` | `boolean \| { throttle?: number }` | `undefined` | Apply `refetchOnFocus` to all `useApi` instances. Per-request value takes precedence (including `false` to opt-out) |
+| `refetchOnReconnect` | `boolean` | `undefined` | Apply `refetchOnReconnect` to all `useApi` instances. Per-request value takes precedence (including `false` to opt-out) |
 
 ---
 
@@ -1872,16 +1874,22 @@ Three type parameters — all optional with defaults:
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `immediate` | `boolean` | `false` | When `true`, executes the request automatically when the composable is created |
-| `watch` | `WatchSource \| WatchSource[]` | `undefined` | One or more refs to watch — request re-fires when any of them change |
-| `debounce` | `number` | `0` | Milliseconds to wait after the last watch change before firing the request |
+| `lazy` | `boolean` | `false` | Disable auto-tracking — reactive changes to `url`, `params`, and `data` will NOT trigger a re-fetch |
+| `debounce` | `number` | `0` | Milliseconds to debounce auto-tracked re-fetches |
 
 **Caching:**
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `cache` | `string \| CacheOptions` | `undefined` | Cache the response in memory. String shorthand uses default 5-min TTL. See [Response Caching](#response-caching) |
+| `cache` | `string \| CacheOptions` | `undefined` | Cache the response in memory. String shorthand uses default 5-min TTL. `CacheOptions.swr: true` enables stale-while-revalidate. See [Response Caching](#response-caching) |
 | `invalidateCache` | `string \| string[]` | `undefined` | Cache key(s) to delete on 2xx success. Never fires on error |
-| `staleWhileRevalidate` | `boolean` | `false` | When `true` and a cache hit occurs, return stale data immediately and revalidate in the background. `revalidating` is `true` during the background fetch. See [SWR](#stale-while-revalidate-swr) |
+
+**Refetch Triggers:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `refetchOnFocus` | `boolean \| { throttle?: number }` | `undefined` | Re-fetch when the browser tab regains focus. `true` uses a 60s throttle. Pass `{ throttle: 0 }` to always re-fetch. Configurable globally via `globalOptions` |
+| `refetchOnReconnect` | `boolean` | `undefined` | Re-fetch when the browser regains network connectivity (`online` event). No throttle. Configurable globally via `globalOptions` |
 
 **Polling:**
 
@@ -1948,12 +1956,12 @@ Three type parameters — all optional with defaults:
 | `error` | `Ref<ApiError \| null>` | Error from the last failed request; `null` on success |
 | `statusCode` | `Ref<number \| null>` | HTTP status code from the last completed request |
 | `response` | `Ref<AxiosResponse<unknown> \| null>` | Full Axios response object including headers (raw, before `select`) |
-| `revalidating` | `Ref<boolean>` | `true` while a background SWR revalidation is in flight. Always `false` when `staleWhileRevalidate` is not set |
+| `revalidating` | `Ref<boolean>` | `true` while a background SWR revalidation is in flight. Always `false` when `cache: { swr: true }` is not set |
 | `execute(config?)` | `(config?: ApiRequestConfig<D>) => Promise<TSelected \| null>` | Manually trigger the request, optionally overriding options |
 | `mutate(newData)` | `(newData: TSelected \| null \| ((prev: TSelected \| null) => TSelected \| null)) => void` | Update `data` locally without a network request; clears `error` |
 | `abort(msg?)` | `(message?: string) => void` | Cancel the current in-flight request |
 | `reset()` | `() => void` | Cancel the request and reset all state to initial values |
-| `ignoreUpdates(fn)` | `(updater: () => void) => void` | Run `updater` without triggering watch-based re-execution |
+| `ignoreUpdates(fn)` | `(updater: () => void) => void` | Run `updater` without triggering auto-tracked re-execution |
 
 #### `execute(config?)`
 
@@ -2196,7 +2204,7 @@ function logout() {
 
 ### 1. Search with Debounce and Reset
 
-Full component: debounced search that resets cleanly without triggering an intermediate request.
+Debounced search input. Typing triggers a request; "Clear" resets the input silently without fetching.
 
 ```vue
 <script setup lang="ts">
@@ -2210,30 +2218,25 @@ interface User {
 }
 
 const search = ref('')
-const page = ref(1)
 
-const { data, loading, execute, ignoreUpdates } = useApi<User[]>(
-  () => `/users?search=${search.value}&page=${page.value}`,
-  {
-    watch: [search, page],
-    debounce: 400,
-    immediate: true
-  }
-)
+const { data, loading, ignoreUpdates } = useApi<User[]>('/users', {
+  params: () => ({ q: search.value }),
+  debounce: 400,
+  immediate: true,
+})
 
-function resetSearch() {
+function clearSearch() {
   ignoreUpdates(() => {
     search.value = ''
-    page.value = 1
   })
-  execute()  // single request with reset values
+  // auto-tracking is paused — no request fires on clear
 }
 </script>
 
 <template>
   <div>
     <input v-model="search" placeholder="Search users..." />
-    <button @click="resetSearch">Clear</button>
+    <button @click="clearSearch">Clear</button>
 
     <div v-if="loading">Searching...</div>
     <ul v-else>
@@ -2249,7 +2252,7 @@ function resetSearch() {
 
 ### 2. Paginated List with Filter Reset
 
-When the user changes a filter, reset the page to 1 using `ignoreUpdates` so only one request fires.
+When the user changes a filter, also reset the page to 1. Vue batches synchronous ref changes, so auto-tracking fires once — no `ignoreUpdates` needed here.
 
 ```vue
 <script setup lang="ts">
@@ -2265,18 +2268,15 @@ interface Post {
 const page = ref(1)
 const status = ref('all')
 
-const { data, loading, execute, ignoreUpdates } = useApi<Post[]>(
-  () => `/posts?status=${status.value}&page=${page.value}`,
-  { watch: [status, page], immediate: true }
-)
+const { data, loading } = useApi<Post[]>('/posts', {
+  params: () => ({ status: status.value, page: page.value }),
+  immediate: true,
+})
 
 function changeStatus(newStatus: string) {
-  // Reset page to 1 when filter changes — one request, not two
-  ignoreUpdates(() => {
-    status.value = newStatus
-    page.value = 1
-  })
-  execute()
+  status.value = newStatus
+  page.value = 1
+  // Vue batches these sync changes — auto-tracking fires once, one request
 }
 </script>
 
@@ -2480,36 +2480,35 @@ Start polling every 2 seconds and stop automatically when the job reaches a term
 
 ```vue
 <script setup lang="ts">
-import { ref } from 'vue'
-import { useApi } from '@ametie/vue-muza-use'
+  import { ref } from 'vue'
+  import { useApi } from '@ametie/vue-muza-use'
 
-interface JobStatus {
-  id: string
-  status: 'pending' | 'processing' | 'complete' | 'failed'
-  progress: number
-}
+  interface JobStatus {
+    id: string
+    status: 'pending' | 'processing' | 'complete' | 'failed'
+    progress: number
+  }
 
-const jobId = ref<string | null>(null)
-const pollInterval = ref(0)
+  const jobId = ref<string | null>(null)
+  const pollInterval = ref(0)
+
+  const { data: job, error } = useApi<JobStatus>(
+          () => jobId.value ? `/jobs/${jobId.value}` : undefined,
+          {
+            poll: { interval: pollInterval },
+            onSuccess(response) {
+              const { status } = response.data
+              if (status === 'complete' || status === 'failed') {
+                pollInterval.value = 0  // Stop polling
+              }
+            }
+          }
+  )
 
-const { data: job, error } = useApi<JobStatus>(
-  () => jobId.value ? `/jobs/${jobId.value}` : undefined,
-  {
-    watch: jobId,
-    poll: { interval: pollInterval },
-    onSuccess(response) {
-      const { status } = response.data
-      if (status === 'complete' || status === 'failed') {
-        pollInterval.value = 0  // Stop polling
-      }
-    }
+  function startJob(id: string) {
+    jobId.value = id
+    pollInterval.value = 2000  // Start polling every 2s
   }
-)
-
-function startJob(id: string) {
-  jobId.value = id
-  pollInterval.value = 2000  // Start polling every 2s
-}
 </script>
 
 <template>
@@ -2530,7 +2529,7 @@ function startJob(id: string) {
 | Problem | Likely Cause | Fix |
 |---------|--------------|-----|
 | `"createApi config not found"` | `createApi()` not called | Call `app.use(createApi(...))` in `main.ts` before mounting |
-| Request fires twice on mount | `immediate: true` AND `watch` on a ref both trigger on setup | Use only `immediate` OR `watch` for the first load — not both |
+| Request fires twice on mount | `immediate: true` fires on mount; auto-tracking also fires when a dep changes immediately | Ensure deps don't change synchronously right after mount, or use `lazy: true` with manual `execute()` |
 | `retry` option does nothing | Default is `retry: false` | Set `retry: true` or `retry: 3` |
 | ALL errors trigger retry, not just some | `retryStatusCodes` not set — uses library default | Specify exact codes or use `retryStatusCodes: []` to retry on any error |
 | `ignoreUpdates` still triggers a request | Updater function contains an `await` | `ignoreUpdates` is sync-only — move async logic outside the updater |