feat: 扩展本地主题兼容能力

docs/PROGRESS.md

@@ -19,11 +19,12 @@ main
 已有提交：
 
 ```text
+fa07472 feat: 实现网页实时预览
 7224dfd feat: 实现 Markdown 渲染核心
 ec48bce chore: 初始化项目骨架
 ```
 
-当前工作区存在未提交修改，主要是网页实时预览、预览 API、动态主题注册和本地 Typora 主题导入。接手时必须保留并审查这些修改，不要重置工作区。
+当前工作区存在未提交修改，主要是主题基础 CSS 组合、安全的 CSS `@import` 展开、三套本地 Typora 默认主题导入和主题开发文档。接手时必须保留并审查这些修改，不要重置工作区。
 
 ## 2. 已完成
 
@@ -59,14 +60,16 @@ ec48bce chore: 初始化项目骨架
 - 主题 ID、名称、版本、作者、许可证；
 - DOM 预设；
 - 支持能力声明；
-- 主体 CSS 和打印 CSS；
+- 可选基础 CSS、主体 CSS 和打印 CSS；
 - 自制 Typora 风格主题；
 - `#write` 兼容文档结构；
 - 内置主题和 `.local/themes` 本地主题动态扫描；
+- 按基础 CSS、主体 CSS、打印 CSS 的固定顺序组合；
+- 主题内相对 CSS `@import` 安全展开；
 - 主题 CSS 相对资源重写与受限资源接口；
 - 目录匹配、真实路径包含关系和外部 URL 安全检查。
 
-内置主题为项目自有实现，没有复制 Typora 官方默认主题。用户可以通过导入工具将本机已安装的 Typora GitHub 默认主题复制到 Git 忽略的 `.local/themes/typora-github`，该副本仅供本机使用，不进入仓库或发布包。
+内置主题为项目自有实现，没有复制 Typora 官方默认主题。用户可以通过导入工具将本机已安装的 Typora 基础 CSS以及 GitHub、Pixyll 和 Whitey 三套适合打印的白色默认主题复制到 Git 忽略的 `.local/themes`。这些副本仅供本机使用，不进入仓库、容器或发布包。
 
 ### 2.4 Markdown 渲染核心
 
@@ -88,43 +91,48 @@ ec48bce chore: 初始化项目骨架
 - 统一 `<article id="write">` 输出；
 - 5 项渲染单元测试。
 
+### 2.5 网页实时预览
+
+提交 `fa07472` 已完成：
+
+- 可测试的 Fastify `buildApp()`；
+- `POST /api/render` 服务端统一 Markdown 渲染；
+- 动态主题清单、CSS 和资源 API；
+- Markdown 编辑及本地 `.md` 文件读取；
+- 250ms 防抖 A4 实时预览；
+- iframe 隔离主题 CSS；
+- KaTeX、highlight.js 和按需加载的 Mermaid；
+- 桌面双栏与移动端上下布局；
+- 5 项渲染器测试和 4 项后端测试。
+
 ## 3. 当前未提交工作
 
 以下内容已写入工作区，但尚未提交：
 
-### 3.1 后端预览 API
+### 3.1 主题清单与服务端主题注册
 
-- 将 Fastify 应用拆分为可测试的 `buildApp()`。
-- `POST /api/render`：接收 Markdown 并返回安全渲染结果。
-- `GET /api/themes`：动态返回内置和本地可用主题。
-- `GET /api/themes/:themeId/css`：返回主题 CSS 和打印 CSS。
-- `GET /api/themes/:themeId/assets/*`：返回经过路径校验的主题字体和图片。
-- 增加请求体积和参数类型检查。
-- 增加 4 项后端 API 测试。
+- 主题清单新增可选 `base` 字段。
+- CSS 按基础 CSS、主体 CSS、打印 CSS 的顺序组合，预览与未来 PDF 可复用同一结果。
+- 支持带引号或 `url()` 写法的相对 `@import`。
+- 限制导入深度为 8 层，并检测循环引用。
+- 阻止外部 URL、绝对路径和 `..` 越界导入。
+- 按每个 CSS 文件所在目录重写相对字体和图片 URL。
+- 增加基础 CSS 组合、相对导入、循环导入和外部导入测试，后端测试增至 6 项。
 
-### 3.2 网页预览
+### 3.2 本地 Typora 默认主题导入
 
