agy-superpowers 5.0.8 → 5.0.9

package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/perf-v-once-v-memo-directives.md

@@ -0,0 +1,182 @@
+---
+title: Use v-once and v-memo to Skip Unnecessary Updates
+impact: MEDIUM
+impactDescription: v-once skips all future updates for static content; v-memo conditionally memoizes subtrees
+type: efficiency
+tags: [vue3, performance, v-once, v-memo, optimization, directives]
+---
+
+# Use v-once and v-memo to Skip Unnecessary Updates
+
+**Impact: MEDIUM** - Vue re-evaluates templates on every reactive change. For content that never changes or changes infrequently, `v-once` and `v-memo` tell Vue to skip updates, reducing render work.
+
+Use `v-once` for truly static content and `v-memo` for conditionally-static content in lists.
+
+## Task List
+
+- Apply `v-once` to elements that use runtime data but never need updating
+- Apply `v-memo` to list items that should only update on specific condition changes
+- Verify memoized content doesn't need to respond to other state changes
+- Profile with Vue DevTools to confirm update skipping
+
+## v-once: Render Once, Never Update
+
+**BAD:**
+```vue
+<template>
+  <!-- BAD: Re-evaluated on every parent re-render -->
+  <div class="terms-content">
+    <h1>Terms of Service</h1>
+    <p>Version: {{ termsVersion }}</p>
+    <div v-html="termsContent"></div>
+  </div>
+
+  <!-- This content NEVER changes, but Vue checks it every render -->
+  <footer>
+    <p>Copyright {{ copyrightYear }} {{ companyName }}</p>
+  </footer>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <!-- GOOD: Rendered once, skipped on all future updates -->
+  <div class="terms-content" v-once>
+    <h1>Terms of Service</h1>
+    <p>Version: {{ termsVersion }}</p>
+    <div v-html="termsContent"></div>
+  </div>
+
+  <!-- v-once tells Vue this never needs to update -->
+  <footer v-once>
+    <p>Copyright {{ copyrightYear }} {{ companyName }}</p>
+  </footer>
+</template>
+
+<script setup>
+// These values are set once at component creation
+const termsVersion = '2.1'
+const termsContent = fetchedTermsHTML
+const copyrightYear = 2024
+const companyName = 'Acme Corp'
+</script>
+```
+
+## v-memo: Conditional Memoization for Lists
+
+**BAD:**
+```vue
+<template>
+  <!-- BAD: All items re-render when selectedId changes -->
+  <div v-for="item in list" :key="item.id">
+    <div :class="{ selected: item.id === selectedId }">
+      <ExpensiveComponent :data="item" />
+    </div>
+  </div>
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <!-- GOOD: Items only re-render when their selection state changes -->
+  <div
+    v-for="item in list"
+    :key="item.id"
+    v-memo="[item.id === selectedId]"
+  >
+    <div :class="{ selected: item.id === selectedId }">
+      <ExpensiveComponent :data="item" />
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const list = ref([/* many items */])
+const selectedId = ref(null)
+
+// When selectedId changes:
+// - Only the previously-selected item re-renders (selected: true -> false)
+// - Only the newly-selected item re-renders (selected: false -> true)
+// - All other items are SKIPPED (v-memo values unchanged)
+</script>
+```
+
+## v-memo with Multiple Dependencies
+
+```vue
+<template>
+  <!-- Re-render only when item's selection OR editing state changes -->
+  <div
+    v-for="item in items"
+    :key="item.id"
+    v-memo="[item.id === selectedId, item.id === editingId]"
+  >
+    <ItemCard
+      :item="item"
+      :selected="item.id === selectedId"
+      :editing="item.id === editingId"
+    />
+  </div>
+</template>
+
+<script setup>
+const selectedId = ref(null)
+const editingId = ref(null)
+const items = ref([/* ... */])
+</script>
+```
+
+## v-memo with Empty Array = v-once
+
+```vue
+<template>
+  <!-- v-memo="[]" is equivalent to v-once -->
+  <div v-for="item in staticList" :key="item.id" v-memo="[]">
+    {{ item.name }}
+  </div>
+</template>
+```
+
+## When NOT to Use These Directives
+
+```vue
+<template>
+  <!-- DON'T: Content that DOES need to update -->
+  <div v-once>
+    <span>Count: {{ count }}</span>  <!-- count won't update! -->
+  </div>
+
+  <!-- DON'T: When child components have their own reactive state -->
+  <div v-memo="[selected]">
+    <InputField v-model="item.name" />  <!-- v-model won't work properly -->
+  </div>
+
+  <!-- DON'T: When the memoization benefit is minimal -->
+  <span v-once>{{ simpleText }}</span>  <!-- Overhead not worth it -->
+</template>
+```
+
+## Performance Comparison
+
+| Scenario | Without Directive | With v-once/v-memo |
+|----------|-------------------|-------------------|
+| Static header, parent re-renders 100x | Re-evaluated 100x | Evaluated 1x |
+| 1000 items, selection changes | 1000 items re-render | 2 items re-render |
+| Complex child component | Full re-render | Skipped if memoized |
+
+## Debugging Memoized Components
+
+```vue
+<script setup>
+import { onUpdated } from 'vue'
+
+// This won't fire if v-memo prevents update
+onUpdated(() => {
+  console.log('Component updated')
+})
+</script>
+```

