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): reject divergent fixed-layer payloads

hugohe3a23bc0549af7
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 442c04b0..fe15a9f9 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -636,7 +636,7 @@ Each completed SVG MUST be a standalone, complete representation of that slide's
Template pages MUST start from the complete `page_layouts` SVG, keep all inherited visible objects in `svg_output/`, and preserve the locked root Master/Layout identity plus stable atomic Master/Layout and slot ids. Strict keeps the prototype structure unchanged. Adaptive keeps its Master contract and, when Layout atoms or slot topology/bounds genuinely evolve, assigns a new key/name and updates `spec_lock.md` immediately. Non-mirror fill/stroke/effects/font sizes still follow `spec_lock`.
-Free-design and brand-only pages are also structured from the first draft. Use the planned Master roster and page Layout mapping, author Master/Layout fixed visuals only as direct root atoms (never `<g>`), and author reusable content zones as top-level slot groups with positive bounds plus exactly one compatible carrier. Every mapped page MUST mark the standard slots it actually has — `title` / `subtitle` / `body` / `picture` / `slide-number` / `footer` — and its `data-pptx-layer` marks: the deck-wide background and every-page chrome as `master`, this layout key's static framing (including chrome repeated on content pages but absent from the cover) as `layout`, per [`executor-base.md`](references/executor-base.md) §1.2. Repeated chrome and per-page headings never stay Slide-local by default; a page shipping only a marked background exports a bare Master and an empty Layout. A Layout may intentionally have zero slots — a stated decision for a fixed composition, never a silent default. Do not add `data-pptx-layout-kind`, `distilled`, `utility`, or a full-page fake slot.
+Free-design and brand-only pages are also structured from the first draft. Use the planned Master roster and page Layout mapping, author Master/Layout fixed visuals only as direct root atoms (never `<g>`), and author reusable content zones as top-level slot groups with positive bounds plus exactly one compatible carrier. Every mapped page MUST mark the standard slots it actually has — `title` / `subtitle` / `body` / `picture` / `slide-number` / `footer` — and its `data-pptx-layer` marks: the deck-wide background and every-page chrome as `master`, this layout key's static framing (including chrome repeated on content pages but absent from the cover) as `layout`, per [`executor-base.md`](references/executor-base.md) §1.2. Repeated chrome stays on its appropriate Master/Layout layer; a per-page heading that should not remain Slide-local is authored as a `title` or `subtitle` slot, never as a fixed Layout atom. Any text or image whose value varies across pages sharing one Layout key MUST be carried by a slot or remain Slide-local. A page shipping only a marked background exports a bare Master and an empty Layout. A Layout may intentionally have zero slots — a stated decision for a fixed composition, never a silent default. Do not add `data-pptx-layout-kind`, `distilled`, `utility`, or a full-page fake slot.
Do not duplicate specialized identity with `data-pptx-role`. Add it 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).
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index c81c4180..2baa15a1 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -112,6 +112,8 @@ Before generating each page, output which template is used:
**Mandatory — per-page slot coverage**: On every mapped page, declare a slot for each standard role the page actually has: the page heading as `title`, 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 text frame as `body`. A page shipping zero slots exports a Layout with no insertable placeholders — valid only for a genuinely fixed composition (see Zero-slot Layout above), never as the deck-wide default. Pages sharing one layout key ship the same slot set.
+**Hard rule — variable slot content**: “Per-page headings never stay Slide-local by default” means authoring them as `title` / `subtitle` slots; it never permits page-varying text or images to become fixed Layout atoms. Any such value that varies across pages sharing one Layout key MUST be carried by a slot or remain Slide-local.
+
**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 (header rule, divider band, zone panels — including chrome repeated on every content page but absent from the cover) `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, give each Layout its visible design.
**Layout identity**: Different keys differ in fixed Layout atoms or slot topology/default bounds/binding modes. Identical contracts should share one key. Current wording, imagery, crop, and Slide-local geometry never define identity.
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.py
index 1404506e..1e40a183 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -175,6 +175,7 @@ try:
load_pptx_structure_lock as _load_pptx_structure_lock,
parse_template_slide as _parse_template_structure_slide,
parse_template_slides as _parse_template_structure_slides,
+ _structure_subtree_signature as _structure_subtree_signature,
template_lock_errors as _template_lock_errors,
template_prototype_errors as _template_prototype_errors,
validate_template_svg as _validate_template_structure_svg,
@@ -184,6 +185,7 @@ except ImportError:
_load_pptx_structure_lock = None
_parse_template_structure_slide = None
_parse_template_structure_slides = None
+ _structure_subtree_signature = None
_template_lock_errors = None
_template_prototype_errors = None
_validate_template_structure_svg = None
@@ -2498,6 +2500,7 @@ class SVGQualityChecker:
_load_pptx_structure_lock is None
or _parse_template_structure_slide is None
or _parse_template_structure_slides is None
+ or _structure_subtree_signature is None
or _template_lock_errors is None
or _TemplateStructureError is None
):
@@ -2514,6 +2517,10 @@ class SVGQualityChecker:
except _TemplateStructureError as exc:
self._pptx_structure_issues.append(('error', str(exc)))
return
+ self._pptx_structure_issues.extend(
+ ('error', message)
+ for message in self._shared_fixed_layer_errors(specs)
+ )
self._pptx_structure_issues.extend(
('warning', message)
for message in self._duplicate_layout_key_warnings(specs)
@@ -2589,6 +2596,10 @@ class SVGQualityChecker:
require_complete_roster=complete_roster,
)
)
+ self._pptx_structure_issues.extend(
+ ('error', message)
+ for message in self._shared_fixed_layer_errors(specs)
+ )
self._pptx_structure_issues.extend(
('warning', message)
for message in self._duplicate_layout_key_warnings(specs)
@@ -2680,6 +2691,82 @@ class SVGQualityChecker:
)
return messages
+ @classmethod
+ def _shared_fixed_layer_errors(cls, specs) -> List[str]:
+ """Reject fixed atoms whose payload varies inside one reuse scope."""
+ master_groups = defaultdict(list)
+ layout_groups = defaultdict(list)
+ for spec in specs:
+ master_groups[spec.master_key].append(spec)
+ layout_groups[(spec.master_key, spec.layout_key)].append(spec)
+
+ try:
+ errors = cls._fixed_layer_group_errors(master_groups, 'master')
+ errors.extend(cls._fixed_layer_group_errors(layout_groups, 'layout'))
+ except _TemplateStructureError as exc:
+ return [str(exc)]
+ return errors
+
+ @classmethod
+ def _fixed_layer_group_errors(cls, groups, layer: str) -> List[str]:
+ """Compare fixed atom payloads across grouped slide specifications."""
+ errors = []
+ for scope_key, group_specs in groups.items():
+ if len(group_specs) < 2:
+ continue
+ variants = defaultdict(lambda: defaultdict(list))
+ for spec in group_specs:
+ payloads = cls._fixed_layer_payloads(spec, layer)
+ for element_id, payload in payloads.items():
+ variants[element_id][payload].append(spec)
+ for element_id, payload_specs in variants.items():
+ if len(payload_specs) < 2:
+ continue
+ slide_names = ', '.join(
+ spec.svg_path.name
+ for spec in sorted(group_specs, key=lambda item: item.slide_num)
+ )
+ if layer == 'master':
+ scope = f"Master {scope_key!r}"
+ else:
+ master_key, layout_key = scope_key
+ scope = (
+ f"Layout {layout_key!r} under Master {master_key!r}"
+ )
+ if element_id is None:
+ subject = "fixed visual resources"
+ verb = "differ"
+ else:
+ subject = f"fixed element {element_id!r}"
+ verb = "differs"
+ errors.append(
+ f"{scope} {subject} {verb} across slides: "
+ f"{slide_names}. Values marked data-pptx-layer={layer!r} must "
+ "remain identical throughout their reuse scope; move variable "
+ "text or images into a placeholder slot or keep them Slide-local."
+ )
+ return errors
+
+ @staticmethod
+ def _fixed_layer_payloads(spec, layer: str) -> Dict[object, tuple]:
+ """Return resolved fixed-layer visual payloads keyed by SVG id."""
+ elements = (
+ spec.master_elements if layer == 'master' else spec.layout_elements
+ )
+ if not elements:
+ return {}
+ signature = _structure_subtree_signature(
+ spec.svg_path,
+ elements,
+ include_skin=True,
+ include_text=True,
+ asset_identity=True,
+ )
+ return {
+ None if element_id == '__visual_resources__' else element_id: payload
+ for element_id, payload in signature
+ }
+
@staticmethod
def _layout_contract_fingerprint(svg_path: Path):
"""Id-insensitive static contract: layout-layer XML + placeholder slots."""