purity-mcp 0.0.0-stage → 2.0.1

package/README.md

@@ -1,3 +1,263 @@
-# Temporary Holding Version
+# Purity Model Context Protocol (MCP) Server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![MCP Standard](https://img.shields.io/badge/MCP-1.32.2-blue.svg)](https://modelcontextprotocol.io/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ES2022-3178C6.svg)](https://www.typescriptlang.org/)
+[![Vitest](https://img.shields.io/badge/Vitest-passing-6E9F18.svg)](https://vitest.dev/)
+[![Design System](https://img.shields.io/badge/Design-Adwaita%20Glassmorphism-9141ac.svg)](https://gnome.org)
+
+Official **Model Context Protocol (MCP)** server for the **Purity** framework.
+
+This server bridges your AI development environments (**Claude Desktop**, **Cursor**, **Google Antigravity / AGY**, **VS Code / Cline / Roo Code / Continue**, **Windsurf**) directly into Purity's architecture—eliminating hallucinations, enforcing synchronous signals, scaffolding 100% compliant Custom Elements, inspecting project health, and transforming foreign template code in real time.
+
+---
+
+## ⚡ Features at a Glance
+
+| Category | Capability | Description |
+| :--- | :--- | :--- |
+| 🛠️ **Tools** | `purity_scaffold` | Scaffold components, services, pipes, directives, validators, interceptors, behaviors, and pages with tests. |
+| 🔍 **Tools** | `purity_validate` | Deep static analysis auditing signal mutations, path aliases, inline styles, Adwaita tokens, and foreign syntax. |
+| 📊 **Tools** | `purity_inspect_project` | Scans workspace health, discovered components, test coverage, and SCSS architecture. |
+| 📚 **Tools** | `purity_get_docs` | Authoritative reference documentation and runnable code examples across 20+ framework topics. |
+| 🧩 **Tools** | `purity_lookup_component` | Look up signatures, reactive signals, methods, events, and copy-paste HTML for shared UI components. |
+| 🗂️ **Tools** | `purity_list_components` | Browse all built-in UI components and widgets categorized by role. |
+| 🔄 **Tools** | `purity_transform_template` | Converts Angular (`*ngFor`, `*ngIf`, `(click)`, `[(ngModel)]`) or Vue (`v-for`, `v-if`, `@click`, `v-model`) to Purity. |
+| 📖 **Resources** | `purity://docs/*` | Live access to Cheatsheet, Architecture Rules, and Adwaita Design Tokens. |
+| 🎨 **Resources** | `purity://catalog/*` | Live catalog of all UI components (`switch-button`, `modal-view`, `expander`, `popover`, etc.). |
+| 📋 **Resources** | `purity://templates/*` | Dynamic starter templates for any Purity construct. |
+| 💬 **Prompts** | `purity-create-component` | Guided workflow to design and implement production-ready Purity Custom Elements. |
+| 💬 **Prompts** | `purity-review-code` | 12-point architectural and quality audit prompt. |
+| 💬 **Prompts** | `purity-migrate-component`| Seamless migration prompt from React / Angular / Vue to Purity. |
+| 💬 **Prompts** | `purity-debug-reactivity` | Reactivity troubleshooter diagnosing signal access, untracked dependencies, and effect loops. |
+
+---
+
+## 🚀 Quick Setup
+
+### 1. Build the MCP Server
+Inside the repository:
+```bash
+cd AI
+npm install
+npm run build
+```
+
+Verify it runs:
+```bash
+node dist/index.js --help
+```
+
+---
+
+## ⚙️ Environment Configuration
+
+### 1. Claude Desktop
+Add to your `claude_desktop_config.json`:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "purity": {
+      "command": "node",
+      "args": ["/absolute/path/to/purity/AI/dist/index.js"]
+    }
+  }
+}
+```
+
+---
+
+### 2. Cursor
+Add to your project's `.cursor/mcp.json` (or global Cursor MCP configuration):
+
+```json
+{
+  "mcpServers": {
+    "purity": {
+      "command": "node",
+      "args": ["${workspaceFolder}/AI/dist/index.js"]
+    }
+  }
+}
+```
+
+---
+
+### 3. Google Antigravity / AGY
+Add to your MCP server configuration:
+
+```json
+{
+  "mcpServers": {
+    "purity": {
+      "command": "node",
+      "args": ["/run/media/{logged_user}/d/Development/purity/AI/dist/index.js"]
+    }
+  }
+}
+```
+
+---
+
+### 4. VS Code (Cline, Roo Code, Continue)
+In your VS Code extension settings (`cline_mcp_settings.json` or `roo_code_mcp_settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "purity": {
+      "command": "node",
+      "args": ["/absolute/path/to/purity/AI/dist/index.js"]
+    }
+  }
+}
+```
+
+---
+
+### 5. Windsurf
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "purity": {
+      "command": "node",
+      "args": ["/absolute/path/to/purity/AI/dist/index.js"]
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ MCP Tools Reference
+
+### `purity_scaffold`
+Generates complete, production-ready Purity boilerplate files adhering to all architectural standards:
+- **`type`**: `'component'` | `'service'` | `'pipe'` | `'directive'` | `'validator'` | `'interceptor'` | `'behavior'` | `'page'`
+- **`name`**: Artifact name (e.g. `'user-badge'`)
+- **`selector`** *(optional)*: Custom element tag (e.g. `'user-badge'`)
+- **`targetDir`** *(optional)*: Directory to save generated files
+- **`writeToDisk`** *(optional)*: Automatically writes files to disk when `true`
+- **`description`** *(optional)*: Summary description of functionality
+
+*Example Tool Call:*
+```json
+{
+  "type": "component",
+  "name": "shopping-cart",
+  "description": "Interactive checkout tray",
+  "writeToDisk": false
+}
+```
+
+---
+
+### `purity_validate`
+Audits TypeScript, HTML, or SCSS against Purity's 12 non-negotiable rules:
+- **`code`** *(optional)*: Raw code string to validate
+- **`filePath`** *(optional)*: Path to file on disk to validate
+- **`fileName`** *(optional)*: Virtual filename (e.g. `'my.component.ts'`, `'card.component.scss'`)
+
+*Checks Include:*
+- Synchronous signals (`.set()`, `.update()`, no direct `.value` assignment)
+- Strictly zero imports from RxJS, Redux, Zustand, MobX
+- Mandatory path aliases (no `../` relative traversal)
+- Zero inline `style="..."` attributes (modular SCSS with `@use '@styles' as *;`)
+- Adwaita design tokens and KDE Breeze cursor tokens
+- No foreign templates or lifecycle hooks
+- **Prohibition of native event listeners and dispatching** (`addEventListener`, `removeEventListener`, `dispatchEvent`, `CustomEvent`) — communication must use signals/effects (nested) or `@Injectable` services (distant)
+- **Prohibition of query selectors** (`querySelector`, `querySelectorAll`, `getElementById`, etc.) — `@ViewChild` decorators are mandatory
+
+*Returns:*
+- Numerical score (0 to 100)
+- Validation status (`valid: true/false`)
+- Specific violation list with line numbers, code snippets, and exact recommended replacements.
+
+---
+
+### `purity_inspect_project`
+Audits the health and structure of a Purity repository:
+- **`projectRoot`** *(optional)*: Path to project root (defaults to current working directory).
+- Detects registered `@Component`, `@Injectable`, `@Pipe`, `@Directive`, `@Validator`, and `HttpInterceptor` instances.
+- Verifies test coverage (`*.spec.ts`) and SCSS pairing for all components.
+
+---
+
+### `purity_get_docs`
+Provides instant reference documentation and runnable code examples:
+- **`topic`**:
+  `'signals'` | `'components'` | `'templates'` | `'repeaters'` | `'virtual-for'` | `'conditionals'` | `'slots'` | `'di'` | `'http'` | `'interceptors'` | `'pipes'` | `'directives'` | `'validators'` | `'behaviors'` | `'router'` | `'seo'` | `'design-system'` | `'cursors'` | `'styling'` | `'testing'` | `'rules'`
+- **`detail`**: `'full'` | `'summary'` | `'examples'`
+
+---
+
+### `purity_lookup_component`
+Inspects built-in shared UI components and widgets:
+- **`query`**: Component name or selector (e.g. `'switch-button'`, `'modal-view'`, `'popover'`, `'expander'`, `'date-time-picker'`, `'loader'`, `'navigation-menu'`, `'profile-avatar'`, `'radial-context-menu'`, `'analogue-clock'`).
+- Returns tag selector, inputs, signals, methods, events, slots, and copy-paste HTML examples.
+
+---
+
+### `purity_transform_template`
+Translates foreign framework templates into idiomatic Purity templates:
+- Angular `*ngFor="let item of items; let i = index"` ➔ `for="let item, i of items"`
+- Vue `v-for="(item, i) in items"` ➔ `for="let item, i of items"`
+- Angular `*ngIf="isLoggedIn"` ➔ `if="isLoggedIn"`
+- Vue `v-if` / `v-else-if` / `v-else` ➔ `if` / `else-if` / `else`
+- Angular `(click)="save()"` / Vue `@click="save"` ➔ `onclick="save()"`
+- Angular `[(ngModel)]="val"` / Vue `v-model="val"` ➔ `value="{{ val() }}" oninput="val.set(this.value)"`
+- Strips prohibited inline styles and suggests clean SCSS styling.
+
+---
+
+## 📖 MCP Resources Reference
+
+Connect to these resources in your MCP client:
+
+- **`purity://docs/cheatsheet`**: Single-page developer cheat sheet covering signals, components, repeaters, DI, and Adwaita styles.
+- **`purity://docs/architecture`**: Official framework architectural rules and quality constraints.
+- **`purity://docs/design-system`**: Adwaita glassmorphism tokens, corner radii hierarchy, and KDE Breeze cursors.
+- **`purity://catalog/components`**: Markdown table of all shared components and widgets with categories and descriptions.
+- **`purity://templates/{type}`**: Dynamic starter template for `component`, `service`, `pipe`, `directive`, `validator`, `interceptor`, `behavior`, or `page`.
+
+---
+
+## 💬 MCP Prompts Reference
+
+Invoke these prompts in your AI chat:
+
+- **`purity-create-component`**: Guides the AI step-by-step in generating an end-to-end Purity Custom Element with signals, templates, SCSS, and unit tests.
+- **`purity-review-code`**: Directs the AI to run a rigorous 12-point compliance audit against Purity rules (signals, lifecycle, `@ViewChild`, no querySelector, no native addEventListener/dispatchEvent, Adwaita tokens, Breeze cursors).
+- **`purity-migrate-component`**: Instructs the AI to migrate React, Angular, or Vue components into Purity Custom Elements.
+- **`purity-debug-reactivity`**: Directs the AI to analyze reactivity bugs (signal subscriptions, untracked dependencies, effect loops).
+
+---
+
+## 🧪 Testing
+
+The MCP server has its own dedicated Vitest test suite:
+
+```bash
+cd AI
+npm test
+```
+
+Tests cover:
+- File scaffolding for all 8 artifact types
+- Deep static validation checks & scoring
+- Workspace inspection and artifact discovery
+- Documentation retrieval across all topics
+- Component catalog lookup and categorization
+- Template conversion from Angular and Vue syntax
+- Server instantiation and registration
+
+---
+
+## 📄 License
+
+MIT © Purity Framework Team

