@gallopsystems/agent-skills 1.4.0 → 1.6.0

package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: vue-nuxt
+description: Author Vue 3 components inside a Nuxt 4 app. Covers Nuxt auto-import rules, component authoring (props/emits/withDefaults/generics), v-model/defineModel, reactivity, when watch is a code smell, and Vue-shaped template idioms.
+---
+
+# Vue-in-Nuxt component authoring
+
+Patterns for writing Vue 3 `<script setup>` components inside a Nuxt 4 app. This
+is the **frontend authoring** slice — the data layer (`useFetch`/`$fetch`, SSR
+storage, hydration, `definePageMeta`/auth, formatters) lives in the
+`nuxt-nitro-api` skill; Volt/PrimeVue styling and dark mode live in
+`volt-primevue`. This skill cross-links to those rather than restating them.
+
+## When to Use This Skill
+
+- Authoring or reviewing a `.vue` component in a Nuxt 4 project
+- Deciding how a component is named / auto-imported
+- Typing props & emits, defaulting props, building a generic component
+- Wiring `v-model` on a component
+- Designing a component's content API — props vs slots, named/scoped slots
+- Authoring a composable — argument shape, what to return, cleanup
+- Anything reactivity-shaped: `computed` vs `watch`, prop→state sync, DOM measurement
+- You see `watch` and want to know if it should be something else
+
+## Reference Files
+
+- [auto-imports.md](./auto-imports.md) — what auto-imports (components with dir-prefix names, composables, utils, Vue/Nuxt APIs) and what does NOT (third-party, types, test files)
+- [component-authoring.md](./component-authoring.md) — type-only `defineProps`/`defineEmits`, `withDefaults`, the Boolean-prop trap, factory defaults, generic components, `defineExpose`, what to extract into a shared component
+- [v-model.md](./v-model.md) — `defineModel` vs the props+emit+computed proxy, named models, paired fields
+- [slots.md](./slots.md) — slots vs props for markup, named/scoped slots, `defineSlots`/`useSlots`, avoiding empty wrappers, forwarding, slot transitions
+- [composables.md](./composables.md) — `MaybeRefOrGetter`/`toValue` argument contract, return refs not `reactive()`, thin pure-core shell, `onScopeDispose`/`effectScope` cleanup
+- [reactivity.md](./reactivity.md) — `ref` over `reactive`, `useTemplateRef`, pure computeds, mutate-don't-reassign, DOM-measure + `ResizeObserver`, `shallowRef`, watch-getter prop sync, `:key` remount, listener cleanup
+- [watch.md](./watch.md) — **`watch` is the escape hatch, not the default**: when it's right, and the four smell shapes (with refactors) found auditing 159 real watchers
+- [template-idioms.md](./template-idioms.md) — duplicate-`@keyup` TS error, `:deep()`/`:slotted()`/`:global()`, click-outside marker class, `NuxtLink`/thin `app.vue`, `useHead`, `v-bind` shorthand, `useId`, `<Teleport>`/`<KeepAlive>`, `v-memo`/`v-once`, file-input reset
+
+## Core Principles
+
+1. **Lean on auto-imports.** `app/components`, `app/composables`, `app/utils`, and the Vue/Nuxt APIs all auto-import. Add an explicit `import` only for third-party symbols and TS types. A nested component's tag carries its directory as a prefix (`components/customers/ProfileCard.vue` → `<CustomersProfileCard>`).
+2. **Type props/emits, default the booleans.** Use the type-only macros (`defineProps<{...}>()`, `defineEmits<{...}>()`). A bare `boolean` prop coerces to `false` when absent (not `undefined`), so any "defaults-on" flag MUST be defaulted — via reactive destructure (`{ flag = true } = defineProps<…>()`, the 3.5 default, no factory needed for arrays/objects) or `withDefaults` (factory required for non-primitives).
+3. **`computed` for derivation, `watch` for escaping the graph.** If a watcher body just assigns one reactive value from others, it's a `computed`. Need to write a value back? A `computed` can have a setter — reach for a writable `computed` or `defineModel` before a sync watcher. Keep computed getters pure (no fetch, no mutation, no DOM).
+4. **Tie effects to lifecycle.** DOM measurement, listeners, observers, and timers go in `onMounted` and are torn down in `onUnmounted`. A computed reading live DOM geometry needs an explicit re-measure signal (DOM size isn't reactive).
+5. **Call composables at the top of `<script setup>`** — never inside a callback or a template expression (both lose Nuxt's request scope). Derive display state with `computed`, guarding for possibly-null data.
+6. **Defer to the right skill.** Fetch/SSR/auth/middleware → `nuxt-nitro-api`. Volt components, `pt:` styling, color tokens, dark mode → `volt-primevue`. Don't duplicate them here.
+
+## Contributing Back
+
+If you hit a Vue-in-Nuxt authoring gotcha this skill doesn't cover (or one it gets
+wrong), upstream it — run `/contribute-skill`.

package/plugins/vue-nuxt/skills/vue-nuxt/auto-imports.md

@@ -0,0 +1,48 @@
+# Nuxt auto-imports
+
+Nuxt auto-imports your own UI surface and the Vue/Nuxt APIs. Add an explicit
+`import` only for third-party symbols and TypeScript types. Knowing exactly what
+resolves — and how component tags are named — prevents the silent "renders
+nothing" failures.
+
+## Components: the tag carries the directory prefix
+
+Files in `app/components` auto-import with **no manual import**. A nested
+component's tag is the PascalCased **directory path prefixed onto** the
+PascalCased filename:
+
+| File | Tag |
+|---|---|
+| `app/components/AppHeader.vue` | `<AppHeader>` |
+| `app/components/customers/ProfileCard.vue` | `<CustomersProfileCard>` |
+| `app/components/form/FileUpload.vue` | `<FormFileUpload>` |
+| `app/components/settings/Sidebar.vue` | `<SettingsSidebar>` |
+
+- **Name to avoid stutter.** Put `ProfileCard.vue` in `customers/` → `<CustomersProfileCard>`, not `CustomerProfileCard.vue` → `<CustomersCustomerProfileCard>`.
+- **Guessing the bare filename fails silently.** `<FileUpload>` for `form/FileUpload.vue` resolves to nothing — no error, just an unrendered tag. If a component "isn't showing up," check the prefix first.
+- **Want a clean unprefixed tag?** Either explicitly import it
+  (`import EstimateHeader from '~/components/estimates/EstimateHeader.vue'`), or
+  register a directory with a prefix in `nuxt.config` (`components: [{ path: '../src/volt', prefix: 'Volt' }]` → `<VoltButton>`).
+
+## What auto-imports (no `import` line)
+
+- **Vue reactivity & lifecycle:** `ref`, `shallowRef`, `reactive`, `computed`, `watch`, `watchEffect`, `onWatcherCleanup`, `toValue`/`toRef`/`toRefs`, `useTemplateRef`, `useId`, `effectScope`/`onScopeDispose`, `onMounted`, `onBeforeUnmount`/`onUnmounted`, `nextTick`, `defineProps`/`defineEmits`/`defineModel`/`withDefaults`/`defineOptions`, `resolveComponent`.
+- **Nuxt helpers:** `useRoute`, `useRouter`, `navigateTo`, `useFetch`, `$fetch`, `useAsyncData`, `useState`, `useCookie`, `useRuntimeConfig`, `useHead`, `definePageMeta`, `useNuxtApp`.
+- **Your `app/composables`** (`useFoo`) and **`app/utils`** (pure helpers, by bare name) — app-wide.
+- **`<NuxtLink>`, `<NuxtPage>`, `<NuxtLayout>`, `<ClientOnly>`, `<Teleport>`** in templates.
+
+Reach for `#imports` (`import { useFoo } from '#imports'`) only to disambiguate a
+naming collision.
+
+## What does NOT auto-import (import explicitly)
+
+- **Third-party composables/components:** `useToast` from `'primevue/usetoast'`, `Column` from `'primevue/column'`, `date-fns` helpers, etc.
+- **TypeScript types** — interfaces, enums, type aliases are never auto-imported. `import type { Foo } from '...'`.
+- **`server/utils`** — auto-imported on the *server* only, never into client code.
+- **Vitest unit tests** — plain `*.test.ts` files do NOT get Nuxt's auto-import context. Import the composable/util under test explicitly: `import { useFormatters } from './useFormatters'`. (Component tests via `@nuxt/test-utils/runtime` + `mountSuspended` DO have the context — see the `nitro-testing` skill.)
+
+## Consistency caveat
+
+Some repos still write explicit `import { ref } from 'vue'` everywhere. **Match
+the file you're editing** — but the default for new code is to rely on
+auto-import.

package/plugins/vue-nuxt/skills/vue-nuxt/component-authoring.md

@@ -0,0 +1,159 @@
+# Component authoring
+
+Type-only macros, props/emits, the Boolean trap, generics, and what to extract.
+
+## Props & emits: type-only macros
+
+Declare props and emits with the type-only generic form; emit payloads as named
+tuple types:
+
+```ts
+const props = defineProps<{ label: string; size?: 'sm' | 'md'; rows: Row[] }>()
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+  saved: []
+  rowClick: [row: Row]
+}>()
+```
+
+Use the runtime/object form only when you need `withDefaults`.
+
+### Forward many props / handlers at once
+
+Spread a whole object of props with `v-bind="obj"`, or a map of handlers with
+`v-on="handlers"`, instead of listing each:
+
+```vue
+<UserCard v-bind="user" v-on="cardHandlers" />
+<!-- equivalent to :name="user.name" :email="user.email" … @edit="…" @delete="…" -->
+```
+
+Handy for forwarding `$attrs`/`$props` straight through a thin wrapper component
+(`<Inner v-bind="$attrs" />`). Be deliberate, though — spreading a large object
+binds *every* key, which can pass props the child didn't ask for.
+
+When you forward `$attrs` onto a specific inner element, set `inheritAttrs: false`
+via **`defineOptions`** so Vue doesn't *also* dump them on the root — the only
+`<script setup>`-native way to set component options (`name`, `inheritAttrs`):
+
+```ts
+defineOptions({ inheritAttrs: false })
+// then: <input v-bind="$attrs" />   — attrs land only where you put them
+```
+
+## Defaulting props: reactive destructure (3.5) vs `withDefaults`
+
+As of Vue 3.5, you can **destructure** `defineProps` and give defaults with `=`.
+The compiler rewrites each reference back to `props.x`, so reactivity is
+preserved, and — unlike `withDefaults` — **non-primitive defaults need no
+factory**. This is now the idiomatic way to default props:
+
+```ts
+const { responsive = true, size = 'md', items = [] } = defineProps<{
+  responsive?: boolean; size?: 'sm' | 'md'; items?: Item[]
+}>()
+// items = [] is safe here — no shared-reference leak, no factory needed
+```
+
+One gotcha: passing a destructured prop into a `watch` source or a standalone
+function **snapshots** it (you destructured a value, not a ref), losing
+reactivity. Wrap it in a getter:
+
+```ts
+watch(() => responsive, onChange)   // ✅   watch(responsive, …) ❌ passes a bool, never re-fires
+```
+
+`withDefaults(defineProps<…>(), {…})` remains correct and is what you'll see in
+existing code — match the file you're in. The two sections below describe the
+traps `withDefaults` has that destructure defaults sidestep.
+
+## The Boolean prop trap (the most-cited authoring gotcha)
+
+A bare `boolean` prop is subject to Vue's **Boolean casting**: when the attribute
+is absent it coerces to **`false`**, not `undefined`. So `props.flag ?? true`
+never sees `undefined`, and a "defaults-on" flag silently stays off.
+
+```ts
+// ❌ absent → false → feature silently disabled (typechecks fine)
+const props = defineProps<{ responsive?: boolean }>()
+const on = props.responsive !== false // always false when not passed
+
+// ✅ default it explicitly
+const props = withDefaults(defineProps<{ responsive?: boolean }>(), { responsive: true })
+```
+
+Any boolean that should default **on** MUST be defaulted explicitly — via
+destructure (`const { responsive = true } = defineProps<…>()`) or `withDefaults`
+— or be inverted to an opt-*out* flag that naturally defaults `false`. (The
+Boolean casting still happens; the default just gives the absent case a value.)
+
+## Factory defaults for arrays/objects
+
+Non-primitive defaults need a **factory** in `withDefaults`, or every instance
+shares one object:
+
+```ts
+withDefaults(defineProps<{ items?: Item[]; config?: Cfg }>(), {
+  items: () => [],          // ✅ factory
+  config: () => ({ x: 1 }), // ✅ factory
+})
+// ❌ { items: [] } — one array shared across all instances, leaks state
+```
+
+Bare literals are only safe for primitives (`isAdmin: false`, `size: 'md'`). This
+factory requirement is a `withDefaults`-ism — reactive destructure defaults
+(`{ items = [] } = defineProps(…)`) take a plain literal safely.
+
+## Generic components
+
+Declare the type param in the tag and thread it through props/emits so a
+tabs/select preserves the caller's literal union instead of widening to `string`:
+
+```vue
+<script setup lang="ts" generic="T extends string">
+const props = defineProps<{ modelValue: T; options: readonly { value: T; label: string }[] }>()
+const emit = defineEmits<{ 'update:modelValue': [value: T] }>()
+</script>
+```
+
+## `defineExpose` — the sanctioned imperative escape hatch
+
+Expose child methods for a parent to call (reset a form after save, trigger
+submit from a dialog footer) instead of prop hacks:
+
+```ts
+defineExpose({ reset, submit })
+// parent: const child = useTemplateRef('child'); child.value?.reset()
+```
+
+## What to put in a shared component vs leave in the caller
+
+When extracting, a **composable shares logic-only**; a **component shares
+markup + logic**. Extract only the genuinely universal surface and leave
+page-specific chrome in each caller. E.g. a reusable `<Dropzone>` owns the
+drag/drop box and file handling; the page keeps its own heading, helper banner,
+and "or paste text" affordance. If you find yourself adding props just to toggle
+caller-specific chrome inside the shared component, that chrome belongs in the
+caller.
+
+## Type off the server contract, don't hand-write DTOs
+
+Derive prop/state types from the data you fetch rather than redeclaring an
+interface that drifts from the API:
+
+```ts
+// from a fetch ref:
+type Project = NonNullable<typeof projects.value>[number]
+// or an endpoint-response helper indexing the generated InternalApi (illustrative —
+// the general rule is "derive from the endpoint type, never hand-write the DTO";
+// see nuxt-nitro-api/fetch-patterns.md type-extraction)
+```
+
+## Advanced: config-driven generic shells
+
+A generic table/form shell can take a typed config array
+(`columns: Column[]`, `fields: FormField[]`) whose entries optionally carry a
+`template?: Component` rendered via `<component :is="col.template" v-bind="...">`,
+plus `defineExpose`d imperative methods. Powerful, but it's an advanced pattern —
+reach for it only when several call sites genuinely share the shell, not as a
+default.

package/plugins/vue-nuxt/skills/vue-nuxt/composables.md

@@ -0,0 +1,95 @@
+# Authoring a composable
+
+How to *write* a composable's reactive surface. The **decision** of composable vs
+plain util lives in `nuxt-nitro-api/composables-utils.md` (logic that touches Vue
+reactivity/lifecycle → composable; pure transform → util). This file is the
+Vue-shaped mechanics: argument shape, what to return, and cleanup.
+
+## Accept ref-or-getter-or-value; normalize with `toValue`
+
+A reactive input should accept a plain value, a `ref`, **or** a getter — typed
+`MaybeRefOrGetter<T>` and read through `toValue()` inside the effect. Don't branch
+on `isRef`/`unref`, and don't read `.value` once at the top (that snapshots and
+loses reactivity):
+
+```ts
+import { toValue, type MaybeRefOrGetter } from 'vue'
+
+export function useDoubled(input: MaybeRefOrGetter<number>) {
+  // re-reads through toValue on every recompute → tracks input if it's reactive
+  return computed(() => toValue(input) * 2)   // caller passes 3, ref(3), or () => count.value
+}
+```
+
+`toValue(x)` returns `x` for a plain value, `x.value` for a ref, `x()` for a
+getter. This is the VueUse-shaped contract and the single biggest "make a
+composable ergonomic" move — callers shouldn't have to wrap a literal in `ref()`
+just to call you.
+
+## Return a plain object of refs — not `reactive()`
+
+Return refs/computeds in a **plain object**. A caller destructures the result, and
+a plain object of refs survives destructuring; a `reactive()` return does not (the
+properties detach into plain values). See [reactivity.md](./reactivity.md) for the
+`ref`-over-`reactive` rule this mirrors.
+
+```ts
+export function usePager(total: MaybeRefOrGetter<number>) {
+  const page = ref(1)
+  const atEnd = computed(() => page.value >= toValue(total))
+  return { page, atEnd }            // ✅ const { page } = usePager(n) stays reactive
+  // ❌ return reactive({ page, atEnd })  → const { page } = … is a dead number
+}
+```
+
+## Thin composable: pure core, reactive shell
+
+Keep business logic in plain functions (no Vue import — trivially unit-testable,
+no Nuxt context needed) and let the composable be a thin reactive wrapper that
+wires that logic to `ref`/`computed`. This is "functional core, imperative shell"
+applied to composables, and it matters here specifically: plain `*.test.ts` files
+**don't** get Nuxt's auto-import context (see [auto-imports.md](./auto-imports.md)),
+so pure functions test without `mountSuspended`.
+
+```ts
+// core.ts — pure, no Vue, unit-test directly
+export const clampPage = (p: number, total: number) => Math.min(Math.max(p, 1), total)
+
+// usePager.ts — thin shell
+export function usePager(total: MaybeRefOrGetter<number>) {
+  const page = ref(1)
+  return { page, go: (p: number) => (page.value = clampPage(p, toValue(total))) }
+}
+```
+
+## Clean up with `onScopeDispose` — not only `onUnmounted`
+
+A composable that starts a listener/timer/observer must tear it down. Inside a
+composable, register cleanup with **`onScopeDispose`** rather than `onUnmounted`:
+it fires on component unmount too, but *also* works when the composable runs in a
+detached `effectScope()` (a shared singleton, a manually-stopped scope) where
+there's no component instance and `onUnmounted` would silently no-op.
+
+```ts
+export function useNow(intervalMs = 1000) {
+  const now = ref(Date.now())
+  const id = setInterval(() => (now.value = Date.now()), intervalMs)
+  onScopeDispose(() => clearInterval(id))   // fires on unmount OR scope.stop()
+  return { now }
+}
+```
+
+For a composable that itself creates watchers/computeds you want to dispose as a
+unit (a store you stand up and tear down by hand), wrap them in an
+**`effectScope()`** and stop the whole scope at once:
+
+```ts
+const scope = effectScope()
+scope.run(() => { /* watchers/computeds created here */ })
+// later: scope.stop()  → disposes every effect created inside, and runs onScopeDispose
+```
+
+`useTemplateRef`, `MaybeRefOrGetter`, and the "return refs" rule together let a
+composable own DOM refs and reactive inputs internally instead of demanding the
+caller thread them in — see [reactivity.md](./reactivity.md) and
+[component-authoring.md](./component-authoring.md).

