@bytechain.cn/colamd 1.5.0 → 1.5.1-beta.2

package/.trae/specs/optimize-theme-loading/checklist.md

@@ -0,0 +1,20 @@
+# Checklist
+
+- [x] themes 目录已从 `src/renderer/themes/` 迁移到 `src/renderer/editor/plugins/themes/`
+- [x] main.ts 中 `./themes/theme-manager` import 路径已更新为 `./editor/plugins/themes/theme-manager`
+- [x] main.ts 中 `./themes/base.css` import 路径已更新为 `./editor/plugins/themes/base.css`
+- [x] `parseTemplateDirective()` 可正确解析 `/* @template: light */` 注释
+- [x] `setCachedCustomTheme()` 在导入自定义主题时正确缓存 CSS 内容和模版引用
+- [x] `customThemeCache` 维护已导入的自定义主题数据
+- [x] `applyTheme('custom:name')` 从缓存恢复 CSS 并正确应用（含模版变量层叠）
+- [x] 自定义 → 预制 → 自定义 切换后样式完全恢复，无残留污染
+- [x] 应用重启后通过 `setCachedCustomTheme` + `applyTheme` 恢复已保存的自定义主题
+- [x] mermaid-plugin-custom.css 已移除与 variables.css 重复的基础选择器（从432行精简至46行）
+- [x] mermaid-plugin-custom.css 变量命名与 `--mermaid-node-stroke` 等 foundation.css 体系对齐
+- [x] mermaid-plugin.ts 中 `getCustomMermaidThemeVariables()` 变量名对齐（8处）
+- [x] mermaid-plugin.ts 中 `getCustomMermaidC4Config()` 变量名对齐（20处）
+- [x] mermaid-plugin.ts 中 custom 的 dark mode 从 `--mermaid-dark-mode` CSS 变量读取
+- [x] 导入引用模版的自定义主题，模版 class 与 theme-custom class 同时生效
+- [x] 导入不引用模版的自定义主题，行为与当前一致（向后兼容）
+- [x] 所有内建主题无需修改，功能不变
+- [x] TypeScript 编译无本次修改引入的新错误

package/.trae/specs/optimize-theme-loading/spec.md

