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.pyindex 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_projectelse 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 Nonediff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml/theme_fonts.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml/theme_fonts.pyindex 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: intbody_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.pyindex 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/chartmarkers 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 safeshared 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/placeholdermetadata; ``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_shapesand 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.pyindex 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 = Nonemaster_text_style_spec = Nonetheme_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 1if 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.pyindex 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)