@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/reactivity-same-tick-batching.md

@@ -0,0 +1,166 @@
+---
+title: Understand Reactive Updates are Batched Per Event Loop Tick
+impact: MEDIUM
+impactDescription: Multiple synchronous reactive changes are batched - watchers only see the final value, not intermediate states
+type: gotcha
+tags: [vue3, reactivity, batching, event-loop, watchers, nextTick]
+---
+
+# Understand Reactive Updates are Batched Per Event Loop Tick
+
+**Impact: MEDIUM** - Vue batches multiple reactive state changes that happen synchronously within the same event loop tick. Watchers and computed properties only see the final state, not intermediate values. This is an optimization, but it can be surprising if you expect watchers to fire for each individual change.
+
+Understanding this behavior is essential for debugging scenarios where you expect to observe every state transition.
+
+## Task Checklist
+
+- [ ] Understand watchers fire once per tick with final value, not for each mutation
+- [ ] Use `nextTick()` if you need to ensure DOM updates between state changes
+- [ ] Use `flush: 'sync'` on watchers only if you absolutely need immediate execution
+- [ ] For intermediate value tracking, consider logging or explicit state snapshots
+
+**Example of batching behavior:**
+```javascript
+import { ref, watch } from 'vue'
+
+const count = ref(0)
+
+watch(count, (newValue) => {
+  console.log('Count changed to:', newValue)
+})
+
+// Multiple synchronous changes in the same tick
+function multipleUpdates() {
+  count.value = 1
+  count.value = 2
+  count.value = 3
+  count.value = 4
+}
+
+multipleUpdates()
+// Console output: "Count changed to: 4"
+// NOT: 1, 2, 3, 4 - only the final value is observed!
+```
+
+**The console logs you WON'T see:**
+```javascript
+const items = reactive([])
+
+watch(items, (newItems) => {
+  console.log('Items count:', newItems.length)
+})
+
+// Batch of changes
+items.push('a')  // length: 1
+items.push('b')  // length: 2
+items.push('c')  // length: 3
+
+// Output: "Items count: 3"
+// You won't see 1, 2, 3 logged separately
+```
+
+**Using flush: 'sync' for immediate watching (use with caution):**
+```javascript
+import { ref, watch } from 'vue'
+
+const count = ref(0)
+
+// Sync watcher fires immediately on each change
+watch(count, (newValue) => {
+  console.log('Immediate:', newValue)
+}, { flush: 'sync' })
+
+count.value = 1  // Logs: "Immediate: 1"
+count.value = 2  // Logs: "Immediate: 2"
+count.value = 3  // Logs: "Immediate: 3"
+
+// WARNING: flush: 'sync' can cause performance issues
+// and creates less predictable behavior. Avoid if possible.
+```
+
+**Using nextTick to separate batches:**
+```javascript
+import { ref, watch, nextTick } from 'vue'
+
+const count = ref(0)
+
+watch(count, (newValue) => {
+  console.log('Count:', newValue)
+})
+
+async function separatedUpdates() {
+  count.value = 1
+  await nextTick()  // Force flush
+  // Output: "Count: 1"
+
+  count.value = 2
+  await nextTick()
+  // Output: "Count: 2"
+
+  count.value = 3
+  // Output: "Count: 3"
+}
+```
+
+**Practical example - form validation:**
+```javascript
+const formData = reactive({
+  email: '',
+  password: ''
+})
+
+const validationErrors = ref([])
+
+// This watcher only fires once, with final form state
+watch(formData, (data) => {
+  // Runs once after all fields are updated
+  validateForm(data)
+}, { deep: true })
+
+// When user submits, you might update multiple fields
+function populateFromSavedData(saved) {
+  formData.email = saved.email
+  formData.password = saved.password
+  // Validation runs once with both fields set
+}
+```
+
+**When batching helps performance:**
+```javascript
+// Without batching, this would trigger 1000 watcher/render cycles
+const list = reactive([])
+
+function addManyItems() {
+  for (let i = 0; i < 1000; i++) {
+    list.push(i)
+  }
+}
+// With batching: renders once with all 1000 items
+// Without batching: would render 1000 times!
+```
+
+**Debugging intermediate states:**
+```javascript
+// If you need to observe every change for debugging:
+import { ref, watch } from 'vue'
+
+const count = ref(0)
+
+// Method 1: Sync watcher (not recommended for production)
+watch(count, (val) => console.log('DEBUG:', val), { flush: 'sync' })
+
+// Method 2: Track history manually
+const history = []
+const originalSet = count.value
+Object.defineProperty(count, 'value', {
+  set(val) {
+    history.push(val)
+    originalSet.call(this, val)
+  }
+})
+```
+
+## Reference
+- [Vue.js Reactivity in Depth](https://vuejs.org/guide/extras/reactivity-in-depth.html)
+- [Vue.js Watchers - Callback Flush Timing](https://vuejs.org/guide/essentials/watchers.html#callback-flush-timing)
+- [Vue.js nextTick()](https://vuejs.org/api/general.html#nexttick)

package/skills/vue-debug-guides/reference/ref-value-access.md

@@ -0,0 +1,61 @@
+---
+title: Always Use .value When Accessing ref() in JavaScript
+impact: HIGH
+impactDescription: Forgetting .value causes silent failures and bugs in reactive state updates
+type: capability
+tags: [vue3, reactivity, ref, composition-api]
+---
+
+# Always Use .value When Accessing ref() in JavaScript
+
+**Impact: HIGH** - Forgetting `.value` causes silent failures where state updates don't trigger reactivity, leading to hard-to-debug issues.
+
+When using `ref()` in Vue 3's Composition API, the reactive value is wrapped in an object and must be accessed via `.value` in JavaScript code. However, in templates, Vue automatically unwraps refs so `.value` is not needed there. This inconsistency is a common source of bugs.
+
+## Task Checklist
+
+- [ ] Always use `.value` when reading or writing ref values in `<script>` or `.js`/`.ts` files
+- [ ] Never use `.value` in `<template>` - Vue unwraps refs automatically there
+- [ ] When passing refs to functions, decide whether to pass the ref object or `.value`
+- [ ] Use IDE/TypeScript to catch missing `.value` errors early
+
+**Incorrect:**
+```javascript
+import { ref } from 'vue'
+
+const count = ref(0)
+
+// These do NOT work as expected
+count++           // Tries to increment the ref object, not the value
+count = 5         // Reassigns the variable, loses reactivity
+console.log(count) // Logs "[object Object]", not the number
+
+const items = ref([1, 2, 3])
+items.push(4)     // Error: push is not a function
+```
+
+**Correct:**
+```javascript
+import { ref } from 'vue'
+
+const count = ref(0)
+
+// Always use .value in JavaScript
+count.value++           // Correctly increments to 1
+count.value = 5         // Correctly sets value to 5
+console.log(count.value) // Logs "5"
+
+const items = ref([1, 2, 3])
+items.value.push(4)     // Correctly adds 4 to the array
+```
+
+```vue
+<template>
+  <!-- In templates, NO .value needed - Vue unwraps automatically -->
+  <p>{{ count }}</p>
+  <button @click="count++">Increment</button>
+</template>
+```
+
+## Reference
+- [Vue.js Reactivity Fundamentals - ref()](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#ref)

package/skills/vue-debug-guides/reference/refs-in-collections-need-value.md

@@ -0,0 +1,81 @@
+---
+title: Refs in Arrays and Collections Require .value
+impact: MEDIUM
+impactDescription: Refs inside reactive arrays, Maps, or Sets are NOT auto-unwrapped like in reactive objects
+type: capability
+tags: [vue3, reactivity, ref, arrays, collections, unwrapping]
+---
+
+# Refs in Arrays and Collections Require .value
+
+**Impact: MEDIUM** - Unlike when a ref is a property of a reactive object, refs inside reactive arrays, Maps, and Sets are NOT automatically unwrapped. You must access them with `.value`, and forgetting this leads to silent bugs.
+
+Vue only auto-unwraps refs when they are properties of reactive objects. When refs are elements in arrays or values in Maps/Sets, they remain as ref objects and require explicit `.value` access.
+
+## Task Checklist
+
+- [ ] Always use `.value` when accessing refs stored in reactive arrays
+- [ ] Always use `.value` when accessing refs stored in reactive Maps or Sets
+- [ ] Consider storing plain values instead of refs in collections to avoid confusion
+- [ ] Be aware of this when iterating over arrays containing refs
+
+**Incorrect:**
+```javascript
+import { ref, reactive } from 'vue'
+
+const books = reactive([ref('Vue 3 Guide')])
+const counts = reactive(new Map([['clicks', ref(0)]]))
+
+// WRONG: Refs in arrays are NOT unwrapped
+console.log(books[0])        // Ref object, not 'Vue 3 Guide'
+books[0] = 'New Title'       // Replaces the ref, doesn't update it!
+
+// WRONG: Refs in Maps are NOT unwrapped
+console.log(counts.get('clicks'))     // Ref object, not 0
+counts.get('clicks')++                // Does nothing useful
+```
+
+**Correct:**
+```javascript
+import { ref, reactive } from 'vue'
+
+const books = reactive([ref('Vue 3 Guide')])
+const counts = reactive(new Map([['clicks', ref(0)]]))
+
+// CORRECT: Use .value for refs in arrays
+console.log(books[0].value)    // 'Vue 3 Guide'
+books[0].value = 'New Title'   // Updates the ref's value
+
+// CORRECT: Use .value for refs in Maps
+console.log(counts.get('clicks').value)  // 0
+counts.get('clicks').value++             // Increments to 1
+```
+
+```javascript
+// ALTERNATIVE: Just store plain values in collections (simpler)
+const books = reactive(['Vue 3 Guide', 'Vuex Handbook'])
+const counts = reactive(new Map([['clicks', 0]]))
+
+// No .value needed - but changes to individual items aren't independently reactive
+console.log(books[0])            // 'Vue 3 Guide'
+console.log(counts.get('clicks')) // 0
+
+// Mutations still trigger reactivity through the reactive wrapper
+books[0] = 'New Title'           // Works
+counts.set('clicks', counts.get('clicks') + 1)  // Works
+```
+
+```vue
+<template>
+  <!-- In templates, refs in arrays also need special handling -->
+  <div v-for="(book, index) in books" :key="index">
+    <!-- If book is a ref, you'd need: -->
+    {{ book.value }}
+
+    <!-- Or use computed to unwrap them first -->
+  </div>
+</template>
+```
+
+## Reference
+- [Vue.js Reactivity Fundamentals - Caveat in Arrays and Collections](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#caveat-in-arrays-and-collections)

package/skills/vue-debug-guides/reference/render-function-avoid-internal-vnode-properties.md

@@ -0,0 +1,151 @@
+---
+title: Do Not Rely on Internal VNode Properties
+impact: MEDIUM
+impactDescription: Using undocumented vnode properties causes code to break on Vue updates
+type: gotcha
+tags: [vue3, render-function, vnode, internal-api]
+---
+
+# Do Not Rely on Internal VNode Properties
+
+**Impact: MEDIUM** - The `VNode` interface contains many internal properties used by Vue's rendering system. Relying on any properties other than the documented public ones will cause your code to break when Vue's internal implementation changes.
+
+Only use the documented vnode properties: `type`, `props`, `children`, and `key`. All other properties are internal implementation details that may change without notice between Vue versions.
+
+## Task Checklist
+
+- [ ] Only access documented vnode properties: `type`, `props`, `children`, `key`
+- [ ] Never access properties like `el`, `component`, `shapeFlag`, `patchFlag`, etc.
+- [ ] If you need DOM element access, use template refs instead
+- [ ] Treat vnodes as opaque data structures for rendering, not inspection
+
+**Incorrect:**
+```javascript
+import { h } from 'vue'
+
+export default {
+  setup(props, { slots }) {
+    return () => {
+      const slotContent = slots.default?.()
+
+      // WRONG: Accessing internal properties
+      if (slotContent?.[0]?.el) {
+        // el is an internal property
+        console.log(slotContent[0].el.tagName)
+      }
+
+      // WRONG: Using shapeFlag internal property
+      if (slotContent?.[0]?.shapeFlag & 1) {
+        // This is internal implementation
+      }
+
+      return h('div', slotContent)
+    }
+  }
+}
+```
+
+```javascript
+// WRONG: Inspecting component instance via vnode
+const vnode = h(MyComponent)
+console.log(vnode.component) // Internal property
+console.log(vnode.appContext) // Internal property
+```
+
+**Correct:**
+```javascript
+import { h } from 'vue'
+
+export default {
+  setup(props, { slots }) {
+    return () => {
+      const slotContent = slots.default?.()
+
+      // CORRECT: Only use documented properties
+      if (slotContent?.[0]) {
+        const vnode = slotContent[0]
+        console.log(vnode.type)     // Safe: element type or component
+        console.log(vnode.props)    // Safe: props object
+        console.log(vnode.children) // Safe: children
+        console.log(vnode.key)      // Safe: key prop
+      }
+
+      return h('div', slotContent)
+    }
+  }
+}
+```
+
+```javascript
+import { h, ref, onMounted } from 'vue'
+
+export default {
+  setup() {
+    // CORRECT: Use template refs for DOM access
+    const divRef = ref(null)
+
+    onMounted(() => {
+      // Safe way to access DOM element
+      console.log(divRef.value.tagName)
+    })
+
+    return () => h('div', { ref: divRef }, 'Content')
+  }
+}
+```
+
+## Documented VNode Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `type` | `string \| Component` | Element tag name or component definition |
+| `props` | `object \| null` | Props passed to the vnode |
+| `children` | `any` | Child vnodes, text, or slots |
+| `key` | `string \| number \| null` | Key for list rendering |
+
+## Safe VNode Inspection Patterns
+
+```javascript
+import { h, isVNode } from 'vue'
+
+export default {
+  setup(props, { slots }) {
+    return () => {
+      const children = slots.default?.() || []
+
+      // Safe: Check if something is a vnode
+      children.forEach(child => {
+        if (isVNode(child)) {
+          // Safe: Check vnode type
+          if (typeof child.type === 'string') {
+            console.log('Element:', child.type)
+          } else if (typeof child.type === 'object') {
+            console.log('Component:', child.type.name)
+          }
+
+          // Safe: Read props
+          if (child.props?.class) {
+            console.log('Has class:', child.props.class)
+          }
+        }
+      })
+
+      return h('div', children)
+    }
+  }
+}
+```
+
+## Why This Matters
+
+Vue's internal vnode structure may change for:
+- Performance optimizations
+- New feature implementations
+- Bug fixes
+- Tree-shaking improvements
+
+Code relying on internal properties will break silently or throw errors when upgrading Vue versions. The documented properties are part of Vue's public API and are guaranteed to remain stable.
+
+## Reference
+- [Vue.js Render Function APIs](https://vuejs.org/api/render-function.html)
+- [Vue.js Render Functions - The Virtual DOM](https://vuejs.org/guide/extras/render-function.html#the-virtual-dom)

package/skills/vue-debug-guides/reference/render-function-vnodes-must-be-unique.md

@@ -0,0 +1,133 @@
+---
+title: VNodes Must Be Unique in Render Functions
+impact: HIGH
+impactDescription: Reusing vnode references causes rendering bugs and unexpected behavior
+type: gotcha
+tags: [vue3, render-function, vnode, composition-api]
+---
+
+# VNodes Must Be Unique in Render Functions
+
+**Impact: HIGH** - Reusing the same vnode reference multiple times in a render function tree causes rendering bugs, where only one instance appears or updates behave unexpectedly.
+
+Every vnode in a component's render tree must be unique. You cannot use the same vnode object multiple times. If you need to render the same element multiple times, create each vnode separately using a factory function or by calling `h()` in a loop.
+
+## Task Checklist
+
+- [ ] Never store a vnode in a variable and use it multiple times in the same tree
+- [ ] Use a factory function or `.map()` to create multiple similar vnodes
+- [ ] Each `h()` call creates a new vnode, so call it for each instance needed
+- [ ] Be especially careful when extracting vnode creation into helper functions
+
+**Incorrect:**
+```javascript
+import { h } from 'vue'
+
+export default {
+  setup() {
+    return () => {
+      // WRONG: Same vnode reference used twice
+      const p = h('p', 'Hello')
+      return h('div', [p, p]) // Bug! Duplicate vnode reference
+    }
+  }
+}
+```
+
+```javascript
+import { h } from 'vue'
+
+export default {
+  setup() {
+    return () => {
+      // WRONG: Reusing vnode in different parts of tree
+      const icon = h('span', { class: 'icon' }, '★')
+      return h('div', [
+        h('button', [icon, ' Save']),    // Uses icon
+        h('button', [icon, ' Delete'])   // Reuses same icon - Bug!
+      ])
+    }
+  }
+}
+```
+
+**Correct:**
+```javascript
+import { h } from 'vue'
+
+export default {
+  setup() {
+    return () => {
+      // CORRECT: Create new vnode for each use
+      return h('div', [
+        h('p', 'Hello'),
+        h('p', 'Hello')
+      ])
+    }
+  }
+}
+```
+
+```javascript
+import { h } from 'vue'
+
+export default {
+  setup() {
+    return () => {
+      // CORRECT: Factory function creates new vnode each time
+      const createIcon = () => h('span', { class: 'icon' }, '★')
+      return h('div', [
+        h('button', [createIcon(), ' Save']),
+        h('button', [createIcon(), ' Delete'])
+      ])
+    }
+  }
+}
+```
+
+```javascript
+import { h } from 'vue'
+
+export default {
+  setup() {
+    return () => {
+      // CORRECT: Using map to create multiple vnodes
+      return h('div',
+        Array.from({ length: 20 }).map(() => h('p', 'Hello'))
+      )
+    }
+  }
+}
+```
+
+```javascript
+import { h } from 'vue'
+
+export default {
+  setup() {
+    const items = ['Apple', 'Banana', 'Cherry']
+
+    return () => h('ul',
+      // CORRECT: Each iteration creates a new vnode
+      items.map((item, index) =>
+        h('li', { key: index }, item)
+      )
+    )
+  }
+}
+```
+
+## Why VNodes Must Be Unique
+
+VNodes are lightweight JavaScript objects that Vue's virtual DOM algorithm uses for diffing and patching. When the same vnode reference appears multiple times:
+- Vue cannot differentiate between the instances
+- The diffing algorithm produces incorrect results
+- Only one instance may render, or updates may corrupt the DOM
+
+Each vnode maintains its own identity and position in the tree, which is essential for:
+- Correct DOM patching during updates
+- Proper lifecycle hook execution
+- Accurate key-based reconciliation in lists
+
+## Reference
+- [Vue.js Render Functions - Vnodes Must Be Unique](https://vuejs.org/guide/extras/render-function.html#vnodes-must-be-unique)