package/dist/data/component-catalog.d.ts

@@ -0,0 +1,3 @@
+import { ComponentMetadata } from '../types.js';
+export declare const COMPONENT_CATALOG: ComponentMetadata[];
+//# sourceMappingURL=component-catalog.d.ts.map

package/dist/data/component-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-catalog.d.ts","sourceRoot":"","sources":["../../src/data/component-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,iBAAiB,EAAE,iBAAiB,EAwUhD,CAAC"}

package/dist/data/component-catalog.js

@@ -0,0 +1,330 @@
+export const COMPONENT_CATALOG = [
+    {
+        name: 'SwitchButtonComponent',
+        selector: 'switch-button',
+        description: 'Adwaita toggle switch component with fine-grained signals and programmatic control.',
+        category: 'form',
+        inputs: [
+            { name: 'checked', type: 'boolean | string', description: 'Initial checked state (supports boolean or "true")', default: 'false' },
+            { name: 'disabled', type: 'boolean | string', description: 'Whether the switch is interactive', default: 'false' }
+        ],
+        signals: [
+            { name: 'checked', type: 'Signal<boolean>', description: 'Current toggle state signal' },
+            { name: 'disabled', type: 'Signal<boolean>', description: 'Disabled state signal' }
+        ],
+        methods: [
+            { name: 'toggle', signature: 'toggle(): void', description: 'Toggles between checked and unchecked' },
+            { name: 'check', signature: 'check(): void', description: 'Sets state to checked' },
+            { name: 'uncheck', signature: 'uncheck(): void', description: 'Sets state to unchecked' }
+        ],
+        events: [
+            { name: 'change', description: 'Dispatched when state changes with detail: { checked: boolean }' }
+        ],
+        slots: [],
+        htmlExample: `<!-- Declarative attribute sync with parent signal -->
+<switch-button checked="{{ isDarkMode() }}" onchange="handleThemeToggle($event)"></switch-button>`,
+        typescriptExample: `import { Component, signal, ViewChild } from '@purity/core';
+import { SwitchButtonComponent } from '@components/switch-button/switch-button.component';
+
+@Component({ selector: 'settings-view' })
+export class SettingsView {
+  @ViewChild('switch-button')
+  toggleSwitch?: SwitchButtonComponent;
+
+  isDarkMode = signal(true);
+
+  handleThemeToggle(e: CustomEvent) {
+    this.isDarkMode.set(e.detail.checked);
+  }
+}`
+    },
+    {
+        name: 'ModalViewComponent',
+        selector: 'modal-view',
+        description: 'Floating Adwaita dialog with open, close, maximize, backdrop blur, and slotted regions.',
+        category: 'overlay',
+        inputs: [
+            { name: 'is-open', type: 'boolean | string', description: 'Visibility state of the modal', default: 'false' },
+            { name: 'title', type: 'string', description: 'Modal header title text', default: '""' }
+        ],
+        signals: [
+            { name: 'isOpen', type: 'Signal<boolean>', description: 'Modal open/closed reactive state' },
+            { name: 'isMaximized', type: 'Signal<boolean>', description: 'Maximized full-screen state' }
+        ],
+        methods: [
+            { name: 'open', signature: 'open(): void', description: 'Opens the modal dialog' },
+            { name: 'close', signature: 'close(): void', description: 'Closes the modal dialog' },
+            { name: 'toggle', signature: 'toggle(): void', description: 'Toggles open/close state' },
+            { name: 'maximize', signature: 'maximize(): void', description: 'Toggles maximized state' }
+        ],
+        events: [
+            { name: 'modal-opened', description: 'Fired when modal opens' },
+            { name: 'modal-closed', description: 'Fired when modal closes' }
+        ],
+        slots: [
+            { name: 'header', description: 'Custom header content' },
+            { name: 'default', description: 'Body content' },
+            { name: 'footer', description: 'Action buttons / footer' }
+        ],
+        htmlExample: `<modal-view is-open="{{ showDialog() }}" title="Confirm Action">
+  <p>Are you sure you want to proceed?</p>
+  <div slot="footer">
+    <button class="button-default" onclick="showDialog.set(false)">Cancel</button>
+    <button class="button-primary" onclick="confirmAction()">Confirm</button>
+  </div>
+</modal-view>`,
+        typescriptExample: `import { Component, signal } from '@purity/core';
+
+@Component({ selector: 'user-manager' })
+export class UserManager {
+  showDialog = signal(false);
+
+  confirmAction() {
+    this.showDialog.set(false);
+  }
+}`
+    },
+    {
+        name: 'ExpanderComponent',
+        selector: 'expander',
+        description: 'Collapsible accordion card with animated header, toggle methods, and slot support.',
+        category: 'layout',
+        inputs: [
+            { name: 'title', type: 'string', description: 'Title displayed on the expander header', default: '""' },
+            { name: 'is-expanded', type: 'boolean | string', description: 'Whether the expander is currently open', default: 'false' }
+        ],
+        signals: [
+            { name: 'isExpanded', type: 'Signal<boolean>', description: 'Expanded reactive state signal' }
+        ],
+        methods: [
+            { name: 'toggle', signature: 'toggle(): void', description: 'Toggles expanded/collapsed state' },
+            { name: 'expand', signature: 'expand(): void', description: 'Expands the content' },
+            { name: 'collapse', signature: 'collapse(): void', description: 'Collapses the content' }
+        ],
+        events: [
+            { name: 'expander-toggled', description: 'Dispatched with detail: { expanded: boolean }' }
+        ],
+        slots: [
+            { name: 'header', description: 'Optional custom header content' },
+            { name: 'default', description: 'Collapsible body content' }
+        ],
+        htmlExample: `<!-- Direct structural repeater interoperability -->
+<expander for="let section of sections" title="{{ section.name }}" is-expanded="{{ section.isOpen }}">
+  <p>{{ section.details }}</p>
+</expander>`,
+        typescriptExample: `import { Component, signal } from '@purity/core';
+
+@Component({ selector: 'faq-section' })
+export class FaqSection {
+  sections = signal([
+    { name: 'Reactivity', isOpen: true, details: 'Synchronous signals with automatic tracking' },
+    { name: 'Components', isOpen: false, details: 'Native Custom Elements v1' }
+  ]);
+}`
+    },
+    {
+        name: 'PopoverComponent',
+        selector: 'popover',
+        description: 'Anchored floating container with viewport collision auto-flipping and directional placement.',
+        category: 'overlay',
+        inputs: [
+            { name: 'is-open', type: 'boolean | string', description: 'Popover visibility state', default: 'false' },
+            { name: 'target', type: 'string', description: 'CSS selector or ID of anchor trigger element', default: '""' },
+            { name: 'placement', type: '"top" | "bottom" | "left" | "right"', description: 'Preferred anchor placement', default: '"bottom"' }
+        ],
+        signals: [
+            { name: 'isOpen', type: 'Signal<boolean>', description: 'Current open signal' }
+        ],
+        methods: [
+            { name: 'open', signature: 'open(): void', description: 'Shows the popover' },
+            { name: 'close', signature: 'close(): void', description: 'Hides the popover' },
+            { name: 'toggle', signature: 'toggle(): void', description: 'Toggles popover visibility' }
+        ],
+        events: [
+            { name: 'popover-opened', description: 'Dispatched when popover displays' },
+            { name: 'popover-closed', description: 'Dispatched when popover closes' }
+        ],
+        slots: [
+            { name: 'default', description: 'Popover card contents' }
+        ],
+        htmlExample: `<button id="btnOptions" class="button-default" onclick="showOptions.set(!showOptions())">Options</button>
+<popover target="#btnOptions" is-open="{{ showOptions() }}" placement="bottom">
+  <div class="popover-menu">
+    <button onclick="edit()">Edit</button>
+    <button onclick="deleteItem()">Delete</button>
+  </div>
+</popover>`,
+        typescriptExample: `import { Component, signal } from '@purity/core';
+
+@Component({ selector: 'action-bar' })
+export class ActionBar {
+  showOptions = signal(false);
+}`
+    },
+    {
+        name: 'DateTimePickerComponent',
+        selector: 'date-time-picker',
+        description: 'Reactive calendar and time selector with body teleportation and Adwaita styling.',
+        category: 'form',
+        inputs: [
+            { name: 'value', type: 'string', description: 'ISO date string or current value', default: '""' },
+            { name: 'format', type: 'string', description: 'Date format string (e.g. "YYYY-MM-DD")', default: '"YYYY-MM-DD"' },
+            { name: 'mode', type: '"date" | "time" | "datetime"', description: 'Picker selection mode', default: '"date"' }
+        ],
+        signals: [
+            { name: 'selectedDate', type: 'Signal<Date | null>', description: 'Currently selected date signal' }
+        ],
+        methods: [
+            { name: 'open', signature: 'open(): void', description: 'Opens the calendar popup' },
+            { name: 'close', signature: 'close(): void', description: 'Closes the calendar popup' },
+            { name: 'setDate', signature: 'setDate(date: Date): void', description: 'Programmatically selects a date' }
+        ],
+        events: [
+            { name: 'date-change', description: 'Dispatched with detail: { date: Date, formatted: string }' }
+        ],
+        slots: [],
+        htmlExample: `<date-time-picker value="{{ eventDate() }}" ondate-change="handleDateSelect($event)"></date-time-picker>`,
+        typescriptExample: `import { Component, signal } from '@purity/core';
+
+@Component({ selector: 'event-form' })
+export class EventForm {
+  eventDate = signal('2026-10-28');
+  handleDateSelect(e: CustomEvent) {
+    this.eventDate.set(e.detail.formatted);
+  }
+}`
+    },
+    {
+        name: 'LoaderComponent',
+        selector: 'loader-component',
+        description: 'Glassmorphic spinner and progress indicator with show/hide methods and message signal.',
+        category: 'overlay',
+        inputs: [
+            { name: 'is-loading', type: 'boolean | string', description: 'Loading state', default: 'false' },
+            { name: 'message', type: 'string', description: 'Optional status message text', default: '""' }
+        ],
+        signals: [
+            { name: 'isLoading', type: 'Signal<boolean>', description: 'Loading state signal' },
+            { name: 'message', type: 'Signal<string>', description: 'Current message signal' }
+        ],
+        methods: [
+            { name: 'show', signature: 'show(message?: string): void', description: 'Activates loader with optional message' },
+            { name: 'hide', signature: 'hide(): void', description: 'Hides loader' }
+        ],
+        events: [],
+        slots: [],
+        htmlExample: `<loader-component is-loading="{{ isFetching() }}" message="Syncing records..."></loader-component>`,
+        typescriptExample: `import { Component, signal } from '@purity/core';
+
+@Component({ selector: 'data-grid' })
+export class DataGrid {
+  isFetching = signal(false);
+}`
+    },
+    {
+        name: 'ProfileAvatarComponent',
+        selector: 'profile-avatar',
+        description: 'User avatar displaying image, fallback initials, presence status badge, and custom sizing.',
+        category: 'widget',
+        inputs: [
+            { name: 'src', type: 'string', description: 'Avatar image URL', default: '""' },
+            { name: 'name', type: 'string', description: 'User full name for initial computation', default: '""' },
+            { name: 'status', type: '"online" | "offline" | "busy" | "away"', description: 'Presence indicator status', default: '"offline"' },
+            { name: 'size', type: '"sm" | "md" | "lg" | "xl"', description: 'Avatar dimensions', default: '"md"' }
+        ],
+        signals: [
+            { name: 'status', type: 'Signal<string>', description: 'Presence status signal' }
+        ],
+        methods: [],
+        events: [],
+        slots: [],
+        htmlExample: `<profile-avatar src="{{ user().avatar }}" name="{{ user().fullName }}" status="online" size="md"></profile-avatar>`,
+        typescriptExample: `import { Component, signal } from '@purity/core';
+
+@Component({ selector: 'user-badge' })
+export class UserBadge {
+  user = signal({ fullName: 'Ada Lovelace', avatar: '' });
+}`
+    },
+    {
+        name: 'RadialContextMenuComponent',
+        selector: 'radial-context-menu',
+        description: 'Circular context menu with pie segments, icon badges, submenus, and mouse trigger.',
+        category: 'navigation',
+        inputs: [
+            { name: 'radius', type: 'number', description: 'Outer circle radius in pixels', default: '120' }
+        ],
+        signals: [
+            { name: 'isOpen', type: 'Signal<boolean>', description: 'Menu open signal' }
+        ],
+        methods: [
+            { name: 'openAt', signature: 'openAt(x: number, y: number): void', description: 'Opens menu at specific viewport coordinates' },
+            { name: 'close', signature: 'close(): void', description: 'Closes radial menu' }
+        ],
+        events: [
+            { name: 'item-selected', description: 'Dispatched with detail: { action: string, data?: any }' }
+        ],
+        slots: [
+            { name: 'default', description: 'Menu item icons and actions' }
+        ],
+        htmlExample: `<div oncontextmenu="handleContextMenu($event)">
+  Right click here
+  <radial-context-menu id="radialMenu"></radial-context-menu>
+</div>`,
+        typescriptExample: `import { Component, ViewChild } from '@purity/core';
+import { RadialContextMenuComponent } from '@components/radial-context-menu/radial-context-menu.component';
+
+@Component({ selector: 'canvas-view' })
+export class CanvasView {
+  @ViewChild('#radialMenu')
+  radialMenu?: RadialContextMenuComponent;
+
+  handleContextMenu(e: MouseEvent) {
+    e.preventDefault();
+    this.radialMenu?.openAt(e.clientX, e.clientY);
+  }
+}`
+    },
+    {
+        name: 'NavigationMenuComponent',
+        selector: 'navigation-menu',
+        description: 'Draggable floating radial navigation bar with quick routes, glassmorphic backdrop, and Breeze cursors.',
+        category: 'navigation',
+        inputs: [],
+        signals: [
+            { name: 'isExpanded', type: 'Signal<boolean>', description: 'Menu expansion state signal' }
+        ],
+        methods: [
+            { name: 'toggle', signature: 'toggle(): void', description: 'Toggles expanded floating items' }
+        ],
+        events: [],
+        slots: [],
+        htmlExample: `<navigation-menu></navigation-menu>`,
+        typescriptExample: `import { Component } from '@purity/core';
+
+@Component({ selector: 'app-root' })
+export class AppRoot {}`
+    },
+    {
+        name: 'AnalogueClockComponent',
+        selector: 'analogue-clock',
+        description: '2D Canvas analogue clock widget with smooth sweep hands, configurable theme, and timezone support.',
+        category: 'widget',
+        inputs: [
+            { name: 'size', type: 'number', description: 'Canvas dimension in pixels', default: '200' },
+            { name: 'timezone', type: 'string', description: 'IANA timezone string (e.g. "UTC", "America/New_York")', default: '"local"' }
+        ],
+        signals: [
+            { name: 'currentTime', type: 'Signal<Date>', description: 'Current ticking clock time' }
+        ],
+        methods: [],
+        events: [],
+        slots: [],
+        htmlExample: `<analogue-clock size="240" timezone="UTC"></analogue-clock>`,
+        typescriptExample: `import { Component } from '@purity/core';
+
+@Component({ selector: 'clock-dashboard' })
+export class ClockDashboard {}`
+    }
+];
+//# sourceMappingURL=component-catalog.js.map

package/dist/data/component-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-catalog.js","sourceRoot":"","sources":["../../src/data/component-catalog.ts"],"names":[],"mappings":"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"}

package/dist/data/documentation.d.ts

@@ -0,0 +1,10 @@
+import { DocTopic } from '../types.js';
+export interface DocEntry {
+    topic: DocTopic;
+    title: string;
+    summary: string;
+    content: string;
+    examples: string[];
+}
+export declare const DOCUMENTATION: Record<DocTopic, DocEntry>;
+//# sourceMappingURL=documentation.d.ts.map

package/dist/data/documentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentation.d.ts","sourceRoot":"","sources":["../../src/data/documentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAooBpD,CAAC"}