Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

refactor(ppt): redesign live preview lifecycle and unify naming

hugohe38a979fbf1d10
diff --git a/AGENTS.md b/AGENTS.md
index 828d92b0..59be8aa4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -20,7 +20,7 @@ PPT Master is an AI-driven presentation generation system. Multi-role collaborat
>
> Object-level animation tuning: when the user asks to change animation order, effect, timing, or a specific object's reveal behavior, run the standalone [`customize-animations`](skills/ppt-master/workflows/customize-animations.md) workflow. Default export already has global animations; do not create `animations.json` unless customization was requested.
>
-> Finished-deck re-entry: the main pipeline starts the live preview during Executor. If the deck has been exported, the editor was closed, and the user later wants another visual edit pass, run [`visual-edit`](skills/ppt-master/workflows/visual-edit.md) to reopen the editor, apply annotations, re-export, and reopen again.
+> Live preview: any time the user mentions "live preview", "preview", "看效果", or wants to click/select a slide element, run [`live-preview`](skills/ppt-master/workflows/live-preview.md). Step 6 auto-starts it during generation; the workflow covers post-export re-entry and applying submitted annotations.
## Execution Requirements
diff --git a/CLAUDE.md b/CLAUDE.md
index 2e5209c7..ab3609f0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,7 +20,7 @@ PPT Master is an AI-driven presentation generation system. Multi-role collaborat
>
> Object-level animation tuning: when the user asks to change animation order, effect, timing, or a specific object's reveal behavior, run the standalone [`customize-animations`](skills/ppt-master/workflows/customize-animations.md) workflow. Default export already has global animations; do not create `animations.json` unless customization was requested.
>
-> Live preview / visual edit: any time the user mentions "live preview", "preview", "看效果", "visual edit", or wants to click/select a slide element, run [`live-preview`](skills/ppt-master/workflows/live-preview.md). Works for both mid-generation preview (`--live`) and post-export re-entry — one unified workflow.
+> Live preview: any time the user mentions "live preview", "preview", "看效果", or wants to click/select a slide element, run [`live-preview`](skills/ppt-master/workflows/live-preview.md). Step 6 auto-starts it during generation; the workflow covers post-export re-entry and applying submitted annotations.
## Execution Requirements
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index d870cf5d..229efb06 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -77,7 +77,7 @@ For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.
| `resume-execute` | `workflows/resume-execute.md` | Phase B entry — resume execution in a fresh chat after Phase A (Step 1–5) completed in another session (split mode) |
| `verify-charts` | `workflows/verify-charts.md` | Chart coordinate calibration — run after SVG generation if the deck contains data charts |
| `customize-animations` | `workflows/customize-animations.md` | Object-level PPTX animation customization — run only when the user explicitly asks to tune animation order/effects/timing |
-| `live-preview` | `workflows/live-preview.md` | Browser-based SVG editor — auto-started during generation and re-enterable any time the user mentions "live preview", "preview", "visual edit", or wants to click/select a slide element |
+| `live-preview` | `workflows/live-preview.md` | Browser-based live preview — auto-started during generation and re-enterable any time the user mentions "live preview", "preview", "看效果", or wants to click/select a slide element |
---
@@ -289,18 +289,15 @@ Read references/executor-consultant-top.md # Top consulting style (MBB level)
**Design Parameter Confirmation (Mandatory)**: before the first SVG, output key design parameters from the spec (canvas dimensions, color scheme, font plan, body font size). See executor-base.md §2.
-**Live Preview Auto-Startup (Mandatory)**: before the first SVG, automatically start the browser editor in live mode and keep it running through Executor + Export:
+**Live Preview Auto-Startup (Mandatory)**: before the first SVG, automatically start the browser editor in live mode and keep it running continuously through Executor + Step 7 export:
```bash
python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live
```
-- This uses the unified [`live-preview`](workflows/live-preview.md) workflow in `--live` mode.
-- Start it immediately when Executor begins; `svg_output/` may be empty.
-- Run it as a long-running side process/session; do not wait for the server process to exit before generating SVG pages.
-- The editor opens `http://localhost:5050` by default and polls for new SVG pages in live mode.
-- **Add annotation** creates a local annotation; **Submit annotations** writes annotations to disk and keeps the service running; **Exit preview** is the only UI action that stops Flask.
-- If the user clicks **Exit preview**, generation should continue without preview unless the user asks to reopen it.
-- If port `5050` is occupied, pass `--port <other>` and report the actual URL.
-- Do not wait for user confirmation after startup; continue the serial Executor pipeline.
+- Start it immediately when Executor begins; `svg_output/` may be empty. Editor opens at `http://localhost:5050`; port conflict → `--port <other>` and report the actual URL.
+- Run it as a long-running side process/session; do not wait for it to exit before generating SVG pages. Do not wait for user confirmation after startup.
+- **Service must keep running** until one of: (a) the user clicks **Exit preview** in the browser, or (b) the user explicitly asks in chat to stop it. Generation continues even if the user closes the editor.
+- **Do NOT read or apply submitted annotations during generation.** Users may annotate at any time, but Executor proceeds without touching them. The window to apply annotations opens only after Step 7 completes — see [`workflows/live-preview.md`](workflows/live-preview.md).
+- UI button semantics and editor details: see [`workflows/live-preview.md`](workflows/live-preview.md) Notes.
**Pre-generation Batch Read (Mandatory)**: before the first SVG, batch-read every distinct layout SVG referenced in `spec_lock.page_layouts` and every distinct chart SVG referenced in `spec_lock.page_charts` (plus any §VII backup charts). One read per file, up front — do not re-read these during page generation. See executor-base.md §1.0.
@@ -319,13 +316,6 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>
- `warning` entries (low-res image, non-PPT-safe font tail, etc.): fix when straightforward, otherwise acknowledge and release.
- Run against `svg_output/` (not after `finalize_svg.py` — finalize rewrites SVG and masks violations).
-**Live Annotation Handling (Mandatory)** — after quality check passes, before speaker notes:
-```bash
-python3 ${SKILL_DIR}/scripts/check_annotations.py <project_path>
-```
-- If no annotations found: continue to Logic Construction Phase.
-- If annotations found: apply each change to the targeted SVG elements (read `data-edit-annotation`, edit in place, remove `data-edit-target` / `data-edit-annotation`), then re-run `svg_quality_checker.py`. Do not proceed past a touched page with quality-check `error`s.
-
**Logic Construction Phase**: generate speaker notes → `<project_path>/notes/total.md`
**✅ Checkpoint — Confirm all SVGs and notes are fully generated and quality-checked. Proceed directly to Step 7 post-processing**:
@@ -334,7 +324,6 @@ python3 ${SKILL_DIR}/scripts/check_annotations.py <project_path>
- [x] Live preview started and kept available at the reported URL
- [x] All SVGs generated to svg_output/
- [x] svg_quality_checker.py passed (0 errors)
-- [x] Submitted live annotations checked/applied or confirmed absent
- [x] Speaker notes generated at notes/total.md
```
@@ -405,7 +394,9 @@ Full effect list, anchor logic, and limits: [`references/animations.md`](referen
> ❌ **NEVER** force `-s output` for the legacy/preview pptx (PowerPoint's internal SVG parser drops icons and rounded corners). The default auto-split already gives native the high-fidelity source it needs without touching legacy.
> ❌ **NEVER** use `--only` (it suppresses one of the two output files)
-> Finished-deck re-entry: any time the user mentions "live preview", "preview", "visual edit", "看效果", or wants to select/click a slide element, run [`live-preview`](workflows/live-preview.md). It handles both mid-generation preview (`--live`) and post-export re-entry in one unified workflow.
+> **Post-export annotation window**: the preview service from Step 6 typically remains running after export. If the user submitted annotations in the browser (during Executor or after export) and now asks to apply them — they may quote the browser prompt (`Annotations saved. ... apply my annotations`), say "apply my annotations" / "应用注解" / equivalent — run [`live-preview`](workflows/live-preview.md) Step 2 to apply and re-export. Annotations submitted during generation are also handled here, not earlier.
+
+> **Preview not running?** Any time the user mentions "live preview", "preview", "看效果", or wants to select/click a slide element and the service is not running, run [`live-preview`](workflows/live-preview.md) Step 1 to start it. If the service is already running, just point them at the URL — do not restart.
---
diff --git a/skills/ppt-master/scripts/svg_editor/server.py b/skills/ppt-master/scripts/svg_editor/server.py
index 0787dc89..acc9b068 100644
--- a/skills/ppt-master/scripts/svg_editor/server.py
+++ b/skills/ppt-master/scripts/svg_editor/server.py
@@ -409,7 +409,7 @@ def main(argv: Optional[list[str]] = None) -> int:
if not args.no_browser:
webbrowser.open(url)
- mode = "live preview" if args.live else "visual edit"
+ mode = "live preview (auto-startup)" if args.live else "live preview"
print(f"SVG Editor running at {url} ({mode})")
print(f"Project: {project_path}")
app.run(host='127.0.0.1', port=args.port, debug=False)
diff --git a/skills/ppt-master/scripts/svg_editor/static/app.js b/skills/ppt-master/scripts/svg_editor/static/app.js
index c0102e78..f28ea26f 100644
--- a/skills/ppt-master/scripts/svg_editor/static/app.js
+++ b/skills/ppt-master/scripts/svg_editor/static/app.js
@@ -583,8 +583,8 @@
// ================================================================
// 10. Save all -- two-step: confirm then save
// ================================================================
- var CONFIRM_MSG = "Submit annotations to disk?\n\nThe preview service will stay open. Use Exit preview when you want to stop it.";
- var SUCCESS_MSG = "Annotations submitted.\n\nReturn to the chat and tell the AI you're ready — it will apply your edits. The preview service is still running.";
+ var CONFIRM_MSG = "Submit annotations to disk?\n\nThe preview service will keep running. Click Exit preview when you want to stop it.";
+ var SUCCESS_MSG = "Annotations saved.\n\nReturn to the chat and tell the AI to apply them (e.g. \"apply my annotations\"). The preview service is still running.";
var EXIT_CONFIRM_MSG = "Exit preview and stop the local server?\n\nUnsaved annotations will be discarded.";
var EXIT_SUCCESS_MSG = "Preview stopped.\n\nYou can close this tab and return to the chat.";
@@ -706,11 +706,7 @@
.then(function (res) { return res.json(); })
.then(function (data) {
liveMode = !!data.live;
- if (liveMode) {
- document.title = "PPT Master - Live Preview";
- } else {
- document.title = "PPT Master - Visual Editor";
- }
+ document.title = "PPT Master - Live Preview";
btnSave.textContent = "Submit annotations";
})
.catch(function () {
diff --git a/skills/ppt-master/workflows/live-preview.md b/skills/ppt-master/workflows/live-preview.md
index c09a7f8b..d8ee9715 100644
--- a/skills/ppt-master/workflows/live-preview.md
+++ b/skills/ppt-master/workflows/live-preview.md
@@ -1,96 +1,97 @@
---
-description: Start or reopen the browser-based live preview editor; AI applies submitted annotations, re-exports, and loops until the user is done
+description: Start the browser SVG editor when it is not running, and apply submitted annotations after Step 7 export
---
# Live Preview Workflow
-> Unified entry point for the browser-based SVG editor. Run this workflow any time the user mentions "live preview", "preview", "看一下效果", "visual edit", "改一下某个元素", or similar — whether the deck is mid-generation or already exported.
-
-This workflow is **independent**: it operates on `<project_path>/svg_output/`, applies submitted annotations, and re-runs the same post-processing scripts the main pipeline uses. Safe to invoke at any stage as long as `svg_output/` contains at least one SVG file.
+> **Purpose**: (1) start/reopen the browser SVG editor when no preview service is currently running, and (2) apply user-submitted annotations after Step 7 export completes.
+>
+> **Not in scope**: Executor's mandatory auto-startup — that lives in [`SKILL.md`](../SKILL.md) Step 6. Do not re-launch a preview that is already running.
## When to Run
-- **During Executor**: automatically, right after quality check passes — the main pipeline launches this via `--live` mode so the user can preview slides as they're generated.
-- **Finished-deck re-entry**: the deck has been exported at least once (Steps 1–7 complete), or the editor was closed after generation, and the user wants to refine specific visual elements.
-- Trigger phrases (any of these): "live preview", "preview", "看效果", "visual edit", "改一下", "打开编辑器", "看一下", "能不能看看", or the user describes clicking/selecting a slide element.
+- **Start (Step 1)** — preview service is not currently running and the user wants to look at the deck or click an element. Typical cases: post-export re-entry in a fresh chat, or the user clicked **Exit preview** earlier and now wants it back.
+- **Apply annotations (Step 2)** — Step 7 has produced at least one PPTX, and the user signals that submitted annotations should now be applied. Triggers include:
+ - quoting the browser prompt (`Annotations saved. ... apply my annotations ...`)
+ - saying `apply my annotations` / `apply my edits` / `应用注解` / `开始应用` / 等价表达
## When NOT to Run
-- The user gave a precise edit you can apply right now ("change page 3 title font-size to 32") — just edit the SVG directly.
-- The user wants a full regeneration ("redo this slide", "换个风格") — use the main workflow.
-- Truly headless with no port-forwarding option: skip and apply edits via conversation instead.
+- The preview service is already running → just give the user the URL; do not restart.
+- The user gave a precise chat edit ("change page 3 title to X") → edit the SVG directly.
+- The user wants a full regeneration → use the main workflow.
+- Step 7 has never run for this project → annotations cannot be applied yet; finish the main pipeline first.
---
-## Step 1: Start the editor
+## Step 1: Start / reopen the editor
-**During Executor (live mode):**
-```bash
-python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live
-```
+**Precondition**: no preview service running on this project.
-**Finished-deck / re-entry:**
```bash
python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path>
```
-The server binds to `127.0.0.1:5050`, opens the browser automatically on local desktop environments, and edits `<project_path>/svg_output/` in place. **Submit annotations** writes annotations to disk; it never stops the server. **Exit preview** closes the Flask server without saving pending annotations. `svg_to_pptx` snapshots `svg_output` into `backup/<timestamp>/` on every export, so prior versions are recoverable.
+(Plain mode — no `--live`. The `--live` flag is reserved for Step 6's auto-startup.)
-### Remote Linux access
+The server binds `127.0.0.1:5050`, opens the browser on a local desktop, and edits `<project_path>/svg_output/` in place. After it prints `SVG Editor running at http://localhost:5050`, tell the user in their language, in one short message:
-If the project lives on a remote Linux server, run with `--no-browser`:
+- editor is at `http://localhost:5050`
+- click an element → write the change → click **Submit annotations** → return to the chat and say `apply my annotations` (or quote the browser prompt)
+- to skip the editor, just describe the change in chat
-```bash
-python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --no-browser
-# or with --live during generation:
-python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --no-browser
-```
+Do not wait for confirmation before launching — the user already asked for preview, so launching is the response. Port conflicts → `--port <other>` and report the new URL. Remote access → see the appendix.
-- **VS Code / Cursor Remote-SSH**: open the **PORTS** panel (`Ctrl+Shift+P` → `Ports: Focus on Ports View`), click **Forward a Port**, enter `5050`. The workspace remembers it.
-- **Termius**: open the **Port Forwarding** module from the left sidebar (top-level, not nested). Add a rule with **Type = Local**, Host = your remote, Binding `127.0.0.1:5050`, Destination `127.0.0.1:5050`. Save, then **start the rule** (▶ button).
-- **Plain SSH**: `ssh -L 5050:127.0.0.1:5050 <user>@<host>` (or add `LocalForward 5050 127.0.0.1:5050` to `~/.ssh/config`).
-
-Then open `http://localhost:5050` in your local browser.
-
-After the server prints `SVG Editor running at http://localhost:5050`, tell the user (in their language) in a single message:
-
-- the editor is running at `http://localhost:5050`
-- they should open it in a browser, click the element they want changed, write the change as a short instruction, then click **Submit annotations**
-- after submitting, they should return to the conversation; the server stays open until they click **Exit preview**
-- if they'd rather just describe the edit in chat, they can say so and you'll apply it directly without the editor
+---
-Do **not** wait for user confirmation before launching — they already signalled preview intent, so launching is the response. The "describe in chat" line is the escape hatch.
+## Step 2: Apply submitted annotations
-## Step 2: Apply annotations (Edit Loop)
+🚧 **GATE**: `<project_path>/exports/` contains at least one `*.pptx` (Step 7 has completed). If not, do not apply annotations — tell the user to finish the main pipeline first.
-Triggered when the user signals (in any wording) that they have submitted annotations and want them applied.
+Triggered by the user signals listed in "When to Run".
-1. Leave the preview server running unless the user clicked **Exit preview**.
-2. Discover annotations:
+1. Discover annotations:
```bash
python3 ${SKILL_DIR}/scripts/check_annotations.py <project_path>
```
-3. If no annotations are found, tell the user and stop.
-4. For each annotated SVG in `<project_path>/svg_output/`:
- - Read the file.
- - For each element with `data-edit-target="true"`, apply the change described in `data-edit-annotation`.
- - Strip `data-edit-target` and `data-edit-annotation` from the modified element.
-5. Re-run post-processing:
+ The output already lists each pending change as `file → element_id → annotation text → content preview`. Use it directly as the to-do list; no need to re-parse SVG attributes yourself.
+2. If the output says no annotations: tell the user, stop.
+3. For each listed annotation:
+ - Edit the targeted element in `<project_path>/svg_output/<file>` per the annotation text.
+ - Remove `data-edit-target` and `data-edit-annotation` from that element.
+4. Re-export:
```bash
python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>
python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
```
-6. If the preview server is still running, keep using it; if it was closed, restart with the Step 1 command.
-7. Tell the user (in their language) that annotations have been applied, the PPT is updated, and the editor is at `http://localhost:5050`. If their browser shows an old slide, ask them to refresh or reselect the slide.
-8. Wait for the user's next message:
- - If they indicate they're done, the loop ends.
- - If they submit more annotations, return to step 2.
+5. Tell the user (in their language): annotations applied, new PPTX exported, preview is still running. If the browser still shows the old slide, refresh or reselect the page.
+6. Loop: more annotations submitted → repeat from step 1. User signals done or "stop preview" → end.
---
-## Notes
+## Notes (editor invariants — referenced from SKILL.md Step 6)
-- **Browser preview**: the server inlines `<use data-icon>` placeholders and serves `images/*` so the SVG renders correctly in the browser. The on-disk SVG is unchanged by these previews.
-- **Element targeting**: each element gets a transient `_edit_N` id assigned by the server while previewing. After save, only annotated elements keep their id; unannotated `_edit_N` ids are stripped before writing back to disk.
-- **Port conflict**: if `5050` is taken, pass `--port <other>` and update the URL you tell the user.
-- **Idle timeout**: the server self-terminates after 15 minutes of inactivity in standard mode (override with `--timeout <seconds>`). In `--live` mode, timeout is disabled by default.
+- **Buttons**: `Add annotation` stages locally; `Submit annotations` writes to disk and keeps the service running; `Exit preview` is the only UI action that stops Flask.
+- **Stop conditions**: once started, the service runs until the user clicks **Exit preview** in the browser, or asks in chat to stop it.
+- **Port**: default `5050`; override with `--port <other>`.
+- **Idle timeout**: plain mode `900s`, `--live` mode `0` (disabled); override with `--timeout <seconds>`.
+- **Transient ids**: each element gets a temporary `_edit_N` id while the editor is running. On save, only annotated elements keep their id; unannotated `_edit_N` ids are stripped before write-back.
+- **Browser preview**: the server inlines `<use data-icon>` placeholders and serves `images/*` so SVG renders correctly; the on-disk SVG is unchanged by this preview.
+
+---
+
+## Appendix: Remote access
+
+If the project lives on a remote Linux server, run with `--no-browser`:
+
+```bash
+python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --no-browser
+# or for Step 6's auto-startup on a remote host:
+python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --no-browser
+```
+
+- **VS Code / Cursor Remote-SSH**: open the **PORTS** panel (`Ctrl+Shift+P` → `Ports: Focus on Ports View`), click **Forward a Port**, enter `5050`. The workspace remembers it.
+- **Termius**: open the **Port Forwarding** module from the left sidebar (top-level, not nested). Add a rule with **Type = Local**, Host = your remote, Binding `127.0.0.1:5050`, Destination `127.0.0.1:5050`. Save, then start the rule (▶ button).
+- **Plain SSH**: `ssh -L 5050:127.0.0.1:5050 <user>@<host>` (or add `LocalForward 5050 127.0.0.1:5050` to `~/.ssh/config`).
+
+Then open `http://localhost:5050` in your local browser.