04-generator-contract

幻灯片生成器契约

article-slide-video 默认使用 frontend-slides 生成 HTML 幻灯片，但系统设计上不绑定它。生成器只要满足同一份视频渲染契约，就可以替换。

为什么要有生成器契约

不同 HTML 幻灯片工具的内部实现差异很大：

• DOM 结构不同。
• CSS class 不同。
• 切页方式不同。
• 是否有路由不同。
• 动画、图片加载、字体加载策略不同。

如果视频交付脚本直接依赖 .slide、.active、某个控制条或特定路由，后续就很难替换生成器。当前设计把这些差异封装在 HTML 自己内部，下游只调用统一接口。

生成器必须输出什么

生成器至少输出两个文件：

• deck.html
• deck-manifest.json

并且 deck.html 必须暴露：

window.__SLIDE_VIDEO__ = {
  async showSlide(slideId) {
    // 切换到指定页面，并关闭控制条、编辑态和动画。
  },
  async ready(slideId) {
    // 等待字体、当前页面图片、异步数据和布局稳定。
  },
};

ready(slideId) 是可选方法，但强烈建议实现。视频渲染器会设置 30 秒超时，避免被隐藏页面的懒加载资源拖死。

浏览器桥接负责什么

showSlide(slideId) 负责把浏览器切到指定页面，并让页面进入适合截图的静态状态：

• 找到对应 slide_id 的页面。
• 只显示目标页面。
• 关闭动画和 transition。
• 隐藏控制条、编辑按钮、热区等非视频元素。
• 把当前页面图片改为 eager 加载。

ready(slideId) 负责等待截图前的稳定条件：

• 字体加载完成。
• 当前页面图片加载完成或失败返回。
• 异步数据和布局稳定。
• 不等待隐藏页面的资源。

这样视频渲染器只关心：“给我 slide-03 的最终画面”。至于页面内部怎么切换，由生成器自己处理。

deck-manifest.json 的安全边界

deck-manifest.json 的 entry 只能是相对路径，而且解析软链接后仍必须留在 manifest 所在目录内。

这个限制有两个目的：

• 防止渲染器意外读取输出目录外的文件。
• 让交付包天然自包含，便于移动、复现和归档。

frontend-slides 如何适配

frontend-slides 在普通幻灯片能力之外，额外支持视频渲染契约：

• 保持单文件 HTML 输出。
• 使用固定 1920×1080 舞台。
• 每页带 data-slide-id。
• deck-manifest.json 复用 narration-plan.json 中的 slide_id。
• HTML 内部实现 window.__SLIDE_VIDEO__。

它可以继续使用自己的 .slide、.active、编辑控件和导航逻辑，但这些都属于生成器内部细节。视频交付脚本不能依赖这些细节。

替换为其他生成器的条件

其他生成器接入时需要满足：

• 能读取 narration-plan.json。
• 能保留原始 slide_id。
• 能输出合法 deck-manifest.json。
• HTML 能通过 showSlide(slideId) 切到指定页面。
• HTML 能通过 ready(slideId) 或等效逻辑等待渲染稳定。
• 输出文件位于统一输出目录内。

只要这些条件满足，article-slide-video 的第 4 步可以替换生成器，而第 5 步之后不需要变化。