@dianzhong/create-harness-app 0.1.0

package/templates/harness/full/.claude/skills/vue-best-practices/references/component-keep-alive.md

@@ -0,0 +1,139 @@
+---
+title: KeepAlive Component Best Practices
+impact: HIGH
+impactDescription: KeepAlive caches component instances; misuse causes stale data, memory growth, or unexpected lifecycle behavior
+type: best-practice
+tags: [vue3, keepalive, cache, performance, router, dynamic-components]
+---
+
+# KeepAlive Component Best Practices
+
+**Impact: HIGH** - `<KeepAlive>` caches component instances instead of destroying them. Use it to preserve state across switches, but manage cache size and freshness explicitly to avoid memory growth or stale UI.
+
+## Task List
+
+- Use KeepAlive only where state preservation improves UX
+- Set a reasonable `max` to cap cache size
+- Declare component names for include/exclude matching
+- Use `onActivated`/`onDeactivated` for cache-aware logic
+- Decide how and when cached views refresh their data
+- Avoid caching memory-heavy or security-sensitive views
+
+## When to Use KeepAlive
+
+Use KeepAlive when switching between views where state should persist (tabs, multi-step forms, dashboards). Avoid it when each visit should start fresh.
+
+**BAD:**
+
+```vue
+<template>
+  <!-- State resets on every switch -->
+  <component :is="currentTab" />
+</template>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <!-- State preserved between switches -->
+  <KeepAlive>
+    <component :is="currentTab" />
+  </KeepAlive>
+</template>
+```
+
+## When NOT to Use KeepAlive
+
+- Search or filter pages where users expect fresh results
+- Memory-heavy components (maps, large tables, media players)
+- Sensitive flows where data must be cleared on exit
+- Components with heavy background activity you cannot pause
+
+## Limit and Control the Cache
+
+Always cap cache size with `max` and restrict caching to specific components when possible.
+
+```vue
+<template>
+  <KeepAlive :max="5" include="Dashboard,Settings">
+    <component :is="currentView" />
+  </KeepAlive>
+</template>
+```
+
+## Ensure Component Names Match include/exclude
+
+`include` and `exclude` match the component `name` option. Explicitly set names for reliable caching.
+
+```vue
+<!-- TabA.vue -->
+<script setup>
+defineOptions({ name: 'TabA' })
+</script>
+```
+
+```vue
+<template>
+  <KeepAlive include="TabA,TabB">
+    <component :is="currentTab" />
+  </KeepAlive>
+</template>
+```
+
+## Cache Invalidation Strategies
+
+Vue 3 has no direct API to remove a specific cached instance. Use keys or dynamic include/exclude to force refreshes.
+
+```vue
+<script setup>
+import { reactive, ref } from 'vue'
+
+const currentView = ref('Dashboard')
+const viewKeys = reactive({ Dashboard: 0, Settings: 0 })
+
+function invalidateCache(view) {
+  viewKeys[view]++
+}
+</script>
+
+<template>
+  <KeepAlive>
+    <component :is="currentView" :key="`${currentView}-${viewKeys[currentView]}`" />
+  </KeepAlive>
+</template>
+```
+
+## Lifecycle Hooks for Cached Components
+
+Cached components are not destroyed on switch. Use activation hooks for refresh and cleanup.
+
+```vue
+<script setup>
+import { onActivated, onDeactivated } from 'vue'
+
+onActivated(() => {
+  refreshData()
+})
+
+onDeactivated(() => {
+  pauseTimers()
+})
+</script>
+```
+
+## Router Caching and Freshness
+
+Decide whether navigation should show cached state or a fresh view. A common pattern is to key by route when params change.
+
+```vue
+<template>
+  <router-view v-slot="{ Component, route }">
+    <KeepAlive>
+      <component :is="Component" :key="route.fullPath" />
+    </KeepAlive>
+  </router-view>
+</template>
+```
+
+If you want cache reuse but fresh data, refresh in `onActivated` and compare query/params before fetching.

package/templates/harness/full/.claude/skills/vue-best-practices/references/component-slots.md

