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(free-design): build deck-owned flat PowerPoint shells

hugohe3dd972d625ab6
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.py
index d0908f8f..095d8827 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -190,6 +190,23 @@ except ImportError:
_template_prototype_errors = None
_validate_template_structure_svg = None
+try:
+ from svg_to_pptx.drawingml.theme_colors import (
+ ThemeColorError as _ThemeColorError,
+ load_theme_color_spec as _load_theme_color_spec,
+ )
+ from svg_to_pptx.drawingml.theme_fonts import (
+ ThemeFontError as _ThemeFontError,
+ load_master_text_style_spec as _load_master_text_style_spec,
+ load_theme_font_spec as _load_theme_font_spec,
+ )
+except ImportError:
+ _ThemeColorError = None
+ _ThemeFontError = None
+ _load_theme_color_spec = None
+ _load_master_text_style_spec = None
+ _load_theme_font_spec = None
+
try:
from svg_finalize.embed_icons import (
resolve_icon_path as _resolve_icon_path,
@@ -310,6 +327,39 @@ def _declared_pptx_structure_mode(project_path: Path) -> str | None:
return mode_match.group(1).strip().lower() if mode_match else None
+def _generated_theme_contract_errors(project_path: Path) -> List[str]:
+ """Validate the current-project theme contract required by release export."""
+ if (
+ _ThemeColorError is None
+ or _ThemeFontError is None
+ or _load_theme_color_spec is None
+ or _load_master_text_style_spec is None
+ or _load_theme_font_spec is None
+ ):
+ return [
+ "PowerPoint theme contract validation is unavailable because the "
+ "theme loader modules could not be imported."
+ ]
+ try:
+ theme_font_spec = _load_theme_font_spec(project_path)
+ _load_master_text_style_spec(project_path)
+ theme_color_spec = _load_theme_color_spec(project_path)
+ except (_ThemeFontError, _ThemeColorError) as exc:
+ return [str(exc)]
+
+ missing: List[str] = []
+ if theme_font_spec is None:
+ missing.append("typography font_family/title_family/body_family")
+ if theme_color_spec is None:
+ missing.append("colors")
+ if not missing:
+ return []
+ return [
+ "spec_lock.md generated PowerPoint theme contract is missing: "
+ + ", ".join(missing)
+ ]
+
+
def _placeholder_bounds_error(value: str) -> str | None:
"""Return a concise error for invalid design-zone bounds."""
raw_values = [item for item in re.split(r"[\s,]+", value.strip()) if item]
@@ -2608,6 +2658,11 @@ class SVGQualityChecker:
if standard_project
else None
)
+ if standard_project and declared_mode in {'flat', 'structured'}:
+ self._pptx_structure_issues.extend(
+ ('error', message)
+ for message in _generated_theme_contract_errors(project_path)
+ )
if standard_project and declared_mode == 'flat':
if (
_load_pptx_structure_lock is None
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml/theme_fonts.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml/theme_fonts.py
index 6ec97880..3a7815a7 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml/theme_fonts.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml/theme_fonts.py
@@ -48,7 +48,7 @@ class ThemeFontSpec:
@dataclass(frozen=True)
class MasterTextStyleSpec:
- """Title/body defaults written to a template slide master's txStyles."""
+ """Title/body defaults written to one generated slide master's txStyles."""
title_hpt: int
body_hpt: int
@@ -125,17 +125,17 @@ def _font_size_hpt(raw: str, field: str) -> int:
def load_master_text_style_spec(project_path: Path) -> MasterTextStyleSpec:
- """Load required title/body defaults for explicit Layout master txStyles."""
+ """Load required title/body defaults for generated Master text styles."""
lock_path = project_path / "spec_lock.md"
if not lock_path.is_file():
raise ThemeFontError(
- "explicit Layout export requires spec_lock.md typography title and body rows"
+ "Master export requires spec_lock.md typography title and body rows"
)
rows = _typography_rows(lock_path)
missing = [field for field in ("title", "body") if field not in rows]
if missing:
raise ThemeFontError(
- "explicit Layout export requires spec_lock.md typography rows: "
+ "Master export requires spec_lock.md typography rows: "
+ ", ".join(missing)
)
return MasterTextStyleSpec(
@@ -217,7 +217,7 @@ def apply_master_text_style_spec(
extract_dir: Path,
spec: MasterTextStyleSpec,
) -> int:
- """Install locked title/body sizes into template slide-master txStyles."""
+ """Install locked title/body sizes into generated slide-master txStyles."""
master_dir = extract_dir / "ppt" / "slideMasters"
master_paths = sorted(master_dir.glob("slideMaster*.xml"))
if not master_paths:
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 62dbabe2..0087a01b 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
@@ -399,6 +399,7 @@ _TOP_LEVEL_SHAPE_TAGS = {
f"{{{PML_NS}}}cxnSp",
f"{{{PML_NS}}}graphicFrame",
}
+_FLAT_SYSTEM_PLACEHOLDER_TYPES = frozenset({"dt", "ftr", "sldNum"})
_REL_ATTRS = {
f"{{{REL_NS}}}embed",
f"{{{REL_NS}}}link",
@@ -3083,6 +3084,201 @@ def _prune_unused_slide_layouts(
return pruned
+def _flat_structure_name(value: str | None) -> str:
+ """Return one compact package identity for a free-design deck."""
+ normalized = " ".join((value or "").split()).strip()
+ return (normalized or "Free Design")[:120]
+
+
+def _flat_placeholder_type(shape: ET.Element) -> str | None:
+ """Return one system placeholder type carried by a top-level shape."""
+ if shape.tag != f"{{{PML_NS}}}sp":
+ return None
+ placeholder = shape.find(
+ f"{{{PML_NS}}}nvSpPr/{{{PML_NS}}}nvPr/{{{PML_NS}}}ph"
+ )
+ return placeholder.get("type") if placeholder is not None else None
+
+
+def _clean_flat_structure_part(
+ part_path: Path,
+ name: str,
+ *,
+ is_layout: bool,
+) -> tuple[int, tuple[str, ...]]:
+ """Keep only standard footer hooks in one project-owned flat shell."""
+ try:
+ tree = ET.parse(part_path)
+ except (OSError, ET.ParseError) as exc:
+ raise RuntimeError(
+ f"Cannot parse flat structure part {part_path}: {exc}"
+ ) from exc
+ root = tree.getroot()
+ common_slide = root.find(f"{{{PML_NS}}}cSld")
+ if common_slide is None:
+ raise RuntimeError(f"Flat structure part has no p:cSld: {part_path}")
+ shape_tree = common_slide.find(f"{{{PML_NS}}}spTree")
+ if shape_tree is None:
+ raise RuntimeError(f"Flat structure part has no p:spTree: {part_path}")
+
+ removed = 0
+ retained: list[str] = []
+ for child in list(shape_tree):
+ if child.tag not in _TOP_LEVEL_SHAPE_TAGS:
+ continue
+ placeholder_type = _flat_placeholder_type(child)
+ if placeholder_type in _FLAT_SYSTEM_PLACEHOLDER_TYPES:
+ retained.append(placeholder_type)
+ continue
+ shape_tree.remove(child)
+ removed += 1
+ for parent in (common_slide, root):
+ for extension_list in parent.findall(f"{{{PML_NS}}}extLst"):
+ parent.remove(extension_list)
+
+ common_slide.set("name", name)
+ if is_layout:
+ root.set("type", "blank")
+ root.set("preserve", "1")
+ _write_xml_tree(part_path, tree)
+ return removed, tuple(retained)
+
+
+def _name_flat_themes(extract_dir: Path, name: str) -> int:
+ """Replace stock Office theme identities with the current deck identity."""
+ theme_paths = sorted((extract_dir / "ppt" / "theme").glob("theme*.xml"))
+ if not theme_paths:
+ raise RuntimeError("Flat PPTX package has no theme part")
+ for theme_path in theme_paths:
+ try:
+ tree = ET.parse(theme_path)
+ except (OSError, ET.ParseError) as exc:
+ raise RuntimeError(
+ f"Cannot parse flat theme {theme_path}: {exc}"
+ ) from exc
+ root = tree.getroot()
+ root.set("name", name)
+ for tag in ("clrScheme", "fontScheme", "fmtScheme"):
+ scheme = root.find(f".//{{{DML_NS}}}{tag}")
+ if scheme is not None:
+ scheme.set("name", name)
+ _write_xml_tree(theme_path, tree)
+ return len(theme_paths)
+
+
+def _prepare_flat_structure(
+ extract_dir: Path,
+ structure: PptxStructureContext,
+ slide_count: int,
+ master_text_style_spec: MasterTextStyleSpec | None,
+ structure_name: str | None,
+ *,
+ verbose: bool = False,
+) -> None:
+ """Materialize one clean current-deck Master and Blank Layout for flat export."""
+ pruned = _prune_unused_slide_layouts(
+ extract_dir,
+ structure,
+ slide_count,
+ verbose=False,
+ )
+ live_structure = _read_slide_layout_targets(extract_dir, slide_count)
+ layout_parts = {
+ _resolve_package_target(
+ f"ppt/slides/slide{slide_num}.xml",
+ live_structure.slide_layout_target(slide_num),
+ )
+ for slide_num in range(1, slide_count + 1)
+ }
+ master_parts = set(live_structure.slide_master_parts.values())
+ physical_layouts = {
+ str(path.relative_to(extract_dir)).replace("\\", "/")
+ for path in (extract_dir / "ppt" / "slideLayouts").glob("slideLayout*.xml")
+ }
+ physical_masters = {
+ str(path.relative_to(extract_dir)).replace("\\", "/")
+ for path in (extract_dir / "ppt" / "slideMasters").glob("slideMaster*.xml")
+ }
+ if len(layout_parts) != 1 or layout_parts != physical_layouts:
+ raise RuntimeError(
+ "Flat export must retain exactly one slide-referenced Blank Layout"
+ )
+ if len(master_parts) != 1 or master_parts != physical_masters:
+ raise RuntimeError(
+ "Flat export must retain exactly one slide-referenced Master"
+ )
+
+ identity = _flat_structure_name(structure_name)
+ theme_name = identity
+ master_name = f"{identity} — Master"
+ layout_name = f"{identity} — Blank"
+ master_path = extract_dir / next(iter(master_parts))
+ layout_path = extract_dir / next(iter(layout_parts))
+ removed_master_shapes, retained_master_placeholders = _clean_flat_structure_part(
+ master_path,
+ master_name,
+ is_layout=False,
+ )
+ removed_layout_shapes, retained_layout_placeholders = _clean_flat_structure_part(
+ layout_path,
+ layout_name,
+ is_layout=True,
+ )
+ theme_count = _name_flat_themes(extract_dir, theme_name)
+ master_count = (
+ apply_master_text_style_spec(extract_dir, master_text_style_spec)
+ if master_text_style_spec is not None
+ else 0
+ )
+
+ for part_path, expected_name, expected_layout in (
+ (master_path, master_name, False),
+ (layout_path, layout_name, True),
+ ):
+ root = ET.parse(part_path).getroot()
+ common_slide = root.find(f"{{{PML_NS}}}cSld")
+ if common_slide is None or common_slide.get("name") != expected_name:
+ raise RuntimeError(
+ f"Flat structure identity read-back failed: {part_path}"
+ )
+ shape_tree = common_slide.find(f"{{{PML_NS}}}spTree")
+ if shape_tree is None:
+ raise RuntimeError(f"Flat structure shell has no shape tree: {part_path}")
+ actual_placeholder_types = tuple(
+ sorted(
+ _flat_placeholder_type(child) or ""
+ for child in shape_tree
+ if child.tag in _TOP_LEVEL_SHAPE_TAGS
+ )
+ )
+ expected_placeholder_types = tuple(
+ sorted(_FLAT_SYSTEM_PLACEHOLDER_TYPES)
+ )
+ if actual_placeholder_types != expected_placeholder_types:
+ raise RuntimeError(
+ "Flat structure shell must retain only one each of the date, "
+ f"footer, and slide-number hooks: {part_path}"
+ )
+ if expected_layout and root.get("type") != "blank":
+ raise RuntimeError(f"Flat layout is not typed as Blank: {part_path}")
+
+ if verbose:
+ print(
+ " Flat structure: project-owned Master + Blank Layout "
+ f"({pruned} stock layout(s), "
+ f"{removed_master_shapes + removed_layout_shapes} stock content "
+ "shape(s) removed, "
+ f"{len(retained_master_placeholders) + len(retained_layout_placeholders)} "
+ "system footer hook(s) retained)"
+ )
+ text_style_status = (
+ f"{master_count} master text style(s)"
+ if master_text_style_spec is not None
+ else "stock text defaults retained (diagnostic caller)"
+ )
+ print(f" Flat theme: {theme_count} theme part(s), {text_style_status}")
+
+
def _append_relationship(
rels_path: Path,
rel_type: str,
@@ -3874,6 +4070,7 @@ def create_pptx_with_native_svg(
native_objects: bool = False,
conversion_trace_path: Path | None = None,
doc_metadata: dict[str, Any] | None = None,
+ structure_name: str | None = None,
pptx_structure: str = "structured",
native_structure_contract: NativeStructureContract | None = None,
theme_font_spec: ThemeFontSpec | None = None,
@@ -3917,6 +4114,8 @@ def create_pptx_with_native_svg(
native_objects: Convert explicit ``data-pptx-native`` table/chart
markers to native PowerPoint objects. Default off.
conversion_trace_path: Optional JSON path for native conversion diagnostics.
+ structure_name: Current deck identity used to name a flat Master, Layout,
+ and theme.
pptx_structure: PPTX structure strategy. ``baseline`` promotes safe
shared native backgrounds and leading chrome to slide masters,
then extracts semantic page-role layout families and exact
@@ -3924,17 +4123,17 @@ def create_pptx_with_native_svg(
SVGs retain filename/id fallback;
``structured`` consumes explicit SVG master/layout/placeholder
metadata; ``preserve`` reuses an imported source PPTX package;
- ``flat`` keeps generated structure slide-local.
+ ``flat`` keeps generated content Slide-local and builds one clean
+ project-owned Master/Blank-Layout shell.
native_structure_contract: Validated source package contract for
``preserve`` mode.
- theme_font_spec: Locked project major/minor fonts for baseline/structured
- theme inheritance. Preserve and flat modes ignore this value.
+ theme_font_spec: Locked project major/minor fonts for flat/structured
+ release-theme inheritance. Direct diagnostic flat callers may omit it.
master_text_style_spec: Required locked title/body sizes for structured
- slide-master text styles. Other structure
- routes ignore this value.
+ and release flat slide-master text styles. Direct diagnostic flat
+ callers may omit it; other routes ignore this value.
theme_color_spec: Locked project color scheme for context-aware
- baseline/structured theme inheritance. Preserve and flat modes
- ignore this value.
+ flat/structured theme inheritance. Preserve mode ignores this value.
structured_baseline: Obsolete compatibility argument; must remain false.
baseline_layout_specs: Obsolete compatibility argument; must remain None.
@@ -4105,14 +4304,16 @@ def create_pptx_with_native_svg(
_clear_preserved_slide_collections(extract_dir)
active_theme_font_spec = (
theme_font_spec
- if use_native_shapes and pptx_structure in {"baseline", "structured"}
+ if use_native_shapes
+ and pptx_structure in {"baseline", "flat", "structured"}
else None
)
if active_theme_font_spec is not None:
apply_theme_font_spec(extract_dir, active_theme_font_spec)
active_theme_color_spec = (
theme_color_spec
- if use_native_shapes and pptx_structure in {"baseline", "structured"}
+ if use_native_shapes
+ and pptx_structure in {"baseline", "flat", "structured"}
else None
)
if active_theme_color_spec is not None:
@@ -4634,6 +4835,20 @@ def create_pptx_with_native_svg(
verbose=verbose,
)
+ if (
+ use_native_shapes
+ and pptx_structure == "flat"
+ and success_count == len(svg_files)
+ ):
+ _prepare_flat_structure(
+ extract_dir,
+ structure,
+ len(svg_files),
+ master_text_style_spec,
+ structure_name,
+ verbose=verbose,
+ )
+
if (
use_native_shapes
and pptx_structure == "structured"
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 a27aa21b..82f893df 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
@@ -324,10 +324,10 @@ Recorded narration:
help=(
'PPTX structure strategy for native export. Omitting this flag reads '
'spec_lock.md: flat is the free-design/brand-only release mode and '
- 'uses the default PowerPoint Master plus Blank Layout with all SVG '
- 'objects slide-local; structured is the deck/layout-template mode and '
- 'requires complete explicit metadata. baseline, template, preserve, '
- 'and generated are accepted only to report a migration error.'
+ 'builds one clean project-owned Master plus Blank Layout while keeping '
+ 'all SVG objects slide-local; structured is the deck/layout-template '
+ 'mode and requires complete explicit metadata. baseline, template, '
+ 'preserve, and generated are accepted only to report a migration error.'
),
)
parser.add_argument('--no-image-optimize', action='store_true',
@@ -449,7 +449,7 @@ Recorded narration:
theme_font_spec = None
master_text_style_spec = None
theme_color_spec = None
- if pptx_structure == 'structured':
+ if pptx_structure in {'flat', 'structured'}:
try:
theme_font_spec = load_theme_font_spec(project_path)
master_text_style_spec = load_master_text_style_spec(project_path)
@@ -457,6 +457,21 @@ Recorded narration:
except (ThemeFontError, ThemeColorError) as exc:
print(f"Error: {exc}", file=sys.stderr)
return 1
+ missing_theme_fields = []
+ if theme_font_spec is None:
+ missing_theme_fields.append(
+ 'typography font_family/title_family/body_family'
+ )
+ if theme_color_spec is None:
+ missing_theme_fields.append('colors')
+ if missing_theme_fields:
+ print(
+ f"Error: {pptx_structure} export requires a current-project "
+ "theme contract in spec_lock.md; missing: "
+ + ", ".join(missing_theme_fields),
+ file=sys.stderr,
+ )
+ return 1
if args.image_max_dimension < 1:
print("Error: --image-max-dimension must be >= 1", file=sys.stderr)
return 1
@@ -852,9 +867,16 @@ Recorded narration:
else:
print(" [warn] metadata.json ignored (top level is not an object)", file=sys.stderr)
+ structure_name = project_name
+ if isinstance(doc_metadata, dict):
+ metadata_title = doc_metadata.get('title')
+ if isinstance(metadata_title, str) and metadata_title.strip():
+ structure_name = metadata_title
+
shared_kwargs = dict(
canvas_format=canvas_format,
doc_metadata=doc_metadata,
+ structure_name=structure_name,
verbose=verbose,
transition=transition,
transition_duration=transition_duration,
diff --git a/skills/ppt-master/scripts/template_preview_pptx.py b/skills/ppt-master/scripts/template_preview_pptx.py
index 0c984de0..4035fbd5 100644
--- a/skills/ppt-master/scripts/template_preview_pptx.py
+++ b/skills/ppt-master/scripts/template_preview_pptx.py
@@ -241,6 +241,7 @@ def main(argv: list[str] | None = None) -> int:
native_objects=True,
pptx_structure="flat" if args.visual_only else "structured",
master_text_style_spec=text_style,
+ structure_name=template_id,
)
if not success or not output_path.is_file():
print("Error: template preview export did not produce a PPTX", file=sys.stderr)