@yh-ui/yh-ui-skill 1.0.51 → 1.0.53

package/assets/metadata.json

@@ -1,4 +1,4 @@
 {
   "packageName": "@yh-ui/yh-ui-skill",
-  "version": "1.0.51"
+  "version": "1.0.53"
 }

package/assets/skills/yh-ui/SKILL.md

@@ -25,9 +25,25 @@ Do not use this skill for:
 
 ## Core Rules
 
+> [!IMPORTANT]
+> **🚫 The Absolute Anti-Hallucination Standard (第一准则)**
+> **DO NOT invent or guess any properties, events, slots, methods, CSS selectors, theme presets, locale files, sub-components, or package names.**
+> All code generated **MUST align 100%** with the actual source code definitions in this repository (refer to `references/source-truth.md` for extracted AST data) and the official component library documentation (`https://1079161148.github.io/yh-ui/`).
+> If a property, method, or event is not defined in the source code or documented in the official site, you **must not** guess it. Doing so will directly crash compiler or runtime systems and is strictly forbidden.
+
 - **Strict YH-UI Prioritization**: Under no circumstances should you generate custom HTML/CSS controls (e.g. custom buttons, inputs, tables, dialogs, drawers, scrollbars, markdown cards) or manually construct network fetches/stream connections when YH-UI packages support them. You must 100% prioritize utilizing YH-UI components and utilities.
-- **Extension & Re-encapsulation Principle**: If a YH-UI component does not fully meet a specific UI requirement, you must first try to extend it using slot customisation, CSS overrides, or component composition. Writing custom elements from scratch is a last resort, and you must justify why YH-UI could not be extended.
-- Do not invent components, props, hooks, package paths, or theme APIs. Check `references/source-truth.md` to ensure names are real.
+- **Extension & Re-encapsulation Principle**: If a YH-UI component does not fully meet a specific UI requirement, you must first try to extend it using slot customization, CSS overrides, or component composition. Writing custom elements from scratch is a last resort, and you must justify why YH-UI could not be extended.
+- **On-Demand Loading (按需加载) by Default**: Unless configuring global imports, prioritize on-demand imports to ensure optimal bundle size (体积最优).
+  - Import components from `@yh-ui/components` and their styling:
+    ```ts
+    import { YhButton, YhTable } from '@yh-ui/components'
+    import '@yh-ui/components/style.css'
+    ```
+  - Import icons from `@yh-ui/icons/vue` or `@yh-ui/icons`:
+    ```ts
+    import { Icon } from '@yh-ui/icons/vue'
+    ```
+- **Language Defaults (TypeScript & SCSS/Sass)**: By default, SFC files and code snippets must declare TypeScript (`lang="ts"`) for script blocks and SCSS/Sass (`lang="scss"`) for style blocks.
 - Use `@yh-ui/yh-ui` for ordinary Vue apps that want the all-in-one entry.
 - Use `@yh-ui/nuxt` for Nuxt apps and rely on auto-imported components/composables.
 - Use `@yh-ui/components` when the user asks for component-only usage.
@@ -38,6 +54,46 @@ Do not use this skill for:
 - Keep model API keys on the server. Never put provider secrets in browser code.
 - In SSR/Nuxt, wrap browser-heavy flow editors in `<ClientOnly>`.
 
