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

feat(template_import): add master/layout reference extraction

hugohe3221c5f3341b9
diff --git a/skills/ppt-master/references/template-designer.md b/skills/ppt-master/references/template-designer.md
index 9bb96416..692acac6 100644
--- a/skills/ppt-master/references/template-designer.md
+++ b/skills/ppt-master/references/template-designer.md
@@ -18,6 +18,8 @@ When the workflow provides a PPTX reference source, the effective input package
- finalized template brief
- `manifest.json`
+- `master_layout_refs.json`
+- `master_layout_analysis.md`
- `analysis.md`
- `normalized_assets.json`
- exported `assets/`
@@ -28,12 +30,14 @@ When the workflow provides a PPTX reference source, the effective input package
Input priority for PPTX-backed template creation:
1. `manifest.json` for factual metadata
-2. `normalized_assets.json` for canonical asset decisions
-3. exported `assets/` for reusable visual resources
-4. `analysis.md` for page-type guidance
-5. `reference_svg_selection.json` for deciding which exported SVG pages to inspect first
-6. cleaned slide SVG references for composition, spacing, and fixed decorative cues
-7. screenshots / original PPTX only for style verification
+2. `master_layout_refs.json` for unique layout/master structure and inheritance
+3. `master_layout_analysis.md` for fast structural review
+4. `normalized_assets.json` for canonical asset decisions
+5. exported `assets/` for reusable visual resources
+6. `analysis.md` for page-type guidance
+7. `reference_svg_selection.json` for deciding which exported SVG pages to inspect first
+8. cleaned slide SVG references for composition, spacing, and fixed decorative cues
+9. screenshots / original PPTX only for style verification
---
diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.md
index 4100f2ec..e406a487 100644
--- a/skills/ppt-master/scripts/docs/project.md
+++ b/skills/ppt-master/scripts/docs/project.md
@@ -92,7 +92,7 @@ Notes:
- Extracts reusable media assets from `ppt/media/`
- Summarizes slide size, theme colors, and font metadata
- Infers background image inheritance across slide, layout, and master
-- Generates `manifest.json`, `analysis.md`, `assets/`, cleaned slide SVGs, and `reference_svg_selection.json`
+- Generates `manifest.json`, `analysis.md`, `master_layout_refs.json`, `master_layout_analysis.md`, `assets/`, cleaned slide SVGs, and `reference_svg_selection.json`
- Native SVG export is Windows-only because it uses installed Microsoft PowerPoint
- On macOS, the script falls back to exporting PDF via Keynote and then converts PDF pages to SVG
- Writes cleaned SVG files to `svg/` after externalizing inline Base64 image payloads
diff --git a/skills/ppt-master/scripts/template_import/manifest.py b/skills/ppt-master/scripts/template_import/manifest.py
index 76fe9348..1df5eced 100644
--- a/skills/ppt-master/scripts/template_import/manifest.py
+++ b/skills/ppt-master/scripts/template_import/manifest.py
@@ -61,6 +61,35 @@ class SlideRecord:
page_type: str
+def summarize_part_record(
+ *,
+ part_path: str | None,
+ root: ET.Element | None,
+ rels: dict[str, dict[str, str]],
+ copied_assets: dict[str, str],
+ used_by_slides: list[int],
+ parent_path: str | None = None,
+ theme_path: str | None = None,
+) -> dict[str, Any] | None:
+ if not part_path:
+ return None
+
+ bg_asset = detect_background_asset(root, rels)
+ image_targets = extract_image_targets(root, rels)
+ return {
+ "path": part_path,
+ "name": PurePosixPath(part_path).name,
+ "parentPath": parent_path,
+ "themePath": theme_path,
+ "backgroundAsset": copied_assets.get(bg_asset, PurePosixPath(bg_asset).name if bg_asset else None),
+ "imageAssets": [copied_assets.get(target, PurePosixPath(target).name) for target in image_targets],
+ "textSamples": extract_text_samples(root),
+ "textCount": len(root.findall(".//a:t", NS)) if root is not None else 0,
+ "shapeCount": count_slide_shapes(root),
+ "usedBySlides": used_by_slides,
+ }
+
+
def normalize_part(path: str, base: str | None = None) -> str:
if base:
path = str(PurePosixPath(base).parent.joinpath(path))
@@ -278,6 +307,59 @@ def write_analysis(
output_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+def write_structure_analysis(
+ output_path: Path,
+ structures: dict[str, Any],
+) -> None:
+ layouts = structures.get("layouts", [])
+ masters = structures.get("masters", [])
+
+ lines = [
+ "# Master/Layout Reference Analysis",
+ "",
+ "## Summary",
+ f"- Unique layouts: {len(layouts)}",
+ f"- Unique masters: {len(masters)}",
+ "",
+ "## Layouts",
+ ]
+
+ if not layouts:
+ lines.append("- (none)")
+ for layout in layouts:
+ sample = " | ".join(layout.get("textSamples", [])[:3]) or "(no text sample)"
+ lines.extend(
+ [
+ f"- {layout['name']}",
+ f" - Path: {layout['path']}",
+ f" - Parent master: {layout.get('parentPath') or 'n/a'}",
+ f" - Used by slides: {', '.join(str(i) for i in layout.get('usedBySlides', [])) or 'n/a'}",
+ f" - Background asset: {layout.get('backgroundAsset') or 'none'}",
+ f" - Image assets: {', '.join(layout.get('imageAssets', [])) or 'none'}",
+ f" - Text sample: {sample}",
+ ]
+ )
+
+ lines.extend(["", "## Masters"])
+ if not masters:
+ lines.append("- (none)")
+ for master in masters:
+ sample = " | ".join(master.get("textSamples", [])[:3]) or "(no text sample)"
+ lines.extend(
+ [
+ f"- {master['name']}",
+ f" - Path: {master['path']}",
+ f" - Theme path: {master.get('themePath') or 'n/a'}",
+ f" - Used by slides: {', '.join(str(i) for i in master.get('usedBySlides', [])) or 'n/a'}",
+ f" - Background asset: {master.get('backgroundAsset') or 'none'}",
+ f" - Image assets: {', '.join(master.get('imageAssets', [])) or 'none'}",
+ f" - Text sample: {sample}",
+ ]
+ )
+
+ output_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
def build_manifest(pptx_path: Path, output_dir: Path) -> dict[str, Any]:
with zipfile.ZipFile(pptx_path, "r") as zf:
presentation_root = load_xml_from_zip(zf, "ppt/presentation.xml")
@@ -305,6 +387,8 @@ def build_manifest(pptx_path: Path, output_dir: Path) -> dict[str, Any]:
slide_parts.append(rel["target"])
asset_dir = output_dir / "assets"
+ if asset_dir.exists():
+ shutil.rmtree(asset_dir)
asset_dir.mkdir(parents=True, exist_ok=True)
copied_assets: dict[str, str] = {}
@@ -326,6 +410,10 @@ def build_manifest(pptx_path: Path, output_dir: Path) -> dict[str, Any]:
slide_records: list[SlideRecord] = []
asset_usage: Counter[str] = Counter()
+ layout_usage: defaultdict[str, list[int]] = defaultdict(list)
+ master_usage: defaultdict[str, list[int]] = defaultdict(list)
+ layout_cache: dict[str, dict[str, Any]] = {}
+ master_cache: dict[str, dict[str, Any]] = {}
theme_summary = {"colors": {}, "fonts": {}}
@@ -388,6 +476,23 @@ def build_manifest(pptx_path: Path, output_dir: Path) -> dict[str, Any]:
for asset_name in resolved_images:
asset_usage[asset_name] += 1
+ if layout_path:
+ layout_usage[layout_path].append(index)
+ if layout_path not in layout_cache:
+ layout_cache[layout_path] = {
+ "root": layout_root,
+ "rels": layout_rels,
+ "master_path": master_path,
+ }
+ if master_path:
+ master_usage[master_path].append(index)
+ if master_path not in master_cache:
+ master_cache[master_path] = {
+ "root": master_root,
+ "rels": master_rels,
+ "theme_path": theme_path,
+ }
+
slide_records.append(
SlideRecord(
index=index,
@@ -410,6 +515,33 @@ def build_manifest(pptx_path: Path, output_dir: Path) -> dict[str, Any]:
for slide in slide_records:
page_type_map[slide.page_type].append(slide.index)
+ layout_records = [
+ summarize_part_record(
+ part_path=layout_path,
+ root=layout_cache[layout_path]["root"],
+ rels=layout_cache[layout_path]["rels"],
+ copied_assets=copied_assets,
+ used_by_slides=layout_usage[layout_path],
+ parent_path=layout_cache[layout_path]["master_path"],
+ )
+ for layout_path in sorted(layout_cache.keys())
+ ]
+ master_records = [
+ summarize_part_record(
+ part_path=master_path,
+ root=master_cache[master_path]["root"],
+ rels=master_cache[master_path]["rels"],
+ copied_assets=copied_assets,
+ used_by_slides=master_usage[master_path],
+ theme_path=master_cache[master_path]["theme_path"],
+ )
+ for master_path in sorted(master_cache.keys())
+ ]
+ structure_refs = {
+ "layouts": [item for item in layout_records if item],
+ "masters": [item for item in master_records if item],
+ }
+
manifest = {
"source": {
"pptx": str(pptx_path),
@@ -422,6 +554,12 @@ def build_manifest(pptx_path: Path, output_dir: Path) -> dict[str, Any]:
"commonAssets": common_assets,
"allAssets": sorted(copied_assets.values()),
},
+ "referenceStructures": {
+ "json": "master_layout_refs.json",
+ "analysis": "master_layout_analysis.md",
+ "layoutCount": len(structure_refs["layouts"]),
+ "masterCount": len(structure_refs["masters"]),
+ },
"pageTypeCandidates": dict(sorted(page_type_map.items())),
"slides": [
{
@@ -450,6 +588,11 @@ def build_manifest(pptx_path: Path, output_dir: Path) -> dict[str, Any]:
slide_records,
common_assets,
)
+ (output_dir / "master_layout_refs.json").write_text(
+ json.dumps(structure_refs, ensure_ascii=False, indent=2) + "\n",
+ encoding="utf-8",
+ )
+ write_structure_analysis(output_dir / "master_layout_analysis.md", structure_refs)
return manifest
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index 7bea3f31..a2a89cc1 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -60,13 +60,15 @@ This helper performs the full PPTX reference preparation in one workspace:
- extracts reusable assets and style metadata
- generates `manifest.json`
- generates `analysis.md`
+- generates `master_layout_refs.json`
+- generates `master_layout_analysis.md`
- exports each slide to `svg/`
- externalizes large inline bitmap payloads into `assets/`
- generates `reference_svg_selection.json`
It is still a reconstruction aid, not a final direct template conversion.
-Use the generated `manifest.json`, `analysis.md`, exported `assets/`, and `svg/` slide references as internal reference material for template reconstruction.
+Use the generated `manifest.json`, `analysis.md`, `master_layout_refs.json`, `master_layout_analysis.md`, exported `assets/`, and `svg/` slide references as internal reference material for template reconstruction.
Then perform an **AI-only asset normalization step** before template generation:
@@ -86,15 +88,19 @@ Recommended fields in `normalized_assets.json`:
When the reference source is `.pptx`, use the following internal priority order during template creation:
1. `manifest.json`
-2. `analysis.md`
-3. `normalized_assets.json`
-4. exported `assets/`
-5. cleaned slide SVG references from `svg/`
-6. user-provided screenshots or the original PPTX only for visual cross-checking
+2. `master_layout_refs.json`
+3. `master_layout_analysis.md`
+4. `analysis.md`
+5. `normalized_assets.json`
+6. exported `assets/`
+7. cleaned slide SVG references from `svg/`
+8. user-provided screenshots or the original PPTX only for visual cross-checking
Interpretation rule:
- `manifest.json` is the source of truth for slide size, theme colors, fonts, background inheritance, and reusable asset inventory
+- `master_layout_refs.json` is the source of truth for unique layout/master structure, inherited backgrounds, and slide reuse relationships
+- `master_layout_analysis.md` is the compact human-readable summary for quickly understanding reusable master/layout motifs
- `analysis.md` is the compact human-readable summary used to guide page-type selection
- `normalized_assets.json` is the source of truth for which imported assets are canonical and which `inline_*` assets are only derived helpers
- exported `assets/` remain the raw import pool and should not be consumed blindly once normalization exists
@@ -146,6 +152,8 @@ If the reference source is `.pptx`, pass the following internal package to the r
- finalized template brief from Step 1
- `manifest.json`
+- `master_layout_refs.json`
+- `master_layout_analysis.md`
- `analysis.md`
- `normalized_assets.json`
- exported `assets/`