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(svg-to-pptx): harden structured template contracts

hugohe383b27780c7af
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index a90a81d9..6519a2f8 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -1510,6 +1510,11 @@ several line shapes as one
PowerPoint placeholder prototype/binding. Leave strict-line text Slide-local
when separate frames are the required result.
+**Blank text carrier**: Leave a marked text carrier empty or whitespace-only
+when the placeholder must remain visually blank. Export materializes one
+invisible U+200B run so the carrier still becomes a native PowerPoint text
+shape. Do not insert a dummy dash or hide a visible glyph with background paint.
+
`title` is normally type-matched without an index in reconstructed layouts; if
an imported source title explicitly has one, preserve that exact index. Every
indexed placeholder on one layout uses a unique OOXML UInt32 index. Structured export writes the semantic type on both the Layout and Slide carrier (except `obj`, whose OOXML default is already `obj`) so PowerPoint and `python-pptx` retain the same identity. A composite object slot instead keeps its visible group ordinary and uses a hidden transparent proxy.
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml/converter.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml/converter.py
index 1a969d47..170b1e73 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml/converter.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml/converter.py
@@ -904,6 +904,7 @@ def convert_element(elem: ET.Element, ctx: ConvertContext) -> ShapeResult | None
'data-pptx-geometry-reason',
'data-pptx-placeholder',
'data-pptx-placeholder-bounds',
+ 'data-pptx-placeholder-carrier',
'data-pptx-placeholder-idx',
'data-pptx-role',
):
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml/elements.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml/elements.py
index a6a94801..bba58a7a 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml/elements.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml/elements.py
@@ -2314,12 +2314,22 @@ def convert_text(elem: ET.Element, ctx: ConvertContext) -> ShapeResult | None:
runs = _build_text_runs(elem, parent_attrs)
runs, single_bullet = _extract_text_bullet(runs)
- if not runs:
- return None
-
- full_text = ''.join(r['text'] for r in runs)
+ full_text = ''.join(r['text'] for r in runs) if runs else ''
if not full_text.strip():
- return None
+ is_placeholder_carrier = (
+ (elem.get('data-pptx-placeholder-carrier') or '').strip().lower()
+ == 'true'
+ )
+ if not is_placeholder_carrier:
+ return None
+ # A declared carrier must compile to one native text shape even when its
+ # authored visual is blank. U+200B is invisible but survives DrawingML.
+ runs = [{**parent_attrs, 'text': '\u200b'}]
+ paragraph_runs = None
+ paragraph_space_before = []
+ paragraph_bullets = []
+ visual_line_widths = []
+ single_bullet = None
# Estimate text dimensions
if paragraph_runs is not None:
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 481b86e1..46d021b4 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
@@ -1583,7 +1583,7 @@ def _template_shape_for_item(
text_hint = (
"; multiline text placeholders require the default paragraph merge "
"and cannot use --no-merge"
- if item.placeholder and item.tag == "text"
+ if item.placeholder and item.placeholder_carrier_tag == "text"
else ""
)
raise TemplateStructureError(
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 3bfd33e7..957317c8 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
@@ -100,9 +100,9 @@ _OBJECT_PLACEHOLDER_TAGS = frozenset({
})
_LAYOUT_KEY_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
_MASTER_KEY_RE = _LAYOUT_KEY_RE
-_LOCK_ROW_RE = re.compile(
- r"^-\s+([A-Za-z0-9][A-Za-z0-9._-]*)\s*:\s*(.+?)\s*$"
-)
+# Parse Markdown row syntax before validating each section's key grammar. Keeping
+# those concerns separate prevents malformed keys from disappearing silently.
+_LOCK_ROW_RE = re.compile(r"^-\s+([^:]+?)\s*:\s*(.*?)\s*$")
_LOCK_PAGE_RE = re.compile(r"^P(\d+)$")
PPTX_STRUCTURE_MODES = frozenset({"structured", "preserve", "flat"})
TEMPLATE_ADHERENCE_MODES = frozenset({"strict", "adaptive"})
@@ -538,7 +538,7 @@ def load_pptx_structure_lock(project_path: Path) -> PptxStructureLock | None:
sections: dict[str, list[tuple[str, str]]] = {}
current_section: str | None = None
- for raw_line in lines:
+ for line_number, raw_line in enumerate(lines, start=1):
line = raw_line.strip()
if line.startswith("## "):
current_section = line[3:].strip()
@@ -554,7 +554,15 @@ def load_pptx_structure_lock(project_path: Path) -> PptxStructureLock | None:
continue
match = _LOCK_ROW_RE.fullmatch(line)
if match:
- sections[current_section].append((match.group(1), match.group(2)))
+ sections[current_section].append((
+ match.group(1).strip(),
+ match.group(2).strip(),
+ ))
+ elif re.match(r"^-\s+", line):
+ raise TemplateStructureError(
+ f"spec_lock.md {current_section} line {line_number} must use "
+ "'- <key>: <value>' syntax"
+ )
structure_rows = sections.get("pptx_structure", [])
master_rows = sections.get("pptx_masters", [])
@@ -663,6 +671,7 @@ def load_pptx_structure_lock(project_path: Path) -> PptxStructureLock | None:
if not _MASTER_KEY_RE.fullmatch(master_key):
raise TemplateStructureError(
f"spec_lock.md has invalid Master key {master_key!r}; use 1-64 "
+ "characters, start with an ASCII letter or digit, and use only "
"ASCII letters, digits, dots, underscores, or hyphens"
)
if master_key in seen_master_keys:
@@ -743,6 +752,7 @@ def load_pptx_structure_lock(project_path: Path) -> PptxStructureLock | None:
if not _LAYOUT_KEY_RE.fullmatch(layout_key):
raise TemplateStructureError(
f"spec_lock.md has invalid Layout key {layout_key!r}; use 1-64 "
+ "characters, start with an ASCII letter or digit, and use only "
"ASCII letters, digits, dots, underscores, or hyphens"
)
if layout_key in seen_layout_keys:
@@ -783,7 +793,7 @@ def load_pptx_structure_lock(project_path: Path) -> PptxStructureLock | None:
else:
raise TemplateStructureError(
f"spec_lock.md Layout {layout_key!r} prototype source must be "
- "P<NN> or template:<basename>"
+ f"P<NN> or template:<basename>; found {raw_source!r}"
)
layout_definitions.append(PptxLayoutDefinition(
layout_key=layout_key,
@@ -2361,6 +2371,37 @@ def _prototype_placeholder_contract(
return tuple(item.contract_signature() for item in spec.placeholders)
+def _layout_contract_difference(
+ actual: tuple[TemplateElementSpec, ...],
+ expected: tuple[TemplateElementSpec, ...],
+) -> str:
+ """Describe the smallest actionable difference in a Layout atom roster."""
+ actual_ids = tuple(item.element_id for item in actual)
+ expected_ids = tuple(item.element_id for item in expected)
+ actual_id_set = set(actual_ids)
+ expected_id_set = set(expected_ids)
+ missing = tuple(item for item in expected_ids if item not in actual_id_set)
+ unexpected = tuple(item for item in actual_ids if item not in expected_id_set)
+ details: list[str] = []
+ if missing:
+ details.append(
+ "missing generated Layout element id(s): "
+ + ", ".join(repr(item) for item in missing)
+ )
+ if unexpected:
+ details.append(
+ "unexpected generated Layout element id(s): "
+ + ", ".join(repr(item) for item in unexpected)
+ )
+ if not details and actual_ids != expected_ids:
+ details.append("generated Layout element order differs")
+ if not details:
+ details.append(
+ "shared Layout element metadata, geometry, topology, or content differs"
+ )
+ return "; ".join(details)
+
+
def template_prototype_errors(
specs: list[TemplateSlideSpec],
structure_lock: PptxStructureLock,
@@ -2598,16 +2639,20 @@ def template_prototype_errors(
)
if not layout_contract_same:
qualifier = "mirror visual/structural" if literal_visual else "structural"
+ difference = _layout_contract_difference(
+ spec.layout_elements,
+ prototype.layout_elements,
+ )
if adherence == "strict":
errors.append(
f"{spec.svg_path.name}: strict Layout {qualifier} contract "
- f"differs from prototype {reference.svg_path.name}"
+ f"differs from prototype {reference.svg_path.name}; {difference}"
)
else:
errors.append(
f"{spec.svg_path.name}: adaptive output reused prototype layout "
f"key {prototype.layout_key!r} but changed its {qualifier} "
- "contract; assign a new key and name"
+ f"contract; {difference}; assign a new key and name"
)
return errors
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index bbe6dbbc..e603061a 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -146,7 +146,7 @@
## pptx_masters
- master-default: Default Master
-> Deck/layout template routes only. One row per Master: `<master_key>: <PowerPoint picker name>`. Keys are deck-unique and stable. Omit this entire section when `pptx_structure.mode: flat`.
+> Deck/layout template routes only. One row per Master: `<master_key>: <PowerPoint picker name>`. A key contains 1–64 ASCII letters, digits, dots, underscores, or hyphens; its first character is a letter or digit. Spaces belong only in the PowerPoint picker name, never in the key. Keys are deck-unique and stable. Omit this entire section when `pptx_structure.mode: flat`.
## pptx_layouts
- cover-hero-split: master-default | Cover — Hero Split | template:01_cover
@@ -154,7 +154,7 @@
- content-two-column: master-default | Two Column | template:03a_content_abstract
- quote-focus: master-default | Quote Focus | template:04_quote_focus
-> Deck/layout template routes only. This is the unique reusable Layout roster, not a page roster. Value format: `<master_key> | <PowerPoint layout name> | <prototype source>`. A prototype source is either `P<NN>` for one generated page carrying that exact Layout contract, or `template:<basename>` for an installed `templates/<basename>.svg`. Omit this section when `pptx_structure.mode: flat`.
+> Deck/layout template routes only. This is the unique reusable Layout roster, not a page roster. Layout keys use the same grammar as Master keys. Value format: `<master_key> | <PowerPoint layout name> | <prototype source>`. Supply all three non-empty fields separated by `|`. A prototype source is either `P<NN>` for one generated page carrying that exact Layout contract, or `template:<basename>` for an installed `templates/<basename>.svg`; the `template:` prefix is required, so a bare basename is invalid. Omit this section when `pptx_structure.mode: flat`.
>
> Every Layout key appears exactly once, belongs to exactly one declared Master, and is globally unique even when two Masters use the same picker name. Every declared Master owns at least one Layout definition. A Layout may remain unused by generated pages; such a Layout must use `template:<basename>` so export can register it without manufacturing a published slide.
>