package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/perf-virtualize-large-lists.md

@@ -0,0 +1,187 @@
+---
+title: Virtualize Large Lists to Avoid DOM Overload
+impact: HIGH
+impactDescription: Rendering thousands of list items creates excessive DOM nodes, causing slow renders and high memory usage
+type: efficiency
+tags: [vue3, performance, virtual-list, large-data, dom, optimization]
+---
+
+# Virtualize Large Lists to Avoid DOM Overload
+
+**Impact: HIGH** - Rendering all items in a large list (hundreds or thousands) creates massive amounts of DOM nodes. Each node consumes memory, slows down initial render, and makes updates expensive. List virtualization only renders visible items, dramatically improving performance.
+
+Use a virtualization library when dealing with lists that could exceed 50-100 items, especially if items have complex content.
+
+## Task List
+
+- Identify lists that render more than 50-100 items
+- Install a virtualization library (vue-virtual-scroller, @tanstack/vue-virtual)
+- Replace standard `v-for` with virtualized component
+- Ensure list items have consistent or estimable heights
+- Test with realistic data volumes during development
+
+## Recommended Libraries
+
+| Library | Best For | Notes |
+|---------|----------|-------|
+| `vue-virtual-scroller` | General use, easy setup | Most popular, good defaults |
+| `@tanstack/vue-virtual` | Complex layouts, headless | Framework-agnostic, flexible |
+| `vue-virtual-scroll-grid` | Grid layouts | 2D virtualization |
+| `vueuc/VVirtualList` | Naive UI projects | Part of Naive UI ecosystem |
+
+**BAD:**
+```vue
+<template>
+  <!-- BAD: Renders ALL 10,000 items immediately -->
+  <div class="user-list">
+    <UserCard
+      v-for="user in users"
+      :key="user.id"
+      :user="user"
+    />
+  </div>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+import UserCard from './UserCard.vue'
+
+const users = ref([])
+
+onMounted(async () => {
+  // 10,000 DOM nodes created, browser struggles
+  users.value = await fetchAllUsers()
+})
+</script>
+```
+
+**GOOD:**
+```vue
+<template>
+  <!-- GOOD: Only renders ~20 visible items at a time -->
+  <RecycleScroller
+    class="user-list"
+    :items="users"
+    :item-size="80"
+    key-field="id"
+    v-slot="{ item }"
+  >
+    <UserCard :user="item" />
+  </RecycleScroller>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+import { RecycleScroller } from 'vue-virtual-scroller'
+import 'vue-virtual-scroller/dist/vue-virtual-scroller.css'
+import UserCard from './UserCard.vue'
+
+const users = ref([])
+
+onMounted(async () => {
+  // 10,000 items in memory, but only ~20 DOM nodes
+  users.value = await fetchAllUsers()
+})
+</script>
+
+<style scoped>
+.user-list {
+  height: 600px; /* Container must have fixed height */
+}
+</style>
+```
+
+## Using @tanstack/vue-virtual
+
+```vue
+<template>
+  <div ref="parentRef" class="list-container">
+    <div
+      :style="{
+        height: `${rowVirtualizer.getTotalSize()}px`,
+        position: 'relative'
+      }"
+    >
+      <div
+        v-for="virtualRow in rowVirtualizer.getVirtualItems()"
+        :key="virtualRow.key"
+        :style="{
+          position: 'absolute',
+          top: 0,
+          left: 0,
+          width: '100%',
+          height: `${virtualRow.size}px`,
+          transform: `translateY(${virtualRow.start}px)`
+        }"
+      >
+        <UserCard :user="users[virtualRow.index]" />
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { useVirtualizer } from '@tanstack/vue-virtual'
+
+const users = ref([/* 10,000 users */])
+const parentRef = ref(null)
+
+const rowVirtualizer = useVirtualizer({
+  count: users.value.length,
+  getScrollElement: () => parentRef.value,
+  estimateSize: () => 80,  // Estimated row height
+  overscan: 5  // Render 5 extra items above/below viewport
+})
+</script>
+
+<style scoped>
+.list-container {
+  height: 600px;
+  overflow: auto;
+}
+</style>
+```
+
+## Dynamic Heights with vue-virtual-scroller
+
+```vue
+<template>
+  <!-- For variable height items, use DynamicScroller -->
+  <DynamicScroller
+    :items="messages"
+    :min-item-size="54"
+    key-field="id"
+  >
+    <template #default="{ item, index, active }">
+      <DynamicScrollerItem
+        :item="item"
+        :active="active"
+        :data-index="index"
+      >
+        <ChatMessage :message="item" />
+      </DynamicScrollerItem>
+    </template>
+  </DynamicScroller>
+</template>
+
+<script setup>
+import { DynamicScroller, DynamicScrollerItem } from 'vue-virtual-scroller'
+</script>
+```
+
+## Performance Comparison
+
+| Approach | 100 Items | 1,000 Items | 10,000 Items |
+|----------|-----------|-------------|--------------|
+| Regular v-for | ~100 DOM nodes | ~1,000 DOM nodes | ~10,000 DOM nodes |
+| Virtualized | ~20 DOM nodes | ~20 DOM nodes | ~20 DOM nodes |
+| Initial render | Fast | Slow | Very slow / crashes |
+| Virtualized render | Fast | Fast | Fast |
+
+## When NOT to Virtualize
+
+- Lists under 50 items with simple content
+- Lists where all items must be accessible to screen readers simultaneously
+- Print layouts where all content must render
+- SEO-critical content that must be in initial HTML