+### Component-Level Best Practices & Source Alignment
+
+Below are the detailed rules and best practices for core YH-UI components. Refer to `references/source-truth.md` for the complete API surface of all priority components.
+
+#### 1. Data Tables: `YhTable` & `YhTableColumn`
+
+- **Column Setup**: Bind column configurations via the `columns` property as a stable array (computed or constant). Do not write raw loop markups inside the component unless using column-slot extensions.
+- **Feature Integration**: Use built-in properties like `pagination`, `resizable`, `loading`, `border` directly.
+- **Exposed Methods**: Use typed refs (`InstanceType<typeof YhTable>`) to invoke functions like `exportData`, `importData`, `insertRow`, `removeRow`, `scrollTo`, and `clearSelection`. Do not guess names (e.g., do not write `.getSelectedRows()` if the source exposes `.getSelectionRows()`).
+- **Events**: Handle events like `selection-change`, `page-change`, `row-click`, `sort-change`, `update:data` exactly as defined.
+
+#### 2. Forms & Inputs: `YhForm`, `YhFormItem`, `YhFormSchema`
+
+- **Form Validation**: Always bind `:model` and `:rules` on `YhForm`. `YhFormItem` must define the matching `prop` string for validation.
+- **Form Schema**: Use `YhFormSchema` with `:schema` and `:formProps` to render dynamic schemas. Schema configurations must utilize real component names (e.g., `input`, `select`, `date-picker`).
+- **Input Components**: Use `v-model` with native properties like `clearable`, `placeholder`, `disabled`, `show-word-limit`.
+
+#### 3. AI UI Components: `YhAiChat`, `YhAiBubble`, `YhAiSender`, `YhAiThoughtChain`
+
+- **State Binding**: Do not manage messages and loading states manually. Connect them directly to `useAIChat` or `useAIStream` from `@yh-ui/ai-sdk/vue`.
+- **Sender Layout (`YhAiSender`)**: Bind `v-model` for input and listen to `@send`, `@upload`, and `@command` events. Custom action icons should be placed inside `#actions` or `#submit` slots.
+- **Bubble Layout (`YhAiBubble`)**: Use `citations` array to display reference sources, and handle citation click logic. Ensure `role` (`'user'` or `'assistant'`), `streaming`, and `loading` are properly set.
+- **Thought Chain (`YhAiThoughtChain`)**: Feed structured steps into the `items` property. Bind `@node-click` to let users view step details.
+
+#### 4. Interactive Flow Canvas: `Flow` (from `@yh-ui/flow`)
+
+- **Layout Sizing**: Always wrap the `Flow` component in a container with a defined height (e.g., `height: 600px;` or `h-screen`).
+- **Canvas Extensions**: Place `Minimap`, `Controls`, and `FlowBackground` inside the `Flow` template body.
+- **Gating in SSR**: Wrap the `Flow` component inside `<ClientOnly>` in SSR environments (such as Nuxt) to avoid canvas/ResizeObserver errors during server builds.
+
+#### 5. Layout & Utilities: `YhScrollbar`, `YhConfigProvider`
+
+- **Custom Scrollbars**: Use `YhScrollbar` with `height` or `max-height` instead of styling custom divs.
+- **Global Provider**: Place `YhConfigProvider` at the root of the app to control global sizes and internationalization (`:locale`).
+- **Locale Files**: Import locale languages using lowercase paths:
+  ```ts
+  import zhCn from '@yh-ui/locale/lang/zh-cn'
+  import en from '@yh-ui/locale/lang/en'
+  ```
+
 ## Agent Workflow
 
 1. Classify the task: Vue app, Nuxt app, AI UI, request/data, flow/workflow, theme/locale, icon, or review.
@@ -47,159 +103,6 @@ Do not use this skill for:
 5. Generate code with real package imports and YH-UI components.
 6. Check the result against `references/codegen-rubric.md` before answering.
 