@@ -0,0 +1,103 @@
+# 优化外部主题载入设定 Spec
+
+## Why
+当前外部导入主题存在两个问题：
+1. **复杂度高**：用户需要编写完整的 CSS 文件（包含大量选择器和变量定义），没有模版继承机制
+2. **Bug**：自定义主题 → 预制主题 → 自定义主题 的切换过程中，自定义 CSS 样式丢失，导致预制主题的样式残留污染
+
+项目已有完整的 CSS 变量抽象体系（`themes/foundation.css` + `themes/base/*.css` + `themes/components/mermaid/*.css`），外部主题应能通过引用基础模版 + 少量变量覆写的方式完成定义，大幅降低配置代码量。
+
+## What Changes
+- 将 `src/renderer/themes/` 目录迁移到 `src/renderer/editor/plugins/themes/` 下
+- `theme-manager.ts`：新增模版引用机制，支持解析 `/* @template: light */` 指令；新增自定义 CSS 持久化缓存，修复切回自定义主题时样式丢失的 Bug
+- `mermaid-plugin-custom.css`：精简优化，利用 CSS 变量体系减少冗余选择器
+- `mermaid-plugin.ts`：优化 custom 主题路径的变量读取逻辑，适配模版引用机制
+- `main.ts`：更新 import 路径；修复 `applyThemeChange` 不传 customCSS 的 Bug
+
+## Impact
+- Affected specs: 主题系统
+- Affected code:
+  - `src/renderer/themes/` → `src/renderer/editor/plugins/themes/` （目录迁移）
+  - `src/renderer/themes/theme-manager.ts` → 新增模版引用 + CSS 缓存
+  - `src/renderer/editor/plugins/mermaid-plugin-custom.css` （精简）
+  - `src/renderer/editor/plugins/mermaid-plugin.ts` （优化 custom 主题路径）
+  - `src/renderer/main.ts` （import 路径 + Bug 修复）
+
+## ADDED Requirements
+
+### Requirement: 外部主题模版引用机制
+The system SHALL 支持外部导入的 CSS 文件通过 `/* @template: <name> */` 注释声明所引用的基础模版。 
+对于没有标注引用的以 light 模版作为引入基础。
+
+支持的模版名称：`light`、`dark`、`elegant`、`newsprint`。
+
+当外部主题声明了模版引用，系统应先加载模版的 CSS 变量（来自 `themes/base/<name>.css` 和 `themes/components/mermaid/<name>.css`），再将导入的 CSS 作为覆写层叠加。导入的 CSS 只需定义与模版有差异的变量。
+
+对现有已经定义的复杂定义的主题模版要做到向下兼容。
+
+#### Scenario: 引用 light 模版
+- **WHEN** 用户导入以下 CSS：
+  ```css
+  /* @template: light */
+  :root {
+    --color-link: #ff6600;
+    --color-accent: #ff6600;
+    --mermaid-node-stroke: #ff6600;
+    --mermaid-highlight: #ff6600;
+  }
+  ```
+- **THEN** 系统先加载 `themes/base/light.css` 的变量，再叠加以上覆写
+- **THEN** 主样式使用 light 模版的字体/颜色/间距，仅链接色和强调色被覆写
+- **THEN** Mermaid 图表使用 light 模版的 mermaid 变量作为基础，节点边框色被覆写为 `#ff6600`
+
+#### Scenario: 不声明模版引用
+- **WHEN** 用户导入的 CSS 不包含 `/* @template: */` 注释
+- **THEN** 行为与当前一致：仅注入自定义 CSS，其他变量使用 `:root` / `foundation.css` 默认值
+
+### Requirement: 自定义主题 CSS 持久化缓存
+The system SHALL 在 `theme-manager.ts` 中缓存最后导入的自定义 CSS 内容和模版引用信息，确保任何时候切换回自定义主题都能正确恢复样式。
+
+#### Scenario: 自定义 → 预制 → 自定义 切换
+- **WHEN** 用户先导入自定义主题，再切换到 dark 主题，再切换回自定义主题
+- **THEN** 自定义主题的 CSS 样式完全恢复，不残留 dark 主题的样式
+- **THEN** Mermaid 图表以自定义主题配色正确渲染
+
+#### Scenario: 应用重启后恢复
+- **WHEN** 应用重启后加载保存的自定义主题（localStorage 中存有 `custom:<name>`）
+- **THEN** 系统通过 API 重新加载该主题的 CSS 文件并恢复样式
+- **THEN** 模版引用信息随主题一起持久化恢复
+
+### Requirement: themes 目录迁移到 editor/plugins 下
+The system SHALL 将 `src/renderer/themes/` 目录整体迁移到 `src/renderer/editor/plugins/themes/`，所有相关 import 路径同步更新。
+
+#### Scenario: main.ts 引用路径
+- **WHEN** main.ts 导入 theme-manager 和 base.css
+- **THEN** import 路径从 `./themes/theme-manager` 更新为 `./editor/plugins/themes/theme-manager`
+- **THEN** CSS import 路径从 `./themes/base.css` 更新为 `./editor/plugins/themes/base.css`
+
+## MODIFIED Requirements
+
+### Requirement: mermaid-plugin-custom.css 精简
+**Before**: 包含大量与 `themes/components/mermaid/variables.css` 功能重叠的选择器（节点样式、连线样式、标签样式等），使用旧的变量命名（`--mermaid-node-border` 而非 `--mermaid-node-stroke`）。
+**After**: 
+- 移除与 `variables.css` 重复的通用选择器（节点/连线/标签/聚类等基础样式）
+- 仅保留 `custom` 主题特有的差异化样式（如 `person-man` 强制白色文字、`foreignObject` span 颜色等）
+- 变量命名与 `foundation.css` 中的 `--mermaid-*` 体系对齐
+
+### Requirement: mermaid-plugin.ts custom 主题变量读取优化
+**Before**: `getCustomMermaidThemeVariables()` 和 `getCustomMermaidC4Config()` 使用旧的变量命名（`--mermaid-node-border`、`--mermaid-line-color` 等），fallback 链混乱。
+**After**: 
+- 变量名与 `foundation.css` 的 `--mermaid-*` 命名体系对齐
+- fallback 逻辑清晰，优先读 `--mermaid-*` 专用变量，fallback 到通用 CSS 变量
+- `getMermaidTheme()` 中 custom 主题的 dark mode 判断从 `--mermaid-dark-mode` CSS 变量读取
+
+### Requirement: theme-manager.ts applyTheme 函数
+**Before**: `applyTheme(name, customCSS?)` 仅注入传入的 `customCSS`，不维护缓存；切回自定义主题时无 CSS 可注入。
+**After**:
+- 内部缓存自定义 CSS 内容和模版引用
+- `applyTheme` 在检测到 `custom:` 前缀时自动应用缓存（含模版变量层叠）
+- 导出 `setCachedCustomTheme(name, css)` 供外部在导入时调用
+- 导出 `getCachedCustomTheme(name)` 支持查询已缓存的主题
+
+## REMOVED Requirements
+无。所有现有功能保持不变，仅做增强和修复。