@@ -0,0 +1,226 @@
+---
+title: Component Slots Best Practices
+impact: MEDIUM
+impactDescription: Poor slot API design causes empty DOM wrappers, weak TypeScript safety, brittle defaults, and unnecessary component overhead
+type: best-practice
+tags: [vue3, slots, components, typescript, composables]
+---
+
+# Component Slots Best Practices
+
+**Impact: MEDIUM** - Slots are a core component API surface in Vue. Structure them intentionally so templates stay predictable, typed, and performant.
+
+## Task List
+
+- Use shorthand syntax for named slots (`#` instead of `v-slot:`)
+- Render optional slot wrapper elements only when slot content exists (`$slots` checks)
+- Type scoped slot contracts with `defineSlots` in TypeScript components
+- Provide fallback content for optional slots
+- Prefer composables over renderless components for pure logic reuse
+
+## Shorthand syntax for named slots
+
+**BAD:**
+
+```vue
+<MyComponent>
+  <template v-slot:header> ... </template>
+</MyComponent>
+```
+
+**GOOD:**
+
+```vue
+<MyComponent>
+  <template #header> ... </template>
+</MyComponent>
+```
+
+## Conditionally Render Optional Slot Wrappers
+
+Use `$slots` checks when wrapper elements add spacing, borders, or layout constraints.
+
+**BAD:**
+
+```vue
+<!-- Card.vue -->
+<template>
+  <article class="card">
+    <header class="card-header">
+      <slot name="header" />
+    </header>
+
+    <section class="card-body">
+      <slot />
+    </section>
+
+    <footer class="card-footer">
+      <slot name="footer" />
+    </footer>
+  </article>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<!-- Card.vue -->
+<template>
+  <article class="card">
+    <header v-if="$slots.header" class="card-header">
+      <slot name="header" />
+    </header>
+
+    <section v-if="$slots.default" class="card-body">
+      <slot />
+    </section>
+
+    <footer v-if="$slots.footer" class="card-footer">
+      <slot name="footer" />
+    </footer>
+  </article>
+</template>
+```
+
+## Type Scoped Slot Props with defineSlots
+
+In `<script setup lang="ts">`, use `defineSlots` so slot consumers get autocomplete and static checks.
+
+**BAD:**
+
+```vue
+<!-- ProductList.vue -->
+<script setup lang="ts">
+interface Product {
+  id: number
+  name: string
+}
+
+defineProps<{ products: Product[] }>()
+</script>
+
+<template>
+  <ul>
+    <li v-for="(product, index) in products" :key="product.id">
+      <slot :product="product" :index="index" />
+    </li>
+  </ul>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<!-- ProductList.vue -->
+<script setup lang="ts">
+interface Product {
+  id: number
+  name: string
+}
+
+defineProps<{ products: Product[] }>()
+
+defineSlots<{
+  default: (props: { product: Product; index: number }) => any
+  empty: () => any
+}>()
+</script>
+
+<template>
+  <ul v-if="products.length">
+    <li v-for="(product, index) in products" :key="product.id">
+      <slot :product="product" :index="index" />
+    </li>
+  </ul>
+  <slot v-else name="empty" />
+</template>
+```
+
+## Provide Slot Fallback Content
+
+Fallback content makes components resilient when parents omit optional slots.
+
+**BAD:**
+
+```vue
+<!-- SubmitButton.vue -->
+<template>
+  <button type="submit" class="btn-primary">
+    <slot />
+  </button>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<!-- SubmitButton.vue -->
+<template>
+  <button type="submit" class="btn-primary">
+    <slot>Submit</slot>
+  </button>
+</template>
+```
+
+## Prefer Composables for Pure Logic Reuse
+
+Renderless components are still useful for slot-driven composition, but composables are usually cleaner for logic-only reuse.
+
+**BAD:**
+
+```vue
+<!-- MouseTracker.vue -->
+<script setup lang="ts">
+import { onMounted, onUnmounted, ref } from 'vue'
+
+const x = ref(0)
+const y = ref(0)
+
+function onMove(event: MouseEvent) {
+  x.value = event.pageX
+  y.value = event.pageY
+}
+
+onMounted(() => window.addEventListener('mousemove', onMove))
+onUnmounted(() => window.removeEventListener('mousemove', onMove))
+</script>
+
+<template>
+  <slot :x="x" :y="y" />
+</template>
+```
+
+**GOOD:**
+
+```ts
+// composables/useMouse.ts
+import { onMounted, onUnmounted, ref } from 'vue'
+
+export function useMouse() {
+  const x = ref(0)
+  const y = ref(0)
+
+  function onMove(event: MouseEvent) {
+    x.value = event.pageX
+    y.value = event.pageY
+  }
+
+  onMounted(() => window.addEventListener('mousemove', onMove))
+  onUnmounted(() => window.removeEventListener('mousemove', onMove))
+
+  return { x, y }
+}
+```
+
+```vue
+<!-- MousePosition.vue -->
+<script setup lang="ts">
+import { useMouse } from '@/composables/useMouse'
+
+const { x, y } = useMouse()
+</script>
+
+<template>
+  <p>{{ x }}, {{ y }}</p>
+</template>
+```