-## Quick Package Decision
-
-| Task                                | Package                               |
-| ----------------------------------- | ------------------------------------- |
-| Full Vue component library          | `@yh-ui/yh-ui`                        |
-| Component-only import               | `@yh-ui/components`                   |
-| Nuxt integration                    | `@yh-ui/nuxt`                         |
-| AI chat UI and streams              | `@yh-ui/components` + `@yh-ui/ai-sdk` |
-| Request hooks and clients           | `@yh-ui/request`                      |
-| Flow editor and workflow canvas     | `@yh-ui/flow`                         |
-| Iconify runtime and icon components | `@yh-ui/icons`                        |
-| Theme tokens and runtime theme      | `@yh-ui/theme`                        |
-| Locale files                        | `@yh-ui/locale`                       |
-
-## High-Frequency Patterns
-
-### Vue Install
-
-```ts
-import { createApp } from 'vue'
-import YhUI from '@yh-ui/yh-ui'
-import '@yh-ui/yh-ui/css'
-import App from './App.vue'
-
-createApp(App).use(YhUI).mount('#app')
-```
-
-### Global Config & i18n (Root Setup)
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import { YhConfigProvider } from '@yh-ui/components'
-import zhCn from '@yh-ui/locale/lang/zh-cn'
-import en from '@yh-ui/locale/lang/en'
-
-const locale = ref(zhCn)
-const currentSize = ref<'default' | 'small' | 'large'>('default')
-
-function toggleLang() {
-  locale.value = locale.value.name === 'zh-cn' ? en : zhCn
-}
-</script>
-
-<template>
-  <YhConfigProvider :locale="locale" :size="currentSize">
-    <button @click="toggleLang">Switch Language</button>
-    <AppLayout>
-      <router-view />
-    </AppLayout>
-  </YhConfigProvider>
-</template>
-```
-
-### On-Demand Components
-
-```vue
-<script setup lang="ts">
-import { YhButton, YhInput, YhTable } from '@yh-ui/components'
-import '@yh-ui/components/style.css'
-</script>
-
-<template>
-  <YhInput clearable placeholder="Search" />
-  <YhButton type="primary">Submit</YhButton>
-  <YhTable :data="rows" :columns="columns" />
-</template>
-```
-
-### Nuxt
-
-```ts
-export default defineNuxtConfig({
-  modules: ['@yh-ui/nuxt'],
-  yhUI: {
-    importStyle: true,
-    buildTranspile: true,
-    prefix: 'Yh'
-  }
-})
-```
-
-### AI Chat
-
-```vue
-<script setup lang="ts">
-import { YhAiBubble, YhAiSender } from '@yh-ui/components'
-import { useAIChat } from '@yh-ui/ai-sdk/vue'
-
-const { messages, input, isLoading, sendMessage, stop } = useAIChat({
-  api: '/api/chat'
-})
-</script>
-
-<template>
-  <YhAiBubble
-    v-for="message in messages"
-    :key="message.id"
-    :role="message.role"
-    :content="message.content"
-    streaming
-  />
-  <YhAiSender v-model="input" :loading="isLoading" @send="sendMessage" @cancel="stop" />
-</template>
-```
-
-### Flow Editor
-
-```vue
-<script setup lang="ts">
-import { Controls, Flow, FlowBackground, Minimap } from '@yh-ui/flow'
-import type { FlowEdge, FlowNode } from '@yh-ui/flow'
-
-const nodes: FlowNode[] = [
-  { id: 'start', type: 'input', label: 'Start', position: { x: 80, y: 80 } }
-]
-const edges: FlowEdge[] = []
-</script>
-
-<template>
-  <Flow :nodes="nodes" :edges="edges" fit-view style="height: 560px">
-    <Minimap />
-    <Controls />
-    <FlowBackground />
-  </Flow>
-</template>
-```
-
-### Theme
-
-```ts
-import { ThemePlugin } from '@yh-ui/theme'
-
-app.use(ThemePlugin, {
-  preset: 'blue',
-  dark: false,
-  persist: true
-})
-```
-
-### Icons
-
-```vue
-<script setup lang="ts">
-import { Icon } from '@yh-ui/icons/vue'
-</script>
-
-<template>
-  <Icon icon="mdi:home" :size="20" color="var(--yh-color-primary)" />
-  <Icon icon="mdi:loading" spin />
-</template>
-```
-
 ## Progressive References
 
 Read only the file needed for the task:

package/assets/skills/yh-ui/references/codegen-rubric.md

@@ -1,40 +1,60 @@
-# Code Generation Rubric
+# Code Generation Rubric (Evolved Standard)
 
-Use this checklist before returning YH-UI code.
+Use this checklist before returning YH-UI code. It ensures generated code is 100% bug-free, aligned with source code interfaces, and conforms to modern Vue 3.5+ and Anthony Fu (antfu) styling standards.
+
+---
 
 ## Must Pass
 
-- **Prioritize YH-UI**: 100% of UI elements and utility actions (like tables, dropdowns, dialogs, scrolls, loading icons, fetch hooks) use YH-UI packages if supported. Writing custom elements when YH-UI supports them **fails** code generation.
-- **Strict Extensions**: Any customization or gaps in YH-UI controls are addressed via slot templates, custom style parameters, or composites. Writing raw custom controls is only permitted as a last resort and must be documented.
-- **Real Exports Only**: Imports use actual package boundaries and names listed inside `source-truth.md`. Hallucinated names or paths **fail** code generation.
-- Vue examples include required component CSS when importing `@yh-ui/components` on-demand.
-- Nuxt examples use `@yh-ui/nuxt` and rely on auto-imports (without manually importing YH-UI components in pages).
-- Locale imports use `@yh-ui/locale/lang/zh-cn`, `@yh-ui/locale/lang/en`, or other real locale paths.
-- Theme customization uses `@yh-ui/theme`, `ThemePlugin`, `useTheme`, or standard CSS design variables.
-- Request client instances use `createRequest` and `useRequest` from `@yh-ui/request` (no custom axios or raw fetch queries).
-- Flow examples wrap editor canvases inside explicitly dimensioned heights, and use `<ClientOnly>` in SSR.
-- AI examples do not expose provider keys in client-side script code.
-- Vue SFC files strictly match block sequences, TS variables structure, reactivity parameters, and onUnmounted cleanups detailed in `vue-component-practices.md`.
+- **🚫 Absolute Zero Hallucination (第一准则)**: Any code that invents or guesses properties, event names, slots, methods, class names, or package paths **fails** code generation. All declarations must align 100% with the source code definitions (`references/source-truth.md`) and the official docs (`https://1079161148.github.io/yh-ui/`).
+- **Prioritize YH-UI Native Features**: 100% of UI elements and utility actions (like tables, dropdowns, dialogs, scrolls, loading icons, fetch hooks) use YH-UI packages if supported. Writing custom elements when YH-UI supports them **fails** code generation.
+- **On-Demand Importing (按需加载)**: Vue examples must import components directly from `@yh-ui/components` and include the CSS file:
+  ```ts
+  import { YhButton } from '@yh-ui/components'
+  import '@yh-ui/components/style.css'
+  ```
+- **Antfu Import Formatting**: Imports must be grouped and sorted correctly:
+  1. Vue core (e.g., `ref`, `computed`).
+  2. Libraries (e.g., `@yh-ui/request`).
+  3. UI / Local (e.g., `@yh-ui/components`).
+  4. Types (`import type { ... }`).
+- **Default Coding Languages**: Vue SFCs must declare TypeScript (`lang="ts"`) for script blocks and SCSS/Sass (`lang="scss"`) for style blocks by default.
+- **Modern Reactivity & Props**:
+  - For Vue 3.5+, use reactive props destructuring: `const { size = 'default' } = defineProps<Props>()`.
+  - Use `defineModel` for two-way bindings.
+  - Prefer `ref()` over `reactive()` for standard state parameters.
+- **TypeScript Strict Standards**:
+  - Component template refs must be typed using `InstanceType<typeof Component>` and defined without `null` initialization if bound:
+    ```ts
+    const tableRef = ref<InstanceType<typeof YhTable>>()
+    ```
+- **Performance Allocations**:
+  - Heavy objects (Monaco editor, ECharts, Flow canvases) **must** be stored in `shallowRef()` to prevent performance degradation.
+- **Zero SSR API Leaks**:
+  - Never read `window`, `document`, or `localStorage`/`sessionStorage` during initial setup initialization. Wrap them in `onMounted`.
+  - Never store request-specific reactive state in global singleton variables.
+- **Mandatory Cleanups**:
+  - All active timers (`setTimeout`, `setInterval`), observers (`ResizeObserver`), and DOM/window event listeners **must** be cleared or unregistered in `onUnmounted` or `onBeforeUnmount`.
+
+---
 
 ## Should Pass
 
