@agiflowai/style-system 0.0.1

package/dist/stdio-CGaoEmM8.js

@@ -0,0 +1,3099 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import path from "node:path";
+import { TemplatesManagerService, log } from "@agiflowai/aicode-utils";
+import { promises } from "node:fs";
+import yaml from "js-yaml";
+import postcss from "postcss";
+import { glob } from "glob";
+import { createHash } from "node:crypto";
+import { loadCsf } from "@storybook/csf-tools";
+import tailwindcss from "@tailwindcss/vite";
+import { viteSingleFile } from "vite-plugin-singlefile";
+import os from "node:os";
+import { chromium, firefox, webkit } from "playwright";
+import sharp from "sharp";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+//#region src/config.ts
+/**
+* Default tags for identifying shared/design system components
+*/
+const DEFAULT_SHARED_COMPONENT_TAGS = ["style-system"];
+/**
+* Default configuration for apps without style-system config
+*/
+const DEFAULT_CONFIG = {
+	type: "tailwind",
+	themeProvider: "@agimonai/web-ui",
+	sharedComponentTags: DEFAULT_SHARED_COMPONENT_TAGS
+};
+/**
+* Validate style-system configuration from project.json.
+* Ensures required fields are present and have correct types.
+*
+* @param config - The config object to validate
+* @param projectName - Project name for error messages
+* @returns Validated DesignSystemConfig
+* @throws Error if validation fails
+*/
+function validateDesignSystemConfig(config, projectName) {
+	if (typeof config !== "object" || config === null) throw new Error(`[${projectName}] style-system config must be an object`);
+	const cfg = config;
+	if (!cfg.type || cfg.type !== "tailwind" && cfg.type !== "shadcn") throw new Error(`[${projectName}] style-system.type must be 'tailwind' or 'shadcn'`);
+	if (!cfg.themeProvider || typeof cfg.themeProvider !== "string") throw new Error(`[${projectName}] style-system.themeProvider is required and must be a string`);
+	if (cfg.tailwindConfig !== void 0 && typeof cfg.tailwindConfig !== "string") throw new Error(`[${projectName}] style-system.tailwindConfig must be a string`);
+	if (cfg.rootComponent !== void 0 && typeof cfg.rootComponent !== "string") throw new Error(`[${projectName}] style-system.rootComponent must be a string`);
+	if (cfg.cssFiles !== void 0) {
+		if (!Array.isArray(cfg.cssFiles) || !cfg.cssFiles.every((f) => typeof f === "string")) throw new Error(`[${projectName}] style-system.cssFiles must be an array of strings`);
+	}
+	if (cfg.componentLibrary !== void 0 && typeof cfg.componentLibrary !== "string") throw new Error(`[${projectName}] style-system.componentLibrary must be a string`);
+	if (cfg.themePath !== void 0 && typeof cfg.themePath !== "string") throw new Error(`[${projectName}] style-system.themePath must be a string`);
+	if (cfg.sharedComponentTags !== void 0) {
+		if (!Array.isArray(cfg.sharedComponentTags) || !cfg.sharedComponentTags.every((t) => typeof t === "string")) throw new Error(`[${projectName}] style-system.sharedComponentTags must be an array of strings`);
+	}
+	return config;
+}
+/**
+* Read design system configuration from an app's project.json.
+*
+* @param appPath - Path to the app directory (relative or absolute)
+* @returns Validated DesignSystemConfig
+* @throws Error if appPath is invalid, project.json cannot be read, or config validation fails
+*/
+async function getAppDesignSystemConfig(appPath) {
+	if (!appPath || typeof appPath !== "string") throw new Error("appPath is required and must be a non-empty string");
+	const monorepoRoot = TemplatesManagerService.getWorkspaceRootSync();
+	const resolvedAppPath = path.isAbsolute(appPath) ? appPath : path.join(monorepoRoot, appPath);
+	const projectJsonPath = path.join(resolvedAppPath, "project.json");
+	try {
+		const content = await promises.readFile(projectJsonPath, "utf-8");
+		let projectJson;
+		try {
+			projectJson = JSON.parse(content);
+		} catch (parseError) {
+			throw new Error(`Invalid JSON in ${projectJsonPath}: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
+		}
+		if (typeof projectJson !== "object" || projectJson === null) throw new Error(`${projectJsonPath} must contain a JSON object`);
+		const project = projectJson;
+		const projectName = typeof project.name === "string" ? project.name : path.basename(resolvedAppPath);
+		if (project["style-system"]) {
+			const validatedConfig = validateDesignSystemConfig(project["style-system"], projectName);
+			log.info(`[Config] Loaded and validated style-system config for ${projectName}`);
+			return validatedConfig;
+		}
+		log.info(`[Config] No style-system config found for ${projectName}, using defaults`);
+		return DEFAULT_CONFIG;
+	} catch (error) {
+		throw new Error(`Failed to read style-system config from ${projectJsonPath}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Get shared component tags from toolkit.yaml or use defaults.
+*
+* Reads configuration from toolkit.yaml at workspace root.
+* Falls back to DEFAULT_SHARED_COMPONENT_TAGS if not configured.
+*
+* @returns Array of tag names that identify shared components
+*/
+async function getSharedComponentTags() {
+	const monorepoRoot = TemplatesManagerService.getWorkspaceRootSync();
+	const toolkitYamlPath = path.join(monorepoRoot, "toolkit.yaml");
+	try {
+		const content = await promises.readFile(toolkitYamlPath, "utf-8");
+		const config = yaml.load(content);
+		if (config?.["style-system"]?.sharedComponentTags?.length) {
+			const tags = config["style-system"].sharedComponentTags;
+			if (Array.isArray(tags) && tags.every((tag) => typeof tag === "string")) {
+				log.info(`[Config] Loaded sharedComponentTags from toolkit.yaml: ${tags.join(", ")}`);
+				return tags;
+			}
+			log.warn("[Config] sharedComponentTags in toolkit.yaml is not a valid string array, using defaults");
+		}
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code !== "ENOENT") log.warn(`[Config] Failed to parse toolkit.yaml: ${error.message}`);
+	}
+	log.info(`[Config] Using default sharedComponentTags: ${DEFAULT_SHARED_COMPONENT_TAGS.join(", ")}`);
+	return DEFAULT_SHARED_COMPONENT_TAGS;
+}
+/**
+* Get getCssClasses tool configuration from toolkit.yaml.
+*
+* Reads configuration from toolkit.yaml at workspace root under
+* style-system.getCssClasses key.
+*
+* @returns GetCssClassesConfig or undefined if not configured
+*/
+async function getGetCssClassesConfig() {
+	const monorepoRoot = TemplatesManagerService.getWorkspaceRootSync();
+	const toolkitYamlPath = path.join(monorepoRoot, "toolkit.yaml");
+	try {
+		const content = await promises.readFile(toolkitYamlPath, "utf-8");
+		const config = yaml.load(content);
+		if (config?.["style-system"]?.getCssClasses) {
+			const getCssClassesConfig = config["style-system"].getCssClasses;
+			if (getCssClassesConfig.customService !== void 0 && typeof getCssClassesConfig.customService !== "string") {
+				log.warn("[Config] style-system.getCssClasses.customService must be a string, ignoring");
+				return;
+			}
+			log.info(`[Config] Loaded getCssClasses config from toolkit.yaml`);
+			return getCssClassesConfig;
+		}
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code !== "ENOENT") log.warn(`[Config] Failed to parse toolkit.yaml: ${error.message}`);
+	}
+}
+/**
+* Get bundler service configuration from toolkit.yaml.
+*
+* Reads configuration from toolkit.yaml at workspace root under
+* style-system.bundler key.
+*
+* @returns BundlerConfig or undefined if not configured
+*/
+async function getBundlerConfig() {
+	const monorepoRoot = TemplatesManagerService.getWorkspaceRootSync();
+	const toolkitYamlPath = path.join(monorepoRoot, "toolkit.yaml");
+	try {
+		const content = await promises.readFile(toolkitYamlPath, "utf-8");
+		const config = yaml.load(content);
+		if (config?.["style-system"]?.bundler) {
+			const bundlerConfig = config["style-system"].bundler;
+			if (bundlerConfig.customService !== void 0 && typeof bundlerConfig.customService !== "string") {
+				log.warn("[Config] style-system.bundler.customService must be a string, ignoring");
+				return;
+			}
+			log.info(`[Config] Loaded bundler config from toolkit.yaml`);
+			return bundlerConfig;
+		}
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code !== "ENOENT") log.warn(`[Config] Failed to parse toolkit.yaml: ${error.message}`);
+	}
+}
+
+//#endregion
+//#region src/services/CssClasses/BaseCSSClassesService.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
+*   }
+* }
+* ```
+*/
+var BaseCSSClassesService = class {
+	config;
+	/**
+	* Creates a new CSS classes service instance
+	* @param config - Style system configuration from toolkit.yaml
+	*/
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* 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
+	*/
+	async validateThemePath(themePath) {
+		try {
+			await promises.access(themePath);
+		} catch {
+			throw new Error(`Theme file not found or not readable: ${themePath}`);
+		}
+	}
+};
+
+//#endregion
+//#region src/services/CssClasses/TailwindCSSClassesService.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
+* ```
+*/
+var TailwindCSSClassesService = class extends BaseCSSClassesService {
+	/**
+	* Creates a new TailwindCSSClassesService instance
+	* @param config - Style system configuration from toolkit.yaml
+	*/
+	constructor(config) {
+		super(config);
+	}
+	/**
+	* Get the CSS framework identifier
+	* @returns Framework identifier string 'tailwind'
+	*/
+	getFrameworkId() {
+		return "tailwind";
+	}
+	/**
+	* 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
+	*/
+	async extractClasses(category, themePath) {
+		try {
+			await this.validateThemePath(themePath);
+			const resolvedThemePath = path.resolve(themePath);
+			const themeContent = await promises.readFile(resolvedThemePath, "utf-8");
+			const variables = await this.extractVariablesWithPostCSS(themeContent);
+			return this.generateClassesFromVariables(variables, category);
+		} catch (error) {
+			throw new Error(`Failed to extract classes from theme file ${themePath}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	/**
+	* 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;
+	* ```
+	*/
+	async extractVariablesWithPostCSS(themeContent) {
+		const variables = /* @__PURE__ */ new Map();
+		try {
+			postcss.parse(themeContent).walkDecls((decl) => {
+				if (decl.prop.startsWith("--")) {
+					const varName = decl.prop.slice(2);
+					const varValue = decl.value.trim();
+					if (!variables.has(varName)) variables.set(varName, varValue);
+				}
+			});
+		} catch (error) {
+			throw new Error(`Failed to parse CSS content: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		return variables;
+	}
+	/**
+	* 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
+	* // }
+	* ```
+	*/
+	generateClassesFromVariables(variables, category) {
+		const colorClasses = [];
+		const typographyClasses = [];
+		const spacingClasses = [];
+		const effectsClasses = [];
+		for (const [varName, varValue] of variables.entries()) {
+			if (category === "all" || category === "colors") {
+				if (varName.startsWith("color-")) {
+					const colorName = varName.replace("color-", "");
+					colorClasses.push({
+						class: `bg-${colorName}`,
+						value: varValue
+					}, {
+						class: `text-${colorName}`,
+						value: varValue
+					}, {
+						class: `border-${colorName}`,
+						value: varValue
+					}, {
+						class: `ring-${colorName}`,
+						value: varValue
+					});
+				} else if (varName.startsWith("sidebar")) colorClasses.push({
+					class: `bg-${varName}`,
+					value: varValue
+				}, {
+					class: `text-${varName}`,
+					value: varValue
+				}, {
+					class: `border-${varName}`,
+					value: varValue
+				});
+			}
+			if (category === "all" || category === "typography") {
+				if (varName.startsWith("text-")) typographyClasses.push({
+					class: varName,
+					value: varValue
+				});
+				if (varName.startsWith("font-")) {
+					const fontName = varName.replace("font-", "");
+					if (fontName.startsWith("weight-")) typographyClasses.push({
+						class: `font-${fontName.replace("weight-", "")}`,
+						value: varValue
+					});
+					else typographyClasses.push({
+						class: `font-${fontName}`,
+						value: varValue
+					});
+				}
+			}
+			if (category === "all" || category === "spacing") {
+				if (varName.startsWith("space-")) {
+					const spaceName = varName.replace("space-", "");
+					const calcValue = `calc(var(--${varName}) * 1)`;
+					spacingClasses.push({
+						class: `p-${spaceName}`,
+						value: calcValue
+					}, {
+						class: `m-${spaceName}`,
+						value: calcValue
+					}, {
+						class: `gap-${spaceName}`,
+						value: calcValue
+					});
+				} else if (varName === "spacing") spacingClasses.push({
+					class: "space",
+					value: varValue
+				});
+			}
+			if (category === "all" || category === "effects") {
+				if (varName.startsWith("shadow-")) {
+					const shadowName = varName.replace("shadow-", "");
+					effectsClasses.push({
+						class: `shadow-${shadowName}`,
+						value: varValue
+					});
+				}
+			}
+		}
+		const result = {
+			category,
+			classes: {},
+			totalClasses: colorClasses.length + typographyClasses.length + spacingClasses.length + effectsClasses.length
+		};
+		if (category === "all" || category === "colors") result.classes.colors = colorClasses;
+		if (category === "all" || category === "typography") result.classes.typography = typographyClasses;
+		if (category === "all" || category === "spacing") result.classes.spacing = spacingClasses;
+		if (category === "all" || category === "effects") result.classes.effects = effectsClasses;
+		return result;
+	}
+};
+
+//#endregion
+//#region src/services/CssClasses/types.ts
+/**
+* Default configuration values
+*/
+const DEFAULT_STYLE_SYSTEM_CONFIG = { cssFramework: "tailwind" };
+
+//#endregion
+//#region src/services/CssClasses/CSSClassesServiceFactory.ts
+/** Valid file extensions for custom service modules */
+const VALID_SERVICE_EXTENSIONS$1 = [
+	".ts",
+	".js",
+	".mjs",
+	".cjs"
+];
+/**
+* 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');
+* ```
+*/
+var CSSClassesServiceFactory = class {
+	/**
+	* 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
+	*/
+	async createService(config = {}) {
+		const resolvedConfig = {
+			...DEFAULT_STYLE_SYSTEM_CONFIG,
+			...config
+		};
+		if (resolvedConfig.customServicePath) return this.loadCustomService(resolvedConfig);
+		return this.createBuiltInService(resolvedConfig);
+	}
+	/**
+	* 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
+	*/
+	createBuiltInService(config) {
+		switch (config.cssFramework) {
+			case "tailwind": return new TailwindCSSClassesService(config);
+			default: throw new Error(`Unsupported CSS framework: ${config.cssFramework}. Supported frameworks: tailwind. Use customServicePath to provide a custom implementation.`);
+		}
+	}
+	/**
+	* 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
+	*/
+	async loadCustomService(config) {
+		const servicePath = config.customServicePath;
+		if (!servicePath) throw new Error("customServicePath is required for custom service loading");
+		const monorepoRoot = TemplatesManagerService.getWorkspaceRootSync();
+		const resolvedPath = path.resolve(monorepoRoot, servicePath);
+		const normalizedWorkspaceRoot = path.resolve(monorepoRoot);
+		if (!resolvedPath.startsWith(normalizedWorkspaceRoot + path.sep)) throw new Error(`Security error: customServicePath "${servicePath}" resolves outside workspace root`);
+		const ext = path.extname(resolvedPath).toLowerCase();
+		if (!VALID_SERVICE_EXTENSIONS$1.includes(ext)) throw new Error(`Invalid file extension "${ext}" for customServicePath. Expected one of: ${VALID_SERVICE_EXTENSIONS$1.join(", ")}`);
+		log.info(`[CSSClassesServiceFactory] Loading custom CSS service from: ${resolvedPath}`);
+		try {
+			const customModule = await import(resolvedPath);
+			const ServiceClass = customModule.default || customModule.CSSClassesService || customModule.CustomCSSClassesService;
+			if (!ServiceClass) throw new Error(`Custom service module at ${resolvedPath} must export a default class, CSSClassesService, or CustomCSSClassesService that extends BaseCSSClassesService`);
+			const instance = new ServiceClass(config);
+			if (!(instance instanceof BaseCSSClassesService)) throw new Error(`Custom service at ${resolvedPath} must extend BaseCSSClassesService`);
+			log.info(`[CSSClassesServiceFactory] Custom CSS service loaded successfully`);
+			return instance;
+		} catch (error) {
+			if (error instanceof Error && error.message.includes("BaseCSSClassesService")) throw error;
+			throw new Error(`Failed to load custom CSS classes service from ${resolvedPath}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+};
+
+//#endregion
+//#region src/tools/GetCSSClassesTool.ts
+/**
+* Valid CSS class category values
+*/
+const VALID_CATEGORIES = [
+	"colors",
+	"typography",
+	"spacing",
+	"effects",
+	"all"
+];
+/**
+* Type guard to validate category input
+* @param value - Value to check
+* @returns True if value is a valid CSSClassCategory
+*/
+function isValidCategory(value) {
+	return VALID_CATEGORIES.includes(value);
+}
+/**
+* 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' });
+* ```
+*/
+var GetCSSClassesTool = class GetCSSClassesTool {
+	static TOOL_NAME = "get_css_classes";
+	static CSS_REUSE_INSTRUCTION = "IMPORTANT: Always reuse these existing CSS classes from the theme as much as possible instead of creating custom styles. This ensures design consistency and reduces CSS bloat.";
+	serviceFactory;
+	service = null;
+	defaultThemePath;
+	/**
+	* Creates a new GetCSSClassesTool instance
+	* @param defaultThemePath - Default path to theme CSS file (relative to workspace root)
+	*/
+	constructor(defaultThemePath = "packages/frontend/web-theme/src/agimon-theme.css") {
+		this.serviceFactory = new CSSClassesServiceFactory();
+		this.defaultThemePath = defaultThemePath;
+	}
+	/**
+	* Returns the tool definition for MCP registration
+	* @returns Tool definition with name, description, and input schema
+	*/
+	getDefinition() {
+		return {
+			name: GetCSSClassesTool.TOOL_NAME,
+			description: "Extract and return all supported CSS classes from the theme file. Call this tool BEFORE writing any component styles or class names to ensure you use existing theme classes.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					category: {
+						type: "string",
+						enum: [
+							"colors",
+							"typography",
+							"spacing",
+							"effects",
+							"all"
+						],
+						description: "Category filter: 'colors', 'typography', 'spacing', 'effects', 'all' (default)"
+					},
+					appPath: {
+						type: "string",
+						description: "Optional app path (relative or absolute) to read theme path from project.json style-system config (e.g., \"apps/agiflow-app\")"
+					}
+				},
+				additionalProperties: false
+			}
+		};
+	}
+	/**
+	* Executes the CSS class extraction
+	* @param input - Tool input parameters
+	* @returns CallToolResult with extracted CSS classes or error
+	*/
+	async execute(input) {
+		try {
+			const category = input.category || "all";
+			if (!isValidCategory(category)) throw new Error(`Invalid category: '${category}'. Must be one of: ${VALID_CATEGORIES.join(", ")}`);
+			const themePath = await this.resolveThemePath(input.appPath);
+			if (!this.service) {
+				const toolkitConfig = await getGetCssClassesConfig();
+				this.service = await this.serviceFactory.createService({ customServicePath: toolkitConfig?.customService });
+			}
+			const result = await this.service.extractClasses(category, themePath);
+			return { content: [{
+				type: "text",
+				text: `${GetCSSClassesTool.CSS_REUSE_INSTRUCTION}\n\n${JSON.stringify(result, null, 2)}`
+			}] };
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+				}],
+				isError: true
+			};
+		}
+	}
+	/**
+	* 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
+	*/
+	async resolveThemePath(appPath) {
+		const workspaceRoot = TemplatesManagerService.getWorkspaceRootSync();
+		if (appPath) {
+			const config = await getAppDesignSystemConfig(appPath);
+			if (config.themePath) {
+				const resolvedAppPath = path.isAbsolute(appPath) ? appPath : path.join(workspaceRoot, appPath);
+				return path.resolve(resolvedAppPath, config.themePath);
+			}
+		}
+		return path.resolve(workspaceRoot, this.defaultThemePath);
+	}
+};
+
+//#endregion
+//#region src/services/StoriesIndexService/StoriesIndexService.ts
+var StoriesIndexService = class {
+	componentIndex = /* @__PURE__ */ new Map();
+	monorepoRoot;
+	initialized = false;
+	/** Last initialization result for error reporting */
+	lastInitResult = null;
+	/**
+	* Creates a new StoriesIndexService instance
+	*/
+	constructor() {
+		this.monorepoRoot = TemplatesManagerService.getWorkspaceRootSync();
+	}
+	/**
+	* Initialize the index by scanning all .stories files.
+	* @returns Initialization result with success/failure statistics
+	*/
+	async initialize() {
+		if (this.initialized && this.lastInitResult) return this.lastInitResult;
+		log.info("[StoriesIndexService] Initializing story index...");
+		const storyFiles = await glob("**/*.stories.{ts,tsx}", {
+			cwd: this.monorepoRoot,
+			ignore: [
+				"**/node_modules/**",
+				"**/dist/**",
+				"**/.next/**",
+				"**/build/**"
+			],
+			absolute: true
+		});
+		log.info(`[StoriesIndexService] Found ${storyFiles.length} story files`);
+		const failures = [];
+		let successCount = 0;
+		for (const filePath of storyFiles) try {
+			await this.indexStoryFile(filePath);
+			successCount++;
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			log.error(`[StoriesIndexService] Error indexing ${filePath}: ${errorMessage}`);
+			failures.push({
+				filePath,
+				error: errorMessage
+			});
+		}
+		this.initialized = true;
+		this.lastInitResult = {
+			totalFiles: storyFiles.length,
+			successCount,
+			failureCount: failures.length,
+			failures
+		};
+		if (failures.length > 0) log.warn(`[StoriesIndexService] Indexed ${successCount}/${storyFiles.length} files successfully. ${failures.length} files failed.`);
+		else log.info(`[StoriesIndexService] Indexed ${this.componentIndex.size} components successfully`);
+		return this.lastInitResult;
+	}
+	/**
+	* Get the last initialization result.
+	* @returns Initialization result or null if not initialized
+	*/
+	getLastInitResult() {
+		return this.lastInitResult;
+	}
+	/**
+	* 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.
+	*/
+	async indexStoryFile(filePath) {
+		const content = await promises.readFile(filePath, "utf-8");
+		const fileHash = this.hashContent(content);
+		const csf = loadCsf(content, {
+			fileName: filePath,
+			makeTitle: (title) => title
+		});
+		await csf.parse();
+		if (!csf.meta?.title) {
+			log.warn(`[StoriesIndexService] No valid meta title in ${filePath}`);
+			return;
+		}
+		const stories = csf.stories.map((story) => story.name).filter((name) => !!name);
+		const tags = Array.isArray(csf.meta.tags) ? csf.meta.tags.filter((t) => typeof t === "string") : [];
+		const description = this.extractDescription(content, csf.meta);
+		const meta = {
+			title: csf.meta.title,
+			tags
+		};
+		const componentInfo = {
+			title: meta.title,
+			filePath,
+			fileHash,
+			tags,
+			stories,
+			meta,
+			description
+		};
+		this.componentIndex.set(meta.title, componentInfo);
+	}
+	/**
+	* 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
+	*/
+	extractDescription(content, meta) {
+		const docsDescription = (((meta?.parameters)?.docs)?.description)?.component;
+		if (typeof docsDescription === "string" && docsDescription.trim()) return docsDescription.trim();
+		const jsDocMatch = content.match(/^\s*\/\*\*\s*([\s\S]*?)\s*\*\//);
+		if (jsDocMatch?.[1]) {
+			const description = jsDocMatch[1].split("\n").map((line) => line.replace(/^\s*\*\s?/, "").trim()).filter((line) => !line.startsWith("@")).join(" ").replace(/\s+/g, " ").trim();
+			if (description) return description;
+		}
+	}
+	/**
+	* Hash file content for cache invalidation
+	*/
+	hashContent(content) {
+		return createHash("sha256").update(content).digest("hex");
+	}
+	/**
+	* Get all components filtered by tags
+	* @param tags - Optional array of tags to filter by
+	* @returns Array of matching components
+	*/
+	getComponentsByTags(tags) {
+		const components = Array.from(this.componentIndex.values());
+		if (!tags || tags.length === 0) return components;
+		return components.filter((component) => tags.some((tag) => component.tags.includes(tag)));
+	}
+	/**
+	* Get component by title
+	* @param title - Exact title to match (e.g., "Components/Button")
+	* @returns Component info or undefined
+	*/
+	getComponentByTitle(title) {
+		return this.componentIndex.get(title);
+	}
+	/**
+	* Find component by partial name match
+	* @param name - Partial name to search for
+	* @returns First matching component or undefined
+	*/
+	findComponentByName(name) {
+		const lowerName = name.toLowerCase();
+		for (const component of this.componentIndex.values()) if ((component.title.split("/").pop() || component.title).toLowerCase() === lowerName) return component;
+		for (const component of this.componentIndex.values()) if ((component.title.split("/").pop() || component.title).toLowerCase().includes(lowerName)) return component;
+	}
+	/**
+	* Refresh a specific file if it has changed
+	* @param filePath - Absolute path to story file
+	* @returns True if file was updated, false if unchanged
+	*/
+	async refreshFile(filePath) {
+		const content = await promises.readFile(filePath, "utf-8");
+		const newHash = this.hashContent(content);
+		const existingComponent = Array.from(this.componentIndex.values()).find((c) => c.filePath === filePath);
+		if (existingComponent && existingComponent.fileHash === newHash) return false;
+		await this.indexStoryFile(filePath);
+		return true;
+	}
+	/**
+	* Get all indexed components
+	* @returns Array of all component info objects
+	*/
+	getAllComponents() {
+		return Array.from(this.componentIndex.values());
+	}
+	/**
+	* Clear the index (useful for testing)
+	*/
+	clear() {
+		this.componentIndex.clear();
+		this.initialized = false;
+		this.lastInitResult = null;
+	}
+	/**
+	* Get all unique tags from indexed components
+	* @returns Sorted array of unique tag names
+	*/
+	getAllTags() {
+		const tagSet = /* @__PURE__ */ new Set();
+		for (const component of this.componentIndex.values()) for (const tag of component.tags) tagSet.add(tag);
+		return Array.from(tagSet).sort();
+	}
+};
+
+//#endregion
+//#region src/services/AppComponentsService/types.ts
+/**
+* Default configuration values.
+*/
+const DEFAULT_APP_COMPONENTS_CONFIG = { pageSize: 50 };
+
+//#endregion
+//#region src/services/AppComponentsService/AppComponentsService.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: {...} }
+* ```
+*/
+var AppComponentsService = class {
+	config;
+	/**
+	* Creates a new AppComponentsService instance.
+	* @param config - Service configuration options
+	*/
+	constructor(config = {}) {
+		this.config = {
+			...DEFAULT_APP_COMPONENTS_CONFIG,
+			...config
+		};
+	}
+	/**
+	* 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
+	*/
+	async listComponents(input) {
+		if (!input.appPath || typeof input.appPath !== "string") throw new Error("appPath is required and must be a non-empty string");
+		if (input.cursor !== void 0 && typeof input.cursor !== "string") throw new Error("cursor must be a string");
+		const { appPath, cursor } = input;
+		const { offset } = cursor ? this.decodeCursor(cursor) : { offset: 0 };
+		const monorepoRoot = TemplatesManagerService.getWorkspaceRootSync();
+		const resolvedAppPath = path.isAbsolute(appPath) ? appPath : path.join(monorepoRoot, appPath);
+		try {
+			await promises.access(resolvedAppPath);
+		} catch {
+			throw new Error(`App path does not exist: ${resolvedAppPath}`);
+		}
+		const appName = await this.getAppName(resolvedAppPath);
+		const workspaceDependencies = await this.getWorkspaceDependencies(resolvedAppPath);
+		log.info(`[AppComponentsService] Found ${workspaceDependencies.length} workspace dependencies for ${appName}`);
+		const packageMap = await this.buildPackageMap(monorepoRoot);
+		const storiesIndex = new StoriesIndexService();
+		await storiesIndex.initialize();
+		const allComponents = storiesIndex.getAllComponents();
+		const { appComponentsArray, packageComponents, totalPackageComponents } = this.categorizeComponents(allComponents, resolvedAppPath, workspaceDependencies, packageMap);
+		const totalComponents = appComponentsArray.length + totalPackageComponents;
+		const { paginatedAppComponents, paginatedPackageComponents, totalReturned } = this.paginateComponents(appComponentsArray, packageComponents, offset);
+		const hasMore = offset + totalReturned < totalComponents;
+		const result = {
+			app: appName,
+			appComponents: paginatedAppComponents,
+			packageComponents: paginatedPackageComponents,
+			pagination: {
+				offset,
+				pageSize: this.config.pageSize,
+				totalComponents,
+				hasMore
+			}
+		};
+		if (hasMore) result.nextCursor = this.encodeCursor(offset + totalReturned);
+		log.info(`[AppComponentsService] Page ${Math.floor(offset / this.config.pageSize) + 1}: Returned ${totalReturned} of ${totalComponents} total components (hasMore: ${hasMore})`);
+		return result;
+	}
+	/**
+	* 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
+	*/
+	async getAppName(resolvedAppPath) {
+		const projectJsonPath = path.join(resolvedAppPath, "project.json");
+		let appName = path.basename(resolvedAppPath);
+		try {
+			appName = JSON.parse(await promises.readFile(projectJsonPath, "utf-8")).name || appName;
+		} catch (error) {
+			log.warn(`[AppComponentsService] Could not read project.json for ${resolvedAppPath}:`, error);
+		}
+		return appName;
+	}
+	/**
+	* Get workspace dependencies from package.json.
+	* @param resolvedAppPath - Absolute path to the app directory
+	* @returns Array of workspace dependency package names
+	*/
+	async getWorkspaceDependencies(resolvedAppPath) {
+		const packageJsonPath = path.join(resolvedAppPath, "package.json");
+		try {
+			const packageJson = JSON.parse(await promises.readFile(packageJsonPath, "utf-8"));
+			const allDeps = {
+				...packageJson.dependencies,
+				...packageJson.devDependencies
+			};
+			return Object.entries(allDeps).filter(([_name, version]) => typeof version === "string" && version.startsWith("workspace:")).map(([name]) => name);
+		} catch (error) {
+			log.warn(`[AppComponentsService] Could not read package.json for ${resolvedAppPath}:`, error);
+			return [];
+		}
+	}
+	/**
+	* 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
+	*/
+	async buildPackageMap(monorepoRoot) {
+		const packageMap = /* @__PURE__ */ new Map();
+		let packageJsonFiles;
+		try {
+			packageJsonFiles = await glob("**/package.json", {
+				cwd: monorepoRoot,
+				ignore: [
+					"**/node_modules/**",
+					"**/dist/**",
+					"**/.next/**",
+					"**/build/**"
+				],
+				absolute: true
+			});
+		} catch (error) {
+			throw new Error(`Failed to scan for package.json files in ${monorepoRoot}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		for (const pkgJsonPath of packageJsonFiles) try {
+			const content = await promises.readFile(pkgJsonPath, "utf-8");
+			const pkgJson = JSON.parse(content);
+			if (pkgJson.name) {
+				const pkgDir = path.dirname(pkgJsonPath);
+				packageMap.set(pkgJson.name, pkgDir);
+			}
+		} catch (error) {
+			log.debug(`[AppComponentsService] Skipping invalid package.json at ${pkgJsonPath}:`, error);
+		}
+		return packageMap;
+	}
+	/**
+	* 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
+	*/
+	categorizeComponents(allComponents, resolvedAppPath, workspaceDependencies, packageMap) {
+		const appComponentsMap = /* @__PURE__ */ new Map();
+		const packageComponentsMap = {};
+		for (const component of allComponents) {
+			const componentName = component.title.split("/").pop() || component.title;
+			const componentBrief = {
+				name: componentName,
+				...component.description && { description: component.description }
+			};
+			if (component.filePath.startsWith(resolvedAppPath)) appComponentsMap.set(componentName, componentBrief);
+			for (const dep of workspaceDependencies) {
+				const packageDir = packageMap.get(dep);
+				if (packageDir && component.filePath.startsWith(packageDir)) {
+					if (!packageComponentsMap[dep]) packageComponentsMap[dep] = /* @__PURE__ */ new Map();
+					packageComponentsMap[dep].set(componentName, componentBrief);
+				}
+			}
+		}
+		const packageComponents = {};
+		for (const [pkg, componentsMap] of Object.entries(packageComponentsMap)) packageComponents[pkg] = Array.from(componentsMap.values()).sort((a, b) => a.name.localeCompare(b.name));
+		return {
+			appComponentsArray: Array.from(appComponentsMap.values()).sort((a, b) => a.name.localeCompare(b.name)),
+			packageComponents,
+			totalPackageComponents: Object.values(packageComponents).reduce((sum, arr) => sum + arr.length, 0)
+		};
+	}
+	/**
+	* 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
+	*/
+	paginateComponents(appComponentsArray, packageComponents, offset) {
+		const totalPackageComponents = Object.values(packageComponents).reduce((sum, arr) => sum + arr.length, 0);
+		const totalComponents = appComponentsArray.length + totalPackageComponents;
+		const paginatedAppComponents = appComponentsArray.slice(offset, offset + this.config.pageSize);
+		const remainingSpace = this.config.pageSize - paginatedAppComponents.length;
+		const paginatedPackageComponents = {};
+		let packageComponentsConsumed = 0;
+		if (remainingSpace > 0 && offset < totalComponents) {
+			const packageOffset = Math.max(0, offset - appComponentsArray.length);
+			let itemsToTake = remainingSpace;
+			let currentOffset = packageOffset;
+			for (const [pkg, components] of Object.entries(packageComponents)) {
+				if (itemsToTake <= 0) break;
+				if (currentOffset < components.length) {
+					const sliced = components.slice(currentOffset, currentOffset + itemsToTake);
+					paginatedPackageComponents[pkg] = sliced;
+					packageComponentsConsumed += sliced.length;
+					itemsToTake -= sliced.length;
+					currentOffset = 0;
+				} else currentOffset -= components.length;
+			}
+		}
+		return {
+			paginatedAppComponents,
+			paginatedPackageComponents,
+			totalReturned: paginatedAppComponents.length + packageComponentsConsumed
+		};
+	}
+	/**
+	* 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
+	*/
+	encodeCursor(offset) {
+		return Buffer.from(JSON.stringify({ offset })).toString("base64");
+	}
+	/**
+	* 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
+	*/
+	decodeCursor(cursor) {
+		try {
+			const decoded = Buffer.from(cursor, "base64").toString("utf-8");
+			return { offset: JSON.parse(decoded).offset || 0 };
+		} catch {
+			log.debug("[AppComponentsService] Invalid cursor, resetting to offset 0");
+			return { offset: 0 };
+		}
+	}
+};
+
+//#endregion
+//#region src/services/BundlerService/BaseBundlerService.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
+* }
+* ```
+*/
+var BaseBundlerService = class {
+	config;
+	/**
+	* Creates a new bundler service instance.
+	* @param config - Service configuration options
+	*/
+	constructor(config = {}) {
+		this.config = config;
+	}
+};
+
+//#endregion
+//#region src/services/BundlerService/ViteReactBundlerService.ts
+/**
+* Maximum age for story configs in milliseconds (5 minutes).
+* Configs older than this are cleaned up to prevent memory leaks.
+*/
+const STORY_CONFIG_MAX_AGE_MS = 300 * 1e3;
+/**
+* Maximum number of story configs to keep in memory.
+* Oldest configs are removed when this limit is exceeded.
+*/
+const STORY_CONFIG_MAX_COUNT = 100;
+/**
+* Maximum size for serialized args in bytes (1MB).
+* Prevents memory issues with extremely large payloads.
+*/
+const MAX_ARGS_SIZE_BYTES = 1024 * 1024;
+/**
+* Valid pattern for story names.
+* Allows alphanumeric characters, underscores, hyphens, and spaces.
+*/
+const VALID_STORY_NAME_PATTERN = /^[a-zA-Z0-9_\- ]+$/;
+/**
+* Valid pattern for component paths.
+* Must end with .stories.tsx, .stories.ts, .stories.jsx, or .stories.js
+*/
+const VALID_COMPONENT_PATH_PATTERN = /\.stories\.(tsx?|jsx?)$/;
+/**
+* Validates a story name to prevent code injection.
+* @param storyName - The story name to validate
+* @throws Error if the story name contains invalid characters
+*/
+function validateStoryName(storyName) {
+	if (!storyName || typeof storyName !== "string") throw new Error("Story name is required and must be a string");
+	if (!VALID_STORY_NAME_PATTERN.test(storyName)) throw new Error(`Story name "${storyName}" contains invalid characters. Only alphanumeric characters, underscores, hyphens, and spaces are allowed.`);
+}
+/**
+* Validates a component path to prevent code injection.
+* @param componentPath - The component path to validate
+* @throws Error if the component path is invalid
+*/
+function validateComponentPath(componentPath) {
+	if (!componentPath || typeof componentPath !== "string") throw new Error("Component path is required and must be a string");
+	if (!VALID_COMPONENT_PATH_PATTERN.test(componentPath)) throw new Error(`Component path "${componentPath}" must be a valid Storybook story file (*.stories.tsx, *.stories.ts, *.stories.jsx, or *.stories.js)`);
+	if (componentPath.includes("..")) throw new Error("Component path must not contain path traversal sequences (..)");
+}
+/**
+* Validates args object size to prevent memory issues.
+* @param args - The args object to validate
+* @throws Error if args exceed size limit
+*/
+function validateArgsSize(args) {
+	const serialized = JSON.stringify(args);
+	const sizeBytes = Buffer.byteLength(serialized, "utf-8");
+	if (sizeBytes > MAX_ARGS_SIZE_BYTES) throw new Error(`Args payload too large: ${sizeBytes} bytes exceeds maximum of ${MAX_ARGS_SIZE_BYTES} bytes (1MB)`);
+}
+/**
+* Validates CSS file paths to prevent path traversal attacks.
+* @param cssFiles - Array of CSS file paths to validate
+* @param workspaceRoot - The workspace root directory
+* @throws Error if any path is invalid or escapes workspace
+*/
+function validateCssFiles(cssFiles, workspaceRoot) {
+	for (const cssFile of cssFiles) {
+		if (typeof cssFile !== "string") throw new Error("CSS file path must be a string");
+		if (cssFile.includes("..")) throw new Error(`CSS file path "${cssFile}" must not contain path traversal sequences (..)`);
+		if (path.isAbsolute(cssFile)) {
+			if (!path.normalize(cssFile).startsWith(workspaceRoot)) throw new Error(`CSS file path "${cssFile}" must be within workspace boundaries`);
+		}
+		const ext = path.extname(cssFile).toLowerCase();
+		if (![
+			".css",
+			".scss",
+			".sass",
+			".less",
+			".pcss",
+			".postcss"
+		].includes(ext)) throw new Error(`CSS file "${cssFile}" must have a valid CSS extension (.css, .scss, .sass, .less, .pcss)`);
+	}
+}
+/**
+* Helper to create a Vite plugin that serves story entry files from memory.
+*/
+function createStoryEntryPlugin(getStoryConfig, generateCode) {
+	return {
+		name: "vite-plugin-story-entry",
+		enforce: "pre",
+		resolveId(id) {
+			if (id.includes("virtual:story-entry")) {
+				log.debug(`[vite-plugin-story-entry] resolveId: ${id}`);
+				return `\0${id.replace(/^\//, "")}`;
+			}
+		},
+		load(id) {
+			if (id.includes("virtual:story-entry")) {
+				log.debug(`[vite-plugin-story-entry] load: ${id}`);
+				const storyId = id.match(/id=([^&]+)/)?.[1];
+				if (storyId) {
+					const config = getStoryConfig(storyId);
+					if (config) return generateCode(config);
+				}
+				throw new Error(`[Vite] Story config not found for id: ${storyId}`);
+			}
+		}
+	};
+}
+/**
+* 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'
+* });
+* ```
+*/
+var ViteReactBundlerService = class ViteReactBundlerService extends BaseBundlerService {
+	static instance = null;
+	server = null;
+	monorepoRoot;
+	serverUrl = null;
+	serverPort = null;
+	currentAppPath = null;
+	storyConfigs = /* @__PURE__ */ new Map();
+	/** Timestamps for when each story config was created, used for cleanup */
+	storyConfigTimestamps = /* @__PURE__ */ new Map();
+	/** Promise that resolves when server startup completes, prevents race conditions */
+	serverStartPromise = null;
+	/**
+	* Creates a new ViteReactBundlerService instance.
+	* Use getInstance() for singleton access.
+	* @param config - Service configuration options
+	*/
+	constructor(config = {}) {
+		super(config);
+		this.monorepoRoot = TemplatesManagerService.getWorkspaceRootSync();
+	}
+	/**
+	* 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() {
+		if (!ViteReactBundlerService.instance) ViteReactBundlerService.instance = new ViteReactBundlerService();
+		return ViteReactBundlerService.instance;
+	}
+	/**
+	* Reset the singleton instance.
+	* This is primarily used in testing to ensure a fresh instance.
+	* @example
+	* ```typescript
+	* afterEach(() => {
+	*   ViteReactBundlerService.resetInstance();
+	* });
+	* ```
+	*/
+	static resetInstance() {
+		ViteReactBundlerService.instance = null;
+	}
+	/**
+	* Get the bundler identifier.
+	* @returns The bundler ID string ('vite')
+	*/
+	getBundlerId() {
+		return "vite";
+	}
+	/**
+	* Get the framework identifier.
+	* @returns The framework ID string ('react')
+	*/
+	getFrameworkId() {
+		return "react";
+	}
+	/**
+	* Get the current server URL.
+	* @returns Server URL or null if not running
+	*/
+	getServerUrl() {
+		return this.serverUrl;
+	}
+	/**
+	* Get the current server port.
+	* @returns Server port or null if not running
+	*/
+	getServerPort() {
+		return this.serverPort;
+	}
+	/**
+	* Check if the dev server is running.
+	* @returns True if server is running
+	*/
+	isServerRunning() {
+		return this.server !== null && this.serverUrl !== null;
+	}
+	/**
+	* Get the current app path being served.
+	* @returns App path or null if not running
+	*/
+	getCurrentAppPath() {
+		return this.currentAppPath;
+	}
+	/**
+	* 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
+	*/
+	async startDevServer(appPath) {
+		const resolvedAppPath = path.isAbsolute(appPath) ? appPath : path.join(this.monorepoRoot, appPath);
+		if (this.isServerRunning() && this.currentAppPath === resolvedAppPath) {
+			log.info(`[ViteReactBundlerService] Server already running for ${resolvedAppPath}`);
+			return {
+				url: this.serverUrl,
+				port: this.serverPort
+			};
+		}
+		if (this.serverStartPromise) {
+			log.info("[ViteReactBundlerService] Server start already in progress, waiting...");
+			return this.serverStartPromise;
+		}
+		this.serverStartPromise = this.doStartDevServer(resolvedAppPath);
+		try {
+			return await this.serverStartPromise;
+		} finally {
+			this.serverStartPromise = null;
+		}
+	}
+	/**
+	* 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
+	*/
+	async doStartDevServer(resolvedAppPath) {
+		const tmpDir = path.join(resolvedAppPath, ".tmp");
+		try {
+			await promises.mkdir(tmpDir, { recursive: true });
+			const { createServer: createServer$1 } = await import("vite");
+			this.server = await createServer$1({
+				root: tmpDir,
+				base: "/",
+				configFile: false,
+				plugins: [tailwindcss(), createStoryEntryPlugin((id) => this.storyConfigs.get(id), (opts) => this.generateEntryFile(opts))],
+				resolve: { alias: { "@": path.join(resolvedAppPath, "src") } },
+				esbuild: {
+					jsx: "automatic",
+					jsxImportSource: "react"
+				},
+				server: {
+					strictPort: false,
+					open: false
+				}
+			});
+			this.server.middlewares.use(async (req, res, next) => {
+				const url$1 = req.url || "/";
+				const match = url$1.match(/^\/preview\/([^/?]+)/);
+				if (match) {
+					const storyId = match[1];
+					const config = this.storyConfigs.get(storyId);
+					if (config) try {
+						const htmlTemplate = this.generateHtmlTemplate(`@virtual:story-entry?id=${storyId}`, config.darkMode);
+						const transformedHtml = await this.server.transformIndexHtml(url$1, htmlTemplate);
+						res.statusCode = 200;
+						res.setHeader("Content-Type", "text/html");
+						res.end(transformedHtml);
+						return;
+					} catch (e) {
+						const err = e;
+						log.error(`[ViteMiddleware] Error serving preview: ${err.message}`);
+						next(err);
+						return;
+					}
+				}
+				next();
+			});
+			await this.server.listen();
+			const address = this.server.httpServer?.address();
+			if (!address || typeof address === "string") throw new Error("Failed to start Vite dev server. Ensure no other process is using the port.");
+			const port = address.port;
+			const url = `http://localhost:${port}`;
+			this.serverUrl = url;
+			this.serverPort = port;
+			this.currentAppPath = resolvedAppPath;
+			log.info(`[ViteReactBundlerService] Vite dev server started at ${url}`);
+			return {
+				url,
+				port
+			};
+		} catch (error) {
+			const err = /* @__PURE__ */ new Error(`Failed to start dev server for ${resolvedAppPath}: ${error instanceof Error ? error.message : String(error)}`);
+			err.cause = error;
+			throw err;
+		}
+	}
+	/**
+	* 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
+	*/
+	async serveComponent(options) {
+		if (!this.isServerRunning()) throw new Error("Dev server is not running. Start it first using startDevServer().");
+		const { componentPath, storyName, args = {}, darkMode = false, appPath, cssFiles = [], rootComponent } = options;
+		validateStoryName(storyName);
+		validateComponentPath(componentPath);
+		validateArgsSize(args);
+		validateCssFiles(cssFiles, this.monorepoRoot);
+		const resolvedAppPath = path.isAbsolute(appPath) ? appPath : path.join(this.monorepoRoot, appPath);
+		if (this.currentAppPath !== resolvedAppPath) throw new Error(`Dev server is running for ${this.currentAppPath} but requested ${resolvedAppPath}.`);
+		const tmpDir = path.join(resolvedAppPath, ".tmp");
+		try {
+			this.cleanupStaleStoryConfigs();
+			await promises.mkdir(tmpDir, { recursive: true });
+			const wrapperCssPath = path.join(tmpDir, "tailwind-wrapper.css");
+			const wrapperCssContent = this.generateWrapperCss(resolvedAppPath, cssFiles);
+			await promises.writeFile(wrapperCssPath, wrapperCssContent, "utf-8");
+			const timestamp = Date.now();
+			const storyId = `${timestamp}-${Math.random().toString(36).slice(2)}`;
+			this.storyConfigs.set(storyId, {
+				componentPath,
+				storyName,
+				args,
+				appPath: resolvedAppPath,
+				darkMode,
+				cssFiles,
+				rootComponent,
+				tmpDir
+			});
+			this.storyConfigTimestamps.set(storyId, timestamp);
+			const url = `${this.serverUrl}/preview/${storyId}`;
+			const htmlContent = this.generateHtmlTemplate(`@virtual:story-entry?id=${storyId}`, darkMode);
+			log.info(`[ViteReactBundlerService] Component served at: ${url}`);
+			return {
+				url,
+				htmlContent
+			};
+		} catch (error) {
+			const err = /* @__PURE__ */ new Error(`Failed to serve component ${storyName}: ${error instanceof Error ? error.message : String(error)}`);
+			err.cause = error;
+			throw err;
+		}
+	}
+	/**
+	* 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
+	*/
+	async prerenderComponent(options) {
+		const { componentPath, storyName, args = {}, darkMode = false, appPath, cssFiles = [], rootComponent } = options;
+		validateStoryName(storyName);
+		validateComponentPath(componentPath);
+		validateArgsSize(args);
+		validateCssFiles(cssFiles, this.monorepoRoot);
+		const resolvedAppPath = path.isAbsolute(appPath) ? appPath : path.join(this.monorepoRoot, appPath);
+		const tmpDir = path.join(resolvedAppPath, ".tmp");
+		try {
+			await promises.mkdir(tmpDir, { recursive: true });
+			return { htmlFilePath: await this.buildComponent({
+				componentPath,
+				storyName,
+				args,
+				appPath: resolvedAppPath,
+				darkMode,
+				cssFiles,
+				rootComponent,
+				tmpDir
+			}) };
+		} catch (error) {
+			const err = /* @__PURE__ */ new Error(`Failed to prerender component ${storyName}: ${error instanceof Error ? error.message : String(error)}`);
+			err.cause = error;
+			throw err;
+		}
+	}
+	/**
+	* 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.
+	*/
+	async cleanup() {
+		if (this.server) {
+			log.info("[ViteReactBundlerService] Closing Vite dev server...");
+			try {
+				await this.server.close();
+			} catch (error) {
+				log.error(`[ViteReactBundlerService] Error closing server: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			this.server = null;
+			this.serverUrl = null;
+			this.serverPort = null;
+			this.currentAppPath = null;
+			this.serverStartPromise = null;
+			this.storyConfigs.clear();
+			this.storyConfigTimestamps.clear();
+			log.info("[ViteReactBundlerService] Vite dev server closed");
+		}
+	}
+	/**
+	* 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.
+	*/
+	cleanupStaleStoryConfigs() {
+		const now = Date.now();
+		const entriesToDelete = [];
+		for (const [storyId, timestamp] of this.storyConfigTimestamps) if (now - timestamp > STORY_CONFIG_MAX_AGE_MS) entriesToDelete.push(storyId);
+		for (const storyId of entriesToDelete) {
+			this.storyConfigs.delete(storyId);
+			this.storyConfigTimestamps.delete(storyId);
+		}
+		if (entriesToDelete.length > 0) log.debug(`[ViteReactBundlerService] Cleaned up ${entriesToDelete.length} stale story configs`);
+		if (this.storyConfigs.size > STORY_CONFIG_MAX_COUNT) {
+			const toRemove = Array.from(this.storyConfigTimestamps.entries()).sort((a, b) => a[1] - b[1]).slice(0, this.storyConfigs.size - STORY_CONFIG_MAX_COUNT);
+			for (const [storyId] of toRemove) {
+				this.storyConfigs.delete(storyId);
+				this.storyConfigTimestamps.delete(storyId);
+			}
+			log.debug(`[ViteReactBundlerService] Removed ${toRemove.length} oldest story configs to stay under limit`);
+		}
+	}
+	/**
+	* 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
+	*/
+	generateWrapperCss(appPath, cssFiles) {
+		const cssImportStatements = cssFiles.map((cssFile) => {
+			if (cssFile.startsWith("@") || cssFile.startsWith("tailwindcss/")) return `@import '${cssFile}';`;
+			if (cssFile.startsWith("packages/") || cssFile.startsWith("apps/")) return `@import '${path.join(this.monorepoRoot, cssFile)}';`;
+			return `@import '${path.join(appPath, cssFile)}';`;
+		}).join("\n");
+		return `/* Tailwind v4 source configuration for component scanning */
+@source "${path.join(appPath, "src")}";
+
+${cssImportStatements}
+`;
+	}
+	/**
+	* 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
+	*/
+	generateEntryFile(options) {
+		const { componentPath, storyName, args, appPath, darkMode, rootComponent, tmpDir } = options;
+		const argsJson = JSON.stringify(args, null, 2);
+		return `${`import '${path.join(tmpDir, "tailwind-wrapper.css").replace(/\\/g, "/")}';`}
+
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import * as Stories from '${componentPath}';
+${rootComponent ? `import { RootDocument } from '${path.join(appPath, rootComponent).replace(/\\/g, "/")}';` : ""}
+
+// Extract story metadata and the specific story to render
+const meta = Stories.default;
+const Story = Stories['${storyName}'];
+const storyArgs = Story?.args || {};
+// Merge story's default args with any custom args passed in
+const args = { ...storyArgs, ...${argsJson} };
+
+// Create the story element - Storybook stories can define rendering in two ways:
+// 1. A render() function that receives args and context
+// 2. A component reference in meta.component
+let element;
+if (Story?.render) {
+  // Story has custom render function - call it with args and minimal context
+  const RenderComponent = () => Story.render(args, { loaded: {}, args });
+  element = React.createElement(RenderComponent);
+} else {
+  // Story uses component from meta - render with merged args as props
+  const Component = meta.component;
+  element = React.createElement(Component, args);
+}
+
+// Wrap element with root component (theme provider, etc.) if specified
+const Wrapper = ${rootComponent ? "RootDocument" : "React.Fragment"};
+const wrappedElement = React.createElement(Wrapper, ${rootComponent ? `{ darkMode: ${darkMode} }` : "{}"}, element);
+
+// Mount to DOM
+const rootEl = document.getElementById('root');
+if (!rootEl) throw new Error('Root element not found');
+const root = createRoot(rootEl);
+root.render(wrappedElement);
+`;
+	}
+	/**
+	* 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
+	*/
+	generateHtmlTemplate(entryFileName, darkMode) {
+		return `<!DOCTYPE html>
+<html class="${darkMode ? "dark" : ""}">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Component Preview</title>
+  <style>
+    body { margin: 0; padding: 0; }
+    #root { display: inline-block; }
+  </style>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/${entryFileName}"><\/script>
+</body>
+</html>`;
+	}
+	async buildComponent(options) {
+		const { appPath, darkMode, tmpDir, cssFiles = [] } = options;
+		const timestamp = Date.now();
+		try {
+			const wrapperCssPath = path.join(tmpDir, "tailwind-wrapper.css");
+			const wrapperCssContent = this.generateWrapperCss(appPath, cssFiles);
+			await promises.writeFile(wrapperCssPath, wrapperCssContent, "utf-8");
+			const storyId = `build-${timestamp}`;
+			const virtualModuleId = `@virtual:story-entry?id=${storyId}`;
+			const htmlTemplate = this.generateHtmlTemplate(virtualModuleId, darkMode);
+			const htmlTemplateFileName = `index-${timestamp}.html`;
+			const htmlTemplatePath = path.join(tmpDir, htmlTemplateFileName);
+			await promises.writeFile(htmlTemplatePath, htmlTemplate, "utf-8");
+			const { build } = await import("vite");
+			const outDir = path.join(tmpDir, `dist-${timestamp}`);
+			const buildStoryConfigs = /* @__PURE__ */ new Map();
+			buildStoryConfigs.set(storyId, options);
+			await build({
+				root: tmpDir,
+				base: "./",
+				configFile: false,
+				plugins: [
+					tailwindcss(),
+					viteSingleFile(),
+					createStoryEntryPlugin((id) => buildStoryConfigs.get(id), (opts) => this.generateEntryFile(opts))
+				],
+				resolve: { alias: { "@": path.join(appPath, "src") } },
+				esbuild: {
+					jsx: "automatic",
+					jsxImportSource: "react"
+				},
+				build: {
+					outDir,
+					emptyOutDir: false,
+					cssCodeSplit: false,
+					rollupOptions: {
+						input: htmlTemplatePath,
+						output: { inlineDynamicImports: true }
+					}
+				}
+			});
+			const builtHtmlPath = path.join(outDir, htmlTemplateFileName);
+			log.info(`[ViteReactBundlerService] Component built to: ${builtHtmlPath}`);
+			await promises.unlink(htmlTemplatePath).catch((err) => log.debug(`[ViteReactBundlerService] Failed to cleanup temp file: ${err.message}`));
+			return builtHtmlPath;
+		} catch (error) {
+			const err = /* @__PURE__ */ new Error(`Failed to build component: ${error instanceof Error ? error.message : String(error)}`);
+			err.cause = error;
+			throw err;
+		}
+	}
+};
+
+//#endregion
+//#region src/services/BundlerService/BundlerServiceFactory.ts
+/** Valid file extensions for custom service modules */
+const VALID_SERVICE_EXTENSIONS = [
+	".ts",
+	".js",
+	".mjs",
+	".cjs"
+];
+/**
+* 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');
+* ```
+*/
+function createDefaultBundlerService() {
+	return ViteReactBundlerService.getInstance();
+}
+/**
+* Registry of available bundler service factories.
+* Allows registration of custom bundler implementations by key.
+*
+* @example
+* ```typescript
+* // Register a custom bundler
+* bundlerRegistry.set('webpack-react', () => new WebpackReactBundlerService());
+*
+* // Get a bundler by key
+* const factory = bundlerRegistry.get('webpack-react');
+* const bundler = factory?.() ?? createDefaultBundlerService();
+* ```
+*/
+const bundlerRegistry = /* @__PURE__ */ new Map();
+bundlerRegistry.set("vite-react", createDefaultBundlerService);
+/** Cached bundler service instance loaded from config */
+let cachedBundlerService = null;
+/**
+* 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');
+* ```
+*/
+async function getBundlerServiceFromConfig() {
+	if (cachedBundlerService) return cachedBundlerService;
+	const config = await getBundlerConfig();
+	if (!config?.customService) {
+		cachedBundlerService = createDefaultBundlerService();
+		return cachedBundlerService;
+	}
+	const monorepoRoot = TemplatesManagerService.getWorkspaceRootSync();
+	const customServicePath = path.resolve(monorepoRoot, config.customService);
+	const normalizedWorkspaceRoot = path.resolve(monorepoRoot);
+	if (!customServicePath.startsWith(normalizedWorkspaceRoot + path.sep)) {
+		log.error(`[BundlerServiceFactory] Security error: customService path "${config.customService}" resolves outside workspace root`);
+		cachedBundlerService = createDefaultBundlerService();
+		return cachedBundlerService;
+	}
+	const ext = path.extname(customServicePath).toLowerCase();
+	if (!VALID_SERVICE_EXTENSIONS.includes(ext)) {
+		log.error(`[BundlerServiceFactory] Invalid file extension "${ext}" for customService. Expected one of: ${VALID_SERVICE_EXTENSIONS.join(", ")}`);
+		cachedBundlerService = createDefaultBundlerService();
+		return cachedBundlerService;
+	}
+	try {
+		log.info(`[BundlerServiceFactory] Loading custom bundler service from: ${customServicePath}`);
+		const module = await import(customServicePath);
+		if (module.default) {
+			if (typeof module.default === "function" && module.default.prototype) if (typeof module.default.getInstance === "function") cachedBundlerService = module.default.getInstance();
+			else cachedBundlerService = new module.default();
+			else if (typeof module.default === "object") cachedBundlerService = module.default;
+		} else if (typeof module.getInstance === "function") cachedBundlerService = module.getInstance();
+		if (!cachedBundlerService) throw new Error("Custom bundler service module must export a class extending BaseBundlerService as default, an instance as default, or a getInstance() function");
+		const missingMethods = [
+			"getBundlerId",
+			"getFrameworkId",
+			"startDevServer",
+			"serveComponent",
+			"prerenderComponent",
+			"isServerRunning",
+			"getServerUrl",
+			"getServerPort",
+			"getCurrentAppPath",
+			"cleanup"
+		].filter((method) => typeof cachedBundlerService[method] !== "function");
+		if (missingMethods.length > 0) throw new Error(`Custom bundler service must implement BaseBundlerService interface. Missing methods: ${missingMethods.join(", ")}`);
+		log.info(`[BundlerServiceFactory] Custom bundler service loaded successfully`);
+		return cachedBundlerService;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		log.error(`[BundlerServiceFactory] Failed to load custom bundler service: ${message}`);
+		log.info("[BundlerServiceFactory] Falling back to default ViteReactBundlerService");
+		cachedBundlerService = createDefaultBundlerService();
+		return cachedBundlerService;
+	}
+}
+
+//#endregion
+//#region src/utils/screenshot.ts
+const browsers = {
+	chromium,
+	firefox,
+	webkit
+};
+/**
+* Browser launch configurations to try in order of preference.
+* Prefers system-installed Chrome before falling back to Playwright's bundled browsers.
+*/
+const browserLaunchConfigs = [
+	{
+		browserType: chromium,
+		channel: "chrome",
+		name: "System Chrome"
+	},
+	{
+		browserType: chromium,
+		channel: void 0,
+		name: "Playwright Chromium"
+	},
+	{
+		browserType: firefox,
+		channel: void 0,
+		name: "Playwright Firefox"
+	}
+];
+/**
+* Attempts to launch a browser, trying multiple configurations in order of preference.
+* @returns Launched browser instance
+* @throws Error if no browser can be launched
+*/
+async function launchBrowserWithFallback() {
+	const errors = [];
+	for (const config of browserLaunchConfigs) try {
+		const browser = await config.browserType.launch({
+			headless: true,
+			channel: config.channel
+		});
+		console.log(`[screenshot] Using ${config.name}`);
+		return browser;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		errors.push(`${config.name}: ${message}`);
+	}
+	throw new Error(`No browser available. Tried:\n${errors.join("\n")}\n\nPlease install Chrome, or run 'npx playwright install chromium'`);
+}
+async function takeScreenshot(options) {
+	const { url, output, width = 1280, height = 800, fullPage = false, browser: browserName = "chromium", waitTime = 1e3, darkMode = false, mobile = false, generateThumbnail = false, thumbnailWidth = 400, thumbnailQuality = 80, base64 = false } = options;
+	let browser = null;
+	try {
+		if (browserName === "chromium") browser = await launchBrowserWithFallback();
+		else {
+			const browserType = browsers[browserName];
+			if (!browserType) throw new Error(`Unsupported browser: ${browserName}`);
+			browser = await browserType.launch({ headless: true });
+		}
+		const page = await (await browser.newContext({
+			viewport: {
+				width,
+				height
+			},
+			colorScheme: darkMode ? "dark" : "light",
+			isMobile: mobile
+		})).newPage();
+		await page.goto(url, { waitUntil: "networkidle" });
+		if (waitTime > 0) await page.waitForTimeout(waitTime);
+		const screenshotBuffer = await page.screenshot({
+			path: output,
+			fullPage
+		});
+		const result = { imagePath: output };
+		if (generateThumbnail) {
+			const ext = path.extname(output);
+			const thumbnailPath = output.replace(ext, `-thumb${ext}`);
+			await sharp(screenshotBuffer).resize(thumbnailWidth).jpeg({ quality: thumbnailQuality }).toFile(thumbnailPath.replace(ext, ".jpg"));
+			result.thumbnailPath = thumbnailPath.replace(ext, ".jpg");
+		}
+		if (base64) result.base64 = screenshotBuffer.toString("base64");
+		return result;
+	} finally {
+		if (browser) await browser.close();
+	}
+}
+
+//#endregion
+//#region src/services/ThemeService/BaseThemeService.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
+*   }
+* }
+* ```
+*/
+var BaseThemeService = class {
+	config;
+	/**
+	* Creates a new theme service instance
+	* @param config - Theme service configuration
+	*/
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* 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
+	*/
+	async validatePath(filePath) {
+		try {
+			await promises.access(filePath);
+		} catch {
+			throw new Error(`File not found or not readable: ${filePath}`);
+		}
+	}
+};
+
+//#endregion
+//#region src/services/ThemeService/CSSThemeService.ts
+/**
+* CSS-based theme service implementation.
+*
+* Extracts themes from CSS files by parsing class selectors that contain
+* CSS custom properties (variables). Each top-level class selector with
+* color variables is treated as a theme.
+*
+* @example
+* ```typescript
+* const service = new CSSThemeService({ themePath: 'apps/my-app/src/styles/colors.css' });
+* const result = await service.listThemes();
+* console.log(result.themes); // [{ name: 'slate', ... }, { name: 'blue', ... }]
+* ```
+*/
+var CSSThemeService = class extends BaseThemeService {
+	monorepoRoot;
+	/**
+	* Creates a new CSSThemeService instance
+	* @param config - Theme service configuration with themePath or cssFiles
+	*/
+	constructor(config) {
+		super(config);
+		this.monorepoRoot = TemplatesManagerService.getWorkspaceRootSync();
+	}
+	/**
+	* Get the source identifier for this service
+	* @returns 'css-file' identifier
+	*/
+	getSourceId() {
+		return "css-file";
+	}
+	/**
+	* List available themes by parsing CSS files.
+	*
+	* Scans the configured CSS files for class selectors that define
+	* CSS custom properties (--color-*, etc.) and returns them as themes.
+	*
+	* @returns Promise resolving to available themes result
+	* @throws Error if no theme files are configured or files cannot be read
+	*/
+	async listThemes() {
+		const cssFilePaths = this.resolveCSSFilePaths();
+		if (cssFilePaths.length === 0) throw new Error("No theme CSS files configured. Set themePath or cssFiles in project.json style-system config.");
+		const themes = [];
+		for (const cssFilePath of cssFilePaths) try {
+			await this.validatePath(cssFilePath);
+			const fileThemes = await this.extractThemesFromCSS(cssFilePath);
+			themes.push(...fileThemes);
+		} catch (error) {
+			log.warn(`[CSSThemeService] Could not process ${cssFilePath}:`, error);
+		}
+		const uniqueThemes = this.deduplicateThemes(themes);
+		return {
+			themes: uniqueThemes.sort((a, b) => a.name.localeCompare(b.name)),
+			activeTheme: uniqueThemes.length > 0 ? uniqueThemes[0].name : void 0,
+			source: "css-file"
+		};
+	}
+	/**
+	* Resolve configured CSS file paths to absolute paths.
+	* @returns Array of absolute CSS file paths
+	*/
+	resolveCSSFilePaths() {
+		const paths = [];
+		if (this.config.themePath) {
+			const themePath = path.isAbsolute(this.config.themePath) ? this.config.themePath : path.join(this.monorepoRoot, this.config.themePath);
+			paths.push(themePath);
+		}
+		if (this.config.cssFiles && this.config.cssFiles.length > 0) for (const cssFile of this.config.cssFiles) {
+			const cssPath = path.isAbsolute(cssFile) ? cssFile : path.join(this.monorepoRoot, cssFile);
+			if (!paths.includes(cssPath)) paths.push(cssPath);
+		}
+		return paths;
+	}
+	/**
+	* Extract themes from a CSS file by parsing class selectors.
+	*
+	* Identifies class selectors that contain CSS custom property declarations
+	* (--color-*, --primary-*, etc.) and treats each as a theme definition.
+	*
+	* @param cssFilePath - Absolute path to CSS file
+	* @returns Array of ThemeInfo objects
+	*/
+	async extractThemesFromCSS(cssFilePath) {
+		const content = await promises.readFile(cssFilePath, "utf-8");
+		const fileName = path.basename(cssFilePath);
+		const themes = [];
+		try {
+			postcss.parse(content).walkRules((rule) => {
+				const selector = rule.selector.trim();
+				if (!selector.startsWith(".") || selector.includes(" ") || selector.includes(",")) return;
+				const className = selector.slice(1);
+				const colorVariables = {};
+				let hasColorVariables = false;
+				rule.walkDecls((decl) => {
+					if (decl.prop.startsWith("--color-") || decl.prop.startsWith("--primary-")) {
+						colorVariables[decl.prop] = decl.value;
+						hasColorVariables = true;
+					}
+				});
+				if (hasColorVariables) themes.push({
+					name: className,
+					fileName,
+					path: cssFilePath,
+					colorVariables,
+					shadeCount: Object.keys(colorVariables).length
+				});
+			});
+		} catch (error) {
+			throw new Error(`Failed to parse CSS file ${cssFilePath}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		log.info(`[CSSThemeService] Found ${themes.length} themes in ${fileName}`);
+		return themes;
+	}
+	/**
+	* Deduplicate themes by name, keeping the first occurrence.
+	* @param themes - Array of themes to deduplicate
+	* @returns Deduplicated array of themes
+	*/
+	deduplicateThemes(themes) {
+		const seen = /* @__PURE__ */ new Set();
+		return themes.filter((theme) => {
+			if (seen.has(theme.name)) return false;
+			seen.add(theme.name);
+			return true;
+		});
+	}
+};
+
+//#endregion
+//#region src/services/ThemeService/ThemeService.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();
+* ```
+*/
+var ThemeService = class {
+	monorepoRoot;
+	config;
+	/**
+	* Creates a new ThemeService instance
+	* @param config - Design system configuration
+	*/
+	constructor(config) {
+		this.monorepoRoot = TemplatesManagerService.getWorkspaceRootSync();
+		this.config = config;
+		log.info(`[ThemeService] Using theme provider: ${this.config.themeProvider}`);
+		log.info(`[ThemeService] Design system type: ${this.config.type}`);
+	}
+	/**
+	* Get design system configuration
+	* @returns Current design system configuration
+	*/
+	getConfig() {
+		return this.config;
+	}
+	/**
+	* Get theme CSS imports from config or common locations
+	* @returns Array of absolute paths to CSS files
+	*/
+	async getThemeCSS() {
+		if (this.config.cssFiles && this.config.cssFiles.length > 0) return this.config.cssFiles.map((cssFile) => path.isAbsolute(cssFile) ? cssFile : path.join(this.monorepoRoot, cssFile));
+		const cssPatterns = ["**/packages/frontend/web-theme/src/**/*.css", "**/packages/frontend/shared-theme/**/*.css"];
+		const cssFiles = [];
+		for (const pattern of cssPatterns) {
+			const files = await glob(pattern, {
+				cwd: this.monorepoRoot,
+				absolute: true,
+				ignore: ["**/node_modules/**", "**/dist/**"]
+			});
+			cssFiles.push(...files);
+		}
+		return cssFiles;
+	}
+	/**
+	* 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, darkMode = false) {
+		const { themeProvider } = this.config;
+		return `
+import React from 'react';
+import ThemeProvider from '${themeProvider}';
+
+const WrappedComponent = () => {
+  return React.createElement(
+    ThemeProvider,
+    { theme: ${darkMode ? "'dark'" : "'light'"} },
+    ${componentCode}
+  );
+};
+
+export default WrappedComponent;
+    `.trim();
+	}
+	/**
+	* Get inline theme styles for SSR
+	* @param darkMode - Whether to use dark mode styles
+	* @returns Combined CSS content as string
+	*/
+	async getInlineStyles(darkMode = false) {
+		const cssFiles = await this.getThemeCSS();
+		let styles = "";
+		for (const cssFile of cssFiles) try {
+			const content = await promises.readFile(cssFile, "utf-8");
+			styles += content + "\n";
+		} catch (error) {
+			log.warn(`[ThemeService] Could not read CSS file ${cssFile}:`, error);
+		}
+		if (darkMode && styles) styles = `.dark { ${styles} }`;
+		return styles;
+	}
+	/**
+	* Get Tailwind CSS classes for theming
+	* @param darkMode - Whether to use dark mode classes
+	* @returns Array of Tailwind class names
+	*/
+	getTailwindClasses(darkMode = false) {
+		const baseClasses = ["font-sans", "antialiased"];
+		if (darkMode) return [
+			...baseClasses,
+			"dark",
+			"bg-gray-900",
+			"text-white"
+		];
+		return [
+			...baseClasses,
+			"bg-white",
+			"text-gray-900"
+		];
+	}
+	/**
+	* Validate that the theme provider path exists
+	* @returns True if theme provider is valid
+	*/
+	async validateThemeProvider() {
+		try {
+			if (this.config.themeProvider.startsWith("@") || !this.config.themeProvider.startsWith("/")) return true;
+			return (await promises.stat(this.config.themeProvider)).isFile();
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* List all available theme configurations
+	* @returns Object containing themes array and active brand
+	* @throws Error if themes directory cannot be read
+	*/
+	async listAvailableThemes() {
+		const configsPath = path.join(this.monorepoRoot, "packages/frontend/shared-theme/configs");
+		try {
+			const themeFiles = (await promises.readdir(configsPath)).filter((file) => file.endsWith(".json"));
+			const themes = [];
+			let activeBrand;
+			for (const file of themeFiles) {
+				const filePath = path.join(configsPath, file);
+				const content = await promises.readFile(filePath, "utf-8");
+				const themeData = JSON.parse(content);
+				const themeName = file.replace(".json", "");
+				themes.push({
+					name: themeName,
+					fileName: file,
+					path: filePath,
+					colors: themeData.colors || themeData
+				});
+				if (themeName === "lightTheme" || themeName === "agimonTheme") activeBrand = themeName;
+			}
+			return {
+				themes: themes.sort((a, b) => a.name.localeCompare(b.name)),
+				activeBrand
+			};
+		} catch (error) {
+			throw new Error(`Failed to list themes: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+};
+
+//#endregion
+//#region src/services/ThemeService/types.ts
+/**
+* Default theme service configuration
+*/
+const DEFAULT_THEME_SERVICE_CONFIG = {
+	themePath: void 0,
+	cssFiles: [],
+	customServicePath: void 0
+};
+
+//#endregion
+//#region src/services/ThemeService/ThemeServiceFactory.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();
+* ```
+*/
+var ThemeServiceFactory = class {
+	/**
+	* 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
+	*/
+	async createService(config = {}) {
+		const resolvedConfig = {
+			...DEFAULT_THEME_SERVICE_CONFIG,
+			...config
+		};
+		if (resolvedConfig.customServicePath) return this.loadCustomService(resolvedConfig);
+		return new CSSThemeService(resolvedConfig);
+	}
+	/**
+	* 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
+	*/
+	async loadCustomService(config) {
+		const servicePath = config.customServicePath;
+		if (!servicePath) throw new Error("customServicePath is required for custom service loading");
+		try {
+			const customModule = await import(servicePath);
+			const ServiceClass = customModule.default || customModule.ThemeService || customModule.CustomThemeService;
+			if (!ServiceClass) throw new Error(`Custom service module at ${servicePath} must export a default class, ThemeService, or CustomThemeService that extends BaseThemeService`);
+			const instance = new ServiceClass(config);
+			if (!(instance instanceof BaseThemeService)) throw new Error(`Custom service at ${servicePath} must extend BaseThemeService`);
+			return instance;
+		} catch (error) {
+			if (error instanceof Error && error.message.includes("BaseThemeService")) throw error;
+			throw new Error(`Failed to load custom theme service from ${servicePath}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+};
+
+//#endregion
+//#region src/services/ComponentRendererService/ComponentRendererService.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);
+* ```
+*/
+var ComponentRendererService = class ComponentRendererService {
+	monorepoRoot;
+	tmpDir;
+	themeService;
+	appPath;
+	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, appPath, options = {}) {
+		if (!appPath) throw new Error("appPath is required for ComponentRendererService");
+		this.monorepoRoot = TemplatesManagerService.getWorkspaceRootSync();
+		this.appPath = appPath;
+		this.tmpDir = path.join(os.tmpdir(), "style-system");
+		this.themeService = new ThemeService(designSystemConfig);
+		this.bundlerFactory = options.bundlerFactory ?? createDefaultBundlerService;
+	}
+	/**
+	* Get the bundler service instance.
+	* Uses the factory to create/retrieve the bundler.
+	* @returns The bundler service instance
+	*/
+	getBundlerService() {
+		return this.bundlerFactory();
+	}
+	/**
+	* 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
+	*/
+	async renderComponent(componentInfo, options = {}) {
+		const { storyName = componentInfo.stories[0] || "Default", args = {}, darkMode = false, width = 1280, height = 800 } = options;
+		try {
+			log.info(`[ComponentRendererService] Rendering ${componentInfo.title} - ${storyName}`);
+			await promises.mkdir(this.tmpDir, { recursive: true });
+			const designSystemConfig = this.themeService.getConfig();
+			log.info(`[ComponentRendererService] Using theme provider: ${designSystemConfig.themeProvider}`);
+			log.info(`[ComponentRendererService] Design system type: ${designSystemConfig.type}`);
+			if (!await this.themeService.validateThemeProvider()) log.warn(`[ComponentRendererService] Theme provider path may not exist: ${designSystemConfig.themeProvider}`);
+			const bundlerService = this.getBundlerService();
+			let componentUrl;
+			let htmlFilePath;
+			if (bundlerService.isServerRunning()) {
+				log.info("[ComponentRendererService] Using dev server for fast rendering");
+				try {
+					const result = await bundlerService.serveComponent({
+						componentPath: componentInfo.filePath,
+						storyName,
+						args,
+						themePath: designSystemConfig.themeProvider,
+						darkMode,
+						appPath: this.appPath,
+						cssFiles: designSystemConfig.cssFiles || [],
+						rootComponent: designSystemConfig.rootComponent
+					});
+					componentUrl = result.url;
+					htmlFilePath = result.htmlFilePath;
+					log.info(`[ComponentRendererService] Component served at: ${componentUrl}`);
+				} catch (devServerError) {
+					log.warn(`[ComponentRendererService] Dev server failed, falling back to static build: ${devServerError instanceof Error ? devServerError.message : String(devServerError)}`);
+					const result = await bundlerService.prerenderComponent({
+						componentPath: componentInfo.filePath,
+						storyName,
+						args,
+						themePath: designSystemConfig.themeProvider,
+						darkMode,
+						appPath: this.appPath,
+						cssFiles: designSystemConfig.cssFiles || [],
+						rootComponent: designSystemConfig.rootComponent
+					});
+					componentUrl = `file://${result.htmlFilePath}`;
+					htmlFilePath = result.htmlFilePath;
+					log.info(`[ComponentRendererService] HTML built to: ${htmlFilePath}`);
+				}
+			} else {
+				log.info("[ComponentRendererService] No dev server running, using static build");
+				const result = await bundlerService.prerenderComponent({
+					componentPath: componentInfo.filePath,
+					storyName,
+					args,
+					themePath: designSystemConfig.themeProvider,
+					darkMode,
+					appPath: this.appPath,
+					cssFiles: designSystemConfig.cssFiles || [],
+					rootComponent: designSystemConfig.rootComponent
+				});
+				componentUrl = `file://${result.htmlFilePath}`;
+				htmlFilePath = result.htmlFilePath;
+				log.info(`[ComponentRendererService] HTML built to: ${htmlFilePath}`);
+			}
+			const timestamp = Date.now();
+			const imageName = `component-${componentInfo.title.split("/").pop()}-${timestamp}.png`;
+			const imagePath = path.join(this.tmpDir, imageName);
+			await takeScreenshot({
+				url: componentUrl,
+				output: imagePath,
+				width,
+				height,
+				fullPage: true,
+				browser: "chromium",
+				waitTime: 2e3,
+				darkMode,
+				mobile: false,
+				generateThumbnail: true,
+				thumbnailWidth: 900,
+				thumbnailQuality: 80,
+				base64: false
+			});
+			log.info(`[ComponentRendererService] Screenshot saved to: ${imagePath}`);
+			let html = "";
+			if (htmlFilePath) {
+				html = await promises.readFile(htmlFilePath, "utf-8");
+				log.info(`[ComponentRendererService] HTML file kept at: ${htmlFilePath}`);
+			} else log.warn("[ComponentRendererService] No HTML file path available, returning empty HTML content");
+			return {
+				imagePath,
+				html,
+				componentInfo
+			};
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			throw new Error(`Failed to render component ${componentInfo.title} (${storyName}): ${errorMessage}`);
+		}
+	}
+	/**
+	* Maximum number of screenshot files to keep in temp directory.
+	* Prevents disk space issues on long-running servers.
+	*/
+	static MAX_TEMP_FILES = 100;
+	/**
+	* 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)
+	*/
+	async cleanup(olderThanMs = 36e5) {
+		try {
+			const files = await promises.readdir(this.tmpDir);
+			const now = Date.now();
+			const componentFiles = [];
+			for (const file of files) if (file.startsWith("component-")) {
+				const filePath = path.join(this.tmpDir, file);
+				try {
+					const stats = await promises.stat(filePath);
+					componentFiles.push({
+						name: file,
+						path: filePath,
+						mtime: stats.mtimeMs
+					});
+				} catch {}
+			}
+			let deletedCount = 0;
+			for (const file of componentFiles) if (now - file.mtime > olderThanMs) {
+				await promises.unlink(file.path).catch((err) => log.warn("[ComponentRendererService] Failed to delete file:", file.path, err));
+				deletedCount++;
+			}
+			const remainingFiles = componentFiles.filter((f) => now - f.mtime <= olderThanMs);
+			if (remainingFiles.length > ComponentRendererService.MAX_TEMP_FILES) {
+				remainingFiles.sort((a, b) => a.mtime - b.mtime);
+				const toDelete = remainingFiles.slice(0, remainingFiles.length - ComponentRendererService.MAX_TEMP_FILES);
+				for (const file of toDelete) {
+					await promises.unlink(file.path).catch((err) => log.warn("[ComponentRendererService] Failed to delete file:", file.path, err));
+					deletedCount++;
+				}
+			}
+			if (deletedCount > 0) log.info(`[ComponentRendererService] Cleaned up ${deletedCount} temp files`);
+		} catch (error) {
+			log.error("[ComponentRendererService] Cleanup error:", error);
+		}
+	}
+	/**
+	* Cleanup bundler server and temp files.
+	* Called on service shutdown.
+	*/
+	async dispose() {
+		try {
+			await this.cleanup(0);
+			const bundlerService = this.getBundlerService();
+			if (!bundlerService.isServerRunning()) await bundlerService.cleanup();
+		} catch (error) {
+			log.error("[ComponentRendererService] Dispose error:", error);
+		}
+	}
+};
+
+//#endregion
+//#region src/services/GetUiComponentService/types.ts
+/**
+* Default configuration values.
+*/
+const DEFAULT_GET_UI_COMPONENT_CONFIG = {
+	defaultStoryName: "Playground",
+	defaultDarkMode: true,
+	defaultWidth: 1280,
+	defaultHeight: 800
+};
+
+//#endregion
+//#region src/services/GetUiComponentService/GetUiComponentService.ts
+/**
+* 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);
+* ```
+*/
+var GetUiComponentService = class {
+	config;
+	storiesIndexFactory;
+	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 = {}, storiesIndexFactory = () => new StoriesIndexService(), rendererFactory = (c, p) => new ComponentRendererService(c, p)) {
+		this.config = {
+			...DEFAULT_GET_UI_COMPONENT_CONFIG,
+			...config
+		};
+		this.storiesIndexFactory = storiesIndexFactory;
+		this.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
+	*/
+	async getComponent(input) {
+		if (!input.componentName || typeof input.componentName !== "string") throw new Error("componentName is required and must be a non-empty string");
+		if (!input.appPath || typeof input.appPath !== "string") throw new Error("appPath is required and must be a non-empty string");
+		if (input.storyName !== void 0 && typeof input.storyName !== "string") throw new Error("storyName must be a string");
+		if (input.darkMode !== void 0 && typeof input.darkMode !== "boolean") throw new Error("darkMode must be a boolean");
+		if (input.selector !== void 0) {
+			if (typeof input.selector !== "string") throw new Error("selector must be a string");
+			if (!/^[a-zA-Z0-9_\-#.\[\]=":' ]+$/.test(input.selector)) throw new Error("selector contains invalid characters");
+			if (/javascript:|expression\(|url\(/i.test(input.selector)) throw new Error("selector contains potentially malicious content");
+		}
+		const { componentName, appPath, storyName = this.config.defaultStoryName, darkMode = this.config.defaultDarkMode } = input;
+		log.info(`[GetUiComponentService] Starting for component: ${componentName}, appPath: ${appPath}, storyName: ${storyName}`);
+		const storiesIndex = this.storiesIndexFactory();
+		try {
+			await storiesIndex.initialize();
+		} catch (error) {
+			throw new Error(`Failed to initialize stories index: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const componentInfo = storiesIndex.findComponentByName(componentName);
+		if (!componentInfo) throw new Error(`Component "${componentName}" not found in stories index. Ensure the component has a .stories.tsx file and has been indexed.`);
+		log.info(`[GetUiComponentService] Found component: ${componentInfo.title}`);
+		const validStoryName = this.resolveStoryName(storyName, componentInfo.stories);
+		const designSystemConfig = await getAppDesignSystemConfig(appPath);
+		log.info(`[GetUiComponentService] Using theme provider: ${designSystemConfig.themeProvider}`);
+		log.info(`[GetUiComponentService] Design system type: ${designSystemConfig.type}`);
+		const renderer = this.rendererFactory(designSystemConfig, appPath);
+		try {
+			const renderResult = await renderer.renderComponent(componentInfo, {
+				storyName: validStoryName,
+				width: this.config.defaultWidth,
+				height: this.config.defaultHeight,
+				darkMode
+			});
+			log.info(`[GetUiComponentService] Component rendered to: ${renderResult.imagePath}`);
+			const storyFileContent = await this.readStoryFile(componentInfo.filePath);
+			log.info("[GetUiComponentService] Completed successfully");
+			return {
+				imagePath: renderResult.imagePath,
+				format: "png",
+				dimensions: "900px width, 80% quality",
+				storyFilePath: componentInfo.filePath,
+				storyFileContent,
+				componentTitle: componentInfo.title,
+				availableStories: componentInfo.stories,
+				renderedStory: validStoryName
+			};
+		} finally {
+			await renderer.dispose();
+		}
+	}
+	/**
+	* 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)
+	*/
+	resolveStoryName(requestedStory, availableStories) {
+		if (availableStories.includes(requestedStory)) return requestedStory;
+		log.warn(`[GetUiComponentService] Story "${requestedStory}" not found, available stories: ${availableStories.join(", ")}`);
+		const fallbackStory = availableStories[0] || "Default";
+		log.info(`[GetUiComponentService] Using fallback story: ${fallbackStory}`);
+		return fallbackStory;
+	}
+	/**
+	* Read the story file content.
+	*
+	* @param filePath - Path to the story file
+	* @returns File content or error message
+	*/
+	async readStoryFile(filePath) {
+		try {
+			const content = await promises.readFile(filePath, "utf-8");
+			log.info(`[GetUiComponentService] Story file read successfully (${content.length} chars)`);
+			return content;
+		} catch (error) {
+			log.warn(`[GetUiComponentService] Warning: Could not read story file: ${error instanceof Error ? error.message : String(error)}`);
+			return `// Could not read file: ${filePath}\n// Error: ${error instanceof Error ? error.message : String(error)}`;
+		}
+	}
+};
+
+//#endregion
+//#region src/tools/GetComponentVisualTool.ts
+/**
+* Template for visual review instructions returned with component screenshots.
+* Guides the LLM to verify visual correctness of the rendered component.
+* @param imagePath - Path to the component screenshot image
+* @returns Formatted markdown string with visual review instructions
+*/
+const REVIEW_INSTRUCTIONS_TEMPLATE = (imagePath) => `
+## Visual Review Instructions
+
+Please review the component screenshot and story code to verify visual correctness:
+
+1. **Read the screenshot** at: ${imagePath}
+2. **Compare with the story code** to ensure the rendered output matches expectations
+3. **Check for visual issues**:
+   - Are all variants rendering correctly?
+   - Are colors, spacing, and typography as expected?
+   - Are interactive states (hover, disabled, loading) properly styled?
+   - Is the layout and alignment correct?
+
+If you notice any visual discrepancies between the code and the rendered output, please report them.
+`;
+var GetComponentVisualTool = class GetComponentVisualTool {
+	static TOOL_NAME = "get_component_visual";
+	service;
+	/**
+	* Creates a new GetComponentVisualTool instance.
+	* @param service - Optional service instance for dependency injection (useful for testing)
+	*/
+	constructor(service) {
+		this.service = service ?? new GetUiComponentService();
+	}
+	/**
+	* Returns the tool definition including name, description, and input schema.
+	* @returns Tool definition with JSON Schema for input validation
+	*/
+	getDefinition() {
+		return {
+			name: GetComponentVisualTool.TOOL_NAME,
+			description: "Get a image preview of a UI component with app-specific design system configuration. Useful when work on the frontend design to review the UI quickly without running the full app.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					componentName: {
+						type: "string",
+						minLength: 1,
+						description: "The name of the component to capture (e.g., \"Button\", \"Card\", etc.)"
+					},
+					appPath: {
+						type: "string",
+						minLength: 1,
+						description: "The app path (relative or absolute) to load design system configuration from (e.g., \"apps/agiflow-app\"). The design system config is read from {appPath}/project.json"
+					},
+					storyName: {
+						type: "string",
+						minLength: 1,
+						description: "The story name to render (e.g., \"Playground\", \"Default\"). Defaults to \"Playground\"."
+					},
+					darkMode: {
+						type: "boolean",
+						description: "Whether to render the component in dark mode. Defaults to true."
+					},
+					selector: {
+						type: "string",
+						minLength: 1,
+						description: "CSS selector to target specific element for screenshot. When provided, screenshot will auto-resize to element dimensions. Defaults to \"#root\"."
+					}
+				},
+				required: ["componentName", "appPath"],
+				additionalProperties: false
+			}
+		};
+	}
+	/**
+	* 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
+	*/
+	async execute(input) {
+		try {
+			const result = await this.service.getComponent(input);
+			const reviewInstructions = REVIEW_INSTRUCTIONS_TEMPLATE(result.imagePath);
+			return { content: [{
+				type: "text",
+				text: JSON.stringify(result, null, 2)
+			}, {
+				type: "text",
+				text: reviewInstructions
+			}] };
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+				}],
+				isError: true
+			};
+		}
+	}
+};
+
+//#endregion
+//#region src/tools/ListAppComponentsTool.ts
+/**
+* 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: {...} }
+* ```
+*/
+var ListAppComponentsTool = class ListAppComponentsTool {
+	static TOOL_NAME = "list_app_components";
+	static COMPONENT_REUSE_INSTRUCTION = "IMPORTANT: Before creating new components, check if a similar component already exists in the list above. Always reuse existing components to maintain consistency and reduce code duplication.";
+	service;
+	constructor() {
+		this.service = new AppComponentsService();
+	}
+	/**
+	* Gets the tool definition including name, description, and input schema.
+	* @returns Tool definition for MCP registration
+	*/
+	getDefinition() {
+		return {
+			name: ListAppComponentsTool.TOOL_NAME,
+			description: "List app-specific components and package components used by an app. Call this tool BEFORE creating new components to check if a similar component already exists. Reads the app's package.json to find workspace dependencies and returns components from both the app and its dependent packages.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					appPath: {
+						type: "string",
+						description: "The app path (relative or absolute) to list components for (e.g., \"apps/my-app\")",
+						minLength: 1
+					},
+					cursor: {
+						type: "string",
+						description: "Optional pagination cursor to fetch the next page of results. Omit to fetch the first page."
+					}
+				},
+				required: ["appPath"],
+				additionalProperties: false
+			}
+		};
+	}
+	/**
+	* 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
+	*/
+	async execute(input) {
+		try {
+			const result = await this.service.listComponents({
+				appPath: input.appPath,
+				cursor: input.cursor
+			});
+			return { content: [{
+				type: "text",
+				text: `${ListAppComponentsTool.COMPONENT_REUSE_INSTRUCTION}\n\n${JSON.stringify(result, null, 2)}`
+			}] };
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+				}],
+				isError: true
+			};
+		}
+	}
+};
+
+//#endregion
+//#region src/tools/ListThemesTool.ts
+/**
+* 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' }
+* ```
+*/
+var ListThemesTool = class ListThemesTool {
+	static TOOL_NAME = "list_themes";
+	serviceFactory;
+	constructor() {
+		this.serviceFactory = new ThemeServiceFactory();
+	}
+	getDefinition() {
+		return {
+			name: ListThemesTool.TOOL_NAME,
+			description: "List all available theme configurations. Reads themes from CSS files configured in the app's project.json style-system config.",
+			inputSchema: {
+				type: "object",
+				properties: { appPath: {
+					type: "string",
+					description: "App path (relative or absolute) to read theme config from project.json (e.g., \"apps/my-app\")"
+				} },
+				additionalProperties: false
+			}
+		};
+	}
+	async execute(input) {
+		try {
+			let themePath;
+			let cssFiles;
+			if (input.appPath) {
+				const appConfig = await getAppDesignSystemConfig(input.appPath);
+				themePath = appConfig.themePath;
+				cssFiles = appConfig.cssFiles;
+			}
+			const result = await (await this.serviceFactory.createService({
+				themePath,
+				cssFiles
+			})).listThemes();
+			return { content: [{
+				type: "text",
+				text: JSON.stringify(result, null, 2)
+			}] };
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+				}],
+				isError: true
+			};
+		}
+	}
+};
+
+//#endregion
+//#region src/tools/ListSharedComponentsTool.ts
+var ListSharedComponentsTool = class ListSharedComponentsTool {
+	static TOOL_NAME = "list_shared_components";
+	static PAGE_SIZE = 50;
+	static COMPONENT_REUSE_INSTRUCTION = "IMPORTANT: Before creating new components, check if a similar component already exists in the list above. Always reuse existing shared components to maintain consistency and reduce code duplication.";
+	/**
+	* Encode pagination state into an opaque cursor string
+	* @param offset - The current offset in the component list
+	* @returns Base64 encoded cursor string
+	*/
+	encodeCursor(offset) {
+		return Buffer.from(JSON.stringify({ offset })).toString("base64");
+	}
+	/**
+	* Decode cursor string into pagination state
+	* @param cursor - Base64 encoded cursor string
+	* @returns Object containing the offset
+	*/
+	decodeCursor(cursor) {
+		try {
+			const decoded = Buffer.from(cursor, "base64").toString("utf-8");
+			return { offset: JSON.parse(decoded).offset || 0 };
+		} catch {
+			return { offset: 0 };
+		}
+	}
+	/**
+	* Gets the tool definition including name, description, and input schema.
+	* @returns Tool definition for MCP registration
+	*/
+	getDefinition() {
+		return {
+			name: ListSharedComponentsTool.TOOL_NAME,
+			description: "List shared UI components from the design system. Call this tool BEFORE creating new components to check if a similar component already exists. Use the \"tags\" parameter to filter by specific tags. If no tags provided, uses configured sharedComponentTags from toolkit.yaml (default: style-system). The response includes \"availableTags\" showing all tags in the codebase for filtering.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					tags: {
+						type: "array",
+						items: { type: "string" },
+						description: "Optional array of tags to filter components by. If not provided, uses configured sharedComponentTags from toolkit.yaml. Pass an empty array [] to list ALL components."
+					},
+					cursor: {
+						type: "string",
+						description: "Optional pagination cursor to fetch the next page of results. Omit to fetch the first page."
+					}
+				},
+				additionalProperties: false
+			}
+		};
+	}
+	/**
+	* 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
+	*/
+	async execute(input) {
+		try {
+			const { cursor, tags: inputTags } = input;
+			const { offset } = cursor ? this.decodeCursor(cursor) : { offset: 0 };
+			const storiesIndex = new StoriesIndexService();
+			await storiesIndex.initialize();
+			const availableTags = storiesIndex.getAllTags();
+			let filterTags;
+			if (inputTags !== void 0) filterTags = inputTags;
+			else filterTags = await getSharedComponentTags();
+			const allComponentNames = storiesIndex.getComponentsByTags(filterTags.length > 0 ? filterTags : void 0).map((component) => component.title.split("/").pop() || component.title).filter((name, index, self) => self.indexOf(name) === index).sort();
+			const totalComponents = allComponentNames.length;
+			const paginatedComponents = allComponentNames.slice(offset, offset + ListSharedComponentsTool.PAGE_SIZE);
+			const hasMore = offset + paginatedComponents.length < totalComponents;
+			const result = {
+				filteredByTags: filterTags,
+				availableTags,
+				components: paginatedComponents,
+				pagination: {
+					offset,
+					pageSize: ListSharedComponentsTool.PAGE_SIZE,
+					totalComponents,
+					hasMore
+				}
+			};
+			if (hasMore) result.nextCursor = this.encodeCursor(offset + paginatedComponents.length);
+			log.info(`[ListSharedComponentsTool] Tags: [${filterTags.join(", ")}], Page ${Math.floor(offset / ListSharedComponentsTool.PAGE_SIZE) + 1}: Returned ${paginatedComponents.length} of ${totalComponents} total components (hasMore: ${hasMore})`);
+			return { content: [{
+				type: "text",
+				text: `${ListSharedComponentsTool.COMPONENT_REUSE_INSTRUCTION}\n\n${JSON.stringify(result, null, 2)}`
+			}] };
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: `Failed to list shared components: ${error instanceof Error ? error.message : "Unknown error"}`
+				}],
+				isError: true
+			};
+		}
+	}
+};
+
+//#endregion
+//#region src/server/index.ts
+function createServer(themePath = "packages/frontend/web-theme/src/agimon-theme.css") {
+	const server = new Server({
+		name: "style-system-mcp",
+		version: "0.1.0"
+	}, {
+		capabilities: { tools: {} },
+		instructions: "Use this MCP when you work on the frontend or design. You can use this to list supported themes, get the correct tailwind classes supported by the repo, list design system components, and get visual + detailed implementation of components."
+	});
+	const listThemesTool = new ListThemesTool();
+	const getCSSClassesTool = new GetCSSClassesTool(themePath);
+	const getComponentVisualTool = new GetComponentVisualTool();
+	const listSharedComponentsTool = new ListSharedComponentsTool();
+	const listAppComponentsTool = new ListAppComponentsTool();
+	server.setRequestHandler(ListToolsRequestSchema, async () => {
+		return { tools: [
+			listThemesTool.getDefinition(),
+			getCSSClassesTool.getDefinition(),
+			getComponentVisualTool.getDefinition(),
+			listSharedComponentsTool.getDefinition(),
+			listAppComponentsTool.getDefinition()
+		] };
+	});
+	server.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const { name, arguments: args } = request.params;
+		if (name === ListThemesTool.TOOL_NAME) return await listThemesTool.execute({});
+		if (name === GetCSSClassesTool.TOOL_NAME) return await getCSSClassesTool.execute(args);
+		if (name === GetComponentVisualTool.TOOL_NAME) return await getComponentVisualTool.execute(args);
+		if (name === ListSharedComponentsTool.TOOL_NAME) return await listSharedComponentsTool.execute({});
+		if (name === ListAppComponentsTool.TOOL_NAME) return await listAppComponentsTool.execute(args);
+		return {
+			content: [{
+				type: "text",
+				text: `Error: Unknown tool: ${name}`
+			}],
+			isError: true
+		};
+	});
+	return server;
+}
+
+//#endregion
+//#region src/transports/stdio.ts
+/**
+* Stdio transport handler for MCP server
+* Used for command-line and direct integrations
+*/
+var StdioTransportHandler = class {
+	server;
+	transport = null;
+	constructor(server) {
+		this.server = server;
+	}
+	async start() {
+		this.transport = new StdioServerTransport();
+		await this.server.connect(this.transport);
+		log.info("style-system-mcp MCP server started on stdio");
+	}
+	async stop() {
+		if (this.transport) {
+			await this.transport.close();
+			this.transport = null;
+		}
+	}
+};
+
+//#endregion
+export { TailwindCSSClassesService as _, ListAppComponentsTool as a, ThemeService as c, ViteReactBundlerService as d, BaseBundlerService as f, DEFAULT_STYLE_SYSTEM_CONFIG as g, CSSClassesServiceFactory as h, ListThemesTool as i, createDefaultBundlerService as l, GetCSSClassesTool as m, createServer as n, GetComponentVisualTool as o, StoriesIndexService as p, ListSharedComponentsTool as r, ComponentRendererService as s, StdioTransportHandler as t, getBundlerServiceFromConfig as u, BaseCSSClassesService as v };