# blog-5l：后台预览一致性 + 排版提醒 + 瞬间置顶/隐藏

<!-- spec-format: 2 -->

- **slug**: 2026-11-05_blog-5l-admin-preview-moments
- **日期**: 2026-11-05
- **状态**: 进行中
- Git integration branch：`spec/2026-11-05_blog-5l-admin-preview-moments`
- 证据协议：evidence: runs
- **提案**: 后台（Sveltia CMS）编辑 markdown 时的预览窗格不渲染排版类（font- 字体、c-/ink- 颜色看不到效果），且编辑时缺少「能用哪些字体/颜色」的提醒；瞬间（moments）需要与文章一致的置顶/隐藏能力。三件事合成一包：预览注入站点排版样式（官方 `CMS.registerPreviewStyle`）、hint/文档提醒、moments pinned/hidden 真字段契约。

## 1. 问题定义
- **项目目标**：后台编辑 markdown 时预览窗格直接显色/显字体（与真实页面一致），编辑时能看到可用字体/颜色的提醒；瞬间获得与文章一致的置顶/隐藏能力。
- **目标用户**：站长（编辑体验与内容管理）；读者不受影响（仅瞬间排序/可见性语义对齐）
- **核心价值**：所见即所得消灭「写完发布才发现样式不对」的往返；moments 与 posts 的管理语义统一，降低心智负担

## 2. 假设与待确认

### 2.1 已确认事实
- Sveltia 0.252.0（本地 pinned bundle）含 `registerPreviewStyle`（raw 字符串/URL 两态，支持 collection 作用域）——bundle 内已核实校验逻辑
- 已有「排版」inline 编辑器组件（Insert ▸ 排版，typography-classes.js 清单 + 自建选择面板：字体实样 + 色卡）
- posts 已有 pinned/hidden 真字段 + post-visibility 单一事实源；moments 排序在 MomentsPage.astro 内联（唯一消费点）
- 自托管字体切片落 public/fonts/<family>/fonts.css（unicode-range 按需取片），路径稳定可被后台引用

### 2.2 关键假设
- 预览窗格是 CMS 内部管理的文档，官方 registerPreviewStyle 是唯一稳定注入口（MutationObserver 手注会被重渲染冲掉且升级易碎）
- 预览目标是「类效果可见」（颜色对、字体对、基础排版近似），不追求像素级还原

### 2.3 待确认问题
- [x] 预览注入走官方 registerPreviewStyle，不走 iframe hack（0.252.0 已核实存在）
- [x] 真字体预览走切片 CSS（unicode-range 按需取片），不在后台整包加载 TTF
- [x] moments 置顶多选允许（与书架/文章口径一致）；隐藏 = 真字段过滤，无 legacy tag 兼容

### 2.4 可选解释与取舍
- 提醒做成 hint 速查 + 已有排版面板的入口提示，不做常驻侧栏文档组件（Sveltia 定制面有限，hint 是官方支持的展示位）
- serif/kai/kuaile 的 CSS 经 Vite ?url 打包成哈希名，后台引不到稳定 URL，预览走字体栈系统回退（近似可见，文档注明差异）

### 2.5 已证伪路径
- 往预览 iframe 手动注入 `<style>`：预览文档由 CMS 内部管理，注入会被重渲染冲掉、升级易碎——官方 API 存在，必须走官方口子

## 3. 功能范围

### 3.1 核心功能（MVP）
- [x] T1 预览一致性：preview-style.js 从清单运行时生成排版类 CSS + 富文本基础排版（raw 注入）+ 自托管艺术字体切片 CSS（URL 注入）；pattern 放宽到多类
- [x] T2 编辑提醒：posts 正文 / moments 文字 / 关于页整页正文三处 hint 补速查；docs/管理台.md 增「预览窗格直接显色/显字体」节
- [x] T3 瞬间置顶/隐藏：schema 真字段 + 列表过滤排序 + 灰阶 pin 徽标 + 后台开关 + E2E 断言

### 3.2 扩展功能
- 无

### 3.3 不在范围内
- Sveltia bundle 升级与魔改；预览像素级还原；moments 单条页面 / RSS / sitemap 变化

## 4. 最小实现路径
- 最简可行：一个新脚本 preview-style.js + 三处既有文件小改（typography-classes 加 css 字段、typography-editor pattern 放宽、config.yml hint/开关）+ moments 三点改（schema/MomentsPage/config.yml）+ 一条置顶示例数据 + E2E 断言更新
- 暂不引入：常驻样式速查面板、预览明暗主题切换
- 不做的抽象：通用「字段级 hint 生成器」（hint 手写三处即可，量小不值得抽）

### 5.1 验证策略
- 范围级别：package
- 变更对象：后台静态资源（public/admin）与瞬间列表渲染（MomentsPage）
- 快速检查：`pnpm astro build` + `python3 scripts/build-perf/config-check.py .`
- 集成检查：E2E 59 项 + content-lint 0/0/0 + 产物 grep（moments 首卡 pin 徽标、admin 三脚本接线序）
- 全项目检查：生产部署后人工核验后台预览显色显字体；**升级条件**——仅当改动触及 BaseLayout 字体注入或 build 链时才升级全站回归，本包不涉及
- 升级触发：后台预览为独立资源面，升级为「后台人工核验」即可

## 6. 成功标准与验证方式
- [x] 后台预览排版类显色/显字体 -> verify: task_0001（manual: 生产后台人工核验，代码面由 task_0001 断言覆盖）
- [x] 编辑字段 hint 含字体/颜色速查与排版面板入口 -> verify: task_0002
- [x] moments 置顶排序 + hidden 过滤 + 后台开关 + pin 徽标 + E2E 全绿 -> verify: task_0003

## 7. 关联与风险
- 前序：5h T1（posts 置顶）、5j T3（页面文案 hint 体系）、5i T9（字体切片管线）
- 风险：registerPreviewStyle 的 URL 模式对预览文档的 base URL 解析若与预期不符，退路是把切片 CSS 也 fetch 成文本走 raw 注入（同一 URL，语义等价）
- 本包不动：热力图（另线预览选型中）