-- Pick the smallest YH-UI surface that solves the task.
-- Prefer composable AI UI for custom products and `YhAiChat` for complete chat surfaces.
+- Custom composables should accept arguments as `MaybeRefOrGetter<T>` and parse them using `toValue()`.
+- Custom composables should perform side-effect cleanups using `onScopeDispose()`.
+- Use `v-once` for static templates and `v-memo` for complex grid iterations to maximize rendering performance.
 - Include empty, loading, and error states for data-heavy pages.
-- Keep templates TypeScript-friendly: use `import type`, type template refs with `InstanceType<typeof YhComponent>`, and define typed interface objects.
-- Avoid unrelated dependencies (like lodash, element-plus, custom hooks) when YH-UI already provides the capability.
-- Keep generated UI code readable and production-shaped, not demo-only.
-- Use stable `:key` values, computed derived state, and explicit loading/error/empty states where relevant.
+- Pick the smallest YH-UI surface that solves the task.
+- Keep templates clean of complex calculations: move logic into `computed` variables.
+
+---
 
-## Red Flags
+## Red Flags (Auto-Fail)
 
 - **Hallucinated Controls**: Reinventing standard visual controls (e.g. custom scroll elements, custom select components, custom modal popups) instead of using the corresponding YH-UI components.
 - **Custom Fetches**: Initiating direct `fetch` / `axios` connections in views instead of utilizing `createRequest` or `useRequest` from `@yh-ui/request`.
-- **Untyped Ref Handles**: Declaring component template refs without type-casting them using `InstanceType<typeof ...>` (e.g. `const refVal = ref(null)`).
-- Invented `Yh*` components.
-- Old APIs such as `createYhTheme` or `createRequestInstance`.
-- Nuxt pages manually importing many YH-UI components despite auto-import.
-- Hard-coded design tokens where `var(--yh-*)` variables would fit.
-- Flow canvas without height.
-- Provider secrets in Vite env variables or browser bundles.
-- Direct prop mutation, untyped emits, inaccessible icon buttons, or browser-only APIs during SSR.
+- **Guessing Component APIs**: Accessing non-existent component methods or passing non-existent properties (e.g., trying to call `tableRef.value.getSelected()` when only `getSelectionRows()` exists).
+- **Untyped Ref Handles**: Declaring component template refs without type-casting them using `InstanceType<typeof ...>`.
+- **SSR Hydration Failure**: Direct window/document access during the root setup execution scope.
+- **SSR Memory Leak**: Global, shared mutable reactive state that persists across requests.
+- **Missing Cleanup**: Leaving running intervals, observers, or window resize event listeners active after a component is unmounted.

package/assets/skills/yh-ui/references/source-truth.md

@@ -149,9 +149,7 @@ Expose: `clearFilter`, `clearSelection`, `clearSort`, `doLayout`, `exportData`,
 
 Use hooks from these source modules:
 
