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): keep layout keys aligned with real compositions

hugohe3eb3e6a0ca877
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index b741ed80..ac04e52b 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -121,6 +121,8 @@ Before generating each page, output which template is used:
**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.
+**Mandatory — different keys differ in the Layout layer**: Pages locked to different layout keys must not carry identical Layout-layer contracts, or they compile to duplicate Layouts. Materialize each composition's identity as Layout-layer zone framing — the table backing panel and its header band, the column panels or central divider, the hero image frame — while the zone's labels, data, and imagery stay Slide-local. When no framing genuinely distinguishes two keys, the pages are one composition: use one key.
+
**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 52ade3ca..182027a4 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`. 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.
+ - **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 or the page's topic. 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**: The key identifies the page's composition — its chrome, zone framing, and placeholder set — not its topic and not its slide-local content. Series pages repeating one composition (three directional timetable pages, per-chapter dividers) share one key; a genuinely different composition gets its own key, and the Executor materializes that difference as Layout-layer zone framing (executor-base.md §1.2). Do not split keys because slide-local wording, data, or imagery differ within one composition. Decide families from the authored page plan — never by post-hoc visual clustering, filenames, or content similarity. **Self-check before writing the section** — two failure signals: distinct keys for pages of one composition (topic-splitting; they compile to duplicate Layouts) and one role key covering different compositions (role-clustering; the Layout matches none of them). Re-derive on either.
- **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 2bf770f0..8671f513 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -2318,6 +2318,10 @@ class SVGQualityChecker:
('error', message)
for message in _template_lock_errors(specs, structure_lock)
)
+ self._pptx_structure_issues.extend(
+ ('warning', message)
+ for message in self._duplicate_layout_key_warnings(specs)
+ )
return
if not structure_locked:
return
@@ -2350,6 +2354,68 @@ class SVGQualityChecker:
)
)
+ def _duplicate_layout_key_warnings(self, specs) -> List[str]:
+ """Flag distinct layout keys whose static contracts are identical.
+
+ Keys split by page topic over one shared skeleton compile into
+ duplicate PowerPoint Layouts; the fingerprint compares the
+ id-insensitive layout-layer drawing plus the placeholder contract.
+ """
+ prototypes: Dict[str, Path] = {}
+ for spec in specs:
+ prototypes.setdefault(spec.layout_key, spec.svg_path)
+ if len(prototypes) < 2:
+ return []
+ fingerprint_keys: Dict[tuple, List[str]] = {}
+ for layout_key, svg_path in prototypes.items():
+ fingerprint = self._layout_contract_fingerprint(svg_path)
+ if fingerprint is None:
+ continue
+ fingerprint_keys.setdefault(fingerprint, []).append(layout_key)
+ messages = []
+ for keys in fingerprint_keys.values():
+ if len(keys) < 2:
+ continue
+ joined = ', '.join(sorted(keys))
+ messages.append(
+ f"layout keys {joined} declare identical static Layout framing "
+ "and placeholder contracts; they compile to duplicate Layouts. "
+ "Either merge them into one composition key (spec_lock.md "
+ "pptx_layouts + each SVG root), or — when the compositions "
+ "genuinely differ — promote each key's distinguishing zone "
+ 'framing (table backing panel, column panels, hero frame) to '
+ 'data-pptx-layer="layout" so the keys diverge.'
+ )
+ return messages
+
+ @staticmethod
+ def _layout_contract_fingerprint(svg_path: Path):
+ """Id-insensitive static contract: layout-layer XML + placeholder slots."""
+ try:
+ root = ET.parse(str(svg_path)).getroot()
+ except (OSError, ET.ParseError):
+ return None
+ layout_parts = []
+ placeholder_parts = []
+ for child in list(root):
+ if child.get('data-pptx-layer') == 'layout':
+ clone = copy.deepcopy(child)
+ for elem in clone.iter():
+ elem.attrib.pop('id', None)
+ xml = ET.tostring(clone, encoding='unicode')
+ layout_parts.append(re.sub(r'\s+', ' ', xml).strip())
+ placeholder = child.get('data-pptx-placeholder')
+ if placeholder is not None:
+ placeholder_parts.append((
+ placeholder,
+ child.tag.rsplit('}', 1)[-1],
+ child.get('x') or '',
+ child.get('y') or '',
+ child.get('data-pptx-placeholder-bounds') or '',
+ child.get('data-pptx-placeholder-idx') or '',
+ ))
+ return (tuple(layout_parts), tuple(sorted(placeholder_parts)))
+
def _check_illustration_resource_contract(self, dir_path: Path) -> None:
"""Project-level illustration resource checks."""
project_path = self._resolve_project_path(dir_path)
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index a97aedd6..9dc0415d 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -162,7 +162,7 @@
> - P05: section-divider | Section Divider
> ```
>
-> **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.
+> **One key per distinct composition — chrome, zone framing, and placeholder contract.** Series pages repeating one composition (e.g., three directional timetable pages) share one key; a genuinely different composition gets its own key, and its distinguishing zone framing (table backing panel, column panels, hero frame) is authored at the Layout layer so different keys compile to genuinely different Layouts. Name keys after the composition (`timeline-spine`, `section-divider`), never after PowerPoint stock roles or page topics: role keys (`title-content`) collapse different compositions into one mismatched Layout, and topic keys (`timetable-yungui` / `timetable-guangxi`) split one composition into duplicate Layouts. Do not split a 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. Zone labels, data, and complex grouped compositions stay Slide-local; do not move concrete content into the Layout to manufacture reuse.
## page_layouts
- P01: 01_cover