Missing Vue Terms — AI Knowledge Base (Gap Analysis)

Purpose: This document is an input for an AI generation pass. It lists the terms that are used in the existing 07-vue/ prose but never defined as their own term, the terms the index promised but never delivered, and the terms a learner needs to reach "hero"/mastery that the curriculum never introduces — plus the relationships each missing term has to other missing terms and to existing terms. Every row is pre-shaped to drop directly into the curriculum's 8-section term template (Prerequisites → Category → Environment → Explanation → Common Mistakes → Exercises → Related Terms → Key Takeaways).

Scope reviewed: 50 existing term files across terms/level_01 … terms/level_10, plus _meta/vue_terms_zero_to_hero.md and _meta/technology_context.md.

Method: (1) Diffed the index's declared filenames against the files on disk — there are four promised-but-missing files, four delivered-but-unindexed files, and one filename typo (Section 0). (2) grep-scanned the corpus for concepts that appear in prose/code but have no term file, counting how many files lean on each, to prioritize by blast radius. No broken ../level_XX/*.md links exist, so "missing" means index divergence and conceptual gaps, not dangling references.

---

0. Structural findings the generating AI must know first

Finding 1 — The index diverges from the files at Levels 9 & 10 (reconcile first).

A filename diff of _meta/vue_terms_zero_to_hero.md against terms/ shows three separate issues:

The file headers already use the correct level titles (Level 9 = "Server-Side Rendering (SSR) & Nuxt", Level 10 = "Tooling & Build Step"); it's the index that's stale. Reconcile by adopting the on-disk files and adding the three 📌 terms.

Exact index rewrite the generating AI must apply to _meta/vue_terms_zero_to_hero.md (Levels 1–8 are already correct and unchanged):

## Level 9: Server-Side Rendering (SSR) & Nuxt
41. Client-Side Rendering (CSR)   (csr.md)
42. Server-Side Rendering (SSR)   (ssr.md)
43. Hydration (Vue)               (hydration.md)
44. Universal Code                (universal_code.md)
45. Nuxt.js                       (nuxt.md)
     + NEW: Static Site Generation (SSG)  (ssg.md)   ← 📌 generate

## Level 10: Tooling & Build Step
46. The Build Step                (build_step.md)
47. Vite                          (vite.md)
48. Vue CLI (legacy)              (vue_cli.md)
49. Vue DevTools                  (vue_devtools.md)
50. Vue Test Utils                (vue_test_utils.md)
     + NEW: VueUse                (vueuse.md)         ← 📌 generate
     + NEW: Transitions & Animations (transition.md)  ← 📌 generate

This makes the index match the 50 existing files and folds the 3 promised terms back in as honest, additive gaps.

Finding 2 — No missing_* deliverable or _meta/missing_terms.md tracker exists yet.

When these terms are generated, create _meta/missing_terms.md to record them, mirroring the 03-javascript/05-nodejs tracker convention.

---

1. Critical gaps — concepts used in existing prose but never defined

These block comprehension the most because existing terms depend on them in prose/code.

---

2. Missing terms by level

Each row: Proposed Term | description | Category | Prerequisites | Related. Categories follow technology_context.md guidance — Vue Core Concept, Directive, Vue Reactivity API, Component Pattern, Ecosystem Tool (plus Rendering Mechanic where the engine is the subject). Environments use the KB's set — Client-Side, Server-Side, Build-Time, Universal, or Composition API (<script setup>). 🆕 = used-but-undefined · 📌 = promised by index, never written · ➕ = absent but needed for mastery.

Level 2 — Reactivity System (fix the destructuring cliff)

Level 3 — Directives (the biggest hole in the curriculum)

Level 4 — Components & Props (formalize the syntax everyone already uses)

Level 5 — Advanced Component Architecture (async UX)

Level 6 — Routing (the everyday router API)

Level 9 — SSR & Nuxt (the promised rendering strategy)

Level 10 — Tooling & Build Step (the promised ecosystem + testing depth)

---

3. Relationship map (dependency graph)

Notation: A → B means "A requires / builds on B". Bold = existing term; plain = missing.

Cluster 1 — The reactivity system (deepens Level 2)

**reactive** → toRefs / toRef   (the fix for the destructuring trap)
**ref** → shallowRef / markRaw  (escape hatches)
**Watchers** → watchEffect
**Proxy Reactivity** → toRefs   (explains *why* destructuring breaks tracking)

