@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/keepalive-transition-memory-leak.md

@@ -0,0 +1,144 @@
+---
+title: KeepAlive with Transition Memory Leak
+impact: MEDIUM
+impactDescription: Combining KeepAlive with Transition can cause memory leaks in certain Vue versions
+type: gotcha
+tags: [vue3, keepalive, transition, memory-leak, animation]
+---
+
+# KeepAlive with Transition Memory Leak
+
+**Impact: MEDIUM** - There is a known memory leak when using `<Transition>` and `<KeepAlive>` together. Component instances may not be properly freed from memory when combining these features.
+
+## Task Checklist
+
+- [ ] Test memory behavior when using KeepAlive + Transition together
+- [ ] Consider if transition animation is necessary with cached components
+- [ ] Use browser DevTools Memory tab to verify no leak
+- [ ] Keep Vue updated to get latest bug fixes
+
+## The Problem
+
+```vue
+<template>
+  <!-- Known memory leak combination in some Vue versions -->
+  <Transition name="fade">
+    <KeepAlive>
+      <component :is="currentView" />
+    </KeepAlive>
+  </Transition>
+</template>
+```
+
+When switching between components repeatedly:
+- Component instances accumulate in memory
+- References prevent garbage collection
+- Memory usage grows with each switch
+
+## Diagnosis
+
+Use Chrome DevTools to detect the leak:
+
+1. Open DevTools > Memory tab
+2. Take heap snapshot
+3. Switch between components 10+ times
+4. Take another heap snapshot
+5. Compare: look for growing VueComponent count
+
+## Workarounds
+
+### Option 1: Remove Transition if Not Essential
+
+```vue
+<template>
+  <!-- No memory leak without Transition -->
+  <KeepAlive :max="5">
+    <component :is="currentView" />
+  </KeepAlive>
+</template>
+```
+
+### Option 2: Use CSS Animations Instead
+
+```vue
+<template>
+  <KeepAlive :max="5">
+    <component
+      :is="currentView"
+      :class="{ 'fade-enter': isTransitioning }"
+    />
+  </KeepAlive>
+</template>
+
+<style>
+.fade-enter {
+  animation: fadeIn 0.3s ease-in;
+}
+
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+</style>
+```
+
+### Option 3: Use Strict Cache Limits
+
+If you must use both, minimize impact with strict limits:
+
+```vue
+<template>
+  <Transition name="fade" mode="out-in">
+    <KeepAlive :max="3">
+      <component :is="currentView" />
+    </KeepAlive>
+  </Transition>
+</template>
+```
+
+### Option 4: Key-Based Cache Invalidation
+
+Force fresh instances when needed:
+
+```vue
+<script setup>
+import { ref, computed } from 'vue'
+
+const currentView = ref('Dashboard')
+const cacheKey = ref(0)
+
+function switchViewFresh(view) {
+  currentView.value = view
+  cacheKey.value++ // Force new instance
+}
+</script>
+
+<template>
+  <Transition name="fade" mode="out-in">
+    <KeepAlive :max="3">
+      <component :is="currentView" :key="cacheKey" />
+    </KeepAlive>
+  </Transition>
+</template>
+```
+
+## Keep Vue Updated
+
+This is a known issue tracked in Vue's GitHub repository. Memory leak fixes are periodically released, so ensure you're on the latest Vue version:
+
+```bash
+npm update vue
+```
+
+## Key Points
+
+1. **Known issue** - Memory leaks with KeepAlive + Transition are documented
+2. **Test in DevTools** - Use Memory tab to verify your specific usage
+3. **Consider alternatives** - CSS animations may work without the leak
+4. **Set strict `max`** - Limit cache size to cap memory impact
+5. **Keep Vue updated** - Bug fixes are released periodically
+
+## Reference
+- [GitHub Issue #9842: Memory leak with transition and keep-alive](https://github.com/vuejs/vue/issues/9842)
+- [GitHub Issue #9840: Memory leak with transition and keep-alive](https://github.com/vuejs/vue/issues/9840)
+- [Vue.js KeepAlive Documentation](https://vuejs.org/guide/built-ins/keep-alive.html)

package/skills/vue-debug-guides/reference/keyup-modifier-timing.md

@@ -0,0 +1,137 @@
+---
+title: System Modifier Keys Must Be Held During keyup Events
+impact: MEDIUM
+impactDescription: Modifier keys (ctrl, alt, shift, meta) behave differently with keyup - they must be held when the key is released
+type: gotcha
+tags: [vue3, events, keyboard, modifiers, keyup, shortcuts]
+---
+
+# System Modifier Keys Must Be Held During keyup Events
+
+**Impact: MEDIUM** - When using system modifier keys (`.ctrl`, `.alt`, `.shift`, `.meta`) with `keyup` events, the modifier must still be pressed when the other key is released. Releasing the modifier key first will not trigger the event, causing keyboard shortcuts to appear broken.
+
+## Task Checklist
+
+- [ ] Understand that `@keyup.ctrl` requires Ctrl to be held while releasing another key
+- [ ] Consider using `keydown` instead of `keyup` for modifier key combinations
+- [ ] Use `.exact` when you need precise modifier key control
+- [ ] Test keyboard shortcuts with proper key release order
+
+**Incorrect:**
+```html
+<!-- WRONG: Expecting this to fire when Ctrl is released -->
+<template>
+  <input @keyup.ctrl="onCtrlRelease" />
+  <!-- This does NOT fire when you just release Ctrl! -->
+  <!-- It fires when you release ANY key while holding Ctrl -->
+</template>
+```
+
+```html
+<!-- WRONG: Misunderstanding keyup.ctrl behavior -->
+<template>
+  <div @keyup.ctrl="handleShortcut">
+    <!-- User presses Ctrl+S, releases Ctrl first, then S -->
+    <!-- Event does NOT fire because Ctrl wasn't held during S release -->
+  </div>
+</template>
+```
+
+**Correct:**
+```html
+<!-- CORRECT: User must hold Ctrl while releasing another key -->
+<template>
+  <input @keyup.ctrl.s="saveDocument" />
+  <!-- User presses Ctrl+S, then releases S while holding Ctrl -->
+  <!-- Event fires correctly -->
+</template>
+
+<script setup>
+function saveDocument(event) {
+  event.preventDefault()
+  // Save logic here
+}
+</script>
+```
+
+```html
+<!-- CORRECT: Use keydown for more intuitive modifier behavior -->
+<template>
+  <div @keydown.ctrl.s="saveDocument">
+    <!-- keydown fires immediately when both keys are pressed -->
+    <!-- More intuitive for keyboard shortcuts -->
+  </div>
+</template>
+```
+
+```html
+<!-- CORRECT: Use .exact for precise modifier control -->
+<template>
+  <!-- Only fires when ONLY Ctrl is pressed (no Shift, Alt, etc.) -->
+  <button @click.ctrl.exact="onCtrlClick">Ctrl+Click Only</button>
+
+  <!-- Fires with no system modifiers at all -->
+  <button @click.exact="onPlainClick">Plain Click Only</button>
+</template>
+```
+
+## How System Modifiers Work with keyup
+
+```javascript
+// Timeline of Ctrl+S keydown:
+// 1. User presses Ctrl (keydown fires)
+// 2. User presses S while holding Ctrl (keydown fires)
+
+// Timeline of Ctrl+S keyup:
+// 3. User releases S while holding Ctrl (keyup.ctrl.s fires!)
+// 4. User releases Ctrl (keyup fires, but not keyup.ctrl.s)
+
+// Common mistake:
+// 3. User releases Ctrl first (nothing fires for our handler)
+// 4. User releases S (keyup.s fires, but not keyup.ctrl.s)
+```
+
+## System Modifier Keys
+
+```html
+<!-- Available system modifiers -->
+<input @keyup.ctrl="..." />   <!-- Ctrl key -->
+<input @keyup.alt="..." />    <!-- Alt key (Option on Mac) -->
+<input @keyup.shift="..." />  <!-- Shift key -->
+<input @keyup.meta="..." />   <!-- Cmd on Mac, Windows key on PC -->
+```
+
+## The .exact Modifier
+
+```html
+<!-- Different .exact behaviors -->
+
+<!-- Fires even if Shift/Alt are also pressed -->
+<button @click.ctrl="onClick">Ctrl + any other modifiers</button>
+
+<!-- Fires ONLY when Ctrl alone is pressed -->
+<button @click.ctrl.exact="onClick">Ctrl only, no other modifiers</button>
+
+<!-- Fires ONLY when no system modifiers are pressed -->
+<button @click.exact="onClick">No modifiers allowed</button>
+```
+
+## Best Practice: Prefer keydown for Shortcuts
+
+```html
+<template>
+  <div
+    tabindex="0"
+    @keydown.ctrl.s.prevent="save"
+    @keydown.ctrl.z.prevent="undo"
+    @keydown.ctrl.shift.z.prevent="redo"
+  >
+    <!-- keydown is more reliable for keyboard shortcuts -->
+    <!-- Add .prevent to stop browser default (e.g., save dialog) -->
+  </div>
+</template>
+```
+
+## Reference
+- [Vue.js Event Handling - Key Modifiers](https://vuejs.org/guide/essentials/event-handling.html#key-modifiers)
+- [Vue.js Event Handling - System Modifier Keys](https://vuejs.org/guide/essentials/event-handling.html#system-modifier-keys)

package/skills/vue-debug-guides/reference/lifecycle-dom-access-timing.md

@@ -0,0 +1,216 @@
+---
+title: Access DOM Only After Mounted Hook
+impact: HIGH
+impactDescription: Accessing DOM elements before mounted causes undefined errors and silent failures
+type: capability
+tags: [vue3, vue2, lifecycle, dom, mounted, created, beforeMount, template-refs]
+---
+
+# Access DOM Only After Mounted Hook
+
+**Impact: HIGH** - Attempting to access DOM elements or `this.$el` in `created` or `beforeMount` hooks fails because the component's template has not yet been rendered to the DOM. This leads to undefined errors, null references, and failed third-party library initializations.
+
+The component's DOM is only available starting from the `mounted` hook (Options API) or after `onMounted` runs (Composition API). Before this point, `this.$el` is undefined and template refs are null.
+
+## Task Checklist
+
+- [ ] Perform DOM manipulations only in `mounted`/`onMounted` or later
+- [ ] Initialize DOM-dependent libraries (charts, maps, editors) in mounted
+- [ ] Use `created` for data initialization and API calls (non-DOM operations)
+- [ ] Access template refs only after mounted
+- [ ] Use `$nextTick` if you need DOM after reactive data changes
+
+**Incorrect:**
+```javascript
+// WRONG: Accessing DOM in created hook
+export default {
+  created() {
+    // DOM doesn't exist yet!
+    console.log(this.$el) // undefined
+    this.$el.querySelector('.chart') // Error: Cannot read property 'querySelector' of undefined
+
+    // Third-party library initialization fails
+    new Chart(document.getElementById('myChart')) // Element doesn't exist yet
+  }
+}
+```
+
+```javascript
+// WRONG: Accessing DOM in beforeMount
+export default {
+  beforeMount() {
+    // Still too early - template is compiled but not mounted
+    console.log(this.$el) // undefined in Vue 3
+    this.$refs.myInput.focus() // Error: Cannot read property 'focus' of undefined
+  }
+}
+```
+
+```vue
+<!-- WRONG: Accessing template ref synchronously in setup -->
+<script setup>
+import { ref } from 'vue'
+
+const myInput = ref(null)
+
+// This runs during setup, before mounting
+myInput.value.focus() // Error: Cannot read property 'focus' of null
+</script>
+
+<template>
+  <input ref="myInput" />
+</template>
+```
+
+**Correct:**
+```javascript
+// CORRECT: Use created for data, mounted for DOM
+export default {
+  data() {
+    return { chartData: null }
+  },
+  async created() {
+    // Data fetching is fine in created
+    this.chartData = await fetchChartData()
+  },
+  mounted() {
+    // Now the DOM exists and is safe to access
+    console.log(this.$el) // <div>...</div>
+
+    // Initialize DOM-dependent libraries
+    this.chart = new Chart(this.$refs.chartCanvas, {
+      data: this.chartData
+    })
+  }
+}
+```
+
+```vue
+<!-- CORRECT: Access template refs in onMounted -->
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const myInput = ref(null)
+
+onMounted(() => {
+  // DOM is now available
+  myInput.value.focus() // Works!
+})
+</script>
+
+<template>
+  <input ref="myInput" />
+</template>
+```
+
+```javascript
+// CORRECT: Using $nextTick for DOM access after data changes
+export default {
+  methods: {
+    async addItem() {
+      this.items.push(newItem)
+
+      // Wait for Vue to update the DOM
+      await this.$nextTick()
+
+      // Now the new element exists in DOM
+      this.$refs.list.lastElementChild.scrollIntoView()
+    }
+  }
+}
+```
+
+## Vue 3 Composition API Pattern
+
+```vue
+<script setup>
+import { ref, onMounted, nextTick } from 'vue'
+
+const listRef = ref(null)
+const items = ref([])
+
+onMounted(() => {
+  // Safe to access DOM here
+  listRef.value.style.height = '400px'
+})
+</script>
+```
+
+## Vue 3.5+ useTemplateRef Pattern
+
+```vue
+<script setup>
+import { useTemplateRef, onMounted } from 'vue'
+
+// Vue 3.5+ recommended approach - decouples ref name from variable name
+const input = useTemplateRef('my-input')
+
+onMounted(() => {
+  input.value.focus()
+})
+</script>
+
+<template>
+  <input ref="my-input" />
+</template>
+```
+
+## Composition API with nextTick
+
+```vue
+<script setup>
+import { ref, nextTick } from 'vue'
+
+const listRef = ref(null)
+const items = ref([])
+
+async function addItem(item) {
+  items.value.push(item)
+
+  // Wait for DOM update after reactive change
+  await nextTick()
+
+  // Now new item is in DOM
+  listRef.value.lastElementChild.focus()
+}
+</script>
+
+<template>
+  <ul ref="listRef">
+    <li v-for="item in items" :key="item.id">{{ item.name }}</li>
+  </ul>
+</template>
+```
+
+## Common Third-Party Libraries
+
+```javascript
+// CORRECT: Initialize in mounted
+export default {
+  mounted() {
+    // Chart.js
+    this.chart = new Chart(this.$refs.canvas, config)
+
+    // Leaflet maps
+    this.map = L.map(this.$refs.mapContainer).setView([51.505, -0.09], 13)
+
+    // Monaco Editor
+    this.editor = monaco.editor.create(this.$refs.editorContainer, options)
+
+    // Video.js
+    this.player = videojs(this.$refs.videoElement)
+  },
+  beforeUnmount() {
+    // Don't forget cleanup!
+    this.chart?.destroy()
+    this.map?.remove()
+    this.editor?.dispose()
+    this.player?.dispose()
+  }
+}
+```
+
+## Reference
+- [Vue.js Lifecycle Hooks](https://vuejs.org/guide/essentials/lifecycle.html)
+- [Vue.js Template Refs](https://vuejs.org/guide/essentials/template-refs.html)
+- [Vue.js nextTick](https://vuejs.org/api/general.html#nexttick)

package/skills/vue-debug-guides/reference/lifecycle-hooks-synchronous-registration.md

@@ -0,0 +1,156 @@
+---
+title: Register Lifecycle Hooks Synchronously During Setup
+impact: HIGH
+impactDescription: Asynchronously registered lifecycle hooks will never execute
+type: capability
+tags: [vue3, composition-api, lifecycle, onMounted, onUnmounted, async, setup]
+---
+
+# Register Lifecycle Hooks Synchronously During Setup
+
+**Impact: HIGH** - Lifecycle hooks registered asynchronously (e.g., inside setTimeout, after await) will never be called because Vue cannot associate them with the component instance. This leads to silent failures where expected initialization or cleanup code never runs.
+
+In Vue 3's Composition API, lifecycle hooks like `onMounted`, `onUnmounted`, `onUpdated`, etc. must be registered synchronously during component setup. The hook registration doesn't need to be lexically inside `setup()` or `<script setup>`, but the call stack must be synchronous and originate from within setup.
+
+## Task Checklist
+
+- [ ] Register all lifecycle hooks at the top level of setup() or `<script setup>`
+- [ ] Never register hooks inside setTimeout, setInterval, or Promise callbacks
+- [ ] When calling composables that use lifecycle hooks, call them synchronously
+- [ ] Hooks CAN be in external functions if called synchronously from setup
+
+**Incorrect:**
+```javascript
+// WRONG: Hook registered asynchronously - will NEVER execute
+import { onMounted } from 'vue'
+
+export default {
+  async setup() {
+    // After await, we're in a different call stack
+    const data = await fetchInitialData()
+
+    // This hook will NOT be registered!
+    onMounted(() => {
+      console.log('This will never run')
+    })
+  }
+}
+```
+
+```javascript
+// WRONG: Hook registered in setTimeout - will NEVER execute
+import { onMounted } from 'vue'
+
+export default {
+  setup() {
+    setTimeout(() => {
+      // This is asynchronous - hook won't be registered!
+      onMounted(() => {
+        initializeChart()
+      })
+    }, 100)
+  }
+}
+```
+
+```javascript
+// WRONG: Hook registered in Promise callback
+import { onMounted } from 'vue'
+
+export default {
+  setup() {
+    fetchConfig().then(() => {
+      // Asynchronous! This will silently fail
+      onMounted(() => {
+        applyConfig()
+      })
+    })
+  }
+}
+```
+
+**Correct:**
+```javascript
+// CORRECT: Hook registered synchronously at top level
+import { onMounted, ref } from 'vue'
+
+export default {
+  setup() {
+    const data = ref(null)
+
+    // Register hook synchronously FIRST
+    onMounted(async () => {
+      // Async operations are fine INSIDE the hook
+      data.value = await fetchInitialData()
+      initializeChart()
+    })
+
+    return { data }
+  }
+}
+```
+
+```vue
+<!-- CORRECT: <script setup> - hooks at top level -->
+<script setup>
+import { onMounted, onUnmounted, ref } from 'vue'
+
+const isReady = ref(false)
+
+// These are synchronous during script setup execution
+onMounted(() => {
+  isReady.value = true
+})
+
+onUnmounted(() => {
+  cleanup()
+})
+</script>
+```
+
+```javascript
+// CORRECT: Hook in external function called synchronously from setup
+import { onMounted, onUnmounted } from 'vue'
+
+function useWindowResize(callback) {
+  // This is fine - it's called synchronously from setup
+  onMounted(() => {
+    window.addEventListener('resize', callback)
+  })
+
+  onUnmounted(() => {
+    window.removeEventListener('resize', callback)
+  })
+}
+
+export default {
+  setup() {
+    // Composable called synchronously - hooks will be registered
+    useWindowResize(handleResize)
+  }
+}
+```
+
+## Multiple Hooks Are Allowed
+
+```javascript
+// CORRECT: You can register the same hook multiple times
+import { onMounted } from 'vue'
+
+export default {
+  setup() {
+    // Both will run, in order of registration
+    onMounted(() => {
+      initializeA()
+    })
+
+    onMounted(() => {
+      initializeB()
+    })
+  }
+}
+```
+
+## Reference
+- [Vue.js Lifecycle Hooks](https://vuejs.org/guide/essentials/lifecycle.html)
+- [Composition API Lifecycle Hooks](https://vuejs.org/api/composition-api-lifecycle.html)