@pythoughts/vue-skills-mcp 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pythoughts/vue-skills-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "MCP server exposing the Vue 3 best-practice skills so any MCP coding agent can fetch them automatically on Vue work.",
   "author": "Mohamed Elkholy (elkaix)",

package/skills/vue-ai-apps/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: vue-ai-apps
+description: "Building AI/LLM and agent apps with Vue 3 and Nuxt: streaming chat UIs, the Vercel AI SDK (`ai` + `@ai-sdk/vue`), `useChat`, tool calling, structured output, and abort/error handling. Load for AI chatbots, assistant UIs, LLM streaming, or agent frontends in Vue or Nuxt."
+version: "1.0.0"
+license: MIT
+author: github.com/Pythoughts-labs
+---
+
+# Vue AI Apps Workflow
+
+Building the **Vue/Nuxt front end** for LLM and agent features with the Vercel AI SDK. This skill covers the Vue-specific integration; the model layer (`streamText`, `tool`, providers) is shown as shape only — follow the AI SDK docs for the current core API, which moves between minor versions.
+
+Assumes the foundations in `vue-best-practices` (Composition API, `<script setup lang="ts">`, composables). Load that skill for component structure and reactivity.
+
+## Core Principles
+
+- **Keys never reach the client.** The provider API key lives on the server. The browser talks to *your* endpoint, never to the model provider directly.
+- **Server streams, client consumes.** A server route runs `streamText`/`streamObject` and returns a stream; the Vue component renders it incrementally. Never block on the full response.
+- **Render message *parts*, not a content string.** AI SDK v5 messages are `UIMessage[]` made of typed `parts` (text, tool calls, reasoning). Iterate `message.parts`.
+- **Drive UI from `status`, not a boolean.** Disabled inputs, spinners, and the stop button key off the `status` state machine.
+
+## 1) Confirm the stack (required)
+
+- Packages: `ai` (core), `@ai-sdk/vue` (composables), a provider (`@ai-sdk/openai`, `@ai-sdk/anthropic`, …), `zod` for tool/object schemas.
+- `useChat` from `@ai-sdk/vue` works against **any** streaming backend. The server snippets here use **Nuxt/Nitro** (`defineEventHandler`, `readBody`); for a non-Nuxt backend, keep the same AI SDK calls in your own route handler.
+- AI SDK **v5** is assumed (messages have `parts`; the hook does not manage input; `status` replaces `isLoading`; tool schemas use `inputSchema`). If the project is on v4, these APIs differ — check the installed version first.
+
+## 2) Build the streaming chat UI (required for chat features)
+
+- Reference: [streaming-chat-ui](references/streaming-chat-ui.md)
+- Server route streams with `streamText` + `toUIMessageStreamResponse()`.
+- Client: `useChat()` returns Vue refs. Own your own `input` ref; call `sendMessage({ text })`. Render `message.parts`.
+
+## 3) Add capabilities only when the feature needs them
+
+- **Tool calling** (agent actions, function calling) → [tool-calling](references/tool-calling.md)
+- **Structured output** (stream a typed object, not chat) → [structured-output](references/structured-output.md)
+
+## 4) Handle abort and errors (required before shipping)
+
+- Reference: [error-handling-and-abort](references/error-handling-and-abort.md)
+- Wire `stop()`, the `error` ref, and `onError`. A streaming UI without an abort path is not done.
+
+## 5) Final self-check
+
+- Provider key is server-only; no key or provider call in client code.
+- Component renders `message.parts`, not `message.content`.
+- Input is disabled and a stop button shows while `status` is `submitted`/`streaming`.
+- Errors are surfaced to the user and retryable (`clearError()` + `regenerate()`).
+- Tool/object schemas validate input with `zod`.
+- Core AI SDK calls were checked against the installed SDK version, not assumed.

package/skills/vue-ai-apps/references/error-handling-and-abort.md