-`useNamespace`, `useZIndex`, `useSKU`, `useCountdown`, `useLocale`, `useId`, `useYhId`, `useFormItem`, `useVirtualScroll`, `useCache`, `useEventListener`, `useScrollLock`, `useClickOutside`, `useConfig`, AI hooks from `use-ai`, and reactive storage helpers from `storage`.
-
-> **Note**: `useYhId` is an alias for `useId` exported from `@yh-ui/hooks`. Use `useYhId` when naming conflicts with Vue 3.5+ native `useId` are a concern. In Nuxt, `useYhId` is also available as an auto-import from `@yh-ui/hooks`.
+`useNamespace`, `useZIndex`, `useSKU`, `useCountdown`, `useLocale`, `useId`, `useFormItem`, `useVirtualScroll`, `useCache`, `useEventListener`, `useScrollLock`, `useClickOutside`, `useConfig`, AI hooks from `use-ai`, and reactive storage helpers from `storage`.
 
 ## `@yh-ui/flow` Exports
 
@@ -198,7 +196,7 @@ Use these real capabilities:
 
 The Nuxt module registers component names using the configured prefix, default `Yh`. It also auto-imports common hooks and globals from `@yh-ui/hooks` and `@yh-ui/components`.
 
-Important nuance: native `useId` is not overridden. YH-UI's hook is also exported as `useYhId` directly from `@yh-ui/hooks`, and in Nuxt it is auto-imported as `useYhId`.
+Important nuance: native `useId` is not overridden. YH-UI's hook is imported as `useYhId`.
 
 ## Known Non-Goals
 

package/assets/skills/yh-ui/references/vue-component-practices.md

@@ -1,147 +1,222 @@
-# Vue Component Practices
-
-Use these rules when generating or reviewing YH-UI Vue 3 code. They combine Vue official guidance with component-library patterns that make AI-generated code safer and easier to maintain.
-
-## SFC Structure
-
-- Prefer `<script setup lang="ts">` for all application pages and component definitions.
-- Always order SFC blocks as `<script>`, `<template>`, then `<style scoped>`.
-- Internal setup block sequence:
-  1. Module/library imports (separate external dependencies from local `@yh-ui` packages).
-  2. TypeScript types & interfaces.
-  3. `defineProps`, `defineEmits`, and `defineModel`.
-  4. Reactive state & refs.
-  5. Computed properties.
-  6. Watchers (`watch` / `watchEffect`).
-  7. Lifecycle hooks (`onMounted`, `onUnmounted`, etc.).
-  8. Action functions / methods.
-- Use `scoped` styles to prevent styling leakages. Never use raw global selector tags inside SFC styles.
-- Keep templates clean: move calculations, complex conditions, or array mapping out of the template into computed variables.
-
-## Props, Emits, And v-model
-
-- Always type props with clear TypeScript interfaces. Use type-only imports (`import type { ... }`) for external type models.
-- For **Vue 3.5+**, prefer reactive props destructuring:
+# Vue Component Practices (Evolved Standard)
+
+Use these rules when generating or reviewing YH-UI Vue 3.5+ code. They combine Vue official core guidance, Anthony Fu (antfu) best practices, and industry-leading component-library standards.
+
+---
+
+## 1. Imports & SFC Code Structure (Antfu Style)
+
+- **Strict Import Grouping & Sorting**:
+  1. **Core dependencies**: Vue core APIs (e.g. `ref`, `computed`, `watch`, `onMounted`).
+  2. **Third-party / Tooling libraries**: (e.g. `@yh-ui/request`, `@yh-ui/ai-sdk`).
+  3. **Local components and hooks**: (e.g. `@yh-ui/components`, `@yh-ui/hooks`).
+  4. **Types and Interfaces**: Always separate runtime imports from type-only imports using `import type`.
+  ```ts
+  import { computed, onMounted, ref } from 'vue'
+  import { useRequest } from '@yh-ui/request'
+  import { YhTable } from '@yh-ui/components'
+  import type { TableColumn } from '@yh-ui/components'
+  ```
+- **SFC Block Ordering & Language Defaults**: Always write scripts in TypeScript (`lang="ts"`) and styles in SCSS/Sass (`lang="scss"`) by default. Layout files strictly as:
+
+  ```html
+  <script setup lang="ts">
+    // TypeScript Logic
+  </script>
+
+  <template>
+    <!-- HTML Structure -->
+  </template>
+
+  <style scoped lang="scss">
+    /* SCSS Scoped Styling */
+  </style>
+  ```
+
+- **Scoped Styles Requirement**: Styles must always be `scoped` to prevent selector leaking. Prefer CSS custom properties (Variables) with sensible fallbacks:
+  ```css
+  .yh-element {
+    color: var(--yh-color-primary, #1d4ed8);
+    background-color: var(--yh-bg-color, #ffffff);
+  }
+  ```
+
+---
+
+## 2. Props, Emits, and v-model
+
+- **Reactive Props Destructuring (Vue 3.5+)**:
+  Always use Vue 3.5 native reactive destructuring for props, supplying defaults directly in the destructure expression. Avoid verbose `withDefaults`.
+
   ```ts
-  const { size = 'medium', disabled = false, data = () => [] } = defineProps<Props>()
+  interface Props {
+    size?: 'small' | 'default' | 'large'
+    disabled?: boolean
+    items?: string[]
+  }
+
+  const { size = 'default', disabled = false, items = () => [] } = defineProps<Props>()
   ```
