@meng-xi/vite-plugin 0.1.1 → 0.1.3

package/README-en.md

@@ -15,9 +15,11 @@
 
 ## Features
 
-- **Ready to Use** - Provides 8 practical plugins covering build progress display, file copying, router generation, version management, version update checking, HTML injection, icon injection, and global Loading state
-  management
-- **Plugin Development Framework** - Exports core components like BasePlugin, Logger, Validator for building custom Vite plugins
+- **Ready to Use** - Provides 10 practical plugins covering build progress display, build artifact analysis & compression, file copying, router generation, version management, version update checking, HTML injection,
+  icon injection, and global Loading state management
+- **Plugin Development Framework** - Exports core components like BasePlugin, Logger, Validator for building custom Vite plugins that follow conventions
+- **Common Utility Library** - Built-in Common module providing reusable utility functions for formatting, file system, compression, path handling, HTML injection, object operations, script generation, and parameter
+  validation
 - **Complete Lifecycle** - Supports initialization, config resolution, destroy lifecycle management with automatic hook composition
 - **Type Safe** - Complete TypeScript type definitions with configuration validators ensuring parameter correctness
 - **Flexible Configuration** - All plugins support detailed configuration to meet diverse scenario requirements
@@ -47,53 +49,22 @@ pnpm add @meng-xi/vite-plugin -D
 
 ```typescript
 import { defineConfig } from 'vite'
-import { buildProgress, copyFile, generateRouter, generateVersion, versionUpdateChecker, htmlInject, faviconManager, loadingManager } from '@meng-xi/vite-plugin'
+import { buildProgress, bundleAnalyzer, compressAssets, copyFile, generateRouter, generateVersion, versionUpdateChecker, htmlInject, faviconManager, loadingManager } from '@meng-xi/vite-plugin'
 
 export default defineConfig({
 	plugins: [
-		// Build progress bar
 		buildProgress(),
-
-		// Copy files
-		copyFile({
-			sourceDir: 'src/assets',
-			targetDir: 'dist/assets'
-		}),
-
-		// Generate router config (uni-app)
-		generateRouter({
-			pagesJsonPath: 'src/pages.json',
-			outputPath: 'src/router.config.ts'
-		}),
-
-		// Generate version
-		generateVersion({
-			format: 'datetime',
-			outputType: 'both'
-		}),
-
-		// Version update checker (works with generateVersion)
+		bundleAnalyzer({ outputFormat: 'both', sizeThreshold: 200 }),
+		compressAssets({ algorithm: 'gzip' }),
+		copyFile({ sourceDir: 'src/assets', targetDir: 'dist/assets' }),
+		generateRouter({ pagesJsonPath: 'src/pages.json', outputPath: 'src/router.config.ts' }),
+		generateVersion({ format: 'datetime', outputType: 'both' }),
 		versionUpdateChecker(),
-
-		// HTML content injection
 		htmlInject({
-			rules: [
-				{
-					id: 'meta-description',
-					content: '<meta name="description" content="My App">',
-					position: 'head-end'
-				}
-			]
+			rules: [{ id: 'meta-description', content: '<meta name="description" content="My App">', position: 'head-end' }]
 		}),
-
-		// Inject website icon (supports string shorthand)
 		faviconManager('/assets'),
-
-		// Global Loading state management
-		loadingManager({
-			defaultVisible: true,
-			autoHideOn: 'DOMContentLoaded'
-		})
+		loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' })
 	]
 })
 ```
@@ -107,23 +78,25 @@ import type { PluginWithInstance } from '@meng-xi/vite-plugin/factory'
 import type { GenerateRouterOptions } from '@meng-xi/vite-plugin'
 
 const routerPlugin = generateRouter({ watch: true }) as PluginWithInstance<GenerateRouterOptions>
-
-// Access plugin internals via pluginInstance
 console.log(routerPlugin.pluginInstance?.options)
 ```
 
 ## Built-in Plugins
 
-| Plugin               | Description                                                                                                       |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| buildProgress        | Real-time build progress bar in terminal, supports bar / spinner / minimal                                        |
-| copyFile             | Copy files or directories after build, supports incremental copying                                               |
-| generateRouter       | Auto-generate router config from pages.json (uni-app)                                                             |
-| generateVersion      | Auto-generate version numbers, supports file output and global variable injection                                 |
-| versionUpdateChecker | Runtime version update checking with multiple prompt styles and custom callbacks                                  |
-| htmlInject           | HTML content injection with multiple positions, conditional injection, template variables, and security filtering |
-| faviconManager       | Manage website favicon links injection into HTML files, supports string shorthand config                          |
-| loadingManager       | Global Loading state management with request interception and white-screen Loading                                |
+| Plugin               | Description                                                                                                          |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| buildProgress        | Real-time build progress bar in terminal, supports bar / spinner / minimal                                           |
+| bundleAnalyzer       | Build artifact size analysis with JSON/HTML reports, gzip calculation, threshold alerts, and build comparison        |
+| compressAssets       | Compress build artifacts with gzip / brotli / both, concurrent compression and statistics report                     |
+| copyFile             | Copy files or directories after build, supports incremental copying                                                  |
+| generateRouter       | Auto-generate router config from pages.json (uni-app)                                                                |
+| generateVersion      | Auto-generate version numbers, supports file output and global variable injection                                    |
+| versionUpdateChecker | Runtime version update checking with multiple prompt styles and custom callbacks                                     |
+| htmlInject           | HTML content injection with multiple positions, conditional injection, template variables, and security filtering    |
+| faviconManager       | Manage website favicon links injection and file copying, supports string shorthand config                            |
+| loadingManager       | Global Loading state management with request interception, debounce, transition animations, and white-screen Loading |
+
+---
 
 ### buildProgress
 
@@ -155,24 +128,10 @@ Display real-time build progress bar in terminal during Vite build, supporting t
 | moduleColor     | `(text: string) => string` | Module name color        |
 
 ```typescript
-// Default bar format
 buildProgress()
-
-// Spinner format
 buildProgress({ format: 'spinner' })
-
-// Minimal format
 buildProgress({ format: 'minimal' })
