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

feat(svg-to-pptx): enforce locked layouts and scoped backgrounds

hugohe3276ab020c706
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 162ed946..e12a1373 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -82,7 +82,7 @@ The past two months' structural capability growth. Single flags / incremental po
- **`--native-objects` hardened from dormant marker to usable opt-in** — the narrow native-object exception (see Non-goals below) now emits charts and pure-text tables that keep the deck's own design instead of snapping to PowerPoint's white default theme. Classic native charts write explicit chart-area / plot-area / axis-line / gridline / label-text colors — inferred from the visible SVG fallback (largest panel `<rect>` → background, fallback text → labels, fallback strokes → axis/grid) or overridden per `style` (`chart_area_fill` / `plot_area_fill` / `text_color` / `axis_color` / `grid_color`, `"none"` for transparent); the color parser normalizes named CSS colors, `#RGB` shorthand, and `rgb()` / `rgba()` to OOXML hex; bar/column series disable negative-value fill inversion so negative bars keep their series color. The activated export is named `<name>_<ts>_native_charts.pptx` to tell it apart from the default flattened-shape export. **The default route is unchanged** — charts/tables still export as SVG-derived DrawingML shapes for cross-renderer fidelity; native objects stay the deliberate opt-in trade documented under Non-goals below
-- **Native package structure + conservative PPTX object round-trip** — native export now keeps the base package's real blank-layout relationship and defaults to a baseline master that promotes only identical backgrounds and a safe leading prefix of repeated chrome. An explicit `--pptx-structure template` mode compiles declared SVG master/layout layers and typed placeholders into reusable PowerPoint layouts without visual inference; supplied PPTX templates still use the preservation-oriented `template-fill-pptx` route. The standalone `pptx_to_svg.py` importer emits fallback SVG plus native metadata for supported unmerged tables and classic-chart caches; exporter-canonical solid series/slice colors and exact title/subtitle structures survive a second `--native-objects` export, while unsupported table/chart semantics remain explicit fallback-only markers
+- **Native package structure + conservative PPTX object round-trip** — native export now keeps the base package's real blank-layout relationship and defaults to a baseline master that promotes only identical backgrounds and a safe leading prefix of repeated chrome. A locked `pptx_structure.mode: template` compiles declared SVG master/layout layers and typed placeholders into reusable PowerPoint layouts without visual inference; every page maps through `pptx_layouts`, same-key pages reuse one contract, and deck/page-type/page-specific solid backgrounds become real Master/Layout/Slide `p:bg` fills. Supplied PPTX templates still use the preservation-oriented `template-fill-pptx` route. The standalone `pptx_to_svg.py` importer emits fallback SVG plus native metadata for supported unmerged tables and classic-chart caches; exporter-canonical solid series/slice colors and exact title/subtitle structures survive a second `--native-objects` export, while unsupported table/chart semantics remain explicit fallback-only markers
---
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 5b5973cd..68f46cb3 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -431,6 +431,8 @@ These direct routes share some analysis primitives with the main pipeline, espec
**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. A supplied PPTX whose existing master/theme must survive still belongs to `template-fill-pptx`; `template` mode does not reconstruct an arbitrary source package.
+**Why each SVG references a layout instead of becoming one.** A generated SVG is a complete slide instance: its actual title, body, pictures, tables, and charts must remain selectable in Normal View. `spec_lock.md` therefore separates `pptx_layouts` (the output PowerPoint layout key/name for every page) from `page_layouts` (an optional input SVG design reference). Pages reuse one output key only when their static layout layer and placeholder contract match. The exporter reads `pptx_structure.mode` from the lock when no CLI override is present. Within that hierarchy, ownership follows scope rather than paint type: a direct full-canvas solid rect becomes Master `p:bg` when deck-wide, Layout `p:bg` when page-type-specific, and Slide `p:bg` when explicitly marked for that scope or left unmarked in the background plane. This keeps new slides inheriting the right background without putting content or selectable full-canvas rectangles into layouts.
+
**Why native-object reconstruction uses markers, not automatic object replacement.** The standalone `pptx_to_svg.py` importer can emit SVG fallback content plus `data-pptx-native` metadata for supported unmerged tables and conservative classic-chart caches. It retains source table-style inheritance, supported solid cell fills/basic text formatting, chart title/legend/axis titles, and plot-level data-label flags for area/bar/column/line charts when the current schema can represent them. Exporter-canonical classic charts also recover canonical solid series/slice colors and exact one- or two-paragraph title metadata. The default export still consumes fallback children as regular DrawingML shapes; only `--native-objects` activates editable PowerPoint tables/charts. Unsupported table cases — including merged cells, direct borders, non-solid fills, and mixed rich text — keep the rendered SVG table. Unsupported chart cases — including ChartEx, rotated/flipped/3D/combo charts, unsupported data-label scopes/types, custom axis semantics, trendlines/error bars, unsupported subtype options, sparse or non-finite caches, and date/formatted category axes — keep a baked preview when one exists, otherwise an explicit placeholder. Both carry `data-pptx-native-status`; the quality checker and native-object export report them as fallback-only warnings. This importer/exporter pairing is a reconstruction aid, not a preservation-route substitute for `template-fill-pptx` or `native-enhance-pptx`.
---
diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.md
index 9ff75a3d..4ddcea49 100644
--- a/docs/zh/roadmap.md
+++ b/docs/zh/roadmap.md
@@ -82,7 +82,7 @@
- **`--native-objects` 从休眠 marker 硬化为可用级 opt-in** — 那条窄「原生对象」例外(见下文 Non-goals)现在导出的图表与纯文本表格会**保留 deck 自己的设计**,不再塌回 PowerPoint 的白底默认主题。classic 原生图表显式写入 chart-area / plot-area / 轴线 / 网格线 / 标签文字颜色——从可见的 SVG fallback 推断(最大面板型 `<rect>` → 背景、fallback 文字 → 标签、fallback 描边 → 轴线/网格),或用 `style` 显式覆盖(`chart_area_fill` / `plot_area_fill` / `text_color` / `axis_color` / `grid_color`,`"none"` 表透明);颜色解析把命名色、`#RGB` 简写、`rgb()` / `rgba()` 归一为 OOXML hex;bar/column 系列关掉负值反色,负值柱保持系列色。激活导出命名为 `<name>_<ts>_native_charts.pptx` 以与默认压平形状导出区分。**默认路线不变**——图表/表格仍以 SVG 派生的 DrawingML 形状导出以保跨渲染器保真;原生对象仍是下文 Non-goals 里那条刻意的 opt-in 取舍
-- **原生 package 结构 + 保守 PPTX 对象回转** — 原生导出现在保留基础 package 的真实空白版式关系,并默认使用 baseline master;只提升完全一致的背景和安全的前置重复 chrome。显式 `--pptx-structure template` 模式会把 SVG 中声明的 master/layout layer 与有类型的 placeholder 编译成可复用 PowerPoint 版式,不做视觉推断;用户提供的 PPTX 模板仍走以保留为目标的 `template-fill-pptx` 路线。独立 `pptx_to_svg.py` 导入器会为受支持的未合并表格与 classic-chart cache 输出 fallback SVG 加原生元数据;由本 exporter 生成的规范纯色系列 / 切片与精确 title/subtitle 结构可经第二次 `--native-objects` 导出继续保留,无法等价表达的表格 / 图表语义则保持明确的 fallback-only marker
+- **原生 package 结构 + 保守 PPTX 对象回转** — 原生导出现在保留基础 package 的真实空白版式关系,并默认使用 baseline master;只提升完全一致的背景和安全的前置重复 chrome。锁定的 `pptx_structure.mode: template` 会把 SVG 中声明的 master/layout layer 与有类型的 placeholder 编译成可复用 PowerPoint 版式,不做视觉推断;每页通过 `pptx_layouts` 映射,同 key 页面复用同一 contract,全 deck / 页型 / 单页纯色背景分别成为真实 Master/Layout/Slide `p:bg`。用户提供的 PPTX 模板仍走以保留为目标的 `template-fill-pptx` 路线。独立 `pptx_to_svg.py` 导入器会为受支持的未合并表格与 classic-chart cache 输出 fallback SVG 加原生元数据;由本 exporter 生成的规范纯色系列 / 切片与精确 title/subtitle 结构可经第二次 `--native-objects` 导出继续保留,无法等价表达的表格 / 图表语义则保持明确的 fallback-only marker
---
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index ab299753..30270ced 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -431,6 +431,8 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份
**为什么可复用版式必须依赖显式 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。这是确定性的结构编译,不是根据视觉相似度猜模板。若用户提供的是必须保留原有 master/theme 的 PPTX,仍应走 `template-fill-pptx`;`template` 模式不会重建任意来源的 package。
+**为什么每个 SVG 应引用版式,而不是直接变成版式。** 生成 SVG 是完整的 slide 实例;其中真实标题、正文、图片、表格和图表必须继续能在普通视图中选择。`spec_lock.md` 因而把 `pptx_layouts`(每页最终引用的 PowerPoint layout key/name)与 `page_layouts`(可选的输入 SVG 设计参考)分开。只有静态 layout layer 与 placeholder contract 相同的页面才复用同一个输出 key。没有 CLI 覆盖时,导出器会读取 lock 中的 `pptx_structure.mode`。在这个继承层级里,归属由复用范围而不是填充类型决定:全画布纯色矩形在全 deck 共享时成为 Master `p:bg`,页型共享时成为 Layout `p:bg`,显式标记为 slide 或位于背景层但未标记时成为 Slide `p:bg`。这样新增页面能继承正确背景,同时不会把实际内容或可选中的全屏矩形塞进版式。
+
**为什么原生对象重建使用 marker,而不是自动替换对象。** 独立的 `pptx_to_svg.py` 导入器会为受支持的未合并表格和保守 classic-chart cache 输出 SVG fallback,并附加 `data-pptx-native` 元数据;当现有 schema 能表达时,还会保留源表格样式继承、受支持的单元格纯色填充 / 基础文字格式,以及图表标题、图例、坐标轴标题和面积图 / 条形图 / 柱形图 / 折线图的 plot 级数据标签开关。由本 exporter 生成的规范 classic chart 还会回读规范纯色系列 / 切片,以及精确的单段或双段标题元数据。默认导出仍把 fallback 子元素当普通 DrawingML shape 处理;只有 `--native-objects` 才会启用可编辑的 PowerPoint 表格 / 图表。合并单元格、直接边框、非纯色填充、混合富文本等不支持的表格场景继续保留实际渲染的 SVG table。ChartEx、旋转 / 翻转 / 3D / 组合图表、不受支持的数据标签作用域或类型、自定义坐标轴语义、趋势线 / 误差线、不受支持的子类型参数、稀疏或非有限 cache、日期 / 格式化类别轴等不支持的图表场景,则在有 baked preview 时保留预览,否则给出明确占位符。两类对象都会写入 `data-pptx-native-status`;质量检查器和 native-object 导出将其报告为 fallback-only warning。这对 importer/exporter 是重建辅助能力,不能替代 `template-fill-pptx` 或 `native-enhance-pptx` 的保留型路线。
---
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 012dff13..27653ca6 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -25,7 +25,7 @@ description: >
> 5. **NO SPECULATIVE EXECUTION** — "Pre-preparing" content for subsequent Steps is FORBIDDEN (e.g., writing SVG code during the Strategist phase)
> 6. **NO SUB-AGENT SVG GENERATION** — Executor Step 6 SVG generation is context-dependent and MUST be completed by the current main agent end-to-end. Delegating page SVG generation to sub-agents is FORBIDDEN
> 7. **SEQUENTIAL PAGE GENERATION ONLY** — In Executor Step 6, after the global design context is confirmed, SVG pages MUST be generated sequentially page by page in one continuous pass. Grouped page batches (for example, 5 pages at a time) are FORBIDDEN
-> 8. **SPEC_LOCK RE-READ PER PAGE** — Before generating each SVG page, Executor MUST `read_file <project_path>/spec_lock.md`. All colors / fonts / icons / images MUST come from this file — no values from memory or invented on the fly. Executor MUST also look up the current page's `page_rhythm` (`anchor` / `dense` / `breathing`), `page_layouts` (which template SVG to inherit, if any), and `page_charts` (which chart template to adapt, if any). Empty / absent entries are intentional Strategist signals — see executor-base.md §2.1. This rule exists to resist context-compression drift on long decks and to break the uniform "every page is a card grid" default
+> 8. **SPEC_LOCK RE-READ PER PAGE** — Before generating each SVG page, Executor MUST `read_file <project_path>/spec_lock.md`. All colors / fonts / icons / images MUST come from this file — no values from memory or invented on the fly. Executor MUST also look up the current page's `page_rhythm` (`anchor` / `dense` / `breathing`), `page_layouts` (which template SVG to inherit, if any), `page_charts` (which chart template to adapt, if any), and — when `pptx_structure.mode` is `template` — `pptx_layouts` (which native PowerPoint layout the page references). Empty / absent entries are intentional Strategist signals — see executor-base.md §2.1. This rule exists to resist context-compression drift on long decks and to break the uniform "every page is a card grid" default
> 9. **SVG MUST BE HAND-WRITTEN, NOT SCRIPT-GENERATED** — Every SVG page is written by the main agent directly, one page at a time (see rules 6 and 7). Writing or running a Python / Node / shell script that produces the SVG files in batch — looping over pages, templating from data, or emitting them via a generator — is FORBIDDEN, including under "save tokens", "quick draft", or "user is in a hurry" pretexts. The script-generation path was tried on a feature branch and abandoned: cross-page visual consistency depends on per-page authoring with full upstream context, which a generator script cannot reproduce
> 10. **FOLLOW DETERMINISTIC ROUTING RULES** — Do not add blocking routing questions when this skill defines a route. If the user request violates a route precondition, state the required prerequisite and stop that route instead of asking the user to choose around the rule. Ordinary finite options, stylistic preferences, and recoverable details are surfaced with a recommended value plus alternatives at the next existing confirmation gate.
@@ -575,7 +575,7 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon
> Image facts: trust the `analysis/image_analysis.csv` regenerated at the end of Step 5. If `images/` changed since (the user swapped or added files), re-run `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` before laying images out — facts are re-derived on use, never a stale store (Step 4 image-facts note).
-**Per-page spec_lock re-read (Mandatory)**: before **each** SVG page, `read_file <project_path>/spec_lock.md` and use only its colors / fonts / icons / images, plus the per-page `page_rhythm` / `page_layouts` / `page_charts` lookups (resolves to template SVGs already loaded in the batch read above). Resists context-compression drift on long decks. See executor-base.md §2.1.
+**Per-page spec_lock re-read (Mandatory)**: before **each** SVG page, `read_file <project_path>/spec_lock.md` and use only its colors / fonts / icons / images, plus the per-page `page_rhythm` / `page_layouts` / `page_charts` lookups and the optional `pptx_structure` / `pptx_layouts` native-layout contract. Resists context-compression drift on long decks. See executor-base.md §2.1.
> ⚠️ **Main-agent only**: SVG generation MUST stay in the current main agent — page design depends on full upstream context. Do NOT delegate to sub-agents.
> ⚠️ **Generation rhythm**: generate pages sequentially, one at a time, in the same continuous context. Do NOT batch (e.g., 5 per group).
@@ -668,8 +668,10 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> 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.
-> **PPTX structure mode** — native export defaults to
-> `--pptx-structure baseline`: the package keeps the real slide master/layout
+> **PPTX structure mode** — native export first reads
+> `spec_lock.md` `pptx_structure.mode`, then falls back to `baseline` when the
+> section is absent. An explicit `--pptx-structure` CLI value overrides the
+> lock for diagnostics. Baseline keeps the real slide master/layout
> relationship from the base deck and promotes the strict-majority identical
> native slide background into the slide master (every slide must carry an
> explicit background; minority slides keep their own, which overrides the
@@ -690,18 +692,22 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> `--pptx-structure flat` only for debugging/comparison when all generated
> backgrounds and chrome must remain slide-local.
-> **Explicit reusable template export** — pass `--pptx-structure template`
-> only when every SVG root declares `data-pptx-layout` and direct children
-> explicitly declare master/layout layers or PowerPoint placeholders. This
+> **Explicit reusable template export** — set `spec_lock.md`
+> `pptx_structure.mode: template` (or pass `--pptx-structure template`
+> explicitly) only when every SVG root declares `data-pptx-layout` and direct children
+> explicitly declare master/layout layers, an optional Slide background, or
+> PowerPoint placeholders. This
> mode builds named reusable layouts and placeholder mappings; it does not
> infer them from visual similarity. Static master/layout elements must be
-> repeated consistently in inheritance/z-order order. Chart/table placeholders
+> repeated consistently in PowerPoint paint order. Chart/table placeholders
> additionally require `--native-objects`. The metadata contract and authoring
> example live in
> [`references/shared-standards.md`](references/shared-standards.md#explicit-pptx-master--layout--placeholder-metadata-template-export).
> Raw PPTX templates still route to `template-fill-pptx`; `template` structure
> mode is for explicitly annotated SVG authoring, not source-package
-> preservation.
+> preservation. In template mode, `pptx_layouts` contains exactly one locked
+> layout key/name per page; reuse a key for a shared structure instead of
+> creating one key per content instance.
> **Paragraph editability vs line fidelity** — by default, mergeable dy-stacked
> paragraph blocks collapse into one editable PowerPoint text frame with multiple
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 022903d1..b9a31ab5 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -91,6 +91,31 @@ Before generating each page, output which template is used:
- **Content pages**: template defines only header/footer; content area is free
- **No template**: generate entirely per the Design Spec
+### 1.2 PowerPoint Master / Layout Mapping
+
+`page_layouts` selects an SVG design reference; `pptx_layouts` declares the native PowerPoint layout produced at export. They are independent contracts.
+
+| `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. |
+| `template` | Every generated SVG MUST implement the matching `pptx_layouts` row and the explicit structure contract below. |
+
+**Hard rule — every template-mode page references one layout**: Read `P<NN>: <layout_key> | <layout name>` from `pptx_layouts`, then put both values on the root SVG as `data-pptx-layout` and `data-pptx-layout-name`. Do not invent, rename, or omit a key.
+
+**Hard rule — PowerPoint paint order**: Direct visual children appear in this order: Master background, Layout background, optional Slide background, shared Master shapes, same-key Layout shapes, then slide-local content/placeholders. Backgrounds are the special plane beneath all inherited shapes. Repeat the same Master contract on every page and the same Layout contract on every page sharing a key.
+
+**Placeholder ownership**: Keep actual title/body/picture/chart/table/footer/slide-number content on the Slide and add the matching `data-pptx-placeholder`. Do not move actual content into a Layout. Chart/table placeholders require native markers and a later `--native-objects` export.
+
+**Background ownership**:
+
+| Scope | SVG authoring |
+|---|---|
+| Deck-wide default | Direct full-canvas solid `<rect data-pptx-layer="master">` repeated identically on every page |
+| Page-type default | Direct full-canvas solid `<rect data-pptx-layer="layout">` repeated on every page sharing that layout key |
+| One-page exception | Direct full-canvas solid `<rect data-pptx-layer="slide">` |
+
+The exporter writes these solid fills as real Master/Layout/Slide `p:bg`, not selectable full-canvas shapes. Gradients, images, textures, and overlay panels stay explicit shapes unless the shared standard says otherwise.
+
---
## 2. Design Parameter Confirmation (Mandatory Step)
@@ -152,6 +177,12 @@ Before drawing each page, look up its entry in `page_layouts` to decide which ba
Do **not** invent a layout entry, and do **not** assume a template just because `templates/` exists — if `page_layouts` is present but silent for this page, that silence is the instruction.
+**Per-page PowerPoint layout lookup — `pptx_layouts` section**:
+
+- `pptx_structure.mode: template` → a `P<NN>` row is mandatory; apply §1.2 to the root and direct children.
+- `pptx_structure.mode: baseline` or missing → omit explicit PPTX structure metadata; baseline export owns conservative promotion.
+- 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**:
Before drawing each page, look up its entry in `page_charts` to decide which chart structure applies (the SVG itself was loaded in §1.0):
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index 5f89d826..1b91cf48 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -927,9 +927,18 @@ steal plot area in PPT. Add `show_legend: true` only when the legend is needed;
### Explicit PPTX Master / Layout / Placeholder Metadata (Template Export)
-**Trigger**: Pass `--pptx-structure template`. Without that flag, the metadata
-stays visually dormant and the SVG exports through the normal baseline / flat
-path.
+**Trigger**: Set `spec_lock.md` `pptx_structure.mode` to `template`, or pass
+`--pptx-structure template` explicitly. The CLI value overrides the lock;
+without either trigger, metadata stays visually dormant and the SVG exports
+through the normal baseline / flat path.
+
+**Project lock**: In the standard project pipeline, template mode requires one
+`pptx_layouts` row per page using
+`P<NN>: <layout_key> | <PowerPoint layout name>`. The SVG root values MUST
+match that row. Reuse one layout key only when pages share the same static
+layout layer and placeholder contract; different content is not a reason to
+create a new layout. Direct diagnostic exports may pass the CLI flag without a
+spec lock; the SVG metadata remains the exporter source of truth.
| Metadata | Placement | Behavior |
|---|---|---|
@@ -937,19 +946,32 @@ path.
| `data-pptx-layout-name="Title and Content"` | root `<svg>` | Sets the PowerPoint layout-picker name; defaults from the layout key |
| `data-pptx-layer="master"` | direct visual child | Moves one repeated static object/background into the slide master |
| `data-pptx-layer="layout"` | direct visual child | Moves one repeated static object/background into the selected layout |
+| `data-pptx-layer="slide"` | direct full-canvas solid `<rect>` only | Writes a one-page override as Slide `p:bg` |
| `data-pptx-placeholder="..."` | direct visual child | Keeps actual content on the slide and maps it to a generated layout placeholder |
| `data-pptx-placeholder-bounds="x y width height"` | placeholder element | Overrides the reusable placeholder frame in SVG user units |
-| `data-pptx-editable="false"` | master/layout element | Declares intentional editing through Master View, not Normal View |
+| `data-pptx-editable="false"` | master/layout element or slide background | Declares intentional editing outside ordinary slide content |
**Hard rule — explicit only**: Template export never promotes visually similar
content by inference. Every SVG requires a root `data-pptx-layout`; every
master/layout/placeholder element requires a unique `id` and must be a direct
child of the root SVG.
-**Layer order**: Author the SVG in PowerPoint inheritance order: master elements
-first, then layout elements, then slide-local content/placeholders. Moving a
-later overlay behind slide content changes z-order, so the exporter rejects
-interleaved structure layers.
+**Layer order**: Author the SVG in PowerPoint paint order: Master background,
+Layout background, optional Slide background, Master shapes, Layout shapes,
+then slide-local content/placeholders. Backgrounds are a special inheritance
+plane beneath every shape; this order keeps standalone SVG preview and
+PowerPoint rendering aligned. The exporter rejects interleaved layers.
+
+**Solid background ownership**: A direct full-canvas solid `<rect>` becomes a
+real `p:bg`, not a selectable shape. Mark it `data-pptx-layer="master"` for the
+deck-wide default, `data-pptx-layer="layout"` for a page-type override, or
+`data-pptx-layer="slide"` for a one-slide override. An unmarked direct
+full-canvas solid rect in the background plane is also treated as Slide scope. A
+Layout background overrides the Master background; a Slide background
+overrides both. Use the Master for a globally stable color and the Layout for
+cover/section/content variants under the same design language. Gradients,
+images, textures, transformed rects, and visible-stroke rects are not promoted
+by this solid-background rule.
| Placeholder value | SVG element | PowerPoint placeholder |
|---|---|---|
@@ -982,6 +1004,9 @@ PowerPoint placeholder.
<rect id="master-bg" data-pptx-layer="master"
data-pptx-editable="false"
width="1280" height="720" fill="#F8FAFC"/>
+ <rect id="content-bg" data-pptx-layer="layout"
+ data-pptx-editable="false"
+ width="1280" height="720" fill="#FFFFFF"/>
<g id="content-rule" data-pptx-layer="layout"
data-pptx-editable="false">
<line x1="48" y1="96" x2="1232" y2="96"
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 798b2fa1..97bfb84f 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -839,6 +839,8 @@ This is what makes the axis meaningful: a `presentation` deck and a `text` deck
- **Cover impact is mandatory**: Page `P01` is the deck's first visual contract, not a generic title slide. In `design_spec.md §IX`, add a `Cover impact` line for `P01` that names one concrete hook and one concrete composition strategy. Use the source's strongest available signal: a provocative core claim, object / scene metaphor, hero number, founder / product / audience moment, or a distilled conflict. Pair it with one concrete composition strategy — such as `full-bleed image + floating title`, `typographic poster`, `hero object`, `data hook`, `editorial scene`, `high-contrast abstract geometry`, or a fresh composition the deck's subject suggests (these are starting points, not the allowed set). If no external or AI image is available, still specify a native-SVG visual hook; do not fall back to "title + subtitle + decorative background". (Beautify / template-fill keep the source cover verbatim — this rule does not apply on those preservation paths.)
- **Cover rhythm lock**: `P01` remains `anchor` in `spec_lock.md page_rhythm`, but its §IX `Cover impact` must prevent content-page patterns. Do not plan multi-card grids, agenda-like bullets, or equal-weight columns on the cover unless a template explicitly requires that structure, or a preservation path (beautify / template-fill) is transcribing the source cover verbatim.
- **Closing impact (only when the deck closes)**: the deck's last page is its final visual contract — the strongest impression after the cover. When the deck genuinely lands on a conclusion / call-to-action / final-takeaway page, give it a `Closing impact` line in §IX: name the one thing the audience should leave with (a distilled takeaway, a forward call, a memorable restatement of the core claim) + one composition that delivers it — never a generic "Thank you" / contact-only slide or a centered-title reprise of the cover. **Do NOT invent a closing page to satisfy this** — the filler-page ban above still holds; apply it only to the page where the deck actually resolves. Same exemptions as the cover: skip on template / beautify / template-fill preservation paths.
+ - **pptx_structure is mandatory**: Write `mode: baseline` by default. Use `mode: template` only when the user explicitly requests a reusable PowerPoint Master/Layout/Placeholder deliverable. Do not choose `flat`; it is a CLI-only diagnostic override.
+ - **pptx_layouts (template structure only)**: When `pptx_structure.mode` is `template`, write one `P<NN>: <layout_key> | <PowerPoint layout name>` row for every page. Reuse a layout key when pages share the same static layout layer and placeholder contract; page content differences do not justify new keys. One-off cover/section layouts are valid. Omit the whole section in baseline mode.
- **page_layouts (write only when a template is in use)**: For each page that inherits a template SVG, add `P<NN>: <svg_basename>` (e.g., `P04: 03a_content_image_text`). Pages designed freely get **no entry** — Executor reads the absence as "free design, no inheritance". If zero pages use a template, omit the section entirely.
- **page_charts (write only for chart pages that match a catalog template)**: For each page in `design_spec.md §VII` whose `reference template path` points to `templates/charts/<name>.svg`, add `P<NN>: <chart_name>`. Pages with `no-template-match` in §VII MUST NOT appear here (Executor would look for a non-existent reference). If the deck has no data-visualization pages, omit the section.
- **Hard rule**: Use both `page_layouts` and `page_charts` for the same page only when the layout template is a compatible shell for the chart. Do not pair chart pages with conflicting page layouts (e.g., `waterfall_chart` + timeline layout, KPI cards + circle-diagram layout). If no compatible layout exists, omit the page from `page_layouts`.
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 6143bb9f..9a3d8f78 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -116,9 +116,9 @@ 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.
-Native `svg_to_pptx.py` also defaults to `--pptx-structure 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. 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.
-Use `--pptx-structure template` only when the final slide SVGs explicitly declare reusable PowerPoint structure. 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 cross-slide consistency, creates one reusable layout per layout key, and keeps unmarked content slide-local. 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).
+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).
`pptx_to_svg.py` annotates supported unmerged tables and conservative classic-chart caches with `data-pptx-native` metadata. Source table-style inheritance, supported solid cell fills/basic text formatting, chart title/legend/axis titles, and plot-level data-label flags for area/bar/column/line charts are retained when the current schema can represent them. Tables with direct borders, non-solid fills, or mixed rich-text formatting remain fallback-only, as do charts with unsupported label scopes/types, custom axis semantics, trendlines/error bars, or subtype options. Unsupported tables keep their rendered SVG table; unsupported charts keep a baked preview or explicit placeholder. Both carry `data-pptx-native-status`, which `svg_quality_checker.py` and `svg_to_pptx.py --native-objects` report as a warning.
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 04f8622d..c867b9fb 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -61,7 +61,7 @@ Behavior:
`svg_final/`. Use `-s` only as an explicit diagnostic override.
- For PPTX template-import workspaces, use `-s svg-flat` when you need a visual round-trip check. The layered `svg/` tree is the machine-readable template source and intentionally does not inline inherited master / layout decoration into each slide.
- Native mode is strict about unsupported visual SVG elements: if a visual element cannot be represented or safely preserved, export fails with the SVG file, element tag, and position instead of silently dropping content.
-- `--pptx-structure template` builds reusable PowerPoint layouts only from explicit SVG metadata: root `data-pptx-layout`, direct-child `data-pptx-layer="master|layout"`, and direct-child `data-pptx-placeholder`. It validates cross-slide structure consistency and never infers layouts from visual similarity. Chart/table placeholders also require `--native-objects`; full contract: [`shared-standards.md`](../../references/shared-standards.md#explicit-pptx-master--layout--placeholder-metadata-template-export).
+- Omitting `--pptx-structure` reads `spec_lock.md` `pptx_structure.mode`, then falls back to `baseline`; an explicit CLI value overrides the lock. Template mode builds reusable PowerPoint layouts only from explicit SVG metadata: root `data-pptx-layout`, direct-child `data-pptx-layer="master|layout"`, optional `data-pptx-layer="slide"` on a full-canvas solid background, and direct-child `data-pptx-placeholder`. It validates the per-page `pptx_layouts` lock plus cross-slide structure consistency and never infers layouts from visual similarity. Direct full-canvas solid rects compile to Master/Layout/Slide `p:bg` by scope; an unmarked one is a Slide override. Chart/table placeholders also require `--native-objects`. Full contract: [`shared-standards.md`](../../references/shared-standards.md#explicit-pptx-master--layout--placeholder-metadata-template-export).
- Native output uses content-hash media filenames, so identical images are reused and different images cannot overwrite each other by sharing a basename.
- `[Content_Types].xml` is generated from the actual media extensions written into the PPTX. Unknown media extensions fail unless Python's `mimetypes` can identify them.
- Native export writes to a temporary file first and publishes the requested PPTX only after conversion succeeds. A failed conversion does not replace the main output file.
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.py
index ceb83a67..c8748f6a 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -75,9 +75,17 @@ except ImportError:
try:
from svg_to_pptx.pptx_package.template_structure import (
+ TemplateStructureError as _TemplateStructureError,
+ load_pptx_structure_lock as _load_pptx_structure_lock,
+ parse_template_slides as _parse_template_structure_slides,
+ template_lock_errors as _template_lock_errors,
validate_template_svg as _validate_template_structure_svg,
)
except ImportError:
+ _TemplateStructureError = None
+ _load_pptx_structure_lock = None
+ _parse_template_structure_slides = None
+ _template_lock_errors = None
_validate_template_structure_svg = None
try:
@@ -317,6 +325,7 @@ class SVGQualityChecker:
self._template_issues: List[Tuple[str, str, str]] = []
self._animation_issues: List[Tuple[str, str]] = []
self._illustration_issues: List[Tuple[str, str, str]] = []
+ self._pptx_structure_issues: List[Tuple[str, str]] = []
self._aggregate_counts_applied = False
def check_file(self, svg_file: str, expected_format: str = None) -> Dict:
@@ -1415,6 +1424,7 @@ class SVGQualityChecker:
result = self.check_file(str(svg_file), expected_format)
self._print_result(result)
+ self._check_pptx_structure_contract(dir_path, svg_files)
if self.template_mode and dir_path.is_dir():
self._check_template_contract(dir_path, svg_files)
elif dir_path.is_dir():
@@ -1423,6 +1433,63 @@ class SVGQualityChecker:
return self.results
+ def _check_pptx_structure_contract(
+ self,
+ target_path: Path,
+ svg_files: List[Path],
+ ) -> None:
+ """Validate project-level layout reuse and spec_lock mappings."""
+ if (
+ _load_pptx_structure_lock is None
+ or _parse_template_structure_slides is None
+ or _template_lock_errors is None
+ or _TemplateStructureError is None
+ ):
+ return
+ project_path = self._resolve_project_path(target_path)
+ try:
+ structure_lock = _load_pptx_structure_lock(project_path)
+ except _TemplateStructureError as exc:
+ self._pptx_structure_issues.append(('error', str(exc)))
+ return
+
+ structure_attrs = {
+ 'data-pptx-layer',
+ 'data-pptx-layout',
+ 'data-pptx-layout-name',
+ 'data-pptx-placeholder',
+ 'data-pptx-placeholder-bounds',
+ 'data-pptx-editable',
+ }
+ has_metadata = False
+ for svg_path in svg_files:
+ try:
+ root = ET.parse(svg_path).getroot()
+ except (OSError, ET.ParseError):
+ continue
+ if any(
+ elem.get(attr) is not None
+ for elem in root.iter()
+ for attr in structure_attrs
+ ):
+ has_metadata = True
+ break
+ template_locked = structure_lock is not None and structure_lock.mode == 'template'
+ if not has_metadata and not template_locked:
+ return
+
+ try:
+ specs = _parse_template_structure_slides(svg_files)
+ except _TemplateStructureError as exc:
+ self._pptx_structure_issues.append(('error', str(exc)))
+ return
+ if not template_locked:
+ return
+ self._pptx_structure_issues.extend(
+ ('error', message)
+ for message in _template_lock_errors(specs, structure_lock)
+ )
+
def _check_illustration_resource_contract(self, dir_path: Path) -> None:
"""Project-level illustration resource checks."""
project_path = self._resolve_project_path(dir_path)
@@ -2101,6 +2168,9 @@ class SVGQualityChecker:
# Illustration strategy aggregation.
self._print_illustration_summary()
+ # Explicit PowerPoint master/layout structure aggregation.
+ self._print_pptx_structure_summary()
+
# Fix suggestions
if self.summary['errors'] > 0 or self.summary['warnings'] > 0:
print(f"\n[TIP] Common fixes:")
@@ -2141,6 +2211,14 @@ class SVGQualityChecker:
for _severity, kind, msg in warnings:
print(f" [{kind}] {msg}")
+ def _print_pptx_structure_summary(self):
+ """Print project-level PowerPoint structure contract issues."""
+ if not self._pptx_structure_issues:
+ return
+ print("\n[PPTX STRUCTURE] Master/layout contract checks")
+ for severity, message in self._pptx_structure_issues:
+ print(f" [{severity.upper()}] {message}")
+
def _print_template_summary(self):
"""Aggregate template-mode roster / placeholder issues at the bottom.
@@ -2194,6 +2272,13 @@ class SVGQualityChecker:
for severity, kind, _msg in self._illustration_issues:
self.issue_types[f'illustration_{kind}_{severity}'] += 1
+ structure_errors = [item for item in self._pptx_structure_issues if item[0] == 'error']
+ structure_warnings = [item for item in self._pptx_structure_issues if item[0] == 'warning']
+ self.summary['errors'] += len(structure_errors)
+ self.summary['warnings'] += len(structure_warnings)
+ for severity, _msg in self._pptx_structure_issues:
+ self.issue_types[f'pptx_structure_{severity}'] += 1
+
def _print_drift_summary(self):
"""Print spec_lock drift aggregation if any was observed.
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 88762358..7071de5e 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
@@ -241,29 +241,29 @@ def _remove_slide_background_xml(slide_xml: str) -> str:
return _SLIDE_BACKGROUND_RE.sub(r"\g<prefix>\g<suffix>", slide_xml, count=1)
-def _put_background_on_master(master_xml: str, background_xml: str) -> str | None:
- """Replace or insert the master-level p:bg before the master spTree.
+def _put_background_on_part(part_xml: str, background_xml: str) -> str | None:
+ """Replace or insert p:bg before a slide/master/layout spTree.
- Returns None when the master carries a p:bg the canonical pattern cannot
+ Returns None when the part carries a p:bg the canonical pattern cannot
replace; inserting there would leave two p:bg children under p:cSld.
"""
- match = _SLIDE_BACKGROUND_RE.search(master_xml)
+ match = _SLIDE_BACKGROUND_RE.search(part_xml)
if match:
return (
- master_xml[:match.start("bg")]
+ part_xml[:match.start("bg")]
+ background_xml
- + master_xml[match.end("bg"):]
+ + part_xml[match.end("bg"):]
)
- if "<p:bg" in master_xml:
+ if "<p:bg" in part_xml:
return None
- cslide_match = re.search(r"(<p:cSld\b[^>]*>)", master_xml)
+ cslide_match = re.search(r"(<p:cSld\b[^>]*>)", part_xml)
if not cslide_match:
- raise RuntimeError("Slide master XML has no p:cSld element")
+ raise RuntimeError("PPTX slide/master/layout part has no p:cSld element")
return (
- master_xml[:cslide_match.end()]
+ part_xml[:cslide_match.end()]
+ background_xml
- + master_xml[cslide_match.end():]
+ + part_xml[cslide_match.end():]
)
@@ -332,7 +332,7 @@ def _promote_common_slide_backgrounds_to_masters(
master_path = extract_dir / master_part
master_xml = master_path.read_text(encoding="utf-8")
- promoted_master_xml = _put_background_on_master(master_xml, background_xml)
+ promoted_master_xml = _put_background_on_part(master_xml, background_xml)
if promoted_master_xml is None:
continue
master_path.write_text(promoted_master_xml, encoding="utf-8")
@@ -903,6 +903,86 @@ def _slide_sp_tree(state: _TemplateRuntimeSlide) -> ET.Element:
return sp_tree
+def _presentation_slide_size_emu(extract_dir: Path) -> tuple[int, int]:
+ """Return the package slide size in EMU."""
+ presentation_path = extract_dir / "ppt" / "presentation.xml"
+ root = ET.parse(presentation_path).getroot()
+ slide_size = root.find(f"{{{PML_NS}}}sldSz")
+ if slide_size is None:
+ raise TemplateStructureError("presentation.xml has no p:sldSz")
+ try:
+ width = int(slide_size.attrib["cx"])
+ height = int(slide_size.attrib["cy"])
+ except (KeyError, ValueError) as exc:
+ raise TemplateStructureError("presentation.xml has an invalid p:sldSz") from exc
+ if width <= 0 or height <= 0:
+ raise TemplateStructureError("presentation.xml p:sldSz must be positive")
+ return width, height
+
+
+def _solid_background_xml_from_shape(
+ shape: ET.Element,
+ slide_size_emu: tuple[int, int],
+) -> str | None:
+ """Convert one exact full-slide solid rectangle shape into p:bg XML."""
+ if shape.tag != f"{{{PML_NS}}}sp":
+ return None
+ if shape.find(f"{{{PML_NS}}}txBody") is not None:
+ return None
+ sp_pr = shape.find(f"{{{PML_NS}}}spPr")
+ if sp_pr is None:
+ return None
+ xfrm = sp_pr.find(f"{{{DML_NS}}}xfrm")
+ if xfrm is None or xfrm.attrib:
+ return None
+ off = xfrm.find(f"{{{DML_NS}}}off")
+ ext = xfrm.find(f"{{{DML_NS}}}ext")
+ if off is None or ext is None:
+ return None
+ try:
+ bounds = (
+ int(off.attrib["x"]),
+ int(off.attrib["y"]),
+ int(ext.attrib["cx"]),
+ int(ext.attrib["cy"]),
+ )
+ except (KeyError, ValueError):
+ return None
+ if bounds != (0, 0, *slide_size_emu):
+ return None
+
+ geometry = sp_pr.find(f"{{{DML_NS}}}prstGeom")
+ if geometry is None or geometry.attrib.get("prst") != "rect":
+ return None
+ solid_fill = sp_pr.find(f"{{{DML_NS}}}solidFill")
+ if solid_fill is None:
+ return None
+ competing_fills = {
+ f"{{{DML_NS}}}noFill",
+ f"{{{DML_NS}}}gradFill",
+ f"{{{DML_NS}}}blipFill",
+ f"{{{DML_NS}}}pattFill",
+ f"{{{DML_NS}}}grpFill",
+ }
+ if any(child.tag in competing_fills for child in sp_pr):
+ return None
+ line = sp_pr.find(f"{{{DML_NS}}}ln")
+ if line is not None and line.find(f"{{{DML_NS}}}noFill") is None:
+ return None
+ for effect_tag in (f"{{{DML_NS}}}effectLst", f"{{{DML_NS}}}effectDag"):
+ effect = sp_pr.find(effect_tag)
+ if effect is not None and (effect.attrib or list(effect)):
+ return None
+
+ background = ET.Element(f"{{{PML_NS}}}bg")
+ background_props = ET.SubElement(background, f"{{{PML_NS}}}bgPr")
+ background_props.append(
+ ET.fromstring(ET.tostring(solid_fill, encoding="utf-8"))
+ )
+ ET.SubElement(background_props, f"{{{DML_NS}}}effectLst")
+ return ET.tostring(background, encoding="unicode")
+
+
def _remove_template_shape(
state: _TemplateRuntimeSlide,
shape: ET.Element,
@@ -947,7 +1027,7 @@ def _move_template_background(
if background_xml is None:
raise TemplateStructureError("Template background is unexpectedly empty")
target_xml = target_path.read_text(encoding="utf-8")
- updated = _put_background_on_master(target_xml, background_xml)
+ updated = _put_background_on_part(target_xml, background_xml)
if updated is None:
raise TemplateStructureError(
f"Cannot install explicit background on {target_path.name}"
@@ -966,11 +1046,109 @@ def _move_template_background(
c_sld.remove(background)
+def _move_template_solid_background_shapes(
+ states: list[_TemplateRuntimeSlide],
+ shapes: list[ET.Element],
+ target_path: Path,
+ slide_size_emu: tuple[int, int],
+) -> bool:
+ """Move repeated full-slide solid rects into a master/layout p:bg."""
+ backgrounds = [
+ _solid_background_xml_from_shape(shape, slide_size_emu)
+ for shape in shapes
+ ]
+ if not any(backgrounds):
+ return False
+ if any(background is None for background in backgrounds):
+ raise TemplateStructureError(
+ "A template background resolves to a full-slide solid rect on only "
+ "some slides sharing the structure"
+ )
+ canonical = {background for background in backgrounds if background is not None}
+ if len(canonical) != 1:
+ slide_names = ", ".join(state.spec.svg_path.name for state in states)
+ raise TemplateStructureError(
+ f"Explicit template solid background differs across slides: {slide_names}"
+ )
+ background_xml = backgrounds[0]
+ if background_xml is None:
+ return False
+ target_xml = target_path.read_text(encoding="utf-8")
+ updated = _put_background_on_part(target_xml, background_xml)
+ if updated is None:
+ raise TemplateStructureError(
+ f"Cannot install explicit solid background on {target_path.name}"
+ )
+ target_path.write_text(updated, encoding="utf-8")
+ for state, shape in zip(states, shapes):
+ _remove_template_shape(state, shape)
+ return True
+
+
+def _set_slide_tree_background(
+ state: _TemplateRuntimeSlide,
+ background_xml: str,
+) -> None:
+ """Replace the slide tree's p:bg with explicit background XML."""
+ c_sld = state.root.find(f"{{{PML_NS}}}cSld")
+ if c_sld is None:
+ raise TemplateStructureError(
+ f"{state.spec.svg_path.name}: slide has no p:cSld"
+ )
+ for existing in list(c_sld):
+ if existing.tag == f"{{{PML_NS}}}bg":
+ c_sld.remove(existing)
+ background = ET.fromstring(background_xml)
+ sp_tree_tag = f"{{{PML_NS}}}spTree"
+ insert_at = next(
+ (index for index, child in enumerate(c_sld) if child.tag == sp_tree_tag),
+ 0,
+ )
+ c_sld.insert(insert_at, background)
+
+
+def _apply_template_slide_backgrounds(
+ states: list[_TemplateRuntimeSlide],
+ slide_size_emu: tuple[int, int],
+) -> int:
+ """Compile one-page solid backgrounds into slide-level p:bg."""
+ applied = 0
+ for state in states:
+ items = [
+ item for item in state.spec.elements
+ if item.layer == "slide" and item.is_background
+ ]
+ if not items:
+ continue
+ item = items[0]
+ shape = _template_shape_for_item(state, item)
+ if shape is None:
+ c_sld = state.root.find(f"{{{PML_NS}}}cSld")
+ if c_sld is None or c_sld.find(f"{{{PML_NS}}}bg") is None:
+ raise TemplateStructureError(
+ f"{state.spec.svg_path.name}: slide background disappeared "
+ "during template structure assembly"
+ )
+ applied += 1
+ continue
+ background_xml = _solid_background_xml_from_shape(shape, slide_size_emu)
+ if background_xml is None:
+ raise TemplateStructureError(
+ f"{state.spec.svg_path.name}: {item.element_id!r} must remain an "
+ "exact full-slide solid rectangle"
+ )
+ _remove_template_shape(state, shape)
+ _set_slide_tree_background(state, background_xml)
+ applied += 1
+ return applied
+
+
def _move_template_static_shape(
states: list[_TemplateRuntimeSlide],
item: TemplateElementSpec,
target_path: Path,
target_rels_path: Path,
+ slide_size_emu: tuple[int, int],
) -> None:
shapes = [_template_shape_for_item(state, item) for state in states]
if any(shape is None for shape in shapes):
@@ -982,6 +1160,16 @@ def _move_template_static_shape(
return
resolved_shapes = [shape for shape in shapes if shape is not None]
+ if (
+ item.is_background
+ and _move_template_solid_background_shapes(
+ states,
+ resolved_shapes,
+ target_path,
+ slide_size_emu,
+ )
+ ):
+ return
canonical = {
_canonical_shape_xml(shape, state.rels)
for state, shape in zip(states, resolved_shapes)
@@ -1257,6 +1445,7 @@ def _apply_template_structure(
"""Materialize explicit SVG master/layout/placeholder metadata into OOXML."""
states = _template_runtime_slides(extract_dir, specs, conversion_traces)
states_by_slide = {state.spec.slide_num: state for state in states}
+ slide_size_emu = _presentation_slide_size_emu(extract_dir)
master_items = specs[0].master_elements
states_by_master: dict[str, list[_TemplateRuntimeSlide]] = {}
@@ -1273,6 +1462,7 @@ def _apply_template_structure(
item,
master_path,
master_rels_path,
+ slide_size_emu,
)
specs_by_layout: dict[str, list[TemplateSlideSpec]] = {}
@@ -1314,6 +1504,7 @@ def _apply_template_structure(
item,
layout_path,
layout_rels_path,
+ slide_size_emu,
)
layout_shape_count += 1
continue
@@ -1346,6 +1537,10 @@ def _apply_template_structure(
for state in layout_states:
_set_slide_layout_target(state.rels_path, layout_target)
+ slide_background_count = _apply_template_slide_backgrounds(
+ states,
+ slide_size_emu,
+ )
for state in states:
_write_xml_tree(state.slide_path, state.tree)
@@ -1355,6 +1550,7 @@ def _apply_template_structure(
f"{len(specs_by_layout)} layout(s), "
f"{len(master_items)} master element(s), "
f"{layout_shape_count} layout element(s), "
+ f"{slide_background_count} slide background(s), "
f"{placeholder_count} placeholder definition(s)"
)
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 78034de9..2611dd36 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
@@ -31,7 +31,12 @@ from .discovery import find_svg_files, find_notes_files
from .builder import create_pptx_with_native_svg
from .narration import NARRATION_EXTENSIONS, find_narration_files, probe_audio_duration
from .slide_xml import TRANSITIONS
-from .template_structure import TemplateStructureError
+from .template_structure import (
+ TemplateStructureError,
+ load_pptx_structure_lock,
+ parse_template_slides,
+ template_lock_errors,
+)
from ..animation_config import load_animation_config, validate_animation_config
try:
@@ -215,13 +220,13 @@ Recorded narration:
parser.add_argument(
'--pptx-structure',
choices=['baseline', 'template', 'flat'],
- default='baseline',
+ default=None,
help=(
- 'PPTX structure strategy for native export. baseline (default) keeps '
- 'a standard master/layout package and promotes safe repeated background/'
- 'chrome; template consumes explicit data-pptx-layout/layer/placeholder '
- 'metadata to build reusable layouts; flat leaves generated structure '
- 'slide-local for debugging/comparison.'
+ 'PPTX structure strategy for native export. When omitted, read '
+ 'spec_lock.md pptx_structure.mode, falling back to baseline. baseline '
+ 'promotes safe repeated background/chrome; template consumes explicit '
+ 'data-pptx-layout/layer/placeholder metadata to build reusable layouts; '
+ 'flat leaves generated structure slide-local for debugging/comparison.'
),
)
parser.add_argument('--svg-snapshot', action='store_true', default=False,
@@ -320,6 +325,15 @@ Recorded narration:
if not project_path.exists():
print(f"Error: Path does not exist: {project_path}")
return 1
+ structure_lock = None
+ pptx_structure = args.pptx_structure
+ if pptx_structure is None:
+ try:
+ structure_lock = load_pptx_structure_lock(project_path)
+ except TemplateStructureError as exc:
+ print(f"Error: {exc}", file=sys.stderr)
+ return 1
+ pptx_structure = structure_lock.mode if structure_lock else 'baseline'
if args.image_max_dimension < 1:
print("Error: --image-max-dimension must be >= 1", file=sys.stderr)
return 1
@@ -382,6 +396,19 @@ Recorded narration:
print("Error: No SVG files found")
return 1
+ if gen_native and pptx_structure == 'template' and structure_lock is not None:
+ try:
+ template_specs = parse_template_slides(native_files)
+ except TemplateStructureError as exc:
+ print(f"Error: {exc}", file=sys.stderr)
+ return 1
+ lock_errors = template_lock_errors(template_specs, structure_lock)
+ if lock_errors:
+ print("Error: PPTX structure does not match spec_lock.md:", file=sys.stderr)
+ for message in lock_errors:
+ print(f" {message}", file=sys.stderr)
+ return 1
+
if args.native_objects:
fallbacks = _native_object_fallbacks(native_files)
if fallbacks:
@@ -662,7 +689,7 @@ Recorded narration:
image_scale=args.image_scale,
image_quality=args.image_quality,
native_objects=args.native_objects,
- pptx_structure=args.pptx_structure,
+ pptx_structure=pptx_structure,
)
success = True
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/template_structure.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/template_structure.py
index 43f50543..a4d9350a 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/template_structure.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/template_structure.py
@@ -32,7 +32,7 @@ _STRUCTURE_ATTRS = frozenset({
"data-pptx-placeholder-bounds",
"data-pptx-editable",
})
-_LAYERS = frozenset({"master", "layout"})
+_LAYERS = frozenset({"master", "layout", "slide"})
_PLACEHOLDERS = frozenset({
"title",
"body",
@@ -44,12 +44,32 @@ _PLACEHOLDERS = frozenset({
})
_TEXT_PLACEHOLDERS = frozenset({"title", "body", "footer", "slide-number"})
_LAYOUT_KEY_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
+_LOCK_ROW_RE = re.compile(r"^-\s+([A-Za-z0-9_]+)\s*:\s*(.+?)\s*$")
+_LOCK_PAGE_RE = re.compile(r"^P(\d+)$")
+PPTX_STRUCTURE_MODES = frozenset({"baseline", "template", "flat"})
class TemplateStructureError(RuntimeError):
"""Reject invalid or ambiguous template-structure metadata."""
+@dataclass(frozen=True)
+class PptxLayoutReference:
+ """One spec_lock page-to-PowerPoint-layout declaration."""
+
+ slide_num: int
+ layout_key: str
+ layout_name: str | None = None
+
+
+@dataclass(frozen=True)
+class PptxStructureLock:
+ """Optional project-level PPTX structure export policy."""
+
+ mode: str
+ layouts: tuple[PptxLayoutReference, ...] = ()
+
+
@dataclass(frozen=True)
class TemplateElementSpec:
"""One direct SVG child carrying explicit PPTX structure metadata."""
@@ -60,6 +80,7 @@ class TemplateElementSpec:
layer: str | None = None
placeholder: str | None = None
placeholder_bounds: tuple[float, float, float, float] | None = None
+ is_background: bool = False
def contract_signature(self) -> tuple[object, ...]:
"""Return metadata that must agree across slides sharing a structure."""
@@ -69,6 +90,7 @@ class TemplateElementSpec:
self.layer,
self.placeholder,
self.placeholder_bounds,
+ self.is_background,
)
@@ -107,6 +129,150 @@ def _local_tag(elem: ET.Element) -> str:
return elem.tag.rsplit("}", 1)[-1] if isinstance(elem.tag, str) else ""
+def _svg_canvas(root: ET.Element) -> tuple[float, float, float, float]:
+ raw_viewbox = (root.get("viewBox") or "").strip()
+ values = [part for part in re.split(r"[\s,]+", raw_viewbox) if part]
+ if len(values) != 4:
+ return 0.0, 0.0, 0.0, 0.0
+ try:
+ x, y, width, height = (float(value) for value in values)
+ except ValueError:
+ return 0.0, 0.0, 0.0, 0.0
+ if not all(math.isfinite(value) for value in (x, y, width, height)):
+ return 0.0, 0.0, 0.0, 0.0
+ return x, y, width, height
+
+
+def _is_full_canvas_solid_rect(
+ elem: ET.Element,
+ canvas: tuple[float, float, float, float],
+) -> bool:
+ """Return whether a direct rect is eligible for scoped p:bg compilation."""
+ if canvas[2] <= 0 or canvas[3] <= 0:
+ return False
+ if _local_tag(elem) != "rect":
+ return False
+ if any(elem.get(attr) for attr in ("transform", "filter", "clip-path")):
+ return False
+ try:
+ geometry = (
+ float(elem.get("x", "0")),
+ float(elem.get("y", "0")),
+ float(elem.get("width", "0")),
+ float(elem.get("height", "0")),
+ )
+ corner_radius = (
+ float(elem.get("rx", "0")),
+ float(elem.get("ry", "0")),
+ )
+ except ValueError:
+ return False
+ if not all(math.isfinite(value) for value in (*geometry, *corner_radius)):
+ return False
+ if corner_radius != (0.0, 0.0):
+ return False
+ if any(abs(actual - expected) > 0.5 for actual, expected in zip(geometry, canvas)):
+ return False
+ fill = (elem.get("fill") or "").strip().lower()
+ if not fill or fill == "none" or fill.startswith("url("):
+ return False
+ stroke = (elem.get("stroke") or "none").strip().lower()
+ if stroke != "none":
+ try:
+ if float(elem.get("stroke-opacity", "1")) != 0:
+ return False
+ except ValueError:
+ return False
+ return True
+
+
+def load_pptx_structure_lock(project_path: Path) -> PptxStructureLock | None:
+ """Load optional pptx_structure/pptx_layouts sections from spec_lock.md."""
+ lock_path = project_path / "spec_lock.md"
+ if not lock_path.is_file():
+ return None
+ try:
+ lines = lock_path.read_text(encoding="utf-8").splitlines()
+ except OSError as exc:
+ raise TemplateStructureError(f"Cannot read {lock_path}: {exc}") from exc
+
+ sections: dict[str, list[tuple[str, str]]] = {}
+ current_section: str | None = None
+ for raw_line in lines:
+ line = raw_line.strip()
+ if line.startswith("## "):
+ current_section = line[3:].strip()
+ sections.setdefault(current_section, [])
+ continue
+ if current_section not in {"pptx_structure", "pptx_layouts"}:
+ continue
+ match = _LOCK_ROW_RE.fullmatch(line)
+ if match:
+ sections[current_section].append((match.group(1), match.group(2)))
+
+ structure_rows = sections.get("pptx_structure", [])
+ layout_rows = sections.get("pptx_layouts", [])
+ if not structure_rows and not layout_rows:
+ return None
+ mode_rows = [value.strip().lower() for key, value in structure_rows if key == "mode"]
+ if len(mode_rows) != 1:
+ raise TemplateStructureError(
+ "spec_lock.md pptx_structure requires exactly one '- mode:' row"
+ )
+ mode = mode_rows[0]
+ if mode not in PPTX_STRUCTURE_MODES:
+ allowed = ", ".join(sorted(PPTX_STRUCTURE_MODES))
+ raise TemplateStructureError(
+ f"spec_lock.md pptx_structure.mode must be one of: {allowed}"
+ )
+
+ references: list[PptxLayoutReference] = []
+ seen_slides: set[int] = set()
+ for page_key, raw_value in layout_rows:
+ page_match = _LOCK_PAGE_RE.fullmatch(page_key)
+ if not page_match or int(page_match.group(1)) <= 0:
+ raise TemplateStructureError(
+ f"spec_lock.md pptx_layouts key {page_key!r} must be P<NN>"
+ )
+ slide_num = int(page_match.group(1))
+ if slide_num in seen_slides:
+ raise TemplateStructureError(
+ f"spec_lock.md pptx_layouts repeats page P{slide_num:02d}"
+ )
+ seen_slides.add(slide_num)
+ value_parts = raw_value.split("|", 1)
+ layout_key = value_parts[0].strip()
+ layout_name = value_parts[1].strip() if len(value_parts) == 2 else None
+ if not _LAYOUT_KEY_RE.fullmatch(layout_key):
+ raise TemplateStructureError(
+ f"spec_lock.md P{slide_num:02d} has invalid layout key "
+ f"{layout_key!r}"
+ )
+ if len(value_parts) == 2 and not layout_name:
+ raise TemplateStructureError(
+ f"spec_lock.md P{slide_num:02d} has an empty layout name"
+ )
+ references.append(PptxLayoutReference(
+ slide_num=slide_num,
+ layout_key=layout_key,
+ layout_name=layout_name,
+ ))
+
+ if mode == "template" and not references:
+ raise TemplateStructureError(
+ "spec_lock.md template mode requires one pptx_layouts row per page"
+ )
+ if mode != "template" and references:
+ raise TemplateStructureError(
+ "spec_lock.md pptx_layouts is allowed only when pptx_structure.mode "
+ "is template"
+ )
+ return PptxStructureLock(
+ mode=mode,
+ layouts=tuple(sorted(references, key=lambda item: item.slide_num)),
+ )
+
+
def _parse_placeholder_bounds(
raw: str | None,
*,
@@ -228,7 +394,8 @@ def parse_template_slide(svg_path: Path, slide_num: int) -> TemplateSlideSpec:
)
elements: list[TemplateElementSpec] = []
- phase = "master"
+ canvas = _svg_canvas(root)
+ last_order_rank = -1
visual_order = 0
for elem in root:
tag = _local_tag(elem)
@@ -244,6 +411,8 @@ def parse_template_slide(svg_path: Path, slide_num: int) -> TemplateSlideSpec:
)
bounds_raw = elem.get("data-pptx-placeholder-bounds")
editable_raw = elem.get("data-pptx-editable")
+ is_background = _is_full_canvas_solid_rect(elem, canvas)
+ effective_layer = layer or ("slide" if is_background else None)
if (
elem.get("data-pptx-layout") is not None
@@ -272,42 +441,47 @@ def parse_template_slide(svg_path: Path, slide_num: int) -> TemplateSlideSpec:
f"{svg_path.name}: {element_id or tag} has empty "
"data-pptx-placeholder"
)
- if layer and placeholder:
+ if effective_layer and placeholder:
raise TemplateStructureError(
f"{svg_path.name}: {element_id or tag} cannot be both a static "
- "master/layout layer and a content placeholder"
+ "structure/background layer and a content placeholder"
+ )
+ if layer == "slide" and not is_background:
+ raise TemplateStructureError(
+ f"{svg_path.name}: data-pptx-layer='slide' is allowed only on a "
+ "direct full-canvas solid background rect"
)
if bounds_raw is not None and not placeholder:
raise TemplateStructureError(
f"{svg_path.name}: {element_id or tag} has placeholder bounds without "
"data-pptx-placeholder"
)
- if (layer or placeholder) and not element_id:
+ if (effective_layer or placeholder) and not element_id:
raise TemplateStructureError(
f"{svg_path.name}: direct <{tag}> with template metadata requires an id"
)
if editable_raw is not None:
- if not layer or editable_raw.strip().lower() != "false":
+ if not effective_layer or editable_raw.strip().lower() != "false":
raise TemplateStructureError(
f"{svg_path.name}: data-pptx-editable currently supports only "
- "'false' on master/layout layer elements"
+ "'false' on master/layout elements or slide backgrounds"
)
- if layer == "master":
- if phase != "master":
- raise TemplateStructureError(
- f"{svg_path.name}: master layer element {element_id} must precede "
- "all layout and slide-local content"
- )
- elif layer == "layout":
- if phase == "slide":
- raise TemplateStructureError(
- f"{svg_path.name}: layout layer element {element_id} must precede "
- "all slide-local content"
- )
- phase = "layout"
+ if is_background:
+ order_rank = {"master": 0, "layout": 1, "slide": 2}[effective_layer]
+ elif effective_layer == "master":
+ order_rank = 3
+ elif effective_layer == "layout":
+ order_rank = 4
else:
- phase = "slide"
+ order_rank = 5
+ if order_rank < last_order_rank:
+ raise TemplateStructureError(
+ f"{svg_path.name}: {element_id or tag} violates template paint order; "
+ "use Master background, Layout background, Slide background, "
+ "Master shapes, Layout shapes, then Slide content/placeholders"
+ )
+ last_order_rank = order_rank
if placeholder:
_validate_placeholder_element(
@@ -322,17 +496,29 @@ def parse_template_slide(svg_path: Path, slide_num: int) -> TemplateSlideSpec:
element_id=element_id or tag,
)
- if layer or placeholder:
+ if effective_layer or placeholder:
elements.append(TemplateElementSpec(
element_id=element_id,
order=visual_order,
tag=tag,
- layer=layer,
+ layer=effective_layer,
placeholder=placeholder,
placeholder_bounds=placeholder_bounds,
+ is_background=is_background,
))
visual_order += 1
+ for scope in ("master", "layout", "slide"):
+ backgrounds = [
+ item for item in elements
+ if item.layer == scope and item.is_background
+ ]
+ if len(backgrounds) > 1:
+ raise TemplateStructureError(
+ f"{svg_path.name}: template mode allows at most one {scope} "
+ "solid background"
+ )
+
return TemplateSlideSpec(
slide_num=slide_num,
svg_path=svg_path,
@@ -385,6 +571,51 @@ def parse_template_slides(svg_files: list[Path]) -> list[TemplateSlideSpec]:
return specs
+def template_lock_errors(
+ specs: list[TemplateSlideSpec],
+ structure_lock: PptxStructureLock,
+) -> list[str]:
+ """Return mismatches between parsed SVG layouts and the project lock."""
+ if structure_lock.mode != "template":
+ return []
+ errors: list[str] = []
+ references = {
+ reference.slide_num: reference
+ for reference in structure_lock.layouts
+ }
+ actual_slides = {spec.slide_num for spec in specs}
+ expected_slides = set(references)
+ missing = sorted(actual_slides - expected_slides)
+ extra = sorted(expected_slides - actual_slides)
+ if missing:
+ pages = ", ".join(f"P{slide_num:02d}" for slide_num in missing)
+ errors.append(
+ f"spec_lock.md pptx_layouts is missing generated page(s): {pages}"
+ )
+ if extra:
+ pages = ", ".join(f"P{slide_num:02d}" for slide_num in extra)
+ errors.append(
+ f"spec_lock.md pptx_layouts references absent page(s): {pages}"
+ )
+ for spec in specs:
+ reference = references.get(spec.slide_num)
+ if reference is None:
+ continue
+ if spec.layout_key != reference.layout_key:
+ errors.append(
+ f"{spec.svg_path.name}: data-pptx-layout={spec.layout_key!r} "
+ f"does not match spec_lock P{spec.slide_num:02d} layout key "
+ f"{reference.layout_key!r}"
+ )
+ if reference.layout_name and spec.layout_name != reference.layout_name:
+ errors.append(
+ f"{spec.svg_path.name}: data-pptx-layout-name={spec.layout_name!r} "
+ f"does not match spec_lock P{spec.slide_num:02d} layout name "
+ f"{reference.layout_name!r}"
+ )
+ return errors
+
+
def validate_template_svg(svg_path: Path) -> list[str]:
"""Return per-file template metadata errors for quality-check integration."""
try:
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index e282ab40..98212254 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -120,6 +120,29 @@
>
> **Missing or empty section** → Executor falls back to `dense` for every page (legacy pre-rhythm behavior). Remove the section only for legacy decks; new decks MUST fill it.
+## pptx_structure
+- mode: baseline
+
+> One deck-wide native PowerPoint structure policy. New projects always include this section.
+>
+> - `baseline` — default. Preserve the conservative shared Master/background/chrome behavior; no explicit reusable placeholder layouts are authored.
+> - `template` — use only when the user explicitly requests a reusable PowerPoint template/master/layout deliverable. Requires a complete `pptx_layouts` section and explicit SVG structure metadata on every generated page.
+> - `flat` — diagnostic escape hatch. Do not lock this in a normal project; pass it on the CLI when comparing slide-local output.
+
+## pptx_layouts
+
+> Emit this section only when `pptx_structure.mode` is `template`. Include exactly one row per generated page. Value format: `<layout_key> | <PowerPoint layout name>`.
+>
+> Example:
+> ```
+> - P01: cover | Cover
+> - P02: title-content | Title and Content
+> - P03: title-content | Title and Content
+> - P04: section | Section Header
+> ```
+>
+> Reuse one key only when pages share the same static layout layer and placeholder contract. Do not generate one unique key per slide merely because every page has different content. A one-off cover/section layout is valid; content differences stay slide-local.
+
## page_layouts
- P01: 01_cover
- P03: 02a_chapter
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index 7688f5c2..dbf84ea1 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -320,7 +320,7 @@ Mirror mode does **not** invoke the "reconstruct into clean SVG" pathway. The sp
1. `design_spec.md` — **personality only**. Required sections: Template Overview, Color Scheme, Signature Design Elements, Page Roster (matching the actual SVG files on disk). Skip Typography / Assets / Placeholder Overrides when they would just restate defaults. Declare brief frontmatter for `register_template.py`. **Do not** restate generic SVG constraints, layout pattern libraries, font-size ratio bands, the canonical placeholder table, or content methodology — those are sourced from `shared-standards.md` / `design_spec_reference.md` / `strategist.md` and are already in the downstream reader's context. Full scope rule and skeleton: [template-designer.md §1](../references/template-designer.md#1-must-generate-design_specmd).
2. Page roster — see [Page Roster](../references/template-designer.md#page-roster) for `standard` / `fidelity` / `mirror` mode rosters, variant naming, and TOC handling
3. Placeholder vocabulary — pages should adopt the conventional names (`{{TITLE}}`, `{{CONTENT_AREA}}`, ...) when they fit. Full reference: [Placeholder Reference](../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template). When a template style legitimately needs different vocabulary (consulting → `{{KEY_MESSAGE}}`, branded cover → `{{BRAND_LOGO}}`), declare a `placeholders:` block in `design_spec.md` frontmatter so the registrar and quality checker treat it as the template's authoritative contract. **Avoid** one-off indexed families such as `{{CHAPTER_01_TITLE}}` — use the indexed TOC pattern instead.
- - `{{...}}` placeholders are the authoring contract used to generate final slide content; they are not PowerPoint `p:ph` objects. If the downstream deliverable must expose reusable PowerPoint layouts, the final generated slide SVGs must separately follow the explicit `data-pptx-layout` / `data-pptx-layer` / `data-pptx-placeholder` contract in [shared standards](../references/shared-standards.md#explicit-pptx-master--layout--placeholder-metadata-template-export) and export with `--pptx-structure template`.
+ - `{{...}}` placeholders are the authoring contract used to generate final slide content; they are not PowerPoint `p:ph` objects. If the downstream deliverable must expose reusable PowerPoint layouts, lock `pptx_structure.mode: template`, map every page under `pptx_layouts`, and make the final generated slide SVGs follow the explicit `data-pptx-layout` / `data-pptx-layer` / `data-pptx-placeholder` contract in [shared standards](../references/shared-standards.md#explicit-pptx-master--layout--placeholder-metadata-template-export).
4. Template assets (optional) — Logos / PNG / JPG / reference SVG bundled with the template package
---