---
name: html-speaker-mode
description: 创建或升级可自然语言逐页修改的动态 HTML 演示课件，提供页面拖拽排序、自动编号、可拖拽编辑布局、当前页与下一页预览、备注、分步动效和纯演示模式。适用于培训、演讲、路演和已有 HTML 课件改造；不是通用网站构建器，不转换原生 PPTX 或 Keynote。
---

# HTML 动态演示工作台 · v2.2

**固定操作架构，不固定视觉创意。** 每页由论点决定构图、动画、图表或交互；不复制示例内容，不要求所有页面套同一个模板。已有材料优先保留用户认可的配色和设计。

## 工作流程

1. **梳理**：接收自然语言、口述或素材，整理讲述主线和页面大纲。新课件先确认大纲；已有明确修改要求则直接实施，不重复确认。
2. **制作**：每页一个核心观点，稳定 ID、短标题、可选讲稿。解释放备注，画面尽量可视化。每页可以独立设计和迭代。
3. **修改**：用“课件 + 当前页码 + 标题/稳定 ID”定位。只修改授权页面和必要公共代码；插页不重建其他页，不修改稳定 ID。
4. **预览与交付**：复用当前浏览器标签；以修改页供用户检查。内容完成后交付 HTML + 相对路径本地资源文件夹。浏览器中的排序/备注需按下文处理，不能误称已写入源文件。部署须单独授权。

## 必须保留的能力

- **编辑模式（默认）**：左侧页目录，中间大幅当前页，下方小幅下一页与备注；没有计时器。三条分隔线可拖动，支持键盘微调、双击复位、重置布局；布局按课件保存在本机。
- **页面排序**：拖拽目录，或 Alt + ↑/↓ 移动当前目录项；自动重新编号，当前页、备注和动效状态由稳定 ID 绑定。提供撤销和排序 JSON 导出。
- **单屏演讲**：F / 单屏演讲，适合镜像投影。只显示当前页，隐藏全部编辑栏、备注、导航、下一页、帮助和计时，并在用户点击或按键手势内请求浏览器原生全屏。Esc 返回同页同动效状态。如宿主拒绝 Fullscreen API，仍保持干净演示并给出原生全屏快捷键提示。
- **逐步讲述**：下一步先推进本页有意义的动效，完成后翻页；上一步反向恢复。静态页一键翻页。不要把每个装饰动画都变成一次点击。
- **无缝切页**：当每页通过 iframe 独立渲染时，使用双缓冲。新页在当前页下方准备，收到 ready / hydrated 后直接替换；加载期间保留当前页，不显示黑屏、空白页或默认首页。观众屏能在同一文档内切页时，不要为每次导航整页重载。
- **翻页笔兼容**：→、↓、PageDown、空格、Enter；反向 ←、↑、PageUp、Backspace。忽略重复按键；输入框、滑块、分隔线保留自己的键盘操作。B/W 临时黑/白屏。
- **鼠标/触控推进**：单击当前页面的非交互空白区域，执行与“下一步”相同的逻辑——先推进本页动效，完成后翻页。按钮、链接、输入框、视频、音频、二维码、弹窗、滑块和显式标记 `data-no-advance` / `data-speaker-interactive` 的区域保留原操作，不误翻页；选中文本或有对话框打开时不推进。
- **媒体稳定性**：非当前页图片使用延迟加载与异步解码，视频默认不预载；只有用户主动播放时才请求媒体，避免翻页过程抢占主线程和网络。
- **备注**：每页独立本地保存，不显示在演示画面和观众消息中。源 HTML 内备注仍可被拿到文件的人读取，视觉隐藏不是保密。
- **双屏演讲**：只在用户主动点击时打开独立观众窗，观众窗放到投影屏，本机编辑屏保留目录、下一页和备注。同步页序、页面和已支持动效。观众窗要请求原生全屏；由于 Safari 等浏览器不允许父窗口替新窗口静默授权全屏，必须提供醒目的“进入观众屏全屏”二次点击退路。不能把可见控制区称为私密。

## 实施路线

### Pointer readiness invariant

The editor must not drop a mouse-advance action while the current preview iframe is loading. Record the build/navigation action first; if the frame is not ready, replay the queued action when the frame reports ready or hydrated. This keeps mouse clicks, keyboard navigation, and a remote clicker on the same state machine.

### 新建材料

用本技能目录中的脚本初始化（不覆盖已有目录）：

```sh
python3 scripts/create_deck.py /absolute/path/my-talk --title '我的演讲'
```

脚本复制控制器资源、创建独立 `deckId`，生成三页中性样例。随后替换内容并自由设计各页，不把示例当版式规定。交付不需要 npm、后端或 API 密钥。

### 改造现有材料

先读 [references/integration.md](references/integration.md)，核对真实 DOM、渲染器、现有动画、文件权威副本及已授权镜像。资源加载顺序：`slide-order.js` → `editor-layout.js` → `speaker-mode.js`；两个 CSS 放在相同目录。控制器以 Shadow DOM 隔离，预览直接运行原文档 iframe，不重画原稿。

配置独立 `deckId` 与每页稳定 `data-speaker-id`。严格校验 ID 唯一；记录物理源序与用户排序的映射。不要为了排序破坏原生脚本的索引假设。

## 状态和交付边界

浏览器排序、布局、备注是 localStorage；当前演示进度是 sessionStorage。**不自动写回源文件，不自动跨设备同步。** 改端口、换浏览器、清缓存后可能不可见。

用户确认顺序后，读取导出的排序 JSON，按稳定 ID 调整源文件及相关索引；备注需显式提取备份后写回。若需单文件 HTML，再内联本地控制器/素材，单独验证；默认输出可离线携带的资源文件夹，不承诺已内联。远程嵌入/视频/3D 的联网依赖须说明并准备退路。

## 验收

用本地 HTTP 服务进行真实浏览器验证，不只检查隐藏源 DOM：

1. 页数、当前页、下一页、首尾定位；无重复 ID。
2. 拖拽排序后重编号，刷新顺序保留；选中页与备注不串页；撤销正常。
3. 三条布局分隔线、键盘微调、刷新保留、重置；主画面足够大。
4. 单屏演讲能在用户手势内请求原生全屏，F/Esc 干净切换与位置保留；导航/备注/分隔线不泄露到画面；连续前后翻页不闪黑、不闪首页。
5. 翻页键推进/回退动效，完成后翻页；输入备注时不翻页。
6. 鼠标单击页面空白处推进动效/翻页；点击按钮、链接、视频、二维码或弹窗不会误翻页；下一页只读预览不能触发推进。
7. 原始交互、素材、链接；常用屏幕及窄窗口不溢出；减少动态效果偏好。
8. 如交付双屏，验证观众窗的全屏入口、同步与退出，并关闭测试窗口；不将软件握手当真实投影验证。

报告实测范围，区分键盘模拟与物理翻页笔。学生包只包含通用代码、说明、中性样例，不带私有课件、头像、二维码、聊天截图、商业数据或凭据。面向学生的安装与使用见 [使用说明.md](使用说明.md)。