-
-// Custom appearance
-buildProgress({
-	width: 40,
-	completeChar: '■',
-	incompleteChar: '□',
-	clearOnComplete: false
-})
-
-// Custom color theme
+buildProgress({ width: 40, completeChar: '■', incompleteChar: '□', clearOnComplete: false })
 buildProgress({
 	theme: {
 		completeColor: t => `\x1b[32m${t}\x1b[39m`,
@@ -184,6 +143,73 @@ buildProgress({
 })
 ```
 
+---
+
+### bundleAnalyzer
+
+Automatically analyze build artifacts in the output directory after Vite build, generating size statistics, module rankings, file type distribution, and other key metrics, with JSON report and HTML visualization support.
+
+**Core Features:**
+
+- Scan build output directory, analyze chunks, modules, and asset files
+- Calculate original size and gzip compressed size
+- File type distribution statistics by extension
+- Top N largest modules ranking
+- Size threshold alerts (2x threshold marked as critical)
+- Compare with previous build results and generate diff report
+- HTML reports support treemap / sunburst / list visualization charts
+
+| Option             | Type                                    | Default             | Description                                               |
+| ------------------ | --------------------------------------- | ------------------- | --------------------------------------------------------- |
+| outputFormat       | `'json'` \| `'html'` \| `'both'`        | `'json'`            | Report output format                                      |
+| outputFile         | `string`                                | `'bundle-analysis'` | Report output filename (without extension)                |
+| openAnalyzer       | `boolean`                               | `false`             | Whether to auto-open browser after generating HTML report |
+| sizeThreshold      | `number`                                | `100`               | Size alert threshold (KB)                                 |
+| topModules         | `number`                                | `20`                | Top N largest modules ranking count                       |
+| gzipSize           | `boolean`                               | `true`              | Whether to calculate gzip size                            |
+| excludeNodeModules | `boolean`                               | `false`             | Whether to exclude node_modules modules                   |
+| excludePatterns    | `string[]`                              | `[]`                | File path patterns to exclude                             |
+| includeExtensions  | `string[]`                              | `[]`                | File extensions to include, empty means all               |
+| compareWith        | `string` \| `null`                      | `null`              | Path to previous analysis report for comparison           |
+| defaultChartType   | `'treemap'` \| `'sunburst'` \| `'list'` | `'treemap'`         | Default chart type in HTML report                         |
+
+```typescript
+bundleAnalyzer()
+bundleAnalyzer({ outputFormat: 'both', openAnalyzer: true })
+bundleAnalyzer({ sizeThreshold: 200, topModules: 30, gzipSize: true })
+bundleAnalyzer({ compareWith: 'dist/bundle-analysis.json', defaultChartType: 'sunburst' })
+bundleAnalyzer({ excludeNodeModules: true, includeExtensions: ['.js', '.css'] })
+```
+
+---
+
+### compressAssets
+
+Automatically compress files in the output directory after Vite build, supporting both gzip and brotli compression algorithms.
+
+| Option             | Type                               | Default                                                     | Description                                        |
+| ------------------ | ---------------------------------- | ----------------------------------------------------------- | -------------------------------------------------- |
+| algorithm          | `'gzip'` \| `'brotli'` \| `'both'` | `'gzip'`                                                    | Compression algorithm                              |
+| threshold          | `number`                           | `1024`                                                      | Minimum compression threshold (bytes)              |
+| deleteOriginalFile | `boolean`                          | `false`                                                     | Whether to delete original files after compression |
+| includeExtensions  | `string[]`                         | `['.js', '.css', '.html', '.svg', '.json', '.xml', '.txt']` | File extensions to compress                        |
+| excludeExtensions  | `string[]`                         | `[]`                                                        | File extensions to exclude                         |
+| excludePaths       | `string[]`                         | `[]`                                                        | Path prefixes to exclude                           |
+| compressionLevel   | `number`                           | `9`                                                         | Gzip compression level (1-9)                       |
+| brotliQuality      | `number`                           | `11`                                                        | Brotli compression quality (1-11)                  |
+| reportOutput       | `string` \| `false`                | `'compress-report.json'`                                    | Compression report output path, false to skip      |
+| parallelLimit      | `number`                           | `10`                                                        | Maximum concurrent file compression count          |
+
+```typescript
+compressAssets()
+compressAssets({ algorithm: 'brotli' })
+compressAssets({ algorithm: 'both', threshold: 2048, compressionLevel: 9, brotliQuality: 11 })
+compressAssets({ deleteOriginalFile: true, reportOutput: 'compress-report.json' })
+compressAssets({ includeExtensions: ['.js', '.css'], excludePaths: ['assets/images'], parallelLimit: 5 })
+```
+
+---
+
 ### copyFile
 
 Copy files or directories to specified locations after Vite build is completed, with `enforce: 'post'`.
@@ -197,21 +223,12 @@ Copy files or directories to specified locations after Vite build is completed,
 | incremental | `boolean` | `true`  | Whether to enable incremental copying      |
 
 ```typescript
-// Basic usage
-copyFile({
-	sourceDir: 'src/assets',
-	targetDir: 'dist/assets'
-})
-
-// Disable overwrite and incremental copy
-copyFile({
-	sourceDir: 'src/static',
-	targetDir: 'dist/static',
-	overwrite: false,
-	incremental: false
-})
+copyFile({ sourceDir: 'src/assets', targetDir: 'dist/assets' })
+copyFile({ sourceDir: 'src/static', targetDir: 'dist/static', overwrite: false, incremental: false })
 ```
 
+---
+
 ### generateRouter
 
 Automatically generate router configuration files based on uni-app project's `pages.json`.
@@ -229,38 +246,19 @@ Automatically generate router configuration files based on uni-app project's `pa
 | exportTypes          | `boolean`                                                 | `true`                   | Whether to export type definitions               |
 | preserveRouteChanges | `boolean`                                                 | `true`                   | Whether to preserve user modifications to routes |
 
-> Default `metaMapping` is `{ navigationBarTitleText: 'title', requireAuth: 'requireAuth' }`, automatically mapping page style fields to route meta. When `nameStrategy` is `'custom'`, `customNameGenerator` must be
-> provided.
+> Default `metaMapping` is `{ navigationBarTitleText: 'title', requireAuth: 'requireAuth' }`. When `nameStrategy` is `'custom'`, `customNameGenerator` must be provided.
 
 ```typescript
-// Basic usage
 generateRouter()
-
-// Custom pages.json path
 generateRouter({ pagesJsonPath: 'pages.json' })
-
-// Output JavaScript file
 generateRouter({ outputFormat: 'js', outputPath: 'src/router.config.js' })
-
-// PascalCase naming strategy
 generateRouter({ nameStrategy: 'pascalCase' })
-
-// Custom route name generator
-generateRouter({
-	nameStrategy: 'custom',
-	customNameGenerator: path => `route_${path.replace(/\//g, '_')}`
-})
-
-// Custom meta mapping
-generateRouter({
-	metaMapping: {
-		navigationBarTitleText: 'title',
-		requireAuth: 'requireAuth',
-		customField: 'custom'
-	}
-})
+generateRouter({ nameStrategy: 'custom', customNameGenerator: path => `route_${path.replace(/\//g, '_')}` })
+generateRouter({ metaMapping: { navigationBarTitleText: 'title', requireAuth: 'requireAuth', customField: 'custom' } })
 ```
 
+---
+
 ### generateVersion
 
 Automatically generate version numbers during the Vite build process.
@@ -300,37 +298,19 @@ Automatically generate version numbers during the Vite build process.
 > and timestamp.
 
 ```typescript
-// Timestamp format (default)
 generateVersion()
-
-// Date format
 generateVersion({ format: 'date' })
-
-// Semantic version format
 generateVersion({ format: 'semver', semverBase: '2.0.0', prefix: 'v' })
-
-// Custom format
-generateVersion({
-	format: 'custom',
-	customFormat: '{YYYY}.{MM}.{DD}-{hash}',
-	hashLength: 6
-})
-
-// Inject into code
+generateVersion({ format: 'custom', customFormat: '{YYYY}.{MM}.{DD}-{hash}', hashLength: 6 })
 generateVersion({ outputType: 'define', defineName: '__VERSION__' })
-
-// Both file output and code injection
-generateVersion({
-	outputType: 'both',
-	outputFile: 'build-info.json',
-	defineName: '__BUILD_VERSION__',
-	extra: { environment: 'production' }
-})
+generateVersion({ outputType: 'both', outputFile: 'build-info.json', defineName: '__BUILD_VERSION__', extra: { environment: 'production' } })
 ```
 
+---
+
 ### versionUpdateChecker
 
-Periodically check for version changes at runtime and prompt users to refresh when a new version is detected. Typically used in conjunction with the `generateVersion` plugin.
+Periodically check for version changes at runtime, prompting users to refresh when a new version is detected. Typically used with the `generateVersion` plugin.
 
 **How it works:**
 
@@ -338,650 +318,582 @@ Periodically check for version changes at runtime and prompt users to refresh wh
 2. `versionUpdateChecker` periodically requests the version file at runtime and compares it with the current version
 3. When a version mismatch is detected, a prompt is shown to guide the user to refresh
 
-| Option                  | Type                                 | Default                                                        | Description                                                  |
-| ----------------------- | ------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------ |
-| versionSource           | `'define'` \| `'file'` \| `'auto'`   | `'auto'`                                                       | Current version source                                       |
-| defineName              | `string`                             | `'__APP_VERSION__'`                                            | Global variable name in define mode                          |
-| checkUrl                | `string`                             | `'/version.json'`                                              | URL path for version check file                              |
-| checkInterval           | `number`                             | `300000`                                                       | Check interval in milliseconds (default 5 minutes)           |
-| checkOnVisibilityChange | `boolean`                            | `true`                                                         | Whether to check immediately on page visibility change       |
-| enableInDev             | `boolean`                            | `false`                                                        | Whether to enable in development mode                        |
-| promptStyle             | `'modal'` \| `'banner'` \| `'toast'` | `'modal'`                                                      | Update prompt UI style                                       |
-| promptMessage           | `string`                             | `'A new version is available. Refresh now to get the latest?'` | Prompt message text                                          |
-| refreshButtonText       | `string`                             | `'Refresh'`                                                    | Refresh button text                                          |
-| dismissButtonText       | `string`                             | `'Later'`                                                      | Dismiss button text                                          |
-| customPromptTemplate    | `string`                             | -                                                              | Custom HTML template for the prompt UI                       |
-| customStyle             | `string`                             | -                                                              | Custom CSS style string                                      |
-| onUpdateAvailable       | `string`                             | -                                                              | Callback when new version is found (function body string)    |
-| onRefresh               | `string`                             | -                                                              | Callback when user chooses to refresh (function body string) |
-| onDismiss               | `string`                             | -                                                              | Callback when user chooses to dismiss (function body string) |
+| Option                  | Type                                 | Default                                      | Description                                                  |
+| ----------------------- | ------------------------------------ | -------------------------------------------- | ------------------------------------------------------------ |
+| versionSource           | `'define'` \| `'file'` \| `'auto'`   | `'auto'`                                     | Current version source                                       |
+| defineName              | `string`                             | `'__APP_VERSION__'`                          | Global variable name in define mode                          |
+| checkUrl                | `string`                             | `'/version.json'`                            | URL path for version check file                              |
+| checkInterval           | `number`                             | `300000`                                     | Check interval (ms, default 5 minutes)                       |
+| checkOnVisibilityChange | `boolean`                            | `true`                                       | Whether to check immediately on page visibility change       |
+| enableInDev             | `boolean`                            | `false`                                      | Whether to enable in development mode                        |
+| promptStyle             | `'modal'` \| `'banner'` \| `'toast'` | `'modal'`                                    | Update prompt UI style                                       |
+| promptMessage           | `string`                             | `'A new version is available. Refresh now?'` | Prompt message text                                          |
+| refreshButtonText       | `string`                             | `'Refresh Now'`                              | Refresh button text                                          |
+| dismissButtonText       | `string`                             | `'Later'`                                    | Dismiss button text                                          |
+| customPromptTemplate    | `string`                             | -                                            | Custom HTML template for the prompt UI                       |
+| customStyle             | `string`                             | -                                            | Custom CSS style string                                      |
+| onUpdateAvailable       | `string`                             | -                                            | Callback when new version is found (function body string)    |
+| onRefresh               | `string`                             | -                                            | Callback when user chooses to refresh (function body string) |
+| onDismiss               | `string`                             | -                                            | Callback when user chooses to dismiss (function body string) |
 
 > `versionSource` explanation: `'define'` reads from global variable, `'file'` reads from version file, `'auto'` prefers define and falls back to file. Custom templates can use `{{message}}`, `{{currentVersion}}`,
-> `{{newVersion}}`, `{{refreshButton}}`, `{{dismissButton}}` placeholders. Callbacks are provided as function body strings with available variables: `currentVersion`, `newVersion`.
+> `{{newVersion}}`, `{{refreshButton}}`, `{{dismissButton}}` placeholders. Callbacks are provided as function body strings, available variables: `currentVersion`, `newVersion`.
 
 ```typescript
-// Basic usage (with generateVersion)
 generateVersion({ outputType: 'both' })
 versionUpdateChecker()
-
-// Read from version file only
 versionUpdateChecker({ versionSource: 'file' })
-
-// Custom check interval and prompt style
-versionUpdateChecker({
-	checkInterval: 60000,
-	promptStyle: 'banner'
-})
-
-// Toast-style prompt
+versionUpdateChecker({ checkInterval: 60000, promptStyle: 'banner' })
 versionUpdateChecker({ promptStyle: 'toast' })
-
-// Custom prompt text
-versionUpdateChecker({
-	promptMessage: 'System updated, refresh to experience new features',
-	refreshButtonText: 'Update',
-	dismissButtonText: 'Cancel'
-})
-
-// Custom callbacks
-versionUpdateChecker({
-	onUpdateAvailable: 'console.log("New version:", newVersion); return true;',
-	onRefresh: 'console.log("User chose to refresh");',
-	onDismiss: 'console.log("User chose to dismiss");'
-})
-
-// Enable in development (for debugging)
+versionUpdateChecker({ promptMessage: 'System updated, refresh to experience new features', refreshButtonText: 'Update', dismissButtonText: 'Cancel' })
+versionUpdateChecker({ onUpdateAvailable: 'console.log("New version:", newVersion); return true;', onRefresh: 'console.log("User chose refresh");', onDismiss: 'console.log("User chose dismiss");' })
 versionUpdateChecker({ enableInDev: true })
 ```
 
-### htmlInject
-
-Inject HTML content into target files during Vite build based on configured rules, supporting multiple injection positions, conditional injection, template variable replacement, and security filtering.
+---
 
-**Injection positions:**
+### htmlInject
 
-| Position           | Description                                |
-| ------------------ | ------------------------------------------ |
-| `head-start`       | Inject after the `<head>` tag              |
-| `head-end`         | Inject before the `</head>` tag            |
-| `body-start`       | Inject after the `<body>` tag              |
-| `body-end`         | Inject before the `</body>` tag            |
-| `before-selector`  | Inject before the selector-matched content |
-| `after-selector`   | Inject after the selector-matched content  |
-| `replace-selector` | Replace the selector-matched content       |
+Inject custom content into HTML files, supporting multiple positions, selector targeting, conditional injection, template variable replacement, and security filtering.
 
-| Option       | Type                     | Default        | Description                       |
-| ------------ | ------------------------ | -------------- | --------------------------------- |
-| targetFile   | `string`                 | `'index.html'` | Target HTML file path or filename |
-| rules        | `InjectRule[]`           | -              | Injection rules array (required)  |
-| security     | `SecurityConfig`         | -              | Security filtering configuration  |
-| templateVars | `Record<string, string>` | -              | Global template variables         |
-| logInjection | `boolean`                | `true`         | Whether to output injection logs  |
+| Option       | Type                     | Default        | Description                                 |
+| ------------ | ------------------------ | -------------- | ------------------------------------------- |
+| targetFile   | `string`                 | `'index.html'` | Target HTML file path or filename           |
+| rules        | `InjectRule[]`           | -              | Injection rules list (required)             |
+| security     | `SecurityConfig`         | -              | Security filtering config                   |
+| templateVars | `Record<string, string>` | `{}`           | Global template variable mapping            |
+| logInjection | `boolean`                | `true`         | Whether to output injection logs to console |
 
 **InjectRule**
 
-| Property             | Type                     | Default    | Description                                              |
-| -------------------- | ------------------------ | ---------- | -------------------------------------------------------- |
-| id                   | `string`                 | -          | Unique rule identifier for logging and debugging         |
-| content              | `string`                 | -          | HTML content to inject (required)                        |
-| position             | `InjectPosition`         | -          | Injection position (required)                            |
-| selector             | `string`                 | -          | Selector string (required for selector positions)        |
-| selectorMatch        | `'string'` \| `'regex'`  | `'string'` | Selector match mode                                      |
-| priority             | `number`                 | `100`      | Priority, lower values execute first                     |
-| condition            | `InjectCondition`        | -          | Injection condition                                      |
-| templateVars         | `Record<string, string>` | -          | Rule-level template variables (override global)          |
-| allowScriptInjection | `boolean`                | `false`    | Whether to allow injecting scripts and dangerous content |
+| Property             | Type                                                                                                                                  | Default    | Description                                               |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------------------------------------- |
+| id                   | `string`                                                                                                                              | -          | Unique rule identifier                                    |
+| content              | `string`                                                                                                                              | -          | Content to inject                                         |
+| position             | `'head-start'` \| `'head-end'` \| `'body-start'` \| `'body-end'` \| `'before-selector'` \| `'after-selector'` \| `'replace-selector'` | -          | Injection position                                        |
+| selector             | `string`                                                                                                                              | -          | Selector string (required for selector-related positions) |
+| selectorMatch        | `'string'` \| `'regex'`                                                                                                               | `'string'` | Selector match mode                                       |
+| priority             | `number`                                                                                                                              | `100`      | Rule priority, lower values execute first                 |
+| condition            | `InjectCondition`                                                                                                                     | -          | Injection condition                                       |
+| templateVars         | `Record<string, string>`                                                                                                              | -          | Rule-level template variables (override global)           |
+| allowScriptInjection | `boolean`                                                                                                                             | `false`    | Whether to allow injecting scripts and dangerous content  |
 
 **InjectCondition**
 
-| Property | Type                                        | Default | Description                            |
-| -------- | ------------------------------------------- | ------- | -------------------------------------- |
-| type     | `'env'` \| `'file-contains'` \| `'custom'`  | -       | Condition type (required)              |
-| value    | `string` \| `((...args: any[]) => boolean)` | -       | Condition value (required)             |
-| negate   | `boolean`                                   | `false` | Whether to negate the condition result |
+| Property | Type                                       | Default | Description                            |
+| -------- | ------------------------------------------ | ------- | -------------------------------------- |
+| type     | `'env'` \| `'file-contains'` \| `'custom'` | -       | Condition type                         |
+| value    | `string` \| `(...args: any[]) => boolean`  | -       | Condition value                        |
+| negate   | `boolean`                                  | `false` | Whether to negate the condition result |
 
 **SecurityConfig**
 
-| Property                 | Type       | Default | Description                           |
-| ------------------------ | ---------- | ------- | ------------------------------------- |
-| blockDangerousTags       | `boolean`  | `true`  | Whether to block dangerous tags       |
-| blockDangerousAttributes | `boolean`  | `true`  | Whether to block dangerous attributes |
-| allowedTags              | `string[]` | -       | Whitelist of allowed tags             |
-| blockedTags              | `string[]` | -       | Custom blocked tags list              |
-| blockedAttributes        | `string[]` | -       | Custom blocked attributes list        |
+| Property                 | Type       | Default | Description                                           |
+| ------------------------ | ---------- | ------- | ----------------------------------------------------- |
+| blockDangerousTags       | `boolean`  | `true`  | Whether to block dangerous tags (script, etc.)        |
+| blockDangerousAttributes | `boolean`  | `true`  | Whether to block dangerous attributes (onclick, etc.) |
+| allowedTags              | `string[]` | -       | Whitelist of allowed tags                             |
+| blockedTags              | `string[]` | -       | Custom blocked tags list                              |
+| blockedAttributes        | `string[]` | -       | Custom blocked attributes list                        |
 
 ```typescript
-// Basic usage
-htmlInject({
-	rules: [{ id: 'meta-desc', content: '<meta name="description" content="My App">', position: 'head-end' }]
-})
-
-// Conditional injection (production only)
 htmlInject({
 	rules: [
-		{
-			id: 'analytics',
-			content: '<script src="/analytics.js"></script>',
-			position: 'body-end',
-			condition: { type: 'env', value: 'PRODUCTION' },
-			allowScriptInjection: true
-		}
+		{ id: 'meta-description', content: '<meta name="description" content="My App">', position: 'head-end' },
+		{ id: 'analytics', content: '<script src="https://analytics.example.com/track.js"></script>', position: 'body-end', allowScriptInjection: true },
+		{ id: 'env-var', content: '<script>window.__ENV__ = "{{env}}"</script>', position: 'head-end', templateVars: { env: 'production' }, allowScriptInjection: true },
+		{ id: 'before-app', content: '<div>Before App</div>', position: 'before-selector', selector: '<div id="app">' },
+		{ id: 'prod-only', content: '<meta name="robots" content="noindex">', position: 'head-end', condition: { type: 'env', value: 'PRODUCTION' } }
 	]
 })
-
-// Template variable replacement
-htmlInject({
-	templateVars: { appName: 'My App', version: '1.0.0' },
-	rules: [{ id: 'meta', content: '<meta name="description" content="{{appName}}">', position: 'head-end' }]
-})
-
-// Selector injection
-htmlInject({
-	rules: [{ id: 'replace-title', content: '<title>New Title</title>', position: 'replace-selector', selector: '<title>.*</title>', selectorMatch: 'regex' }]
-})
-
-// Security configuration
-htmlInject({
-	security: { blockDangerousTags: true, allowedTags: ['iframe'] },
-	rules: [{ id: 'embed', content: '<iframe src="https://example.com"></iframe>', position: 'body-end' }]
-})
 ```
 
-### faviconManager
+---
 
-Inject website icon links into the head of HTML files during the Vite build process. Supports string shorthand config.
+### faviconManager
 
-| Option      | Type     | Default | Description                     |
-| ----------- | -------- | ------- | ------------------------------- |
-| base        | `string` | `'/'`   | Base path for icon files        |
-| url         | `string` | -       | Complete URL for the icon       |
-| link        | `string` | -       | Custom complete link tag HTML   |
-| icons       | `Icon[]` | -       | Custom icon array               |
-| copyOptions | `object` | -       | Icon file copying configuration |
+Manage website favicon links injection into HTML files, supports icon file copying, supports string shorthand config.
 
-> Priority: `link` > `url` > `base`. When `link` is provided, custom HTML is injected directly; when `url` is provided, the complete URL is used; otherwise `base + '/favicon.ico'` is used.
+| Option      | Type          | Default | Description                                            |
+| ----------- | ------------- | ------- | ------------------------------------------------------ |
+| base        | `string`      | `'/'`   | Base path for icon files                               |
+| url         | `string`      | -       | Complete icon URL (overrides base + favicon.ico)       |
+| link        | `string`      | -       | Custom complete link tag HTML (highest priority)       |
+| icons       | `Icon[]`      | -       | Custom icon array, supports multiple formats and sizes |
+| copyOptions | `CopyOptions` | -       | Icon file copying config                               |
 
-`Icon` interface definition:
+**Icon**
 
-| Property | Type     | Required | Description        |
-| -------- | -------- | -------- | ------------------ |
-| rel      | `string` | Yes      | Icon relation type |
-| href     | `string` | Yes      | Icon URL           |
-| sizes    | `string` | No       | Icon sizes         |
-| type     | `string` | No       | Icon MIME type     |
+| Property | Type     | Description        |
+| -------- | -------- | ------------------ |
+| rel      | `string` | Icon relation type |
+| href     | `string` | Icon URL           |
+| sizes    | `string` | Icon sizes         |
+| type     | `string` | Icon MIME type     |
 
-`copyOptions` interface definition:
+**CopyOptions**
 
-| Property  | Type      | Required | Default | Description                 |
-| --------- | --------- | -------- | ------- | --------------------------- |
-| sourceDir | `string`  | Yes      | -       | Icon source directory       |
-| targetDir | `string`  | Yes      | -       | Icon target directory       |
-| overwrite | `boolean` | No       | `true`  | Whether to overwrite files  |
-| recursive | `boolean` | No       | `true`  | Whether to copy recursively |
+| Property  | Type      | Default | Description                         |
+| --------- | --------- | ------- | ----------------------------------- |
+| sourceDir | `string`  | -       | Icon source directory (required)    |
+| targetDir | `string`  | -       | Icon target directory (required)    |
+| overwrite | `boolean` | `true`  | Whether to overwrite existing files |
+| recursive | `boolean` | `true`  | Whether to copy recursively         |
 
 ```typescript
-// Use default config
-faviconManager()
-
-// String shorthand (set base path)
 faviconManager('/assets')
-
-// Custom icon array
+faviconManager({ base: '/assets', url: '/assets/favicon.ico' })
 faviconManager({
 	base: '/assets',
 	icons: [
 		{ rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' },
-		{ rel: 'icon', href: '/favicon-32x32.png', sizes: '32x32', type: 'image/png' },
-		{ rel: 'apple-touch-icon', href: '/apple-touch-icon.png', sizes: '180x180' }
+		{ rel: 'icon', href: '/favicon-32x32.png', sizes: '32x32', type: 'image/png' }
 	]
 })
-
-// Custom complete link tag
-faviconManager({
-	link: '<link rel="icon" href="/favicon.svg" type="image/svg+xml" />'
-})
-
-// With file copying
 faviconManager({
 	base: '/assets',
-	copyOptions: {
-		sourceDir: 'src/assets/icons',
-		targetDir: 'dist/assets/icons'
-	}
+	copyOptions: { sourceDir: 'src/assets/icons', targetDir: 'dist/assets/icons' }
 })
 ```
 
+---
+
 ### loadingManager
 
-Inject global Loading state management with XHR/Fetch request interception, white-screen Loading, custom styles, and lifecycle callbacks.
-
-**Injection strategy:**
-
-- `defaultVisible: false` (default): All code (CSS + HTML + JS) is dynamically injected via JS before `</body>`
-- `defaultVisible: true`: CSS + HTML are injected as static tags before `</head>` (visible on white screen), JS is injected before `</body>`
-
-| Option         | Type                                            | Default                 | Description                                             |
-| -------------- | ----------------------------------------------- | ----------------------- | ------------------------------------------------------- |
-| position       | `'center'` \| `'top'` \| `'bottom'`             | `'center'`              | Loading display position                                |
-| defaultText    | `string`                                        | `'Loading...'`          | Default display text                                    |
-| spinnerType    | `'spinner'` \| `'dots'` \| `'pulse'` \| `'bar'` | `'spinner'`             | Spinner icon type                                       |
-| style          | `LoadingStyle`                                  | -                       | Custom style configuration                              |
-| transition     | `TransitionConfig`                              | `{ enabled: true }`     | Transition animation configuration                      |
-| minDisplayTime | `MinDisplayTime`                                | `{ enabled: true }`     | Minimum display time configuration                      |
-| delayShow      | `DelayShow`                                     | `{ enabled: true }`     | Delayed show configuration                              |
-| debounceHide   | `DebounceHide`                                  | `{ enabled: false }`    | Debounced hide configuration                            |
-| autoBind       | `'fetch'` \| `'xhr'` \| `'all'` \| `'none'`     | `'none'`                | Auto-bind request interception mode                     |
-| requestFilter  | `RequestFilter`                                 | -                       | Request filter configuration                            |
-| globalName     | `string`                                        | `'__LOADING_MANAGER__'` | Global variable name injected into browser              |
-| customTemplate | `string`                                        | -                       | Custom HTML template (must include `data-loading-text`) |
-| defaultVisible | `boolean`                                       | `false`                 | Whether initially visible (white-screen Loading)        |
-| autoHideOn     | `'DOMContentLoaded'` \| `'load'` \| `'manual'`  | `'DOMContentLoaded'`    | Auto-hide timing (requires `defaultVisible: true`)      |
-| callbacks      | `LoadingCallbacks`                              | -                       | Lifecycle callbacks                                     |
+Global Loading state management with request interception, debounce, transition animations, and white-screen Loading.
+
+| Option         | Type               | Default                 | Description                                                   |
+| -------------- | ------------------ | ----------------------- | ------------------------------------------------------------- |
+| position       | `LoadingPosition`  | `'center'`              | Loading display position                                      |
+| defaultText    | `string`           | `'Loading...'`          | Default display text                                          |
+| spinnerType    | `SpinnerType`      | `'spinner'`             | Spinner icon type                                             |
+| style          | `LoadingStyle`     | -                       | Custom style config                                           |
+| transition     | `TransitionConfig` | -                       | Transition animation config                                   |
+| minDisplayTime | `MinDisplayTime`   | -                       | Minimum display time config                                   |
+| delayShow      | `DelayShow`        | -                       | Delay show config                                             |
+| debounceHide   | `DebounceHide`     | -                       | Debounce hide config                                          |
+| autoBind       | `AutoBindMode`     | `'none'`                | Auto-bind request interception mode                           |
+| requestFilter  | `RequestFilter`    | -                       | Request filter config                                         |
+| globalName     | `string`           | `'__LOADING_MANAGER__'` | Injected global variable name                                 |
+| customTemplate | `string`           | -                       | Custom Loading HTML template                                  |
+| defaultVisible | `boolean`          | `false`                 | Loading DOM initial visibility (white-screen Loading)         |
+| autoHideOn     | `AutoHideOn`       | `'DOMContentLoaded'`    | Auto-hide timing (only effective when defaultVisible is true) |
+| callbacks      | `LoadingCallbacks` | -                       | Lifecycle callbacks                                           |
+
+**LoadingPosition**: `'center'` | `'top'` | `'bottom'`
+
+**SpinnerType**: `'spinner'` | `'dots'` | `'pulse'` | `'bar'`
+
+**AutoBindMode**: `'fetch'` | `'xhr'` | `'all'` | `'none'`
+
+**AutoHideOn**: `'DOMContentLoaded'` | `'load'` | `'manual'`
 
 **LoadingStyle**
 
 | Property           | Type      | Default                   | Description                              |
 | ------------------ | --------- | ------------------------- | ---------------------------------------- |
 | overlayColor       | `string`  | `'rgba(255,255,255,0.7)'` | Overlay background color                 |
-| spinnerColor       | `string`  | `'#4361ee'`               | Spinner icon color                       |
-| spinnerSize        | `string`  | `'40px'`                  | Spinner icon size                        |
+| spinnerColor       | `string`  | `'#4361ee'`               | Loading icon color                       |
+| spinnerSize        | `string`  | `'40px'`                  | Loading icon size                        |
 | textColor          | `string`  | `'#333'`                  | Text color                               |
 | textSize           | `string`  | `'14px'`                  | Text size                                |
 | customClass        | `string`  | -                         | Custom CSS class name                    |
-| customStyle        | `string`  | -                         | Custom inline style                      |
-| zIndex             | `number`  | `9999`                    | z-index value                            |
+| customStyle        | `string`  | -                         | Custom inline style string               |
+| zIndex             | `number`  | `9999`                    | Overlay z-index                          |
 | pointerEvents      | `boolean` | `true`                    | Whether to enable overlay pointer events |
 | backdropBlur       | `boolean` | `false`                   | Whether to enable backdrop blur          |
 | backdropBlurAmount | `number`  | `4`                       | Backdrop blur amount (px)                |
 
 **TransitionConfig**
 
-| Property | Type      | Default      | Description                  |
-| -------- | --------- | ------------ | ---------------------------- |
-| enabled  | `boolean` | `true`       | Whether to enable transition |
-| duration | `number`  | `200`        | Transition duration (ms)     |
-| easing   | `string`  | `'ease-out'` | Easing function              |
+| Property | Type      | Default      | Description                    |
+| -------- | --------- | ------------ | ------------------------------ |
+| enabled  | `boolean` | `true`       | Whether to enable transition   |
+| duration | `number`  | `200`        | Transition duration (ms)       |
+| easing   | `string`  | `'ease-out'` | CSS transition easing function |
 
 **MinDisplayTime**
 
-| Property | Type      | Default | Description                                               |
-| -------- | --------- | ------- | --------------------------------------------------------- |
-| enabled  | `boolean` | `true`  | Whether to enable                                         |
-| duration | `number`  | `300`   | Minimum display time (ms), prevents Loading from flashing |
+| Property | Type      | Default | Description                            |
+| -------- | --------- | ------- | -------------------------------------- |
+| enabled  | `boolean` | `true`  | Whether to enable minimum display time |
+| duration | `number`  | `300`   | Minimum display time (ms)              |
 
 **DelayShow**
 
-| Property | Type      | Default | Description                                                                    |
-| -------- | --------- | ------- | ------------------------------------------------------------------------------ |
-| enabled  | `boolean` | `true`  | Whether to enable                                                              |
-| duration | `number`  | `200`   | Delay duration (ms); if request completes within this time, Loading won't show |
+| Property | Type      | Default | Description                                                     |
+| -------- | --------- | ------- | --------------------------------------------------------------- |
+| enabled  | `boolean` | `true`  | Whether to enable delay show                                    |
+| duration | `number`  | `200`   | Delay time (ms), requests completed within this time won't show |
 
 **DebounceHide**
 
-| Property | Type      | Default | Description             |
-| -------- | --------- | ------- | ----------------------- |
-| enabled  | `boolean` | `false` | Whether to enable       |
-| duration | `number`  | `100`   | Debounce wait time (ms) |
+| Property | Type      | Default | Description                     |
+| -------- | --------- | ------- | ------------------------------- |
+| enabled  | `boolean` | `false` | Whether to enable debounce hide |
+| duration | `number`  | `100`   | Debounce wait time (ms)         |
 
 **RequestFilter**
 
-| Property           | Type       | Description                                                           |
-| ------------------ | ---------- | --------------------------------------------------------------------- |
-| excludeUrls        | `RegExp[]` | Array of URL regex patterns to exclude                                |
-| includeUrls        | `RegExp[]` | Array of URL regex patterns to include (higher priority than exclude) |
-| excludeMethods     | `string[]` | Array of HTTP methods to exclude                                      |
-| excludeUrlPrefixes | `string[]` | Array of URL prefixes to exclude (prefix matching, more efficient)    |
+| Property           | Type       | Description                    |
+| ------------------ | ---------- | ------------------------------ |
+| excludeUrls        | `RegExp[]` | URL regex patterns to exclude  |
+| includeUrls        | `RegExp[]` | URL regex patterns to include  |
+| excludeMethods     | `string[]` | HTTP methods to exclude        |
+| excludeUrlPrefixes | `string[]` | URL string prefixes to exclude |
 
 **LoadingCallbacks**
 
-Callbacks are provided as **function body strings** (injected into browser at build time, function references cannot be passed).
-
-| Property     | Type     | Description                                     |
-| ------------ | -------- | ----------------------------------------------- |
-| onBeforeShow | `string` | Before show callback, `return false` to prevent |
-| onShow       | `string` | After show callback                             |
-| onBeforeHide | `string` | Before hide callback, `return false` to prevent |
-| onHide       | `string` | After hide callback                             |
-| onDestroy    | `string` | On destroy callback                             |
-
-**LoadingManager API**
-
-Access via `window.__LOADING_MANAGER__`:
-
-| Method                     | Description                                                         |
-| -------------------------- | ------------------------------------------------------------------- |
-| `show(text?)`              | Show Loading, optionally pass text                                  |
-| `hide()`                   | Hide Loading (subject to min display time and debounce constraints) |
-| `forceHide()`              | Force hide, ignoring min display time and debounce                  |
-| `toggle(text?)`            | Toggle Loading show/hide state                                      |
-| `updateText(text)`         | Update text content                                                 |
-| `isVisible()`              | Get whether Loading is currently visible                            |
-| `isPointerEventsEnabled()` | Get whether pointer events are currently enabled                    |
-| `enablePointerEvents()`    | Enable overlay pointer events, intercept all clicks and scrolls     |
-| `disablePointerEvents()`   | Disable overlay pointer events, allow interaction passthrough       |
-| `togglePointerEvents()`    | Toggle overlay pointer events state                                 |
-| `getPendingCount()`        | Get the number of pending requests                                  |
-| `destroy()`                | Destroy instance, clean up DOM and restore original interceptors    |
+| Property     | Type     | Description                                              |
+| ------------ | -------- | -------------------------------------------------------- |
+| onBeforeShow | `string` | Before show callback (`return false` to prevent showing) |
+| onShow       | `string` | After show callback                                      |
+| onBeforeHide | `string` | Before hide callback (`return false` to prevent hiding)  |
+| onHide       | `string` | After hide callback                                      |
+| onDestroy    | `string` | On destroy callback                                      |
 
-```typescript
-// White-screen Loading: visible on page load, auto-hide on DOMContentLoaded
-loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' })
-
-// White-screen Loading: auto-hide after all resources loaded
-loadingManager({ defaultVisible: true, autoHideOn: 'load' })
-
-// Vue/React SPA: visible on white screen, manually hide after framework renders
-loadingManager({ defaultVisible: true, autoHideOn: 'manual' })
-// In app entry: window.__LOADING_MANAGER__.hide()
-
-// Auto-intercept all requests
-loadingManager({ autoBind: 'all' })
-
-// Custom styles + request filtering
-loadingManager({
-	style: { overlayColor: 'rgba(0,0,0,0.5)', spinnerColor: '#fff', backdropBlur: true },
-	autoBind: 'fetch',
-	requestFilter: { excludeUrls: [/\/api\/health/], excludeUrlPrefixes: ['http://localhost'] }
-})
-
-// Debounced hide (prevent rapid flashing)
-loadingManager({ debounceHide: { enabled: true, duration: 100 } })
+> Callbacks are provided as function body strings because they need to be injected into client-side code. `customTemplate` must contain an element with the `data-loading-text` attribute for text display.
 
-// Lifecycle callbacks
-loadingManager({
-	callbacks: {
-		onBeforeShow: 'if (shouldSkip) return false;',
-		onShow: 'console.log("loading shown")',
-		onBeforeHide: 'if (shouldKeepVisible) return false;',
-		onHide: 'console.log("loading hidden")'
-	}
-})
+**Runtime API:**
 
-// Manual control
-loadingManager()
-window.__LOADING_MANAGER__.show('Saving...')
+```typescript
+window.__LOADING_MANAGER__.show('Loading...')
 window.__LOADING_MANAGER__.hide()
-window.__LOADING_MANAGER__.toggle()
+window.__LOADING_MANAGER__.forceHide()
+window.__LOADING_MANAGER__.toggle('Loading...')
+window.__LOADING_MANAGER__.updateText('Processing...')
+window.__LOADING_MANAGER__.isVisible()
+window.__LOADING_MANAGER__.getPendingCount()
+window.__LOADING_MANAGER__.enablePointerEvents()
 window.__LOADING_MANAGER__.disablePointerEvents()
+window.__LOADING_MANAGER__.destroy()
 ```
 
-## Common Utilities
-
-Exported via `@meng-xi/vite-plugin/common`, reusable in custom plugins:
-
 ```typescript
-import { deepMerge, formatDate, parseTemplate, toCamelCase, toPascalCase, stripJsonComments, generateRandomHash, escapeHtmlAttr, Validator } from '@meng-xi/vite-plugin/common'
-import { readFileContent, writeFileContent, fileExists, copySourceToTarget } from '@meng-xi/vite-plugin/common/fs'
-import { injectBeforeTag, injectHtmlByPriority, injectBeforeTagWithFallback, injectHeadAndBody } from '@meng-xi/vite-plugin/common/html'
-import { makeCallback, containsScriptTag, validateIdentifierName } from '@meng-xi/vite-plugin/common/script'
-import { validateGlobalName, validateNoScriptInTemplate, validateCallbackFields, validateNonNegativeNumber, validateNestedDuration, validateEnumValue } from '@meng-xi/vite-plugin/common/validation'
+loadingManager()
+loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' })
+loadingManager({ position: 'top', defaultText: 'Please wait...', spinnerType: 'dots' })
+loadingManager({ autoBind: 'fetch', requestFilter: { excludeUrls: [/\/api\/health/] } })
+loadingManager({
+	style: { overlayColor: 'rgba(0,0,0,0.5)', spinnerColor: '#ff6b6b', backdropBlur: true, backdropBlurAmount: 6 }
+})
+loadingManager({ transition: { enabled: true, duration: 300, easing: 'cubic-bezier(0.4,0,0.2,1)' } })
+loadingManager({ debounceHide: { enabled: true, duration: 100 } })
+loadingManager({ callbacks: { onShow: 'console.log("shown")', onBeforeShow: 'return true' } })
+loadingManager({ customTemplate: '<div class="my-loader"><span data-loading-text></span></div>' })
+loadingManager({ defaultVisible: true, autoHideOn: 'manual' })
 ```
 
-| Function                        | Description                                                                   | Sub-path            |
-| ------------------------------- | ----------------------------------------------------------------------------- | ------------------- |
-| `deepMerge()`                   | Deep merge objects (undefined skipped, arrays overwritten)                    | `common/object`     |
-| `formatDate()`                  | Format date with `{YYYY}`, `{MM}`, `{DD}` etc. placeholders                   | `common/format`     |
-| `parseTemplate()`               | Parse template string, replace placeholders                                   | `common/format`     |
-| `toCamelCase()`                 | Convert to camelCase                                                          | `common/format`     |
-| `toPascalCase()`                | Convert to PascalCase                                                         | `common/format`     |
-| `stripJsonComments()`           | Remove comments from JSON string                                              | `common/format`     |
-| `generateRandomHash()`          | Generate random hash string (1-64 characters)                                 | `common/format`     |
-| `escapeHtmlAttr()`              | Escape special characters in HTML attribute values, prevent XSS injection     | `common/format`     |
-| `readFileContent()`             | Async read file content                                                       | `common/fs`         |
-| `writeFileContent()`            | Async write file content                                                      | `common/fs`         |
-| `fileExists()`                  | Async check if file exists                                                    | `common/fs`         |
-| `copySourceToTarget()`          | Copy files or directories with incremental copy and concurrency               | `common/fs`         |
-| `injectBeforeTag()`             | Inject code before a specified closing HTML tag                               | `common/html`       |
-| `injectHtmlByPriority()`        | Inject code into HTML by priority (`</head>` → `</body>` → `</html>`)         | `common/html`       |
-| `injectBeforeTagWithFallback()` | Inject with fallback strategy (`</body>` → `</html>` → append)                | `common/html`       |
-| `injectHeadAndBody()`           | Dual-zone HTML injection (head + body)                                        | `common/html`       |
-| `makeCallback()`                | Wrap callback function body as safe function expression (with try-catch)      | `common/script`     |
-| `containsScriptTag()`           | Detect if a string contains `<script>` tags                                   | `common/script`     |
-| `validateIdentifierName()`      | Validate string as a legal JavaScript identifier, prevent prototype pollution | `common/script`     |
-| `validateGlobalName()`          | Validate global variable name legality                                        | `common/validation` |
-| `validateNoScriptInTemplate()`  | Validate template string does not contain script tags (XSS protection)        | `common/validation` |
-| `validateCallbackFields()`      | Validate callback fields do not contain script tags                           | `common/validation` |
-| `validateNonNegativeNumber()`   | Validate number is non-negative                                               | `common/validation` |
-| `validateNestedDuration()`      | Validate nested config duration legality                                      | `common/validation` |
-| `validateEnumValue()`           | Validate string value is in allowed enum list                                 | `common/validation` |
+---
 
 ## Plugin Development Framework
 
-### BasePlugin Core Concepts
+This package not only provides built-in plugins but also exports a complete plugin development framework to help quickly build custom Vite plugins that follow conventions.
 
-`BasePlugin` is the base class for all plugins, providing complete lifecycle management and development conventions:
+### BasePlugin
 
-#### Lifecycle
+The base class for all built-in plugins, providing core capabilities such as configuration management, logging, error handling, and lifecycle management.
 
-| Phase             | Method             | Description                                                    |
-| ----------------- | ------------------ | -------------------------------------------------------------- |
-| Initialization    | `constructor`      | Merge options, initialize logger and validator                 |
-| Config Resolution | `onConfigResolved` | Called when Vite config is resolved                            |
-| Hook Registration | `addPluginHooks`   | Register Vite plugin hooks                                     |
-| Destroy           | `destroy`          | Automatically called during `closeBundle` for resource cleanup |
+```typescript
+import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin'
+import type { Plugin } from 'vite'
 
-#### Automatic Hook Composition
+interface MyPluginOptions {
+	prefix?: string
+}
 
-The `toPlugin()` method automatically composes the following hooks:
+class MyPlugin extends BasePlugin<MyPluginOptions> {
+	protected getPluginName() {
+		return 'my-plugin'
+	}
 
-- **configResolved** - Base class `onConfigResolved` runs first, then subclass hook
-- **closeBundle** - Subclass hook runs first, then base class `destroy`
+	protected getDefaultOptions() {
+		return { prefix: '[app]' }
+	}
 
-> Subclasses don't need to manually register `closeBundle` hooks for cleanup — just override the `destroy()` method.
+	protected validateOptions() {
+		this.validator.field('prefix').string().notEmpty().validate()
+	}
 
-#### Required Methods
+	protected addPluginHooks(plugin: Plugin) {
+		plugin.writeBundle = {
+			order: 'post',
+			handler: async () => {
+				await this.safeExecute(async () => {
+					this.logger.info('Plugin executing...')
+				}, 'Execute custom logic')
+			}
+		}
+	}
+}
 
-| Method                   | Description           |
-| ------------------------ | --------------------- |
-| `getPluginName()`        | Return plugin name    |
-| `addPluginHooks(plugin)` | Add Vite plugin hooks |
+export const myPlugin = createPluginFactory(MyPlugin)
+```
 
-#### Optional Methods
+**BasePlugin Core Methods:**
+
+| Method              | Description                                                    |
+| ------------------- | -------------------------------------------------------------- |
+| `getDefaultOptions` | Returns plugin default config, can be overridden by subclasses |
+| `validateOptions`   | Validates user config, can be overridden by subclasses         |
+| `getPluginName`     | Returns plugin name (abstract method, must be implemented)     |
+| `getEnforce`        | Returns plugin execution timing (pre / post / undefined)       |
+| `addPluginHooks`    | Registers Vite hooks (abstract method, must be implemented)    |
+| `onConfigResolved`  | Config resolution complete callback                            |
+| `destroy`           | Plugin destroy callback                                        |
+| `safeExecute`       | Safely execute async function with automatic error handling    |
+| `safeExecuteSync`   | Safely execute sync function with automatic error handling     |
+| `handleError`       | Handle errors based on errorStrategy                           |
+| `toPlugin`          | Convert to Vite plugin object                                  |
+
+**BasePluginOptions Base Config:**
+
+| Option        | Type                               | Default   | Description             |
+| ------------- | ---------------------------------- | --------- | ----------------------- |
+| enabled       | `boolean`                          | `true`    | Whether to enable       |
+| verbose       | `boolean`                          | `true`    | Whether to log          |
+| errorStrategy | `'throw'` \| `'log'` \| `'ignore'` | `'throw'` | Error handling strategy |
 
-| Method                     | Default Behavior  | Description                                 |
-| -------------------------- | ----------------- | ------------------------------------------- |
-| `getDefaultOptions()`      | Returns `{}`      | Provide plugin default options              |
-| `validateOptions()`        | No validation     | Validate configuration parameters           |
-| `getEnforce()`             | `undefined`       | Plugin execution order (`'pre'` / `'post'`) |
-| `onConfigResolved(config)` | Store config      | Config resolved callback                    |
-| `destroy()`                | Unregister logger | Cleanup logic when plugin is destroyed      |
+### createPluginFactory
 
-#### Built-in Properties
+Creates a plugin factory function that converts a BasePlugin subclass into a directly usable Vite plugin function.
 
-| Property     | Type                     | Description                   |
-| ------------ | ------------------------ | ----------------------------- |
-| `options`    | `Required<T>`            | Merged complete configuration |
-| `logger`     | `PluginLogger`           | Plugin logger                 |
-| `validator`  | `Validator<T>`           | Configuration validator       |
-| `viteConfig` | `ResolvedConfig \| null` | Resolved Vite configuration   |
+```typescript
+import { createPluginFactory } from '@meng-xi/vite-plugin'
 
-#### Error Handling Strategy
+const myPlugin = createPluginFactory(MyPlugin)
 
-Control error behavior via the `errorStrategy` configuration option:
+// Supports options normalizer (e.g. string shorthand config)
+const myPluginWithNormalizer = createPluginFactory(MyPlugin, opt => (typeof opt === 'string' ? { prefix: opt } : opt))
+```
 
-- `'throw'` (default) - Log error and throw exception, halting the build
-- `'log'` - Log error but don't throw, continue execution
-- `'ignore'` - Log error but don't throw, continue execution
+### Logger
 
-Wrap error-prone operations with `safeExecute` / `safeExecuteSync`:
+Global singleton log manager, providing independent log proxies for each plugin.
 
 ```typescript
-// Async safe execution
-const result = await this.safeExecute(async () => {
-	return await someAsyncOperation()
-}, 'Execute async operation')
-
-// Sync safe execution
-const value = this.safeExecuteSync(() => {
-	return someSyncOperation()
-}, 'Execute sync operation')
+import { Logger } from '@meng-xi/vite-plugin/logger'
+
+const logger = Logger.create({ name: 'my-plugin', enabled: true })
+logger.info('Info log')
+logger.success('Success log')
+logger.warn('Warning log')
+logger.error('Error log')
 ```
 
-### createPluginFactory
+### Validator
 
-Create plugin factory functions with optional normalizer support:
+Chain-style configuration validator for validating plugin configuration parameters.
 
 ```typescript
-// Basic usage
-const myPlugin = createPluginFactory(MyPlugin)
+import { Validator } from '@meng-xi/vite-plugin/common/validation'
 
-// With normalizer (supports shorthand string config)
-const myPlugin = createPluginFactory(MyPlugin, opt => (typeof opt === 'string' ? { path: opt } : opt))
-
-// Usage with shorthand
-myPlugin('./custom-path')
+const validator = new Validator(myOptions)
+validator.field('port').number().minValue(1).maxValue(65535).field('host').string().notEmpty().field('mode').enum(['development', 'production']).validate()
 ```
 
-### Validator
+---
 
-Fluent configuration validator with chainable API:
+## Common Utility Modules
 
-```typescript
-import { Validator } from '@meng-xi/vite-plugin/common'
+Built-in general-purpose utility function library, organized by functional modules, supporting on-demand sub-path imports.
 
-const validator = new Validator(options)
-validator
-	.field('sourceDir')
-	.required()
-	.string()
-	.field('targetDir')
-	.required()
-	.string()
-	.field('overwrite')
-	.boolean()
-	.default(true)
-	.field('port')
-	.number()
-	.field('list')
-	.array()
-	.field('config')
-	.object()
-	.field('name')
-	.custom(val => val.length > 0, 'name cannot be empty')
-	.validate()
+### Import Methods
+
+```typescript
+// Import all utilities
+import { formatFileSize, scanDirectory } from '@meng-xi/vite-plugin/common'
+
+// Import by module
+import { formatFileSize } from '@meng-xi/vite-plugin/common/format'
+import { scanDirectory, writeJsonReport } from '@meng-xi/vite-plugin/common/fs'
+import { calculateGzipSize } from '@meng-xi/vite-plugin/common/compress'
+import { isNodeModule } from '@meng-xi/vite-plugin/common/path'
 ```
 
-| Method       | Description                                                       |
-| ------------ | ----------------------------------------------------------------- |
-| `field()`    | Specify the field to validate                                     |
-| `required()` | Mark field as required                                            |
-| `string()`   | Validate field value is a string type                             |
-| `boolean()`  | Validate field value is a boolean type                            |
-| `number()`   | Validate field value is a number type                             |
-| `array()`    | Validate field value is an array type                             |
-| `object()`   | Validate field value is an object type                            |
-| `enum()`     | Validate field value is in allowed enum list                      |
-| `minValue()` | Validate number field value is not less than specified minimum    |
-| `maxValue()` | Validate number field value is not greater than specified maximum |
-| `default()`  | Set default value for field (only when value is undefined/null)   |
-| `custom()`   | Validate field value with a custom function                       |
-| `validate()` | Execute validation, throws error on failure                       |
+### Module List
 
-### Logger
+| Sub-path                                 | Description             |
+| ---------------------------------------- | ----------------------- |
+| `@meng-xi/vite-plugin/common/compress`   | Compression utilities   |
+| `@meng-xi/vite-plugin/common/format`     | Formatting utilities    |
+| `@meng-xi/vite-plugin/common/fs`         | File system utilities   |
+| `@meng-xi/vite-plugin/common/html`       | HTML injection utils    |
+| `@meng-xi/vite-plugin/common/object`     | Object operation utils  |
+| `@meng-xi/vite-plugin/common/path`       | Path handling utils     |
+| `@meng-xi/vite-plugin/common/script`     | Script generation utils |
+| `@meng-xi/vite-plugin/common/validation` | Validation utilities    |
+
+### compress — Compression
 
-Global singleton log manager providing independent log control for each plugin:
+| Function            | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `calculateGzipSize` | Calculate gzip compressed size of given data (bytes) |
 
 ```typescript
-import { Logger } from '@meng-xi/vite-plugin/logger'
+import { calculateGzipSize } from '@meng-xi/vite-plugin/common/compress'
 
-// Create logger (usually called automatically by BasePlugin)
-Logger.create({ name: 'my-plugin', enabled: true })
+const size = await calculateGzipSize(Buffer.from('hello world'))
+```
+
+### format — Formatting
+
+| Function              | Description                                        |
+| --------------------- | -------------------------------------------------- |
+| `formatFileSize`      | Format bytes to human-readable file size string    |
+| `getExtension`        | Get file extension (lowercase)                     |
+| `formatDate`          | Format date                                        |
+| `parseTemplate`       | Parse template string, replace placeholders        |
+| `toCamelCase`         | Convert string to camelCase                        |
+| `toPascalCase`        | Convert string to PascalCase                       |
+| `padNumber`           | Pad number with leading zeros                      |
+| `generateRandomHash`  | Generate random hash string                        |
+| `getDateFormatParams` | Get date formatting parameters                     |
+| `stripJsonComments`   | Remove comments from JSON string                   |
+| `escapeHtmlAttr`      | Escape special characters in HTML attribute values |
 
-// Unregister plugin log config (automatically called on plugin destroy)
-Logger.unregister('my-plugin')
+```typescript
+import { formatFileSize, formatDate, toCamelCase } from '@meng-xi/vite-plugin/common/format'
 
-// Destroy singleton (for test scenarios)
-Logger.destroy()
+formatFileSize(2461726) // '2.35MB'
+formatDate(new Date(), '{YYYY}-{MM}-{DD}') // '2026-05-31'
+toCamelCase('pages/user/profile') // 'pagesUserProfile'
 ```
 
-Log output format:
+### fs — File System
 
-```
-ℹ️ [@meng-xi/vite-plugin:my-plugin] Info message
-✅ [@meng-xi/vite-plugin:my-plugin] Success message
-⚠️ [@meng-xi/vite-plugin:my-plugin] Warning message
-❌ [@meng-xi/vite-plugin:my-plugin] Error message
+| Function             | Description                                   |
+| -------------------- | --------------------------------------------- |
+| `scanDirectory`      | Recursively scan directory, collect file info |
+| `writeJsonReport`    | Write data to JSON file                       |
+| `writeFileContent`   | Write file content                            |
+| `readFileContent`    | Read file content                             |
+| `fileExists`         | Check if file exists                          |
+| `checkSourceExists`  | Check if source file exists                   |
+| `ensureTargetDir`    | Create target directory                       |
+| `copySourceToTarget` | Execute file copy operation                   |
+| `runWithConcurrency` | Batch execution with concurrency limit        |
+
+```typescript
+import { scanDirectory, writeJsonReport } from '@meng-xi/vite-plugin/common/fs'
+
+const files = await scanDirectory('dist', {
+	includeExtensions: ['.js', '.css'],
+	excludePatterns: ['node_modules'],
+	filter: (filePath, ext, size) => size > 1024
+})
+
+await writeJsonReport('dist/report.json', { timestamp: Date.now(), files })
 ```
 
-### Custom Plugin Example
+### html — HTML Injection
+
+| Function                      | Description                              |
+| ----------------------------- | ---------------------------------------- |
+| `injectBeforeTag`             | Inject code before specified closing tag |
+| `injectHtmlByPriority`        | Inject code into HTML by priority        |
+| `injectBeforeTagWithFallback` | Inject code with fallback strategy       |
+| `injectHeadAndBody`           | Dual-zone HTML injection (head + body)   |
 
 ```typescript
-import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin'
-import type { BasePluginOptions, PluginWithInstance } from '@meng-xi/vite-plugin/factory'
-import type { Plugin } from 'vite'
+import { injectBeforeTag, injectHeadAndBody } from '@meng-xi/vite-plugin/common/html'
 
-interface MyPluginOptions extends BasePluginOptions {
-	path: string
-}
+const result = injectBeforeTag(html, '</head>', '<style>body{margin:0}</style>')
+const dual = injectHeadAndBody(html, '<style>...</style>', '<script>...</script>')
+```
 
-class MyPlugin extends BasePlugin<MyPluginOptions> {
-	protected getDefaultOptions() {
-		return { path: './default' }
-	}
+### object — Object Operations
 
-	protected validateOptions(): void {
-		this.validator.field('path').required().string().validate()
-	}
+| Function    | Description        |
+| ----------- | ------------------ |
+| `deepMerge` | Deep merge objects |
 
-	protected getPluginName(): string {
-		return 'my-plugin'
-	}
+```typescript
+import { deepMerge } from '@meng-xi/vite-plugin/common/object'
 
-	protected addPluginHooks(plugin: Plugin): void {
-		plugin.buildStart = () => {
-			this.logger.info(`Plugin started with path: ${this.options.path}`)
-		}
-	}
+deepMerge({ a: { b: 1 } }, { a: { c: 2 } }) // { a: { b: 1, c: 2 } }
+```
 
-	protected destroy(): void {
-		super.destroy()
-		// Custom cleanup logic, e.g. close connections, stop watchers
-	}
-}
+### path — Path Handling
 
-// Basic usage
-export const myPlugin = createPluginFactory(MyPlugin)
+| Function       | Description                             |
+| -------------- | --------------------------------------- |
+| `isNodeModule` | Check if module ID is from node_modules |
 
-// With normalizer (supports shorthand string config)
-export const myPluginWithNormalizer = createPluginFactory(MyPlugin, opt => (typeof opt === 'string' ? { path: opt } : opt))
-// Usage with shorthand: myPluginWithNormalizer('./custom-path')
+```typescript
+import { isNodeModule } from '@meng-xi/vite-plugin/common/path'
+
+isNodeModule('node_modules/lodash/index.js') // true
+isNodeModule('src/utils/helper.ts') // false
 ```
 
-## Sub-path Exports
+### script — Script Generation
 
-Support importing modules on demand to reduce bundle size:
+| Function                 | Description                                                    |
+| ------------------------ | -------------------------------------------------------------- |
+| `makeCallback`           | Wrap callback function body string as safe function expression |
+| `containsScriptTag`      | Detect if string contains `<script>` tag                       |
+| `validateIdentifierName` | Validate if string is a valid JS identifier                    |
 
 ```typescript
-// Full import
-import { buildProgress, copyFile, htmlInject, loadingManager, BasePlugin, Logger } from '@meng-xi/vite-plugin'
+import { makeCallback, validateIdentifierName } from '@meng-xi/vite-plugin/common/script'
 
-// Module-level import
-import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin/factory'
-import { Logger } from '@meng-xi/vite-plugin/logger'
-import { buildProgress, copyFile, generateRouter, htmlInject, loadingManager } from '@meng-xi/vite-plugin/plugins'
-import { Validator, readFileContent, writeFileContent } from '@meng-xi/vite-plugin/common'
-
-// Type imports (on-demand type definitions from sub-paths)
-import type { PluginWithInstance, PluginFactory, BasePluginOptions } from '@meng-xi/vite-plugin/factory'
-import type { BuildProgressOptions, GenerateVersionOptions, VersionUpdateCheckerOptions, HtmlInjectOptions, InjectRule, FaviconManagerOptions, LoadingManagerOptions, Icon } from '@meng-xi/vite-plugin/plugins'
-import type { DateFormatOptions } from '@meng-xi/vite-plugin/common/format'
-import type { HtmlInjectResult, DualInjectResult } from '@meng-xi/vite-plugin/common/html'
-import type { CopyOptions, CopyResult } from '@meng-xi/vite-plugin/common/fs'
+makeCallback('console.log("done")')
+// 'function() { try { console.log("done") } catch(e) { console.error("[callback] error:", e); } }'
+
+validateIdentifierName('__APP_VERSION__') // passes
 ```
 
-## Changelog
+### validation — Validation
 
-View [GitHub Releases](https://github.com/MengXi-Studio/vite-plugin/releases)
+| Function                     | Description                         |
+| ---------------------------- | ----------------------------------- |
+| `Validator`                  | Chain-style configuration validator |
+| `validateGlobalName`         | Validate global variable name       |
+| `validateNoScriptInTemplate` | Validate no script tag in template  |
+| `validateCallbackFields`     | Validate callback function fields   |
+| `validateNonNegativeNumber`  | Validate non-negative number        |
+| `validateNestedDuration`     | Validate nested duration config     |
+| `validateEnumValue`          | Validate enum value                 |
 
-## Contributing
+```typescript
+import { Validator } from '@meng-xi/vite-plugin/common/validation'
 
-Contributions are welcome! Please follow these steps:
+const validator = new Validator(options)
+validator.field('port').number().minValue(1).maxValue(65535).validate()
+```
+
+---
+
+## Sub-path Exports
 
-1. Fork this project
-2. Create a feature branch: `git checkout -b feature/your-feature`
-3. Commit changes: `git commit -m "feat: your feature description"`
-4. Push branch: `git push origin feature/your-feature`
-5. Create a Pull Request
+| Sub-path                                              | Description                          |
+| ----------------------------------------------------- | ------------------------------------ |
+| `@meng-xi/vite-plugin`                                | Main entry (all plugins + framework) |
+| `@meng-xi/vite-plugin/factory`                        | Plugin development framework         |
+| `@meng-xi/vite-plugin/logger`                         | Log manager                          |
+| `@meng-xi/vite-plugin/plugins`                        | All plugins                          |
+| `@meng-xi/vite-plugin/common`                         | All utility functions                |
+| `@meng-xi/vite-plugin/common/compress`                | Compression utilities                |
+| `@meng-xi/vite-plugin/common/format`                  | Formatting utilities                 |
+| `@meng-xi/vite-plugin/common/fs`                      | File system utilities                |
+| `@meng-xi/vite-plugin/common/html`                    | HTML injection utilities             |
+| `@meng-xi/vite-plugin/common/object`                  | Object operation utilities           |
+| `@meng-xi/vite-plugin/common/path`                    | Path handling utilities              |
+| `@meng-xi/vite-plugin/common/script`                  | Script generation utilities          |
+| `@meng-xi/vite-plugin/common/validation`              | Validation utilities                 |
+| `@meng-xi/vite-plugin/plugins/build-progress`         | buildProgress plugin                 |
+| `@meng-xi/vite-plugin/plugins/bundle-analyzer`        | bundleAnalyzer plugin                |
+| `@meng-xi/vite-plugin/plugins/compress-assets`        | compressAssets plugin                |
+| `@meng-xi/vite-plugin/plugins/copy-file`              | copyFile plugin                      |
+| `@meng-xi/vite-plugin/plugins/favicon-manager`        | faviconManager plugin                |
+| `@meng-xi/vite-plugin/plugins/generate-router`        | generateRouter plugin                |
+| `@meng-xi/vite-plugin/plugins/generate-version`       | generateVersion plugin               |
+| `@meng-xi/vite-plugin/plugins/html-inject`            | htmlInject plugin                    |
+| `@meng-xi/vite-plugin/plugins/loading-manager`        | loadingManager plugin                |
+| `@meng-xi/vite-plugin/plugins/version-update-checker` | versionUpdateChecker plugin          |
+
+---
 
 ## License