@agiflowai/style-system 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,1368 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+
+//#region src/server/index.d.ts
+
+declare function createServer(themePath?: string): Server;
+//#endregion
+//#region src/config.d.ts
+/**
+ * App-specific design system configuration
+ *
+ * This configuration is read from each app's project.json file
+ * under the "style-system" key.
+ */
+/**
+ * Design system configuration schema
+ */
+interface DesignSystemConfig {
+  /** Type of design system (tailwind or shadcn) */
+  type: 'tailwind' | 'shadcn';
+  /** Path to tailwind config file (optional) */
+  tailwindConfig?: string;
+  /** Path to theme provider component with default export */
+  themeProvider: string;
+  /** Path to root component for wrapping rendered components (optional) */
+  rootComponent?: string;
+  /** CSS file paths to include (optional) */
+  cssFiles?: string[];
+  /** Component library path (for shadcn) */
+  componentLibrary?: string;
+  /** Path to theme CSS file for Tailwind class extraction (optional) */
+  themePath?: string;
+  /**
+   * Tags that identify shared/design system components.
+   * Components with these tags are considered shared and reusable.
+   * Default: ['style-system']
+   */
+  sharedComponentTags?: string[];
+}
+//#endregion
+//#region src/services/StoriesIndexService/types.d.ts
+/**
+ * StoriesIndexService Types
+ *
+ * Type definitions for the StoriesIndexService service.
+ */
+/**
+ * Story meta information from default export
+ */
+interface StoryMeta {
+  /** Story title (e.g., "Components/Button") */
+  title: string;
+  /** Reference to the component */
+  component?: unknown;
+  /** Story tags for filtering */
+  tags?: string[];
+  /** Story parameters */
+  parameters?: Record<string, unknown>;
+  /** Arg type definitions */
+  argTypes?: Record<string, unknown>;
+}
+/**
+ * Component information extracted from story files
+ */
+interface ComponentInfo {
+  /** Full title from meta (e.g., "Components/Button") */
+  title: string;
+  /** Absolute path to story file */
+  filePath: string;
+  /** SHA256 hash of file content for cache invalidation */
+  fileHash: string;
+  /** Tags from story meta */
+  tags: string[];
+  /** Names of exported stories */
+  stories: string[];
+  /** Full story meta object */
+  meta: StoryMeta;
+  /** Component description extracted from file header JSDoc or meta.parameters.docs.description */
+  description?: string;
+}
+//#endregion
+//#region src/services/StoriesIndexService/StoriesIndexService.d.ts
+
+/**
+ * StoriesIndexService handles indexing and querying Storybook story files.
+ *
+ * Provides methods for scanning story files, extracting metadata using AST parsing,
+ * and querying components by tags, title, or name.
+ *
+ * @example
+ * ```typescript
+ * const service = new StoriesIndexService();
+ * await service.initialize();
+ * const components = service.getAllComponents();
+ * const button = service.findComponentByName('Button');
+ * ```
+ */
+/**
+ * Result of initialization with success/failure statistics.
+ */
+interface InitializationResult {
+  /** Total number of story files found */
+  totalFiles: number;
+  /** Number of successfully indexed files */
+  successCount: number;
+  /** Number of files that failed to index */
+  failureCount: number;
+  /** List of files that failed with their error messages */
+  failures: Array<{
+    filePath: string;
+    error: string;
+  }>;
+}
+declare class StoriesIndexService {
+  private componentIndex;
+  private monorepoRoot;
+  private initialized;
+  /** Last initialization result for error reporting */
+  private lastInitResult;
+  /**
+   * Creates a new StoriesIndexService instance
+   */
+  constructor();
+  /**
+   * Initialize the index by scanning all .stories files.
+   * @returns Initialization result with success/failure statistics
+   */
+  initialize(): Promise<InitializationResult>;
+  /**
+   * Get the last initialization result.
+   * @returns Initialization result or null if not initialized
+   */
+  getLastInitResult(): InitializationResult | null;
+  /**
+   * Index a single story file using @storybook/csf-tools.
+   *
+   * Uses the official Storybook CSF parser which handles all CSF formats
+   * including TypeScript satisfies/as expressions.
+   */
+  private indexStoryFile;
+  /**
+   * Extract component description from file header JSDoc or meta.parameters.docs.description.
+   *
+   * Priority:
+   * 1. meta.parameters.docs.description.component (Storybook standard)
+   * 2. File header JSDoc comment (first block comment in file)
+   *
+   * @param content - Raw file content
+   * @param meta - Parsed meta object from csf-tools
+   * @returns Description string or undefined
+   */
+  private extractDescription;
+  /**
+   * Hash file content for cache invalidation
+   */
+  private hashContent;
+  /**
+   * Get all components filtered by tags
+   * @param tags - Optional array of tags to filter by
+   * @returns Array of matching components
+   */
+  getComponentsByTags(tags?: string[]): ComponentInfo[];
+  /**
+   * Get component by title
+   * @param title - Exact title to match (e.g., "Components/Button")
+   * @returns Component info or undefined
+   */
+  getComponentByTitle(title: string): ComponentInfo | undefined;
+  /**
+   * Find component by partial name match
+   * @param name - Partial name to search for
+   * @returns First matching component or undefined
+   */
+  findComponentByName(name: string): ComponentInfo | undefined;
+  /**
+   * Refresh a specific file if it has changed
+   * @param filePath - Absolute path to story file
+   * @returns True if file was updated, false if unchanged
+   */
+  refreshFile(filePath: string): Promise<boolean>;
+  /**
+   * Get all indexed components
+   * @returns Array of all component info objects
+   */
+  getAllComponents(): ComponentInfo[];
+  /**
+   * Clear the index (useful for testing)
+   */
+  clear(): void;
+  /**
+   * Get all unique tags from indexed components
+   * @returns Sorted array of unique tag names
+   */
+  getAllTags(): string[];
+}
+//#endregion
+//#region src/services/BundlerService/types.d.ts
+/**
+ * BundlerService Types
+ *
+ * Type definitions for the BundlerService abstraction.
+ * Supports multiple bundler implementations (Vite, Webpack, etc.)
+ * and multiple frameworks (React, Vue, etc.).
+ */
+/**
+ * Options for rendering a component through the bundler.
+ *
+ * @example
+ * ```typescript
+ * const options: RenderOptions = {
+ *   componentPath: '/path/to/Button.stories.tsx',
+ *   storyName: 'Primary',
+ *   appPath: 'apps/my-app',
+ *   darkMode: true,
+ * };
+ * ```
+ */
+interface RenderOptions$1 {
+  /** Absolute path to the component story file */
+  componentPath: string;
+  /** Name of the story to render */
+  storyName: string;
+  /** Optional args to pass to the story */
+  args?: Record<string, unknown>;
+  /** Path to theme provider */
+  themePath?: string;
+  /** Whether to use dark mode */
+  darkMode?: boolean;
+  /** Path to the app directory */
+  appPath: string;
+  /** CSS files to import */
+  cssFiles?: string[];
+  /** Path to root component wrapper */
+  rootComponent?: string;
+}
+/**
+ * Result from starting a dev server.
+ */
+interface DevServerResult {
+  /** URL where the dev server is accessible */
+  url: string;
+  /** Port the server is listening on */
+  port: number;
+}
+/**
+ * Result from serving a component through dev server.
+ */
+interface ServeComponentResult {
+  /** URL to access the rendered component */
+  url: string;
+  /** Path to the generated HTML file (optional if served from memory) */
+  htmlFilePath?: string;
+  /** The generated HTML content (optional if served from memory) */
+  htmlContent?: string;
+}
+/**
+ * Result from pre-rendering a component to static HTML.
+ */
+interface PrerenderResult {
+  /** Path to the generated static HTML file */
+  htmlFilePath: string;
+}
+/**
+ * Configuration for BundlerService implementations.
+ */
+interface BundlerServiceConfig {
+  /** Enable verbose logging @default false */
+  verbose?: boolean;
+}
+//#endregion
+//#region src/services/BundlerService/BaseBundlerService.d.ts
+/**
+ * Abstract base class for bundler service implementations.
+ *
+ * Subclasses must implement the abstract methods to provide
+ * bundler-specific (Vite, Webpack, etc.) and framework-specific
+ * (React, Vue, etc.) component rendering logic.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomBundlerService extends BaseBundlerService {
+ *   async startDevServer(appPath: string): Promise<DevServerResult> {
+ *     // Custom dev server logic
+ *   }
+ *   // ... implement other abstract methods
+ * }
+ * ```
+ */
+declare abstract class BaseBundlerService {
+  protected config: BundlerServiceConfig;
+  /**
+   * Creates a new bundler service instance.
+   * @param config - Service configuration options
+   */
+  constructor(config?: BundlerServiceConfig);
+  /**
+   * Get the bundler identifier for this service.
+   * @returns Bundler identifier string (e.g., 'vite', 'webpack')
+   */
+  abstract getBundlerId(): string;
+  /**
+   * Get the framework identifier for this service.
+   * @returns Framework identifier string (e.g., 'react', 'vue')
+   */
+  abstract getFrameworkId(): string;
+  /**
+   * Start a dev server for hot reload and caching.
+   *
+   * @param appPath - Absolute or relative path to the app directory
+   * @returns Promise resolving to server URL and port
+   * @throws Error if server fails to start
+   */
+  abstract startDevServer(appPath: string): Promise<DevServerResult>;
+  /**
+   * Serve a component dynamically through the dev server.
+   *
+   * @param options - Component rendering options
+   * @returns Promise resolving to the component URL and HTML file path
+   * @throws Error if dev server is not running or rendering fails
+   */
+  abstract serveComponent(options: RenderOptions$1): Promise<ServeComponentResult>;
+  /**
+   * Pre-render a component to a static HTML file.
+   *
+   * @param options - Component rendering options
+   * @returns Promise resolving to the HTML file path
+   * @throws Error if build fails
+   */
+  abstract prerenderComponent(options: RenderOptions$1): Promise<PrerenderResult>;
+  /**
+   * Check if the dev server is running.
+   * @returns True if server is running
+   */
+  abstract isServerRunning(): boolean;
+  /**
+   * Get the current server URL.
+   * @returns Server URL or null if not running
+   */
+  abstract getServerUrl(): string | null;
+  /**
+   * Get the current server port.
+   * @returns Server port or null if not running
+   */
+  abstract getServerPort(): number | null;
+  /**
+   * Get the current app path being served.
+   * @returns App path or null if not running
+   */
+  abstract getCurrentAppPath(): string | null;
+  /**
+   * Clean up server resources and reset state.
+   */
+  abstract cleanup(): Promise<void>;
+}
+//#endregion
+//#region src/services/BundlerService/ViteReactBundlerService.d.ts
+/**
+ * ViteReactBundlerService provides Vite + React bundling for component rendering.
+ *
+ * This is the default implementation of BaseBundlerService that uses Vite
+ * as the bundler and React as the framework for rendering components.
+ *
+ * @example
+ * ```typescript
+ * const service = ViteReactBundlerService.getInstance();
+ * await service.startDevServer('apps/my-app');
+ * const { url } = await service.serveComponent({
+ *   componentPath: '/path/to/Button.stories.tsx',
+ *   storyName: 'Primary',
+ *   appPath: 'apps/my-app'
+ * });
+ * ```
+ */
+declare class ViteReactBundlerService extends BaseBundlerService {
+  private static instance;
+  private server;
+  private monorepoRoot;
+  private serverUrl;
+  private serverPort;
+  private currentAppPath;
+  private storyConfigs;
+  /** Timestamps for when each story config was created, used for cleanup */
+  private storyConfigTimestamps;
+  /** Promise that resolves when server startup completes, prevents race conditions */
+  private serverStartPromise;
+  /**
+   * Creates a new ViteReactBundlerService instance.
+   * Use getInstance() for singleton access.
+   * @param config - Service configuration options
+   */
+  constructor(config?: BundlerServiceConfig);
+  /**
+   * Get the singleton instance of ViteReactBundlerService.
+   * Singleton pattern ensures only one dev server runs at a time,
+   * preventing port conflicts and resource duplication.
+   * @returns The singleton ViteReactBundlerService instance
+   */
+  static getInstance(): ViteReactBundlerService;
+  /**
+   * Reset the singleton instance.
+   * This is primarily used in testing to ensure a fresh instance.
+   * @example
+   * ```typescript
+   * afterEach(() => {
+   *   ViteReactBundlerService.resetInstance();
+   * });
+   * ```
+   */
+  static resetInstance(): void;
+  /**
+   * Get the bundler identifier.
+   * @returns The bundler ID string ('vite')
+   */
+  getBundlerId(): string;
+  /**
+   * Get the framework identifier.
+   * @returns The framework ID string ('react')
+   */
+  getFrameworkId(): string;
+  /**
+   * Get the current server URL.
+   * @returns Server URL or null if not running
+   */
+  getServerUrl(): string | null;
+  /**
+   * Get the current server port.
+   * @returns Server port or null if not running
+   */
+  getServerPort(): number | null;
+  /**
+   * Check if the dev server is running.
+   * @returns True if server is running
+   */
+  isServerRunning(): boolean;
+  /**
+   * Get the current app path being served.
+   * @returns App path or null if not running
+   */
+  getCurrentAppPath(): string | null;
+  /**
+   * Start a Vite dev server for hot reload and caching.
+   * Handles concurrent calls by returning the same promise if server is already starting.
+   * @param appPath - Absolute or relative path to the app directory
+   * @returns Promise resolving to server URL and port
+   * @throws Error if server fails to start
+   */
+  startDevServer(appPath: string): Promise<DevServerResult>;
+  /**
+   * Internal method that performs the actual server startup.
+   * @param resolvedAppPath - Resolved absolute path to the app directory
+   * @returns Promise resolving to server URL and port
+   */
+  private doStartDevServer;
+  /**
+   * Serve a component dynamically through the dev server.
+   * @param options - Component rendering options
+   * @returns Promise resolving to the component URL and HTML file path
+   * @throws Error if dev server is not running or file operations fail
+   */
+  serveComponent(options: RenderOptions$1): Promise<ServeComponentResult>;
+  /**
+   * Pre-render a component to a static HTML file.
+   * @param options - Component rendering options
+   * @returns Promise resolving to the HTML file path
+   * @throws Error if build fails
+   */
+  prerenderComponent(options: RenderOptions$1): Promise<PrerenderResult>;
+  /**
+   * Clean up server resources and reset state.
+   * Closes the Vite dev server if running.
+   *
+   * Note: Errors during server close are intentionally logged but not re-thrown.
+   * This ensures cleanup always completes and state is reset, even if the server
+   * is in an unexpected state. Callers should not depend on cleanup failure detection.
+   */
+  cleanup(): Promise<void>;
+  /**
+   * Clean up stale story configs to prevent memory leaks.
+   * Removes configs that are older than STORY_CONFIG_MAX_AGE_MS or
+   * when the number of configs exceeds STORY_CONFIG_MAX_COUNT.
+   */
+  private cleanupStaleStoryConfigs;
+  /**
+   * Generate a wrapper CSS file with @source directive for Tailwind v4.
+   * This tells Tailwind where to scan for class names when building from .tmp directory.
+   * @param appPath - Absolute path to the app directory
+   * @param cssFiles - Array of CSS file paths to import
+   * @returns Generated CSS content with @source directive
+   */
+  private generateWrapperCss;
+  /**
+   * Generate the React entry file content for rendering a story.
+   * @param options - Build options including component path and story name
+   * @returns Generated TypeScript/JSX entry file content
+   */
+  private generateEntryFile;
+  /**
+   * Generate the HTML template for component preview.
+   * @param entryFileName - Name of the entry file to include
+   * @param darkMode - Whether to add dark mode class to HTML
+   * @returns Generated HTML template string
+   */
+  private generateHtmlTemplate;
+  private buildComponent;
+}
+//#endregion
+//#region src/services/BundlerService/BundlerServiceFactory.d.ts
+/**
+ * Default factory that creates a ViteReactBundlerService instance.
+ * Uses the singleton pattern to ensure only one dev server runs at a time.
+ *
+ * @returns The singleton ViteReactBundlerService instance
+ *
+ * @example
+ * ```typescript
+ * import { createDefaultBundlerService } from './BundlerServiceFactory';
+ *
+ * const bundler = createDefaultBundlerService();
+ * await bundler.startDevServer('apps/my-app');
+ * ```
+ */
+declare function createDefaultBundlerService(): BaseBundlerService;
+/**
+ * Get bundler service based on toolkit.yaml configuration.
+ *
+ * If a custom service is configured in toolkit.yaml under style-system.bundler.customService,
+ * it will be dynamically loaded. Otherwise, returns the default ViteReactBundlerService.
+ *
+ * The custom service module must:
+ * - Export a class that extends BaseBundlerService as default export, OR
+ * - Export an instance of BaseBundlerService as default export, OR
+ * - Export a getInstance() function that returns a BaseBundlerService
+ *
+ * @returns Promise resolving to a bundler service instance
+ *
+ * @example
+ * ```typescript
+ * // In toolkit.yaml:
+ * // style-system:
+ * //   bundler:
+ * //     customService: packages/my-app/src/bundler/CustomBundlerService.ts
+ *
+ * const bundler = await getBundlerServiceFromConfig();
+ * await bundler.startDevServer('apps/my-app');
+ * ```
+ */
+declare function getBundlerServiceFromConfig(): Promise<BaseBundlerService>;
+//#endregion
+//#region src/services/ComponentRendererService/types.d.ts
+/**
+ * Factory function type for creating bundler service instances.
+ * Allows users to provide custom bundler implementations.
+ */
+type BundlerFactory = () => BaseBundlerService;
+/**
+ * Options for rendering a component
+ */
+interface RenderOptions {
+  /** The story variant name to render (e.g., 'Primary', 'Secondary') */
+  storyName?: string;
+  /** Component props/arguments to pass to the story */
+  args?: Record<string, unknown>;
+  /** Whether to render in dark mode theme */
+  darkMode?: boolean;
+  /** Viewport width in pixels */
+  width?: number;
+  /** Viewport height in pixels */
+  height?: number;
+}
+/**
+ * Result of component rendering
+ */
+interface RenderResult {
+  /** Path to the rendered image file */
+  imagePath: string;
+  /** Generated HTML content */
+  html: string;
+  /** Component metadata */
+  componentInfo: ComponentInfo;
+}
+//#endregion
+//#region src/services/ComponentRendererService/ComponentRendererService.d.ts
+/**
+ * ComponentRendererService handles rendering React components to images.
+ *
+ * Uses BundlerService for building/serving components and ThemeService
+ * for theme configuration. Supports both dev server (fast) and static
+ * build (fallback) rendering modes.
+ *
+ * The bundler service can be customized by providing a bundlerFactory
+ * to support different bundlers (Vite, Webpack) and frameworks (React, Vue).
+ *
+ * @example
+ * ```typescript
+ * // Using default bundler (Vite + React)
+ * const service = new ComponentRendererService(designConfig, 'apps/my-app');
+ *
+ * // Using custom bundler
+ * const service = new ComponentRendererService(
+ *   designConfig,
+ *   'apps/my-app',
+ *   { bundlerFactory: () => new MyCustomBundlerService() }
+ * );
+ *
+ * const result = await service.renderComponent(componentInfo, {
+ *   storyName: 'Primary',
+ *   darkMode: true,
+ *   width: 1280,
+ *   height: 800
+ * });
+ * console.log(result.imagePath);
+ * ```
+ */
+declare class ComponentRendererService {
+  private monorepoRoot;
+  private tmpDir;
+  private themeService;
+  private appPath;
+  private bundlerFactory;
+  /**
+   * Creates a new ComponentRendererService instance
+   * @param designSystemConfig - Design system configuration
+   * @param appPath - Path to the app directory (relative or absolute)
+   * @param options - Optional configuration including custom bundler factory
+   */
+  constructor(designSystemConfig: DesignSystemConfig, appPath: string, options?: {
+    bundlerFactory?: BundlerFactory;
+  });
+  /**
+   * Get the bundler service instance.
+   * Uses the factory to create/retrieve the bundler.
+   * @returns The bundler service instance
+   */
+  private getBundlerService;
+  /**
+   * Render a component to an image
+   * @param componentInfo - Component metadata from StoriesIndexService
+   * @param options - Render options (story name, args, dimensions, etc.)
+   * @returns Rendered image path, HTML content, and component info
+   * @throws Error if rendering fails
+   */
+  renderComponent(componentInfo: ComponentInfo, options?: RenderOptions): Promise<RenderResult>;
+  /**
+   * Maximum number of screenshot files to keep in temp directory.
+   * Prevents disk space issues on long-running servers.
+   */
+  private static readonly MAX_TEMP_FILES;
+  /**
+   * Clean up old rendered files.
+   * Removes files older than the specified duration and enforces a max file count.
+   * @param olderThanMs - Remove files older than this duration (default: 1 hour)
+   */
+  cleanup(olderThanMs?: number): Promise<void>;
+  /**
+   * Cleanup bundler server and temp files.
+   * Called on service shutdown.
+   */
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/services/ThemeService/types.d.ts
+/**
+ * Theme metadata returned by listAvailableThemes
+ */
+interface ThemeInfo {
+  /** Theme name (derived from CSS class selector or filename) */
+  name: string;
+  /** Original filename with extension */
+  fileName: string;
+  /** Absolute path to theme file */
+  path: string;
+  /** Color variables defined in theme (from CSS parsing) */
+  colorVariables?: Record<string, string>;
+  /** Legacy: color data from JSON config (deprecated, use colorVariables) */
+  colors?: Record<string, unknown>;
+  /** Number of color shades (e.g., 50-950) */
+  shadeCount?: number;
+}
+/**
+ * Result of listing available themes
+ */
+interface AvailableThemesResult {
+  /** Array of available themes */
+  themes: ThemeInfo[];
+  /** Currently active theme name if detected */
+  activeTheme?: string;
+  /** Legacy: active brand name (deprecated, use activeTheme) */
+  activeBrand?: string;
+  /** Source of themes (css-file, json-config, custom) */
+  source?: 'css-file' | 'json-config' | 'custom';
+}
+//#endregion
+//#region src/services/ThemeService/ThemeService.d.ts
+/**
+ * ThemeService handles theme configuration and CSS generation.
+ *
+ * Provides methods for accessing theme CSS, generating theme wrappers,
+ * and listing available theme configurations.
+ *
+ * @example
+ * ```typescript
+ * const service = new ThemeService(designConfig);
+ * const cssFiles = await service.getThemeCSS();
+ * const themes = await service.listAvailableThemes();
+ * ```
+ */
+declare class ThemeService {
+  private monorepoRoot;
+  private config;
+  /**
+   * Creates a new ThemeService instance
+   * @param config - Design system configuration
+   */
+  constructor(config: DesignSystemConfig);
+  /**
+   * Get design system configuration
+   * @returns Current design system configuration
+   */
+  getConfig(): DesignSystemConfig;
+  /**
+   * Get theme CSS imports from config or common locations
+   * @returns Array of absolute paths to CSS files
+   */
+  getThemeCSS(): Promise<string[]>;
+  /**
+   * Generate theme provider wrapper code
+   * Uses default export as specified in config
+   * @param componentCode - Component code to wrap
+   * @param darkMode - Whether to use dark mode theme
+   * @returns Generated wrapper code string
+   */
+  generateThemeWrapper(componentCode: string, darkMode?: boolean): string;
+  /**
+   * Get inline theme styles for SSR
+   * @param darkMode - Whether to use dark mode styles
+   * @returns Combined CSS content as string
+   */
+  getInlineStyles(darkMode?: boolean): Promise<string>;
+  /**
+   * Get Tailwind CSS classes for theming
+   * @param darkMode - Whether to use dark mode classes
+   * @returns Array of Tailwind class names
+   */
+  getTailwindClasses(darkMode?: boolean): string[];
+  /**
+   * Validate that the theme provider path exists
+   * @returns True if theme provider is valid
+   */
+  validateThemeProvider(): Promise<boolean>;
+  /**
+   * List all available theme configurations
+   * @returns Object containing themes array and active brand
+   * @throws Error if themes directory cannot be read
+   */
+  listAvailableThemes(): Promise<AvailableThemesResult>;
+}
+//#endregion
+//#region src/services/CssClasses/types.d.ts
+/**
+ * CSSClasses Service Types
+ *
+ * Shared type definitions for CSS class extraction services.
+ * Configuration is read from toolkit.yaml under the 'style-system' key.
+ */
+/**
+ * Represents a single CSS class with its name and value
+ */
+interface CSSClassValue {
+  class: string;
+  value: string;
+}
+/**
+ * Categories of CSS classes that can be extracted
+ */
+type CSSClassCategory = 'colors' | 'typography' | 'spacing' | 'effects' | 'all';
+/**
+ * Result of CSS class extraction organized by category
+ */
+interface CSSClassesResult {
+  category: string;
+  classes: {
+    colors?: CSSClassValue[];
+    typography?: CSSClassValue[];
+    spacing?: CSSClassValue[];
+    effects?: CSSClassValue[];
+    sidebar?: CSSClassValue[];
+    icons?: CSSClassValue[];
+    grid?: CSSClassValue[];
+    animations?: CSSClassValue[];
+  };
+  totalClasses?: number;
+}
+/**
+ * CSS classes service configuration
+ *
+ * Example toolkit.yaml:
+ * ```yaml
+ * style-system:
+ *   getCssClasses:
+ *     customService: ./my-custom-css-service.ts
+ * ```
+ */
+interface StyleSystemConfig {
+  /** CSS framework type (tailwind, vanilla, etc.) */
+  cssFramework: string;
+  /**
+   * Custom service class path for CSS extraction override.
+   * Path is relative to workspace root.
+   * The module must export a class that extends BaseCSSClassesService.
+   */
+  customServicePath?: string;
+}
+/**
+ * Default configuration values
+ */
+declare const DEFAULT_STYLE_SYSTEM_CONFIG: StyleSystemConfig;
+//#endregion
+//#region src/services/CssClasses/BaseCSSClassesService.d.ts
+/**
+ * Abstract base class for CSS class extraction services.
+ *
+ * Subclasses must implement the `extractClasses` method to provide
+ * framework-specific CSS class extraction logic.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomCSSService extends BaseCSSClassesService {
+ *   async extractClasses(category: CSSClassCategory, themePath: string): Promise<CSSClassesResult> {
+ *     // Custom extraction logic
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseCSSClassesService {
+  protected config: StyleSystemConfig;
+  /**
+   * Creates a new CSS classes service instance
+   * @param config - Style system configuration from toolkit.yaml
+   */
+  constructor(config: StyleSystemConfig);
+  /**
+   * Extract CSS classes from a theme file.
+   *
+   * Subclasses must implement this method to provide framework-specific
+   * extraction logic (e.g., Tailwind, vanilla CSS, CSS-in-JS).
+   *
+   * @param category - Category filter for CSS classes ('colors', 'typography', 'spacing', 'effects', 'all')
+   * @param themePath - Absolute path to the theme CSS file
+   * @returns Promise resolving to extracted CSS classes organized by category
+   * @throws Error if theme file cannot be read or parsed
+   */
+  abstract extractClasses(category: CSSClassCategory | string, themePath: string): Promise<CSSClassesResult>;
+  /**
+   * Get the CSS framework identifier for this service
+   * @returns Framework identifier string (e.g., 'tailwind', 'vanilla')
+   */
+  abstract getFrameworkId(): string;
+  /**
+   * Validate that the theme path exists and is readable.
+   * Can be overridden by subclasses for custom validation.
+   *
+   * @param themePath - Path to validate
+   * @throws Error if path is invalid or unreadable
+   */
+  protected validateThemePath(themePath: string): Promise<void>;
+}
+//#endregion
+//#region src/services/CssClasses/TailwindCSSClassesService.d.ts
+/**
+ * Tailwind CSS class extraction service.
+ *
+ * Extracts CSS classes from Tailwind theme files by parsing CSS variables
+ * using postcss AST and generating corresponding utility class names.
+ *
+ * @example
+ * ```typescript
+ * const service = new TailwindCSSClassesService(config);
+ * const result = await service.extractClasses('colors', '/path/to/theme.css');
+ * console.log(result.classes.colors); // Array of color utility classes
+ * ```
+ */
+declare class TailwindCSSClassesService extends BaseCSSClassesService {
+  /**
+   * Creates a new TailwindCSSClassesService instance
+   * @param config - Style system configuration from toolkit.yaml
+   */
+  constructor(config: StyleSystemConfig);
+  /**
+   * Get the CSS framework identifier
+   * @returns Framework identifier string 'tailwind'
+   */
+  getFrameworkId(): string;
+  /**
+   * Extract Tailwind CSS classes from a theme file.
+   *
+   * Uses postcss to parse the CSS AST and safely extract variable declarations,
+   * then generates corresponding Tailwind utility classes (e.g., bg-*, text-*, border-*).
+   *
+   * Note: If an unrecognized category is passed, the method returns a result with
+   * empty classes object. Use valid categories: 'colors', 'typography', 'spacing', 'effects', 'all'.
+   *
+   * @param category - Category filter ('colors', 'typography', 'spacing', 'effects', 'all')
+   * @param themePath - Absolute path to the theme CSS file
+   * @returns Promise resolving to extracted CSS classes organized by category
+   * @throws Error if theme file cannot be read or parsed
+   */
+  extractClasses(category: CSSClassCategory | string, themePath: string): Promise<CSSClassesResult>;
+  /**
+   * Extract CSS variables with their values from theme content using postcss AST.
+   *
+   * Walks the CSS AST to find all custom property declarations (--*),
+   * handling multi-line values, comments, and any CSS formatting.
+   *
+   * @param themeContent - Raw CSS content from theme file
+   * @returns Promise resolving to Map of variable names (without --) to their values
+   *
+   * @example
+   * ```typescript
+   * // Handles standard declarations
+   * // --color-primary: #3b82f6;
+   *
+   * // Handles multi-line declarations
+   * // --shadow-lg:
+   * //   0 10px 15px -3px rgba(0, 0, 0, 0.1),
+   * //   0 4px 6px -4px rgba(0, 0, 0, 0.1);
+   *
+   * // Handles compressed CSS
+   * // --color-primary:#3b82f6;--color-secondary:#10b981;
+   * ```
+   */
+  private extractVariablesWithPostCSS;
+  /**
+   * Generate utility classes with actual values from CSS variables.
+   *
+   * Maps CSS variable naming conventions to Tailwind utility classes:
+   * - color-* → bg-*, text-*, border-*, ring-*
+   * - sidebar* → bg-*, text-*, border-*
+   * - text-* → text-* (typography)
+   * - font-* → font-* (typography)
+   * - space-* → p-*, m-*, gap-*
+   * - shadow-* → shadow-*
+   *
+   * Note: If the variables Map is empty, returns a result with empty arrays
+   * for all requested categories.
+   *
+   * @param variables - Map of CSS variable names to values
+   * @param category - Category filter for which classes to generate
+   * @returns CSSClassesResult with organized classes by category
+   *
+   * @example
+   * ```typescript
+   * const variables = new Map([
+   *   ['color-primary', '#3b82f6'],
+   *   ['shadow-md', '0 4px 6px rgba(0,0,0,0.1)']
+   * ]);
+   * const result = generateClassesFromVariables(variables, 'colors');
+   * // Returns:
+   * // {
+   * //   category: 'colors',
+   * //   classes: {
+   * //     colors: [
+   * //       { class: 'bg-primary', value: '#3b82f6' },
+   * //       { class: 'text-primary', value: '#3b82f6' },
+   * //       { class: 'border-primary', value: '#3b82f6' },
+   * //       { class: 'ring-primary', value: '#3b82f6' }
+   * //     ]
+   * //   },
+   * //   totalClasses: 4
+   * // }
+   * ```
+   */
+  private generateClassesFromVariables;
+}
+//#endregion
+//#region src/services/CssClasses/CSSClassesServiceFactory.d.ts
+/**
+ * Factory for creating CSS classes service instances.
+ *
+ * Supports built-in frameworks (tailwind) and custom service implementations
+ * loaded dynamically from user-specified paths.
+ *
+ * @example
+ * ```typescript
+ * const factory = new CSSClassesServiceFactory();
+ * const service = await factory.createService({ cssFramework: 'tailwind' });
+ * const classes = await service.extractClasses('colors', '/path/to/theme.css');
+ * ```
+ */
+declare class CSSClassesServiceFactory {
+  /**
+   * Create a CSS classes service based on configuration.
+   *
+   * @param config - Style system configuration (defaults to tailwind)
+   * @returns Promise resolving to a CSS classes service instance
+   * @throws Error if framework is unknown or custom service cannot be loaded
+   */
+  createService(config?: Partial<StyleSystemConfig>): Promise<BaseCSSClassesService>;
+  /**
+   * Create a built-in CSS classes service based on framework identifier.
+   *
+   * @param config - Resolved style system configuration
+   * @returns CSS classes service instance
+   * @throws Error if framework is not supported
+   */
+  private createBuiltInService;
+  /**
+   * Load a custom CSS classes service from user-specified path.
+   *
+   * The custom service must export a class that extends BaseCSSClassesService.
+   *
+   * @param config - Configuration with customServicePath set
+   * @returns Promise resolving to custom service instance
+   * @throws Error if service cannot be loaded or is invalid
+   */
+  private loadCustomService;
+}
+//#endregion
+//#region src/types/index.d.ts
+/**
+ * Tool definition for MCP
+ */
+interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: string;
+    properties: Record<string, any>;
+    required?: string[];
+    additionalProperties?: boolean;
+  };
+}
+/**
+ * Base tool interface following MCP SDK patterns
+ */
+interface Tool<TInput = any> {
+  getDefinition(): ToolDefinition;
+  execute(input: TInput): Promise<CallToolResult>;
+}
+//#endregion
+//#region src/tools/GetCSSClassesTool.d.ts
+/**
+ * Input parameters for GetCSSClassesTool
+ */
+interface GetCSSClassesInput {
+  category?: string;
+  appPath?: string;
+}
+/**
+ * MCP Tool for extracting CSS classes from theme files.
+ *
+ * Uses the CSSClassesServiceFactory to create the appropriate service
+ * based on configuration, supporting Tailwind and custom CSS frameworks.
+ *
+ * @example
+ * ```typescript
+ * const tool = new GetCSSClassesTool();
+ * const result = await tool.execute({ category: 'colors' });
+ * ```
+ */
+declare class GetCSSClassesTool implements Tool<GetCSSClassesInput> {
+  static readonly TOOL_NAME = "get_css_classes";
+  private static readonly CSS_REUSE_INSTRUCTION;
+  private serviceFactory;
+  private service;
+  private defaultThemePath;
+  /**
+   * Creates a new GetCSSClassesTool instance
+   * @param defaultThemePath - Default path to theme CSS file (relative to workspace root)
+   */
+  constructor(defaultThemePath?: string);
+  /**
+   * Returns the tool definition for MCP registration
+   * @returns Tool definition with name, description, and input schema
+   */
+  getDefinition(): ToolDefinition;
+  /**
+   * Executes the CSS class extraction
+   * @param input - Tool input parameters
+   * @returns CallToolResult with extracted CSS classes or error
+   */
+  execute(input: GetCSSClassesInput): Promise<CallToolResult>;
+  /**
+   * Resolves the theme file path based on app configuration or defaults.
+   *
+   * Resolution strategy:
+   * 1. If appPath provided, read themePath from project.json style-system config
+   * 2. themePath is resolved relative to the app directory (where project.json is)
+   * 3. Fall back to default theme path if not configured
+   *
+   * @param appPath - Optional app path to read config from
+   * @returns Absolute path to the theme file
+   */
+  private resolveThemePath;
+}
+//#endregion
+//#region src/services/GetUiComponentService/types.d.ts
+/**
+ * GetUiComponentService Types
+ *
+ * Type definitions for the GetUiComponentService service.
+ */
+/**
+ * Configuration options for GetUiComponentService.
+ *
+ * All options are optional. When not provided, values from
+ * DEFAULT_GET_UI_COMPONENT_CONFIG are used as fallbacks.
+ */
+interface GetUiComponentServiceConfig {
+  /** Default story name to render if not specified @default 'Playground' */
+  defaultStoryName?: string;
+  /** Default dark mode setting @default true */
+  defaultDarkMode?: boolean;
+  /** Default viewport width @default 1280 */
+  defaultWidth?: number;
+  /** Default viewport height @default 800 */
+  defaultHeight?: number;
+}
+/**
+ * Input parameters for getting a UI component preview.
+ *
+ * @example
+ * ```typescript
+ * const input: GetUiComponentInput = {
+ *   componentName: 'Button',
+ *   appPath: './apps/my-app',
+ *   storyName: 'Primary',
+ *   darkMode: true,
+ * };
+ * ```
+ */
+interface GetUiComponentInput {
+  /** The name of the component to capture (e.g., "Button", "Card") */
+  componentName: string;
+  /** App path (relative or absolute) to load design system configuration from */
+  appPath: string;
+  /** The story name to render (e.g., "Playground", "Default") */
+  storyName?: string;
+  /** Whether to render the component in dark mode */
+  darkMode?: boolean;
+  /** CSS selector to target specific element for screenshot */
+  selector?: string;
+}
+/**
+ * Result returned by GetUiComponentService.getComponent().
+ */
+interface GetUiComponentResult {
+  /** Path to the rendered image file */
+  imagePath: string;
+  /** Image format */
+  format: string;
+  /** Dimension info */
+  dimensions: string;
+  /** Path to the story file */
+  storyFilePath: string;
+  /** Content of the story file */
+  storyFileContent: string;
+  /** Component title from stories index */
+  componentTitle: string;
+  /** Available stories for this component */
+  availableStories: string[];
+  /** The story that was actually rendered */
+  renderedStory: string;
+}
+//#endregion
+//#region src/services/GetUiComponentService/GetUiComponentService.d.ts
+/**
+ * Factory function type for creating StoriesIndexService instances.
+ */
+type StoriesIndexFactory = () => StoriesIndexService;
+/**
+ * Factory function type for creating ComponentRendererService instances.
+ */
+type RendererFactory = (config: DesignSystemConfig, appPath: string) => ComponentRendererService;
+/**
+ * GetUiComponentService handles rendering UI component previews.
+ *
+ * Locates components in the stories index, renders them with app-specific
+ * design system configuration, and returns screenshot results.
+ *
+ * @example
+ * ```typescript
+ * const service = new GetUiComponentService();
+ * const result = await service.getComponent({
+ *   componentName: 'Button',
+ *   appPath: 'apps/my-app',
+ * });
+ * console.log(result.imagePath);
+ * ```
+ */
+declare class GetUiComponentService {
+  private config;
+  private storiesIndexFactory;
+  private rendererFactory;
+  /**
+   * Creates a new GetUiComponentService instance.
+   * @param config - Service configuration options
+   * @param storiesIndexFactory - Factory for creating StoriesIndexService (for DI/testing)
+   * @param rendererFactory - Factory for creating ComponentRendererService (for DI/testing)
+   */
+  constructor(config?: GetUiComponentServiceConfig, storiesIndexFactory?: StoriesIndexFactory, rendererFactory?: RendererFactory);
+  /**
+   * Get a UI component preview image.
+   *
+   * @param input - Component input parameters
+   * @returns Result with image path and component metadata
+   * @throws Error if input validation fails, component not found, or rendering fails
+   */
+  getComponent(input: GetUiComponentInput): Promise<GetUiComponentResult>;
+  /**
+   * Resolve and validate the story name.
+   *
+   * @param requestedStory - The requested story name
+   * @param availableStories - List of available stories for the component
+   * @returns Valid story name (requested or fallback)
+   */
+  private resolveStoryName;
+  /**
+   * Read the story file content.
+   *
+   * @param filePath - Path to the story file
+   * @returns File content or error message
+   */
+  private readStoryFile;
+}
+//#endregion
+//#region src/tools/GetComponentVisualTool.d.ts
+declare class GetComponentVisualTool implements Tool<GetUiComponentInput> {
+  static readonly TOOL_NAME = "get_component_visual";
+  private service;
+  /**
+   * Creates a new GetComponentVisualTool instance.
+   * @param service - Optional service instance for dependency injection (useful for testing)
+   */
+  constructor(service?: GetUiComponentService);
+  /**
+   * Returns the tool definition including name, description, and input schema.
+   * @returns Tool definition with JSON Schema for input validation
+   */
+  getDefinition(): ToolDefinition;
+  /**
+   * Executes the tool to get a UI component preview.
+   * @param input - The input parameters for getting the component
+   * @returns Promise resolving to CallToolResult with component info or error
+   */
+  execute(input: GetUiComponentInput): Promise<CallToolResult>;
+}
+//#endregion
+//#region src/tools/ListAppComponentsTool.d.ts
+/**
+ * Input parameters for ListAppComponentsTool.
+ */
+interface ListAppComponentsInput {
+  appPath: string;
+  cursor?: string;
+}
+/**
+ * Tool to list app-specific components and package components used by an app.
+ *
+ * Detects app components by file path (within app directory) and resolves
+ * workspace dependencies to find package components from Storybook stories.
+ *
+ * @example
+ * ```typescript
+ * const tool = new ListAppComponentsTool();
+ * const result = await tool.execute({ appPath: 'apps/my-app' });
+ * // Returns: { app: 'my-app', appComponents: ['Button'], packageComponents: {...}, pagination: {...} }
+ * ```
+ */
+declare class ListAppComponentsTool implements Tool<ListAppComponentsInput> {
+  static readonly TOOL_NAME = "list_app_components";
+  private static readonly COMPONENT_REUSE_INSTRUCTION;
+  private service;
+  constructor();
+  /**
+   * Gets the tool definition including name, description, and input schema.
+   * @returns Tool definition for MCP registration
+   */
+  getDefinition(): ToolDefinition;
+  /**
+   * Lists app-specific and package components for a given application.
+   * @param input - Object containing appPath and optional cursor for pagination
+   * @returns CallToolResult with component list or error
+   */
+  execute(input: ListAppComponentsInput): Promise<CallToolResult>;
+}
+//#endregion
+//#region src/tools/ListThemesTool.d.ts
+/**
+ * Input parameters for ListThemesTool
+ */
+interface ListThemesInput {
+  appPath?: string;
+}
+/**
+ * Tool to list all available theme configurations.
+ *
+ * Reads themes from CSS files configured in the app's project.json
+ * style-system config. Themes are extracted by parsing CSS class selectors
+ * that contain color variable definitions.
+ *
+ * @example
+ * ```typescript
+ * const tool = new ListThemesTool();
+ * const result = await tool.execute({ appPath: 'apps/my-app' });
+ * // Returns: { themes: [{ name: 'slate', ... }, { name: 'blue', ... }], source: 'css-file' }
+ * ```
+ */
+declare class ListThemesTool implements Tool<ListThemesInput> {
+  static readonly TOOL_NAME = "list_themes";
+  private serviceFactory;
+  constructor();
+  getDefinition(): ToolDefinition;
+  execute(input: ListThemesInput): Promise<CallToolResult>;
+}
+//#endregion
+//#region src/tools/ListSharedComponentsTool.d.ts
+/**
+ * Input parameters for ListSharedComponentsTool
+ */
+interface ListSharedComponentsInput {
+  /** Optional tags to filter components by. If not provided, uses configured sharedComponentTags from toolkit.yaml */
+  tags?: string[];
+  /** Optional pagination cursor to fetch the next page of results */
+  cursor?: string;
+}
+declare class ListSharedComponentsTool implements Tool<ListSharedComponentsInput> {
+  static readonly TOOL_NAME = "list_shared_components";
+  static readonly PAGE_SIZE = 50;
+  private static readonly COMPONENT_REUSE_INSTRUCTION;
+  /**
+   * Encode pagination state into an opaque cursor string
+   * @param offset - The current offset in the component list
+   * @returns Base64 encoded cursor string
+   */
+  private encodeCursor;
+  /**
+   * Decode cursor string into pagination state
+   * @param cursor - Base64 encoded cursor string
+   * @returns Object containing the offset
+   */
+  private decodeCursor;
+  /**
+   * Gets the tool definition including name, description, and input schema.
+   * @returns Tool definition for MCP registration
+   */
+  getDefinition(): ToolDefinition;
+  /**
+   * Lists shared UI components from the design system.
+   * @param input - Object containing optional tags filter and cursor for pagination
+   * @returns CallToolResult with component list or error
+   */
+  execute(input: ListSharedComponentsInput): Promise<CallToolResult>;
+}
+//#endregion
+//#region src/transports/stdio.d.ts
+/**
+ * Stdio transport handler for MCP server
+ * Used for command-line and direct integrations
+ */
+declare class StdioTransportHandler {
+  private server;
+  private transport;
+  constructor(server: Server);
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+//#endregion
+export { BaseBundlerService, BaseCSSClassesService, type CSSClassCategory, type CSSClassValue, type CSSClassesResult, CSSClassesServiceFactory, ComponentRendererService, DEFAULT_STYLE_SYSTEM_CONFIG, GetCSSClassesTool, GetComponentVisualTool, ListAppComponentsTool, ListSharedComponentsTool, ListThemesTool, StdioTransportHandler, StoriesIndexService, type StyleSystemConfig, TailwindCSSClassesService, ThemeService, Tool, ToolDefinition, ViteReactBundlerService, createDefaultBundlerService, createServer, getBundlerServiceFromConfig };