nuxtseo-layer-devtools 0.4.5 → 0.5.1

package/skills/devtools-layer-skilld/SKILL.md

@@ -9,6 +9,14 @@ Shared Nuxt layer providing components, composables, and a design system for all
 
 **Source:** `packages/devtools-layer/` (published as `nuxtseo-layer-devtools`)
 
+## Available Libraries
+
+The layer registers these Nuxt modules, so all consumers have them available without extra config:
+
+- **`@nuxt/ui`** (v4): Full component library. Use `UButton`, `UBadge`, `UIcon`, `UInput`, `UTooltip`, `UApp`, etc. freely in devtools clients. Default variants configured via `app.config.ts` (primary: green, buttons: ghost/neutral/sm, badges: subtle/neutral/xs, tooltips: zero delay).
+- **`@vueuse/nuxt`**: All VueUse composables auto imported.
+- **Shiki**: Syntax highlighting via the layer's `loadShiki` / `useRenderCodeHighlight` composables.
+
 ## Architecture
 
 1. **nuxtseo-shared/devtools** (`packages/shared/src/devtools.ts`): `setupDevToolsUI()` registers iframe tab, handles dev proxy + production sirv
@@ -20,13 +28,14 @@ Shared Nuxt layer providing components, composables, and a design system for all
 1. ALWAYS extend `nuxtseo-layer-devtools` in client/nuxt.config.ts
 2. ALWAYS create `client/composables/rpc.ts` that calls `useDevtoolsConnection()`
 3. ALWAYS use layer components over custom HTML: `DevtoolsSection` not custom details, `DevtoolsKeyValue` not custom tables, `DevtoolsSnippet` not custom code blocks. Use `KeyValueItem.code` for inline code rendering instead of separate snippets
-4. NEVER add custom CSS that duplicates what the layer provides
-5. NEVER enable SSR in the client (it runs in an iframe)
-6. ALWAYS disable the module itself in the client nuxt config (e.g. `robots: false`)
-7. ALWAYS guard devtools setup with `if (nuxt.options.dev)` in module.ts
-8. ALWAYS use `useAsyncData` with `watch: [refreshTime]` for reactive data fetching
-9. Use Carbon icons consistently (prefix: `carbon:`)
-10. Debug server routes ONLY registered in dev mode
+4. ALWAYS use `@nuxt/ui` components (`UButton`, `UInput`, `UBadge`, `UIcon`, `UTooltip`, etc.) for interactive elements. Never add a custom button, input, badge, or tooltip when a Nuxt UI component exists.
+5. NEVER add custom CSS that duplicates what the layer or Nuxt UI provides
+6. NEVER enable SSR in the client (it runs in an iframe)
+7. ALWAYS disable the module itself in the client nuxt config (e.g. `robots: false`)
+8. ALWAYS guard devtools setup with `if (nuxt.options.dev)` in module.ts
+9. ALWAYS use `useAsyncData` with `watch: [refreshTime]` for reactive data fetching
+10. Use Carbon icons consistently (prefix: `carbon:`)
+11. Debug server routes ONLY registered in dev mode
 
 ## Required File Structure
 