package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/plugins.md

@@ -0,0 +1,166 @@
+---
+title: Vue Plugin Best Practices
+impact: MEDIUM
+impactDescription: Incorrect plugin structure or injection key strategy causes install failures, collisions, and unsafe APIs
+type: best-practice
+tags: [vue3, plugins, provide-inject, typescript, dependency-injection]
+---
+
+# Vue Plugin Best Practices
+
+**Impact: MEDIUM** - Vue plugins should follow the `app.use()` contract, expose explicit capabilities, and use collision-safe injection keys. This keeps plugin setup predictable and composable across large apps.
+
+## Task List
+
+- Export plugins as an object with `install()` or as an install function
+- Use the `app` instance in `install()` to register components/directives/provides
+- Type plugin APIs with `Plugin` (and options tuple types when needed)
+- Use symbol keys (prefer `InjectionKey<T>`) for `provide/inject` in plugins
+- Add a small typed composable wrapper for required injections to fail fast
+
+## Structure Plugins for `app.use()`
+
+A Vue plugin must be either:
+- An object with `install(app, options?)`
+- A function with the same signature
+
+**BAD:**
+```ts
+const notAPlugin = {
+  doSomething() {}
+}
+
+app.use(notAPlugin)
+```
+
+**GOOD:**
+```ts
+import type { App } from 'vue'
+
+interface PluginOptions {
+  prefix?: string
+  debug?: boolean
+}
+
+const myPlugin = {
+  install(app: App, options: PluginOptions = {}) {
+    const { prefix = 'my', debug = false } = options
+
+    if (debug) {
+      console.log('Installing myPlugin with prefix:', prefix)
+    }
+
+    app.provide('myPlugin', { prefix })
+  }
+}
+
+app.use(myPlugin, { prefix: 'custom', debug: true })
+```
+
+**GOOD:**
+```ts
+import type { App } from 'vue'
+
+function simplePlugin(app: App, options?: { message: string }) {
+  app.config.globalProperties.$greet = () => options?.message ?? 'Hello!'
+}
+
+app.use(simplePlugin, { message: 'Welcome!' })
+```
+
+## Register Capabilities Explicitly in `install()`
+
+Inside `install()`, wire behavior through Vue application APIs:
+- `app.component()` for global components
+- `app.directive()` for global directives
+- `app.provide()` for injectable services and config
+- `app.config.globalProperties` for optional global helpers (sparingly)
+
+**BAD:**
+```ts
+const uselessPlugin = {
+  install(app, options) {
+    const service = createService(options)
+  }
+}
+```
+
+**GOOD:**
+```ts
+const usefulPlugin = {
+  install(app, options) {
+    const service = createService(options)
+    app.provide(serviceKey, service)
+  }
+}
+```
+
+## Type Plugin Contracts
+
+Use Vue's `Plugin` type to keep install signatures and options type-safe.
+
+```ts
+import type { App, Plugin } from 'vue'
+
+interface MyOptions {
+  apiKey: string
+}
+
+const myPlugin: Plugin<[MyOptions]> = {
+  install(app: App, options: MyOptions) {
+    app.provide(apiKeyKey, options.apiKey)
+  }
+}
+```
+
+## Use Symbol Injection Keys in Plugins
+
+String keys can collide (`'http'`, `'config'`, `'i18n'`). Use symbol keys with `InjectionKey<T>` so injections are unique and typed.
+
+**BAD:**
+```ts
+export default {
+  install(app) {
+    app.provide('http', axios)
+    app.provide('config', appConfig)
+  }
+}
+```
+
+**GOOD:**
+```ts
+import type { InjectionKey } from 'vue'
+import type { AxiosInstance } from 'axios'
+
+interface AppConfig {
+  apiUrl: string
+  timeout: number
+}
+
+export const httpKey: InjectionKey<AxiosInstance> = Symbol('http')
+export const configKey: InjectionKey<AppConfig> = Symbol('appConfig')
+
+export default {
+  install(app) {
+    app.provide(httpKey, axios)
+    app.provide(configKey, { apiUrl: '/api', timeout: 5000 })
+  }
+}
+```
+
+## Provide Required Injection Helpers
+
+Wrap required injections in composables that throw clear setup errors.
+
+```ts
+import { inject } from 'vue'
+import { authKey, type AuthService } from '@/injection-keys'
+
+export function useAuth(): AuthService {
+  const auth = inject(authKey)
+  if (!auth) {
+    throw new Error('Auth plugin not installed. Did you forget app.use(authPlugin)?')
+  }
+  return auth
+}
+```