package/.trae/specs/optimize-theme-loading/tasks.md

@@ -0,0 +1,40 @@
+# Tasks
+
+- [x] Task 1: 迁移 themes 目录到 editor/plugins 下
+  - [x] 将 `src/renderer/themes/` 完整移动到 `src/renderer/editor/plugins/themes/`
+  - [x] 更新 `src/renderer/main.ts` 中的 import 路径：`./themes/theme-manager` → `./editor/plugins/themes/theme-manager`
+  - [x] 更新 `src/renderer/main.ts` 中的 CSS import：`./themes/base.css` → `./editor/plugins/themes/base.css`
+
+- [x] Task 2: 重构 theme-manager.ts — 模版引用 + CSS 缓存 + Bug 修复
+  - [x] 新增 `parseTemplateDirective(css: string): string | null` 函数，解析 `/* @template: <name> */`
+  - [x] 新增自定义 CSS 缓存（`customThemeCache: Map<string, { css: string; template: string | null }>`）
+  - [x] 导出 `setCachedCustomTheme(name, css)` 用于导入时缓存
+  - [x] 导出 `getCachedCustomTheme(name)` 用于查询已缓存的主题
+  - [x] 修改 `applyTheme(name, customCSS?)`：当 `name` 以 `custom:` 开头时从缓存恢复 CSS，并根据模版引用叠加模版 class
+
+- [x] Task 3: 优化 mermaid-plugin-custom.css — 精简与 variables.css 去重
+  - [x] 移除与 `themes/components/mermaid/variables.css` 重复的基础选择器（节点/连线/标签/聚类等）
+  - [x] 保留 custom 主题特有的差异化样式（person-man 强制白色、文字偏移等）
+  - [x] 文件从 432 行精简至 46 行
+
+- [x] Task 4: 优化 mermaid-plugin.ts — custom 主题变量读取对齐
+  - [x] 更新 `getCustomMermaidThemeVariables()` 中的变量名（8处对齐）
+  - [x] 更新 `getCustomMermaidC4Config()` 中的变量名（20处对齐）
+  - [x] `getMermaidTheme()` 中 custom 的 dark mode 判断已从 `--mermaid-dark-mode` CSS 变量读取（无需修改，已正确实现）
+
+- [x] Task 5: 更新 main.ts — import 路径 + 调用来适配新 API
+  - [x] 导入 `setCachedCustomTheme` 函数
+  - [x] 修改 `onMenuImportTheme` 回调：先 `setCachedCustomTheme` 再 `applyTheme`
+  - [x] 修改移动端菜单 `import-theme` 回调，同上
+  - [x] 修改应用重启恢复逻辑：先 `setCachedCustomTheme` 再 `applyTheme`
+
+- [x] Task 6: 验证
+  - [x] TypeScript renderer 编译无本次修改引入的新错误
+  - [x] 14 项 checklist 全部通过
+
+# Task Dependencies
+- Task 2 依赖 Task 1（迁移后路径才正确）
+- Task 3 依赖 Task 1（CSS 文件引用 themes 目录）
+- Task 4 可与 Task 3 并行
+- Task 5 依赖 Task 1 和 Task 2
+- Task 6 依赖 Task 1-5 全部完成