-- Markdown 文本编辑区；
-- 本地 `.md` 文件读取；
-- 250ms 防抖实时预览；
-- 固定 210mm 宽度的 A4 纸张效果；
-- 内置和本地主题选择；
-- iframe 隔离主题 CSS，避免主题影响应用界面；
-- KaTeX 样式；
-- highlight.js 样式；
-- Mermaid 浏览器渲染；
-- Mermaid 改为按需加载；
-- Mermaid 使用逐个 `render()` 后注入安全 SVG；
-- 桌面双栏与移动端上下布局；
-- PDF 按钮保留为下一阶段入口。
+- 导入器从本机 Typora 安装目录读取 `resources/style`。
+- 一次导入 GitHub、Pixyll 和 Whitey 三套适合打印的白色默认主题。
+- 每套本地主题包含独立的 Typora 基础 CSS、主题 CSS 和所需资源。
+- 主题版本从 Typora `resources/package.json` 读取；当前本机版本为 1.14.7。
+- 默认拒绝覆盖已有主题；`--replace` 使用暂存目录并将旧副本备份到 `.local/theme-backups/<时间戳>`。
+- 当前三套主题及替换操作产生的备份均位于被 Git 忽略的 `.local`，不得提交或发布。
 
 ### 3.3 文档及依赖
 
-- README 已更新为预览阶段状态。
-- 增加 `npm run theme:import-typora` 本地主题导入命令。
-- `.local/` 已加入 Git 忽略规则。
-- 增加 Mermaid、KaTeX、highlight.js 和后端测试依赖。
-- `package-lock.json` 已更新。
+- README 已更新三套本地 Typora 主题的导入和替换说明。
+- 新增 `docs/THEMES.md`，说明主题目录、清单字段、CSS 加载顺序、`#write` DOM、相对资源、安全限制和自定义主题流程。
+- `npm run theme:import-typora` 保持为本地导入入口。
 
 ## 4. 已执行验证
 
@@ -140,22 +148,25 @@ git diff --check
 结果：
 
 - 渲染器测试：5 项通过；
-- 后端测试：4 项通过；
+- 后端测试：6 项通过；
 - 全项目类型检查通过；
 - 生产构建通过；
-- `git diff --check` 通过，仅出现工作区 LF 将来可能转为 CRLF 的提示。
+- `git diff --check` 通过，仅出现工作区 LF 将来可能转为 CRLF 的提示；
+- 导入器默认的已存在目标保护通过；
+- GitHub、Pixyll 和 Whitey 三套本地主题的 CSS API 均返回成功，组合结果无残留 `@import`。
 
 已使用浏览器插件完成视觉验证：
 
 - 导入并打开 `tmp/数据中台项目周报_2026_W30.md`；
 - 参考 `tmp/数据中台项目周报_2026_W30.pdf` 的 Typora 输出；
-- A4 纸张宽度、标题、长表格和滚动布局正常；
-- 本地 Typora GitHub 主题及 Open Sans 字体加载正常；
-- 内置主题与本地主题切换正常；
+- GitHub、Pixyll 和 Whitey 三套保留的本地主题均可正常切换；
+- 三套主题中的表格均为 `border-collapse: collapse`、单元格间距为 0，并铺满 `#write` 内容宽度；
+- GitHub 表格边框颜色与主题定义的 `#dfe2e5` 一致；
+- Open Sans、PT Serif 和 Merriweather 字体资源均成功加载；
 - KaTeX、代码高亮和 Mermaid 正常显示；
 - 浏览器控制台无警告或错误。
 
-视觉验证所启动的开发服务进程树已清理，3001 和 5173 端口无残留监听。
+为方便用户继续检查，开发服务当前仍在后台运行，前端监听 5173，后端监听 3001。
 
 ## 5. 当前注意事项
 
@@ -163,7 +174,9 @@ git diff --check
 - `apps/web/src/App.tsx` 是当前预览实现的主要文件。
 - `apps/server/src/app.ts` 是新增的可测试 Fastify 应用。
 - `apps/server/src/theme-registry.ts` 负责内置和本地主题发现、CSS 处理及资源安全。
-- `.local/themes/typora-github` 是用户本机副本，已被 Git 忽略，不得提交。
+- `.local/themes/typora-*` 是用户本机副本，已被 Git 忽略，不得提交。
+- `.local/theme-backups` 中保留 GitHub、Pixyll 和 Whitey 的可恢复备份；Newsprint 和 Night 的当前副本及备份已按用户要求删除。
+- Typora 官方资源是 All Rights Reserved，仅限当前用户本机使用，不进入 Git、容器或发布包。
 - Mermaid 已按需加载，但生产构建仍提示 `mermaid.core` 和 `cynefin` 两个分块超过 500 kB；这不影响功能，可后续优化。
 - PDF 生成尚未实现。
 - 资源目录上传、本地相对图片、临时目录和路径安全尚未实现。
@@ -171,12 +184,12 @@ git diff --check
 
 ## 6. 推荐接手顺序
 
-### 阶段一：提交网页预览
+### 阶段一：提交主题兼容增强
 
-网页预览、动态主题、本地 Typora 主题导入、全量验证和视觉检查均已完成。用户确认后创建独立提交：
+网页实时预览已在 `fa07472` 提交。当前主题基础 CSS、三套本地 Typora 主题导入、主题开发文档、全量验证和视觉检查均已完成。用户确认后创建独立提交：
 
 ```text
-feat: 实现网页实时预览
+feat: 扩展本地主题兼容能力
 ```
 
 ### 阶段二：实现真实 PDF