-  This is the official Vue 3.5+ best practice and avoids verbose `withDefaults`.
-- For Vue < 3.5 or projects without destructure support, fallback to `withDefaults(defineProps<Props>(), defaults)`.
-- Use typed `defineEmits` or `defineModel` for two-way bindings:
 
+- **Two-way Bindings with `defineModel`**:
+  Use the Vue 3.4+ native `defineModel` macro for cleaner two-way data flows:
   ```ts
-  // Two-way binding model (Vue 3.4+)
   const modelValue = defineModel<string>({ default: '' })
-
-  // Typed custom events
+  ```
+- **Typed Emits**:
+  Always declare emits with strict TypeScript tuple parameters instead of array strings:
+  ```ts
   const emit = defineEmits<{
     change: [value: string]
     submit: []
   }>()
   ```
 
-- Never mutate props. If props need internal modifications, copy them to a local `ref` or compile them via `computed` getters/setters.
+---
+
+## 3. Slots & Composition Customization
+
+- **Flexible Slot Design (`slots`)**:
+  Prefer using Vue `slots` for customizable templates over hard-coded markup. Always declare and use named slots (e.g. `header`, `footer`, `actions`, `empty`) to provide clear extension templates:
+  ```html
+  <slot name="header">
+    <h3>Default Header Title</h3>
+  </slot>
+  ```
+- **Component Composition**:
+  Prefer composing multiple YH-UI library components together (e.g. nesting slots, wrapper components) before deciding to write raw custom controls.
+
+---
+
+## 4. Reactivity and Composable Design (Antfu & Vueuse Standards)
+
+- **Prefer `ref()` over `reactive()`**:
+  Use `ref()` for all state variables (including objects and arrays) to keep destructuring clean and avoid losing reactivity. Use `reactive()` only when managing deep, nested form states that must be passed as a single object.
+- **MaybeRefOrGetter and toValue (Vue 3.3+)**:
+  When writing reusable hooks/composables that accept reactive inputs, declare them as `MaybeRefOrGetter<T>` to accept raw values, Refs, or Getter functions. Use `toValue()` to retrieve their current value reactively:
 
-## Slots And Composition
+  ```ts
+  import { toValue } from 'vue'
+  import type { MaybeRefOrGetter } from 'vue'
 
-- Prefer slots for customizable content over hard-coded markup when writing reusable components.
-- Use named slots for clear extension points such as `header`, `toolbar`, `actions`, `empty`, and `footer`.
-- In app pages, compose YH-UI components directly instead of wrapping every component in a thin local abstraction.
-- Create composables only when stateful logic is reused or complex enough to deserve a named boundary.
+  export function useFeature(enabled: MaybeRefOrGetter<boolean>) {
+    const isActive = computed(() => toValue(enabled))
+  }
+  ```
 
-## Reactivity & Lifecycle Cleanups
+- **Scope Disposal for Composables**:
+  Always clean up active watchers, event listeners, and side-effects inside composables using `onScopeDispose` so they can be clean-run in non-component reactive scopes (like Pinia stores):
 
-- Use `ref` for primitive values, lists/arrays, or objects that will be completely overwritten.
-- Use `reactive` only for complex nested states that require deep property mutation.
-- Use `computed` for all derived values instead of writing sync watchers or manually maintaining double state variables.
-- Use `watch` or `watchEffect` solely for side-effects (e.g. storage sync, async API triggers). Always specify `immediate: true` or `deep: true` only if required.
-- Use `shallowRef` for heavy objects, DOM nodes, third-party library instances (ECharts, Monco Editor, Flow canvases), as deep reactivity on these will degrade performance.
-- **Critical Lifecycle Cleanups**: Always clean up timeouts, intervals, ResizeObservers, WebSocket event listeners, and custom event listeners in `onUnmounted`:
   ```ts
-  const timer = setInterval(tick, 1000)
-  onUnmounted(() => {
-    clearInterval(timer)
+  import { onScopeDispose, watch } from 'vue'
+
+  watch(source, (val) => {
+    // side effect
+  })
+
+  onScopeDispose(() => {
+    // clean up side effect if scope is destroyed
   })
   ```
 