@@ -0,0 +1,87 @@
+---
+title: Abort and Error Handling for AI Streams (AI SDK v5)
+impact: HIGH
+impactDescription: A streaming UI with no stop button and no error surface leaves users stuck on hung or failed requests
+type: best-practice
+tags: [vue3, nuxt, ai-sdk, useChat, abort, error-handling, streaming]
+---
+
+# Abort and Error Handling for AI Streams (AI SDK v5)
+
+**Impact: HIGH** - LLM streams are long-running and can fail mid-response. `useChat` exposes everything needed — `status`, `stop()`, `error`, `clearError()`, `regenerate()`, and an `onError` option — but none of it is wired up by default. A chat UI is not shippable until the user can stop a runaway generation and recover from an error.
+
+## Task Checklist
+
+- [ ] Show a **Stop** button while `status` is `submitted` or `streaming`, calling `stop()`
+- [ ] Render the `error` ref when present
+- [ ] Offer recovery: `clearError()` then `regenerate()`
+- [ ] Pass `onError` for logging/toasts (never log the provider key or full request)
+- [ ] Disable the send control unless `status === 'ready'`
+
+**Incorrect - no abort, no error surface:**
+```vue
+<script setup lang="ts">
+const { messages, sendMessage } = useChat() // ❌ ignores status/error/stop
+</script>
+<!-- user cannot cancel a long stream and never sees failures -->
+```
+
+**Correct:**
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useChat } from '@ai-sdk/vue'
+
+const input = ref('')
+const { messages, sendMessage, status, error, stop, clearError, regenerate } = useChat({
+  onError(err) {
+    // surface to logging/toast; keep payloads out of logs
+    console.error('chat stream failed:', err.message)
+  },
+})
+
+function send() {
+  const text = input.value.trim()
+  if (!text || status.value !== 'ready') return
+  sendMessage({ text })
+  input.value = ''
+}
+
+function retry() {
+  clearError()
+  regenerate()
+}
+</script>
+
+<template>
+  <!-- messages render here (see streaming-chat-ui) -->
+
+  <div v-if="error" role="alert">
+    Something went wrong: {{ error.message }}
+    <button @click="retry">Retry</button>
+  </div>
+
+  <form @submit.prevent="send">
+    <input v-model="input" :disabled="status !== 'ready'" />
+    <button
+      v-if="status === 'submitted' || status === 'streaming'"
+      type="button"
+      @click="stop"
+    >
+      Stop
+    </button>
+    <button v-else :disabled="status !== 'ready'">Send</button>
+  </form>
+</template>
+```
+
+## Notes
+
+- `stop()` aborts the in-flight request; the partial assistant message stays in `messages`.
+- `regenerate()` (v5; replaces v4 `reload`) re-runs the last user turn — pair with `clearError()` after a failure.
+- `useObject` does not expose `status`; it uses `isLoading` + `error` + `stop()` instead.
+- Surface a friendly message to users; keep raw errors, request bodies, and keys out of client logs.
+
+## Reference
+- [AI SDK — useChat reference](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat)
+- [AI SDK — Chatbot: status & stop](https://ai-sdk.dev/docs/ai-sdk-ui/chatbot)

package/skills/vue-ai-apps/references/streaming-chat-ui.md

@@ -0,0 +1,101 @@
+---
+title: Streaming Chat UI with useChat (AI SDK v5)
+impact: HIGH
+impactDescription: Rendering message.content or managing input inside the hook is the v4 API and silently breaks in v5
+type: capability
+tags: [vue3, nuxt, ai-sdk, useChat, streaming, llm, chat]
+---
+
+# Streaming Chat UI with useChat (AI SDK v5)
+
+**Impact: HIGH** - In AI SDK v5 the Vue `useChat` composable no longer manages the input field, exposes `status` instead of `isLoading`, and returns messages as `UIMessage[]` built from typed `parts`. Code written for v4 (`input`, `handleSubmit`, `message.content`, `isLoading`) compiles but renders nothing useful.
+
+The provider API key must stay on the server. The browser calls your own route; your route calls the model.
+
+## Task Checklist
+
+- [ ] Keep the provider key and `streamText` call in a server route, never in the component
+- [ ] Import `useChat` from `@ai-sdk/vue` (not `@ai-sdk/react`)
+- [ ] Own a local `input` ref; send with `sendMessage({ text })`
+- [ ] Render `message.parts`, branching on `part.type`
+- [ ] Disable the input while `status` is `submitted` or `streaming`
+
+**Incorrect - v4-style usage, broken in v5:**
+```vue
+<script setup lang="ts">
+import { useChat } from '@ai-sdk/vue'
+// ❌ input / handleSubmit / isLoading no longer exist on the hook in v5
+const { messages, input, handleSubmit, isLoading } = useChat()
+</script>
+
+<template>
+  <div v-for="m in messages" :key="m.id">
+    {{ m.content }} <!-- ❌ v5 messages have no `content`; they have `parts` -->
+  </div>
+  <form @submit.prevent="handleSubmit">
+    <input v-model="input" :disabled="isLoading" />
+  </form>
+</template>
+```
+
+**Correct - server route (Nuxt/Nitro), `server/api/chat.ts`:**
+```ts
+import { streamText, convertToModelMessages, type UIMessage } from 'ai'
+import { openai } from '@ai-sdk/openai' // key read from env on the server
+
+export default defineEventHandler(async (event) => {
+  const { messages } = await readBody<{ messages: UIMessage[] }>(event)
+
+  const result = streamText({
+    model: openai('gpt-4o'),
+    messages: convertToModelMessages(messages),
+  })
+
+  // Standard v5 streaming response. (The Nuxt template also shows a
+  // gateway-wrapped form with toUIMessageStream — both are valid.)
+  return result.toUIMessageStreamResponse()
+})
+```
+
+**Correct - component, `pages/index.vue`:**
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useChat } from '@ai-sdk/vue'
+
+const input = ref('')
+const { messages, sendMessage, status } = useChat()
+
+function send() {
+  const text = input.value.trim()
+  if (!text || status.value !== 'ready') return
+  sendMessage({ text })
+  input.value = ''
+}
+</script>
+
+<template>
+  <div v-for="m in messages" :key="m.id">
+    <strong>{{ m.role === 'user' ? 'You' : 'AI' }}:</strong>
+    <template v-for="(part, i) in m.parts" :key="i">
+      <span v-if="part.type === 'text'">{{ part.text }}</span>
+    </template>
+  </div>
+
+  <form @submit.prevent="send">
+    <input v-model="input" :disabled="status !== 'ready'" placeholder="Ask something…" />
+    <button :disabled="status !== 'ready'">Send</button>
+  </form>
+</template>
+```
+
+## Notes
+
+- `useChat` returns Vue refs (`messages.value`, `status.value`); templates unwrap them automatically.
+- `status` values: `'submitted'` (sent, awaiting first token) → `'streaming'` (receiving) → `'ready'` (done) → `'error'`. Treat `submitted` + `streaming` as busy.
+- `sendMessage` also accepts files/attachments and per-call options; `text` is the common case.
+- The core `streamText` signature can change between AI SDK minors — verify against the installed version rather than copying blindly.
+
+## Reference
+- [AI SDK — Nuxt quickstart](https://ai-sdk.dev/docs/getting-started/nuxt)
+- [AI SDK — useChat reference](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat)

package/skills/vue-ai-apps/references/structured-output.md

@@ -0,0 +1,90 @@
+---
+title: Streaming Structured Output in Vue (AI SDK v5)
+impact: MEDIUM
+impactDescription: Use streamObject + useObject for typed data; the object streams in partial, so the UI must tolerate undefined fields
+type: capability
+tags: [vue3, nuxt, ai-sdk, streamObject, useObject, structured-output, zod]
+---
+
+# Streaming Structured Output in Vue (AI SDK v5)
+
+**Impact: MEDIUM** - When the model should return a typed object (a recipe, a form, an extraction) rather than chat, use `streamObject` on the server and the `useObject` composable on the client. The object arrives **incrementally as a deep-partial**, so every field can be `undefined` mid-stream. Templates must guard with optional chaining and `v-if`, or they throw while streaming.
+
+`useObject` uses its own surface (`object`, `submit`, `isLoading`) — it does **not** share `useChat`'s `status`/`sendMessage` API.
+
+## Task Checklist
+
+- [ ] Use `streamObject` server-side with a `zod` `schema`
+- [ ] Return `result.toTextStreamResponse()`
+- [ ] Drive the UI from `useObject`'s `object`, `submit`, `isLoading`
+- [ ] Treat every field of `object` as possibly `undefined` while streaming
+- [ ] Verify the exact `useObject` export name in your installed `@ai-sdk/vue`
+
+**Incorrect - assuming the object is complete:**
+```vue
+<!-- ❌ object and its fields are undefined until the stream fills them -->
+<li v-for="step in object.recipe.steps">{{ step }}</li>
+```
+
+**Correct - server route, `server/api/recipe.ts`:**
+```ts
+import { streamObject } from 'ai'
+import { openai } from '@ai-sdk/openai'
+import { z } from 'zod'
+
+export const recipeSchema = z.object({
+  recipe: z.object({
+    name: z.string(),
+    steps: z.array(z.string()),
+  }),
+})
+
+export default defineEventHandler(async (event) => {
+  const { dish } = await readBody<{ dish: string }>(event)
+
+  const result = streamObject({
+    model: openai('gpt-4o'),
+    schema: recipeSchema,
+    prompt: `Generate a recipe for ${dish}`,
+  })
+
+  return result.toTextStreamResponse()
+})
+```
+
+**Correct - component:**
+```vue
+<script setup lang="ts">
+// Verify the export name against the installed @ai-sdk/vue:
+// it is exposed as `useObject` (cross-framework convention aliases
+// it as `experimental_useObject`).
+import { useObject } from '@ai-sdk/vue'
+import { z } from 'zod'
+
+const schema = z.object({
+  recipe: z.object({ name: z.string(), steps: z.array(z.string()) }),
+})
+
+const { object, submit, isLoading } = useObject({ api: '/api/recipe', schema })
+</script>
+
+<template>
+  <button :disabled="isLoading" @click="submit({ dish: 'pad thai' })">Generate</button>
+
+  <!-- guard every level: partial object during streaming -->
+  <h2 v-if="object?.recipe?.name">{{ object.recipe.name }}</h2>
+  <ol>
+    <li v-for="(step, i) in object?.recipe?.steps ?? []" :key="i">{{ step }}</li>
+  </ol>
+</template>
+```
+
+## Notes
+
+- `useObject` is experimental and available for React, Svelte, and **Vue**. The reference docs page only prints the React import, so confirm the Vue export name (`useObject` vs `experimental_useObject`) in `node_modules/@ai-sdk/vue` for your version.
+- `object` is typed as `DeepPartial<Schema>` — TypeScript already forces the optional-chaining discipline above.
+- For free-form text streaming use `useChat` (or `useCompletion`); reach for `useObject` only when you need a validated shape.
+
+## Reference
+- [AI SDK — useObject reference](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-object)
+- [AI SDK — streamObject](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-object)

package/skills/vue-ai-apps/references/tool-calling.md

@@ -0,0 +1,88 @@
+---
+title: Tool Calling in Vue Chat UIs (AI SDK v5)
+impact: HIGH
+impactDescription: Tool calls arrive as typed message parts with a state machine; ignoring the state renders blank or stale UI
+type: capability
+tags: [vue3, nuxt, ai-sdk, tools, function-calling, agents, useChat]
+---
+
+# Tool Calling in Vue Chat UIs (AI SDK v5)
+
+**Impact: HIGH** - When the model calls a tool, the result surfaces in the chat as a `parts` entry of type `tool-<name>` with a `state` field. The Vue UI must branch on `part.state` (`input-streaming` → `input-available` → `output-available` / `output-error`) to show progress and results. Rendering the part without checking `state` shows nothing while the tool runs, then throws when accessing `part.output` too early.
+
+Multi-step agent loops (call tool → feed result back → answer) require `stopWhen` on the server; without it the model stops after the first tool call.
+
+## Task Checklist
+
+- [ ] Define tools server-side with `tool({ description, inputSchema: z.object(...), execute })`
+- [ ] Use `inputSchema` (v5), not `parameters` (v4)
+- [ ] Allow multiple steps with `stopWhen: stepCountIs(n)` for agent behavior
+- [ ] In the template, branch tool parts on `part.state`
+- [ ] Access `part.input` / `part.output` only in the matching state
+
+**Incorrect - v4 keys + no state handling:**
+```ts
+// ❌ `parameters` and `maxSteps` are v4; renamed in v5
+tool({ parameters: z.object({ city: z.string() }), execute })
+streamText({ /* ... */ tools, maxSteps: 5 })
+```
+```vue
+<!-- ❌ reads output before the tool has produced it -->
+<div v-if="part.type === 'tool-getWeather'">{{ part.output.tempC }}</div>
+```
+
+**Correct - server route, `server/api/chat.ts`:**
+```ts
+import { streamText, tool, convertToModelMessages, stepCountIs, type UIMessage } from 'ai'
+import { openai } from '@ai-sdk/openai'
+import { z } from 'zod'
+
+export default defineEventHandler(async (event) => {
+  const { messages } = await readBody<{ messages: UIMessage[] }>(event)
+
+  const result = streamText({
+    model: openai('gpt-4o'),
+    messages: convertToModelMessages(messages),
+    stopWhen: stepCountIs(5), // let the model use a tool then answer
+    tools: {
+      getWeather: tool({
+        description: 'Get the current weather for a city',
+        inputSchema: z.object({ city: z.string() }),
+        execute: async ({ city }) => ({ city, tempC: 21 }),
+      }),
+    },
+  })
+
+  return result.toUIMessageStreamResponse()
+})
+```
+
+**Correct - rendering the tool part:**
+```vue
+<template v-for="(part, i) in m.parts" :key="i">
+  <span v-if="part.type === 'text'">{{ part.text }}</span>
+
+  <!-- a tool named `getWeather` produces parts of type `tool-getWeather` -->
+  <template v-else-if="part.type === 'tool-getWeather'">
+    <div v-if="part.state === 'input-streaming'">Preparing request…</div>
+    <div v-else-if="part.state === 'input-available'">
+      Fetching weather for {{ part.input.city }}…
+    </div>
+    <div v-else-if="part.state === 'output-available'">
+      {{ part.output.city }}: {{ part.output.tempC }}°C
+    </div>
+    <div v-else-if="part.state === 'output-error'">Error: {{ part.errorText }}</div>
+  </template>
+</template>
+```
+
+## Notes
+
+- Part type follows the pattern `tool-${toolName}`; dynamically registered tools use type `dynamic-tool` with `part.toolName`.
+- Useful accessors: `part.input`, `part.output`, `part.toolCallId`, `part.errorText`.
+- **Client-side tools** (a `tool()` with no `execute`) are fulfilled from the UI by calling `addToolResult({ tool, toolCallId, output })` returned by `useChat`.
+- `stepCountIs` / `stopWhen` and the `tool()` signature are core AI SDK API — confirm against the installed version.
+
+## Reference
+- [AI SDK — Chatbot tool usage](https://ai-sdk.dev/docs/ai-sdk-ui/chatbot-tool-usage)
+- [AI SDK — tool() / stopWhen](https://ai-sdk.dev/docs/reference/ai-sdk-core/step-count-is)

package/skills/vue-best-practices/SKILL.md

@@ -4,7 +4,7 @@ description: MUST be used for Vue.js tasks. Strongly recommends Composition API
 license: MIT
 metadata:
   author: github.com/Pythoughts-labs
-  version: "18.1.0"
+  version: "18.2.0"
 ---
 
 # Vue Best Practices Workflow
@@ -102,6 +102,11 @@ Entry/root and route view rule:
 - Keep composable APIs small, typed, and predictable.
 - Separate feature logic from presentational components.
 
+### Vue 3.5+ APIs (apply on Vue 3.5 or newer)
+
+- Prefer destructure defaults over `withDefaults()`; mind the getter-boundary rule -> [reactive-props-destructure](references/reactive-props-destructure.md)
+- Use 3.5 built-ins before hand-rolling: `useId`, `onWatcherCleanup`, `<Teleport defer>`, lazy hydration -> [vue-3-5-helpers](references/vue-3-5-helpers.md)
+
 ## 3) Consider optional features only when requirements call for them
 
 ### 3.1 Standard optional features
@@ -138,6 +143,8 @@ Performance work is a post-functionality pass. Do not optimize before core behav
 - Over-abstraction in hot list paths -> [perf-avoid-component-abstraction-in-lists](references/perf-avoid-component-abstraction-in-lists.md)
 - Expensive updates triggered too often -> [updated-hook-performance](references/updated-hook-performance.md)
 
+Experimental: a measured rendering hotspot may justify Vapor Mode (Vue 3.6, opt-in, unstable) -> [vapor-mode](references/vapor-mode.md). Do not enable by default.
+
 ## 5) Final self-check before finishing
 
 - Core behavior works and matches requirements.

package/skills/vue-best-practices/references/reactive-props-destructure.md

@@ -0,0 +1,80 @@
+---
+title: Reactive Props Destructure (Vue 3.5+)
+impact: HIGH
+impactDescription: Destructured props lose reactivity when passed across a function boundary, silently breaking watchers and composables
+type: best-practice
+tags: [vue3, vue35, props, defineProps, reactivity, composition-api, withDefaults]
+---
+
+# Reactive Props Destructure (Vue 3.5+)
+
+**Impact: HIGH** - Since Vue 3.5 (stable, on by default), destructuring `defineProps()` keeps reactivity and lets you declare defaults with plain JS syntax — replacing `withDefaults()`. The compiler rewrites each destructured access back to `props.x`. The catch: a destructured prop is only reactive when accessed *inside* a reactive scope (template, `computed`, `watchEffect`). The moment you pass the bare variable **into a function** — `watch(count, …)`, a composable, `toRef(count)` — you pass a snapshot value, and reactivity is lost.
+
+Vue's compiler warns when it detects a destructured prop passed directly into a function call, but the fix must be applied for the code to work.
+
+## Task Checklist
+
+- [ ] Use destructure defaults instead of `withDefaults()` in Vue 3.5+
+- [ ] Access destructured props directly in templates, `computed`, and `watchEffect`
+- [ ] When passing a prop across a function boundary, wrap it in a getter `() => prop`
+- [ ] Watch a destructured prop with `watch(() => prop, …)`, never `watch(prop, …)`
+- [ ] In composables, accept `() => T` and read it with `toValue()`
+
+**Incorrect - reactivity lost at the function boundary:**
+```vue
+<script setup lang="ts">
+import { watch } from 'vue'
+import { useFetch } from './useFetch'
+
+const { id, count = 0 } = defineProps<{ id: number; count?: number }>()
+
+// ❌ passes the current number, not a reactive source — never re-runs
+watch(id, () => reload())
+
+// ❌ composable receives a one-time value, not a live source
+const { data } = useFetch(id)
+</script>
+```
+
+**Correct - wrap in a getter when crossing a function boundary:**
+```vue
+<script setup lang="ts">
+import { watch, computed } from 'vue'
+import { useFetch } from './useFetch'
+
+// defaults via plain destructure syntax — replaces withDefaults()
+const { id, count = 0 } = defineProps<{ id: number; count?: number }>()
+
+// ✅ getter preserves reactivity
+watch(() => id, () => reload())
+const { data } = useFetch(() => id)
+
+// ✅ bare access is fine inside computed / template / watchEffect
+const doubled = computed(() => count * 2)
+</script>
+
+<template>
+  <p>{{ count }} → {{ doubled }}</p>
+</template>
+```
+
+**Correct - composable consuming a getter:**
+```ts
+import { toValue, watchEffect, type MaybeRefOrGetter } from 'vue'
+
+export function useFetch(id: MaybeRefOrGetter<number>) {
+  watchEffect(() => {
+    const current = toValue(id) // normalizes getter | ref | plain value
+    // fetch with `current`…
+  })
+}
+```
+
+## Notes
+
+- This is the recommended way to set prop defaults in 3.5+. If a component still uses `withDefaults()`, its caveats (e.g. mutable factory defaults) continue to apply — prefer migrating to destructure defaults for new code.
+- The getter rule applies **only** across function boundaries. Bare `count` in a template or `computed` body is fully reactive; do not over-wrap.
+
+## Reference
+- [Vue.js — Reactive Props Destructure](https://vuejs.org/guide/components/props.html#reactive-props-destructure)
+- [Vue 3.5 release notes](https://blog.vuejs.org/posts/vue-3-5)

package/skills/vue-best-practices/references/vapor-mode.md

@@ -0,0 +1,65 @@
+---
+title: Vapor Mode (Vue 3.6, Experimental)
+impact: LOW
+impactDescription: Vapor is opt-in and unstable; adopting it app-wide or expecting full ecosystem support is premature
+type: capability
+tags: [vue3, vue36, vapor, performance, experimental, compiler]
+---
+
+# Vapor Mode (Vue 3.6, Experimental)
+
+**Impact: LOW (forward-looking)** - Vapor Mode is an alternative compilation strategy in Vue 3.6 that drops the Virtual DOM and compiles components to direct, fine-grained DOM updates (Solid-like), for smaller bundles and less memory. As of the Vue 3.6 beta it is **feature-complete but unstable** — opt in per component, do not bet a production app on it, and do not present it as the default.
+
+This is an experimental, version-gated feature. Treat everything below as subject to change.
+
+## Task Checklist
+
+- [ ] Do **not** enable Vapor by default; use the standard VDOM build unless a measured hotspot justifies it
+- [ ] Opt in **per component** with `<script setup vapor>`
+- [ ] Keep Vapor components Composition API + `<script setup>` only (no Options API)
+- [ ] When mixing Vapor and VDOM components, register `vaporInteropPlugin`
+- [ ] Confirm UI libraries work inside a Vapor region before relying on them
+
+**Opt in per component:**
+```vue
+<script setup vapor>
+// Composition API only; no Options API, getCurrentInstance() returns null here
+import { ref } from 'vue'
+const count = ref(0)
+</script>
+
+<template>
+  <button @click="count++">{{ count }}</button>
+</template>
+```
+
+**Mixing with an existing VDOM app — interop plugin required:**
+```ts
+import { createApp, vaporInteropPlugin } from 'vue'
+import App from './App.vue'
+
+createApp(App).use(vaporInteropPlugin).mount('#app')
+// Vapor and VDOM components can then nest in each other.
+```
+
+**Fully-Vapor app (smallest baseline, no VDOM runtime):**
+```ts
+import { createVaporApp } from 'vue'
+import App from './App.vue'
+
+createVaporApp(App).mount('#app')
+```
+
+## Constraints & caveats (3.6 beta)
+
+- `<script setup>` + Composition API only; Options API is unsupported.
+- `getCurrentInstance()` returns `null` in Vapor components — libraries depending on it can break.
+- Interop has rough edges (e.g. Vapor slots inside VDOM components need `renderSlot`); expect issues with some VDOM-based UI libraries.
+- Intended adoption today: a performance-sensitive sub-region of an existing app, or a small greenfield app built fully in Vapor.
+- `defineVaporComponent` exists but its API (TS generics, runtime props) is still evolving.
+
+> Separately, Vue 3.6 rewrites `@vue/reactivity` on alien-signals, giving performance and memory gains to **all** 3.6 apps — independent of Vapor and with no API change.
+
+## Reference
+- [Vue.js Nation 2025 — Evan You on Vue 3.6 & Vapor Mode](https://vueschool.io/articles/news/vn-talk-evan-you-preview-of-vue-3-6-vapor-mode)
+- [vuejs/core v3.6.0-beta release notes](https://github.com/vuejs/core/releases)

package/skills/vue-best-practices/references/vue-3-5-helpers.md

@@ -0,0 +1,91 @@
+---
+title: Vue 3.5 Helpers (useId, onWatcherCleanup, deferred Teleport, lazy hydration)
+impact: MEDIUM
+impactDescription: Reaching for manual id generation, ad-hoc watcher cleanup, or eager hydration when a built-in 3.5 helper exists
+type: best-practice
+tags: [vue3, vue35, useId, onWatcherCleanup, teleport, hydration, ssr, composition-api]
+---
+
+# Vue 3.5 Helpers (useId, onWatcherCleanup, deferred Teleport, lazy hydration)
+
+**Impact: MEDIUM** - Vue 3.5 (stable) ships small built-ins that replace hand-rolled patterns. Reach for these before writing your own.
+
+## Task Checklist
+
+- [ ] Use `useId()` for SSR-safe unique ids (form `:for`/`:id`, a11y attributes)
+- [ ] Register watcher teardown with `onWatcherCleanup()` instead of tracking cleanup manually
+- [ ] Use `<Teleport defer>` when the target element renders later in the same template
+- [ ] Hydrate heavy SSR async components lazily with a `hydrate` strategy
+
+### `useId()` — SSR-stable unique ids
+
+Generates an id that matches across server and client render, avoiding hydration mismatches. Each call returns a distinct value.
+
+```vue
+<script setup lang="ts">
+import { useId } from 'vue'
+const id = useId()
+</script>
+
+<template>
+  <label :for="id">Name</label>
+  <input :id="id" />
+</template>
+```
+
+Do not call `useId()` inside a `computed()`; declare it at setup top level.
+
+### `onWatcherCleanup()` — cancel in-flight work
+
+Registers cleanup that runs before the watcher re-fires or on unmount. Must be called **synchronously** within the effect (before any `await`).
+
+```ts
+import { watch, onWatcherCleanup } from 'vue'
+
+watch(id, (newId) => {
+  const controller = new AbortController()
+  fetch(`/api/items/${newId}`, { signal: controller.signal })
+  onWatcherCleanup(() => controller.abort()) // abort the stale request
+})
+```
+
+### `<Teleport defer>` — target rendered later
+
+Without `defer`, `<Teleport>` needs its target to already exist. `defer` delays mounting until after the current render tick, so the target can appear later in the same template.
+
+```vue
+<template>
+  <Teleport defer target="#modal-host">
+    <Modal />
+  </Teleport>
+  <!-- target defined after the Teleport in the same template -->
+  <div id="modal-host" />
+</template>
+```
+
+### Lazy hydration for async components (SSR)
+
+Defer hydrating heavy, below-the-fold components until they are needed, cutting time-to-interactive. Strategies are imported from `vue`.
+
+```ts
+import {
+  defineAsyncComponent,
+  hydrateOnVisible,
+  hydrateOnIdle,
+  hydrateOnInteraction,
+  hydrateOnMediaQuery,
+} from 'vue'
+
+const HeavyChart = defineAsyncComponent({
+  loader: () => import('./HeavyChart.vue'),
+  hydrate: hydrateOnVisible({ rootMargin: '100px' }), // IntersectionObserver
+  // hydrateOnIdle(timeout?)                  → requestIdleCallback
+  // hydrateOnInteraction('click')            → hydrates on first interaction
+  // hydrateOnMediaQuery('(min-width: 768px)')→ hydrates when the query matches
+})
+```
+
+## Reference
+- [Vue.js — Composition API helpers (useId, onWatcherCleanup)](https://vuejs.org/api/composition-api-helpers.html)
+- [Vue.js — Teleport (defer)](https://vuejs.org/guide/built-ins/teleport.html)
+- [Vue.js — Lazy hydration](https://vuejs.org/guide/components/async.html#lazy-hydration)

package/skills/create-adaptable-composable/SKILL.md

@@ -1,76 +0,0 @@
----
-name: create-adaptable-composable
-description: Create a library-grade Vue composable that accepts maybe-reactive inputs (MaybeRef / MaybeRefOrGetter) so callers can pass a plain value, ref, or getter. Normalize inputs with toValue()/toRef() inside reactive effects (watch/watchEffect) to keep behavior predictable and reactive. Use this skill when user asks for creating adaptable or reusable composables.
-license: MIT
-metadata:
-  author: github.com/Pythoughts-labs
-  version: "17.0.0"
-compatibility: Requires Vue 3 (or above) or Nuxt 3 (or above) project
----
-
-# Create Adaptable Composable
-
-Adaptable composables are reusable functions that can accept both reactive and non-reactive inputs. This allows developers to use the composable in a variety of contexts without worrying about the reactivity of the inputs.
-
-Steps to design an adaptable composable in Vue.js:
-1. Confirm the composable's purpose and API design and expected inputs/outputs.
-2. Identify inputs params that should be reactive (MaybeRef / MaybeRefOrGetter).
-3. Use `toValue()` or `toRef()` to normalize inputs inside reactive effects.
-4. Implement the core logic of the composable using Vue's reactivity APIs.
-
-## Core Type Concepts
-
-### Type Utilities
-
-```ts
-/**
- * value or writable ref (value/ref/shallowRef/writable computed)
- */
-export type MaybeRef<T = any> = T | Ref<T> | ShallowRef<T> | WritableComputedRef<T>;
-
-/**
- * MaybeRef<T> + ComputedRef<T> + () => T
- */
-export type MaybeRefOrGetter<T = any> = MaybeRef<T> | ComputedRef<T> | (() => T);
-```
-
-### Policy and Rules
-
-- Read-only, computed-friendly input: use `MaybeRefOrGetter`
-- Needs to be writable / two-way input: use `MaybeRef`
-- Parameter might be a function value (callback/predicate/comparator): do not use `MaybeRefOrGetter`, or you may accidentally invoke it as a getter.
-- DOM/Element targets: if you want computed/derived targets, use `MaybeRefOrGetter`.
-
-When `MaybeRefOrGetter` or `MaybeRef` is used: 
-- resolve reactive value using `toRef()` (e.g. watcher source)
-- resolve non-reactive value using `toValue()`
-
-### Examples
-
-Adaptable `useDocumentTitle` Composable: read-only title parameter
-
-```ts
-import { watch, toRef } from 'vue'
-import type { MaybeRefOrGetter } from 'vue'
-
-export function useDocumentTitle(title: MaybeRefOrGetter<string>) {
-  watch(toRef(title), (t) => {
-    document.title = t
-  }, { immediate: true })
-}
-```
-
-Adaptable `useCounter` Composable: two-way writable count parameter
-
-```ts
-import { watch, toRef } from 'vue'
-import type { MaybeRef } from 'vue'
-
-function useCounter(count: MaybeRef<number>) {
-  const countRef = toRef(count)
-  function add() {
-    countRef.value++
-  }
-  return { add }
-}
-```