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(svg-to-pptx): retire SVG-image PPTX export

hugohe3f56476bd5aa2
diff --git a/README.md b/README.md
index da4de955..65f31091 100644
--- a/README.md
+++ b/README.md
@@ -306,7 +306,7 @@ AI: Sure. Let's confirm the design spec:
The AI handles everything — content analysis, visual design, SVG generation, and PPTX export.
-> **Output:** Native-shapes `.pptx` (directly editable) saved to `exports/<name>_<timestamp>.pptx`. A copy of `svg_output/` is always snapshotted to `backup/<timestamp>/svg_output/` for re-export / archival. Pass `--svg-snapshot` to additionally emit an SVG-image preview pptx alongside the native pptx in `exports/` (see [FAQ](./docs/faq.md)). Requires Office 2016+. By default charts and tables export as SVG-derived shapes (pixel-consistent across PowerPoint / Keynote / WPS); pass `--native-objects` to instead emit them as **real editable PowerPoint chart / table objects backed by data** (rendering may vary across apps), saved as `exports/<name>_<timestamp>_native_charts.pptx`.
+> **Output:** The SVG pipeline has one PPTX export route: PPT Master's converter reads `svg_output/` and writes a directly editable native DrawingML deck to `exports/<name>_<timestamp>.pptx`. Step 7 still always runs `finalize_svg.py`, producing self-contained files in `svg_final/` for visual inspection or manual insertion as SVG pictures; PowerPoint's manual **Convert to Shape** command is outside the supported contract. A copy of `svg_output/` is always snapshotted to `backup/<timestamp>/svg_output/` for re-export / archival. By default charts and tables export as SVG-derived shapes (pixel-consistent across PowerPoint / Keynote / WPS); pass `--native-objects` to instead emit them as **real editable PowerPoint chart / table objects backed by data** (rendering may vary across apps), saved as `exports/<name>_<timestamp>_native_charts.pptx`.
> **Already have a `.pptx` you want to reuse?** Hand the AI that deck plus your material and ask it to "fill this deck with the new content" — it fills text, table, and chart data into your existing design and exports only the pages you pick, staying natively editable. See the [FAQ](./docs/faq.md) and [template-fill workflow](./skills/ppt-master/workflows/template-fill-pptx.md).
diff --git a/README_CN.md b/README_CN.md
index 218445f7..e5e21b9d 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -316,7 +316,7 @@ AI:好的,先确认设计规范:
AI 全程处理——内容分析、视觉设计、SVG 生成、PPTX 导出。
-> **输出说明:** 原生形状版 `.pptx`(可直接编辑)保存至 `exports/<name>_<timestamp>.pptx`;`svg_output/` 始终镜像到 `backup/<timestamp>/svg_output/`,便于归档或后续重跑。加 `--svg-snapshot` 时,额外在 `exports/` 内并排生成 SVG 快照版 pptx(详见[常见问题](./docs/zh/faq.md))。需要 Office 2016+。图表和表格默认导出为 SVG 派生的形状(在 PowerPoint / Keynote / WPS 间像素一致);加 `--native-objects` 则改为导出**带数据、可直接编辑的 PowerPoint 原生图表 / 表格对象**(跨软件渲染可能略有差异),保存为 `exports/<name>_<timestamp>_native_charts.pptx`。
+> **输出说明:** 标准导出从 `svg_output/` 经项目转换器生成原生 DrawingML `.pptx`,保存至 `exports/<name>_<timestamp>.pptx`;这是唯一的 PPTX 产物路线,文字和图形可直接编辑。`svg_output/` 始终镜像到 `backup/<timestamp>/svg_output/`,便于归档或后续重跑。流程仍会强制生成 `svg_final/`:它是一组自包含的视觉预览 SVG,可直接打开,也可作为 SVG 图片手动插入 PowerPoint;PowerPoint 手工“转换为形状”不在支持范围。图表和表格默认导出为 SVG 派生的 DrawingML 形状(在 PowerPoint / Keynote / WPS 间像素一致);加 `--native-objects` 则在同一原生导出路线中改为**带数据、可直接编辑的 PowerPoint 原生图表 / 表格对象**(跨软件渲染可能略有差异),保存为 `exports/<name>_<timestamp>_native_charts.pptx`。
> **已有一份想复用的 `.pptx`?** 把那份 deck 连同素材给 AI,说「套模板」即可——它会把新内容(文字、表格、图表数据)填进你现有的设计,只导出你挑选的页面,且保持原生可编辑。详见 [常见问题](./docs/zh/faq.md) 与 [套模板工作流](./skills/ppt-master/workflows/template-fill-pptx.md)。
diff --git a/docs/faq.md b/docs/faq.md
index 15bcff64..0bff1009 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -75,7 +75,9 @@ Be clear on what this buys you: **web search only finds *a* relevant, downloadab
## Q: Can I edit the generated presentations?
-Yes. The main `.pptx` (native PowerPoint shapes — all text, graphics, and colors directly editable without any conversion) is saved to `exports/` with a timestamp. A copy of `svg_output/` (the Executor's raw SVG source) is always written to `backup/<timestamp>/svg_output/` so you can rebuild via `finalize_svg → svg_to_pptx` without re-running the LLM. Pass `--svg-snapshot` to additionally emit an SVG-image preview pptx alongside the native pptx in `exports/` — handy for cross-platform distribution as a single file; off by default because live preview already serves as the SVG visual reference for day-to-day work. Requires **Office 2016** or later.
+Yes. The only PPTX export route in the SVG pipeline is PPT Master's own `svg_output/` → DrawingML conversion. It saves a timestamped native PowerPoint deck to `exports/`, with text, graphics, and colors directly editable as PowerPoint objects. A copy of `svg_output/` (the Executor's raw SVG source) is always written to `backup/<timestamp>/svg_output/` so you can rebuild via `finalize_svg → svg_to_pptx` without re-running the LLM.
+
+`finalize_svg.py` remains a mandatory Step 7 operation even though native PPTX export reads `svg_output/`. It produces self-contained files in `svg_final/` for visual inspection and for manual insertion into another deck as SVG pictures. PowerPoint's manual **Convert to Shape** command is not a supported round-trip path; use the generated native PPTX when you need editable shapes.
## Q: Why is one paragraph split into multiple text boxes? Can I get one text box per paragraph instead?
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 2e337c63..88dd4b0f 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -44,11 +44,14 @@ User Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text)
[Post-processing] → total_md_split.py (split notes) → finalize_svg.py → svg_to_pptx.py
↓
Output:
+ svg_final/
+ └── *.svg ← Mandatory self-contained visual previews; may be inserted as SVG pictures
+
+ # Every PPTX variant below is produced through the svg_output → native DrawingML route
exports/
├── presentation_<timestamp>.pptx ← Native shapes (DrawingML) — canonical output, edit & deliver from here
├── presentation_<timestamp>_native_charts.pptx ← Native chart/table objects instead of flattened shapes (opt-in via --native-objects)
- ├── presentation_<timestamp>_narrated.pptx ← Narrated version — embedded per-slide audio + auto-advance timings (via --recorded-narration audio)
- └── presentation_<timestamp>_svg.pptx ← SVG snapshot pptx — pixel-perfect visual reference (opt-in via --svg-snapshot)
+ └── presentation_<timestamp>_narrated.pptx ← Narrated version — embedded per-slide audio + auto-advance timings (via --recorded-narration audio)
# Always written in default-flow mode (no -o)
backup/<timestamp>/
@@ -215,7 +218,7 @@ Two converter design choices still shape the system:
| `icons/` | project-local icon set copied by `icon_sync.py`, with global library fallback at export |
| `templates/` | copied template specs / SVG references / non-image template assets |
| `svg_output/` | the only hand-authored SVG source directory |
-| `svg_final/` | derived, self-contained SVGs for IDE/browser/preview-snapshot workflows |
+| `svg_final/` | mandatory derived, self-contained SVGs for IDE/browser preview or manual insertion as SVG pictures; not a supported Convert-to-Shape path |
| `live_preview/` | preview server state, edit history, and annotation logs |
| `notes/` | `total.md` and split per-slide speaker notes |
| `exports/` | timestamped native PPTX deliverables |
@@ -238,7 +241,7 @@ These invariants are stronger than ordinary implementation preferences. If a cha
| `design_spec.md` explains the design; `spec_lock.md` executes it | Executor reads locked values from `spec_lock.md`, not from prose memory |
| `spec_lock.md` is re-read before every page | colors, fonts, icons, images, rhythm, layouts, and chart choices stay stable across long decks |
| `svg_output/` is the only hand-authored SVG directory | quality checks, manual edits, re-export, and `update_spec.py` target authored source |
-| `svg_final/` is derived | it can be regenerated from `svg_output/` and should not become the native export source of truth |
+| `svg_final/` is mandatory but derived | it is regenerated from `svg_output/` for self-contained visual preview or manual insertion as an SVG picture; it does not become the native export source of truth, and PowerPoint Convert to Shape is outside the supported contract |
| Native PPTX export reads `svg_output/` by default | converter preserves icons, `preserveAspectRatio`, rounded rects, and native image crop metadata before finalization rewrites them |
| Direct OOXML routes do not enter the SVG pipeline | preservation workflows patch native PPTX parts directly |
| Image facts come from regenerated metadata | `analysis/image_analysis.csv` is re-derived from the live `images/` folder; agents do not inspect image pixels directly |
@@ -337,7 +340,7 @@ Several architectural decisions shape this phase:
**Terminal status before Executor.** Rows that require acquisition must end in `Generated`, `Sourced`, or `Needs-Manual`; `Pending` and `Failed` are not allowed to leak into Executor. A `Needs-Manual` row can continue through SVG generation only as a known placeholder/dependency, and Step 7 re-checks required files before final export.
-**External refs during development, two divergent embedding strategies for delivery.** While editing in `svg_output/`, images are external file references — fast iteration, single-source-of-truth replacement. The two delivery artifacts then diverge: `svg_final/` Base64-inlines (a folder of self-contained SVGs that IDE preview, browser, and the preview pptx can all open without missing the bitmap dependencies); native pptx instead copies bitmaps into the PPTX media folder and uses `<a:srcRect>` to express the cropping. The split exists because Base64 inside DrawingML works but bloats file size 3-4×, while file-referenced bitmaps are PowerPoint's native idiom for which `<a:srcRect>` is the canonical crop expression — wrong tool in either direction would cost editability or file size.
+**External refs during development, two divergent embedding strategies for derived outputs.** While editing in `svg_output/`, images are external file references — fast iteration, single-source-of-truth replacement. Step 7 always creates both downstream forms: `svg_final/` Base64-inlines assets into self-contained SVGs that an IDE or browser can inspect and users may manually insert as SVG pictures; native pptx instead reads `svg_output/`, copies bitmaps into the PPTX media folder, and uses `<a:srcRect>` to express cropping. The split exists because Base64 inside DrawingML works but bloats file size 3-4×, while file-referenced bitmaps are PowerPoint's native idiom for which `<a:srcRect>` is the canonical crop expression. Manual PowerPoint Convert to Shape is not a third conversion route and is not covered by the project contract.
**Three-dimensional AI image lock at Strategist time.** When the deck includes AI-generated images, Strategist decides three orthogonal dimensions up front — `rendering` (visual style family: vector-illustration / editorial / 3d-isometric / sketch-notes / …), `palette` (how the deck's HEX values are *used*: proportion + role + temperament), `type` (per-image internal composition: background / hero / framework / comparison / …). The first two are deck-wide and written into `spec_lock.md`; Image_Generator then assembles every per-image prompt from the single locked rendering + palette plus a per-image type, instead of re-deciding style per image. Without this, every image gets its own style drift and the deck reads as a stack of unrelated illustrations. This is the visual-cohesion dual of `spec_lock`'s typography/color anti-drift mechanism, just one level upstream of pixels. Strategist surfaces ≥3 candidate `rendering × palette` combinations to the user during the Strategist confirmation stage — never auto-locking a single combination silently, because the choice has far-reaching deck-wide consequences and the user's taste is the only oracle for it.
@@ -393,23 +396,22 @@ The architectural reasons worth knowing here:
### Delivery artifacts and workflows
-The post-processing and export stages work with distinct artifacts. Each one serves a workflow that nothing else in the pipeline can replace.
+The post-processing and export stages work with distinct artifacts. Each one serves a workflow that nothing else in the pipeline can replace. Every PPTX entry below is a variant of the same `svg_output/` → native DrawingML route, not a parallel image-based converter.
| Artifact | Workflow it serves | Why nothing else replaces it |
| --- | --- | --- |
| `svg_output/` | source of truth, manual editing, `update_spec.py`, `svg_quality_checker.py` | only directory whose contents are authored, not derived |
-| `svg_final/` | IDE inline preview (VSCode/Cursor open `.svg` directly), browser open of a single page | `.pptx` is not openable in IDEs; `svg_output/` won't render fully because of external icon / image refs |
+| `svg_final/` | mandatory self-contained visual preview; IDE/browser inspection; manual insertion as an SVG picture | `.pptx` is not openable in IDEs; `svg_output/` won't render fully because of external icon / image refs. PowerPoint Convert to Shape is not supported |
| `exports/<name>_<ts>.pptx` (native) | primary deliverable — editable in PowerPoint with DrawingML shapes | only artifact whose shapes the user can resize / recolor / restyle natively in PowerPoint |
| `exports/<name>_<ts>_native_charts.pptx` (opt-in via `--native-objects`) | when `data-pptx-native` chart/table markers should ship as real editable PowerPoint objects instead of flattened shapes | data-backed chart/table objects the user can edit in PowerPoint; name marks it apart from the plain shape export |
| `exports/<name>_<ts>_narrated.pptx` (via `--recorded-narration audio`) | narrated deck for auto-play and PowerPoint video export | embedded per-slide audio plus auto-advance timings; name marks it apart from silent exports |
-| `exports/<name>_<ts>_svg.pptx` (preview, opt-in via `--svg-snapshot`) | cross-platform single-file distribution, multi-page browse, email attachment | self-contained, multi-page, opens in PowerPoint / Keynote / WPS / LibreOffice; an `svg_final/` folder is harder to distribute. Off by default — live preview already provides the SVG visual reference for dev/diagnostic work |
| `backup/<ts>/svg_output/` (always written in default-flow mode) | re-export from frozen SVG sources without re-running the LLM, archival | the only persisted copy of the Executor's raw SVG source after the project has been edited downstream |
### SVG preprocessors have TWO consumers
This is the key insight that's easy to miss when reading the code. Cleanup modules under `skills/ppt-master/scripts/svg_finalize/`, together with the local-reference expander, are used in two places for two different products.
-**Disk consumer** — `finalize_svg.py` writes `svg_output/` → `svg_final/` once per run, expanding both project icon placeholders and qualified local `<use>` references. `svg_final/` then feeds IDE preview and the preview pptx.
+**Disk consumer** — `finalize_svg.py` writes `svg_output/` → `svg_final/` once per run, expanding both project icon placeholders and qualified local `<use>` references. This mandatory output feeds IDE/browser preview and may be inserted manually as an SVG picture; it is not converted into a separate PPTX artifact.
**Memory consumer** — native pptx generation reads `svg_output/` directly (no disk hop), but DrawingML cannot consume project icon placeholders, retained SVG reference instances, or positional text runs inline, so the converter applies the matching preprocessors **in memory**:
@@ -426,9 +428,9 @@ This is the key insight that's easy to miss when reading the code. Cleanup modul
| `embed_icons.py` | `finalize_svg` `embed-icons` step (followed by local-use expansion) | `svg_to_pptx/use_expander.py` | native pptx loses all icons + `svg_final/` not self-contained |
| `svg_to_pptx/use_expander.py` (local references) | `finalize_svg` `embed-icons` step | native converter preflight | finalize/native export can no longer materialize qualified local reuse |
| `flatten_tspan.py` | `finalize_svg` `flatten-text` step | `svg_to_pptx/tspan_flattener.py` | **native pptx multi-line `dy`-stacked text collapses to one line** |
-| `align_embed_images.py` | `finalize_svg` `align-images` step | — | `svg_final/` loses image embedding → IDE preview / preview pptx have no images |
+| `align_embed_images.py` | `finalize_svg` `align-images` step | — | `svg_final/` loses image embedding → self-contained preview and manually inserted SVG pictures lose images |
| `crop_images.py` / `embed_images.py` / `fix_image_aspect.py` | imported by `align_embed_images.py` | — | `align_embed_images` `ImportError`, full chain broken |
-| `svg_rect_to_path.py` | `finalize_svg` `fix-rounded` step | — | only PowerPoint's manual "Convert to Shape" loses rounded corners; browsers / IDE / PowerPoint's own SVG renderer all OK without it |
+| `svg_rect_to_path.py` | — (legacy standalone utility; no supported pipeline consumer) | — | no supported preview or native-PPTX artifact depends on it; PowerPoint's manual Convert to Shape command is outside the project contract |
---
@@ -448,7 +450,7 @@ These direct routes share some analysis primitives with the main pipeline, espec
**Why per-element dispatch, not whole-file translation.** SVG's hierarchical model maps cleanly onto DrawingML's group / shape / picture types — there's no need for a holistic optimizer that re-plans the slide. Each shape kind gets its own narrow translator, which keeps each translator simple enough to debug and unit-test in isolation. The output quality of a slide is the sum of independent local conversions; that property is fragile under whole-file translation but robust under element dispatch.
-**Why compatibility fallback belongs to the SVG snapshot path, not native shapes.** Native PPTX export translates supported SVG elements into DrawingML shapes and explicitly disables PNG+SVG compatibility mode in native-shapes mode. The PNG fallback is used only by the legacy SVG-image path (`--svg-snapshot` / `--only legacy`) when a renderer is available, because that path embeds SVG media that older Office builds may not display. Legacy compatibility is therefore an optional snapshot deliverable, not a fallback bundled inside the primary editable native deck.
+**Why there is only one PPTX export route.** Native export reads `svg_output/` and translates supported SVG elements into DrawingML shapes. The project does not package whole-slide SVG media or alternate raster renderings into a second PPTX. `svg_final/` is still generated on every standard run, but it is a self-contained visual-preview artifact rather than a PPTX source; users may insert it as an SVG picture, while PowerPoint's manual Convert to Shape command remains outside the supported contract.
**Why the default native deck has a baseline master, not inferred templates.** `svg_to_pptx.py` starts from the actual blank slide layout relationship in the base package and defaults to `--pptx-structure baseline`. Baseline promotes only low-risk shared structure: the strict-majority identical slide background plus a common leading prefix of repeated top-level SVG chrome explicitly marked as `logo`, `footer`, `header`, `watermark`, `chrome`, or `page-number`. Exact id tokens remain a fallback for marker-free legacy SVGs. Promotion requires identical generated OOXML, no timing reference, and z-order safety; minority pages keep their shapes slide-local and use a `Cover` layout with `showMasterSp="0"`. A later export-only pass maps root `data-pptx-page-role` to `Cover`, `Agenda`, `Section`, `Closing`, or `Content`, falling back to conservative filename tokens only when the root marker is absent. It moves an exact family-wide background and an exact leading family-wide chrome prefix into that Layout, but never compares visual similarity or infers placeholders. Actual content remains on the Slide. This gives free-design decks useful Master/Layout structure without constraining SVG authoring.
@@ -490,6 +492,7 @@ The tempting simplifications below have explicit costs. Treat them as negative c
| Do not script-generate batches of Executor SVG pages | cross-page design judgment depends on sequential main-agent authoring |
| Do not make `image_analysis.csv` a durable cache | `images/` is a live folder; facts must be regenerated on use |
| Do not make `svg_final/` the default native PPTX input | `svg_final/` is rewritten for self-contained preview, while native conversion needs high-fidelity `svg_output/` semantics |
+| Do not treat PowerPoint Convert to Shape as an export fallback | editable shapes come from PPT Master's `svg_output/` → DrawingML converter; `svg_final/` is a visual-preview / SVG-picture artifact only |
| Do not auto-enable object-level entrance animations | page transitions are default; object builds are an explicit export policy |
| Do not default visual review, narration, chart verification, or animation customization into every run | these workflows have narrow triggers and extra dependencies |
| Do not replace `finalize_svg.py` with a file copy | finalization embeds icons/images, flattens special text, and prepares preview artifacts |
diff --git a/docs/windows-installation.md b/docs/windows-installation.md
index abc46b45..de020b92 100644
--- a/docs/windows-installation.md
+++ b/docs/windows-installation.md
@@ -82,11 +82,10 @@ If a `.pptx` file appears in `exports/` that opens in PowerPoint — **you're do
## Step 6 — Optional Enhancements (most users can skip this)
-With Python and `requirements.txt` installed, you already have everything needed to generate presentations. The items below are **edge-case fallbacks and enhancements** — install only if you hit the specific scenario.
+With Python and `requirements.txt` installed, you already have everything needed to generate presentations. PPTX export writes native DrawingML shapes, so it does not require CairoSVG, GTK, or a separate SVG rasterization stack. The item below is an **edge-case fallback** — install it only if you hit the specific scenario.
| Enhancement | Install only if… | How to install | Verify |
|-------------|-----------------|----------------|--------|
-| **CairoSVG** — higher quality PNG fallbacks | You want crisper PNG fallbacks for Office versions that don't render SVG natively. `svglib` (already installed) is fine for most cases. | Install [GTK3 Runtime](https://github.com/nickvdp/gtk3/releases), then `pip install cairosvg` | `python -c "import cairosvg"` |
| **Pandoc** — legacy document formats | You need to convert `.doc`, `.odt`, `.rtf`, `.tex`, `.rst`, `.org`, or `.typ`. `.docx`/`.html`/`.epub`/`.ipynb` work natively in Python. | Download `.msi` from [pandoc.org](https://pandoc.org/installing.html) | `pandoc --version` |
---
diff --git a/docs/zh/animations.md b/docs/zh/animations.md
index 6f3433c8..3e6afde5 100644
--- a/docs/zh/animations.md
+++ b/docs/zh/animations.md
@@ -9,7 +9,7 @@ PPT Master 导出的 PPTX 同时支持**页间转场**(page transition)与**
| 页间转场 | `fade`,0.4 秒 | 适合大多数 deck 的中性基线 |
| 页内元素动画 | **`none`(关闭)** | 翻到一页时整页一次性呈现。元素一个个自动级联出来是「AI 味」最重的信号,且没人主动要,所以页内动画改为按需开启。用 `-a auto`(或其它效果)开启:根据每个 group 的 SVG id 映射效果(chart→wipe、card-/step-/pillar-→fly、title/takeaway→fade),图片类 id(`hero` / `figure-` / `image` / `img-` / `kpi`)在更丰富的视觉池(zoom / dissolve / circle / box / diamond / wheel)中循环以产生 deck 内变化,未命中的 id 在 fade/wipe/fly/zoom 间循环 |
-修改设置只需对同一份 `svg_output/`(或 `svg_final/`)重跑 `svg_to_pptx.py`,无需重新跑 LLM。如要为整份 deck 开启页内动画,加 `-a auto`。
+修改设置只需对同一份 `svg_output/` 重跑 `svg_to_pptx.py`,无需重新跑 LLM。`-s final` 只保留给诊断对比,不能作为受支持的发布源。如要为整份 deck 开启页内动画,加 `-a auto`。
## 对象级自定义动画
@@ -141,9 +141,9 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation-trigger w
## 限制
-- **仅原生形状模式生效。** 页内动画需要可编辑形状作为锚点。`--only legacy` 模式每页一张大图,没有元素粒度,因此不响应 `-a/--animation`,只受 `-t/--transition` 影响。
+- **动画只写入原生 DrawingML PPTX。** 页间转场和页内元素动画都属于项目转换器从 `svg_output/` 生成的 PPTX;`svg_final/` 仍是静态视觉预览,不是带动画的替代 PPTX 路线。
- **不同 Office 版本对元素动画存在轻微差异。** 实现走 `<p:animEffect filter=...>` 路径(而非 `presetID` 查找表),在 PowerPoint 2016+ 上表现一致;更老的 Office 可能把部分效果降级为 Appear。
-- **兼容模式的 PNG fallback 只用于显示。** 转场与动画都在 slide XML 里,不在 PNG 中;关掉兼容模式不影响两个动画层。
+- **手工 SVG 形状转换不受支持。** 把 `svg_final/` 页面作为 SVG 图片插入 PowerPoint,不会获得元素级动画锚点;需要可编辑且可动画的形状时,请使用原生 PPTX。
## 常用速查
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index b7804b30..6fc5bfd3 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -77,7 +77,9 @@ python3 skills/ppt-master/scripts/update_repo.py
## Q: 生成的 PPT 可以编辑吗?
-可以。主 `.pptx`(原生 PowerPoint 形状,文字、图形、颜色均可直接编辑,无需转换)以时间戳命名保存至 `exports/`。Executor 的原始 SVG 源(`svg_output/` 副本)始终镜像到 `backup/<timestamp>/svg_output/`,便于归档或基于该版重跑 `finalize_svg → svg_to_pptx` 重建 pptx,无需再走 LLM。加 `--svg-snapshot` 会额外在 `exports/` 内并排生成 SVG 快照版 pptx,便于跨平台单文件分发;默认关闭——日常开发/诊断场景中 live preview 已经提供了 SVG 视觉参考。需要 **Office 2016** 或更高版本。
+可以。唯一受支持的 PPTX 产物路线,是由项目转换器读取 `svg_output/` 并生成原生 DrawingML `.pptx`;文字、图形和颜色无需额外转换即可编辑,文件以时间戳命名保存至 `exports/`。Executor 的原始 SVG 源(`svg_output/` 副本)始终镜像到 `backup/<timestamp>/svg_output/`,便于归档或基于该版重跑 `finalize_svg → svg_to_pptx` 重建 PPTX,无需再走 LLM。
+
+Step 7 仍会强制生成 `svg_final/`。其中每页都是自包含的视觉预览 SVG,可直接在浏览器或 IDE 中打开,也可作为 SVG 图片手动插入 PowerPoint;项目只保证其作为预览或图片显示,不保证 PowerPoint 手工“转换为形状”后的结果。需要可编辑形状时,请使用 `exports/` 中由项目转换器生成的原生 PPTX。
## Q: 为什么一段正文被拆成了好几个文本框?能不能一段一个文本框?
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 0bf6d98f..1805792b 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -44,11 +44,13 @@
[后处理] → total_md_split.py(拆分讲稿)→ finalize_svg.py → svg_to_pptx.py
↓
输出:
+ svg_final/
+ └── *.svg ← 强制生成的自包含视觉预览,可手动作为 SVG 图片插入
+
exports/
- ├── presentation_<timestamp>.pptx ← 原生形状版(DrawingML)— 唯一标准产物,编辑/交付从这里走
- ├── presentation_<timestamp>_native_charts.pptx ← 原生图表/表格对象版(而非压平形状,加 --native-objects 时生成)
- ├── presentation_<timestamp>_narrated.pptx ← 旁白版 — 逐页嵌入音频并写入自动推进时间(加 --recorded-narration audio 时生成)
- └── presentation_<timestamp>_svg.pptx ← SVG 快照版 pptx — 像素级视觉参考(加 --svg-snapshot 时生成)
+ ├── presentation_<timestamp>.pptx ← 原生形状版(DrawingML)— 唯一 PPTX 生成路线的标准文件
+ ├── presentation_<timestamp>_native_charts.pptx ← 同一路线的原生图表/表格对象变体(加 --native-objects 时生成)
+ └── presentation_<timestamp>_narrated.pptx ← 同一路线的旁白变体(加 --recorded-narration audio 时生成)
# 默认流程(未指定 -o)始终写入
backup/<timestamp>/
@@ -70,6 +72,8 @@
这是一条“页面设计闭包”规则,不代表 SVG 要描述完整 PPTX package。相关验收是:完成的页面 SVG 能重建对应幻灯片的可见设计;不要求仅凭 SVG 重建讲稿、音频、计时、relationships 或直接原生编辑结果。
+`svg_final/` 不改变这条边界。Step 7 必须从 `svg_output/` 派生这组自包含视觉预览,供 IDE、浏览器查看,也可由用户手动作为 SVG 图片插入 PowerPoint;它不是第二条 PPTX 导出路线,也不承担 PowerPoint 手工“转换为形状”的兼容性。需要可编辑形状时,唯一受支持的路径是项目转换器把 `svg_output/` 翻译为原生 DrawingML PPTX。
+
以下直接 PPTX 工作流会有意绕过 SVG 创作路线,并继续保持独立:
| 工作流 | 输入角色 | 输出机制 | 为什么独立 |
@@ -145,7 +149,7 @@ analysis/<stem>.slide_library.json + 源 PPTX + fill_plan.json
└─> native_enhance_pptx.py -> exports/*.pptx
```
-关键切分是:`svg_output/` 是作者状态,`svg_final/`、`exports/` 和 `backup/` 是派生的交付或归档状态。模糊这条线,会让校验、重导出和人工修复都更难推理。
+关键切分是:`svg_output/` 是作者状态,`svg_final/` 是派生视觉预览,`exports/` 和 `backup/` 是派生的交付或归档状态。模糊这条线,会让校验、重导出和人工修复都更难推理。
---
@@ -213,7 +217,7 @@ SVG 也是唯一同时满足流程中所有角色需要的格式:**AI 能可
| `icons/` | 由 `icon_sync.py` 复制的项目级图标集;导出时可回退到全局库 |
| `templates/` | 复制进项目的模板 spec / SVG reference / 非图片模板资产 |
| `svg_output/` | 唯一手写 SVG 源目录 |
-| `svg_final/` | 派生出的自包含 SVG,服务 IDE / 浏览器 / 预览快照 |
+| `svg_final/` | 强制派生的自包含视觉预览 SVG,服务 IDE / 浏览器,也可手动作为 SVG 图片插入 PowerPoint;不保证“转换为形状” |
| `live_preview/` | 预览服务状态、直接编辑历史和注解日志 |
| `notes/` | `total.md` 与拆分后的逐页讲稿 |
| `exports/` | 带时间戳的 native PPTX 交付物 |
@@ -236,8 +240,9 @@ CLI 仍支持三种导入模式:`--move`、`--copy`,以及“仓库内文件
| `design_spec.md` 解释设计;`spec_lock.md` 执行设计 | Executor 从 `spec_lock.md` 取锁定值,而不是从叙述记忆里取 |
| 每页生成前重读 `spec_lock.md` | 长 deck 中的颜色、字体、图标、图片、节奏、布局和图表选择保持稳定 |
| `svg_output/` 是唯一手写 SVG 目录 | 质量检查、手工编辑、重导出和 `update_spec.py` 都面向作者源 |
-| `svg_final/` 是派生产物 | 它可以从 `svg_output/` 重建,不应成为 native 导出的事实源 |
-| native PPTX 默认读取 `svg_output/` | 转换器要在 finalize 重写前保留图标、`preserveAspectRatio`、圆角矩形和原生图片裁剪语义 |
+| `svg_final/` 是派生产物 | 它必须能从 `svg_output/` 重建,只负责自包含视觉预览,不应成为 native 导出的事实源 |
+| native PPTX 标准导出读取 `svg_output/` | 唯一受支持的可编辑形状路线由项目转换器执行;它要在 finalize 重写前保留图标、`preserveAspectRatio`、圆角矩形和原生图片裁剪语义 |
+| PowerPoint 手工“转换为形状”不属于兼容性契约 | `svg_final/` 可以作为 SVG 图片插入,但转换后的结构与视觉结果不做保证,也不反向约束 SVG 允许能力 |
| 直接 OOXML 路由不进入 SVG 流水线 | 保留型工作流直接 patch 原生 PPTX parts |
| 图片事实来自重算元数据 | `analysis/image_analysis.csv` 从实时 `images/` 目录重算;agent 不直接看图片像素 |
| 原生 PPTX 模板不是 Step 3 模板 | Step 3 只消费可复用模板目录 |
@@ -335,7 +340,7 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
**Executor 前必须进入终态。** 需要获取的资源行必须落到 `Generated`、`Sourced` 或 `Needs-Manual`;`Pending` 和 `Failed` 不能漏进 Executor。`Needs-Manual` 可以作为已知占位 / 依赖继续进入 SVG 生成,但 Step 7 会在最终导出前重新检查必需文件是否已经存在。
-**开发期外部引用,交付期分叉成两套嵌入策略。** 在 `svg_output/` 里编辑时,图片是外部文件引用——快速迭代、单点替换。两份交付产物随后分叉:`svg_final/` 走 Base64 内联(产出一组自包含 SVG,IDE 预览、浏览器、preview pptx 都能开而不丢位图依赖);native pptx 反过来把位图复制进 PPTX 的 media 文件夹,用 `<a:srcRect>` 表达裁剪。分叉的理由:在 DrawingML 里塞 Base64 能跑但文件膨胀 3-4 倍;文件引用的位图是 PowerPoint 原生表达方式,配 `<a:srcRect>` 的裁剪也是 DrawingML 的规范写法——任一方向用错工具都要付出可编辑性或文件大小的代价。
+**开发期外部引用,下游分叉成预览与原生导出两套嵌入策略。** 在 `svg_output/` 里编辑时,图片是外部文件引用——快速迭代、单点替换。随后分成两种表达:`svg_final/` 走 Base64 内联,产出一组不依赖外部位图文件的自包含 SVG,供 IDE、浏览器和手工插入为 SVG 图片;native PPTX 则把位图复制进 PPTX 的 media 文件夹,用 `<a:srcRect>` 表达裁剪。分叉的理由是职责不同:前者服务视觉预览,后者服务项目转换器生成的可编辑 DrawingML。`svg_final/` 不作为 PowerPoint 手工“转换为形状”的兼容源。
**AI 图片三维系统:Strategist 阶段就锁定。** 当 deck 包含 AI 生成图片时,Strategist 在前置阶段一次性确定三个正交维度——`rendering`(视觉风格家族:vector-illustration / editorial / 3d-isometric / sketch-notes / ……)、`palette`(deck 的 HEX 在图里**怎么用**:比例 + 角色 + 气质)、`type`(每张图的内部构图:background / hero / framework / comparison / ……)。前两个是 deck 级、写进 `spec_lock.md`;Image_Generator 此后每张图的 prompt 都从同一份锁定的 rendering + palette 加上该图的 type 组装出来,而不是逐图重决风格。没有这层锁定,每张图都会自己风格漂移,整套 deck 读起来就是一摞互不相关的插画。这是 `spec_lock` 字体/色彩抗漂移机制在像素上游的对偶——同一思路,往前推一层。Strategist 在策略师确认阶段会向用户呈现 **≥3 个 `rendering × palette` 候选**,绝不静默地自动锁定单一组合,因为这是一个会牵动全 deck 视觉的选择,唯一权威只有用户的品味。
@@ -396,18 +401,17 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
| 产物 | 服务的工作流 | 为何无可替代 |
| --- | --- | --- |
| `svg_output/` | 唯一源、手工编辑入口、`update_spec.py`、`svg_quality_checker.py` | 流水线中唯一**手写**而非派生的目录 |
-| `svg_final/` | IDE 内即时预览(VSCode/Cursor 直接打开 `.svg`)、浏览器单页预览 | `.pptx` 在 IDE 里打不开;`svg_output/` 因图标 / 图片是外部引用,IDE 中渲染不完整 |
+| `svg_final/` | IDE 内即时预览(VSCode/Cursor 直接打开 `.svg`)、浏览器单页预览、手动作为 SVG 图片插入 | `.pptx` 在 IDE 里打不开;`svg_output/` 因图标 / 图片是外部引用,IDE 中渲染不完整。PowerPoint 手工“转换为形状”不在支持范围 |
| `exports/<name>_<ts>.pptx`(native) | 主交付物——PowerPoint 中以 DrawingML 形状形态可编辑 | 唯一一份用户可在 PowerPoint 中原生改尺寸 / 改色 / 改样式的产物 |
| `exports/<name>_<ts>_native_charts.pptx`(需 `--native-objects` 显式开启) | 让带 `data-pptx-native` 标记的图表/表格以真·PowerPoint 原生对象交付,而非压平形状 | 带数据、可在 PowerPoint 中直接编辑的图表/表格对象;命名与普通压平形状导出区分开 |
| `exports/<name>_<ts>_narrated.pptx`(经 `--recorded-narration audio` 生成) | 自动放映与 PowerPoint 视频导出用的旁白版 deck | 逐页嵌入音频并写入自动推进时间;命名与无声导出区分开 |
-| `exports/<name>_<ts>_svg.pptx`(preview,需 `--svg-snapshot` 显式开启) | 跨平台单文件分发、整体多页浏览、邮件附件 | 自包含、多页、PowerPoint / Keynote / WPS / LibreOffice 都能直接打开;`svg_final/` 是文件夹,分发不便。默认关闭——live preview 已经覆盖 dev / 诊断场景的 SVG 视觉参考需求 |
| `backup/<ts>/svg_output/`(默认流程下始终生成) | 不重跑 LLM 的前提下从冻结 SVG 源重建 pptx、长期存档 | 项目下游被改动后,Executor 原始 SVG 唯一的留存副本 |
### SVG 预处理器有**两种**消费者
这是读代码时容易忽略的关键事实。`skills/ppt-master/scripts/svg_finalize/` 下的清理模块和本地引用展开器,会在两个地方被使用,服务两份不同的产物。
-**写盘消费者** —— `finalize_svg.py` 每次运行都把 `svg_output/` → `svg_final/` 写到磁盘一次,同时展开项目图标占位符和合规的本地 `<use>` 引用。`svg_final/` 随后供 IDE 预览和 preview pptx 使用。
+**写盘消费者** —— `finalize_svg.py` 每次运行都把 `svg_output/` → `svg_final/` 写到磁盘一次,同时展开项目图标占位符和合规的本地 `<use>` 引用。`svg_final/` 随后供 IDE / 浏览器视觉预览及手工 SVG 图片插入使用。
**内存消费者** —— native pptx 直接读 `svg_output/`(不经磁盘中转),但 DrawingML 无法内联处理项目图标占位符、保留的 SVG 引用实例和定位文本 run,所以转换器在内存中应用对应预处理器:
@@ -424,9 +428,9 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
| `embed_icons.py` | `finalize_svg` 的 `embed-icons` 步骤(随后展开本地 use) | `svg_to_pptx/use_expander.py` | native pptx 丢失全部图标 + `svg_final/` 不再自包含 |
| `svg_to_pptx/use_expander.py`(本地引用) | `finalize_svg` 的 `embed-icons` 步骤 | native 转换器预检 | finalize/native 导出失去实体化合规本地复用的能力 |
| `flatten_tspan.py` | `finalize_svg` 的 `flatten-text` 步骤 | `svg_to_pptx/tspan_flattener.py` | **native pptx 中 `dy` 堆叠的多行文本塌成一行** |
-| `align_embed_images.py` | `finalize_svg` 的 `align-images` 步骤 | — | `svg_final/` 失去图片嵌入 → IDE 预览 / preview pptx 都没图 |
+| `align_embed_images.py` | `finalize_svg` 的 `align-images` 步骤 | — | `svg_final/` 失去图片嵌入 → IDE / 浏览器预览和手工插入的 SVG 图片缺图 |
| `crop_images.py` / `embed_images.py` / `fix_image_aspect.py` | 被 `align_embed_images.py` import | — | `align_embed_images` `ImportError`,整条链路 broken |
-| `svg_rect_to_path.py` | `finalize_svg` 的 `fix-rounded` 步骤 | — | 只影响 PowerPoint 内手动「Convert to Shape」时圆角丢失;浏览器 / IDE / PowerPoint 自带的 SVG 渲染器都正常 |
+| `svg_rect_to_path.py` | — | — | 仅保留为历史诊断工具,不属于 `finalize_svg` 或受支持导出流程;不得据此承诺 PowerPoint 手工“转换为形状”兼容性 |
---
@@ -446,7 +450,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
**为什么是逐元素派发而不是整体翻译。** SVG 的层级模型干净地映射到 DrawingML 的 group / shape / picture 类型——不需要一个全局优化器去重新规划幻灯片。每种形状都有自己窄的翻译器,简单到能单独调试和单元测试。一张幻灯片的最终质量等于这些独立局部转换之和;这个性质在整体翻译下脆弱,在元素派发下稳健。
-**为什么兼容 fallback 属于 SVG snapshot 路径,而不是 native shapes。** Native PPTX 导出会把受支持的 SVG 元素翻译成 DrawingML 形状,并在 native-shapes 模式下显式关闭 PNG+SVG 兼容模式。PNG fallback 只在 legacy SVG-image 路径(`--svg-snapshot` / `--only legacy`)且本地 renderer 可用时使用,因为那条路径嵌入的是旧版 Office 可能无法显示的 SVG media。因此,旧版兼容是一份可选 snapshot 交付物,不是捆在主 editable native deck 里的兜底层。
+**为什么只有项目转换器产出的 native PPTX。** Native 导出把 `svg_output/` 中受支持的 SVG 元素逐个翻译成 DrawingML 形状;这是唯一受支持的 SVG→PPTX 路线。`svg_final/` 仍由强制后处理生成,但只承担自包含视觉预览和 SVG 图片插入,不会再被封装成另一份 PPTX,也不为 PowerPoint 手工“转换为形状”提供兼容兜底。
**为什么默认 native deck 使用基线母版,而不推断模板。** `svg_to_pptx.py` 默认使用 `--pptx-structure baseline`。它只提升低风险共享结构:严格多数页面完全一致的背景,以及显式标记为 `logo`、`footer`、`header`、`watermark`、`chrome` 或 `page-number` 的共同前置 chrome;没有结构角色的旧 SVG 才回退到精确 id token。提升还要求 OOXML 完全一致、无动画引用且 z-order 安全;少数派页面继续使用隐藏母版图形的 `Cover` 版式。导出后处理优先按根节点 `data-pptx-page-role` 分配 `Cover`、`Agenda`、`Section`、`Closing` 或 `Content`,只有缺少根标记的旧 SVG 才回退到保守文件名判断。它可以把一家族所有页面完全一致的背景与前置 chrome 提升到该 Layout,但不做视觉相似度比较、不猜占位符,实际内容始终留在 Slide。
@@ -488,6 +492,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
| 不要用脚本批量生成 Executor SVG 页面 | 跨页设计判断依赖主代理逐页连续创作 |
| 不要把 `image_analysis.csv` 当持久缓存 | `images/` 是实时工作目录;事实必须按需重算 |
| 不要让 `svg_final/` 成为 native PPTX 默认输入 | `svg_final/` 为自包含预览而重写,native 转换需要 `svg_output/` 的高保真语义 |
+| 不要把 `svg_final/` 当作可还原形状的交换格式 | 它只保证自包含视觉预览和 SVG 图片插入;PowerPoint 手工“转换为形状”不在支持范围 |
| 不要默认开启对象级入场动画 | 页面转场是默认;对象 build 是显式导出策略 |
| 不要把 visual review、旁白、图表校准或动画定制默认塞进每次运行 | 这些工作流触发范围窄,且有额外依赖 |
| 不要用文件复制替代 `finalize_svg.py` | finalize 会嵌入图标 / 图片、展开特殊文本并准备预览产物 |
diff --git a/docs/zh/windows-installation.md b/docs/zh/windows-installation.md
index cbd8f2d7..f9cdc83c 100644
--- a/docs/zh/windows-installation.md
+++ b/docs/zh/windows-installation.md
@@ -79,17 +79,21 @@ python -c "import pptx; import fitz; print('All core dependencies OK')"
请创建一个 3 页测试 PPT,封面 + 内容页 + 封底,主题"Hello World"
```
-`exports/` 下出现 `.pptx` 且能在 PowerPoint 中打开 → **搞定了。**
+标准流程完成后应同时看到:
+
+- `exports/` 下出现由项目转换器从 `svg_output/` 生成的原生 DrawingML `.pptx`,并能在 PowerPoint 中打开、逐元素编辑。
+- 项目下生成 `svg_final/`,其中是可直接打开的自包含视觉预览 SVG;这些文件也可作为 SVG 图片手动插入 PowerPoint,但手工“转换为形状”不在支持范围。
+
+两项都满足 → **搞定了。**
---
## Step 6 — 可选增强(大多数用户可以跳过)
-装好 Python 和 `requirements.txt` 后,生成 PPT 的全部功能已经就绪。下面是**边缘场景的备用方案和增强项**——只有遇到对应的具体场景才需要装。
+装好 Python 和 `requirements.txt` 后,生成 PPT 的全部功能已经就绪。PPTX 导出直接写入原生 DrawingML 形状,不需要 CairoSVG、GTK 或另一套 SVG 栅格化环境。下面只保留一种**边缘场景的备用工具**——遇到对应需求时再装。
| 增强项 | 只在以下情况才装 | 安装方式 | 验证 |
|--------|-----------------|---------|------|
-| **CairoSVG** — 更高质量 PNG 后备图 | 你希望在不原生支持 SVG 的 Office 版本下获得更清晰的 PNG 后备图。`svglib`(已默认安装)足够大多数场景。 | 安装 [GTK3 Runtime](https://github.com/nickvdp/gtk3/releases) 后 `pip install cairosvg` | `python -c "import cairosvg"` |
| **Pandoc** — 旧格式文档 | 你需要转 `.doc`、`.odt`、`.rtf`、`.tex`、`.rst`、`.org`、`.typ`。`.docx`/`.html`/`.epub`/`.ipynb` 已由 Python 原生处理。 | [pandoc.org](https://pandoc.org/installing.html) 下载 `.msi` 安装 | `pandoc --version` |
---
diff --git a/projects/README.md b/projects/README.md
index ea77365e..e893fd91 100644
--- a/projects/README.md
+++ b/projects/README.md
@@ -32,17 +32,19 @@ project_name_format_YYYYMMDD/
│ ├── 01_xxx.svg
│ └── ...
├── templates/ # Project-level templates (if any)
-└── *.pptx
+└── exports/
+ └── *.pptx # Native DrawingML deliverables
```
Projects can remain at different stages and do not necessarily have all artifacts at once. For example:
- Only `sources/` archiving and the Design Specification & Content Outline (design_spec) are complete
- `svg_output/` has been generated, but post-processing has not yet been executed
-- `svg_final/`, `notes/`, and `*.pptx` are all complete
+- `svg_final/` is a self-contained visual preview, and `exports/*.pptx` is complete
## Notes
- Contents under this directory are excluded by `.gitignore`
+- `svg_final/` may be opened directly or inserted manually as an SVG image; PowerPoint's manual Convert to Shape behavior is not supported
- Completed projects can be moved to the `examples/` directory for sharing
- Files outside the workspace are copied by default; files within the workspace are moved directly to the project's `sources/`
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index c0e03128..3f8e85ee 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -20,7 +20,8 @@ description: >
| Any route that authors or regenerates slide visuals through SVG | `svg_output/` is the complete page-design source: every visible text, image, shape, chart/table fallback, and layout element that should appear on the exported slide is present in that page SVG or referenced by it. |
| Templates, `design_spec.md`, and `spec_lock.md` | Authoring/control inputs. They guide SVG creation but MUST NOT supply visible slide content that is absent from the completed SVG during export. |
| Semantic SVG markers | Minimal rendering-neutral compiler hints used only after existing Layout/Layer/Placeholder/Native metadata has been considered. They never replace native SVG geometry, text, styles, grouping, or asset references. |
-| SVG-to-PPTX export | Translation only: map SVG content to DrawingML/native objects and reorganize represented content into Master/Layout/Slide structure without inventing new visible page content. |
+| `svg_final/` | Mandatory derived, self-contained SVG visual preview. It may be opened directly or inserted into PowerPoint as an SVG picture, but it is not a supported PPTX source and carries no manual Convert-to-Shape compatibility contract. |
+| SVG-to-PPTX export | The only supported generated-PPTX route reads `svg_output/` and maps its content through the project converter to DrawingML/native objects. It may reorganize represented content into Master/Layout/Slide structure but MUST NOT invent new visible page content. |
| Direct PPTX and presentation-behavior workflows | Remain separate. `template-fill-pptx`, `native-enhance-pptx`, animations, transitions, speaker notes, narration, and package relationships are not required to round-trip through SVG. |
**MUST — page-design closure**: For an SVG-authoring route, inspect the final page SVG to determine what the exported slide looks like. Do not reinterpret “SVG is the page-design language” as “SVG is the complete PPTX package description language.”
@@ -653,11 +654,11 @@ Canonical three-command pipeline (this step is the workflow authority;
python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>
```
-**Step 7.2** — SVG post-processing (icon embedding / image crop & embed / raster image optimization / text flattening / rounded rect to path):
+**Step 7.2** — SVG post-processing (icon embedding / image crop & embed / raster image optimization / text flattening):
```bash
python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>
```
-Default raster handling for `svg_final/`: images are embedded at the rendered SVG size budget (`--image-scale 2`, `--max-dimension 2560`), opaque PNG photos may be written as JPEG, and transparent assets remain PNG. Use `--no-compress` or a higher `--max-dimension` only for diagnostic / high-fidelity SVG snapshots.
+This mandatory step writes self-contained visual-preview SVGs to `svg_final/`. Those files may be opened directly or manually inserted into PowerPoint as SVG pictures. Default raster handling embeds images at the rendered SVG size budget (`--image-scale 2`, `--max-dimension 2560`); opaque PNG photos may be written as JPEG, and transparent assets remain PNG. The existing EMF/WMF exception still applies: Office vector assets stay externally referenced for lossless native-PPTX passthrough, so the native PPTX remains the source of truth for pages that use them. Use `--no-compress` or a higher `--max-dimension` only for diagnostic / high-fidelity SVG previews.
**Step 7.3** — Export PPTX (embeds speaker notes by default):
```bash
@@ -668,9 +669,6 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
# backup/<timestamp>/templates/{native_structure.json,source_template.pptx}
# ← preserve mode only
# backup/<timestamp>/spec_lock.md ← preserve mode only
-#
-# Add --svg-snapshot to additionally emit the SVG-image preview pptx alongside the native pptx:
-# exports/<project_name>_<timestamp>_svg.pptx ← SVG preview pptx (reads svg_final/)
# Add --native-objects to emit real editable chart/table objects instead of flattened shapes:
# exports/<project_name>_<timestamp>_native_charts.pptx ← native chart/table objects (data-pptx-native markers)
# Re-export with --recorded-narration audio (generate-audio workflow) embeds per-slide narration:
@@ -691,11 +689,19 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> The `svg_output/`
> snapshot in `backup/<timestamp>/` is always written so the project can be
> re-exported from frozen SVG sources without re-running the LLM. The SVG-rendered
-> preview pptx is opt-in via `--svg-snapshot`. Preserve mode also backs up the
-> paired native structure/source files and `spec_lock.md` under the same timestamp.
-> Live preview already provides the
-> SVG visual reference, so it's only needed when you want a self-contained file
-> to share. Pass `-s output` or `-s final` to force a single source if you need it.
+> preview remains the mandatory `svg_final/` artifact from Step 7.2; it is not
+> packaged as a second PPTX. Preserve mode also backs up the paired native
+> structure/source files and `spec_lock.md` under the same timestamp. Use the
+> default source selection for release exports. `-s final` is diagnostic-only
+> when comparing conversion behavior against the post-processed SVGs; it does
+> not change `svg_output/` ownership or establish a supported release route.
+
+> **Supported PPTX boundary** — the only supported generated-PPTX path is
+> `svg_output/` → the project SVG-to-DrawingML converter → native PPTX. The
+> project does not emit an SVG-image PPTX and does not support PowerPoint's
+> manual **Convert to Shape** operation on `svg_final/`. Inserted `svg_final/`
+> pages remain ordinary SVG pictures unless the user independently accepts the
+> results of an unsupported Office conversion.
> **PPTX structure mode** — native export first reads
> `spec_lock.md` `pptx_structure.mode`, then falls back to `baseline` when the
@@ -825,9 +831,7 @@ Do NOT call `notes_to_audio.py` directly without going through the workflow —
Full effect list, anchor logic, and limits: [`references/animations.md`](references/animations.md).
> ❌ **NEVER** substitute `cp` for `finalize_svg.py` — finalize performs multiple critical processing steps
-> ❌ **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` in the standard pipeline. Keep it only for explicit
-> one-product diagnostics or compatibility checks.
+> ❌ **NEVER** use `-s final` for a release export. It is a diagnostic comparison only; the supported native route reads `svg_output/`.
> **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 (`Changes saved to svg_output...` / `修改已保存到 svg_output...`), 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.
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.md
index 091c17fc..95f3ccc5 100644
--- a/skills/ppt-master/references/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -9,7 +9,7 @@ PPT Master's exported PPTX supports **page transitions** (slide-to-slide) and **
| Page transition | `fade`, 0.4s | Calm baseline that suits most decks |
| Per-element animation | **`none` (off)** | A page appears as a whole. Auto-firing element builds are an unsolicited "AI deck" tell, so element entrance is opt-in. Turn it on with `-a auto` (or another effect): effects map from group id (chart→wipe, card-/step-/pillar-→fly, title/takeaway→fade); image-like ids (`hero` / `figure-` / `image` / `img-` / `kpi`) cycle a richer visual pool (zoom / dissolve / circle / box / diamond / wheel) so multiple images vary across the deck; unmatched ids cycle a small fade/wipe/fly/zoom pool |
-To regenerate a deck with different settings, rerun `svg_to_pptx.py` against the same `svg_output/` (or `svg_final/`) — no need to rerun the LLM. To turn per-element animation on for the whole deck, pass `-a auto`.
+To regenerate a deck with different settings, rerun `svg_to_pptx.py` against the same `svg_output/` — no need to rerun the LLM. `-s final` is reserved for diagnostic comparison and is not a supported release source. To turn per-element animation on for the whole deck, pass `-a auto`.
## Custom Object-Level Animation
@@ -141,9 +141,9 @@ Executors should wrap logical sections in `<g id>` regardless of whether you pla
## Limitations
-- **Native shapes mode only.** Per-element animation needs editable shape anchors. `--only legacy` produces one image per slide and has no element granularity to animate; that mode is unaffected by `-a/--animation` and only honors `-t/--transition`.
+- **Native DrawingML output only.** Page transitions and per-element animations are authored on the PPTX produced by the project converter from `svg_output/`. `svg_final/` remains a static SVG visual preview, not an animated or alternate PPTX route.
- **Office version drift on element animations.** Effects use the `<p:animEffect filter=...>` path (vs. `presetID` lookup tables) to stay stable across Office versions. Most filters render identically in PowerPoint 2016+; older Office may downgrade some filters to plain Appear.
-- **PNG fallback (compat mode) is for visual rendering only.** Transitions and animations live in the slide XML, not in the PNG, so disabling compat mode does not affect either layer.
+- **Manual SVG shape conversion is unsupported.** Inserting an `svg_final/` page as an SVG picture does not establish element animation anchors; use the native PPTX when editable animated shapes are required.
## Quick Reference
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.md
index c7d31820..e23214a8 100644
--- a/skills/ppt-master/references/artifact-ownership.md
+++ b/skills/ppt-master/references/artifact-ownership.md
@@ -27,8 +27,8 @@ Global artifact ownership rules for PPT Master projects.
| `svg_output/` | Page-design author source | Main-agent handwritten SVG pages containing the complete visible design | Quality checker and native PPTX export read this as the canonical visual/page-layout source; templates and locks do not add missing visible objects at export |
| `notes/total.md` | Speaker-note source | Complete notes before splitting | Step 6 writes; Step 7.1 splits |
| `notes/slide_*.md` | Split notes | Per-slide notes generated from `total.md` | Derived by `total_md_split.py` |
-| `svg_final/` | Derived preview/export SVGs | Self-contained post-processed SVGs | Rebuild from `svg_output/` with `finalize_svg.py` |
-| `exports/` | Delivery artifacts | Native PPTX and optional SVG snapshot PPTX | Step 7.3 writes final outputs |
+| `svg_final/` | Derived visual preview | Self-contained post-processed SVGs that may be opened directly or inserted as SVG pictures | Rebuild from `svg_output/` with `finalize_svg.py`; do not use as a supported PPTX source |
+| `exports/` | Delivery artifacts | Native DrawingML PPTX and its explicit native-object/narration variants | Step 7.3 writes final outputs from `svg_output/` |
| `backup/<timestamp>/svg_output/` | Frozen author-source archive | Re-export source without re-running LLM | `svg_to_pptx.py` writes a snapshot during export |
| `animations.json` | Optional animation config | Object-level animation sidecar | Created only by explicit animation workflow/request |
@@ -46,8 +46,9 @@ Global artifact ownership rules for PPT Master projects.
| SVG source | `svg_output/` is the only author source for generated pages. |
| Page-design closure | On SVG-authoring routes, every visible exported-slide object exists in the corresponding page SVG or an explicitly referenced visual asset. |
| Package-behavior separation | Speaker notes, animations, transitions, narration, and direct native-PPTX workflows keep their owning artifacts; do not force them into SVG metadata. |
-| Post-processed SVG | `svg_final/` is disposable and must be rebuildable from `svg_output/`. |
-| Export source | Native PPTX export reads `svg_output/` by default. SVG snapshot export reads `svg_final/` only when requested. |
+| Post-processed SVG | `svg_final/` is disposable, must be rebuilt in Step 7.2, and serves only as a self-contained visual preview / manually insertable SVG picture. |
+| Export source | The only supported generated-PPTX route reads `svg_output/` through the project SVG-to-DrawingML converter. A diagnostic `-s final` override does not change ownership or create a supported release route. |
+| Shape-conversion boundary | PowerPoint's manual Convert-to-Shape operation on `svg_final/` is outside the project compatibility contract. |
| Confirmation | Final `confirm_ui/result.json` or chat confirmation overrides recommendations. |
**Forbidden - mixed ownership**: Do not copy chart values from Markdown into `analysis/` by hand, do not edit `svg_final/` as the source of a fix, and do not treat `design_spec.md` prose as a replacement for `spec_lock.md`.
@@ -62,6 +63,5 @@ Global artifact ownership rules for PPT Master projects.
| `notes/slide_*.md` | `notes/total.md` | `python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>` |
| `svg_final/` | `svg_output/` plus project assets | `python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>` |
| Native PPTX | `svg_output/` plus notes/assets | `python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>` |
-| SVG snapshot PPTX | `svg_final/` | `svg_to_pptx.py --svg-snapshot` |
**Default - regenerate derived views**: When a source artifact changes, regenerate the derived artifact at the owning step instead of patching the derived file directly.
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index b6b4d691..9ce469ad 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -6,6 +6,8 @@
**Hard rule — minimal semantics without semantic loss**: `baseline` / free-design roots declare `data-pptx-page-role`; `template` / `preserve` roots already use `data-pptx-layout` and do not duplicate that identity. Add `data-pptx-role` only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by layer, placeholder, or native-object metadata; the marked element uses a stable unique `id`. Ordinary page content keeps normal SVG structure without duplicate semantic classification. See [`semantic-svg.md`](./semantic-svg.md).
+**Hard rule — supported PPTX route**: The only supported generated-PPTX path is `svg_output/` through the project SVG-to-DrawingML converter. Step 7.2 still generates `svg_final/` as a mandatory self-contained visual preview that may be inserted as an SVG picture. Do not treat PowerPoint's manual Convert-to-Shape operation as an authoring target or compatibility requirement.
+
> Note: this rule covers page design only. Speaker notes, animations, transitions, narration, and direct native-PPTX workflows retain their separate artifacts and package-level processing.
---
@@ -506,15 +508,15 @@ Auto-split `notes/total.md` into per-page files in `notes/`.
# 1. Split speaker notes
python3 scripts/total_md_split.py <project_path>
-# 2. SVG post-processing (auto-embed icons, images, etc.)
+# 2. SVG post-processing (auto-embed icons/images and flatten positioned text)
python3 scripts/finalize_svg.py <project_path>
+# Output: svg_final/ self-contained SVG visual previews
# 3. Export PPTX
python3 scripts/svg_to_pptx.py <project_path>
# Output (default-flow mode):
# exports/<project_name>_<timestamp>.pptx ← native pptx (canonical output)
# backup/<timestamp>/svg_output/ ← Executor SVG source backup (always written)
-#
-# Add --svg-snapshot to additionally emit:
-# exports/<project_name>_<timestamp>_svg.pptx ← SVG snapshot pptx (sibling of native pptx)
```
+
+`svg_final/` may be opened directly or manually inserted into PowerPoint as an SVG picture. It is not a second PPTX route. Use `-s final` only for converter diagnostics; release exports use the default `svg_output/` source. Manual Convert-to-Shape behavior is unsupported.
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index 639f203c..e52e05d0 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -252,6 +252,8 @@ These forms are needed only when the stated PPT behavior matters:
| Native PowerPoint background promotion | Use a direct, full-canvas, solid `<rect>` without transform, filter, clip, rounding, or visible stroke. Other SVG backgrounds remain ordinary slide shapes. Template routes add the ownership metadata in §7. |
| Free-design page family/chrome extraction | Use the semantic markers in §4.1. Marker-free pages retain conservative filename/id fallbacks, but no visual content is inferred. |
+**Hard rule — supported shape conversion**: Every PPT editability claim in this specification refers to the project converter reading `svg_output/` and emitting native DrawingML. `svg_final/` is a self-contained visual preview that may be inserted into PowerPoint as an SVG picture. PowerPoint's manual Convert-to-Shape operation is unsupported; do not narrow the authoring contract to its undocumented SVG subset.
+
---
## 5. Workflow Authority
diff --git a/skills/ppt-master/references/svg-image-embedding.md b/skills/ppt-master/references/svg-image-embedding.md
index aeaf730c..e761661d 100644
--- a/skills/ppt-master/references/svg-image-embedding.md
+++ b/skills/ppt-master/references/svg-image-embedding.md
@@ -56,7 +56,9 @@ Defined in the Design Specification & Content Outline; each image carries an `Ac
5. Post-processing & Export → follow [`SKILL.md` Step 7](../SKILL.md)
```
-> Keep external references in `svg_output/` during generation. `finalize_svg.py` auto-embeds images into `svg_final/`; export PPTX from `svg_final/`.
+> Keep external references in `svg_output/` during generation. `finalize_svg.py` auto-embeds images into the mandatory `svg_final/` visual preview; native PPTX export independently reads `svg_output/`.
+
+**Hard rule — export boundary**: `svg_final/` is a self-contained SVG preview for embeddable raster/SVG assets and may be manually inserted into PowerPoint as an SVG picture. EMF/WMF assets retain the documented external-reference exception for lossless native passthrough. The only supported generated-PPTX route is `svg_output/` through the project SVG-to-DrawingML converter. PowerPoint's manual Convert-to-Shape operation is unsupported.
---
@@ -65,7 +67,7 @@ Defined in the Design Specification & Content Outline; each image carries an `Ac
| Method | Pros | Cons | Suitable For |
|--------|------|------|-------------|
| **External reference** | Small file size, fast iteration, easy to replace | Preview requires HTTP server from project root | `svg_output/` development phase |
-| **Base64 embedding** | Self-contained file, stable export | Large file size | `svg_final/` delivery phase |
+| **Base64 embedding** | Self-contained file, stable direct preview / SVG-picture insertion | Large file size | `svg_final/` preview phase |
---
@@ -106,7 +108,7 @@ python3 -m http.server -d <project_path> 8000
---
-## Method 2: Base64 Embedding (Recommended for Delivery Phase)
+## Method 2: Base64 Embedding (Recommended for Preview Phase)
### Syntax
@@ -128,7 +130,7 @@ python3 -m http.server -d <project_path> 8000
## Conversion Process
-Use the unified pipeline in [`SKILL.md` Step 7](../SKILL.md). `finalize_svg.py` runs before export so image references in `svg_output/` become embedded assets in `svg_final/`.
+Use the unified pipeline in [`SKILL.md` Step 7](../SKILL.md). `finalize_svg.py` remains mandatory and embeds image references into the self-contained `svg_final/` preview. The following PPTX command still reads `svg_output/` by default and converts it directly to native DrawingML; it does not consume `svg_final/` in the supported release route.
```bash
python3 scripts/finalize_svg.py <project_path>
@@ -169,7 +171,7 @@ project/
├── sources/ # Source files and their accompanying images
│ └── article_files/
├── svg_output/ # Raw version (external references)
-└── svg_final/ # Final version (images embedded)
+└── svg_final/ # Derived self-contained visual preview (images embedded)
```
### Rounded Corner / Non-rectangular Image Cropping
diff --git a/skills/ppt-master/requirements.txt b/skills/ppt-master/requirements.txt
index 8b34c01d..273f5123 100644
--- a/skills/ppt-master/requirements.txt
+++ b/skills/ppt-master/requirements.txt
@@ -12,8 +12,8 @@
# ─────────────────────────────────────────────────────────────
# Batch-convert SVG files to PowerPoint presentations.
# 用于将 SVG 文件批量转换为 PowerPoint 演示文稿
-# Uses Office-compatible mode (PNG + SVG dual format) by default, supports all Office versions.
-# 默认使用 Office 兼容模式(PNG + SVG 双格式),支持所有 Office 版本
+# Converts supported SVG elements to editable native DrawingML shapes.
+# 将受支持的 SVG 元素转换为可编辑的原生 DrawingML 形状
python-pptx>=0.6.21
XlsxWriter>=3.0.0
@@ -22,19 +22,6 @@ XlsxWriter>=3.0.0
# notes_to_audio.py 用于在 macOS/Linux/Windows 上生成逐页旁白音频。
edge-tts>=7.2.8
-# Office compatibility dependencies (choose one, CairoSVG preferred)
-# Office 兼容模式依赖(二选一,优先使用 cairosvg)
-# Converts SVG to PNG fallback images for Office LTSC 2021 etc.
-# 用于将 SVG 转换为 PNG 后备图片,确保 Office LTSC 2021 等版本正常显示
-#
-# Option A / 方案 A: CairoSVG (recommended / 推荐, ~25MB, full gradient/filter support)
-# pip install cairosvg
-# macOS: brew install cairo
-#
-# Option B / 方案 B: svglib (lightweight / 轻量, ~5MB, some gradients may be lost)
-svglib>=1.5.0
-reportlab>=4.0.0
-
# ─────────────────────────────────────────────────────────────
# PDF to Markdown tool / PDF 转 Markdown 工具 (skills/ppt-master/scripts/source_to_md/pdf_to_md.py)
# ─────────────────────────────────────────────────────────────
@@ -76,8 +63,8 @@ openpyxl>=3.1.0
# ─────────────────────────────────────────────────────────────
# Image processing tools / 图片处理工具
# ─────────────────────────────────────────────────────────────
-# fix_image_aspect.py - Fix image aspect ratio (prevent stretching during PPT shape conversion)
-# fix_image_aspect.py - 修复图片宽高比(防止 PPT 转形状时拉伸)
+# fix_image_aspect.py - Normalize image boxes for PowerPoint SVG rendering diagnostics
+# fix_image_aspect.py - 为 PowerPoint SVG 渲染诊断归一化图片框
# gemini_watermark_remover.py - Remove watermarks from Gemini-generated images
# gemini_watermark_remover.py - 去除 Gemini 生成图片的水印
Pillow>=9.0.0
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 9fef3b2f..1bd0d10f 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -116,6 +116,8 @@ python3 scripts/svg_to_pptx.py <project_path>
`finalize_svg.py` optimizes raster images by default using `2x` display pixels and max `2560px`. Native `svg_to_pptx.py` defaults to `--image-sizing cap`: only oversized full source images are reduced to max `2560px`, so later PowerPoint resizing keeps more image detail. Use `svg_to_pptx.py --image-sizing display --image-scale 2` only for aggressive size reduction, or `--no-image-optimize` when the native PPTX must embed original image bytes.
+`finalize_svg.py` remains mandatory because it creates the self-contained `svg_final/` visual preview. Those SVGs may be opened directly or inserted into PowerPoint as SVG pictures. The only supported generated-PPTX path is `svg_output/` through the project SVG-to-DrawingML converter; `-s final` is diagnostic-only, and PowerPoint's manual Convert-to-Shape operation is unsupported.
+
For SVG-authoring routes, `svg_output/` is the complete visible page-design source: every exported text, image, shape, background, and template-derived layout element is present in the page SVG or explicitly referenced by it. Export may translate represented content into Master/Layout/Slide parts or native objects, but it does not retrieve missing visible content from templates or planning files. Speaker notes, animation, narration, transitions, `template-fill-pptx`, and `native-enhance-pptx` remain separately owned capabilities.
When `spec_lock.md` has no `pptx_structure` section, native `svg_to_pptx.py` falls back to `baseline`: the generated deck keeps a standard Master/Layout relationship and promotes only exact, z-order-safe shared backgrounds/chrome. Root `data-pptx-page-role` selects `Cover`, `Agenda`, `Section`, `Closing`, or `Content`; filenames are a fallback for marker-free legacy SVGs. A family-wide exact background and an exact leading structurally marked chrome prefix may move into that Layout; ids are consulted only when the structural role is absent. Actual titles, body content, pictures, charts, tables, page numbers, and page-specific shapes remain on Slide. No visual-similarity or placeholder inference is performed. Baseline also prunes unused layouts and maps locked typography/colors into the PowerPoint theme. Use `--pptx-structure flat` for slide-local diagnostics.
@@ -154,7 +156,7 @@ python3 scripts/update_repo.py --skip-pip
- Keep one user-facing entry point per workflow at the top level of `scripts/`
- Move provider-specific or helper internals into subdirectories
- Prefer the unified entry points `project_manager.py`, `finalize_svg.py`, and `image_gen.py`
-- Use `svg_output/` for native export and `svg_final/` for SVG snapshot/preview export
+- Use `svg_output/` for the only supported native PPTX export and `svg_final/` for self-contained SVG visual preview / picture insertion
## Related Docs
@@ -165,4 +167,4 @@ python3 scripts/update_repo.py --skip-pip
- [Troubleshooting](./docs/troubleshooting.md)
- [Skill Entry](../SKILL.md)
-_Last updated: 2026-07-10_
+_Last updated: 2026-07-11_
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 23b897df..a0a3ba14 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -4,6 +4,8 @@
These tools cover post-processing, SVG validation, speaker notes, recorded narration, and PPTX export.
+The supported delivery contract has one PPTX path: `svg_output/` → the project SVG-to-DrawingML converter → native PPTX. The mandatory `finalize_svg.py` step separately creates self-contained `svg_final/` visual previews, which may be opened directly or inserted into PowerPoint as SVG pictures. There is no SVG-image PPTX output, and PowerPoint's manual Convert-to-Shape operation is unsupported.
+
## Recommended Pipeline
Run these steps in order:
@@ -23,7 +25,8 @@ It aggregates:
- static same-document `<use>` expansion from `svg_to_pptx/use_expander.py`
- `align_embed_images.py` (`crop-images` / `fix-aspect` / `embed-images` aliases route here)
- `flatten_tspan.py`
-- `svg_rect_to_path.py`
+
+`svg_final/` remains a required Step 7.2 artifact even though the native exporter reads `svg_output/`. It is the self-contained visual reference and may be manually inserted as an SVG picture.
## `svg_to_pptx.py`
@@ -36,7 +39,9 @@ python3 scripts/svg_to_pptx.py <project_path> --pptx-structure template # expli
python3 scripts/svg_to_pptx.py <project_path> --pptx-structure preserve # imported source package contract
python3 scripts/svg_to_pptx.py <project_path> --pptx-structure flat # structure diagnostic
# Template-import visual round-trip diagnostic only:
-python3 scripts/svg_to_pptx.py <template_import_output> --only native -s svg-flat
+python3 scripts/svg_to_pptx.py <template_import_output> -s svg-flat
+# Post-processed-source comparison diagnostic only (never a release export):
+python3 scripts/svg_to_pptx.py <project_path> -s final
python3 scripts/svg_to_pptx.py <project_path> --no-notes
python3 scripts/svg_to_pptx.py <project_path> -t none
python3 scripts/svg_to_pptx.py <project_path> --auto-advance 3
@@ -50,17 +55,15 @@ Behavior:
- Default output (default-flow mode, no `-o`):
- `exports/<project_name>_<timestamp>.pptx` — native editable pptx (canonical output)
- `backup/<timestamp>/svg_output/` — copy of Executor SVG source, always written so the pptx can be rebuilt via `finalize_svg → svg_to_pptx` without re-running the LLM
-- `--svg-snapshot` (opt-in) additionally emits:
- - `exports/<project_name>_<timestamp>_svg.pptx` — SVG snapshot pptx for visual reference, sibling of the native pptx
- - Live preview already serves as the SVG visual reference for day-to-day use; the snapshot pptx is for distribution or frozen-state archival
-- Explicit `-o/--output` skips `backup/`; pair with `--svg-snapshot` to also emit the side-by-side `_svg.pptx` next to the chosen path
+- `finalize_svg.py` always creates `svg_final/` before export. This directory is the self-contained SVG visual preview; it is not packaged as a second PPTX.
+- Explicit `-o/--output` changes the native PPTX destination and skips `backup/`.
- Paragraph merging is enabled by default and trades some SVG line-layout fidelity for PowerPoint editability:
- Default: mergeable paragraph blocks (same x, dy clustered around one base line-height, optional larger gap for paragraph breaks) collapse into one editable text frame with multiple `<a:p>` and precise `<a:lnSpc>` / `<a:spcBef>`. Resizing the box reflows text inside it.
- With `--no-merge`: every dy-stacked `<tspan>` becomes its own text frame — exact SVG line layout is preserved but a 12-line paragraph is 12 separate textboxes
- Side effect: PowerPoint may wrap merged paragraphs to a different line count than the SVG source. Long body text (abstracts, multi-paragraph sections, reference lists) usually benefits from the default; pages with tight typographic alignment (covers, charts, tables) usually want `--no-merge`
- Mergeable detection is conservative: only fires when the children form a clean paragraph block; mixed-layout `<text>` falls through to the default per-line path
-- Native export reads `svg_output/`; `--svg-snapshot` and legacy export read
- `svg_final/`. Use `-s` only as an explicit diagnostic override.
+- Native release export reads `svg_output/`. `-s final` is an explicit diagnostic override for comparing conversion behavior against post-processed SVGs; it does not change artifact ownership or create a supported release path.
+- `svg_final/` may be opened directly or inserted into PowerPoint as an SVG picture. PowerPoint's manual Convert-to-Shape operation is outside the compatibility contract.
- On every SVG-authoring route, each file in `svg_output/` is the complete visible
page-design source. Templates and locks may guide authoring, but finalize/export
never use them to overlay visible content missing from the SVG. Notes, animation,
@@ -103,12 +106,6 @@ Behavior:
- `--animation-duration` controls per-element entrance length (default `0.4`); `--animation-stagger` adds gap between elements in `after-previous` mode (default `0.5`)
- Optional object-level overrides live in `<project>/animations.json` or a path passed via `--animation-config`; build and validate them with `animation_config.py scaffold|validate`
-Performance (legacy `_svg.pptx` PNG fallback, only when `--svg-snapshot` or `--only legacy`):
-- SVG→PNG is pre-rendered in a process pool before the main loop. Default workers = `min(cpu, pages, 8)`; override with `--workers N` (set `1` for sequential, `0` is treated as sequential).
-- Results are cached at `<project>/.cache/svg_png/` keyed by SVG content hash + size + active renderer (`cairosvg` vs `svglib`). Switching renderers naturally invalidates the cache; nothing to clean by hand.
-- `--cache-dir <path>` relocates the cache; `--no-cache` forces re-render without writing/reading the cache (handy when debugging rendering).
-- Native mode (`--only native`) is unaffected — that path embeds DrawingML shapes and never touches PNG.
-
Dependency:
```bash
@@ -188,16 +185,6 @@ python3 scripts/svg_finalize/flatten_tspan.py examples/<project>/svg_output
python3 scripts/svg_finalize/flatten_tspan.py path/to/input.svg path/to/output.svg
```
-### `svg_rect_to_path.py`
-
-```bash
-python3 scripts/svg_finalize/svg_rect_to_path.py <project_path>
-python3 scripts/svg_finalize/svg_rect_to_path.py <project_path> -s final
-python3 scripts/svg_finalize/svg_rect_to_path.py path/to/file.svg
-```
-
-Use when rounded corners must survive PowerPoint shape conversion.
-
### `align_embed_images.py`
```bash
diff --git a/skills/ppt-master/scripts/docs/troubleshooting.md b/skills/ppt-master/scripts/docs/troubleshooting.md
index 9b177146..efb33265 100644
--- a/skills/ppt-master/scripts/docs/troubleshooting.md
+++ b/skills/ppt-master/scripts/docs/troubleshooting.md
@@ -15,12 +15,15 @@ python3 scripts/project_manager.py validate <project_path>
1. Check the file path and filename.
2. Confirm naming conventions are consistent.
-3. Preview via a local server if browser file loading is inconsistent:
+3. Run the mandatory post-processing step when you need a self-contained preview:
```bash
-python3 -m http.server --directory <svg_output_path> 8000
+python3 scripts/finalize_svg.py <project_path>
+python3 -m http.server --directory <project_path>/svg_final 8000
```
+`svg_final/` is the visual-preview artifact and may be inserted into PowerPoint as an SVG picture. Fix authored content in `svg_output/`, then regenerate `svg_final/`; do not edit the derived preview as the source.
+
## Speaker Notes Do Not Split
Check `total.md`:
@@ -44,7 +47,11 @@ python3 scripts/finalize_svg.py <project_path>
python3 scripts/svg_to_pptx.py <project_path>
```
-Do not export directly from `svg_output/` when `svg_final/` exists.
+Keep all three steps even though they have different consumers: Step 7.2 creates the mandatory `svg_final/` visual preview, while the supported native PPTX exporter reads `svg_output/` directly. Do not pass `-s final` for a release export; that override is diagnostic-only.
+
+## Inserted SVG Does Not Convert Cleanly to Shapes
+
+PowerPoint's manual Convert-to-Shape behavior is unsupported. `svg_final/` is supported only as a visual preview / SVG picture. Use the native PPTX generated from `svg_output/` when editable DrawingML shapes are required.
## Recorded Narration Missing
diff --git a/skills/ppt-master/scripts/finalize_svg.py b/skills/ppt-master/scripts/finalize_svg.py
index a95469c1..05781a47 100644
--- a/skills/ppt-master/scripts/finalize_svg.py
+++ b/skills/ppt-master/scripts/finalize_svg.py
@@ -2,9 +2,12 @@
"""
PPT Master - SVG Post-processing Tool (Unified Entry Point)
-Processes SVG files from svg_output/ and outputs them to svg_final/.
-By default, all processing steps are executed. You can also specify
-individual steps via arguments.
+Processes SVG files from svg_output/ and produces the visual preview in
+svg_final/, embedding supported raster/SVG assets. Native PPTX export continues
+to read svg_output/ by default; svg_final/ may be opened directly or inserted
+as an SVG image. EMF/WMF assets retain their external-reference exception.
+By default, all processing steps are executed. You can also specify individual
+steps via arguments.
Architecture note: this module's outputs feed svg_final/ on disk AND its
sub-modules (svg_finalize.embed_icons, svg_finalize.flatten_tspan, ...)
@@ -17,7 +20,7 @@ Usage:
python3 scripts/finalize_svg.py <project_directory>
# Execute only specific steps
- python3 scripts/finalize_svg.py <project_directory> --only embed-icons fix-rounded
+ python3 scripts/finalize_svg.py <project_directory> --only embed-icons align-images
Examples:
python3 scripts/finalize_svg.py projects/my_project
@@ -30,10 +33,8 @@ Processing options:
trio. The old names remain accepted as aliases for the
merged step, so existing --only invocations keep working.
flatten-text - Convert <tspan> to independent <text> (for special renderers)
- fix-rounded - Convert <rect rx="..."/> to <path> (for PPT shape conversion)
"""
-import os
import sys
import shutil
import argparse
@@ -101,28 +102,6 @@ def process_flatten_text(svg_file: Path, verbose: bool = False) -> bool:
return False
-def process_rounded_rect(svg_file: Path, verbose: bool = False) -> int:
- """Convert rounded rectangles in a single SVG file (in-place modification)"""
- try:
- from svg_finalize.svg_rect_to_path import process_svg
-
- with open(svg_file, 'r', encoding='utf-8') as f:
- content = f.read()
-
- processed, count = process_svg(content, verbose=False)
-
- if count > 0:
- with open(svg_file, 'w', encoding='utf-8') as f:
- f.write(processed)
- if verbose:
- safe_print(f" [OK] {svg_file.name}: {count} rounded rectangle(s)")
- return count
- except Exception as e:
- if verbose:
- safe_print(f" [ERROR] {svg_file.name}: {e}")
- return 0
-
-
def finalize_project(
project_dir: Path,
options: dict[str, bool],
@@ -189,7 +168,7 @@ def finalize_project(
# Step 2: Expand project icons, then standard same-document use references.
if options.get('embed_icons'):
if not quiet:
- safe_print("[1/4] Expanding icons + local use references...")
+ safe_print("[1/3] Expanding icons + local use references...")
icons_count = 0
for svg_file in svg_final.glob('*.svg'):
count = embed_icons_in_file(
@@ -241,7 +220,7 @@ def finalize_project(
# from disk once.
if options.get('align_images'):
if not quiet:
- safe_print("[2/4] Aligning + embedding images...")
+ safe_print("[2/3] Aligning + embedding images...")
img_count = 0
img_errors = 0
office_vector_count = 0
@@ -279,7 +258,7 @@ def finalize_project(
# Step 4: Flatten text
if options.get('flatten_text'):
if not quiet:
- safe_print("[3/4] Flattening text...")
+ safe_print("[3/3] Flattening text...")
flatten_count = 0
for svg_file in svg_final.glob('*.svg'):
if process_flatten_text(svg_file, verbose=False):
@@ -290,20 +269,6 @@ def finalize_project(
else:
safe_print(" No processing needed")
- # Step 5: Convert rounded rects to Path
- if options.get('fix_rounded'):
- if not quiet:
- safe_print("[4/4] Converting rounded rects to Path...")
- rounded_count = 0
- for svg_file in svg_final.glob('*.svg'):
- count = process_rounded_rect(svg_file, verbose=False)
- rounded_count += count
- if not quiet:
- if rounded_count > 0:
- safe_print(f" {rounded_count} rounded rectangle(s) converted")
- else:
- safe_print(" No rounded rectangles")
-
# Done
if not quiet:
print()
@@ -323,14 +288,13 @@ def main() -> None:
epilog='''
Examples:
%(prog)s projects/my_project # Execute all processing (default)
- %(prog)s projects/my_project --only embed-icons fix-rounded
+ %(prog)s projects/my_project --only embed-icons align-images
%(prog)s projects/my_project -q # Quiet mode
Processing options (for --only):
embed-icons Expand project icons and static same-document <use>
align-images Align (slice/meet) + Base64-embed all <image> (single pass)
flatten-text Flatten text
- fix-rounded Convert rounded rects to Path
Aliases (still accepted):
crop-images, fix-aspect, embed-images → all map to align-images
@@ -345,7 +309,7 @@ Aliases (still accepted):
'align-images',
# Backwards-compatible aliases — all three map to align-images now.
'crop-images', 'fix-aspect', 'embed-images',
- 'flatten-text', 'fix-rounded',
+ 'flatten-text',
],
help=('Execute only specified processing steps (default: all). '
'crop-images / fix-aspect / embed-images are accepted as '
@@ -381,7 +345,6 @@ Aliases (still accepted):
'embed_icons': 'embed-icons' in only,
'align_images': bool(only & _ALIGN_ALIASES),
'flatten_text': 'flatten-text' in only,
- 'fix_rounded': 'fix-rounded' in only,
}
else:
# Execute all by default
@@ -389,7 +352,6 @@ Aliases (still accepted):
'embed_icons': True,
'align_images': True,
'flatten_text': True,
- 'fix_rounded': True,
}
if args.max_dimension < 1:
diff --git a/skills/ppt-master/scripts/project_manager.py b/skills/ppt-master/scripts/project_manager.py
index ac92bb8d..1fd744dd 100644
--- a/skills/ppt-master/scripts/project_manager.py
+++ b/skills/ppt-master/scripts/project_manager.py
@@ -167,7 +167,7 @@ class ProjectManager:
f"- Created: {date_str}\n\n"
"## Directories\n\n"
"- `svg_output/`: raw SVG output\n"
- "- `svg_final/`: finalized SVG output\n"
+ "- `svg_final/`: self-contained SVG visual preview; may be inserted manually as an SVG image, but PowerPoint Convert to Shape is unsupported\n"
"- `images/`: runtime image pool; converter assets keep their original short filenames when possible\n"
"- `icons/`: project icon set — selected library icons copied in (via icon_sync.py) plus any custom icons you add; embedded from here at export\n"
"- `notes/`: speaker notes\n"
@@ -175,7 +175,7 @@ class ProjectManager:
"- `live_preview/`: browser preview runtime files and history (lock.json, server.log, edits.jsonl, annotations.jsonl)\n"
"- `sources/`: source materials and normalized markdown\n"
"- `analysis/`: machine-extracted intermediate analysis (PPTX intake, image_analysis.csv) — the pipeline's canonical must-read source/asset facts\n"
- "- `exports/`: main native pptx (timestamped); `_svg.pptx` sibling added with `--svg-snapshot`, `_native_charts.pptx` name with `--native-objects`, `_narrated.pptx` name when narration audio is embedded\n"
+ "- `exports/`: native DrawingML pptx (timestamped); `_native_charts.pptx` name with `--native-objects`, `_narrated.pptx` name when narration audio is embedded\n"
"- `backup/<timestamp>/`: svg_output/ archive (always written in default-flow mode; safe to delete old timestamps)\n"
),
encoding="utf-8",
diff --git a/skills/ppt-master/scripts/svg_finalize/align_embed_images.py b/skills/ppt-master/scripts/svg_finalize/align_embed_images.py
index 1759c1c7..7c0f12e0 100644
--- a/skills/ppt-master/scripts/svg_finalize/align_embed_images.py
+++ b/skills/ppt-master/scripts/svg_finalize/align_embed_images.py
@@ -9,12 +9,12 @@ Replaces the previous three independent finalize_svg steps:
reference points to a pre-cropped asset.
fix-aspect → for each <image>, read the source bitmap dimensions and
adjust x/y/width/height so the rendered box matches the
- image aspect ratio (PowerPoint's "Convert to Shape"
- ignores preserveAspectRatio and stretches otherwise).
- embed-images → Base64-inline every external image reference so the
- legacy/preview pptx (which packages the SVG verbatim)
- can resolve them — pptx-internal SVG cannot follow
- ``../images/…`` relative URIs.
+ image aspect ratio in PowerPoint SVG rendering paths that
+ do not honor preserveAspectRatio consistently.
+ embed-images → Base64-inline every embeddable external image reference
+ so ``svg_final/`` remains portable when opened or manually
+ inserted as an SVG image. EMF/WMF keep the documented
+ external-reference exception.
Why merge: each step independently parsed + serialized the SVG, each step
re-read the same bitmap from disk, and the two spatial transforms (crop and
diff --git a/skills/ppt-master/scripts/svg_finalize/fix_image_aspect.py b/skills/ppt-master/scripts/svg_finalize/fix_image_aspect.py
index b9297577..1e47a6ce 100644
--- a/skills/ppt-master/scripts/svg_finalize/fix_image_aspect.py
+++ b/skills/ppt-master/scripts/svg_finalize/fix_image_aspect.py
@@ -3,11 +3,12 @@
SVG Image Aspect Ratio Fix Tool
Fixes the dimensions of <image> elements in SVG to match the original image aspect ratio.
-This prevents images from being stretched when PowerPoint converts SVG to editable shapes.
+This prevents images from being stretched by PowerPoint SVG rendering paths that do not
+honor preserveAspectRatio consistently.
Principle:
- When PowerPoint converts SVG to editable shapes, it ignores the preserveAspectRatio attribute
- and directly stretches the image to fill the area specified by width/height.
+ Some PowerPoint SVG rendering paths ignore the preserveAspectRatio attribute and directly
+ stretch the image to fill the area specified by width/height.
This tool reads the actual image aspect ratio and recalculates the x, y, width, height of
<image> elements so that images are centered and maintain their original aspect ratio.
@@ -331,7 +332,7 @@ def fix_image_aspect_in_svg(svg_path: str, dry_run: bool = False, verbose: bool
def main() -> None:
"""Run the CLI entry point."""
parser = argparse.ArgumentParser(
- description='Fix image aspect ratios in SVG to prevent stretching when PowerPoint converts to shapes',
+ description='Normalize SVG image boxes for PowerPoint SVG rendering diagnostics',
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog='''
Examples:
diff --git a/skills/ppt-master/scripts/svg_finalize/svg_rect_to_path.py b/skills/ppt-master/scripts/svg_finalize/svg_rect_to_path.py
index 128a256a..b793bac9 100644
--- a/skills/ppt-master/scripts/svg_finalize/svg_rect_to_path.py
+++ b/skills/ppt-master/scripts/svg_finalize/svg_rect_to_path.py
@@ -1,9 +1,10 @@
#!/usr/bin/env python3
"""
-PPT Master - SVG Rounded Rectangle to Path Tool
+PPT Master - Legacy SVG Rounded Rectangle Diagnostic
-Solves the issue of rounded corners being lost when using "Convert to Shape" in PowerPoint:
-Converts <rect> elements with rx/ry to equivalent <path> elements.
+Historical diagnostic that converts <rect> elements with rx/ry to equivalent
+<path> elements. It is not part of finalize_svg.py or the supported export
+workflow; PowerPoint's manual "Convert to Shape" behavior is not supported.
Usage:
python3 scripts/svg_finalize/svg_rect_to_path.py <SVG file or directory>
@@ -235,7 +236,7 @@ def find_svg_files(project_path: Path, source: str = 'output') -> tuple[list[Pat
def main() -> None:
"""Run the CLI entry point."""
parser = argparse.ArgumentParser(
- description='PPT Master - SVG Rounded Rectangle to Path Tool',
+ description='PPT Master - Legacy SVG Rounded Rectangle Diagnostic',
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog='''
Examples:
@@ -245,7 +246,7 @@ Examples:
What it does:
Converts <rect> elements with rx/ry to equivalent <path> elements.
- Processed SVGs preserve rounded corners when using "Convert to Shape" in PowerPoint.
+ Legacy diagnostic only; the standard pipeline preserves SVG rounded rectangles.
'''
)
@@ -269,7 +270,7 @@ What it does:
quiet = args.quiet
if not quiet:
- print("PPT Master - SVG Rounded Rectangle to Path Tool")
+ print("PPT Master - Legacy SVG Rounded Rectangle Diagnostic")
print("=" * 50)
total_converted = 0
diff --git a/skills/ppt-master/scripts/svg_to_pptx.py b/skills/ppt-master/scripts/svg_to_pptx.py
index 13d83aff..4f091d7b 100644
--- a/skills/ppt-master/scripts/svg_to_pptx.py
+++ b/skills/ppt-master/scripts/svg_to_pptx.py
@@ -1,7 +1,8 @@
#!/usr/bin/env python3
"""PPT Master - SVG to PPTX Tool (thin wrapper).
-Delegates to the svg_to_pptx package. Kept for CLI backward compatibility:
+Delegates to the svg_to_pptx package. ``-s final`` remains a native-export
+diagnostic override; the standard pipeline reads ``svg_output/``:
python3 scripts/svg_to_pptx.py <project_path> -s final
"""
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
index f98afa3c..ebb57404 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
@@ -3220,7 +3220,7 @@ def create_pptx_with_native_svg(
use_compat_mode: bool = True,
notes: dict[str, str] | None = None,
enable_notes: bool = True,
- use_native_shapes: bool = False,
+ use_native_shapes: bool = True,
animation: str | None = None,
animation_duration: float = 0.4,
animation_stagger: float = 0.5,
@@ -3246,7 +3246,7 @@ def create_pptx_with_native_svg(
theme_font_spec: ThemeFontSpec | None = None,
theme_color_spec: ThemeColorSpec | None = None,
) -> bool:
- """Create a PPTX file with native SVG.
+ """Create a PPTX file with native DrawingML shapes.
Args:
svg_files: List of SVG files.
@@ -3256,10 +3256,10 @@ def create_pptx_with_native_svg(
transition: Transition effect name.
transition_duration: Transition duration in seconds.
auto_advance: Auto-advance interval in seconds.
- use_compat_mode: Use Office compatibility mode (PNG + SVG dual format).
+ use_compat_mode: Retained for API compatibility; ignored in native mode.
notes: Notes dict, key is SVG stem, value is notes content.
enable_notes: Whether to enable notes embedding.
- use_native_shapes: Convert SVG to native DrawingML shapes.
+ use_native_shapes: Must remain true; SVG-image PPTX export is unsupported.
animation: Per-element entrance animation mode (single effect name,
'mixed', 'random', or None to disable). Native shapes mode only.
animation_duration: Per-element entrance duration in seconds.
@@ -3300,13 +3300,16 @@ def create_pptx_with_native_svg(
Returns:
Whether all slides were successfully created.
"""
+ if not use_native_shapes:
+ raise ValueError(
+ "SVG-image PPTX export is no longer supported; use svg_final/ "
+ "directly for preview and native DrawingML PPTX for delivery"
+ )
if not svg_files:
print("Error: No SVG files found")
return False
- # Native shapes mode takes priority over compat mode
- if use_native_shapes:
- use_compat_mode = False
+ use_compat_mode = False
if pptx_structure not in {"baseline", "template", "preserve", "flat"}:
raise ValueError(f"Unsupported pptx_structure: {pptx_structure}")
if use_native_shapes and pptx_structure == "template":
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
index 59e92eff..24ed6314 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
@@ -114,13 +114,11 @@ def main(argv: list[str] | None = None) -> int:
)
parser = argparse.ArgumentParser(
- description='PPT Master - SVG to PPTX Tool (Office Compatibility Mode)',
+ description='PPT Master - SVG to native DrawingML PPTX Tool',
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=f'''
Examples:
%(prog)s examples/ppt169_demo # Default: native pptx -> exports/, svg_output -> backup/<ts>/
- %(prog)s examples/ppt169_demo --svg-snapshot # Also emit SVG-rendered snapshot pptx
- %(prog)s examples/ppt169_demo --only legacy # Only SVG image version (skips native)
%(prog)s examples/ppt169_demo -o out.pptx # Explicit path (no backup/)
# Disable transition / change transition effect
@@ -129,9 +127,9 @@ Examples:
SVG source directory (-s):
output - svg_output (hand-authored source; native default)
- final - svg_final (post-processed; legacy SVG-image path source)
+ final - svg_final (post-processed preview; diagnostic native input only)
<any> - Specify a subdirectory name directly
- Omit -s to use the default: native reads svg_output, legacy reads svg_final.
+ Omit -s to use the default: native export reads svg_output.
Transition effects (-t/--transition):
{', '.join(transition_choices)}
@@ -154,13 +152,6 @@ Per-element entrance animation (-a/--animation, native shapes mode):
random samples from the same legacy pool. Use "-a none" to disable
element builds explicitly.
-Compatibility mode (enabled by default):
- - Automatically generates PNG fallback images, SVG embedded as extension
- - Compatible with all Office versions (including Office LTSC 2021)
- - Newer Office still displays SVG (editable), older versions display PNG
- - Requires svglib: pip install svglib reportlab
- - Use --no-compat to disable (only Office 2019+ supported)
-
Speaker notes (enabled by default):
- Automatically reads Markdown notes files from the notes/ directory
- Supports two naming conventions:
@@ -186,24 +177,13 @@ Recorded narration:
parser.add_argument('project_path', type=str, help='Project directory path')
parser.add_argument('-o', '--output', type=str, default=None, help='Output file path')
parser.add_argument('-s', '--source', type=str, default=None,
- help='SVG source directory. Default: native reads '
- 'svg_output/ (high-fidelity, preserves icons / '
- 'preserveAspectRatio / rx-ry); legacy reads '
- 'svg_final/ (PPT-internal SVG parser fallback). '
- 'Pass output/final/<name> to force one source.')
+ help='Native SVG source directory. Default: svg_output/. '
+ 'Pass output/final/<name> only for diagnostics.')
parser.add_argument('-f', '--format', type=str,
choices=list(CANVAS_FORMATS.keys()), default=None,
help='Specify canvas format')
parser.add_argument('-q', '--quiet', action='store_true', help='Quiet mode')
- parser.add_argument('--no-compat', action='store_true',
- help='Disable Office compatibility mode (pure SVG only, requires Office 2019+)')
-
- mode_group = parser.add_mutually_exclusive_group()
- mode_group.add_argument('--only', type=str, choices=['native', 'legacy'], default=None,
- help='Only generate one version: native (editable shapes) or legacy (SVG image)')
- mode_group.add_argument('--native', action='store_true', default=False,
- help='(Deprecated, now default) Convert SVG to native DrawingML shapes')
merge_group = parser.add_mutually_exclusive_group()
merge_group.add_argument('--merge-paragraphs', action='store_true', dest='merge_paragraphs',
help='Compatibility no-op: mergeable paragraph blocks are merged '
@@ -238,14 +218,6 @@ Recorded narration:
'flat leaves generated structure slide-local for debugging/comparison.'
),
)
- parser.add_argument('--svg-snapshot', action='store_true', default=False,
- help='Also emit the SVG-rendered snapshot pptx alongside '
- 'the native pptx in exports/ (named '
- '<project>_<ts>_svg.pptx). Off by default — the '
- 'native pptx is the canonical output; live preview '
- 'already provides the SVG visual reference. '
- 'Note: the svg_output/ source snapshot is always written to backup/<ts>/ '
- 'regardless of this flag.')
parser.add_argument('--no-image-optimize', action='store_true',
help='Disable native PPTX raster image optimization; embeds original image bytes.')
parser.add_argument('--image-max-dimension', type=int, default=2560,
@@ -314,20 +286,6 @@ Recorded narration:
parser.add_argument('--narration-padding', type=float, default=0.5,
help='Seconds to add after each narration before auto-advance (default: 0.5)')
- parser.add_argument('--cache-dir', type=str, default=None,
- help='Cache directory for SVG→PNG renders (default: '
- '<project>/.cache/svg_png). Cache key uses SVG content '
- 'hash + size + renderer; safe across renderer switches. '
- 'Removed automatically after a successful export.')
- parser.add_argument('--no-cache', action='store_true',
- help='Disable the SVG→PNG cache for this run (still parallel).')
- parser.add_argument('--keep-cache', action='store_true',
- help='Keep the SVG→PNG cache directory after export '
- '(default: removed on success to keep project clean).')
- parser.add_argument('--workers', type=int, default=None,
- help='Parallel workers for SVG→PNG pre-rendering. '
- 'Default: min(cpu, pages, 8). Set 1 for sequential.')
-
args = parser.parse_args(argv)
project_path = Path(args.project_path)
@@ -397,49 +355,17 @@ Recorded narration:
if canvas_format is None and detected_format and detected_format != 'unknown':
canvas_format = detected_format
- # Determine which versions to generate.
- # Default is native-only; SVG snapshot is opt-in via --svg-snapshot.
- # --only native / --only legacy still force a single version explicitly.
- only_mode = args.only
- if only_mode == 'native':
- gen_native, gen_legacy = True, False
- elif only_mode == 'legacy':
- gen_native, gen_legacy = False, True
- else:
- gen_native = True
- gen_legacy = args.svg_snapshot
-
- # Pipeline split: native pptx gets the high-fidelity svg_output/ source
- # (icons, preserveAspectRatio, rounded-rect rx/ry are all preserved by the
- # converter); legacy pptx still needs svg_final/ because PowerPoint's
- # internal SVG parser cannot handle <use data-icon> or honour
- # preserveAspectRatio. An explicit -s overrides both branches so callers
- # can keep the previous single-source behaviour for unusual workflows.
- explicit_source = args.source is not None
- native_source = args.source if explicit_source else 'output'
- legacy_source = args.source if explicit_source else 'final'
-
- native_files: list[Path] = []
- legacy_files: list[Path] = []
- native_source_dir = ''
- legacy_source_dir = ''
-
- if gen_native:
- native_files, native_source_dir = find_svg_files(project_path, native_source)
- if gen_legacy:
- legacy_files, legacy_source_dir = find_svg_files(project_path, legacy_source)
-
- # Reference list for cross-product lookups (notes / narration matching).
- # native_files and legacy_files share filenames because svg_final/ is
- # copytree'd from svg_output/, so either list works for matching.
- ref_files = native_files or legacy_files
- if not ref_files:
+ # Native DrawingML is the only PPTX product. ``-s`` remains an explicit
+ # diagnostic source override; standard export always reads svg_output/.
+ native_source = args.source or 'output'
+ native_files, native_source_dir = find_svg_files(project_path, native_source)
+ ref_files = native_files
+ if not native_files:
print("Error: No SVG files found")
return 1
if (
- gen_native
- and pptx_structure in {'template', 'preserve'}
+ pptx_structure in {'template', 'preserve'}
and structure_lock is not None
):
try:
@@ -491,37 +417,24 @@ Recorded narration:
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
backup_dir: Path | None = None
- legacy_path: Path | None = None
if args.output:
- output_base = Path(args.output)
- native_path = output_base
- if gen_legacy:
- stem = output_base.stem
- legacy_path = output_base.parent / f"{stem}_svg{output_base.suffix}"
+ native_path = Path(args.output)
else:
exports_dir = project_path / "exports"
exports_dir.mkdir(parents=True, exist_ok=True)
# --native-objects yields a materially different file (real editable
# PowerPoint chart/table objects instead of flattened shapes), so mark
- # it in the default-flow name to tell it apart from a plain shape export
- # and the _svg snapshot. Narration flags likewise mark _narrated (audio
- # embedded per slide + auto-advance timings); both entry points share
- # the tag. Flag-driven (not content-sniffed) so the name is predictable;
- # an explicit -o keeps the caller's exact name untouched.
+ # it in the default-flow name to tell it apart from a plain shape export.
+ # Narration flags likewise mark _narrated (audio embedded per slide +
+ # auto-advance timings). Flag-driven (not content-sniffed) so the name
+ # is predictable; an explicit -o keeps the caller's exact name untouched.
native_tag = "_native_charts" if args.native_objects else ""
narrated_tag = "_narrated" if (args.recorded_narration or args.narration_audio_dir) else ""
native_path = exports_dir / f"{project_name}_{timestamp}{native_tag}{narrated_tag}.pptx"
- # svg_output/ snapshot always goes under backup/<ts>/ in default-flow
- # mode (no -o). --svg-snapshot only controls the optional legacy
- # SVG-rendered pptx, which now sits alongside the native pptx in
- # exports/ rather than nested inside backup/.
+ # Preserve the authored svg_output/ beside every default-flow export.
backup_dir = project_path / "backup" / timestamp
- if gen_legacy:
- legacy_path = exports_dir / f"{project_name}_{timestamp}_svg.pptx"
native_path.parent.mkdir(parents=True, exist_ok=True)
- if legacy_path is not None:
- legacy_path.parent.mkdir(parents=True, exist_ok=True)
verbose = not args.quiet
@@ -679,7 +592,7 @@ Recorded narration:
'animation_trigger': args.animation_trigger is not None,
}
- if args.recorded_narration and gen_native:
+ if args.recorded_narration:
on_click_slides = _recorded_narration_on_click_slides(
ref_files,
animation_config,
@@ -699,17 +612,6 @@ Recorded narration:
print(f" ... and {len(on_click_slides) - 20} more", file=sys.stderr)
return 1
- if args.no_cache:
- cache_dir: Path | None = None
- elif args.cache_dir:
- cache_dir = Path(args.cache_dir)
- if not cache_dir.is_absolute():
- cache_dir = project_path / cache_dir
- else:
- cache_dir = project_path / '.cache' / 'svg_png'
-
- # svg_files is per-product (native vs legacy may now read different
- # directories); everything else is shared.
# Optional per-project document properties. Absent file → factual fields
# are still stamped at export; only the authored fields stay blank.
doc_metadata = None
@@ -734,7 +636,6 @@ Recorded narration:
transition=transition,
transition_duration=transition_duration,
auto_advance=args.auto_advance,
- use_compat_mode=not args.no_compat,
notes=notes,
enable_notes=enable_notes,
animation=animation,
@@ -746,8 +647,6 @@ Recorded narration:
narration_audio=narration_audio,
use_narration_timings=use_narration_timings,
narration_padding=args.narration_padding,
- cache_dir=cache_dir,
- workers=args.workers,
merge_paragraphs=args.merge_paragraphs,
image_optimize=not args.no_image_optimize,
image_max_dimension=args.image_max_dimension,
@@ -761,58 +660,32 @@ Recorded narration:
theme_color_spec=theme_color_spec,
)
- success = True
-
- # --- Native shapes version (primary) ---
- if gen_native:
- if verbose:
- print("PPT Master - SVG to PPTX Tool")
- print("=" * 50)
- print(f" Project path: {project_path}")
- print(f" SVG directory: {native_source_dir}")
- print(f" Output file: {native_path}")
- print()
+ if verbose:
+ print("PPT Master - SVG to native DrawingML PPTX Tool")
+ print("=" * 50)
+ print(f" Project path: {project_path}")
+ print(f" SVG directory: {native_source_dir}")
+ print(f" Output file: {native_path}")
+ print()
- try:
- ok = create_pptx_with_native_svg(
- output_path=native_path,
- use_native_shapes=True,
- svg_files=native_files,
- conversion_trace_path=(
- native_path.with_name(native_path.name + '.trace.json')
- if args.conversion_trace else None
- ),
- **shared_kwargs,
- )
- except TemplateStructureError as exc:
- print(f"Error: {exc}", file=sys.stderr)
- return 1
- success = success and ok
-
- # --- SVG image reference version ---
- if gen_legacy:
- if verbose:
- if gen_native:
- print()
- print("-" * 50)
- print("PPT Master - SVG to PPTX Tool (SVG Reference)")
- print("=" * 50)
- print(f" Project path: {project_path}")
- print(f" SVG directory: {legacy_source_dir}")
- print(f" Output file: {legacy_path}")
- print()
-
- ok = create_pptx_with_native_svg(
- output_path=legacy_path,
- use_native_shapes=False,
- svg_files=legacy_files,
+ try:
+ success = create_pptx_with_native_svg(
+ output_path=native_path,
+ use_native_shapes=True,
+ svg_files=native_files,
+ conversion_trace_path=(
+ native_path.with_name(native_path.name + '.trace.json')
+ if args.conversion_trace else None
+ ),
**shared_kwargs,
)
- success = success and ok
+ except TemplateStructureError as exc:
+ print(f"Error: {exc}", file=sys.stderr)
+ return 1
- # svg_output/ snapshot — runs once per export in default-flow mode,
- # decoupled from --svg-snapshot. Preserves the AI-generated SVG sources
- # under backup/<ts>/svg_output/ for later inspection / re-export.
+ # Archive svg_output/ once per default-flow export. This preserves the
+ # authored SVG sources under backup/<ts>/svg_output/ for inspection and
+ # deterministic re-export.
if success and backup_dir is not None:
svg_output_src = project_path / "svg_output"
if svg_output_src.is_dir():
@@ -848,16 +721,6 @@ Recorded narration:
if verbose:
print(f" [warn] preserve contract backup skipped: {exc}")
- if success and cache_dir is not None and cache_dir.is_dir() and not args.keep_cache:
- try:
- shutil.rmtree(cache_dir)
- cache_parent = cache_dir.parent
- if cache_parent.is_dir() and cache_parent.name == '.cache' and not any(cache_parent.iterdir()):
- cache_parent.rmdir()
- except Exception as exc:
- if verbose:
- print(f" [warn] cache cleanup skipped: {exc}")
-
return 0 if success else 1
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/discovery.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/discovery.py
index dc8f66ab..7b7196fe 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/discovery.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/discovery.py
@@ -16,7 +16,7 @@ def find_svg_files(
project_path: Project directory path.
source: SVG source directory alias or name.
- 'output': svg_output (hand-authored source; native default)
- - 'final': svg_final (post-processed; legacy SVG-image path source)
+ - 'final': svg_final (post-processed preview; diagnostic input)
- or any subdirectory name
Returns: