@agimon-ai/style-system 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,1959 @@
+import { Container, ContainerModule } from "inversify";
+import "zod";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { AliasOptions, Plugin, UserConfig } from "vite";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+//#region src/container/module.d.ts
+interface StyleSystemModuleOptions {
+  defaultThemePath?: string;
+}
+declare function createStyleSystemModule(optionsInput?: StyleSystemModuleOptions): ContainerModule;
+//#endregion
+//#region src/container/types.d.ts
+declare const STYLE_SYSTEM_TYPES: {
+  readonly ListThemesTool: symbol;
+  readonly GetCSSClassesTool: symbol;
+  readonly GetComponentVisualTool: symbol;
+  readonly ListSharedComponentsTool: symbol;
+  readonly ListAppComponentsTool: symbol;
+  readonly PolishComponentTool: symbol;
+  readonly ThemeServiceFactory: symbol;
+  readonly CSSClassesServiceFactory: symbol;
+  readonly StoriesIndexService: symbol;
+  readonly GetUiComponentService: symbol;
+  readonly AppComponentsService: symbol;
+  readonly StoriesIndexFactory: symbol;
+  readonly RendererFactory: symbol;
+  readonly StyleSystemConfigLoader: symbol;
+  readonly DefaultThemePath: symbol;
+  readonly GetUiComponentServiceConfig: symbol;
+  readonly AppComponentsServiceConfig: symbol;
+};
+//#endregion
+//#region src/container/index.d.ts
+declare function createContainer(options?: StyleSystemModuleOptions): Container;
+//#endregion
+//#region src/config/types.d.ts
+declare const SUPPORTED_COLOR_SCHEMES: readonly ["light", "dark", "automatic"];
+type ColorSchemePreference = (typeof SUPPORTED_COLOR_SCHEMES)[number];
+interface StyleSystemViewport {
+  /** Browser viewport width in pixels */
+  width: number;
+  /** Browser viewport height in pixels */
+  height: number;
+}
+/**
+ * Fields that may appear in any layer: root `defaults`, a preset, or a project config.
+ */
+interface DesignSystemFields {
+  /** Type of design system (tailwind or shadcn) */
+  type?: 'tailwind' | 'shadcn';
+  /** Bundler service identifier (e.g., 'vite-react', 'vite-react-native') */
+  bundler?: string;
+  /** Brand theme key for native rendering (e.g., 'gruu', 'boomlink', 'receiptnote') */
+  brand?: string;
+  /** Path to native app Unistyles runtime configuration */
+  unistylesConfig?: string;
+  /** Supported color scheme. Fixed light/dark apps override render requests. */
+  colorScheme?: ColorSchemePreference;
+  /** Default browser viewport for component screenshots. */
+  viewport?: StyleSystemViewport;
+  /** Path to tailwind config file */
+  tailwindConfig?: string;
+  /** Legacy path to a theme provider component with a default export */
+  themeProvider?: string;
+  /** Path to root component for wrapping rendered components */
+  rootComponent?: string;
+  /** CSS file paths to include */
+  cssFiles?: string[];
+  /** Component library path (for shadcn) */
+  componentLibrary?: string;
+  /** Path to theme CSS file for Tailwind class extraction */
+  themePath?: string;
+  /**
+   * Tags that identify shared/design system components.
+   * Workspace-wide tags live at the root config; see `getSharedComponentTags`.
+   */
+  sharedComponentTags?: string[];
+}
+/**
+ * Resolved design system configuration.
+ *
+ * Same shape as `DesignSystemFields` except `type` is required, which is enforced
+ * once by `finalizeDesignSystemConfig` rather than by any file schema.
+ */
+interface DesignSystemConfig extends DesignSystemFields {
+  type: 'tailwind' | 'shadcn';
+}
+/** Resolution result carrying the provenance callers need. */
+interface ResolvedDesignSystemConfig {
+  /** Merged and validated configuration. */
+  config: DesignSystemConfig;
+  /** True when the project declares its own `style-system.config.yaml`. */
+  hasProjectConfig: boolean;
+  /** Absolute path to the project config, when one exists. */
+  projectConfigPath?: string;
+  /** Preset names applied, root-most first. */
+  appliedPresets: string[];
+}
+/** Configuration for getCssClasses tool custom service override */
+interface GetCssClassesConfig {
+  /** Path to custom service module (relative to workspace root) */
+  customService?: string;
+}
+/** Configuration for bundler service override */
+interface BundlerConfig {
+  /** Path to custom bundler service module (relative to workspace root) */
+  customService?: string;
+}
+/** A named preset: design system fields plus an optional parent chain. */
+interface PresetConfig extends DesignSystemFields {
+  extends?: string | string[];
+}
+/** Workspace root `style-system.config.yaml`, after parsing. */
+interface StyleSystemRootConfig {
+  root: true;
+  sharedComponentTags?: string[];
+  getCssClasses?: GetCssClassesConfig;
+  bundler?: BundlerConfig;
+  defaults?: DesignSystemFields;
+  presets?: Record<string, PresetConfig>;
+}
+//#endregion
+//#region src/config/StyleSystemConfigLoader.d.ts
+declare class StyleSystemConfigLoader {
+  /**
+   * Promises rather than values, so concurrent resolves de-duplicate. Several
+   * callers hit config from inside Promise.all/allSettled.
+   */
+  private rootPromise;
+  private readonly projectCache;
+  /** Drop all cached config state. */
+  invalidate(): void;
+  /** Load and cache the workspace root config. */
+  loadRoot(): Promise<StyleSystemRootConfig>;
+  /** Resolve the merged configuration for a project. */
+  resolveProject(appPath: string): Promise<ResolvedDesignSystemConfig>;
+  private readRoot;
+  private readProject;
+  private finalize;
+}
+//#endregion
+//#region src/config/themePath.d.ts
+/**
+ * Resolve a configured `themePath` to an absolute filesystem path.
+ *
+ * Canonical config uses workspace-root relative paths (for example
+ * packages/frontend/web-theme/dist/agiflow-theme.css). The app-relative candidate
+ * is kept as a compatibility fallback, mainly for user supplied `--theme-path`
+ * values, and warns when it is the one that resolves.
+ */
+declare function resolveStyleSystemThemePath(input: {
+  appPath?: string | null;
+  themePath: string;
+}): Promise<string>;
+//#endregion
+//#region src/config/index.d.ts
+/** Drop all cached config state. Test and long-lived-process seam. */
+declare function resetStyleSystemConfigCache(): void;
+/** Resolve a project's design system configuration. */
+declare function getAppDesignSystemConfig(appPath: string): Promise<DesignSystemConfig>;
+/** Resolve a project's configuration together with its provenance. */
+declare function resolveAppDesignSystemConfig(appPath: string): Promise<ResolvedDesignSystemConfig>;
+/** True when the project declares its own style-system.config.yaml. */
+declare function hasStyleSystemProjectConfig(appPath: string): Promise<boolean>;
+/** Workspace-wide tags that identify shared/design system components. */
+declare function getSharedComponentTags(): Promise<string[]>;
+//#endregion
+//#region src/server/index.d.ts
+declare function createServer(containerOrThemePath?: Container | string): Server;
+//#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;
+}
+/**
+ * Configuration options for StoriesIndexService
+ */
+interface StoriesIndexServiceConfig {
+  /**
+   * Enable verbose logging
+   * @default false
+   */
+  verbose?: boolean;
+  /** Workspace used to resolve relative search roots. */
+  workspaceRoot?: string;
+  /** Directories to scan, relative to the workspace or absolute. Defaults to the workspace root. */
+  searchRoots?: string[];
+  /** Exact story files to add without scanning their surrounding projects. */
+  storyFiles?: string[];
+  /** Maximum number of story files parsed concurrently. */
+  concurrency?: number;
+}
+//#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;
+  private readonly config;
+  /**
+   * Creates a new StoriesIndexService instance
+   */
+  constructor(config?: StoriesIndexServiceConfig);
+  /**
+   * 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;
+  private findStoryFiles;
+  private indexConcurrency;
+  private indexStoryFiles;
+  /**
+   * Index a single story file using storybook/internal/csf-tools.
+   *
+   * File reads remain cheap enough to hash on every new index. The expensive CSF
+   * parse is shared by content hash across service instances and concurrent rules.
+   */
+  private indexStoryFile;
+  private parseStoryFile;
+  /**
+   * 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, preferredAppPath?: 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;
+  /** Path to native app Unistyles runtime configuration */
+  unistylesConfig?: string;
+}
+/**
+ * Internal options for building a component to static HTML.
+ */
+interface BuildOptions {
+  /** Absolute path to the component story file */
+  componentPath: string;
+  /** Name of the story to render */
+  storyName: string;
+  /** Args to pass to the story */
+  args: Record<string, unknown>;
+  /** Resolved absolute path to the app directory */
+  appPath: string;
+  /** Whether to use dark mode */
+  darkMode: boolean;
+  /** CSS files to import */
+  cssFiles: string[];
+  /** Path to root component wrapper */
+  rootComponent?: string;
+  /** Path to native app Unistyles runtime configuration */
+  unistylesConfig?: string;
+  /** Temporary directory for build artifacts */
+  tmpDir: 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>;
+  /**
+   * Get Vite resolve configuration for the given app path.
+   * Subclasses can override to add platform-specific aliases (e.g., react-native-web).
+   */
+  protected getViteResolveConfig(appPath: string): {
+    alias: AliasOptions;
+    extensions?: string[];
+  };
+  /**
+   * Get Vite define replacements.
+   * Subclasses can override to provide platform globals.
+   */
+  protected getViteDefineConfig(): UserConfig['define'];
+  /**
+   * Generate preview HTML styles.
+   * Subclasses can override for platform-specific layout constraints.
+   */
+  protected generatePreviewStyles(): string;
+  /**
+   * Get Vite esbuild configuration.
+   * Subclasses can override to handle platform-specific JSX needs.
+   */
+  protected getViteEsbuildConfig(): UserConfig['esbuild'];
+  /**
+   * Get Vite Oxc configuration.
+   * Subclasses can override to disable Oxc for platform-specific parsing needs.
+   */
+  protected getViteOxcConfig(): UserConfig['oxc'];
+  /**
+   * Get additional Vite plugins.
+   * Subclasses can override to add platform-specific plugins (e.g., @vitejs/plugin-react).
+   */
+  protected getAdditionalVitePlugins(_appPath?: string): Plugin[];
+  /**
+   * 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;
+  /**
+   * Infer an app stylesheet when project.json does not define style-system.cssFiles.
+   * Many Vite apps keep their Tailwind/theme entrypoint in src/assets/main.css.
+   */
+  private getDefaultCssFiles;
+  /**
+   * 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 framework-specific setup imports that must run before story imports.
+   * Native rendering overrides this to load app-specific runtime setup.
+   */
+  protected generateFrameworkSetupImports(_options: BuildOptions): string;
+  protected generateStoryImport(componentPath: string): string;
+  protected wrapFrameworkElement(elementExpression: string, _options: BuildOptions): string;
+  /**
+   * 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 the workspace style-system.config.yaml.
+ *
+ * If a custom service is configured under 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 style-system.config.yaml at the workspace root:
+ * // 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;
+  /** Width of the generated screenshot in pixels */
+  width: number;
+  /** Height of the generated screenshot in pixels */
+  height: number;
+}
+//#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: DEFAULT_RENDER_WIDTH,
+ *   height: DEFAULT_RENDER_HEIGHT
+ * });
+ * result.imagePath;
+ * ```
+ */
+declare class ComponentRendererService {
+  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>;
+  /**
+   * Default maximum number of screenshot files to keep in temp directory.
+   * Prevents disk space issues on long-running servers.
+   */
+  private static readonly DEFAULT_MAX_TEMP_FILES;
+  /**
+   * Number of recent files to keep when cleaning up on dispose.
+   */
+  private static readonly DISPOSE_KEEP_COUNT;
+  /**
+   * 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)
+   * @param keepCount - Maximum number of recent files to keep (default: 100)
+   */
+  cleanup(olderThanMs?: number, keepCount?: number): Promise<void>;
+  /**
+   * Cleanup bundler server resources and old temp files.
+   * Called on service shutdown.
+   * Keeps the most recent files for caching purposes.
+   */
+  dispose(): Promise<void>;
+}
+//#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 for automatic-theme apps @default false */
+  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;
+  /** Browser viewport width in pixels */
+  width?: number;
+  /** Browser viewport height in pixels */
+  height?: number;
+  /** 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;
+  /** Resolved light or dark color scheme used for the screenshot */
+  colorScheme: 'light' | 'dark';
+  /** Browser viewport used for the screenshot */
+  viewport: {
+    width: number;
+    height: number;
+  };
+}
+//#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',
+ * });
+ * 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>;
+  private validateViewportDimension;
+  /**
+   * Resolve and validate the story name.
+   *
+   * A mismatch throws rather than falling back to another story: the caller would
+   * otherwise receive a real screenshot of a story it did not ask for, with nothing
+   * downstream able to tell.
+   *
+   * @param requestedStory - The requested story name
+   * @param availableStories - List of available stories for the component
+   * @param componentTitle - Story title of the component being resolved
+   * @returns The requested story name
+   * @throws When the requested story is not one of the component's indexed stories
+   */
+  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/services/ThemeService/types.d.ts
+/**
+ * ThemeService Types
+ *
+ * Type definitions for the ThemeService service.
+ */
+/**
+ * Configuration for theme service
+ */
+interface ThemeServiceConfig {
+  /** Path to theme CSS file (from style-system.config.yaml themePath) */
+  themePath?: string;
+  /** CSS files to scan for themes (from style-system.config.yaml cssFiles) */
+  cssFiles?: string[];
+  /** Custom service path for user-provided theme service implementation */
+  customServicePath?: string;
+}
+/**
+ * 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/BaseThemeService.d.ts
+/**
+ * Abstract base class for theme listing services.
+ *
+ * Subclasses must implement the `listThemes` method to provide
+ * source-specific theme extraction logic (CSS files, JSON configs, etc.).
+ *
+ * @example
+ * ```typescript
+ * class MyCustomThemeService extends BaseThemeService {
+ *   async listThemes(): Promise<AvailableThemesResult> {
+ *     // Custom theme extraction logic
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseThemeService {
+  protected config: ThemeServiceConfig;
+  /**
+   * Creates a new theme service instance
+   * @param config - Theme service configuration
+   */
+  constructor(config: ThemeServiceConfig);
+  /**
+   * List available themes from the configured source.
+   *
+   * Subclasses must implement this method to provide source-specific
+   * theme extraction logic (e.g., CSS class selectors, JSON files).
+   *
+   * @returns Promise resolving to available themes result
+   * @throws Error if themes cannot be loaded
+   */
+  abstract listThemes(): Promise<AvailableThemesResult>;
+  /**
+   * Get the source identifier for this service
+   * @returns Source identifier string (e.g., 'css-file', 'json-config', 'custom')
+   */
+  abstract getSourceId(): 'css-file' | 'json-config' | 'custom';
+  /**
+   * Validate that a file path exists and is readable.
+   * Can be overridden by subclasses for custom validation.
+   *
+   * @param filePath - Path to validate
+   * @throws Error if path is invalid or unreadable
+   */
+  protected validatePath(filePath: string): Promise<void>;
+}
+//#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
+   * Imports the configured provider's default export and exposes a named wrapper
+   * @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/ThemeService/ThemeServiceFactory.d.ts
+/**
+ * Factory for creating theme service instances.
+ *
+ * Supports the built-in CSSThemeService and custom service implementations
+ * loaded dynamically from user-specified paths.
+ *
+ * @example
+ * ```typescript
+ * const factory = new ThemeServiceFactory();
+ *
+ * // Create default CSS-based service
+ * const service = await factory.createService({
+ *   themePath: 'apps/my-app/src/styles/colors.css'
+ * });
+ *
+ * // Create with custom service override
+ * const customService = await factory.createService({
+ *   customServicePath: './my-custom-theme-service.ts'
+ * });
+ *
+ * const themes = await service.listThemes();
+ * ```
+ */
+declare class ThemeServiceFactory {
+  /**
+   * Create a theme service based on configuration.
+   *
+   * Resolution order:
+   * 1. If customServicePath is provided, load custom service dynamically
+   * 2. Otherwise, create the default CSSThemeService
+   *
+   * @param config - Theme service configuration
+   * @returns Promise resolving to a theme service instance
+   * @throws Error if custom service cannot be loaded or is invalid
+   */
+  createService(config?: Partial<ThemeServiceConfig>): Promise<BaseThemeService>;
+  /**
+   * Load a custom theme service from user-specified path.
+   *
+   * The custom service must export a class that extends BaseThemeService.
+   *
+   * @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/services/CssClasses/types.d.ts
+/**
+ * CSSClasses Service Types
+ *
+ * Shared type definitions for CSS class extraction services.
+ * Configuration is read from the workspace style-system.config.yaml.
+ */
+/**
+ * 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 style-system.config.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 style-system.config.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: 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 {
+  /**
+   * 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: 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/utils/OxlintPatternGenerator.d.ts
+/**
+ * A single pattern entry within the oxlint no-restricted-classes rule
+ */
+interface OxlintRestrictedClassPattern {
+  pattern: string;
+  message: string;
+}
+/**
+ * The full patterns config for the oxlint no-restricted-classes rule
+ */
+interface OxlintRestrictedClassesConfig {
+  patterns: OxlintRestrictedClassPattern[];
+}
+/**
+ * Extract unique custom color token base names from a CSSClassesResult.
+ *
+ * Strips known utility prefixes (bg-, text-, border-, ring-, etc.) from
+ * the color class names to derive the semantic token name (e.g., `primary`,
+ * `muted-foreground`, `accent`).
+ *
+ * @param cssResult - The extracted CSS classes result from TailwindCSSClassesService
+ * @returns Alphabetically sorted array of unique custom token base names
+ *
+ * @example
+ * ```typescript
+ * const result = await service.extractClasses('colors', themePath);
+ * const tokens = extractCustomTokenNames(result);
+ * // ['accent', 'background', 'destructive', 'muted', 'primary', ...]
+ * ```
+ */
+declare function extractCustomTokenNames(cssResult: CSSClassesResult): string[];
+/**
+ * Generate an oxlint `tailwindcss/no-restricted-classes` config from
+ * extracted CSS design tokens.
+ *
+ * Produces a regex pattern matching default Tailwind color utilities
+ * (e.g., `bg-red-500`, `dark:text-zinc-100`) and a human-readable
+ * message listing available custom theme tokens.
+ *
+ * @param cssResult - The extracted CSS classes result from TailwindCSSClassesService
+ * @returns Config object suitable for the oxlint rule's `patterns` array
+ *
+ * @example
+ * ```typescript
+ * const result = await service.extractClasses('colors', themePath);
+ * const config = generateRestrictedClassesConfig(result);
+ * // {
+ * //   patterns: [{
+ * //     pattern: "([a-zA-Z0-9:/_-]*:)?(text|bg|...)-(slate|gray|...)-(50|100|...)(/[0-9]{1,3})?$",
+ * //     message: "Default Tailwind color is disabled. Use custom theme colors instead (e.g., primary, accent, muted)."
+ * //   }]
+ * // }
+ * ```
+ */
+declare function generateRestrictedClassesConfig(cssResult: CSSClassesResult): OxlintRestrictedClassesConfig;
+//#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;
+  };
+  _meta?: Record<string, unknown>;
+}
+/**
+ * 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 defaultThemePath?;
+  /**
+   * Creates a new GetCSSClassesTool instance
+   * @param serviceFactory - Injected CSSClassesServiceFactory
+   * @param defaultThemePath - Default path to theme CSS file (relative to workspace root)
+   */
+  constructor(serviceFactory: CSSClassesServiceFactory, 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 the resolved style-system config
+   * 2. themePath is resolved relative to the workspace root, with app-relative fallback
+   * 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/AppComponentsService/types.d.ts
+/**
+ * AppComponentsService Types
+ *
+ * Type definitions for the AppComponentsService service.
+ */
+/**
+ * Configuration options for AppComponentsService.
+ */
+interface AppComponentsServiceConfig {
+  /** Page size for pagination @default 50 */
+  pageSize?: number;
+}
+/**
+ * Input parameters for listing app components.
+ */
+interface ListAppComponentsInput$1 {
+  /** App path (relative or absolute) to list components for */
+  appPath: string;
+  /** Optional pagination cursor from previous response */
+  cursor?: string;
+}
+/**
+ * Pagination metadata in the result.
+ */
+interface PaginationInfo {
+  offset: number;
+  pageSize: number;
+  totalComponents: number;
+  hasMore: boolean;
+}
+/**
+ * Brief component information for list results.
+ */
+interface ComponentBrief {
+  /** Component name (e.g., "Button") */
+  name: string;
+  /** Component description from story file JSDoc or parameters.docs.description */
+  description?: string;
+}
+/**
+ * Result returned by AppComponentsService.listComponents().
+ */
+interface AppComponentsServiceResult {
+  /** Name of the app */
+  app: string;
+  /** Components defined within the app directory */
+  appComponents: ComponentBrief[];
+  /** Components from workspace dependencies, keyed by package name */
+  packageComponents: Record<string, ComponentBrief[]>;
+  /** Pagination metadata */
+  pagination: PaginationInfo;
+  /** Cursor for fetching next page, if more results exist */
+  nextCursor?: string;
+}
+//#endregion
+//#region src/services/AppComponentsService/AppComponentsService.d.ts
+/**
+ * AppComponentsService handles listing app-specific and package components.
+ *
+ * Detects components by file path (within app directory) and resolves
+ * workspace dependencies to find package components.
+ *
+ * @example
+ * ```typescript
+ * const service = new AppComponentsService();
+ * const result = await service.listComponents({ appPath: 'apps/my-app' });
+ * // Returns: { app: 'my-app', appComponents: ['Button'], packageComponents: {...}, pagination: {...} }
+ * ```
+ */
+declare class AppComponentsService {
+  private config;
+  /**
+   * Creates a new AppComponentsService instance.
+   * @param config - Service configuration options
+   */
+  constructor(config?: AppComponentsServiceConfig);
+  /**
+   * List app-specific and package components for a given application.
+   * @param input - Object containing appPath and optional cursor for pagination
+   * @returns Promise resolving to paginated component list
+   * @throws Error if input validation fails, app path does not exist, or stories index fails to initialize
+   */
+  listComponents(input: ListAppComponentsInput$1): Promise<AppComponentsServiceResult>;
+  /**
+   * Get app name from project.json.
+   * @param resolvedAppPath - Absolute path to the app directory
+   * @returns App name from project.json or directory basename as fallback
+   */
+  private getAppName;
+  /**
+   * Get workspace dependencies from package.json.
+   * @param resolvedAppPath - Absolute path to the app directory
+   * @returns Array of workspace dependency package names
+   */
+  private getWorkspaceDependencies;
+  /**
+   * Find all package.json files in the monorepo and build a map of package name → directory path.
+   * @param monorepoRoot - The root directory of the monorepo
+   * @returns Promise resolving to a Map where keys are package names and values are directory paths
+   * @throws Error if scanning for package.json files fails
+   */
+  private buildPackageMap;
+  /**
+   * Categorize components into app-specific and package components.
+   * App components are detected by file path (within app directory).
+   * Package components are matched to workspace dependencies.
+   *
+   * @param allComponents - All components from stories index
+   * @param resolvedAppPath - Absolute path to the app directory
+   * @param workspaceDependencies - List of workspace dependency package names
+   * @param packageMap - Map of package name to directory path
+   * @returns Categorized components with totals
+   */
+  private categorizeComponents;
+  /**
+   * Apply pagination to component lists.
+   *
+   * Pagination strategy:
+   * 1. First, fill page with app components starting from offset
+   * 2. Then, fill remaining page space with package components in order
+   * 3. Track total returned for cursor calculation
+   *
+   * @param appComponentsArray - Sorted array of app component briefs
+   * @param packageComponents - Record of package name to component briefs
+   * @param offset - Current pagination offset (0-indexed)
+   * @returns Paginated components and total returned count
+   */
+  private paginateComponents;
+  /**
+   * Encode pagination state into a base64 cursor string.
+   * @param offset - The current offset position in the component list
+   * @returns Base64-encoded cursor string for the next page
+   */
+  private encodeCursor;
+  /**
+   * Decode cursor string into pagination state.
+   * @param cursor - Base64-encoded cursor string from previous response
+   * @returns Object with offset position; defaults to 0 if cursor is invalid
+   */
+  private decodeCursor;
+}
+//#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 - Injected GetUiComponentService instance
+   */
+  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(service: AppComponentsService);
+  /**
+   * 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(serviceFactory: ThemeServiceFactory);
+  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 sharedComponentTags from the workspace style-system.config.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;
+  private storiesIndexFactory;
+  constructor(storiesIndexFactory: StoriesIndexFactory);
+  /**
+   * 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/tools/PolishComponentTool.d.ts
+interface PolishComponentInput {
+  filePath: string;
+  instructions?: string;
+}
+declare class PolishComponentTool implements Tool<PolishComponentInput> {
+  static readonly TOOL_NAME = "polish_component";
+  private antigravityService;
+  private getUiComponentService;
+  private cssClassesServiceFactory;
+  private storiesIndexFactory;
+  constructor(getUiComponentService: GetUiComponentService, cssClassesServiceFactory: CSSClassesServiceFactory, storiesIndexFactory: StoriesIndexFactory);
+  getDefinition(): ToolDefinition;
+  execute(input: PolishComponentInput): Promise<CallToolResult>;
+  private detectPlatform;
+  private buildSystemPrompt;
+  /**
+   * Read design tokens from config.themePath.
+   * For web: extracts Tailwind CSS classes. For native: reads the TypeScript types file.
+   */
+  private getDesignTokens;
+  private findStoriesFile;
+  /**
+   * Find the app that owns a file, for style-system context.
+   * Only apps declaring their own style-system.config.yaml are eligible.
+   */
+  private findAppPath;
+  private getComponentVisual;
+  private getDesignPrinciples;
+  private getSharedComponents;
+}
+//#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, type DesignSystemConfig, GetCSSClassesTool, GetComponentVisualTool, GetUiComponentService, ListAppComponentsTool, ListSharedComponentsTool, ListThemesTool, type OxlintRestrictedClassPattern, type OxlintRestrictedClassesConfig, PolishComponentTool, type ResolvedDesignSystemConfig, STYLE_SYSTEM_TYPES, StdioTransportHandler, StoriesIndexService, type StyleSystemConfig, StyleSystemConfigLoader, type StyleSystemModuleOptions, TailwindCSSClassesService, ThemeService, type Tool, type ToolDefinition, ViteReactBundlerService, createContainer, createDefaultBundlerService, createServer, createStyleSystemModule, extractCustomTokenNames, generateRestrictedClassesConfig, getAppDesignSystemConfig, getBundlerServiceFromConfig, getSharedComponentTags, hasStyleSystemProjectConfig, resetStyleSystemConfigCache, resolveAppDesignSystemConfig, resolveStyleSystemThemePath };