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.mdindex 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 Requirementsdiff --git a/CLAUDE.md b/CLAUDE.mdindex 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 Requirementsdiff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex 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:```bashpython3 ${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.pyindex 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.jsindex 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.mdindex 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:**```bashpython3 ${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:```bashpython3 ${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:```bashpython3 ${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.