document presenter mode in readme

README.en.md

@@ -11,7 +11,7 @@
 ![Kimi work Gold Sponsor](https://img.shields.io/static/v1?label=Kimi%20work&message=Gold%20Sponsor&color=111111&style=flat-square)
 ![Cola Skill Gold Sponsor](https://img.shields.io/static/v1?label=Cola%20Skill&message=Gold%20Sponsor&color=E4353F&style=flat-square)
 
-An agent skill for Claude Code, Codex, and similar coding-agent environments. It generates **single-file HTML horizontal-swipe decks**, deck visuals, and social cover pages.
+An agent skill for Claude Code, Codex, and similar coding-agent environments. It generates **single-file HTML horizontal-swipe decks**, deck visuals, and social cover pages, with a complete rehearsal and presenter mode built in.
 
 It ships with two visual systems:
 
@@ -59,6 +59,7 @@ Other useful prompts:
 Turn this Markdown file into an editorial magazine-style presentation.
 Create a 21:9 social cover from the core idea of this deck.
 Redesign this product screenshot as a 16:10 slide visual.
+Add speaker notes and planned timing to this deck, then help me rehearse it in presenter mode.
 ```
 
 ## Sponsors and Supporters
@@ -88,6 +89,7 @@ Beyond Claude Code / Codex, you can also use Guizang PPT Skill on these platform
 - 🎨 **Curated theme presets**: 5 electronic-ink themes for Style A, 4 Swiss anchor-color themes for Style B
 - 🖼 **Optional Codex image flow**: generate documentary photos, infographics, flow diagrams, system maps, and UI scenes with GPT-Image 2.0 / GPT-M 2.0, then insert them at template-safe ratios
 - 📰 **Social covers**: generate 21:9 WeChat cover images, 1:1 share cards, 3:4 Xiaohongshu covers, video thumbnails, and related variants
+- 🎤 **Presenter mode**: dual-window audience output, 16:9 current/next previews, speaker notes, timing and rehearsal, auto advance, laser pointer, circles, and live recovery controls
 - 📴 **Low-power static mode**: press `B` to turn WebGL / canvas animation into static visuals
 - 📄 **Single HTML file** — no build, no server, open directly in the browser
 
@@ -107,12 +109,13 @@ Beyond Claude Code / Codex, you can also use Guizang PPT Skill on these platform
 | Deck visuals | In Codex, generate photos, infographics, flow diagrams, system maps, or UI scenes |
 | Social covers | Generate 21:9 main covers, 1:1 share cards, 3:4 vertical covers, and video thumbnails from the same idea |
 | Screenshot normalization | Redesign raw screenshots into template-safe ratios before inserting them into slides |
+| Live talk / rehearsal | Ask the agent to generate notes and timing, then press the bottom-right `P` to enter presenter mode |
 
 ## Why HTML decks
 
 - **Agent-native editing**: HTML / CSS is plain text, so agents can read, edit, and validate it directly.
 - **Higher visual density than Markdown**: precise layout, positioning, motion, interactivity, and cover formats.
-- **Lightweight delivery**: one HTML file can be opened, presented, sent, screenshotted, or recorded.
+- **Lightweight delivery**: one HTML file can be opened, presented, sent, screenshotted, or recorded, with presenter tools included.
 - **Better quality gates**: the Swiss validator can catch layout drift, unsafe image placement, centered body titles, and SVG text traps.
 - **One visual system across outputs**: decks, generated visuals, covers, and screenshot redesigns can share the same style rules.
 
@@ -162,6 +165,7 @@ Once installed, Claude Code auto-detects the skill. Trigger phrases:
 - "Electronic ink slides for my talk"
 - "Create a 21:9 WeChat cover from this article"
 - "Create a 1:1 share card from this deck"
+- "Add speaker notes to this deck and help me rehearse it in presenter mode"
 
 ## Workflow
 
@@ -172,12 +176,55 @@ The skill is a structured workflow; the agent walks you through each step:
 3. **Copy template** — Style A uses `assets/template.html`; Style B uses `assets/template-swiss.html`
 4. **Fill content** — create a rhythm plan, then choose and adapt the matching layout skeletons
 5. **Optional image generation** — in Codex, ask whether to use GPT-Image 2.0 / GPT-M 2.0 images, then insert them at page-appropriate ratios
-6. **Self-check** — match against `references/checklist.md`; P0 issues must all pass; Swiss decks must also pass the layout validator
+6. **Generate speaker notes** — derive each slide's purpose, talking points, transition, and planned duration from the outline; do not invent missing live details
-7. **Preview** — open the HTML in a browser
+7. **Self-check** — match against `references/checklist.md`; P0 issues must all pass; run the Swiss and presenter validators when applicable
-8. **Iterate** — use inline styles to tune font size, height, spacing
+8. **Preview** — open the HTML in a browser
+9. **Rehearse / present** — press the bottom-right `P`, verify audience sync, and record actual timing
+10. **Iterate** — adjust content, font size, height, and spacing from rehearsal results
 
 Full spec in [`SKILL.md`](./SKILL.md).
 
+## Presenter mode
+
+Both templates ship with the same presenter runtime. Open a deck and press the bottom-right `P` to enter presenter view; the browser opens a clean audience window at the same time. Core features run entirely inside the local HTML and browser—no live-caption service, cloud relay, phone remote, or AI coaching service is required.
+
+### What the speaker sees
+
+- **Current and next slides**: stacked vertically and always kept at `16:9`; small windows scale the whole slide without cropping or reflowing its text
+- **Grid navigation**: replace the preview area with an inline overview, choose a slide, then return immediately to the two previews while the audience follows
+- **Structured notes**: title, purpose, talking points, and transition are required; interaction, delivery, advance cue, fallback, and pronunciation appear only when supplied by the outline
+- **Progress and health**: current / total slide count, completion percentage, plus audience states for connecting, synced, unsynced, frozen, disconnected, or popup blocked
+
+### Timing, rehearsal, and auto advance
+
+- The footer separates elapsed, current-slide, and remaining / overtime values, with explicit “Start timer / Resume timer / Reset timer” controls
+- Rehearsal mode records actual time per slide and a local session summary; it does not grade the speaker with AI
+- Auto advance is off by default and only runs when the outline provides per-slide seconds or the user enables a global interval
+- Auto advance pauses while the grid, settings, or annotation tool is open, when the page is hidden, or when the audience is paused or out of sync
+
+### Live tools and recovery
+
+- Laser pointer, circle annotation, and clear actions sync to the audience window
+- Black screen, white screen, or freeze the audience; unfreezing catches it up to the presenter's current slide
+- Closing the audience window or losing its heartbeat produces a visible “Disconnected” state; “Reopen audience” is always available
+- Exiting presenter mode closes the audience window when allowed, or leaves a clear “Presentation ended” fallback
+- Preflight checks cover popups, fullscreen, fonts, images / video, and `16:9` previews, while reminding the speaker to verify HDMI adapters and projectors manually
+
+Common shortcuts: `← / →` navigate, `Home / End` jump to first or last, `G` opens the grid, `L` laser, `C` circle, `B / W` black or white screen, `F` freezes the audience, and `?` opens the full shortcut list.
+
+Ask an agent to prepare presenter mode with:
+
+```text
+Use this outline to add a purpose, talking points, transition, and planned duration to every slide. Do not invent interaction or live details that were not provided, then run the presenter-mode validator.
+```
+
+See [`references/presenter-mode.md`](./references/presenter-mode.md) for the full notes contract and runtime behavior. Validate with:
+
+```bash
+node scripts/validate-presenter-mode.mjs path/to/index.html
+node scripts/validate-presenter-mode.mjs path/to/index.html --target-minutes 30
+```
+
 ## Style B Swiss
 
 The Swiss theme is a strict layout system, not just a CSS skin.
@@ -258,7 +305,9 @@ guizang-ppt-skill/
 │   ├── template-swiss.html   ← Style B Swiss template
 │   └── screenshot-backgrounds/ ← bundled WebP screenshot backgrounds: 5 style-a / 4 style-b
 ├── scripts/
-│   └── validate-swiss-deck.mjs ← Swiss layout validator
+│   ├── validate-swiss-deck.mjs ← Swiss layout validator
+│   ├── validate-presenter-mode.mjs ← speaker notes, timing, and runtime validator
+│   └── check-presenter-runtime-sync.mjs ← cross-template presenter runtime drift check
 └── references/
     ├── components.md     ← component catalog (type, color, grid, icons, callout, stat, pipeline)
     ├── layouts.md        ← 10 layout skeletons (paste-ready)
@@ -268,6 +317,7 @@ guizang-ppt-skill/
     ├── themes-swiss.md   ← 4 Swiss anchor-color themes
     ├── image-prompts.md  ← GPT-Image 2.0 / GPT-M 2.0 image types, ratios, and base prompts
     ├── screenshot-framing.md ← CleanShot X-style screenshot framing semantics
+    ├── presenter-mode.md ← notes contract, rehearsal, audience output, and live tools
     └── checklist.md      ← quality checklist (P0 / P1 / P2 / P3 tiers)
 ```
 
@@ -341,6 +391,12 @@ Yes. Style A layouts can be extended in `references/layouts.md`. Style B is stri
 **Is Codex image generation required?**
 No. Decks work without generated images. The image flow is only used when you need photos, infographics, UI scenes, or covers.
 
+**Does presenter mode require internet access or another service?**
+No. Dual-window sync, notes, timing, rehearsal, auto advance, and annotations run locally in the browser. It does not provide live captions, phone control, or AI rehearsal scoring.
+
+**Why does closing the audience window show “Disconnected”?**
+The presenter uses acknowledgements and heartbeats to verify the software link. Closing the window or losing its heartbeat produces “Disconnected”; use “Reopen audience” to recover. The browser cannot verify a physical HDMI or projector cable, so the speaker still needs a visual check.
+
 **How do I update the skill?**
 Run the install command again, or run `git pull` inside your local skill directory.
 
@@ -351,6 +407,8 @@ Bugs, layout issues, new layout requests — Issues and PRs welcome. Prioritize:
 - Add new classes to `template.html` first; don't let `layouts.md` reference undefined classes
 - When changing `template-swiss.html`, update `layouts-swiss.md` and `swiss-layout-lock.md` together
 - When adding Swiss rules, update `scripts/validate-swiss-deck.mjs`
+- Presenter runtime changes must land in both templates and pass `scripts/check-presenter-runtime-sync.mjs`; CI rejects CSS / JavaScript drift
+- Presenter-note or live-behavior changes must also update `references/presenter-mode.md`, `references/checklist.md`, and `scripts/validate-presenter-mode.mjs`
 - Log pitfalls into `checklist.md` at the matching P0 / P1 / P2 / P3 tier
 - New theme colors go into `themes.md` with a recommended use case
 

README.md

@@ -13,7 +13,7 @@
 
 > 🌏 **English version: [README.en.md](./README.en.md)**
 
-一个适配 Claude Code / Codex 等 Agent 环境的网页 PPT 技能,用于生成**单文件 HTML 横向翻页 PPT**、PPT 配图和多平台封面。
+一个适配 Claude Code / Codex 等 Agent 环境的网页 PPT 技能,用于生成**单文件 HTML 横向翻页 PPT**、PPT 配图和多平台封面,并内置完整的排练与演讲者模式。
 
 内置两套视觉系统:
 
@@ -61,6 +61,7 @@ npx skills add https://github.com/op7418/guizang-ppt-skill --skill guizang-ppt-s
 帮我把这份 Markdown 做成杂志风演讲 PPT。
 基于这份 PPT 的核心观点,生成一张公众号 21:9 头图。
 把这张产品截图重新设计成适合 PPT 的 16:10 配图。
+给这份 PPT 补齐演讲备注和每页计划时长,然后用演讲者模式帮我排练。
 ```
 
 ## 赞助与支持
@@ -90,6 +91,7 @@ Guizang PPT Skill 的持续迭代获得 **360 安全龙虾**、**Kimi work**、*
 - 🎨 **主题色预设**:Style A 5 套电子墨水主题,Style B 4 套瑞士高饱和锚点色
 - 🖼 **Codex 可选配图流程**:可用 GPT-Image 2.0 / GPT-M 2.0 生成纪实照片、信息图、流程图、系统关系图、UI 情景图,并按模板比例插入
 - 📰 **多平台封面**:可用同一套视觉规则生成公众号 21:9、公众号分享卡 1:1、小红书 3:4、视频号横版等封面
+- 🎤 **演讲者模式**:双窗口观众屏、当前页/下一页 16:9 预览、演讲备注、计时排练、自动翻页、激光笔、圈选和现场故障恢复
 - 📴 **低性能静态模式**:按 `B` 可关闭 WebGL / canvas 动画,让动态内容退回静态背景
 - 📄 **单文件 HTML**:不需要构建、不需要服务器,浏览器直接打开
 
@@ -109,12 +111,13 @@ Guizang PPT Skill 的持续迭代获得 **360 安全龙虾**、**Kimi work**、*
 | PPT 配图 | 在 Codex 中用 GPT-Image 2.0 / GPT-M 2.0 生成照片、信息图、流程图、UI 情景图 |
 | 多平台封面 | 从同一份内容生成公众号 21:9、1:1 分享卡、小红书 3:4、视频号横版封面 |
 | 截图统一风格 | 把原始截图重新生成到模板需要的比例,再插入 PPT |
+| 现场演讲 / 排练 | 让 Agent 从大纲生成备注和时长,按右下角 `P` 进入演讲者模式 |
 
 ## 为什么是 HTML PPT
 
 - **更适合 Agent 生成和修改**:HTML / CSS 是文本,Agent 能直接读、改、验证。
 - **表现力比 Markdown 更高**:可以做精细排版、空间定位、动画、交互和响应式封面。
-- **交付更轻**:单文件 HTML 可以直接打开、演示、发送、截图。
+- **交付更轻**:单文件 HTML 可以直接打开、演示、发送、截图,演讲者工具也随文件一起交付。
 - **更容易做质量控制**:瑞士风可以用脚本校验版式、图片槽位、标题对齐、危险 SVG,并在可用时用 Playwright 后验测量超出、底部空白、nav 安全线和标题间距。
 - **更适合视觉内容链路**:同一套主题能覆盖 PPT、配图、封面和截图再设计。
 
@@ -164,6 +167,7 @@ git clone https://github.com/op7418/guizang-ppt-skill.git ~/.claude/skills/guiza
 - "electronic ink 风格演讲 slides"
 - "基于这篇文章做一张公众号 21:9 封面"
 - "基于这份 PPT 生成一张 1:1 分享卡"
+- "给这份 PPT 补齐演讲备注,并用演讲者模式帮我排练"
 
 ## 使用流程
 
@@ -174,12 +178,55 @@ Skill 本身是结构化工作流,Agent 会逐步引导:
 3. **拷贝模板** — Style A 用 `assets/template.html`,Style B 用 `assets/template-swiss.html`
 4. **填充内容** — 先做主题节奏表,再从对应 layout 骨架里挑、粘、改文案
 5. **可选配图** — 在 Codex 中询问是否用 GPT-Image 2.0 / GPT-M 2.0 生成配图,再按页面比例插入
-6. **自检** — 对照 `references/checklist.md`,P0 级问题必须全过；瑞士风还要运行版式校验器
+6. **生成演讲备注** — 从大纲提取每页目的、讲述要点、转场和计划时长；用户没提供的信息不猜测
-7. **预览** — 浏览器直接打开
+7. **自检** — 对照 `references/checklist.md`,P0 级问题必须全过；瑞士风和演讲模式分别运行对应校验器
-8. **迭代** — inline style 改字号/高度/间距
+8. **预览** — 浏览器直接打开
+9. **排练 / 演讲** — 按右下角 `P` 进入演讲者模式,检查观众屏同步并记录实际时长
+10. **迭代** — 根据排练结果调整内容、字号、高度和间距
 
 详细说明见 [`SKILL.md`](./SKILL.md)。
 
+## 演讲者模式
+
+两套模板都内置同一套演讲者运行时。打开 deck 后,点击右下角 `P` 即可进入演讲者视图；浏览器会同时打开一个干净的观众屏。所有核心能力都在本地 HTML 和浏览器里完成,不依赖实时字幕、云端中继、手机遥控或 AI 教练服务。
+
+### 演讲时能看到什么
+
+- **当前页与下一页**:上下排列并始终保持 `16:9`,小屏时整页等比缩放,不裁切、不挤压文字
+- **宫格选页**:在预览区原位切换总览,点选页面后立即回到双预览,观众屏同步跟随
+- **结构化备注**:标题、本页目的、讲述要点和转场必填；互动、语气、翻页时机、备用方案和读音等信息只在大纲提供时显示
+- **进度与状态**:显示当前页 / 总页数、完成百分比,以及观众屏的连接中、已同步、未同步、已冻结、未连接或弹窗被拦截状态
+
+### 时间、排练与自动翻页
+
+- 底栏分别显示已进行、本页和剩余 / 超时时间,按钮明确区分“开始计时 / 继续计时 / 重置计时”
+- 排练模式记录每页实际时长和整场汇总,数据保存在本地浏览器,不会做 AI 评分
+- 自动翻页默认关闭；只有大纲明确给出页面停留秒数,或用户在设置中开启全局间隔时才启用
+- 打开宫格、设置、圈选工具,页面隐藏,或观众屏暂停 / 失去同步时,自动翻页会暂停
+
+### 现场工具与故障恢复
+
+- 激光笔、圈选和清除会同步到观众屏
+- 一键黑屏、白屏,或冻结观众屏；恢复后自动追平演讲者当前页
+- 观众窗口关闭或心跳超时后明确显示“未连接”,可随时点击“重新打开观众屏”
+- 退出演讲时自动关闭观众窗口；浏览器不允许自关时,观众端显示“演示已结束”
+- 演前检查覆盖弹窗、全屏、字体、图片 / 视频和 `16:9` 预览,并提醒人工确认 HDMI、转接器和投影仪
+
+常用快捷键：`← / →` 翻页,`Home / End` 跳首页或尾页,`G` 宫格,`L` 激光笔,`C` 圈选,`B / W` 黑屏或白屏,`F` 冻结观众屏,`?` 查看完整快捷键。
+
+让 Agent 生成或补齐演讲模式时,可以直接说：
+
+```text
+根据这份大纲给每一页补齐演讲目的、讲述要点、转场和计划时长。没有提供的互动或现场信息不要猜,然后运行演讲模式校验器。
+```
+
+演讲备注契约和完整行为说明见 [`references/presenter-mode.md`](./references/presenter-mode.md)。校验命令：
+
+```bash
+node scripts/validate-presenter-mode.mjs path/to/index.html
+node scripts/validate-presenter-mode.mjs path/to/index.html --target-minutes 30
+```
+
 ## Style B 瑞士风
 
 瑞士风是这次新增的结构化主题。它不是"换一套 CSS",而是一套更严格的版式系统。
@@ -259,7 +306,9 @@ guizang-ppt-skill/
 │   ├── template-swiss.html   ← Style B 瑞士国际主义模板
 │   └── screenshot-backgrounds/ ← 截图美化内置背景(WebP):style-a 5 套 / style-b 4 套
 ├── scripts/
-│   └── validate-swiss-deck.mjs ← 瑞士风版式校验器
+│   ├── validate-swiss-deck.mjs ← 瑞士风版式校验器
+│   ├── validate-presenter-mode.mjs ← 演讲备注、时长和运行时校验器
+│   └── check-presenter-runtime-sync.mjs ← 两套模板演讲者运行时防漂移检查
 └── references/
     ├── components.md     ← 组件手册(字体、色、网格、图标、callout、stat、pipeline)
     ├── layouts.md        ← 10 种页面布局骨架(可直接粘贴)
@@ -269,6 +318,7 @@ guizang-ppt-skill/
     ├── themes-swiss.md   ← 4 套瑞士风锚点色
     ├── image-prompts.md  ← GPT-Image 2.0 / GPT-M 2.0 配图类型、比例和基础提示词
     ├── screenshot-framing.md ← CleanShot X 式截图适配语义
+    ├── presenter-mode.md ← 演讲备注契约、排练、观众屏与现场工具说明
     └── checklist.md      ← 质量检查清单(P0 / P1 / P2 / P3 分级)
 ```
 
@@ -342,6 +392,12 @@ guizang-ppt-skill/
 **Codex 配图是必须的吗?**
 不是。没有配图也能生成 PPT。配图流程只在需要照片、信息图、UI 情景图或封面时使用。
 
+**演讲者模式需要联网或额外服务吗?**
+不需要。双窗口同步、备注、计时、排练、自动翻页和标注都在本地浏览器完成。它不会提供实时字幕、手机遥控或 AI 排练评分。
+
+**为什么关掉观众窗口后显示“未连接”?**
+演讲者端会通过观众屏确认和心跳判断软件链路。窗口关闭或心跳超时会显示“未连接”,点击“重新打开观众屏”即可恢复。浏览器无法判断 HDMI 或投影仪线缆是否真的接通,现场仍需目视确认。
+
 **怎么更新到最新版?**
 重新运行安装命令,或在本地 skill 目录执行 `git pull`。
 
@@ -352,6 +408,8 @@ Bug、排版问题、新布局需求——欢迎开 Issue 或 PR。改动请优
 - 在 `template.html` 里补类,不要让 layouts.md 使用未定义的类
 - 在 `template-swiss.html` 里补类时,同步更新 `layouts-swiss.md` 和 `swiss-layout-lock.md`
 - 瑞士风新增规则后,同步更新 `scripts/validate-swiss-deck.mjs`
+- 演讲者运行时必须同时更新两套模板,并运行 `scripts/check-presenter-runtime-sync.mjs`；CI 会拦截两份模板的 CSS / JavaScript 漂移
+- 演讲备注或现场行为变化时,同步更新 `references/presenter-mode.md`、`references/checklist.md` 和 `scripts/validate-presenter-mode.mjs`
 - 把踩过的坑写到 `checklist.md` 对应的 P0 / P1 / P2 / P3 级别
 - 新主题色进 `themes.md` 并给出适合的场景