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

fix(pptx-layouts): stop free-design layout collapse and bare-layout export

hugohe3a719843db145
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 967f190c..9e30366e 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -631,7 +631,7 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon
Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Before drawing a literal stock shape, apply [`native-shape-authoring.md`](references/native-shape-authoring.md): use the stdout-only helper when one PowerPoint preset exactly matches, keep basic SVG primitives for rect/round-rect/ellipse, and keep free SVG for custom semantics. Never infer a preset from contour similarity.
-Every newly generated page root MUST declare the locked `data-pptx-layout` and `data-pptx-layout-name`, including free-design/brand-only pages that remain in `baseline` mode. Do not duplicate that identity with `data-pptx-page-role`; only a legacy baseline project whose whole `pptx_layouts` section is absent uses the canonical page-role marker. Add `data-pptx-role` only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by `data-pptx-layer`, `data-pptx-placeholder`, or `data-pptx-native`; such an element needs a stable unique `id`. Do not add generic content roles to ordinary titles, body text, cards, KPIs, diagrams, charts, icons, or images. Full contract: [`references/semantic-svg.md`](references/semantic-svg.md).
+Every newly generated page root MUST declare the locked `data-pptx-layout` and `data-pptx-layout-name`, including free-design/brand-only pages that remain in `baseline` mode. Every mapped page MUST also mark the standard placeholder slots it actually has — `title` / `subtitle` / `body` / `picture` / `slide-number` / `footer` per [`executor-base.md`](references/executor-base.md) §1.2 — and its `data-pptx-layer` marks: the deck-wide background as `master`, this layout key's static framing as `layout`. A mapped page normally ships at least its title placeholder and master-background mark, or its Layout exports as a bare frame with no insertable slots. Do not duplicate that identity with `data-pptx-page-role`; only a legacy baseline project whose whole `pptx_layouts` section is absent uses the canonical page-role marker. Add `data-pptx-role` only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by `data-pptx-layer`, `data-pptx-placeholder`, or `data-pptx-native`; such an element needs a stable unique `id`. Do not add generic content roles to ordinary titles, body text, cards, KPIs, diagrams, charts, icons, or images. Full contract: [`references/semantic-svg.md`](references/semantic-svg.md).
**Quality Check Gate (Mandatory)** — after all SVGs, BEFORE annotation handling and speaker notes:
```bash
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 79c90115..b741ed80 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -117,6 +117,10 @@ Before generating each page, output which template is used:
**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.
+**Mandatory — per-page placeholder coverage**: On every mapped page, mark each standard slot the page actually has: the page heading as `title` (one direct `<text>`), a cover tagline as `subtitle`, the page number as `slide-number`, running footer text as `footer`, a hero / content image as `picture`, and a body block already authored as one merged dy-stacked `<text>` as `body`. A page shipping zero placeholders exports a Layout with no insertable slots — valid only when the page genuinely has none of these. Pages sharing one layout key ship the same slot set (see the shared-contract rules below).
+
+**Mandatory — master/layout layer coverage**: On every mapped page, mark the deck-wide background and every-page chrome (footer bar, running logo) `data-pptx-layer="master"`, and mark the static framing that defines this layout key's composition (divider band, header rule, zone panels) `data-pptx-layer="layout"`. A mapped page with zero `data-pptx-layer` marks exports a bare Master and an empty Layout — the layer marks, not the slide content, are what give each Layout its visible design.
+
**Placeholder ownership**: Keep actual title/subtitle/body/picture/chart/table/object/media/date/footer/slide-number content on the Slide and add the matching `data-pptx-placeholder`. Do not duplicate placeholder identity with `data-pptx-role`; in particular, `data-pptx-placeholder="slide-number"` already owns page-number field behavior. A reconstructed `title` normally omits `data-pptx-placeholder-idx`; preserve an explicit imported title index when present. Every indexed placeholder on one Layout uses a unique index. Chart/table placeholders require native markers and a later `--native-objects` export; object/media placeholders must each resolve to one top-level DrawingML object.
**Atomic placeholder carrier exception**: A normal title/subtitle/body/date/footer/slide-number placeholder is one direct `<text>`; picture/media is one direct `<image>` or imported crop `<svg>`; object is one direct supported atomic object. These direct carriers are the narrow exception to the mandatory top-level `<g>` rule and do not count against the 3–8 content-group budget. Do not wrap multiple drawing atoms in an arbitrary `<g>` and promise that the composite is one placeholder. The separately specified chart/table native-marker group remains its own specialized contract. Any other complex `<g>` composition stays Slide-local without placeholder metadata.
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index d71f416b..52ade3ca 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -852,8 +852,8 @@ This is what makes the axis meaningful: a `presentation` deck and a `text` deck
- **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` for free design and brand-only routes. When a deck/layout template is confirmed, write `mode: template` plus `template_adherence: strict|adaptive`. Both adherence values stay on explicit template export. Use `mode: preserve` only when reopening a legacy strict project that already carries a validated `native_structure.json` + `source_template.pptx` pair. Do not choose `flat`; it is a CLI-only diagnostic override.
- - **pptx_layouts (native output Layout contract)**: Write one `P<NN>: <layout_key> | <PowerPoint layout name>` row for every page in every new generated deck. Free-design and brand-only routes remain `mode: baseline`; derive stable keys and picker names from the compositions planned in §IX, without adding `page_layouts`. Template strict uses the selected template SVG's exact key/name; adaptive may introduce a new stable key/name. Legacy preserve uses the exact source key/name. A legacy baseline project whose whole section is absent remains valid and uses page-role compatibility behavior.
- - **Layout-family boundary**: Reuse a key only when pages share the same reusable static Layout layer and the same placeholder type/index/bounds contract. Assign a different key when the real reusable composition changes, even if the pages share a semantic role; do not split keys merely because slide-local wording, data, or imagery differs. Decide these families from the authored page plan — never by post-hoc visual clustering, filenames, or content similarity. Keep concrete slide content and complex grouped compositions Slide-local; they are not Layout material.
+ - **pptx_layouts (native output Layout contract)**: Write one `P<NN>: <layout_key> | <PowerPoint layout name>` row for every page in every new generated deck. Free-design and brand-only routes remain `mode: baseline`; derive stable keys and picker names from the compositions planned in §IX, without adding `page_layouts`. Name each key after its composition (`timeline-spine`, `kpi-band-trio`), never after a PowerPoint stock role. Template strict uses the selected template SVG's exact key/name; adaptive may introduce a new stable key/name. Legacy preserve uses the exact source key/name. A legacy baseline project whose whole section is absent remains valid and uses page-role compatibility behavior.
+ - **Layout-family boundary**: Different reusable composition → different key; a free-design deck of visually distinct pages yields close to one key per page. Reuse a key only when pages share the same reusable static Layout layer and the same placeholder type/index/bounds contract; do not split keys merely because slide-local wording, data, or imagery differs. Decide these families from the authored page plan — never by post-hoc visual clustering, filenames, or content similarity. Keep concrete slide content and complex grouped compositions Slide-local; they are not Layout material. **Self-check before writing the section**: count distinct keys against the distinct compositions in §IX — a deck of mostly distinct pages collapsing to a handful of role keys (`cover` / `title-content` / `section`) means pages were clustered by role, not composition; re-derive.
- **page_layouts (deck/layout templates only)**: Add one `P<NN>: <svg_basename>` row for every page. Strict inherits that SVG contract unchanged. Adaptive uses it as the architecture reference and may evolve the Layout layer under a new `pptx_layouts` key; it must not drop into free design. Omit the whole section for free-design and brand-only routes; their required `pptx_layouts` rows do not imply an SVG template reference.
- **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` only with a compatible template shell. For a chart page without an exact roster match, adaptive mode selects the closest neutral content template and assigns a new explicit Layout key; strict mode must select an existing compatible Layout or revise the outline. Never omit `page_layouts` inside a deck/layout template route.
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.py
index 31e45c3a..2bf770f0 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -1716,6 +1716,28 @@ class SVGQualityChecker:
for attr in structure_attrs
):
return
+ if root.get('data-pptx-layout') is not None:
+ if not any(
+ elem.get('data-pptx-placeholder') is not None
+ for elem in root.iter()
+ ):
+ result['warnings'].append(
+ "Mapped page declares data-pptx-layout but no data-pptx-placeholder "
+ "slot; its Layout exports without insertable placeholders. Mark the "
+ "page's real slots (title / subtitle / body / picture / slide-number "
+ "/ footer) unless the page genuinely has none."
+ )
+ if not any(
+ elem.get('data-pptx-layer') is not None
+ for elem in root.iter()
+ ):
+ result['warnings'].append(
+ "Mapped page declares data-pptx-layout but no data-pptx-layer mark; "
+ "the exported Master gets no shared background/chrome and the Layout "
+ "gets no static framing. Mark the deck-wide background "
+ 'data-pptx-layer="master" and this layout key\'s framing '
+ 'data-pptx-layer="layout".'
+ )
if _validate_template_structure_svg is None:
result['warnings'].append(
"Detected PPTX template structure metadata, but its validator "
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index 02b83d43..a97aedd6 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -155,13 +155,14 @@
>
> Example:
> ```
-> - P01: cover | Cover
-> - P02: title-content | Title and Content
-> - P03: title-content | Title and Content
-> - P04: section | Section Header
+> - P01: cover-hero-split | Cover — Hero Split
+> - P02: kpi-band-trio | KPI Band Trio
+> - P03: section-divider | Section Divider
+> - P04: timeline-spine | Timeline Spine
+> - P05: section-divider | Section Divider
> ```
>
-> Reuse one key only when pages share the same reusable static Layout layer and placeholder type/index/bounds contract. Give genuinely different reusable compositions different keys even when they share a page role. Do not generate one unique key per slide merely because its wording, data, or imagery differs. Choose keys from the authored page plan, never from visual clustering, filenames, or content similarity. Keep concrete content and complex grouped compositions Slide-local; do not move them into the Layout to manufacture reuse.
+> **Different reusable composition → different key.** A free-design deck of visually distinct pages yields close to one key per page; reuse one key only for a genuinely repeated composition — the same static Layout layer and placeholder type/index/bounds contract (recurring section dividers, a repeated content template). Name keys after the composition (`timeline-spine`), never after PowerPoint stock roles: distinct compositions collapsing into `title-content` / `section` role keys produces a deck whose Layouts do not match its pages. Do not split a genuinely shared key merely because slide-local wording, data, or imagery differs. Choose keys from the authored page plan, never from visual clustering, filenames, or content similarity. Keep concrete content and complex grouped compositions Slide-local; do not move them into the Layout to manufacture reuse.
## page_layouts
- P01: 01_cover