@@ -99,7 +108,7 @@ watch(data, () => {
 </script>
 
 <template>
-  <DevtoolsLayout v-model:active-tab="activeTab" title="Name" icon="carbon:icon" :nav-items="navItems" github-url="..." :loading @refresh="refreshSources">
+  <DevtoolsLayout v-model:active-tab="activeTab" title="Name" icon="carbon:icon" module-name="nuxt-<module>" :nav-items="navItems" github-url="..." :loading @refresh="refreshSources">
     <DevtoolsLoading v-if="loading" />
     <template v-else-if="activeTab === 'overview'">
       <!-- content -->

package/skills/devtools-layer-skilld/reference.md

@@ -1,16 +1,41 @@
 # Devtools Layer API Reference
 
+## Nuxt UI (available to all consumers)
+
+The layer registers `@nuxt/ui` v4, so all Nuxt UI components are auto imported. Use them freely:
+
+- `UButton`, `UInput`, `UTextarea`, `USelect`, `UCheckbox`, `UToggle`, `URadio`
+- `UBadge`, `UIcon`, `UTooltip`, `UPopover`, `UModal`, `UDrawer`
+- `UApp` (wraps the root, already used by `DevtoolsLayout`)
+- `UCard`, `UAccordion`, `UTabs`, `UDropdownMenu`
+
+Default variants via `app.config.ts`: primary green, neutral neutral. Buttons: ghost/neutral/sm. Badges: subtle/neutral/xs. Tooltips: zero delay.
+
+Icons use the Iconify format. Convention: `carbon:*` prefix for consistency.
+
 ## Components (auto imported)
 
 ### Layout & Structure
 
 | Component | Props | Key Slots | Purpose |
 |---|---|---|---|
-| `DevtoolsLayout` | `title`, `icon`, `version?`, `navItems`, `githubUrl`, `loading?` | `actions`, default | Main shell with header, tabs, refresh |
-| `DevtoolsPanel` | `title?` | `header`, `actions`, default | Card container with close button |
+| `DevtoolsLayout` | `title`, `icon`, `version?`, `moduleName?`, `npmPackage?`, `navItems: DevtoolsNavItem[]`, `githubUrl`, `loading?` | `actions`, default | Main shell with header, tabs, refresh, module splash, standalone mode, production mode. Pass `npmPackage` to enable update check indicator on version badge. |
+| `DevtoolsPanel` | `title?`, `icon?`, `closable?` (false), `padding?` (true) | `header`, `actions`, default | Card container. Emits `close` when closable button clicked. |
 | `DevtoolsToolbar` | `variant` ('default'\|'minimal') | default | Horizontal toolbar strip |
 | `DevtoolsSection` | `icon?`, `text?`, `description?`, `collapse?`, `open?`, `padding?` | `text`, `description`, `actions`, `details`, default, `footer` | Collapsible details/summary block |
 
+### DevtoolsNavItem Interface
+
+```ts
+interface DevtoolsNavItem {
+  value: string
+  to?: string // If set, renders as NuxtLink (route navigation)
+  icon: string
+  label: string
+  devOnly?: boolean // Hidden in production mode
+}
+```
+
 ### Feedback & States
 
 | Component | Props | Key Slots | Purpose |
@@ -31,6 +56,16 @@
 | `DevtoolsSnippet` | `label?`, `code`, `lang` ('js'\|'json'\|'xml') | `header` | Code block with header, copy, max 300px scroll |
 | `OCodeBlock` | `code`, `lang`, `lines?`, `transformRendered?` | none | Shiki syntax highlighted pre |
 | `DevtoolsDocs` | `url` | none | Full height iframe |
+| `DevtoolsPlaygrounds` | `moduleName` | none | StackBlitz playground links with UTabs for variant selection. Reusable standalone or inside other components. Shows nothing if module has no playgrounds. |
+| `DevtoolsTroubleshooting` | `moduleName`, `version?` | none | Guided troubleshooting section: clear .nuxt, debug mode, create repro (with playgrounds), report issue. Shows all installed module versions with copy for GitHub issues. |
+
+### Module Navigation
+
+| Component | Props | Key Slots | Purpose |
+|---|---|---|---|
+| `DevtoolsModuleSplash` | `currentModule?` | none | Modal overlay showing all Nuxt SEO modules with install status, switch between modules, Pro section |
+| `DevtoolsStandaloneConnect` | none | none | Connection form for standalone mode (outside devtools iframe) |
+| `NuxtSeoLogo` | none | none | Nuxt SEO brand logo SVG |
 
 ### KeyValueItem Interface
 
@@ -73,6 +108,11 @@ const host: ComputedRef<string>
 const refreshSources: () => void // Debounced 200ms
 const slowRefreshSources: () => void // Debounced 1000ms
 
+// Standalone mode (running outside devtools iframe)
+const standaloneUrl: Ref<string> // localStorage persisted
+const isConnected: Ref<boolean>
+const isStandalone: ComputedRef<boolean> // true when not connected but has standaloneUrl
+
 // Production preview mode
 const previewSource: Ref<'local' | 'production'> // localStorage persisted
 const productionUrl: Ref<string>
@@ -80,6 +120,21 @@ const hasProductionUrl: ComputedRef<boolean>
 const isProductionMode: ComputedRef<boolean>
 ```
 
+### Modules (`composables/modules.ts`)
+
+```ts
+interface SeoModuleInfo { name: string, title: string, icon: string, route: string }
+interface SeoModuleCatalogEntry extends SeoModuleInfo { description: string, installed: boolean, npm: string, pro?: boolean, playgrounds?: Record<string, string> }
+
+const installedModules: Ref<SeoModuleInfo[]>
+const showModuleSplash: Ref<boolean>
+const moduleCatalog: ComputedRef<SeoModuleCatalogEntry[]>
+
+function fetchInstalledModules(): void // Called by DevtoolsLayout automatically
+function findModuleByName(moduleName: string): SeoModuleCatalogEntry | undefined // Look up module info by name
+function switchToModule(moduleName: string): void // Navigate devtools iframe to another module
+```
+
 ### Shiki (`composables/shiki.ts`)
 
 ```ts
@@ -93,9 +148,21 @@ function useRenderCodeHighlight(code: MaybeRef<string>, lang: string): ComputedR
 function useCopy(timeout?: number): { copy: (text: string) => Promise<void>, copied: Ref<boolean> }
 ```
 
+### Update Check (`composables/update-check.ts`)
+
+```ts
+function useModuleUpdate(npmPackage: string | undefined, currentVersion: string | undefined): {
+  hasUpdate: ComputedRef<boolean>
+  latestVersion: ComputedRef<string | undefined>
+  info: ComputedRef<ModuleUpdateInfo | undefined>
+}
+```
+
+Fetches latest version from npm registry. Results are cached per package name. Already integrated into `DevtoolsLayout` when `npmPackage` prop is provided.
+
 ## CSS Design System
 
-Do NOT add custom CSS unless layer components are insufficient.
+Do NOT add custom CSS unless layer components or Nuxt UI are insufficient.
 
 ### Semantic Variables
 
@@ -105,10 +172,6 @@ Do NOT add custom CSS unless layer components are insufficient.
 
 `.glass` (backdrop blur), `.gradient-bg` (green/blue radials), `.card` (elevated hover), `.code-block`, `.status-enabled/.status-disabled`, `.link-external` (with arrow), `.hint-callout`, `.panel-grids`, `.animate-fade-up/.scale-in/.spin`, `.stagger-children`, `.devtools-main-content` (max-width 80rem centered container)
 
-### Nuxt UI Defaults (app.config.ts)
-
-Primary: green, Neutral: neutral. Buttons: ghost/neutral/sm. Badges: subtle/neutral/xs. Tooltips: zero delay.
-
 ## Common Patterns
 
 ### Production Mode Data Fetching