@bytechain.cn/colamd-themes 0.3.1 → 0.5.0

package/RELEASENOTE.md

@@ -1,365 +1,541 @@
-# Release Notes
-
-## Version 0.3.1 (2026-06-01) — Security & Stability Patch 🔒
-
-> **Important**: This release contains critical security fixes and important stability improvements.
-> **All users are strongly recommended to upgrade.**
-
-### 🚨 Critical Security Fixes
-
-**SSRF Vulnerability Patch (CVE-Level)**
-- **Issue**: URL extractor was vulnerable to Server-Side Request Forgery attacks
-  - Attackers could force the server to access internal network resources
-  - Could expose sensitive internal services or cause denial-of-service
-- **Fix**: Implemented comprehensive URL validation in [`url-extractor.ts`](src/extractors/url-extractor.ts):
-  - ✅ Protocol whitelist: Only `http:` and `https:` allowed
-  - ✅ Private network blocking: localhost, 10.x, 172.16-31.x, 192.168.x, 169.254.x
-  - ✅ Clear error messages for blocked attempts
-- **Impact**: Prevents unauthorized internal network access; protects against SSRF attacks
-
-**Input Validation Hardening**
-- **Issue**: No validation on custom CSS theme files before processing
-  - Large files could cause memory exhaustion (OOM)
-  - Invalid file formats could crash the process
-- **Fix**: Added multi-layer validation in [`theme-store.ts`](src/theme-store.ts):
-  - ✅ File extension check (must be `.css`)
-  - ✅ Size limit enforcement (1MB maximum)
-  - ✅ Content validity verification (minimum 10 characters)
-  - ✅ Sanitized filename extraction (removes special chars, limits length)
-- **Impact**: Prevents OOM attacks; ensures graceful error handling
-
-### 🐛 Major Bug Fixes
-
-**PDF Export Theme Not Applied**
-- **Symptom**: Custom themes were ignored when exporting to PDF; documents rendered with default styling only
-- **Root Cause**: Puppeteer's `emulateMediaType("screen")` forced browser into screen mode, causing CSS `@media print { ... }` rules to be completely ignored
-- **Fix**: Removed screen media type emulation in [`renderer.ts`](src/renderer.ts); allows default print mode where all `@media print` styles apply correctly
-- **Result**: PDF exports now render with full theme fidelity — colors, fonts, backgrounds, spacing, and all visual styling correctly applied
-
-**Puppeteer Resource Leak**
-- **Symptom**: Zombie Chromium processes left running after export operations completed
-- **Cause**: Page objects not explicitly closed before browser termination
-- **Fix**: Explicit page cleanup in [`renderer.ts`](src/renderer.ts#L150-L155) close() method
-- **Result**: Clean process shutdown; no resource leaks
-
-**CLI Version Display Incorrect**
-- **Symptom**: `colamd-themes --version` always showed "0.2.0" regardless of actual version
-- **Cause**: Hardcoded version string in CLI initialization
-- **Fix**: Dynamic version reading from [`package.json`](package.json) via [`getPackageVersion()`](src/cli.ts)
-- **Result**: Accurate version display matching published package version
-
-### ⚡ Performance Improvements
-
-**Async I/O Migration**
-- **Before**: Synchronous file operations (`readFileSync`, `writeFileSync`) blocked event loop during theme configuration
-- **After**: All theme store operations now use async API (`fs/promises`)
-- **Benefit**:
-  - Non-blocking configuration reads/writes
-  - Improved responsiveness during batch exports
-  - Better scalability for concurrent operations
-- **Files Updated**: [`theme-store.ts`](src/theme-store.ts)
-
-**Template Cache Management**
-- **Before**: Single global template variable; recompiled on every call after first use; no size limits
-- **After**: Sophisticated cache system with three-layer invalidation:
-  1. **LRU Eviction**: Maximum 10 cached templates (evicts oldest when full)
-  2. **TTL Expiration**: Automatic expiry after 30 minutes of inactivity
-  3. **mtime Detection**: Auto-invalidates when source template file is modified on disk
-- **Benefit**:
-  - ~90% reduction in template compilations for repeated operations
-  - Stable memory usage in long-running processes
-  - Fresh templates automatically loaded after updates
-- **Files Updated**: [`generator.ts`](src/generator.ts)
-
-### 🛠️ Code Quality Enhancements
-
-**Unified Error Handling System**
-- **New Module**: [`cli-utils.ts`](src/utils/cli-utils.ts)
-- **Features**:
-  - `CLIError` class: Structured errors with code, message, and cause chain
-  - `ErrorCode` enum: Standardized categories (FILE_NOT_FOUND, THEME_ERROR, RENDER_ERROR, INVALID_INPUT, UNKNOWN)
-  - Consistent error propagation across all commands
-- **Impact**:
-  - Better debugging experience with detailed error context
-  - Consistent user-facing error messages
-  - Easier error tracking and logging
-  - Process exits with meaningful exit codes
-
-**Code Deduplication**
-- **Extracted Utilities**:
-  - `resolveInputPath(input)`: Validates existence, converts relative→absolute paths
-  - `resolveOutputPath(input, output?, ext?)`: Smart output path derivation
-  - `getDocumentTitle(filePath)`: Extracts clean document title from path
-- **Impact**:
-  - Eliminated duplicate path resolution logic across 4+ command handlers
-  - Single source of truth reduces maintenance burden
-  - Consistent behavior across all export commands
-
-### 📊 Metrics & Benchmarks
-
-| Metric | v0.3.0 | v0.3.1 | Improvement |
-|--------|--------|--------|-------------|
-| **Security Vulnerabilities** | 2 Critical | 0 Known | ✅ Resolved |
-| **Memory Usage (100 files)** | Unbounded | Stable | ✅ Predictable |
-| **Template Compilations** | ~100 per batch | ~10 max | ⚡ 90% fewer |
-| **Event Loop Blocking** | Frequent sync I/O | Minimal async ops | ⚡ Responsive |
-| **Error Consistency** | Mixed patterns | Unified codes | ✅ Maintainable |
-| **Zombie Processes** | Possible leak | Clean shutdown | ✅ Reliable |
-
-### 🔧 Migration Guide
-
-**For Most Users**: No action required! This is a drop-in replacement.
-
-**Breaking Changes**: None — fully backward compatible.
-
-**API Changes** (for programmatic usage):
-```typescript
-// Before (v0.3.0): Sync API
-import { resolveTheme } from '@bytechain.cn/colamd-themes';
-const theme = resolveTheme('elegant'); // Sync
-
-// After (v0.3.1): Async API
-import { resolveTheme } from '@bytechain.cn/colamd-themes';
-const theme = await resolveTheme('elegant'); // Async
-```
-
-**New Error Handling** (recommended):
-```typescript
-import { CLIError, ErrorCode } from '@bytechain.cn/colamd-themes';
-
-try {
-  await exportHTML(document, { theme: 'custom' });
-} catch (error) {
-  if (error instanceof CLIError) {
-    console.error(`Error ${error.code}: ${error.message}`);
-    // Handle specific error types
-    switch (error.code) {
-      case ErrorCode.FILE_NOT_FOUND: /* ... */ break;
-      case ErrorCode.THEME_ERROR: /* ... */ break;
-      case ErrorCode.RENDER_ERROR: /* ... */ break;
-      default: /* ... */ break;
-    }
-  }
-}
-```
-
-### ✅ Testing Recommendations
-
-After upgrading, verify these critical scenarios:
-
-1. **Security Test**:
-   ```bash
-   # Should be blocked (private network)
-   cthemes from-url "http://localhost:3000" --name test
-   
-   # Should be blocked (invalid protocol)
-   cthemes from-url "ftp://example.com/file.css" --name test
-   
-   # Should work (public HTTPS)
-   cthemes from-url "https://example.com" --name my-theme
-   ```
-
-2. **PDF Export Test**:
-   ```bash
-   # Verify themes now apply correctly
-   cthemes export-pdf doc.md -t elegant -o test.pdf
-   open test.pdf  # Check styling is applied
-   ```
-
-3. **Version Display Test**:
-   ```bash
-   # Should show 0.3.1
-   cthemes --version
-   ```
-
-4. **Large File Protection Test**:
-   ```bash
-   # Create a large CSS file (>1MB)
-   dd if=/dev/urandom of=large-theme.css bs=1024 count=1100
-   
-   # Should fail gracefully
-   cthemes set-theme big --css large-theme.css
-   ```
-
-### 📝 Full Changelog
-
-For complete details on all changes, see [CHANGELOG.md](./CHANGELOG.md).
-
----
-
-## Version 0.3.0 (2026-06-01)
-
-### 📦 Package Name Change
-
-**Migrated to Scoped Package**
-- Package name changed from `colamd-themes` to **`@bytechain.cn/colamd-themes`**
-- Belongs to the `@bytechain.cn` organization ecosystem
-- Consistent with dependency `@bytechain.cn/colamd`
-
-**New Short CLI Command**
-- Added `cthemes` as a short alias for `colamd-themes`
-- Both commands are fully equivalent and interchangeable
-- Recommended for frequent use: shorter to type, same functionality
-
-### 🎨 New Themes
-
-**Trae Blue Theme**
-- Modern blue color scheme optimized for technical documentation
-- Enhanced readability with carefully tuned contrast ratios
-- Perfect for developer guides, API documentation, and code-heavy content
-
-**Forest Ink Theme**
-- Nature-inspired dark green palette with elegant ink aesthetics
-- Sophisticated design suitable for long-form reading and literary content
-- Unique visual identity that stands out from traditional themes
-
-### ✨ Improvements
-
-**Enhanced Swiss Design Theme**
-- Refined typography with improved spacing and line heights
-- Better color contrast for enhanced accessibility
-- Polished overall visual appearance
-
-**Better Developer Experience**
-- **Absolute Path Support**: Use full file paths in all CLI commands — no more relative path confusion
-  ```bash
-  cthemes export-html /full/path/to/document.md -t elegant -o output.html
-  ```
-- **Interactive Previews**: New HTML preview files for colly and salvator-blog themes
-- **Build Process**: Fixed template file copying to ensure reliable distributions
-
-### 🧹 Housekeeping
-
-- Removed system files (`.DS_Store`) from repository
-
----
-
-## Version 0.2.0 (2026-05-25)
-
-### 🚀 Major Upgrade: v3.0 Design System
-
-**Complete Paradigm Overhaul**
-- Implemented ColaMD's new v3.0 seed palette architecture
-- **15 predefined palettes** across 5 color families:
-  - Morandi (soft, muted tones)
-  - Macaron (pastel, playful)
-  - Nordic (cool, minimalist)
-  - Vintage (warm, retro)
-  - Mint (fresh, vibrant)
-- **Auto-derived semantic mapping**: Design tokens automatically generate consistent color relationships
-- **Mermaid Integration**: 3 diagram presets with 20 customizable variables
-
-### 📚 Academic Focus
-
-**New Academic Style Theme**
-- Specialized formatting for research papers and scholarly documents
-- Optimized typography for citations, references, and structured content
-- Follows academic publishing conventions
-
-**Redesigned Academic Paper Theme**
-- Restructured to comply with v3.0 paradigm specifications
-- Improved consistency with other themes in the ecosystem
-
-### 🔧 Under the Hood
-
-**Refactored Extractors**
-- **URL Extractor**: Advanced CSS parsing with specificity-aware style resolution
-- **DOCX Extractor**: Enhanced Word document style mapping via mammoth
-- **PDF Extractor**: Multi-layer heuristic analysis for better metadata extraction
-- **Auto-Detection**: Smarter source type identification
-
-**Validation Engine**
-- WCAG 2.1 compliance checking built-in
-- 15+ design constraint rules with auto-fix suggestions
-- Contrast ratio and luminance calculations
-
----
-
-## Version 0.1.0 (2026-05-22) — Initial Release 🎉
-
-### Core Features
-
-**Theme Extraction from Any Source**
-- **Web Pages**: Fetch URLs and extract CSS styling automatically
-- **Word Documents**: Import `.docx` files and preserve document styles
-- **PDF Files**: Analyze PDF typography and generate matching themes
-- **Smart Detection**: Automatically identifies source type
-
-**Professional Export Capabilities**
-- **HTML Export**: Standalone documents with embedded themes
-  - Full Mermaid diagram rendering
-  - KaTeX math formula support
-  - Responsive layout with print optimization
-- **PDF Export**: High-quality PDF generation via Chromium
-  - Pixel-perfect theme reproduction
-  - Custom page formats (A4, Letter, etc.)
-  - Batch processing for multiple files
-
-**Complete Theme Management**
-- Built-in theme library (light, dark, elegant, newsprint)
-- Custom theme registration from CSS files
-- Default theme configuration
-- Easy switching between themes
-
-**Developer-Friendly CLI**
-
-```bash
-# Extract theme from any source (use `colamd-themes` or short alias `cthemes`)
-cthemes extract source.docx --name my-theme
-
-# Export with beautiful styling
-cthemes export-html doc.md -t elegant -o output.html
-cthemes export-pdf doc.md -t dark --format A4 -o output.pdf
-
-# Batch process entire directories
-cthemes export docs/ --format pdf -t elegant -d output/
-
-# Manage your themes
-cthemes list
-cthemes validate themes/my-theme.css
-cthemes set-theme my-brand --css custom.css --default
-```
-
-### Technology Stack
-
-- **TypeScript**: Type-safe implementation with full IDE support
-- **css-tree**: Robust CSS parsing and analysis
-- **mammoth**: Reliable DOCX processing
-- **puppeteer**: Accurate PDF rendering
-- **handlebars**: Flexible template engine
-- **commander**: Intuitive CLI framework
-
-### Perfect For
-
-✅ Technical documentation teams needing consistent branding
-✅ Content creators exporting Markdown to professional formats
-✅ Developers building documentation pipelines
-✅ Anyone wanting beautiful, themed Markdown output
-
----
-
-## Quick Start
-
-```bash
-# Install
-git clone https://github.com/byteuser1977/ColaMD-themes.git
-cd ColaMD-themes
-npm install
-npm run build
-
-# Try it out (use either command)
-cthemes export-html README.md -t trae-blue -o preview.html
-open preview.html
-```
-
-## Links
-
-- **Documentation**: [README.md](./README.md)
-- **Chinese Documentation**: [README_CN.md](./README_CN.md)
-- **Changelog**: [CHANGELOG.md](./CHANGELOG.md)
-- **Issues**: [GitHub Issues](https://github.com/byteuser1977/ColaMD-themes/issues)
-- **Contributing**: Pull requests welcome!
-
----
-
-*Last updated: 2026-06-01*
+# Release Notes
+## Version 0.5.0 (2026-10-25) — ColaMD 2.7.7 Support 🎨
+
+> **Verified against the published `@bytechain.cn/colamd@2.7.7` npm package**: all 16 themes are fully contract-compatible, and the design quality of 10 themes has been brought to zero paradigm errors.
+
+### 🎨 Theme Quality Overhaul
+
+**10 themes optimized to pass every paradigm rule (0 errors):**
+
+| Theme | Fix |
+|-------|-----|
+| `colly` / `salvator-blog` / `meeting-minutes` | Panel hierarchy inverted → `--seed-panel-alt` deepened for a proper 2-step contrast |
+| `swiss-design` | Border vs panel-alt lightness gap widened to 3 steps |
+| `shimo-theme` | Panels now neutral grey; accent saturation raised to 83% (`#2a6bf2`) |
+| `elegant` | Brick accent saturation 55% → 70% (`#b0401f`); hardcoded rgba values synced |
+| `guizang` | Beige panels moved to neutral warm grey (fixes NT-02 hue drift) |
+| `pixso-design` | Accent saturation 56% → 76% (`#4f46e5`); 6 gradients/borders migrated from `#6366f1` |
+| `trae-blue` | Accent saturation 70% → 85% (`#2563eb`); panels neutralized |
+| `forest-ink` | Accent saturation raised (`#356b44`); text greys re-tinted onto the ink-green hue axis |
+
+Intentional warnings kept: the low-saturation scholarly accents of the academic trio, and meeting-minutes' pure-black accent (Swiss-minimal signature).
+
+**Removed**: the legacy pre-2.7 theme (`body.theme-custom` root block, 58 dead variables, mojibake filename) — it had no effect under 2.7.7.
+
+### ✅ 2.7.7 Compatibility Audit
+
+Audited against the actual published npm package (`@bytechain.cn/colamd@2.7.7`):
+
+- **Class hooks**: zero drift — every `.cm-md-*` class used by our themes exists among the 49 hooks in the 2.7.7 renderer CSS
+- **Live variables**: the 14 core + 4 typography variables and all 9 `--pele-*` overrides are consumed by 2.7.7
+- **Injection**: the 2.7.7 app appends custom theme CSS to `document.head` (`applyTheme`), so `:root` declarations cascade correctly
+- **Contract version references** across the CLI, validators, and generator unified to 2.7.7
+
+### 🛡️ Export Pipeline Guard
+
+The npm `@bytechain.cn/colamd@2.7.7` package is the **Electron app distribution** — it no longer ships `dist/lib/colamd-renderer.js`, the library entry our HTML/PDF export pipeline needs. The CLI therefore keeps `@bytechain.cn/colamd@^1.5.2`, and `renderer.ts` now detects a 2.x install and fails with a clear downgrade instruction instead of a generic "Cannot find renderer" error.
+
+Two related export fixes verified by smoke test:
+
+- **Built-in theme resolution** — `-t elegant` previously let the 1.5.x renderer apply its own pre-2.7 built-in palette (`#c44b2b`); it now loads our `themes/elegant.css` (2.7.7 contract) first. Registered custom themes and direct `.css` paths were already correct.
+- **Body-variable bridge** — the 1.5.x base CSS declares theme variables on `body`, overriding `:root` inheritance; the pipeline mirrors the theme's `:root` declarations onto `body` at injection time. Theme files themselves remain `:root`-only per the 2.7.7 contract.
+
+> Theme files need no changes for the 2.7.7 app — import them via **Theme > Import Theme** or drop them into `~/.colamd/themes/`.
+> Note: the app now ships its own built-in `elegant` theme; if you import our `elegant.css` into the app, consider renaming the file (e.g. `elegant-brick.css`) to avoid a name clash.
+
+### 🔧 Housekeeping
+
+- Fixed `package-lock.json` root manifest drift (`^2.0.0` → `^1.5.2`, matching `package.json`)
+- Version bumped to **0.5.0**
+
+### 📦 Upgrade
+
+No breaking changes. Pull and rebuild:
+
+```bash
+git pull
+npm install
+npm run build
+```
+
+---
+
+
+## Version 0.4.0 (2026-08-17) — DeepSeek Harness Integration 🤖
+
+> **Multi-agent ecosystem update**: added DeepSeek Harness skill support and formalized 6-agent coverage.
+
+### 🤖 AI Agent Update
+
+**DeepSeek Harness Skill Support**
+- Added `.dsh/skills/colamd-themes/SKILL.md` for DeepSeek Harness integration
+- Build script now supports `bash skills/build-skills.sh dsh` target
+- Consolidated multi-agent documentation across Claude Code, OpenCode, OpenClaw, Hermes, Trae, and DeepSeek Harness
+
+### 🛠️ Improvements
+
+- Standardized agent skill frontmatter with agent-specific metadata and command prerequisites
+- Extended verification scripts (`DSH_SUPPORT_SUMMARY.md`, `test-dsh-skill.sh`)
+
+---
+
+
+## Version 0.3.3 (2026-08-26) — MCP Server & AI Agent Integration 🤖
+
+> **AI ecosystem integration**: ColaMD-themes now connects to AI coding assistants via MCP protocol.
+> **Chinese theme names now fully supported** — no more ASCII-only restriction.
+
+### ✨ New Features
+
+**MCP Server (Model Context Protocol)**
+- Full MCP server implementation in `mcp-server/` directory
+- 14 tools covering theme extraction, export, validation, and management
+- Works with Chatbox, Cursor, Claude Desktop, Continue, and all MCP-compatible clients
+- Quick setup via `npm run mcp` or configure in your MCP client settings
+
+**Multi-Agent Skill Definitions**
+- Added skill files for 5 AI coding agents:
+  - Claude Code, OpenCode, OpenClaw, Hermes, Trae
+- Auto-generated from `skills/colamd-themes/SKILL.md` via `build-skills.sh`
+
+**Chinese Theme Name Support**
+- Fixed CLI ASCII-only filter that stripped non-ASCII characters from theme names
+- MCP server detects non-ASCII names and bypasses the filter using `-o` flag
+- Tested with: `"我的主题"` -> `themes/我的主题.css` ✅
+
+### 📦 Quick Start (MCP)
+
+**Chatbox Configuration:**
+```json
+{
+  "mcpServers": {
+    "colamd-themes": {
+      "command": "node",
+      "args": ["D:/path/to/ColaMD-themes/mcp-server/dist/index.js"],
+      "cwd": "D:/path/to/ColaMD-themes"
+    }
+  }
+}
+```
+
+**Then in your chat:**
+> "Extract a theme from https://example.com named 'My Theme'"
+
+### 🛠️ MCP Tools Reference
+
+| Category | Tool | Description |
+|----------|------|-------------|
+| Extraction | `extract_from_url` | Theme from web page |
+| | `extract_from_docx` | Theme from Word doc |
+| | `extract_from_pdf` | Theme from PDF |
+| | `extract_auto` | Auto-detect source |
+| Management | `list_themes` | List all themes |
+| | `validate_theme` | Validate theme rules |
+| | `check_fonts` | Check font availability |
+| | `set_theme` | Register custom theme |
+| Color | `list_color_systems` | 15 built-in palettes |
+| | `list_mermaid_presets` | 3 Mermaid presets |
+| Export | `export_html` | Markdown to HTML |
+| | `export_pdf` | Markdown to PDF |
+| | `export_batch` | Batch export |
+
+### 🔧 Migration
+
+**No breaking changes** — fully backward compatible.
+
+**New scripts available:**
+```bash
+npm run build:mcp    # Build MCP server only
+npm run build:all    # Build CLI + MCP server
+npm run mcp          # Start MCP server
+```
+
+---
+
+## Version 0.3.2 (2026-05-29) — Theme Authoring Guide 📝
+
+> **AI agent skill enhancement**: Added comprehensive CSS pitfall quick reference for reliable theme generation.
+
+### 📝 AI Agent Skill Update
+
+**CSS Pitfall Quick Reference**
+- Added 6-topic theme authoring guide to all AI agent skill definitions:
+  1. **Screen & Print Sync** — every SECTION 5 rule must mirror in SECTION 6 `@media print`
+  2. **Body Text First-Line Indent** — correct selector chain: `body.theme-custom p, body.theme-custom #write > p`
+  3. **Indent Exclusion** — prevent indent pollution in lists, tables, mermaid blocks, blockquotes, and figures
+  4. **List Indentation** — use `margin-left: 2em` instead of `padding-left`; include `#editor .ProseMirror` selectors
+  5. **Mermaid CJK Text Overflow** — ≤ 2 lines per node, `fontSize: 14px`, simplified text
+  6. **Mermaid classDef Inheritance** — must explicitly declare `fill / color / stroke`
+- References `academic-paper.css` and `swiss-design.css` as canonical examples
+- Skill files affected: `.claude/skills/`, `.opencode/skills/`, `.openclaw/skills/`, `.hermes/skills/`, `.trae/rules/`, `.dsh/skills/colamd-themes/SKILL.md`
+
+### 🔧 Changes
+
+- Consolidated all unreleased changes from v0.3.1 into this patch release
+- Updated CHANGELOG and version links for the 0.3.2 release
+
+---
+
+## Version 0.3.1 (2026-06-01) — Security & Stability Patch 🔒
+
+> **Important**: This release contains critical security fixes and important stability improvements.
+> **All users are strongly recommended to upgrade.**
+
+### 🚨 Critical Security Fixes
+
+**SSRF Vulnerability Patch (CVE-Level)**
+- **Issue**: URL extractor was vulnerable to Server-Side Request Forgery attacks
+  - Attackers could force the server to access internal network resources
+  - Could expose sensitive internal services or cause denial-of-service
+- **Fix**: Implemented comprehensive URL validation in [`url-extractor.ts`](src/extractors/url-extractor.ts):
+  - ✅ Protocol whitelist: Only `http:` and `https:` allowed
+  - ✅ Private network blocking: localhost, 10.x, 172.16-31.x, 192.168.x, 169.254.x
+  - ✅ Clear error messages for blocked attempts
+- **Impact**: Prevents unauthorized internal network access; protects against SSRF attacks
+
+**Input Validation Hardening**
+- **Issue**: No validation on custom CSS theme files before processing
+  - Large files could cause memory exhaustion (OOM)
+  - Invalid file formats could crash the process
+- **Fix**: Added multi-layer validation in [`theme-store.ts`](src/theme-store.ts):
+  - ✅ File extension check (must be `.css`)
+  - ✅ Size limit enforcement (1MB maximum)
+  - ✅ Content validity verification (minimum 10 characters)
+  - ✅ Sanitized filename extraction (removes special chars, limits length)
+- **Impact**: Prevents OOM attacks; ensures graceful error handling
+
+### 🐛 Major Bug Fixes
+
+**PDF Export Theme Not Applied**
+- **Symptom**: Custom themes were ignored when exporting to PDF; documents rendered with default styling only
+- **Root Cause**: Puppeteer's `emulateMediaType("screen")` forced browser into screen mode, causing CSS `@media print { ... }` rules to be completely ignored
+- **Fix**: Removed screen media type emulation in [`renderer.ts`](src/renderer.ts); allows default print mode where all `@media print` styles apply correctly
+- **Result**: PDF exports now render with full theme fidelity — colors, fonts, backgrounds, spacing, and all visual styling correctly applied
+
+**Puppeteer Resource Leak**
+- **Symptom**: Zombie Chromium processes left running after export operations completed
+- **Cause**: Page objects not explicitly closed before browser termination
+- **Fix**: Explicit page cleanup in [`renderer.ts`](src/renderer.ts#L150-L155) close() method
+- **Result**: Clean process shutdown; no resource leaks
+
+**CLI Version Display Incorrect**
+- **Symptom**: `colamd-themes --version` always showed "0.2.0" regardless of actual version
+- **Cause**: Hardcoded version string in CLI initialization
+- **Fix**: Dynamic version reading from [`package.json`](package.json) via [`getPackageVersion()`](src/cli.ts)
+- **Result**: Accurate version display matching published package version
+
+### ⚡ Performance Improvements
+
+**Async I/O Migration**
+- **Before**: Synchronous file operations (`readFileSync`, `writeFileSync`) blocked event loop during theme configuration
+- **After**: All theme store operations now use async API (`fs/promises`)
+- **Benefit**:
+  - Non-blocking configuration reads/writes
+  - Improved responsiveness during batch exports
+  - Better scalability for concurrent operations
+- **Files Updated**: [`theme-store.ts`](src/theme-store.ts)
+
+**Template Cache Management**
+- **Before**: Single global template variable; recompiled on every call after first use; no size limits
+- **After**: Sophisticated cache system with three-layer invalidation:
+  1. **LRU Eviction**: Maximum 10 cached templates (evicts oldest when full)
+  2. **TTL Expiration**: Automatic expiry after 30 minutes of inactivity
+  3. **mtime Detection**: Auto-invalidates when source template file is modified on disk
+- **Benefit**:
+  - ~90% reduction in template compilations for repeated operations
+  - Stable memory usage in long-running processes
+  - Fresh templates automatically loaded after updates
+- **Files Updated**: [`generator.ts`](src/generator.ts)
+
+### 🛠️ Code Quality Enhancements
+
+**Unified Error Handling System**
+- **New Module**: [`cli-utils.ts`](src/utils/cli-utils.ts)
+- **Features**:
+  - `CLIError` class: Structured errors with code, message, and cause chain
+  - `ErrorCode` enum: Standardized categories (FILE_NOT_FOUND, THEME_ERROR, RENDER_ERROR, INVALID_INPUT, UNKNOWN)
+  - Consistent error propagation across all commands
+- **Impact**:
+  - Better debugging experience with detailed error context
+  - Consistent user-facing error messages
+  - Easier error tracking and logging
+  - Process exits with meaningful exit codes
+
+**Code Deduplication**
+- **Extracted Utilities**:
+  - `resolveInputPath(input)`: Validates existence, converts relative→absolute paths
+  - `resolveOutputPath(input, output?, ext?)`: Smart output path derivation
+  - `getDocumentTitle(filePath)`: Extracts clean document title from path
+- **Impact**:
+  - Eliminated duplicate path resolution logic across 4+ command handlers
+  - Single source of truth reduces maintenance burden
+  - Consistent behavior across all export commands
+
+### 📊 Metrics & Benchmarks
+
+| Metric | v0.3.0 | v0.3.1 | Improvement |
+|--------|--------|--------|-------------|
+| **Security Vulnerabilities** | 2 Critical | 0 Known | ✅ Resolved |
+| **Memory Usage (100 files)** | Unbounded | Stable | ✅ Predictable |
+| **Template Compilations** | ~100 per batch | ~10 max | ⚡ 90% fewer |
+| **Event Loop Blocking** | Frequent sync I/O | Minimal async ops | ⚡ Responsive |
+| **Error Consistency** | Mixed patterns | Unified codes | ✅ Maintainable |
+| **Zombie Processes** | Possible leak | Clean shutdown | ✅ Reliable |
+
+### 🔧 Migration Guide
+
+**For Most Users**: No action required! This is a drop-in replacement.
+
+**Breaking Changes**: None — fully backward compatible.
+
+**API Changes** (for programmatic usage):
+```typescript
+// Before (v0.3.0): Sync API
+import { resolveTheme } from '@bytechain.cn/colamd-themes';
+const theme = resolveTheme('elegant'); // Sync
+
+// After (v0.3.1): Async API
+import { resolveTheme } from '@bytechain.cn/colamd-themes';
+const theme = await resolveTheme('elegant'); // Async
+```
+
+**New Error Handling** (recommended):
+```typescript
+import { CLIError, ErrorCode } from '@bytechain.cn/colamd-themes';
+
+try {
+  await exportHTML(document, { theme: 'custom' });
+} catch (error) {
+  if (error instanceof CLIError) {
+    console.error(`Error ${error.code}: ${error.message}`);
+    // Handle specific error types
+    switch (error.code) {
+      case ErrorCode.FILE_NOT_FOUND: /* ... */ break;
+      case ErrorCode.THEME_ERROR: /* ... */ break;
+      case ErrorCode.RENDER_ERROR: /* ... */ break;
+      default: /* ... */ break;
+    }
+  }
+}
+```
+
+### ✅ Testing Recommendations
+
+After upgrading, verify these critical scenarios:
+
+1. **Security Test**:
+   ```bash
+   # Should be blocked (private network)
+   cthemes from-url "http://localhost:3000" --name test
+   
+   # Should be blocked (invalid protocol)
+   cthemes from-url "ftp://example.com/file.css" --name test
+   
+   # Should work (public HTTPS)
+   cthemes from-url "https://example.com" --name my-theme
+   ```
+
+2. **PDF Export Test**:
+   ```bash
+   # Verify themes now apply correctly
+   cthemes export-pdf doc.md -t elegant -o test.pdf
+   open test.pdf  # Check styling is applied
+   ```
+
+3. **Version Display Test**:
+   ```bash
+   # Should show 0.3.1
+   cthemes --version
+   ```
+
+4. **Large File Protection Test**:
+   ```bash
+   # Create a large CSS file (>1MB)
+   dd if=/dev/urandom of=large-theme.css bs=1024 count=1100
+   
+   # Should fail gracefully
+   cthemes set-theme big --css large-theme.css
+   ```
+
+### 📝 Full Changelog
+
+For complete details on all changes, see [CHANGELOG.md](./CHANGELOG.md).
+
+---
+
+## Version 0.3.0 (2026-06-01)
+
+### 📦 Package Name Change
+
+**Migrated to Scoped Package**
+- Package name changed from `colamd-themes` to **`@bytechain.cn/colamd-themes`**
+- Belongs to the `@bytechain.cn` organization ecosystem
+- Consistent with dependency `@bytechain.cn/colamd`
+
+**New Short CLI Command**
+- Added `cthemes` as a short alias for `colamd-themes`
+- Both commands are fully equivalent and interchangeable
+- Recommended for frequent use: shorter to type, same functionality
+
+### 🎨 New Themes
+
+**Trae Blue Theme**
+- Modern blue color scheme optimized for technical documentation
+- Enhanced readability with carefully tuned contrast ratios
+- Perfect for developer guides, API documentation, and code-heavy content
+
+**Forest Ink Theme**
+- Nature-inspired dark green palette with elegant ink aesthetics
+- Sophisticated design suitable for long-form reading and literary content
+- Unique visual identity that stands out from traditional themes
+
+### ✨ Improvements
+
+**Enhanced Swiss Design Theme**
+- Refined typography with improved spacing and line heights
+- Better color contrast for enhanced accessibility
+- Polished overall visual appearance
+
+**Better Developer Experience**
+- **Absolute Path Support**: Use full file paths in all CLI commands — no more relative path confusion
+  ```bash
+  cthemes export-html /full/path/to/document.md -t elegant -o output.html
+  ```
+- **Interactive Previews**: New HTML preview files for colly and salvator-blog themes
+- **Build Process**: Fixed template file copying to ensure reliable distributions
+
+### 🧹 Housekeeping
+
+- Removed system files (`.DS_Store`) from repository
+
+---
+
+## Version 0.2.0 (2026-05-25)
+
+### 🚀 Major Upgrade: v3.0 Design System
+
+**Complete Paradigm Overhaul**
+- Implemented ColaMD's new v3.0 seed palette architecture
+- **15 predefined palettes** across 5 color families:
+  - Morandi (soft, muted tones)
+  - Macaron (pastel, playful)
+  - Nordic (cool, minimalist)
+  - Vintage (warm, retro)
+  - Mint (fresh, vibrant)
+- **Auto-derived semantic mapping**: Design tokens automatically generate consistent color relationships
+- **Mermaid Integration**: 3 diagram presets with 20 customizable variables
+
+### 📚 Academic Focus
+
+**New Academic Style Theme**
+- Specialized formatting for research papers and scholarly documents
+- Optimized typography for citations, references, and structured content
+- Follows academic publishing conventions
+
+**Redesigned Academic Paper Theme**
+- Restructured to comply with v3.0 paradigm specifications
+- Improved consistency with other themes in the ecosystem
+
+### 🔧 Under the Hood
+
+**Refactored Extractors**
+- **URL Extractor**: Advanced CSS parsing with specificity-aware style resolution
+- **DOCX Extractor**: Enhanced Word document style mapping via mammoth
+- **PDF Extractor**: Multi-layer heuristic analysis for better metadata extraction
+- **Auto-Detection**: Smarter source type identification
+
+**Validation Engine**
+- WCAG 2.1 compliance checking built-in
+- 15+ design constraint rules with auto-fix suggestions
+- Contrast ratio and luminance calculations
+
+---
+
+## Version 0.1.0 (2026-05-22) — Initial Release 🎉
+
+### Core Features
+
+**Theme Extraction from Any Source**
+- **Web Pages**: Fetch URLs and extract CSS styling automatically
+- **Word Documents**: Import `.docx` files and preserve document styles
+- **PDF Files**: Analyze PDF typography and generate matching themes
+- **Smart Detection**: Automatically identifies source type
+
+**Professional Export Capabilities**
+- **HTML Export**: Standalone documents with embedded themes
+  - Full Mermaid diagram rendering
+  - KaTeX math formula support
+  - Responsive layout with print optimization
+- **PDF Export**: High-quality PDF generation via Chromium
+  - Pixel-perfect theme reproduction
+  - Custom page formats (A4, Letter, etc.)
+  - Batch processing for multiple files
+
+**Complete Theme Management**
+- Built-in theme library (light, dark, elegant, newsprint)
+- Custom theme registration from CSS files
+- Default theme configuration
+- Easy switching between themes
+
+**Developer-Friendly CLI**
+
+```bash
+# Extract theme from any source (use `colamd-themes` or short alias `cthemes`)
+cthemes extract source.docx --name my-theme
+
+# Export with beautiful styling
+cthemes export-html doc.md -t elegant -o output.html
+cthemes export-pdf doc.md -t dark --format A4 -o output.pdf
+
+# Batch process entire directories
+cthemes export docs/ --format pdf -t elegant -d output/
+
+# Manage your themes
+cthemes list
+cthemes validate themes/my-theme.css
+cthemes set-theme my-brand --css custom.css --default
+```
+
+### Technology Stack
+
+- **TypeScript**: Type-safe implementation with full IDE support
+- **css-tree**: Robust CSS parsing and analysis
+- **mammoth**: Reliable DOCX processing
+- **puppeteer**: Accurate PDF rendering
+- **handlebars**: Flexible template engine
+- **commander**: Intuitive CLI framework
+
+### Perfect For
+
+✅ Technical documentation teams needing consistent branding
+✅ Content creators exporting Markdown to professional formats
+✅ Developers building documentation pipelines
+✅ Anyone wanting beautiful, themed Markdown output
+
+---
+
+## Quick Start
+
+```bash
+# Install
+git clone https://github.com/byteuser1977/ColaMD-themes.git
+cd ColaMD-themes
+npm install
+npm run build
+
+# Try it out (use either command)
+cthemes export-html README.md -t trae-blue -o preview.html
+open preview.html
+```
+
+## Links
+
+- **Documentation**: [README.md](./README.md)
+- **Chinese Documentation**: [README_CN.md](./README_CN.md)
+- **Changelog**: [CHANGELOG.md](./CHANGELOG.md)
+- **Issues**: [GitHub Issues](https://github.com/byteuser1977/ColaMD-themes/issues)
+- **Contributing**: Pull requests welcome!
+
+---
+
+*Last updated: 2026-10-25*