package/CHANGELOG.md

@@ -0,0 +1,323 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.5.1-beta.2] - 2026-05-22
+
+### Fixed
+
+#### TypeScript Type Errors
+- Fixed 15 TypeScript type errors across the codebase:
+  - `capacitor-api.ts`: Fixed `string | null` type assignment error
+  - `editor.ts`: Fixed `remarkPluginsCtx` type mismatch and `rootEl` null check
+  - `math-plugin.ts`: Fixed `$NodeSchema` type compatibility with `$view` function
+  - `mermaid-plugin.ts`: Fixed Mermaid theme type and `$NodeSchema` type issues
+  - `main.ts`: Added Vite client types reference for `import.meta.glob`
+  - `main/index.ts`: Removed invalid `createServer` import from `fs` and `marginType` from `PrintToPDFOptions`
+
+#### TypeScript Project Configuration
+- Added `"composite": true` to all TypeScript project configurations for proper project references:
+  - `tsconfig.main.json`
+  - `tsconfig.preload.json`
+  - `tsconfig.renderer.json`
+
+### Changed
+
+#### Mermaid Theme System Refactor
+- **Restructured Mermaid styles to warm color palette**:
+  - Changed Mermaid color scheme to Guizang warm tones (cream background + brown tones)
+  - Adjusted font size to 10.5pt for academic printing compatibility
+  - Added Typora compatible selectors (`.md-diagram-panel`)
+  - Added mobile responsive adaptation
+  - Unified text color and border styles
+
+#### Theme System Architecture
+- **New modular theme architecture**:
+  - `src/renderer/editor/plugins/themes/` — New theme manager and base styles
+  - `themes/base/` — Base theme CSS files (light, dark, elegant, newsprint)
+  - `themes/components/mermaid/` — Mermaid-specific theme CSS files
+  - `foundation.css` — Shared foundation styles
+  - `variables.css` — CSS variables for Mermaid theming
+
+### Added
+
+#### New Themes
+- **Academic Paper theme**: [`academic-paper.css`](themes/academic-paper.css)
+  - Mermaid color scheme in Guizang warm tones (cream background + brown tones)
+  - Font size optimized for academic printing (10.5pt)
+  - Typora compatible selectors (`.md-diagram-panel`)
+  - Mobile responsive adaptation
+- **Pixso Design theme**: [`pixso-design.css`](themes/pixso-design.css)
+- **Swiss Design theme**: [`swiss-design.css`](themes/swiss-design.css) 🇨🇭
+  - Pure black-white-red color system inspired by Swiss International Typographic Style
+  - Geometric sans-serif fonts (Helvetica / Inter), grid-based layout with generous whitespace
+  - Form follows function design philosophy, minimal and restrained aesthetic
+  - Complete Mermaid diagram integration with monochrome + accent red styling
+
+#### Theme Development Framework
+- **Theme paradigm document**: [`docs/theme-paradigm.md`](docs/theme-paradigm.md)
+  - Comprehensive CSS theme development specification (v3.0)
+  - Design principles: variable-based, modular, semantic naming, AI-agent derivable
+  - Mandatory design constraints with validation methods (MUST / MUST NOT / SHOULD levels)
+  - Color space specification: 5 seed colors + 3 font stacks auto-derivation system
+  - Print fidelity requirements: `@media print` as screen style mirror enhancement
+
+- **Standardized theme template**: [`themes/template.css`](themes/template.css)
+  - Reference implementation following the v3.0 paradigm
+  - All required sections: design tokens, editor styles, code blocks, blockquotes, tables, Mermaid variables, print styles
+  - Ready-to-use template for creating new custom themes
+
+#### Documentation Updates
+- Updated [README.md](README.md) and [README_CN.md](README_CN.md) to include Swiss Design theme in the downloadable themes table
+- Added comprehensive theme descriptions for all 7 external themes (elegant, guizang, forest-ink, academic-paper, pixso-design, swiss-design, template)
+
+---
+
+## [1.5.1-beta.1] - 2026-05-22
+
+### Added
+
+#### Android Platform Support
+- **Full Android platform support**: Integrated Capacitor 6 for native Android app builds
+- **File picker functionality**: Integrated `@capawesome/capacitor-file-picker` plugin for file selection on Android devices
+- **Mobile responsive styles**: Added [`mobile.css`](src/renderer/mobile.css) for optimized mobile display and interaction
+- **Auto-generated app icons**: Added [`generate-icons.js`](scripts/generate-icons.js) script to auto-generate Android/iOS icons at various sizes
+  - Android mipmap icons (48px-192px)
+  - Android adaptive icon foreground layer (108px-432px)
+  - iOS AppIcon (1024x1024)
+
+#### New Themes & Styles
+- **Forest Ink slide theme**: Added forest ink color scheme slide template with full presentation logic and responsive layout
+- **Academic Paper theme**: Added [`academic-paper.css`](src/renderer/styles/themes/academic-paper.css) theme
+  - Mermaid color scheme in Guizang warm tones (cream background + brown tones)
+  - Font size optimized for academic printing (10.5pt)
+  - Typora compatible selectors (`.md-diagram-panel`)
+  - Mobile responsive adaptation
+- **Pixso Design theme**: Added [`pixso-design.css`](src/renderer/styles/themes/pixso-design.css) theme
+
+### Fixed
+
+#### Android Platform Fixes
+- **Chinese IME (Input Method Editor) fix**:
+  - Removed `e.preventDefault()` in `beforeinput` event to resolve CJK input method issues
+  - Enhanced ProseMirror editor IME composition event handling
+  - Used `-webkit-user-modify: read-write-plaintext-only` to improve input experience
+- **Intent file open fix**:
+  - Added `Intent.ACTION_VIEW` handling in `MainActivity`
+  - Supported `onNewIntent` for opening new files when app is already running
+  - Passed file content to WebView via JavaScript events
+- **PDF export fix**:
+  - Replaced Capacitor Plugin bridge with `JavascriptInterface`
+  - Added `ColaMDNativeBridge` class to call Android native `PrintManager`
+  - Added "Save as PDF" option
+  - Fixed pagination, save button, mermaid version, and layer residue issues
+
+#### Export Functionality Improvements
+- **PDF/HTML export**:
+  - Refactored Mermaid rendering logic with export sync wait mechanism
+  - Supported real-time rendered content export
+  - Fixed default filename logic
+- **File manager open**:
+  - Adopted pull model: JS actively calls Java `checkPendingFile()` to query
+  - Eliminated JS event injection timing issues
+  - Added init detection + setInterval polling for dual guarantee
+
+### Changed
+
+- **Mobile IME handling refactor**:
+  - Simplified mobile CSS styles, removed outdated Android IME patches
+  - Refactored Android file open event listener, using new `colamd-open-event` instead of old `intent-file-opened`
+- **Close button style optimization**: Replaced rectangle rotation icon with standard cross line icon for more consistent visual effect
+- **Theme style updates**:
+  - `mermaid-plugin.css`: Minor adjustments
+  - `forest-ink.css`: Updated forest ink theme
+
+### Documentation
+
+- Added [`demo.md`](docs/demo.md) and [`demo.pdf`](docs/demo.pdf) demo documents
+- Updated README and README_CN.md with export documentation and new doc paths
+- Added mobile support documentation with tech stack, build/release workflow, and troubleshooting
+- Added Forest Ink theme documentation
+
+### Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| @capawesome/capacitor-file-picker | ^6.2.0 | Android file picker plugin |
+| sharp | ^0.34.5 | Icon generation tool |
+
+---
+
+## [1.5.1] - 2026-05-18
+
+### Added
+
+#### Capacitor 6 — Mobile Platform Support (Cross-Platform Extension)
+- **Capacitor 6 integration** for building native Android (.apk) and iOS (.ipa) apps
+- **Platform bridge layer** ([`capacitor-api.ts`](src/renderer/capacitor-api.ts)): Full replacement of Electron IPC with Capacitor native plugins
+  - Filesystem plugin for file read/write on mobile devices
+  - Share plugin for content sharing and export
+  - App plugin for lifecycle management and deep linking
+  - Status bar plugin for mobile UI integration
+  - Haptics plugin for tactile feedback support
+- **Auto-detection runtime**: `window.electronAPI || createCapacitorAPI()` — seamless switching between desktop (Electron) and mobile (Capacitor) environments
+- **Mobile responsive UI** ([`mobile.css`](src/renderer/mobile.css)):
+  - Touch-optimized interactions with `-webkit-tap-highlight-color: transparent`
+  - Safe area insets support (`env(safe-area-inset-*)`) for notched devices
+  - Responsive breakpoints: 768px (tablet), 480px (phone)
+  - Optimized font sizes, padding, and scroll behavior for mobile screens
+  - Context menu adaptation for touch interfaces
+
+#### Android Platform Configuration
+- Android project initialized at [`android/`](android/) with Gradle build system
+- **File association**: Registered `.md` / `.markdown` file handlers in `AndroidManifest.xml`
+- **Storage permissions**: `READ_EXTERNAL_STORAGE`, `WRITE_EXTERNAL_STORAGE`, `MANAGE_EXTERNAL_STORAGE`
+- **Network security config**: Cleartext traffic allowed for local development
+- **Soft input mode**: `adjustResize` for proper keyboard handling in editor
+- **5 Capacitor plugins auto-detected**: @capacitor/app, filesystem, haptics, share, status-bar
+
+#### iOS Platform Configuration
+- Xcode project initialized at [`ios/`](ios/) with CocoaPods dependency management
+- Requires Xcode + CocoaPods for full build (pod install)
+- Web assets synced to `ios/App/App/public/`
+
+#### Build Scripts & Workflow
+- New npm scripts for Capacitor development workflow:
+
+| Script | Purpose |
+|--------|---------|
+| `npm run cap:sync` | Sync web assets to native platforms |
+| `npm run cap:open:android` | Open in Android Studio |
+| `npm run cap:open:ios` | Open in Xcode |
+| `npm run cap:run:android` | Build → Sync → Run on Android device/emulator |
+| `npm run cap:run:ios` | Build → Sync → Run on iOS simulator |
+| `npm run cap:build:android` | Build debug APK |
+| `npm run cap:build:ios` | Build iOS project |
+
+#### Dual-Platform Architecture
+```
+┌─────────────────────────────────────┐
+│         src/renderer/main.ts         │
+│   api = electronAPI || capacitorAPI  │ ← Auto-detect platform
+├──────────────┬──────────────────────┤
+│  Electron    │     Capacitor 6      │
+│  (Desktop)   │     (Mobile)          │
+│              │                      │
+│ IPC comm     │ Filesystem Plugin    │
+│ dialog       │ Share Plugin         │
+│ shell.open   │ App Plugin           │
+│ fs module    │ localStorage storage │
+└──────────────┴──────────────────────┘
+```
+
+### Changed
+- Updated [`editor.ts`](src/renderer/editor/editor.ts): Added fallback `window.capacitorAPI?.openExternal()` for link handling on mobile
+- Updated [`env.d.ts`](src/renderer/env.d.ts): Extended type declarations to include `window.capacitorAPI`
+- Package version bumped to **1.5.1**
+
+### Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| @capacitor/core | ^6.2.1 | Capacitor core runtime |
+| @capacitor/cli | ^6.2.1 | Capacitor CLI tools |
+| @capacitor/android | ^6.2.1 | Android native bridge |
+| @capacitor/ios | ^6.2.1 | iOS native bridge |
+| @capacitor/filesystem | ^6.0.4 | Mobile file I/O |
+| @capacitor/share | ^6.0.4 | Native sharing |
+| @capacitor/app | ^6.0.3 | App lifecycle |
+| @capacitor/haptics | ^6.0.3 | Tactile feedback |
+| @capacitor/status-bar | ^6.0.3 | Status bar control |
+
+## [1.5.0] - 2026-05-18
+
+### Added
+
+#### Renderer Plugin System (Core Feature)
+- Introduce declarative plugin architecture with independent registration, enable/disable toggle, and dynamic module management
+- Unified plugin design pattern: Schema Definition → NodeView Interaction → Remark Parsing → Markdown Serialization → PNG Export → Rendered/Source Dual Mode
+- **Plug** menu in menu bar for unified plugin render control
+
+#### Math Plugin (KaTeX Integration)
+- Add KaTeX rendering engine for LaTeX math equation support
+- **Inline equations** (`$...$`): embedded within paragraphs, e.g., $E = mc^2$
+- **Block equations** (`$$...$$`): centered display with support for complex expressions (equation systems, matrices, physics formulas)
+- **Dual-mode toggle**: switch between rendered preview and source editing with one click
+- Live editing: edit LaTeX source directly in raw mode; auto-save and re-render on blur
+- Graceful fallback: degrade to plain text on KaTeX parse failure without blocking workflow
+
+#### Mermaid Plugin (Diagram Rendering)
+- Add Mermaid.js v11.15 for 17+ diagram type visualization:
+
+| Category | Supported Diagrams |
+|----------|-------------------|
+| Flowchart | `graph` (TD/LR/RL/BT), `flowchart` |
+| Sequence | `sequenceDiagram` |
+| Class | `classDiagram` |
+| State | `stateDiagram-v2` |
+| ER | `erDiagram` |
+| User Journey | `journey` |
+| Pie | `pie` |
+| Gantt | `gantt` |
+| Git Graph | `gitGraph` |
+| Mind Map | `mindmap` |
+| Timeline | `timeline` |
+| Quadrant Chart | `quadrantChart` |
+| XY/Line/Bar Chart | `xyChart` |
+| C4 Architecture | `C4Context`, `C4Container`, `C4Component`, `C4Dynamic`, `C4Deployment` |
+| Sankey | `sankey-beta` |
+| Block | `block-beta` |
+| Architecture | `architecture-beta` |
+
+- Input shortcut: typing `` ```mermaid `` + Enter auto-converts to mermaid_block node
+- Async-safe rendering: render counter prevents race conditions
+- Multi-theme deep adaptation: each built-in theme has corresponding Mermaid color scheme
+- C4 architecture-specific semantic colors for persons/systems/containers/components
+- Auto node height adjustment after rendering (+6px padding) to prevent content overflow
+
+#### Theme Support
+- **Guizang theme**: new Chinese-style dark theme with traditional aesthetics
+- Custom Mermaid theme adaptation for Elegant, Newsprint, Dark, and Guizang themes:
+  - Light → Default Mermaid theme (clean & bright)
+  - Dark → GitHub Dark style (`#0d1117` background, `#8b949e` border/text)
+  - Elegant → Custom warm palette (`#e8e2db` background, LXGW WenKai font)
+  - Newsprint → Print style (PT Serif font, newsprint texture)
+
+#### Slides Feature — Markdown as Database
+- New concept: Markdown as content layer, HTML templates as view layer
+- Supported layouts: `cover` · `statement` · `section` · `video` · `thankyou`
+- Optional features: background image (`bg:`), video embed (`src:`), inline image preview (`preview:`)
+- Export formats: single-file HTML (Base64-inlined images) or folder (with video resources)
+- Tutorial template included at `resources/templates/slides/`
+
+### Fixed
+- Mermaid diagram color scheme issues in dark themes causing unreadable content
+- Mermaid diagram container offset/miscalculation leading to content overflow
+- Sankey diagram syntax parsing compatibility
+- Slides templates not properly bundled into extraResources during build
+
+### Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| @milkdown/kit | ^7.19.2 | WYSIWYG editor core |
+| katex | ^0.16.46 | Math equation rendering engine |
+| mermaid | ^11.15.0 | Diagram rendering library |
+| electron | ^34.0.0 | Cross-platform desktop framework |
+
+## [1.4.0] - Previous Release
+
+### Added
+- Slides feature — Markdown as Database concept
+- Slide export capabilities (HTML single-file and folder formats)
+
+---
+
+[1.5.1-beta.2]: https://github.com/byteuser1977/ColaMD-extend/releases/tag/v1.5.1-beta.2
+[1.5.1-beta.1]: https://github.com/byteuser1977/ColaMD-extend/releases/tag/v1.5.1-beta.1
+[1.5.1]: https://github.com/byteuser1977/ColaMD-extend/releases/tag/v1.5.1
+[1.5.0]: https://github.com/byteuser1977/ColaMD-extend/releases/tag/v1.5.0
+[1.4.0]: https://github.com/byteuser1977/ColaMD-extend/releases/tag/v1.4.0