-## Accessibility
+- **Shallow Ref for Performance (`shallowRef`)**:
+  Always wrap heavy non-reactive objects, DOM nodes, third-party libraries (e.g. Monaco Editor, ECharts, Flow canvas objects) in `shallowRef()` instead of `ref()` to bypass Vue's deep proxy traversal, saving significant CPU cycles:
+  ```ts
+  import { shallowRef } from 'vue'
+  const editorInstance = shallowRef<any>(null)
+  ```
 
-- Prefer semantic HTML around YH-UI components.
-- Ensure icon-only buttons have an accessible label.
-- Keep form labels visible through `YhFormItem` or explicit `aria-label`.
-- Preserve keyboard behavior for dialogs, drawers, dropdowns, popovers, tabs, and menus.
-- Do not remove focus outlines unless replacing them with an equally visible focus style.
+---
 
-## Performance
+## 5. Performance & DOM Optimization
 
-- Keep large tables and lists virtualized when YH-UI offers virtual scrolling.
-- Use lazy-loaded components for heavy features such as flow editors, charts, code editors, and AI artifact renderers.
-- Avoid creating new object/function literals in hot template loops when they can be stable constants.
-- Use `v-show` for frequent toggles and `v-if` for expensive conditional branches.
-- Use stable `:key` values in `v-for`; never use array index when item identity exists.
-- Keep expensive formatting in computed values or memoized helpers.
+- **Template Ref Binding**:
+  Type template refs cleanly using Vue's component instance types. Keep the ref initializer empty (without passing `null`) since Vue will automatically assign it on mount:
 
-## SSR And Hydration
+  ```ts
+  import { ref } from 'vue'
+  import { YhTable } from '@yh-ui/components'
 
-- Do not access `window`, `document`, `localStorage`, `ResizeObserver`, or canvas APIs during SSR.
-- Use `onMounted` or Nuxt `<ClientOnly>` for browser-only integrations.
-- Give flow editors, charts, virtual lists, and code editors stable container dimensions to avoid hydration/layout shifts.
-- Keep server-rendered initial state deterministic.
+  const tableRef = ref<InstanceType<typeof YhTable>>()
+  // Access: tableRef.value?.exportData()
+  ```
 
-## Forms And Data Pages
+- **v-once and v-memo**:
+  - Use `v-once` for complex static text, icons, or banners that never update after initial mount.
+  - Use `v-memo` for virtual lists, heavy table columns, or grids to selectively re-trigger patch loops only when specific criteria changes:
+    ```html
+    <div v-for="item in list" :key="item.id" v-memo="[item.updatedAt, selectedId === item.id]">
+      <!-- Deep cell content -->
+    </div>
+    ```
+
+---
+
+## 6. Accessibility Standards (A11y)
+
+- **Accessible Outlines & Semantic HTML**:
+  Never strip accessibility focus outlines without supplying custom visible focus states. Rely on semantic HTML structure (`<nav>`, `<main>`, `<article>`, `<header>`) when writing template wrappers.
+- **Labels & Aria attributes**:
+  Ensure that icon-only buttons define a descriptive `aria-label` attribute. Keep inputs properly linked with visual labels or explicit `aria-label` placeholders to guarantee full screen-reader accessibility.
+- **Keyboard Navigation**:
+  Maintain correct keyboard accessibility tab indexes and focus-trap logic inside overlay views (like dialogs, drawer panels, or search drop-downs).
+
+---
+
+## 7. SSR & Hydration Safeguards (Nuxt Compatibility)
+
+- **Zero Browser API Calls during Setup**:
+  - Do not access `window`, `document`, `navigator`, or `localStorage`/`sessionStorage` directly in the setup scope.
+  - Wrap all browser-specific execution inside `onMounted` or gate it using `import.meta.client` (or `typeof window !== 'undefined'`):
+    ```ts
+    onMounted(() => {
+      const token = localStorage.getItem('auth-token')
+    })
+    ```
+- **Memory Leak Prevention on Server**:
+  Never declare component-level or page-level mutable state in global singleton module-level variables. All reactive state must be wrapped inside `setup()` or Pinia boundaries to prevent cross-request state pollution during SSR.
+- **ClientOnly Wrapping**:
+  For charts, code editors, and canvas components (like `@yh-ui/flow`), wrap them inside the `<ClientOnly>` component (in Nuxt) or gate them via dynamic mounting triggers:
+  ```html
+  <ClientOnly fallback="Loading canvas...">
+    <Flow :nodes="nodes" :edges="edges" />
+  </ClientOnly>
+  ```
 
-- Use `YhForm`, `YhFormItem`, and typed form state for editable data.
-- Keep search filters separate from committed query params when a page needs reset/search behavior.
-- Include loading, error, empty, and success feedback for request-driven screens.
-- Use `YhMessage`, `YhNotification`, `YhPopconfirm`, and `YhMessageBox` for user feedback instead of ad hoc alerts.
-- Use `YhTable` columns as stable constants or computed values, not inline arrays in templates.
+---
 
