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

docs(pptx-structure): align baseline layout extraction guidance

hugohe3f4c4e494efae
diff --git a/docs/technical-design.md b/docs/technical-design.md
index b83beefa..d0b114c4 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -427,7 +427,7 @@ These direct routes share some analysis primitives with the main pipeline, espec
**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 the default native deck has a baseline master, not inferred templates.** `svg_to_pptx.py` keeps the actual blank slide layout relationship from the base package and defaults to `--pptx-structure baseline`. Baseline promotes only low-risk shared structure: the strict-majority identical slide background (every slide must carry an explicit background, and minority slides keep their own overriding fill), plus a common leading prefix of repeated top-level SVG chrome whose exact id tokens say `logo`, `footer`, `header`, `watermark`, `chrome`, `pageNumber`, or `slideNumber`. Chrome promotion also requires identical generated OOXML, no slide-timing reference, and the same leading z-order across a strict majority of slides sharing the master; overlay chrome stays slide-local. Minority slides — covers and section pages — keep every shape slide-local and are rebound to a generated `Cover` layout with `showMasterSp="0"`, following the PowerPoint convention that page-type differences live in layouts under one master rather than in extra masters, so promoted chrome never leaks onto them. After all pages are generated, an export-only pass assigns `Cover`, `Agenda`, `Section`, `Closing`, or fallback `Content` from exact filename role tokens. It preserves the current master-shape visibility, never compares page visuals or infers placeholders, and moves a family background to its Layout only when every family member carries the exact same explicit `p:bg`; actual page content remains on the Slide. Image relationships for promoted chrome are copied to the slide master, base-template slide layouts no generated slide references are pruned from the package, and `pageNumber`/`slideNumber` chrome whose text exactly equals the slide's display number (honoring `firstSlideNum`) becomes an auto-updating slide-number field so reordering slides in PowerPoint renumbers pages. This gives ordinary decks a useful master/layout roster without constraining SVG authoring or spending model context on layout planning.
+**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 (every slide must carry an explicit background, and minority slides keep their own overriding fill), plus a common leading prefix of repeated top-level SVG chrome whose exact id tokens say `logo`, `footer`, `header`, `watermark`, `chrome`, `pageNumber`, or `slideNumber`. Chrome promotion also requires identical generated OOXML, no slide-timing reference, and the same leading z-order across a strict majority of slides sharing the master; overlay chrome stays slide-local. Minority slides — covers and section pages — keep every shape slide-local and are rebound to a generated `Cover` layout with `showMasterSp="0"`, following the PowerPoint convention that page-type differences live in layouts under one master rather than in extra masters, so promoted chrome never leaks onto them. After all pages are generated, an export-only pass assigns `Cover`, `Agenda`, `Section`, `Closing`, or fallback `Content` from exact filename role tokens. It preserves the current master-shape visibility, never compares page visuals or infers placeholders, and moves a family background to its Layout only when every family member carries the exact same explicit `p:bg`; actual page content remains on the Slide. Image relationships for promoted chrome are copied to the slide master, base-template slide layouts no generated slide references are pruned from the package, and `pageNumber`/`slideNumber` chrome whose text exactly equals the slide's display number (honoring `firstSlideNum`) becomes an auto-updating slide-number field so reordering slides in PowerPoint renumbers pages. This gives ordinary decks a useful master/layout roster without constraining SVG authoring or spending model context on layout planning.
**Why reusable layouts require explicit SVG metadata.** `--pptx-structure template` is the opt-in path for a generated deck that must remain reusable as a PowerPoint template. The final slide SVGs declare a layout key at the root, mark only direct root children as master/layout layers, and attach typed placeholder semantics to the slide-local prototypes that should become layout placeholders. Export validates that shared master and same-key layout declarations are structurally and visually identical, then emits real layout parts and `p:ph` references while leaving every unmarked object slide-local. This is deterministic structure compilation, not visual-template inference.
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 7609730d..e4745fc5 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -427,7 +427,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份
**为什么兼容 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 deck 使用基线母版,而不推断模板。** `svg_to_pptx.py` 会保留基础 package 中空白版式的真实关系,并默认使用 `--pptx-structure baseline`。Baseline 只提升低风险共享结构:严格多数页面完全一致的页面背景(每页都必须携带显式背景,少数派页面保留自己的背景并覆盖母版填充),以及位于 shape 序列开头(视觉后层)、且 id 精确 token 为 `logo`、`footer`、`header`、`watermark`、`chrome`、`pageNumber` 或 `slideNumber` 的重复 SVG chrome。Chrome 还必须在共享同一母版的严格多数页面上生成完全一致的 OOXML、没有被页面动画引用,并保持相同的前置 z-order;覆盖在正文之上的 chrome 继续留在 slide 本地。少数派页面(封面、章节页)的全部元素保持 slide-local,并被改绑到生成的 `Cover` 版式(`showMasterSp="0"`)——遵循 PowerPoint 的惯例:页型差异用同一母版下的版式表达而不是增加母版,因此被提升的母版 chrome 绝不会泄漏到这些页面上。全部页面生成完成后,导出器只根据文件名中的明确角色 token 分配 `Cover`、`Agenda`、`Section`、`Closing` 或兜底 `Content`;它保留当前版式的母版图形可见性,不比较页面视觉、不猜占位符,只有某一家族的每页都携带完全相同的显式 `p:bg` 时才把该背景提升到 Layout,实际页面内容始终留在 Slide。被提升 chrome 的图片关系会复制到 slide master,基础模板中没有任何页面引用的 slide layout 也会从 package 中裁剪掉;`pageNumber`/`slideNumber` chrome 的文本若恰好等于该页应显示的页码(尊重 `firstSlideNum`),会转换为自动更新的 PowerPoint 页码字段,此后在 PowerPoint 中调整页序页码自动重算,其他编号方案保持字面文本不动。这样普通 deck 能获得实用的 master/layout 清单,同时不限制 SVG 创作,也不消耗模型上下文预先规划版式。
+**为什么默认 native deck 使用基线母版,而不推断模板。** `svg_to_pptx.py` 会从基础 package 中空白版式的真实关系开始构建,并默认使用 `--pptx-structure baseline`。Baseline 只提升低风险共享结构:严格多数页面完全一致的页面背景(每页都必须携带显式背景,少数派页面保留自己的背景并覆盖母版填充),以及位于 shape 序列开头(视觉后层)、且 id 精确 token 为 `logo`、`footer`、`header`、`watermark`、`chrome`、`pageNumber` 或 `slideNumber` 的重复 SVG chrome。Chrome 还必须在共享同一母版的严格多数页面上生成完全一致的 OOXML、没有被页面动画引用,并保持相同的前置 z-order;覆盖在正文之上的 chrome 继续留在 slide 本地。少数派页面(封面、章节页)的全部元素保持 slide-local,并被改绑到生成的 `Cover` 版式(`showMasterSp="0"`)——遵循 PowerPoint 的惯例:页型差异用同一母版下的版式表达而不是增加母版,因此被提升的母版 chrome 绝不会泄漏到这些页面上。全部页面生成完成后,导出器只根据文件名中的明确角色 token 分配 `Cover`、`Agenda`、`Section`、`Closing` 或兜底 `Content`;它保留当前版式的母版图形可见性,不比较页面视觉、不猜占位符,只有某一家族的每页都携带完全相同的显式 `p:bg` 时才把该背景提升到 Layout,实际页面内容始终留在 Slide。被提升 chrome 的图片关系会复制到 slide master,基础模板中没有任何页面引用的 slide layout 也会从 package 中裁剪掉;`pageNumber`/`slideNumber` chrome 的文本若恰好等于该页应显示的页码(尊重 `firstSlideNum`),会转换为自动更新的 PowerPoint 页码字段,此后在 PowerPoint 中调整页序页码自动重算,其他编号方案保持字面文本不动。这样普通 deck 能获得实用的 master/layout 清单,同时不限制 SVG 创作,也不消耗模型上下文预先规划版式。
**为什么可复用版式必须依赖显式 SVG 元数据。** `--pptx-structure template` 是生成型 deck 需要继续作为 PowerPoint 模板复用时的 opt-in 路径。最终 slide SVG 在根节点声明 layout key,只允许根节点的直接子元素标记 master/layout layer,并在应成为版式占位框的 slide-local 原型上附加类型语义。导出器会验证共享 master 与同 key layout 的声明在结构和视觉上完全一致,再生成真实 layout part 与 `p:ph` 引用;所有未标记对象仍保持 slide-local。这是确定性的结构编译,不是根据视觉相似度猜模板。
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index e085218b..f4480fd5 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -741,8 +741,8 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> template SVG roster as optional visual/layout references and exports through
> `baseline`, even when the template directory contains the native pair. Pages
> without a `page_layouts` row remain free design; the baseline post-pass owns
-> conservative Master/background/chrome extraction exactly as it does without a
-> template.
+> conservative Master/background/chrome extraction plus filename-backed Layout
+> family assignment exactly as it does without a template.
> **Explicit reusable template export** — set `spec_lock.md`
> `pptx_structure.mode: template` (or pass `--pptx-structure template`
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index d19e2030..94fedae1 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -100,7 +100,7 @@ Before generating each page, output which template is used:
| `pptx_structure.mode` | Executor behavior |
|---|---|
-| `baseline` or missing | Author ordinary SVG pages. Do not add explicit PPTX structure metadata merely because a page uses a visual template or its directory carries a native structure pair. |
+| `baseline` or missing | Author ordinary SVG pages. Do not add explicit PPTX structure metadata merely because a page uses a visual template or its directory carries a native structure pair; export assigns conservative filename-backed Layout families after generation. |
| `template` | Every generated SVG MUST implement the matching `pptx_layouts` row and the explicit structure contract below. |
| `preserve` | Every generated SVG MUST use the locked source layout key/name. Keep inherited master/layout visuals as marked preview layers; export removes the previews and reuses the original source package parts. |
@@ -187,7 +187,7 @@ Do **not** invent a layout entry, and do **not** assume a template just because
**Per-page PowerPoint layout lookup — `pptx_layouts` section**:
- `pptx_structure.mode: template` or `preserve` → a `P<NN>` row is mandatory; apply §1.2 to the root and direct children. Preserve mode uses the exact source key/name and placeholder indices.
-- `pptx_structure.mode: baseline` or missing → omit explicit PPTX structure metadata; baseline export owns conservative promotion.
+- `pptx_structure.mode: baseline` or missing → omit explicit PPTX structure metadata; baseline export owns conservative Master/background/chrome promotion plus filename-backed Layout family assignment.
- A layout key may repeat across non-adjacent pages. Reuse is based on identical static/placeholder contracts, not page proximity or content wording.
**Per-page chart reference — `page_charts` section**:
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index ccc8d0b7..3f9dca22 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -116,7 +116,7 @@ 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.
-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 the strict-majority identical native slide background into the slide master (minority slides keep their own overriding background). A shared leading prefix of top-level SVG elements with exact chrome id tokens such as `logo`, `footer`, `header`, `watermark`, `chrome`, `pageNumber`, or `slideNumber` may also be promoted when its generated OOXML is identical on a strict majority of slides, it is not referenced by slide timing, and moving it behind slide-local content preserves z-order; image relationships are copied to the master. Minority slides such as covers keep every shape slide-local and are bound to a generated `Cover` layout (`showMasterSp="0"`) that hides the promoted master chrome. Baseline additionally prunes base-template slide layouts that no generated slide references, and swaps `pageNumber`/`slideNumber` chrome text for an auto-updating slide-number field when the text exactly equals the slide's display number. Use `--pptx-structure flat` when all generated backgrounds and chrome must remain slide-local for debugging or comparison.
+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 the strict-majority identical native slide background into the slide master (minority slides keep their own overriding background). A shared leading prefix of top-level SVG elements with exact chrome id tokens such as `logo`, `footer`, `header`, `watermark`, `chrome`, `pageNumber`, or `slideNumber` may also be promoted when its generated OOXML is identical on a strict majority of slides, it is not referenced by slide timing, and moving it behind slide-local content preserves z-order; image relationships are copied to the master. Minority slides such as covers keep every shape slide-local and are bound to a generated `Cover` layout (`showMasterSp="0"`) that hides the promoted master chrome. After all SVG pages are complete, baseline assigns filename-backed `Cover`, `Agenda`, `Section`, `Closing`, or fallback `Content` layouts while preserving that master-shape visibility. It moves a family background to Layout only when every member carries the exact same explicit `p:bg`; actual titles, body content, pictures, charts, tables, and page-specific shapes remain on Slide, with no visual-similarity or placeholder inference. Baseline additionally prunes base-template slide layouts that no generated slide references, and swaps `pageNumber`/`slideNumber` chrome text for an auto-updating slide-number field when the text exactly equals the slide's display number. For projects with locked typography and colors, baseline/template export also maps the title/body families and canonical palette roles into the PowerPoint theme while preserving the initial SVG rendering. Use `--pptx-structure flat` when all generated structure and theme tokens must remain slide-local/concrete for debugging or comparison.
Use template structure only when the final slide SVGs explicitly declare reusable PowerPoint structure. The CLI reads `spec_lock.md` `pptx_structure.mode` when `--pptx-structure` is omitted, so a locked `template` project exports structurally through the standard command; an explicit CLI value still overrides the lock. Each SVG names its layout with `data-pptx-layout`; direct root children may opt into master/layout layers with `data-pptx-layer`, and supported text, picture, chart, table, footer, or slide-number elements may declare `data-pptx-placeholder`. The exporter validates the project-level `pptx_layouts` mapping and cross-slide consistency, creates one reusable layout per layout key, and keeps actual content slide-local. A direct full-canvas solid rect becomes a real Master/Layout/Slide `p:bg` according to its declared scope; an unmarked full-canvas solid rect is a Slide override. It never infers placeholders from visual similarity. The complete metadata contract lives in [`references/shared-standards.md`](../references/shared-standards.md#explicit-pptx-master--layout--placeholder-metadata-template-export).