package/CLAUDE.md

@@ -85,3 +85,59 @@ src/
 - 主题 CSS 与编辑器逻辑完全分离
 - 代码简洁，不过度设计
 - 每个新功能先问：这是必要的吗？
+
+### 插件系统规范
+
+插件与主程序通过 `RendererPlugin` 接口通信，遵循**弱耦合**原则：
+
+**1. 插件注册**
+
+插件通过 `registerPluginModule()` 自注册（副作用导入）：
+
+```typescript
+// ✅ 正确：副作用导入，仅触发 registerPluginModule
+import './editor/plugins/math-plugin'
+import './editor/plugins/mermaid-plugin'
+
+// ✅ 兜底：glob 加载可能遗漏的插件
+const _pluginRegistry = import.meta.glob('./editor/plugins/*-plugin.ts', { eager: true })
+
+// ❌ 禁止：导入插件专用函数/类型
+import { awaitAllMermaidRenders } from './editor/plugins/mermaid-plugin'
+```
+
+**2. 接口驱动**
+
+`main.ts` 只通过 `RendererPlugin` 接口方法与插件交互，**禁止**直接导入插件专用函数或硬编码插件 ID：
+
+```typescript
+// ✅ 正确：遍历插件，调用通用接口
+for (const p of getAllPlugins()) p.ensureRendered?.()
+
+// ❌ 禁止：直接导入插件专用函数
+import { awaitAllMermaidRenders } from './editor/plugins/mermaid-plugin'
+await awaitAllMermaidRenders()
+
+// ❌ 禁止：硬编码插件 ID 做特殊处理
+getAllPlugins().filter(p => p.id === 'mermaid')
+```
+
+**3. 功能归属**
+
+| 逻辑类型 | 归属 |
+|----------|------|
+| 插件注册、schema、视图、导出能力 | 插件文件 (`*-plugin.ts`) |
+| 通用插件查询、切换、导出能力发现 | `plugins/index.ts` |
+| 编辑器创建、markdown 读写 | `editor/editor.ts` |
+| IPC 事件路由、UI 协调 | `main.ts` |
+
+**4. 减少 main.ts 修改**
+
+新增插件功能时，优先在插件文件和 `plugins/index.ts` 中实现。`main.ts` 仅在需要新的 IPC 事件路由或 UI 协调时才修改。
+
+**5. `RendererPlugin` 接口约定**
+
+- `ensureRendered?: () => Promise<void>` — 导出前等待渲染完成
+- `onThemeChange?: (theme: string) => void` — 主题切换时重新配置
+- `exportCapabilities?: ExportCapability[]` — 右键导出菜单
+- `nodeTypes?: string[]` — 声明插件管理的 ProseMirror 节点类型