@dianzhong/create-harness-app 0.1.0

package/templates/harness/full/.agents/skills/vue-best-practices/references/perf-v-once-v-memo-directives.md

@@ -0,0 +1,185 @@
+---
+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>
+
+  <!-- This content NEVER changes, but Vue checks it every render -->
+  <footer>
+    <p>Copyright {{ copyrightYear }} {{ companyName }}</p>
+  </footer>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<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>
+
+<template>
+  <!-- GOOD: Rendered once, skipped on all future updates -->
+  <div v-once class="terms-content">
+    <h1>Terms of Service</h1>
+    <p>Version: {{ termsVersion }}</p>
+    <div v-html="termsContent" />
+  </div>
+
+  <!-- v-once tells Vue this never needs to update -->
+  <footer v-once>
+    <p>Copyright {{ copyrightYear }} {{ companyName }}</p>
+  </footer>
+</template>
+```
+
+## 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
+<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>
+
+<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>
+```
+
+## v-memo with Multiple Dependencies
+
+```vue
+<script setup>
+const selectedId = ref(null)
+const editingId = ref(null)
+const items = ref([
+  /* ... */
+])
+</script>
+
+<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>
+```
+
+## 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/templates/harness/full/.agents/skills/vue-best-practices/references/perf-virtualize-large-lists.md

@@ -0,0 +1,182 @@
+---
+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
+<script setup>
+import { onMounted, ref } from 'vue'
+
+import UserCard from './UserCard.vue'
+
+const users = ref([])
+
+onMounted(async () => {
+  // 10,000 DOM nodes created, browser struggles
+  users.value = await fetchAllUsers()
+})
+</script>
+
+<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>
+```
+
+**GOOD:**
+
+```vue
+<script setup>
+import { onMounted, ref } from 'vue'
+import { RecycleScroller } from 'vue-virtual-scroller'
+
+import UserCard from './UserCard.vue'
+
+import 'vue-virtual-scroller/dist/vue-virtual-scroller.css'
+
+const users = ref([])
+
+onMounted(async () => {
+  // 10,000 items in memory, but only ~20 DOM nodes
+  users.value = await fetchAllUsers()
+})
+</script>
+
+<template>
+  <!-- GOOD: Only renders ~20 visible items at a time -->
+  <RecycleScroller
+    v-slot="{ item }"
+    class="user-list"
+    :items="users"
+    :item-size="80"
+    key-field="id"
+  >
+    <UserCard :user="item" />
+  </RecycleScroller>
+</template>
+
+<style scoped>
+.user-list {
+  height: 600px; /* Container must have fixed height */
+}
+</style>
+```
+
+## Using @tanstack/vue-virtual
+
+```vue
+<script setup>
+import { useVirtualizer } from '@tanstack/vue-virtual'
+import { ref } from 'vue'
+
+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>
+
+<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>
+
+<style scoped>
+.list-container {
+  height: 600px;
+  overflow: auto;
+}
+</style>
+```
+
+## Dynamic Heights with vue-virtual-scroller
+
+```vue
+<script setup>
+import { DynamicScroller, DynamicScrollerItem } from 'vue-virtual-scroller'
+</script>
+
+<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>
+```
+
+## 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/templates/harness/full/.agents/skills/vue-best-practices/references/plugins.md

@@ -0,0 +1,178 @@
+---
+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 { AxiosInstance } from 'axios'
+import type { InjectionKey } from 'vue'
+
+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 type { AuthService } from '@/injection-keys'
+
+import { inject } from 'vue'
+
+import { authKey } 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
+}
+```