package/templates/harness/full/.claude/skills/vue-best-practices/references/component-suspense.md

@@ -0,0 +1,231 @@
+---
+title: Suspense Component Best Practices
+impact: MEDIUM
+impactDescription: Suspense coordinates async dependencies with fallback UI; misconfiguration leads to missing loading states or confusing UX
+type: best-practice
+tags:
+  [vue3, suspense, async-components, async-setup, loading, fallback, router, transition, keepalive]
+---
+
+# Suspense Component Best Practices
+
+**Impact: MEDIUM** - `<Suspense>` coordinates async dependencies (async components or async setup) and renders a fallback while they resolve. Misconfiguration leads to missing loading states, empty renders, or subtle UX bugs.
+
+## Task List
+
+- Wrap default and fallback slot content in a single root node
+- Use `timeout` when you need the fallback to appear on reverts
+- Force root replacement with `:key` when you need Suspense to re-trigger
+- Add `suspensible` to nested Suspense boundaries (Vue 3.3+)
+- Use `@pending`, `@resolve`, and `@fallback` for programmatic loading state
+- Nest `RouterView` -> `Transition` -> `KeepAlive` -> `Suspense` in that order
+- Keep Suspense usage centralized and documented in production
+
+## Single Root in Default and Fallback Slots
+
+Suspense tracks a single immediate child in both slots. Wrap multiple elements in a single element or component.
+
+**BAD:**
+
+```vue
+<template>
+  <Suspense>
+    <AsyncHeader />
+    <AsyncList />
+
+    <template #fallback>
+      <LoadingSpinner />
+      <LoadingHint />
+    </template>
+  </Suspense>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <Suspense>
+    <div>
+      <AsyncHeader />
+      <AsyncList />
+    </div>
+
+    <template #fallback>
+      <div>
+        <LoadingSpinner />
+        <LoadingHint />
+      </div>
+    </template>
+  </Suspense>
+</template>
+```
+
+## Fallback Timing on Reverts (`timeout`)
+
+When Suspense is already resolved and new async work starts, the previous content remains visible until the timeout elapses. Use `timeout="0"` for immediate fallback or a short delay to avoid flicker.
+
+**BAD:**
+
+```vue
+<template>
+  <Suspense>
+    <component :is="currentView" :key="viewKey" />
+
+    <template #fallback> Loading... </template>
+  </Suspense>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <Suspense :timeout="200">
+    <component :is="currentView" :key="viewKey" />
+
+    <template #fallback> Loading... </template>
+  </Suspense>
+</template>
+```
+
+## Pending State Only Re-triggers on Root Replacement
+
+Once resolved, Suspense only re-enters pending when the root node of the default slot changes. If async work happens deeper in the tree, no fallback appears.
+
+**BAD:**
+
+```vue
+<template>
+  <Suspense>
+    <TabContainer>
+      <AsyncDashboard v-if="tab === 'dashboard'" />
+      <AsyncSettings v-else />
+    </TabContainer>
+
+    <template #fallback> Loading... </template>
+  </Suspense>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <Suspense>
+    <component :is="tabs[tab]" :key="tab" />
+
+    <template #fallback> Loading... </template>
+  </Suspense>
+</template>
+```
+
+## Use `suspensible` for Nested Suspense (Vue 3.3+)
+
+Nested Suspense boundaries need `suspensible` on the inner boundary so the parent can coordinate loading state. Without it, inner async content may render empty nodes until resolved.
+
+**BAD:**
+
+```vue
+<template>
+  <Suspense>
+    <LayoutShell>
+      <Suspense>
+        <AsyncWidget />
+        <template #fallback> Loading widget... </template>
+      </Suspense>
+    </LayoutShell>
+
+    <template #fallback> Loading layout... </template>
+  </Suspense>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <Suspense>
+    <LayoutShell>
+      <Suspense suspensible>
+        <AsyncWidget />
+        <template #fallback> Loading widget... </template>
+      </Suspense>
+    </LayoutShell>
+
+    <template #fallback> Loading layout... </template>
+  </Suspense>
+</template>
+```
+
+## Track Loading with Suspense Events
+
+Use `@pending`, `@resolve`, and `@fallback` for analytics, global loading indicators, or coordinating UI outside the Suspense boundary.
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const isLoading = ref(false)
+
+function onPending() {
+  isLoading.value = true
+}
+
+function onResolve() {
+  isLoading.value = false
+}
+</script>
+
+<template>
+  <LoadingBar v-if="isLoading" />
+
+  <Suspense @pending="onPending" @resolve="onResolve">
+    <AsyncPage />
+    <template #fallback>
+      <PageSkeleton />
+    </template>
+  </Suspense>
+</template>
+```
+
+## Recommended Nesting with RouterView, Transition, KeepAlive
+
+When combining these components, the nesting order should be `RouterView` -> `Transition` -> `KeepAlive` -> `Suspense` so each wrapper works correctly.
+
+**BAD:**
+
+```vue
+<template>
+  <RouterView v-slot="{ Component }">
+    <Suspense>
+      <KeepAlive>
+        <Transition mode="out-in">
+          <component :is="Component" />
+        </Transition>
+      </KeepAlive>
+    </Suspense>
+  </RouterView>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <RouterView v-slot="{ Component }">
+    <Transition mode="out-in">
+      <KeepAlive>
+        <Suspense>
+          <component :is="Component" />
+          <template #fallback> Loading... </template>
+        </Suspense>
+      </KeepAlive>
+    </Transition>
+  </RouterView>
+</template>
+```
+
+## Treat Suspense Cautiously in Production
+
+In production code, keep Suspense boundaries minimal, document where they are used, and have a fallback loading strategy if you ever need to replace or refactor them.

package/templates/harness/full/.claude/skills/vue-best-practices/references/component-teleport.md

@@ -0,0 +1,110 @@
+---
+title: Teleport Component Best Practices
+impact: MEDIUM
+impactDescription: Teleport renders content outside the component's DOM position, which is essential for overlays but affects styling and layout
+type: best-practice
+tags: [vue3, teleport, modal, overlay, positioning, responsive]
+---
+
+# Teleport Component Best Practices
+
+**Impact: MEDIUM** - `<Teleport>` renders part of a component's template in a different place in the DOM while preserving the Vue component hierarchy. Use it for overlays (modals, toasts, tooltips) or any UI that must escape stacking contexts, overflow, or fixed positioning constraints.
+
+## Task List
+
+- Teleport overlays to `body` or a dedicated container outside the app root
+- Keep a shared target for similar UI (`#modals`, `#notifications`) and control layering with order or z-index
+- Use `:disabled` for responsive layouts that should render inline on small screens
+- Remember props, emits, and provide/inject still work through teleport
+- Avoid relying on parent stacking contexts or transforms for teleported UI
+
+## Teleport Overlays Out of Transformed Containers
+
+When an ancestor has `transform`, `filter`, or `perspective`, fixed-position overlays can behave like they are locally positioned. Teleport escapes that context.
+
+**BAD:**
+
+```vue
+<template>
+  <div class="animated-container">
+    <button @click="open = true">Open</button>
+
+    <!-- Broken: fixed positioning is scoped to the transformed parent -->
+    <div v-if="open" class="modal">Modal</div>
+  </div>
+</template>
+
+<style>
+.animated-container {
+  transform: translateZ(0);
+}
+
+.modal {
+  position: fixed;
+  inset: 0;
+  z-index: 9999;
+}
+</style>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <div class="animated-container">
+    <button @click="open = true">Open</button>
+
+    <Teleport to="body">
+      <div v-if="open" class="modal">Modal</div>
+    </Teleport>
+  </div>
+</template>
+```
+
+## Responsive Layouts with `disabled`
+
+Use `:disabled` to render inline on mobile and teleport on larger screens:
+
+```vue
+<script setup>
+import { useMediaQuery } from '@vueuse/core'
+
+const isMobile = useMediaQuery('(max-width: 768px)')
+</script>
+
+<template>
+  <Teleport to="body" :disabled="isMobile">
+    <nav class="sidebar">Navigation</nav>
+  </Teleport>
+</template>
+```
+
+## Logical Hierarchy Is Preserved
+
+Teleport changes DOM position, not the Vue component tree. Props, emits, slots, and provide/inject still work:
+
+```vue
+<template>
+  <Teleport to="body">
+    <ChildPanel :message="message" @close="open = false" />
+  </Teleport>
+</template>
+```
+
+## Multiple Teleports to the Same Target
+
+Teleports to the same target append in declaration order:
+
+```vue
+<template>
+  <Teleport to="#notifications">
+    <div>First</div>
+  </Teleport>
+
+  <Teleport to="#notifications">
+    <div>Second</div>
+  </Teleport>
+</template>
+```
+
+Use a shared container to keep stacking predictable, and apply z-index only when you need explicit layering.