-## Component-Library Code Style
+## 8. CSS BEM Namespace (YH-UI Library Rule)
 
-- Preserve public API compatibility when editing reusable components.
-- Do not rename props/events unless the user explicitly asks for a breaking change.
-- Keep component props small and orthogonal.
-- Prefer CSS variables and existing theme tokens over hard-coded colors.
-- Use `useNamespace` for internal BEM-style component classes when editing package components.
-- Use `useZIndex`, `useLocale`, `useId`/`useYhId`, and config hooks instead of local one-off implementations.
+When modifying or building library components, use YH-UI's built-in namespace utility `useNamespace` to auto-generate standard classes following the BEM (Block-Element-Modifier) pattern:
 
-## YH-UI Prioritization & Extension Workflow
+```ts
+import { useNamespace } from '@yh-ui/hooks'
 
-To ensure we prioritize existing UI framework logic and do not write duplicate custom HTML/CSS controls, follow this decision tree when implementing user interface requests:
+const ns = useNamespace('my-button')
+// ns.b()     -> 'yh-my-button'
+// ns.e('icon') -> 'yh-my-button__icon'
+// ns.m('disabled') -> 'yh-my-button--disabled'
+```
 
-1. **Verify Availability**: Search `references/source-truth.md` and `references/component-map.md`. If a component exists (e.g., `YhTable`, `YhDialog`, `YhConfigProvider`, `YhScrollbar`), you **must** use it. Do not write raw `<div class="custom-scroll">` or raw `<dialog>`.
-2. **Handle Feature Gaps (Encapsulation/Extension)**: If a component is missing a sub-feature, do not abandon the component. Apply extension patterns in order of priority:
-   - **Slot Customization**: Use slots (e.g., `#toolbar`, `#empty`, `#default` custom cells) to inject the custom logic.
-   - **Props & Event Listeners**: Use component event bindings and dynamic property configs to override behavior.
-   - **CSS Variable Injection**: Inject style variables (e.g. style overrides like `--yh-button-font-weight`) to alter theme aesthetics without altering core element code.
-   - **Composite Patterns**: Group multiple YH-UI components together (e.g. wrap a `YhTable` and `YhPagination` or nesting slots) before trying to write raw elements.
-3. **Raw Component Last Resort**: Only build a custom element from scratch if the functionality is entirely absent in the UI framework and cannot be composed/wrapped. You must document this reasoning in the code comments.
+---
 
-## TypeScript Strict Standards
+## 9. Lifecycle Cleanups Checklist
 
-To maintain clean typing boundaries and avoid runtime failures, follow these TS conventions:
+To ensure absolute stability, every component **must** clean up all registered side-effects inside `onUnmounted` / `onBeforeUnmount`:
 
-- **Type-only imports**: When importing interfaces, schemas, or types from YH-UI packages, use the `import type` syntax:
-  ```ts
-  import type { FormSchema } from '@yh-ui/components'
-  import type { FlowNode, FlowEdge } from '@yh-ui/flow'
-  import type { ThemeOptions } from '@yh-ui/theme'
-  ```
-- **Type Template Refs**: Never leave component template refs untyped (`const refVal = ref(null)`). Always use Vue's `InstanceType` utility to extract component exports:
+- Clear all `setTimeout` and `setInterval` handles.
+- Disconnect `ResizeObserver`, `IntersectionObserver`, and `MutationObserver` instances.
+- Remove event listeners bound to `window`, `document`, or custom event emitter nodes:
 
   ```ts
-  import { ref } from 'vue'
-  import { YhTable } from '@yh-ui/components'
+  const onResize = () => {
+    /* ... */
+  }
+  window.addEventListener('resize', onResize)
 
-  const tableRef = ref<InstanceType<typeof YhTable> | null>(null)
+  onUnmounted(() => {
+    window.removeEventListener('resize', onResize)
+  })
   ```
 
-- **Exposed APIs**: Access exposed methods on components strictly through these typed instances (e.g., `tableRef.value?.exportData(...)`, `formRef.value?.validate()`).
-- **Data Models**: Strongly type response objects and row lists using `interface` declarations; never pass `any` into data bindings or request helper promises.
-
-## Testing Expectations
-
-- For reusable components, test props, emitted events, slots, keyboard/focus behavior, and important visual states.
-- For composables, test state transitions and cleanup.
-- For request code, test loading, success, error, retry, and cancellation when present.
-- For Nuxt/SSR examples, check that browser-only code is gated.
+- Clean up active audio/video elements, media recorders, or streaming controllers (like LangChain's `AbortController`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yh-ui/yh-ui-skill",
-  "version": "1.0.51",
+  "version": "1.0.53",
   "description": "YH-UI skill installer for modern AI coding tools",
   "type": "module",
   "bin": {