Cluster 2 — Directives & the template (deepens Level 3, the biggest hole)

**Directives** → v-for (List Rendering) & :key → **Virtual DOM** (diffing needs keys)
**Directives** → Event, Key & Form Modifiers → **v-on** / **v-model**
**Directives** → Custom Directives → **Component Lifecycle**
v-for & :key → **v-memo** / **v-once**   (list-level optimization)

Cluster 3 — Component authoring syntax (deepens Level 4)

**Composition API** → <script setup> & Compiler Macros
                        ├─→ **Props** (defineProps)
                        ├─→ **Emitting Events** (defineEmits)
                        └─→ defineModel / defineExpose
**Components** → Dynamic Components (<component :is>) → **KeepAlive** / **Async Components**
**Components** → Fallthrough Attributes ($attrs)
Reactive State → nextTick   (await the DOM flush)

Cluster 4 — Async & advanced architecture (Level 5)

**Async Components** → <Suspense> → **Teleport** (overlay UX)
<Suspense> → **Hydration**   (SSR async boundaries)

Cluster 5 — Routing in practice (Level 6)

**Vue Router** → Programmatic Navigation (useRouter / useRoute)
**Dynamic Routing** → Route Params, Query & Meta → **Navigation Guards**

Cluster 6 — Rendering strategies & tooling (Levels 9–10)

**CSR** / **SSR** → Static Site Generation (SSG) → **Nuxt.js** → **Hydration**
**Composables** → VueUse
**v-if/show** + v-for → Transitions & Animations (<Transition>/<TransitionGroup>)
**Vue Test Utils** → Vitest → **Build Step** / **Vite**
<script setup> & Macros → TypeScript with Vue

---

4. Suggested generation priority

---

5. Notes for the generating AI

1. Follow the existing 8-section template exactly (see terms/level_02/ref.md and terms/level_03/directives.md): Prerequisites → Term Category → Environment Context → Explanation (1. Design Motivation / 2. How it works under the hood / 3. Real-world application & trade-offs) → Common Mistakes & Pitfalls (with a "Golden Rule") → Practice Exercises (with a <details> hint block) → Related Terms → Key Takeaways.
2. Obey _meta/technology_context.md: Senior Frontend Architect persona — pragmatic, performance-oriented, "magic is just well-hidden machinery." Emphasize Vue 3 + Composition API + <script setup>; briefly acknowledge the Options API for Vue 2 transitioners but assert Composition API is the future. Explicitly contrast Vue's Proxy-based reactivity ("state tracks its own dependencies") with React's re-render model. Treat Vite and Pinia as the modern standards (Vue CLI/Vuex are legacy). Praise SFCs and standard HTML/CSS over JSX.
3. Use the KB's Category vocabulary — Vue Core Concept, Directive, Vue Reactivity API, Component Pattern, Ecosystem Tool (Section 2 assigns one per term). Environment must be one of Client-Side, Server-Side, Build-Time, Universal, or Composition API (<script setup>).
4. Reconcile the index first (Section 0, Finding 1). Apply the exact Level 9–10 rewrite: fix the nuxtjs.md→nuxt.md typo, add the three unindexed files, and add the three 📌 terms. Levels 1–8 are already correct — do not touch them.
5. Code style must match technology_context.md: all examples in Vue 3 <script setup>; use ref/reactive correctly (remember .value in script, auto-unwrap in template); specify the language on every code block (vue, javascript, html).
6. Wire cross-links using the relative format ../level_XX/<file>.md, matching the Prerequisites/Related columns in Section 2. Every new term must be reachable from at least one existing term (add it to that term's Related section too) — e.g. add v-for to directives.md and virtual_dom.md Related lists.
7. Renumber consistently. Existing terms use # Term #N: headers numbered 1–50. Decide whether new terms append after #50 or adopt level-relative numbering, and apply it uniformly; when you insert a term mid-curriculum (e.g. v-for into Level 3), update the index and downstream numbers together.
8. Create _meta/missing_terms.md (it does not exist here yet) and record each generated term, mirroring the tracker convention in the other knowledge bases.
9. Marker meaning: 🆕 = used-but-undefined in existing prose/code (highest priority — closes holes in what's already taught, e.g. v-for). 📌 = the index promised a file that was never written (SSG, VueUse, Transitions). ➕ = absent but needed for mastery (not yet referenced). Generate in the Section 4 priority order.