package/plugins/vue-nuxt/skills/vue-nuxt/reactivity.md

@@ -0,0 +1,133 @@
+# Reactivity gotchas
+
+Derivation, prop sync, DOM measurement, remounting, and cleanup. For the
+`watch`-vs-`computed` decision and the `watch` smell catalog, see
+[watch.md](./watch.md).
+
+## Keep computed getters pure
+
+A `computed` getter derives and returns — nothing else. Mutating another ref/Set,
+firing an async request, or touching the DOM inside a getter makes it
+order-dependent, can re-trigger itself, and is undebuggable. Move side effects to
+a `watch` or an event handler. (And never mutate a computed's *return* value —
+it's a read-only snapshot; update the source state instead.)
+
+## Mutate a ref's object in place — don't reassign
+
+When a ref's object is bound to `v-model` inputs, update it **in place**;
+reassigning a fresh literal swaps the proxied target the template tracks, and
+later programmatic writes to the old reference are lost:
+
+```ts
+// ❌ form.value = { ...next }      // swaps the tracked proxy
+// ✅
+Object.assign(form.value, next)     // or per-key assignment
+```
+
+## Default to `ref`; reach for `reactive` rarely
+
+`ref` is the default for all state. Use `reactive` only to **group** tightly
+related fields or to wrap a non-Vue object (`Map`/`Set`). `reactive`'s traps are
+why: it loses reactivity when **destructured** (the keys become plain values —
+`toRefs` to recover) and when **reassigned wholesale** (the proxy identity swaps).
+A `ref` has neither problem — `.value` is always the live cell.
+
+```ts
+const state = reactive({ count: 0 })
+const { count } = state          // ❌ plain number now, not reactive
+const { count } = toRefs(state)  // ✅ if you must destructure a reactive
+// Rule: default ref(); reactive() only to group state or wrap Map/Set.
+```
+
+## Template refs: prefer `useTemplateRef`
+
+To reach a DOM element or child component, use **`useTemplateRef('name')`** (Vue
+3.5 / Nuxt 4) — pass the string that matches `ref="name"` in the template. It
+self-documents that the value is an element/component handle, infers the type, and
+lets a composable own the ref internally. The legacy "declare `const el =
+ref(null)` whose variable name must match `ref="el"`" form still works but is
+fragile to rename drift — prefer `useTemplateRef` in new code.
+
+```ts
+const input = useTemplateRef('input')          // <input ref="input">
+onMounted(() => input.value?.focus())
+// v-for: useTemplateRef returns an ARRAY, and its order is NOT guaranteed —
+// key/sort yourself rather than trusting index alignment.
+```
+
+## DOM-measured computeds need a re-measure signal
+
+DOM size isn't reactive, so a `computed` reading live geometry
+(`offsetLeft`/`offsetWidth`) won't recompute on resize or a breakpoint flip. Add
+an explicit version ref and bump it from a `ResizeObserver`:
+
+```ts
+const container = useTemplateRef('container')   // <div ref="container">
+const layoutVersion = ref(0)
+let ro: ResizeObserver | null = null
+onMounted(() => { ro = new ResizeObserver(() => layoutVersion.value++); ro.observe(container.value!) })
+onBeforeUnmount(() => ro?.disconnect())
+
+const indicator = computed(() => {
+  void layoutVersion.value          // subscribe to re-measure
+  const b = buttons.value[active.value]
+  return b ? { left: `${b.offsetLeft}px`, width: `${b.offsetWidth}px` } : { left: '0px', width: '0px' }
+})
+```
+
+Measure conditionally-mounted elements only **after `await nextTick()`** (and hold
+them via a null-guarded template ref) — right after toggling `visible`, the
+element isn't laid out and a sync `getBoundingClientRect()` reads 0.
+
+## React to prop changes with a watch on a getter
+
+Props aren't directly watchable — watch a getter, and seed local state with
+`{ immediate: true }`:
+
+```ts
+watch(() => props.thing, (next) => { local.value = next }, { immediate: true })
+```
+
+The legitimate prop→local case is **owning an editable draft**: a parent owns
+server data via `useFetch` (keep `refresh`), passes it as a prop; the child clones
+it into a local draft (`structuredClone(toRaw(prop))`), re-syncs on a watch of the
+prop, and emits `@saved`/`@updated` so the parent re-fetches. Copy into local
+state — never mutate the prop. (A bare `local = ref(props.x)` + sync watch with no
+emit-back is the `prop-sync` smell — use `defineModel`; see [v-model.md](./v-model.md).)
+
+## Remount on identity change with `:key`
+
+```vue
+<UserDetail :key="route.params.id" :id="route.params.id" />
+```
+
+Bind `:key` to the **identifying value** so the component remounts cleanly when
+identity changes. Do NOT abuse an incrementing `:key="bump++"` to force a data
+re-pull — that destroys child state/scroll; use a watcher or `refresh()` instead.
+When a *full remount* genuinely is the goal (reset all of a child's internal
+state), bumping `:key` is the right tool — and `$forceUpdate()` is the wrong one
+(it re-renders but skips computeds and bypasses the reactivity graph; if you
+"need" it, you have a reactivity bug to fix instead).
+
+## Always pair setup with teardown
+
+Anything started in `onMounted` — `addEventListener`, `setInterval`,
+`ResizeObserver`, `MutationObserver` — must be torn down in
+`onUnmounted`/`onBeforeUnmount` (`removeEventListener`, `clearInterval`,
+`disconnect`). Keep the handle in a module-scope `let` so teardown can reach it.
+Inside a **composable**, register teardown with `onScopeDispose` instead so it
+also fires for a detached `effectScope` — see [composables.md](./composables.md).
+
+## `shallowRef` for large or wholesale-replaced data
+
+Deep reactivity has a cost: `ref`/`reactive` recursively proxy every nested
+property. For a large list, a third-party class instance (a `Map`, an editor/map
+object you drive imperatively), or data you always **replace wholesale** rather
+than mutate, use `shallowRef` (or `shallowReactive`) — only `.value` reassignment
+triggers, nested mutation does not.
+
+```ts
+const rows = shallowRef<Row[]>([])
+rows.value = [...rows.value, next]   // ✅ replace .value — triggers
+// rows.value.push(next)             // ❌ no trigger under shallowRef (use triggerRef if you must mutate)
+```

package/plugins/vue-nuxt/skills/vue-nuxt/slots.md

@@ -0,0 +1,139 @@
+# Slots & reusability
+
+Slots are how a component accepts **markup** from its caller. Reach for a slot
+whenever a component is a *container* for caller-provided content — cards, panels,
+menus, layouts, list rows, buttons.
+
+## Slots beat props for markup and open-endedness
+
+A prop can carry a string, but not a chunk of markup, and it forces you to
+pre-plan every variant. If a `<Button>` takes `type: 'primary' | 'secondary'`, a
+caller can't add a third look without you editing `Button`. A slot is
+open-ended — the caller passes whatever they need:
+
+```vue
+<!-- ❌ prop must anticipate every case -->
+<Button label="Save" type="primary" />
+<!-- ✅ slot accepts any content -->
+<Button @click="save">Save <Spinner v-if="saving" /></Button>
+```
+
+Rule of thumb: **prop for data, slot for markup.** If you find yourself adding a
+prop just to toggle a bit of caller-specific UI, that UI belongs in a slot.
+
+## Named slots + the `#` shorthand
+
+```vue
+<!-- Card.vue -->
+<template>
+  <article>
+    <header><slot name="header" /></header>
+    <slot />                <!-- default slot -->
+    <footer><slot name="footer" /></footer>
+  </article>
+</template>
+
+<!-- caller -->
+<Card>
+  <template #header><h2>Title</h2></template>   <!-- #header == v-slot:header -->
+  Body content goes in the default slot.
+  <template #footer><Button>OK</Button></template>
+</Card>
+```
+
+## Fallback (default) content
+
+Content between the `<slot>` tags renders when the caller provides nothing:
+
+```vue
+<slot name="empty">No results yet.</slot>
+```
+
+## Scoped slots — the mental model
+
+A scoped slot is **a function the parent supplies that returns markup; the child
+calls it with data.** The child exposes values by binding them on `<slot>`; the
+caller receives them via the slot prop:
+
+```vue
+<!-- List.vue — child owns iteration, caller owns each row's markup -->
+<template>
+  <ul>
+    <li v-for="item in items" :key="item.id">
+      <slot :item="item" :index="index" />   <!-- expose data to the slot -->
+    </li>
+  </ul>
+</template>
+
+<!-- caller -->
+<List :items="invoices">
+  <template #default="{ item }">
+    <strong>{{ item.number }}</strong> — {{ item.total }}
+  </template>
+</List>
+```
+
+This is the core reusability move: the child encapsulates *logic* (fetching,
+iterating, state) while the caller decides *presentation*.
+
+## Typing & inspecting slots (Composition API)
+
+- **Type** the slots a component accepts with `defineSlots` (compile-time only,
+  like `defineProps`):
+
+  ```ts
+  defineSlots<{
+    default(props: { item: Invoice; index: number }): any
+    header(): any
+  }>()
+  ```
+
+- **Inspect** which slots the caller actually passed with `useSlots()` — use it to
+  avoid rendering an empty wrapper:
+
+  ```vue
+  <script setup lang="ts">
+  const slots = useSlots()
+  </script>
+  <template>
+    <!-- only render the styled footer wrapper if a footer slot was given -->
+    <footer v-if="slots.footer" class="border-t p-4"><slot name="footer" /></footer>
+  </template>
+  ```
+
+  (In a template you can also test `$slots.footer` directly.) Without the guard
+  you ship an empty `<footer>` whose padding/border still affects layout.
+
+## Forwarding & splitting slots
+
+- **Forward** a slot through a wrapper so the inner component receives it:
+
+  ```vue
+  <Inner>
+    <template v-for="(_, name) in $slots" #[name]="scope">
+      <slot :name="name" v-bind="scope" />
+    </template>
+  </Inner>
+  ```
+
+- **Split** one incoming slot into two render positions by branching with `v-if`
+  on a condition, each `<slot>` keeping its own fallback.
+
+## Slot transitions need keyed content
+
+Wrapping a `<slot>` in `<Transition>` only animates if the slotted content is
+**keyed**, so Vue can tell one state from the next:
+
+```vue
+<Transition name="fade" mode="out-in">
+  <component :is="current" :key="current" />
+</Transition>
+```
+
+## Reusable ≠ big
+
+Small components are worth extracting too. A three-line `OverflowMenu` that always
+pairs the same trigger icon + a11y wiring is worth a component: every use stays
+identical, and a change happens in one place. Extract the genuinely shared
+surface; leave caller-specific chrome in the caller (see the "what to extract"
+note in [component-authoring.md](./component-authoring.md)).