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

refactor(create-template): de-duplicate import workspace, layered SVG export, single-source index

hugohe31ddd408082bf
diff --git a/skills/ppt-master/references/template-designer.md b/skills/ppt-master/references/template-designer.md
index 95310e24..b8e47d9f 100644
--- a/skills/ppt-master/references/template-designer.md
+++ b/skills/ppt-master/references/template-designer.md
@@ -17,22 +17,22 @@ Generate reusable page templates for the **global template library** based on a
When the workflow provides a PPTX reference source, the effective input package comes from the unified `pptx_template_import.py` preparation workspace and becomes:
- finalized template brief
-- `manifest.json`
-- `master_layout_refs.json`
-- `master_layout_analysis.md`
-- `analysis.md`
+- `manifest.json` — single source of truth (slide size, theme, assets, layouts, masters, slides, page-type candidates)
+- `summary.md` — short orientation digest derived from manifest.json
- exported `assets/`
-- cleaned slide SVG references from `svg/`
+- `svg/master_*.svg` / `svg/layout_*.svg` — each unique master / layout rendered once as standalone SVG (decorative + structural shapes only, no placeholders, no inlining of parent shapes)
+- `svg/slide_NN.svg` — each slide's own shapes only; master / layout decoration is **not** inlined
+- `svg/inheritance.json` — which layout / master each slide consumes
- optional screenshots for visual cross-checking
Input priority for PPTX-backed template creation:
-1. `manifest.json` for factual metadata
-2. `master_layout_refs.json` for unique layout/master structure and inheritance
-3. `master_layout_analysis.md` for fast structural review
-4. `analysis.md` for page-type guidance
-5. exported `assets/` for reusable visual resources
-6. cleaned slide SVG references for composition, spacing, and fixed decorative cues
+1. `manifest.json` for all factual metadata (theme, assets, unique layout/master structure, slide reuse, page-type guidance)
+2. `svg/master_*.svg` + `svg/layout_*.svg` — the **primary source for the deck's shared visual language**: backgrounds, page chrome, decorative bars, recurring brand motifs. These are what the new template's fixed structure should adopt or reinterpret. Read these before any slide SVG.
+3. `svg/inheritance.json` for confirming which slide uses which layout / master
+4. exported `assets/` for reusable visual resources
+5. `svg/slide_NN.svg` — each slide's unique content, useful for judging composition rhythm and content density (not for fixed structure)
+6. `summary.md` only as a fast scan; never as the canonical fact source
7. screenshots / original PPTX only for style verification
---
@@ -79,9 +79,9 @@ Extension page types beyond the canonical four (transition / appendix / disclaim
- Cluster slides from `manifest.json` by `pageType` + visual structure (column count, hero-image vs. icon-grid vs. quote, etc.)
- One SVG per cluster — do **not** emit a variant for a cluster represented by a single source slide unless that slide is structurally distinct from existing variants
- Cap at 8 content variants per template; collapse near-duplicates into the closest existing variant
-- Record every emitted page in `design_spec.md §VI` and in the `pages` field of the `layouts_index.json` entry
+- Record every emitted page in `design_spec.md §VI` and in the `pages` field of the `layouts_index.json` entry (auto-collected by `register_template.py`)
-**Placeholder contract for variants**: variants reuse the parent type's placeholder set (every `03*_content*.svg` shares the content placeholder set). Do **not** introduce variant-specific placeholder families.
+> Variants reuse the parent type's placeholder set — see §4 (Placeholder Reference) below.
---
@@ -117,11 +117,11 @@ Templates must strictly follow the finalized template brief and the generated `d
If PPTX import output exists:
- Prefer imported theme colors and fonts over visually guessed values
- Reuse exported `assets/` images directly — `<image>` references in `svg/` already point at canonical files
-- Treat page-type candidates from `analysis.md` as hints, not guarantees
+- Treat page-type candidates from `manifest.pageTypeCandidates` as hints, not guarantees
**Precondition**:
-- When PPTX import output is provided, do not generate any template SVG or `design_spec.md` until every file under `<import_workspace>/svg/` has been read
+- When PPTX import output is provided, do not generate any template SVG or `design_spec.md` until every file under `<import_workspace>/svg/` has been read — including `master_*.svg`, `layout_*.svg`, and every `slide_*.svg`
- Before template generation begins, explicitly report the read slide indexes
### 2.1 PPTX Import Simplification Rule
@@ -134,7 +134,7 @@ Do:
- simplify repeated decorative fragments into a smaller number of maintainable SVG elements
- use a background image asset when the original decorative layer is too complex to recreate cleanly
- use cleaned slide SVG references to inspect composition, spacing, text hierarchy, and fixed decorative structure only after factual metadata has been anchored
-- read every cleaned SVG reference page under `svg/`, regardless of slide count — partial coverage drops template fidelity
+- read every reference SVG under `svg/` — `master_*.svg`, `layout_*.svg`, and every `slide_*.svg` regardless of slide count. Master / layout files describe the deck's shared visual language (read first); slide files describe per-page content (read after). Partial coverage drops template fidelity.
- rename adopted assets to semantic names (`cover_bg.png`, `brand_emblem.png`) rather than carrying raw `image3.png` into the final template
Do not:
@@ -159,28 +159,39 @@ Use clear placeholder markers for replaceable content:
</text>
```
-### 4. Placeholder Reference
-
-| Placeholder | Purpose | Applicable Template |
-|------------|---------|-------------------|
-| `{{TITLE}}` | Main title | Cover |
-| `{{SUBTITLE}}` | Subtitle | Cover |
-| `{{DATE}}` | Date | Cover |
-| `{{AUTHOR}}` | Author / Organization | Cover |
-| `{{CHAPTER_NUM}}` | Chapter number | Chapter page |
-| `{{CHAPTER_TITLE}}` | Chapter title | Chapter page |
-| `{{CHAPTER_DESC}}` | Chapter description | Chapter page |
-| `{{PAGE_TITLE}}` | Page title | Content page |
-| `{{KEY_MESSAGE}}` | Key takeaway | Content page (consulting style) |
-| `{{CONTENT_AREA}}` | Content area | Content page |
-| `{{SECTION_NAME}}` | Section name | Content page footer |
-| `{{SOURCE}}` | Data source | Content page footer |
-| `{{PAGE_NUM}}` | Page number | Content page, ending page |
-| `{{THANK_YOU}}` | Thank-you message | Ending page |
-| `{{ENDING_SUBTITLE}}` | Ending subtitle | Ending page |
-| `{{CLOSING_MESSAGE}}` | Closing message | Ending page |
-| `{{CONTACT_INFO}}` | Contact info | Ending page |
-| `{{COPYRIGHT}}` | Copyright | Ending page |
+### 4. Placeholder Reference (canonical convention, overridable per template)
+
+This is the **default vocabulary** used across the library. Newly created templates SHOULD prefer these names so projects that consume the library find familiar slots; designers MAY substitute or extend them when a style genuinely needs different vocabulary (e.g. consulting decks lead with `{{KEY_MESSAGE}}` instead of `{{PAGE_TITLE}}`; a brand cover may need `{{BRAND_LOGO}}`).
+
+`svg_quality_checker.py --template-mode` emits **advisory warnings** when a page lacks the conventional placeholder for its type. To silence those warnings — and document the template's actual contract — declare a `placeholders:` map in `design_spec.md` frontmatter:
+
+```yaml
+placeholders:
+ 01_cover: ["{{TITLE}}", "{{SUBTITLE}}", "{{BRAND_LOGO}}"]
+ 03_content: ["{{KEY_MESSAGE}}", "{{CONTENT_AREA}}"]
+ 03a_content_dual_col: [] # explicitly assert "no required placeholders"
+```
+
+| Placeholder | Purpose | Applicable page | Convention role |
+|------------|---------|-------------------|--------|
+| `{{TITLE}}` | Main title | Cover | Default |
+| `{{SUBTITLE}}` | Subtitle | Cover | Default |
+| `{{DATE}}` | Date | Cover | Default |
+| `{{AUTHOR}}` | Author / Organization | Cover | Default |
+| `{{CHAPTER_NUM}}` | Chapter number | Chapter page | Default |
+| `{{CHAPTER_TITLE}}` | Chapter title | Chapter page | Default |
+| `{{CHAPTER_DESC}}` | Chapter description | Chapter page | Optional |
+| `{{PAGE_TITLE}}` | Page title | Content page | Default |
+| `{{CONTENT_AREA}}` | Content area | Content page | Default |
+| `{{PAGE_NUM}}` | Page number | Content page, ending page | Default |
+| `{{KEY_MESSAGE}}` | Key takeaway | Content page (consulting style) | Style-specific |
+| `{{SECTION_NAME}}` | Section name | Content page footer | Optional |
+| `{{SOURCE}}` | Data source | Content page footer | Optional |
+| `{{THANK_YOU}}` | Thank-you message | Ending page | Default |
+| `{{CONTACT_INFO}}` | Contact info | Ending page | Default |
+| `{{ENDING_SUBTITLE}}` | Ending subtitle | Ending page | Optional |
+| `{{CLOSING_MESSAGE}}` | Closing message | Ending page | Style-specific |
+| `{{COPYRIGHT}}` | Copyright | Ending page | Optional |
For TOC pages in **newly created library templates**, use indexed placeholders:
@@ -190,7 +201,9 @@ For TOC pages in **newly created library templates**, use indexed placeholders:
Do **not** create new TOC placeholder families such as `{{CHAPTER_01_TITLE}}` for new templates. Existing templates may contain legacy placeholder variants, but new library assets should converge on the indexed TOC contract.
-When rebuilding from imported PPTX references, placeholder insertion takes priority over visual mimicry. If the original layout leaves insufficient room for canonical placeholders, adjust the layout instead of inventing one-off placeholder families.
+Variants reuse their parent type's placeholder set by default: every `03*_content*.svg` shares the content placeholder list above, unless the spec frontmatter declares an override for that specific stem.
+
+When rebuilding from imported PPTX references, placeholder insertion takes priority over visual mimicry. If the original layout leaves insufficient room for canonical placeholders, adjust the layout instead of inventing one-off placeholder families — or, if the deviation is intentional and meaningful, declare it in frontmatter.
---
diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.md
index a1450b2c..4eb28ca6 100644
--- a/skills/ppt-master/scripts/docs/project.md
+++ b/skills/ppt-master/scripts/docs/project.md
@@ -88,13 +88,16 @@ python3 scripts/pptx_template_import.py <template.pptx> -o <output_dir>
python3 scripts/pptx_template_import.py <template.pptx> --manifest-only
python3 scripts/pptx_template_import.py <template.pptx> --skip-manifest
python3 scripts/pptx_template_import.py <template.pptx> --embed-images
+python3 scripts/pptx_template_import.py <template.pptx> --inheritance-mode flat
```
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`, `master_layout_refs.json`, `master_layout_analysis.md`, `assets/`, and shape-level slide SVGs under `svg/`
+- Generates `manifest.json` (single source of truth for slide size, theme, assets, layouts, masters, slides, page-type candidates), `summary.md` (short orientation digest), `assets/`, and shape-level SVGs under `svg/`
+- **SVG output is layered by default**: each unique master / layout is rendered once as `svg/master_*.svg` / `svg/layout_*.svg`; `svg/slide_NN.svg` contains only that slide's own shapes; `svg/inheritance.json` records which layout / master each slide consumes. This gives template designers a clear separation between shared visual language and per-slide content.
+- Pass `--inheritance-mode flat` only when you need self-contained slide SVGs (round-trip use cases). The default `layered` is what `/create-template` consumes.
- SVG export reads OOXML directly via `pptx_to_svg` — no PowerPoint or Keynote dependency, runs on any platform
- `<image>` elements in `svg/` reference files in `assets/` directly; pass `--embed-images` to inline as data URIs instead
- Required in `/create-template` whenever the reference source is `.pptx`
diff --git a/skills/ppt-master/scripts/pptx_template_import.py b/skills/ppt-master/scripts/pptx_template_import.py
index 0718de79..d95aa7e7 100644
--- a/skills/ppt-master/scripts/pptx_template_import.py
+++ b/skills/ppt-master/scripts/pptx_template_import.py
@@ -3,9 +3,9 @@
Reads OOXML directly via `pptx_to_svg` and writes a reusable reference workspace:
-- `manifest.json` — slide size, theme colors, fonts, asset inventory
-- `master_layout_refs.json` / `master_layout_analysis.md` — master/layout structure
-- `analysis.md` — page-type guidance
+- `manifest.json` — single source of truth for slide size, theme colors, fonts,
+ asset inventory, and per-slide / per-layout / per-master metadata
+- `summary.md` — short human-readable digest derived from manifest.json
- `assets/` — extracted reusable image assets
- `svg/` — shape-level SVG per slide (real <text>, <image>, geometry)
"""
@@ -20,6 +20,7 @@ from template_import.manifest import build_manifest
def parse_args() -> argparse.Namespace:
+ """Build the CLI argument parser for the import entry point."""
parser = argparse.ArgumentParser(
description="Prepare a PPTX reference workspace for /create-template."
)
@@ -37,17 +38,35 @@ def parse_args() -> argparse.Namespace:
parser.add_argument(
"--manifest-only",
action="store_true",
- help="Only extract manifest.json, analysis.md, and reusable assets without exporting slides to SVG",
+ help=(
+ "Only extract manifest.json + summary.md + reusable assets, "
+ "without exporting slides to SVG"
+ ),
)
parser.add_argument(
"--embed-images",
action="store_true",
help="Inline images as data: URIs instead of writing files to assets/",
)
+ parser.add_argument(
+ "--inheritance-mode",
+ choices=("layered", "flat"),
+ default="layered",
+ help=(
+ "How to render master/layout shapes inside slide SVGs. "
+ "'layered' (default for /create-template): each slide SVG contains "
+ "only its own shapes; master/layout are rendered once each as "
+ "separate svg/master_*.svg / svg/layout_*.svg files plus "
+ "svg/inheritance.json. 'flat': inline inherited shapes inside every "
+ "slide (legacy behavior; pick this only when you need self-contained "
+ "slide SVGs)."
+ ),
+ )
return parser.parse_args()
def main() -> int:
+ """CLI entry point: write the PPTX reference workspace to disk."""
args = parse_args()
pptx_path = Path(args.pptx_file).expanduser().resolve()
if not pptx_path.exists():
@@ -68,14 +87,15 @@ def main() -> int:
print("Error: --skip-manifest and --manifest-only cannot be used together")
return 1
+ manifest = None
+ manifest_path = output_dir / "manifest.json"
if not args.skip_manifest:
try:
manifest = build_manifest(pptx_path, output_dir)
- except Exception as exc:
+ except (RuntimeError, OSError, ValueError) as exc:
print(f"Error: failed to extract PPTX metadata: {exc}")
return 1
- manifest_path = output_dir / "manifest.json"
manifest_path.write_text(
json.dumps(manifest, ensure_ascii=False, indent=2) + "\n",
encoding="utf-8",
@@ -84,11 +104,14 @@ def main() -> int:
if args.manifest_only:
print(f"Imported PPTX template source: {pptx_path.name}")
print(f"Output directory: {output_dir}")
- if not args.skip_manifest:
+ if manifest is not None:
print(f"Manifest: {manifest_path.name}")
+ print("Summary: summary.md")
print(f"Assets exported: {len(manifest['assets']['allAssets'])}")
print(f"Common assets: {len(manifest['assets']['commonAssets'])}")
print(f"Slides analyzed: {len(manifest['slides'])}")
+ print(f"Layouts (unique): {len(manifest.get('layouts', []))}")
+ print(f"Masters (unique): {len(manifest.get('masters', []))}")
return 0
from pptx_to_svg import convert_pptx_to_svg
@@ -98,11 +121,17 @@ def main() -> int:
media_subdir="assets",
embed_images=args.embed_images,
keep_hidden=False,
+ inheritance_mode=args.inheritance_mode,
)
result = convert_pptx_to_svg(pptx_path, output_dir, options)
total_bytes = sum(len(art.svg.encode("utf-8")) for art in result.slides)
+ print(f"Inheritance mode: {args.inheritance_mode}")
print(f"Exported SVG slides: {len(result.slides)}")
+ if args.inheritance_mode == "layered":
+ print(f"Exported masters: {len(result.masters)}")
+ print(f"Exported layouts: {len(result.layouts)}")
+ print("Inheritance graph: svg/inheritance.json")
print(f"SVG bytes: {total_bytes}")
print(f"Output directory: {output_dir}")
return 0
diff --git a/skills/ppt-master/scripts/pptx_to_svg/converter.py b/skills/ppt-master/scripts/pptx_to_svg/converter.py
index 0dbc9955..21b2d338 100644
--- a/skills/ppt-master/scripts/pptx_to_svg/converter.py
+++ b/skills/ppt-master/scripts/pptx_to_svg/converter.py
@@ -13,13 +13,15 @@ loads the package and reports basic per-slide structure to verify wiring.
from __future__ import annotations
+import json
+import re
from dataclasses import dataclass, field
-from pathlib import Path
+from pathlib import Path, PurePosixPath
from .color_resolver import ColorPalette
from .emu_units import NS
-from .ooxml_loader import OoxmlPackage, SlideRef
-from .slide_to_svg import assemble_slide
+from .ooxml_loader import OoxmlPackage, PartRef, SlideRef
+from .slide_to_svg import assemble_part_solo, assemble_slide
@dataclass
@@ -31,11 +33,29 @@ class ConvertOptions:
embed_images: when True, base64-encode images inline instead of writing
files. Default False (matches svg_to_pptx default of external images).
keep_hidden: include shapes marked hidden="1". Default False.
+ inheritance_mode: how to render master/layout shapes inside each slide SVG.
+ - "flat" (default): inline inherited shapes into every slide. Used by
+ svg_to_pptx round-trip and any caller that wants self-contained slides.
+ - "layered": skip inherited shapes inside the slide. The orchestrator
+ additionally renders each unique master and layout to its own SVG and
+ writes svg/inheritance.json so the deck's reuse graph is explicit.
"""
media_subdir: str = "assets"
embed_images: bool = False
keep_hidden: bool = False
+ inheritance_mode: str = "flat"
+
+
+@dataclass
+class PartArtifact:
+ """Result of converting a master or layout part to SVG (layered mode only)."""
+
+ role: str # "master" | "layout"
+ part_path: str # OOXML part path, e.g. "ppt/slideLayouts/slideLayout3.xml"
+ filename: str # output svg filename, e.g. "layout_03_title.xml.svg"
+ svg: str
+ media_files: dict[str, bytes] = field(default_factory=dict)
@dataclass
@@ -45,6 +65,8 @@ class SlideArtifact:
index: int # 1-based
svg: str
media_files: dict[str, bytes] = field(default_factory=dict)
+ layout_part_path: str | None = None
+ master_part_path: str | None = None
@dataclass
@@ -55,6 +77,8 @@ class ConvertResult:
canvas_px: tuple[float, float] = (1280.0, 720.0)
theme_colors: dict[str, str] = field(default_factory=dict)
theme_fonts: dict[str, str] = field(default_factory=dict)
+ layouts: list[PartArtifact] = field(default_factory=list)
+ masters: list[PartArtifact] = field(default_factory=list)
# ---------------------------------------------------------------------------
@@ -78,6 +102,11 @@ def convert_pptx_to_svg(
ConvertResult with per-slide SVG strings and resolved theme info.
"""
options = options or ConvertOptions()
+ if options.inheritance_mode not in {"flat", "layered"}:
+ raise ValueError(
+ f"inheritance_mode must be 'flat' or 'layered', "
+ f"got {options.inheritance_mode!r}"
+ )
result = ConvertResult()
with OoxmlPackage(pptx_path) as pkg:
@@ -124,6 +153,10 @@ def convert_pptx_to_svg(
artifact = _convert_slide(pkg, slide, palette, options, result.theme_fonts)
result.slides.append(artifact)
+ # Layered mode: also render each unique master / layout once.
+ if options.inheritance_mode == "layered":
+ _convert_inheritance_parts(pkg, palette, options, result)
+
if output_dir is not None:
_write_artifacts(output_dir, result, options)
@@ -144,8 +177,75 @@ def _convert_slide(
media_subdir=options.media_subdir,
embed_images=options.embed_images,
keep_hidden=options.keep_hidden,
+ inheritance_mode=options.inheritance_mode,
+ )
+ return SlideArtifact(
+ index=slide.index,
+ svg=svg,
+ media_files=media,
+ layout_part_path=slide.layout.path if slide.layout else None,
+ master_part_path=slide.master.path if slide.master else None,
+ )
+
+
+def _convert_inheritance_parts(
+ pkg: OoxmlPackage,
+ palette: ColorPalette,
+ options: ConvertOptions,
+ result: ConvertResult,
+) -> None:
+ """Render each unique master and layout to its own SVG (layered mode)."""
+ # Collect unique parts in slide-encounter order so output filenames are
+ # deterministic for a given .pptx.
+ seen_layouts: dict[str, PartRef] = {}
+ seen_masters: dict[str, PartRef] = {}
+ for slide in pkg.iter_slides():
+ if slide.layout is not None and slide.layout.path not in seen_layouts:
+ seen_layouts[slide.layout.path] = slide.layout
+ if slide.master is not None and slide.master.path not in seen_masters:
+ seen_masters[slide.master.path] = slide.master
+
+ for seq, part in enumerate(seen_masters.values(), start=1):
+ result.masters.append(_render_part(
+ pkg, part, palette, options, result.theme_fonts,
+ role="master", seq=seq,
+ ))
+ for seq, part in enumerate(seen_layouts.values(), start=1):
+ result.layouts.append(_render_part(
+ pkg, part, palette, options, result.theme_fonts,
+ role="layout", seq=seq,
+ ))
+
+
+def _render_part(
+ pkg: OoxmlPackage,
+ part: PartRef,
+ palette: ColorPalette,
+ options: ConvertOptions,
+ theme_fonts: dict[str, str],
+ *,
+ role: str,
+ seq: int,
+) -> PartArtifact:
+ """Render a master/layout part, returning a PartArtifact with output filename."""
+ svg, media = assemble_part_solo(
+ pkg, part, palette,
+ role=role,
+ theme_fonts=theme_fonts,
+ media_subdir=options.media_subdir,
+ embed_images=options.embed_images,
+ keep_hidden=options.keep_hidden,
+ )
+ stem = PurePosixPath(part.path).stem # e.g. "slideLayout3"
+ safe_stem = re.sub(r"[^A-Za-z0-9_-]+", "_", stem).strip("_") or role
+ filename = f"{role}_{seq:02d}_{safe_stem}.svg"
+ return PartArtifact(
+ role=role,
+ part_path=part.path,
+ filename=filename,
+ svg=svg,
+ media_files=media,
)
- return SlideArtifact(index=slide.index, svg=svg, media_files=media)
def _write_artifacts(output_dir: Path, result: ConvertResult,
@@ -157,12 +257,68 @@ def _write_artifacts(output_dir: Path, result: ConvertResult,
media_dir = output_dir / options.media_subdir
media_written: set[str] = set()
- for art in result.slides:
- target = svg_dir / f"slide_{art.index:02d}.svg"
- target.write_text(art.svg, encoding="utf-8")
- for filename, blob in art.media_files.items():
+ def _write_media(media: dict[str, bytes]) -> None:
+ for filename, blob in media.items():
if filename in media_written:
continue
media_dir.mkdir(parents=True, exist_ok=True)
(media_dir / filename).write_bytes(blob)
media_written.add(filename)
+
+ # Layered mode: write masters and layouts first so they sort ahead of slides.
+ for art in result.masters:
+ (svg_dir / art.filename).write_text(art.svg, encoding="utf-8")
+ _write_media(art.media_files)
+ for art in result.layouts:
+ (svg_dir / art.filename).write_text(art.svg, encoding="utf-8")
+ _write_media(art.media_files)
+
+ # Slides
+ for art in result.slides:
+ target = svg_dir / f"slide_{art.index:02d}.svg"
+ target.write_text(art.svg, encoding="utf-8")
+ _write_media(art.media_files)
+
+ # Layered mode: dump the inheritance graph alongside the SVGs.
+ if options.inheritance_mode == "layered":
+ _write_inheritance_json(svg_dir, result)
+
+
+def _write_inheritance_json(svg_dir: Path, result: ConvertResult) -> None:
+ """Record which layout/master each slide consumes (layered mode only)."""
+ layout_by_path = {art.part_path: art.filename for art in result.layouts}
+ master_by_path = {art.part_path: art.filename for art in result.masters}
+ layout_to_master: dict[str, str | None] = {}
+ # We don't have the part->parent map from OoxmlPackage here directly, so
+ # derive it from slides.
+ for slide in result.slides:
+ if slide.layout_part_path and slide.layout_part_path not in layout_to_master:
+ layout_to_master[slide.layout_part_path] = slide.master_part_path
+
+ inheritance = {
+ "masters": [
+ {"file": art.filename, "partPath": art.part_path}
+ for art in result.masters
+ ],
+ "layouts": [
+ {
+ "file": art.filename,
+ "partPath": art.part_path,
+ "master": master_by_path.get(layout_to_master.get(art.part_path) or ""),
+ }
+ for art in result.layouts
+ ],
+ "slides": [
+ {
+ "file": f"slide_{slide.index:02d}.svg",
+ "index": slide.index,
+ "layout": layout_by_path.get(slide.layout_part_path or ""),
+ "master": master_by_path.get(slide.master_part_path or ""),
+ }
+ for slide in result.slides
+ ],
+ }
+ (svg_dir / "inheritance.json").write_text(
+ json.dumps(inheritance, ensure_ascii=False, indent=2) + "\n",
+ encoding="utf-8",
+ )
diff --git a/skills/ppt-master/scripts/pptx_to_svg/slide_to_svg.py b/skills/ppt-master/scripts/pptx_to_svg/slide_to_svg.py
index b42a8425..1df8f7c0 100644
--- a/skills/ppt-master/scripts/pptx_to_svg/slide_to_svg.py
+++ b/skills/ppt-master/scripts/pptx_to_svg/slide_to_svg.py
@@ -88,8 +88,19 @@ def assemble_slide(
media_subdir: str = "assets",
embed_images: bool = False,
keep_hidden: bool = False,
+ inheritance_mode: str = "flat",
) -> tuple[str, dict[str, bytes]]:
- """Convert one slide to a complete SVG string + media files map."""
+ """Convert one slide to a complete SVG string + media files map.
+
+ inheritance_mode controls how master/layout shapes are rendered:
+ - "flat" (default): emit master + layout non-placeholder shapes inline
+ inside the slide SVG. This is the historical behavior, used for
+ round-trip fidelity with svg_to_pptx.
+ - "layered": skip inherited shapes entirely. The slide SVG contains
+ only its own shapes. Callers (e.g. /create-template's PPTX import)
+ render master/layout once each as separate SVGs and record the
+ inheritance graph in inheritance.json.
+ """
ctx = AssemblyContext(
palette=palette,
pkg=pkg,
@@ -108,9 +119,14 @@ def assemble_slide(
if bg_xml:
body_parts.append(bg_xml)
- # Inherited layout/master shapes render behind slide-local shapes. Skip
- # placeholders; they define editable regions, not visible background.
- body_parts.extend(_emit_inherited_shapes(slide, ctx))
+ if inheritance_mode == "flat":
+ # Inherited layout/master shapes render behind slide-local shapes. Skip
+ # placeholders; they define editable regions, not visible background.
+ body_parts.extend(_emit_inherited_shapes(slide, ctx))
+ elif inheritance_mode != "layered":
+ raise ValueError(
+ f"inheritance_mode must be 'flat' or 'layered', got {inheritance_mode!r}"
+ )
# Walk shapes
nodes = walk_sp_tree(slide.part.xml)
@@ -135,6 +151,76 @@ def assemble_slide(
return svg, ctx.media
+def assemble_part_solo(
+ pkg: OoxmlPackage,
+ part: PartRef,
+ palette: ColorPalette | None,
+ *,
+ role: str,
+ theme_fonts: dict[str, str] | None = None,
+ media_subdir: str = "assets",
+ embed_images: bool = False,
+ keep_hidden: bool = False,
+) -> tuple[str, dict[str, bytes]]:
+ """Render a single slideMaster or slideLayout part as a standalone SVG.
+
+ Used by the layered export path. Skips placeholders the same way
+ `_emit_inherited_shapes` does, so the output represents the part's
+ decorative / structural shapes only — what the part *contributes* to its
+ descendants. The first ancestor's background (if any) is emitted as the
+ first body element so the output reads like a real slide.
+
+ Args:
+ role: 'master' or 'layout'. Used as the group_id_prefix to keep ids
+ unique when the workspace inlines multiple parts in a viewer.
+ """
+ if role not in {"master", "layout"}:
+ raise ValueError(f"role must be 'master' or 'layout', got {role!r}")
+
+ ctx = AssemblyContext(
+ palette=palette,
+ pkg=pkg,
+ slide_part=part,
+ theme_fonts=theme_fonts or {},
+ media_subdir=media_subdir,
+ embed_images=embed_images,
+ keep_hidden=keep_hidden,
+ group_id_prefix=f"{role}-",
+ )
+
+ canvas_w, canvas_h = pkg.slide_size_px
+
+ body_parts: list[str] = []
+
+ # Background: only meaningful if the part itself declares one.
+ fake_slide = SlideRef(index=0, part=part, layout=None, master=None)
+ bg_xml = _emit_background(fake_slide, ctx, canvas_w, canvas_h)
+ if bg_xml:
+ body_parts.append(bg_xml)
+
+ # Walk shapes, skipping placeholders (consistent with _emit_inherited_shapes).
+ for node in walk_sp_tree(part.xml):
+ if _is_placeholder_node(node):
+ continue
+ chunk = _convert_node(node, ctx, top_level=True)
+ if chunk:
+ body_parts.append(chunk)
+
+ defs_xml = "".join(ctx.defs) if ctx.defs else ""
+ defs_block = f"<defs>{defs_xml}</defs>" if defs_xml else ""
+
+ svg = (
+ f'<svg xmlns="http://www.w3.org/2000/svg" '
+ f'xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" '
+ f'width="{fmt_num(canvas_w)}" height="{fmt_num(canvas_h)}" '
+ f'viewBox="0 0 {fmt_num(canvas_w)} {fmt_num(canvas_h)}">'
+ f"{defs_block}"
+ + "\n".join(body_parts)
+ + "</svg>"
+ )
+ return svg, ctx.media
+
+
# ---------------------------------------------------------------------------
# Per-node dispatch
# ---------------------------------------------------------------------------
diff --git a/skills/ppt-master/scripts/register_template.py b/skills/ppt-master/scripts/register_template.py
new file mode 100644
index 00000000..2d6b3ee0
--- /dev/null
+++ b/skills/ppt-master/scripts/register_template.py
@@ -0,0 +1,485 @@
+#!/usr/bin/env python3
+"""Register a layout template into the global template index.
+
+Reads ``templates/layouts/<template_id>/design_spec.md`` (preferring its YAML
+frontmatter when present, falling back to the §I / §III table values) and
+synchronizes two derived indexes:
+
+- ``templates/layouts/layouts_index.json`` — slim machine-readable map
+- ``templates/layouts/README.md`` — human-facing "Quick Template Index" table
+
+This script is the single source-of-truth bridge between a template's design
+spec and the indexes. Run it after creating a new template (or after editing a
+spec) and the indexes update automatically — no manual JSON / Markdown surgery.
+
+Usage:
+ python3 scripts/register_template.py <template_id>
+ python3 scripts/register_template.py <template_id> --dry-run
+ python3 scripts/register_template.py --rebuild-all
+
+The last form rebuilds every entry from scratch, which is the recommended way
+to repair index drift across many templates at once.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from collections import OrderedDict
+from pathlib import Path
+from typing import Iterable
+
+try:
+ import yaml # type: ignore
+except ImportError: # pragma: no cover — yaml is part of stdlib-adjacent deps
+ yaml = None
+
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+SKILL_DIR = SCRIPT_DIR.parent
+LAYOUTS_DIR = SKILL_DIR / "templates" / "layouts"
+INDEX_PATH = LAYOUTS_DIR / "layouts_index.json"
+README_PATH = LAYOUTS_DIR / "README.md"
+
+QUICK_INDEX_BEGIN = "<!-- quick-index:begin -->"
+QUICK_INDEX_END = "<!-- quick-index:end -->"
+
+
+# ---------------------------------------------------------------------------
+# design_spec.md parsing
+# ---------------------------------------------------------------------------
+
+class SpecParseError(RuntimeError):
+ """Raised when a design_spec.md cannot be turned into an index entry."""
+
+
+def _read_spec(spec_path: Path) -> tuple[dict | None, str]:
+ """Split YAML frontmatter from the body. Returns ``(frontmatter, body)``."""
+ text = spec_path.read_text(encoding="utf-8")
+ if not text.startswith("---\n"):
+ return None, text
+
+ end = text.find("\n---\n", 4)
+ if end == -1:
+ return None, text
+
+ fm_block = text[4:end]
+ body = text[end + 5:]
+ if yaml is None:
+ raise SpecParseError(
+ "design_spec.md has YAML frontmatter but PyYAML is not installed; "
+ "install pyyaml or remove the frontmatter."
+ )
+ try:
+ data = yaml.safe_load(fm_block) or {}
+ except yaml.YAMLError as exc:
+ raise SpecParseError(f"invalid YAML frontmatter: {exc}") from exc
+ if not isinstance(data, dict):
+ raise SpecParseError("YAML frontmatter must be a mapping")
+ return data, body
+
+
+def _extract_section_field(body: str, section_title: str, labels: list[str]) -> str | None:
+ """Find a field within the named section.
+
+ Tolerates two layouts the existing specs use:
+
+ 1. Markdown table row: ``| **Label** | value |``
+ 2. Bullet list: ``- **Label**: value``
+
+ Tries each label variant in order. Returns the first match or ``None``.
+ """
+ section_re = re.compile(
+ rf"^##\s+{re.escape(section_title)}\b.*?(?=^##\s+|\Z)",
+ re.MULTILINE | re.DOTALL,
+ )
+ section_match = section_re.search(body)
+ if section_match is None:
+ return None
+ section = section_match.group(0)
+
+ for label in labels:
+ # Table form
+ row = re.search(
+ rf"^\|\s*\*?\*?{re.escape(label)}\*?\*?\s*\|\s*(.+?)\s*\|",
+ section,
+ re.MULTILINE | re.IGNORECASE,
+ )
+ if row:
+ return _clean_field_value(row.group(1))
+
+ # Bullet form
+ bullet = re.search(
+ rf"^[-*]\s*\*?\*?{re.escape(label)}\*?\*?\s*[::]\s*(.+?)\s*$",
+ section,
+ re.MULTILINE | re.IGNORECASE,
+ )
+ if bullet:
+ return _clean_field_value(bullet.group(1))
+ return None
+
+
+def _clean_field_value(value: str) -> str:
+ """Strip surrounding markdown decorations from an extracted field value."""
+ value = value.strip()
+ # Drop wrapping backticks / asterisks / underscores.
+ value = re.sub(r"^[`*_]+", "", value)
+ value = re.sub(r"[`*_]+$", "", value)
+ return value.strip()
+
+
+def _strip_paren_alias(value: str) -> str:
+ """Drop a trailing ``(... alias ...)`` if the slug appears at the start."""
+ return re.sub(r"\s*\([^)]*\)\s*$", "", value).strip()
+
+
+def _find_first_color(section: str) -> str | None:
+ match = re.search(r"`(#[0-9A-Fa-f]{3,8})`", section)
+ return match.group(1).upper() if match else None
+
+
+def _extract_primary_color(body: str) -> str | None:
+ """Pull the first hex color out of the §III Color Scheme section."""
+ section_match = re.search(
+ r"^##\s+III\.\s+Color Scheme\b.*?(?=^##\s+|\Z)",
+ body,
+ re.MULTILINE | re.DOTALL,
+ )
+ if section_match is None:
+ return None
+ return _find_first_color(section_match.group(0))
+
+
+def _split_keywords(value: object) -> list[str]:
+ if isinstance(value, list):
+ return [str(item).strip() for item in value if str(item).strip()]
+ if isinstance(value, str):
+ parts = re.split(r"[,,;;/、]", value)
+ return [p.strip() for p in parts if p.strip()]
+ return []
+
+
+def _summary_from_use_cases(use_cases: str | None) -> str | None:
+ if not use_cases:
+ return None
+ cleaned = use_cases.strip().rstrip(".")
+ if not cleaned:
+ return None
+ return f"For {cleaned}."
+
+
+# ---------------------------------------------------------------------------
+# Per-template extraction
+# ---------------------------------------------------------------------------
+
+def _list_pages(template_dir: Path) -> list[str]:
+ return sorted(p.stem for p in template_dir.glob("*.svg"))
+
+
+def _extract_entry(template_id: str, template_dir: Path) -> dict:
+ spec_path = template_dir / "design_spec.md"
+ if not spec_path.exists():
+ raise SpecParseError(f"missing design_spec.md in {template_dir}")
+
+ frontmatter, body = _read_spec(spec_path)
+ fm = frontmatter or {}
+
+ label = fm.get("label")
+ if not label:
+ raw = _extract_section_field(
+ body, "I. Template Overview", ["Template Name", "Name"]
+ )
+ if raw:
+ # Prefer the human-facing form when present, else fall back to id.
+ if "(" in raw and ")" in raw:
+ inner = _clean_field_value(
+ raw[raw.find("(") + 1: raw.rfind(")")]
+ )
+ label = inner or _strip_paren_alias(raw) or template_id
+ else:
+ label = _strip_paren_alias(raw) or template_id
+ else:
+ label = template_id
+
+ summary = fm.get("summary")
+ if not summary:
+ summary = _summary_from_use_cases(
+ _extract_section_field(
+ body, "I. Template Overview", ["Use Cases", "Use cases"]
+ )
+ )
+ summary = (summary or "").strip()
+
+ keywords = _split_keywords(fm.get("keywords"))
+ if not keywords:
+ tone = _extract_section_field(
+ body, "I. Template Overview", ["Design Tone", "Tone"]
+ ) or ""
+ keywords = _split_keywords(tone)[:5]
+
+ primary_color = fm.get("primary_color") or _extract_primary_color(body)
+ category = fm.get("category", "general")
+ use_cases = (
+ fm.get("use_cases")
+ or _extract_section_field(
+ body, "I. Template Overview", ["Use Cases", "Use cases"]
+ )
+ or ""
+ )
+ design_tone = (
+ fm.get("design_tone")
+ or _extract_section_field(
+ body, "I. Template Overview", ["Design Tone", "Tone"]
+ )
+ or ""
+ )
+
+ pages = _list_pages(template_dir)
+
+ entry = OrderedDict(
+ label=label,
+ summary=summary,
+ keywords=keywords,
+ pages=pages,
+ )
+
+ extras = OrderedDict(
+ category=str(category),
+ primary_color=str(primary_color or ""),
+ use_cases=str(use_cases),
+ design_tone=str(design_tone),
+ )
+ return {"entry": entry, "extras": extras}
+
+
+# ---------------------------------------------------------------------------
+# Index writers
+# ---------------------------------------------------------------------------
+
+def _load_index() -> "OrderedDict[str, dict]":
+ if not INDEX_PATH.exists():
+ return OrderedDict()
+ raw = json.loads(INDEX_PATH.read_text(encoding="utf-8"))
+ return OrderedDict(sorted(raw.items()))
+
+
+def _write_index(data: "OrderedDict[str, dict]", *, dry_run: bool) -> None:
+ payload = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
+ if dry_run:
+ print(f"--- {INDEX_PATH.name} (dry-run) ---")
+ print(payload)
+ return
+ INDEX_PATH.write_text(payload, encoding="utf-8")
+
+
+def _render_quick_index_rows(
+ items: Iterable[tuple[str, dict, dict]],
+) -> list[str]:
+ rows: list[str] = [
+ "| Template Name | Category | Use Cases | Primary Color | Design Tone |",
+ "|---------------|----------|-----------|---------------|-------------|",
+ ]
+ for tid, _, extras in items:
+ cat = extras.get("category") or "general"
+ use_cases = extras.get("use_cases") or "—"
+ primary = extras.get("primary_color") or "—"
+ if primary != "—":
+ primary = f"`{primary}`"
+ tone = extras.get("design_tone") or "—"
+ rows.append(
+ f"| `{tid}` | {cat.title()} | {use_cases} | {primary} | {tone} |"
+ )
+ return rows
+
+
+def _patch_readme(
+ items: list[tuple[str, dict, dict]],
+ *,
+ dry_run: bool,
+) -> None:
+ text = README_PATH.read_text(encoding="utf-8") if README_PATH.exists() else ""
+
+ # Update header count
+ new_total = len(items)
+ text = re.sub(
+ r"^# Page Layout Template Library \(\d+ Templates\)",
+ f"# Page Layout Template Library ({new_total} Templates)",
+ text,
+ count=1,
+ flags=re.MULTILINE,
+ )
+
+ rows = _render_quick_index_rows(items)
+ block = "\n".join([QUICK_INDEX_BEGIN, *rows, QUICK_INDEX_END])
+
+ if QUICK_INDEX_BEGIN in text and QUICK_INDEX_END in text:
+ text = re.sub(
+ re.escape(QUICK_INDEX_BEGIN) + r".*?" + re.escape(QUICK_INDEX_END),
+ block,
+ text,
+ count=1,
+ flags=re.DOTALL,
+ )
+ else:
+ # Insert the auto-managed block after the "## Quick Template Index"
+ # heading; if the heading is missing, append at end.
+ anchor = "## Quick Template Index"
+ if anchor in text:
+ head, _, tail = text.partition(anchor)
+ # Drop the legacy hand-maintained table that follows the anchor up
+ # to the next "## " heading, then re-insert the managed block.
+ tail_lines = tail.splitlines(keepends=True)
+ keep_from = 0
+ for idx, line in enumerate(tail_lines[1:], start=1):
+ if line.startswith("## "):
+ keep_from = idx
+ break
+ preserved_tail = "".join(tail_lines[keep_from:])
+ text = (
+ f"{head}{anchor}\n\n{block}\n\n{preserved_tail}"
+ )
+ else:
+ text = f"{text.rstrip()}\n\n## Quick Template Index\n\n{block}\n"
+
+ if dry_run:
+ print(f"--- {README_PATH.name} (dry-run) ---")
+ print(text)
+ return
+ README_PATH.write_text(text, encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def _enumerate_templates() -> list[str]:
+ return sorted(
+ p.name for p in LAYOUTS_DIR.iterdir()
+ if p.is_dir() and p.name != "images" and (p / "design_spec.md").exists()
+ )
+
+
+def _print_completion_card(template_id: str, entry: dict, extras: dict) -> None:
+ print()
+ print("## Template Creation Complete")
+ print()
+ print(f"**Template Name**: {template_id}"
+ f" ({entry.get('label', template_id)})")
+ print(f"**Template Path**: `templates/layouts/{template_id}/`")
+ print(f"**Category**: {extras.get('category', 'general')}")
+ primary = extras.get("primary_color") or "—"
+ print(f"**Primary Color**: {primary}")
+ print("**Index Registration**: Done")
+ print()
+ print("### Files Included")
+ print()
+ print("| File | Status |")
+ print("|------|--------|")
+ for page in entry.get("pages", []):
+ print(f"| `{page}.svg` | Done |")
+ print()
+
+
+def main() -> int:
+ """CLI entry: register one template (or rebuild all) into the index."""
+ parser = argparse.ArgumentParser(
+ description="Register / refresh layout templates in the global index."
+ )
+ parser.add_argument(
+ "template_id",
+ nargs="?",
+ help="Template directory under templates/layouts/. Omit with --rebuild-all.",
+ )
+ parser.add_argument(
+ "--rebuild-all",
+ action="store_true",
+ help="Rebuild every index entry from each template's design_spec.md.",
+ )
+ parser.add_argument(
+ "--dry-run",
+ action="store_true",
+ help="Show what would be written without modifying any files.",
+ )
+ args = parser.parse_args()
+
+ if not args.template_id and not args.rebuild_all:
+ parser.error("provide a template_id or use --rebuild-all")
+
+ if args.rebuild_all:
+ ids = _enumerate_templates()
+ else:
+ ids = [args.template_id]
+ spec_dir = LAYOUTS_DIR / args.template_id
+ if not spec_dir.is_dir():
+ print(f"Error: template directory not found: {spec_dir}",
+ file=sys.stderr)
+ return 1
+
+ # Build entries for the requested ids.
+ extracted: dict[str, dict] = {}
+ for tid in ids:
+ try:
+ extracted[tid] = _extract_entry(tid, LAYOUTS_DIR / tid)
+ except SpecParseError as exc:
+ print(f"Error: {tid}: {exc}", file=sys.stderr)
+ return 1
+
+ # Merge into the index (preserving sibling entries when single-template mode).
+ if args.rebuild_all:
+ index = OrderedDict(
+ (tid, extracted[tid]["entry"]) for tid in sorted(extracted)
+ )
+ else:
+ index = _load_index()
+ for tid, payload in extracted.items():
+ index[tid] = payload["entry"]
+ index = OrderedDict(sorted(index.items()))
+
+ _write_index(index, dry_run=args.dry_run)
+
+ # README is rebuilt from the union of (current index) + (newly extracted
+ # entries). For rebuild-all it is just the extracted set.
+ if args.rebuild_all:
+ readme_items: list[tuple[str, dict, dict]] = [
+ (tid, extracted[tid]["entry"], extracted[tid]["extras"])
+ for tid in sorted(extracted)
+ ]
+ else:
+ readme_items = []
+ all_extras: dict[str, dict] = {}
+ for tid in index:
+ if tid in extracted:
+ all_extras[tid] = extracted[tid]["extras"]
+ else:
+ template_dir = LAYOUTS_DIR / tid
+ if (template_dir / "design_spec.md").exists():
+ try:
+ all_extras[tid] = _extract_entry(tid, template_dir)["extras"]
+ except SpecParseError:
+ all_extras[tid] = {}
+ else:
+ all_extras[tid] = {}
+ readme_items.append((tid, index[tid], all_extras[tid]))
+
+ _patch_readme(readme_items, dry_run=args.dry_run)
+
+ if not args.dry_run and not args.rebuild_all:
+ tid = args.template_id
+ _print_completion_card(
+ tid, extracted[tid]["entry"], extracted[tid]["extras"]
+ )
+ return 0
+
+ print()
+ print(
+ f"[OK] {'Dry-run preview' if args.dry_run else 'Updated'}: "
+ f"{len(extracted)} template(s) processed; "
+ f"index now lists {len(index)} entries."
+ )
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.py
index 5f8d3f4e..fcb8ba00 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -46,10 +46,111 @@ RAMP_MIN_RATIO = 0.5
RAMP_MAX_RATIO = 5.0
+def _parse_placeholders_fallback(block: str) -> Dict[str, Tuple[str, ...]]:
+ """Tiny YAML-free reader for the documented ``placeholders:`` shape.
+
+ Used only when PyYAML is unavailable. Recognized lines (indentation-aware,
+ two-space indent assumed):
+
+ .. code-block:: yaml
+
+ placeholders:
+ 01_cover: ["{{TITLE}}", "{{LOGO}}"]
+ 03_content: []
+ 03a_content_two_col:
+ - "{{LEFT_TITLE}}"
+ - "{{RIGHT_TITLE}}"
+
+ Anything outside this minimal grammar is silently skipped — designers who
+ rely on advanced YAML should install pyyaml.
+ """
+ out: Dict[str, Tuple[str, ...]] = {}
+ inline_re = re.compile(
+ r"^\s{2}([A-Za-z0-9_]+)\s*:\s*\[(.*)\]\s*$"
+ )
+ empty_re = re.compile(r"^\s{2}([A-Za-z0-9_]+)\s*:\s*\[\s*\]\s*$")
+ block_header_re = re.compile(r"^\s{2}([A-Za-z0-9_]+)\s*:\s*$")
+ item_re = re.compile(r'^\s{4}-\s*"?([^"]+)"?\s*$')
+
+ in_section = False
+ current_block_key: str | None = None
+ current_items: List[str] = []
+
+ def _flush_block() -> None:
+ nonlocal current_block_key, current_items
+ if current_block_key is not None:
+ out[current_block_key] = tuple(current_items)
+ current_block_key = None
+ current_items = []
+
+ for line in block.splitlines():
+ if line.startswith("placeholders:"):
+ in_section = True
+ continue
+ if not in_section:
+ continue
+
+ # End of section: dedent to a non-key line.
+ if line and not line.startswith(" "):
+ _flush_block()
+ in_section = False
+ continue
+
+ if current_block_key is not None:
+ m = item_re.match(line)
+ if m:
+ value = m.group(1).strip().strip('"').strip("'")
+ if value:
+ current_items.append(value)
+ continue
+ # Block ended.
+ _flush_block()
+
+ if empty_re.match(line):
+ key = empty_re.match(line).group(1)
+ out[key] = ()
+ continue
+
+ m = inline_re.match(line)
+ if m:
+ key, raw = m.group(1), m.group(2)
+ items = [p.strip().strip('"').strip("'") for p in raw.split(",")]
+ out[key] = tuple(item for item in items if item)
+ continue
+
+ m = block_header_re.match(line)
+ if m:
+ current_block_key = m.group(1)
+ current_items = []
+ continue
+
+ _flush_block()
+ return out
+
+
class SVGQualityChecker:
"""SVG quality checker"""
- def __init__(self):
+ # Default placeholder convention per page-type prefix. This is a *hint*,
+ # not a hard contract: templates may define their own placeholder vocabulary
+ # via `placeholders:` in design_spec.md frontmatter (see
+ # references/template-designer.md §4). Missing default placeholders surface
+ # as warnings, never errors — designers may legitimately swap
+ # `{{THANK_YOU}}` for `{{CLOSING_MESSAGE}}`, omit `{{DATE}}` when irrelevant,
+ # or build content variants with bespoke slot vocabularies.
+ #
+ # Variants reuse the parent type's expectation (`03a_content_two_col.svg`
+ # is matched by the same `03_content` rules as `03_content.svg`).
+ DEFAULT_PLACEHOLDER_CONVENTION = {
+ "01_cover": ("{{TITLE}}",), # only the title is universally expected
+ "02_chapter": ("{{CHAPTER_TITLE}}",),
+ "02_toc": (), # TOC layouts vary too widely to assert anything
+ "03_content": ("{{PAGE_TITLE}}",),
+ "04_ending": (), # ending pages legitimately use varied vocabularies
+ }
+
+ def __init__(self, *, template_mode: bool = False):
+ self.template_mode = template_mode
self.results = []
self.summary = {
'total': 0,
@@ -68,6 +169,10 @@ class SVGQualityChecker:
}
self._lock_seen = False # True once we locate at least one spec_lock.md
self._source_manifest_cache: Dict[Path, Dict] = {}
+ # Template-mode aggregation (populated by check_directory when
+ # template_mode=True). Each entry is (severity, kind, message) where
+ # severity is 'error' or 'warning'. Printed in print_summary.
+ self._template_issues: List[Tuple[str, str, str]] = []
def check_file(self, svg_file: str, expected_format: str = None) -> Dict:
"""
@@ -127,11 +232,16 @@ class SVGQualityChecker:
# 6. Check image references (file existence and resolution)
self._check_image_references(content, svg_path, result)
- # 7. Check spec_lock drift (colors / font-family / font-size)
- self._check_spec_lock_drift(content, svg_path, result)
+ # 7. Check spec_lock drift (colors / font-family / font-size).
+ # Templates do not ship a spec_lock.md, so skip in template
+ # mode to avoid noise.
+ if not self.template_mode:
+ self._check_spec_lock_drift(content, svg_path, result)
- # 8. Check web-sourced image attribution
- self._check_sourced_image_attribution(content, svg_path, result)
+ # 8. Check web-sourced image attribution. Templates don't carry
+ # image_sources.json; skip in template mode.
+ if not self.template_mode:
+ self._check_sourced_image_attribution(content, svg_path, result)
# Determine pass/fail
result['passed'] = len(result['errors']) == 0
@@ -682,10 +792,14 @@ class SVGQualityChecker:
if dir_path.is_file():
svg_files = [dir_path]
else:
- svg_output = dir_path / \
- 'svg_output' if (
- dir_path / 'svg_output').exists() else dir_path
- svg_files = sorted(svg_output.glob('*.svg'))
+ if self.template_mode:
+ # Template directories live at templates/layouts/<id>/.
+ svg_files = sorted(dir_path.glob('*.svg'))
+ else:
+ svg_output = dir_path / \
+ 'svg_output' if (
+ dir_path / 'svg_output').exists() else dir_path
+ svg_files = sorted(svg_output.glob('*.svg'))
if not svg_files:
print(f"[WARN] No SVG files found")
@@ -697,8 +811,233 @@ class SVGQualityChecker:
result = self.check_file(str(svg_file), expected_format)
self._print_result(result)
+ if self.template_mode and dir_path.is_dir():
+ self._check_template_contract(dir_path, svg_files)
+
return self.results
+ def _check_template_contract(self, dir_path: Path,
+ svg_files: List[Path]) -> None:
+ """Template-mode-only checks: roster ↔ design_spec consistency and
+ per-page placeholder hints.
+
+ - **Roster mismatch (orphan / missing)** is reported as an *error*: a
+ stale roster will produce a wrong ``layouts_index.json`` entry.
+ - **Placeholder gaps** are reported as *warnings*. Templates may
+ legitimately omit conventional placeholders or swap them out (e.g.
+ ``{{CLOSING_MESSAGE}}`` instead of ``{{THANK_YOU}}``), and a content
+ variant may use a bespoke slot vocabulary. Designers can declare
+ their own per-stem expectations via ``placeholders:`` frontmatter
+ in ``design_spec.md`` to suppress these warnings explicitly.
+
+ Issues are aggregated and printed in :py:meth:`print_summary` so the
+ per-file report stays focused on intrinsic SVG validity.
+ """
+ spec_path = dir_path / 'design_spec.md'
+ spec_text = spec_path.read_text(encoding='utf-8') if spec_path.exists() else ""
+ spec_pages = self._extract_spec_roster(spec_text) if spec_text else []
+ custom_contract = self._extract_frontmatter_placeholders(spec_text) if spec_text else {}
+
+ on_disk = {p.stem for p in svg_files}
+
+ if spec_pages:
+ spec_set = set(spec_pages)
+ orphan = sorted(on_disk - spec_set)
+ missing = sorted(spec_set - on_disk)
+ for page in orphan:
+ self._template_issues.append((
+ 'error',
+ 'roster_orphan',
+ f"{page}.svg exists on disk but is not listed in design_spec.md §VI",
+ ))
+ for page in missing:
+ self._template_issues.append((
+ 'error',
+ 'roster_missing',
+ f"design_spec.md §VI lists {page} but {page}.svg is missing on disk",
+ ))
+ elif spec_path.exists():
+ # design_spec.md is present but §VI parser found nothing — surface
+ # as a warning. Legacy specs may not have an explicit roster table.
+ self._template_issues.append((
+ 'warning',
+ 'roster_unknown',
+ f"could not extract page roster from {spec_path.name}; "
+ "skipping orphan/missing checks",
+ ))
+ else:
+ self._template_issues.append((
+ 'error',
+ 'spec_missing',
+ f"{spec_path.name} not found — required for every library template",
+ ))
+
+ # Per-file placeholder coverage. Variants reuse the parent type's set
+ # (e.g. 03a_content_two_col.svg ↔ 03_content rules) unless the spec
+ # frontmatter overrides that page (custom_contract takes precedence).
+ for svg_file in svg_files:
+ expected = self._lookup_template_contract(
+ svg_file.stem, overrides=custom_contract,
+ )
+ if expected is None:
+ continue # extension pages or stems with no convention
+ try:
+ content = svg_file.read_text(encoding='utf-8')
+ except OSError:
+ continue
+ for placeholder in expected:
+ if placeholder not in content:
+ self._template_issues.append((
+ 'warning',
+ 'placeholder_hint',
+ f"{svg_file.name}: missing conventional placeholder {placeholder} "
+ "(declare 'placeholders:' frontmatter in design_spec.md to silence)",
+ ))
+
+ @staticmethod
+ def _extract_frontmatter_placeholders(spec_text: str) -> Dict[str, Tuple[str, ...]]:
+ """Read the optional ``placeholders:`` map from design_spec.md frontmatter.
+
+ Shape:
+
+ .. code-block:: yaml
+
+ placeholders:
+ 01_cover: ["{{TITLE}}", "{{BRAND_LOGO}}"]
+ 03_content: [] # explicitly assert "no expectation"
+ 03a_content_two_col: # variant-specific override
+ - "{{LEFT_TITLE}}"
+ - "{{RIGHT_TITLE}}"
+
+ Each key is a stem (full filename without ``.svg``) or page-type prefix
+ (``01_cover``). An empty list silences the default convention for that
+ stem; a populated list replaces the default. Stems / prefixes not
+ listed fall back to ``DEFAULT_PLACEHOLDER_CONVENTION``.
+
+ We parse with PyYAML when available; otherwise we fall back to a
+ minimal regex that handles the documented shape.
+ """
+ if not spec_text.startswith("---\n"):
+ return {}
+ end = spec_text.find("\n---\n", 4)
+ if end == -1:
+ return {}
+ block = spec_text[4:end]
+
+ try:
+ import yaml # type: ignore
+ except ImportError:
+ return _parse_placeholders_fallback(block)
+
+ try:
+ data = yaml.safe_load(block) or {}
+ except yaml.YAMLError:
+ return {}
+ if not isinstance(data, dict):
+ return {}
+ raw = data.get("placeholders")
+ if not isinstance(raw, dict):
+ return {}
+
+ out: Dict[str, Tuple[str, ...]] = {}
+ for stem, value in raw.items():
+ if not isinstance(stem, str):
+ continue
+ if isinstance(value, list):
+ out[stem] = tuple(str(v) for v in value)
+ elif value is None:
+ out[stem] = ()
+ return out
+
+ @staticmethod
+ def _extract_spec_roster(spec_text: str) -> List[str]:
+ """Best-effort: extract the page roster from design_spec.md.
+
+ Existing templates do not use a uniform section title — some declare a
+ formal "§VI. Page Roster" table, others bury the filenames under a
+ prose "§VII. Page Types" section as ``### N. Cover Page (01_cover.svg)``.
+ We try a focused §VI scan first, then fall back to scanning the whole
+ document for any backtick-wrapped ``<stem>.svg`` reference.
+
+ Returns the deduplicated stem list in document order. Empty result
+ means we can't determine the roster confidently — caller should treat
+ that as "skip orphan/missing checks", not as "no pages declared".
+ """
+ # Pass 1: explicit §VI section.
+ section = re.search(
+ r"^##\s+VI\.\s+(?:Page Roster|Page Structure|Pages)\b.*?(?=^##\s+|\Z)",
+ spec_text,
+ re.MULTILINE | re.DOTALL | re.IGNORECASE,
+ )
+ scope = section.group(0) if section else None
+
+ # Pass 2: full document. We *only* trust this scan when the explicit
+ # §VI scan came up empty (no `<stem>.svg` references inside it) —
+ # otherwise the explicit section's deliberate roster wins over loose
+ # mentions elsewhere.
+ if scope and re.search(r"[`\(][0-9A-Za-z_]+\.svg[`\)]", scope):
+ text = scope
+ else:
+ text = spec_text
+
+ stems: List[str] = []
+ seen: set = set()
+ # Accept backtick-quoted (`01_cover.svg`) and parenthesized
+ # (01_cover.svg) forms — existing specs use either.
+ svg_ref_re = re.compile(r"[`\(]([0-9A-Za-z_]+\.svg)[`\)]")
+ for match in svg_ref_re.finditer(text):
+ stem = match.group(1)[:-4]
+ if stem in seen or not re.match(r"^\d", stem):
+ continue
+ seen.add(stem)
+ stems.append(stem)
+
+ # If the explicit §VI scan listed bare stems (without .svg), accept
+ # those as fallback — but only when they were inside that section.
+ if not stems and scope:
+ for match in re.finditer(r"`([0-9]{2}[a-z]?_[A-Za-z0-9_]+)`", scope):
+ stem = match.group(1)
+ if stem in seen:
+ continue
+ seen.add(stem)
+ stems.append(stem)
+
+ return stems
+
+ @classmethod
+ def _lookup_template_contract(
+ cls, stem: str, *,
+ overrides: Dict[str, Tuple[str, ...]] | None = None,
+ ) -> Tuple[str, ...] | None:
+ """Resolve a SVG stem to its expected placeholder set.
+
+ Resolution order, first hit wins:
+ 1. ``overrides[stem]`` — frontmatter entry for the exact filename
+ 2. ``overrides[<page_type_prefix>]`` — frontmatter entry for the
+ variant's parent type (e.g. ``03_content`` for
+ ``03a_content_two_col``)
+ 3. ``DEFAULT_PLACEHOLDER_CONVENTION[<page_type_prefix>]``
+
+ Returns ``None`` for stems with no matching convention or override —
+ e.g. extension pages like ``05_section_break``. ``()`` (empty tuple)
+ is a valid value meaning "no expected placeholders" — used to
+ explicitly silence the default convention.
+ """
+ overrides = overrides or {}
+ if stem in overrides:
+ return overrides[stem]
+
+ # Variant convention: <NN><letter>?_<rest>; strip the letter to find
+ # the parent type prefix, e.g. "03a_content_two_col" -> "03_content".
+ match = re.match(r"^(\d{2})([a-z])?_([a-z]+)", stem)
+ if not match:
+ return None
+ num, _letter, kind = match.groups()
+ key = f"{num}_{kind}"
+ if key in overrides:
+ return overrides[key]
+ return cls.DEFAULT_PLACEHOLDER_CONVENTION.get(key)
+
def _print_result(self, result: Dict):
"""Print check result for a single file"""
if result['passed']:
@@ -758,6 +1097,9 @@ class SVGQualityChecker:
# spec_lock drift aggregation (only printed when a lock was found)
self._print_drift_summary()
+ # Template-mode aggregation (orphan/missing roster + placeholder hints)
+ self._print_template_summary()
+
# Fix suggestions
if self.summary['errors'] > 0 or self.summary['warnings'] > 0:
print(f"\n[TIP] Common fixes:")
@@ -766,6 +1108,39 @@ class SVGQualityChecker:
print(f" 3. foreignObject: Use <text> + <tspan> for manual line breaks")
print(f" 4. Font issues: end every font-family stack with a PPT-safe family (e.g. Microsoft YaHei / Arial / Consolas)")
+ def _print_template_summary(self):
+ """Aggregate template-mode roster / placeholder issues at the bottom.
+
+ Errors land under the ``errors`` summary count (so the exit signal
+ from ``main`` agrees), warnings under ``warnings``. Both are listed
+ per file so the user can act on them directly.
+ """
+ if not self._template_issues:
+ return
+
+ errors = [item for item in self._template_issues if item[0] == 'error']
+ warnings = [item for item in self._template_issues if item[0] == 'warning']
+
+ # Mirror into the global summary so downstream "0 errors" gates honor
+ # template-mode issues.
+ self.summary['errors'] += len(errors)
+ self.summary['warnings'] += len(warnings)
+ for severity, kind, _msg in self._template_issues:
+ self.issue_types[f"template_{kind}"] += 1
+
+ print("\n[TEMPLATE] Template mode checks")
+ if errors:
+ print(f" Errors ({len(errors)}):")
+ for _sev, kind, msg in errors:
+ print(f" [{kind}] {msg}")
+ if warnings:
+ print(f" Warnings ({len(warnings)}):")
+ for _sev, kind, msg in warnings:
+ print(f" [{kind}] {msg}")
+ if not errors:
+ print(" No structural roster issues. Placeholder hints above are advisory only;")
+ print(" declare 'placeholders:' frontmatter in design_spec.md to silence them.")
+
def _print_drift_summary(self):
"""Print spec_lock drift aggregation if any was observed.
@@ -851,11 +1226,19 @@ def print_usage() -> None:
print("Usage:")
print(" python3 scripts/svg_quality_checker.py <svg_file>")
print(" python3 scripts/svg_quality_checker.py <directory>")
+ print(" python3 scripts/svg_quality_checker.py <template_dir> --template-mode")
print(" python3 scripts/svg_quality_checker.py --all examples")
print("\nExamples:")
print(" python3 scripts/svg_quality_checker.py examples/project/svg_output/slide_01.svg")
print(" python3 scripts/svg_quality_checker.py examples/project/svg_output")
print(" python3 scripts/svg_quality_checker.py examples/project")
+ print(" python3 scripts/svg_quality_checker.py templates/layouts/anthropic --template-mode")
+ print("\nOptions:")
+ print(" --format <ppt169|ppt43|...> Expected canvas format")
+ print(" --template-mode Validate a templates/layouts/<id> directory:")
+ print(" glob *.svg directly, skip spec_lock checks,")
+ print(" enforce roster ↔ design_spec.md §VI consistency,")
+ print(" and emit advisory placeholder-convention warnings.")
def main() -> None:
@@ -873,7 +1256,8 @@ def main() -> None:
print_usage()
sys.exit(1)
- checker = SVGQualityChecker()
+ template_mode = '--template-mode' in sys.argv
+ checker = SVGQualityChecker(template_mode=template_mode)
# Parse arguments
target = sys.argv[1]
diff --git a/skills/ppt-master/scripts/template_import/manifest.py b/skills/ppt-master/scripts/template_import/manifest.py
index 1df5eced..4a3259f3 100644
--- a/skills/ppt-master/scripts/template_import/manifest.py
+++ b/skills/ppt-master/scripts/template_import/manifest.py
@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python3
"""Internal helper: extract lightweight template assets and style metadata from a PPTX file.
This helper is intentionally limited in scope:
@@ -8,11 +8,18 @@ This helper is intentionally limited in scope:
- produce a compact manifest for downstream template reconstruction
It does NOT try to convert arbitrary PPTX shapes into SVG templates.
+
+Output contract (single source of truth):
+ <workspace>/manifest.json — all factual metadata (theme, assets, slides, layouts, masters)
+ <workspace>/summary.md — short human-readable digest derived from manifest.json
+ <workspace>/assets/ — extracted reusable image assets
+
+This module is a pure library. The CLI entry point lives in
+``pptx_template_import.py`` at the scripts root.
"""
from __future__ import annotations
-import argparse
import json
import posixpath
import re
@@ -272,90 +279,63 @@ def choose_common_assets(asset_usage: Counter[str]) -> list[str]:
return sorted(common)
-def write_analysis(
- output_path: Path,
- pptx_name: str,
- slide_size: dict[str, int],
- theme: dict[str, Any],
- slides: list[SlideRecord],
- common_assets: list[str],
-) -> None:
- lines = [
- f"# Template Import Analysis - {pptx_name}",
+def write_summary(output_path: Path, manifest: dict[str, Any]) -> None:
+ """Render a short human digest derived from manifest.json.
+
+ This intentionally stays terse: every fact already lives in manifest.json.
+ The digest exists only so a reviewer can scan the workspace at a glance
+ without parsing JSON.
+ """
+ source_name = manifest["source"]["name"]
+ slide_size = manifest["slideSize"]
+ theme = manifest["theme"]
+ slides = manifest["slides"]
+ layouts = manifest.get("layouts", [])
+ masters = manifest.get("masters", [])
+ common_assets = manifest["assets"]["commonAssets"]
+ page_type_map = manifest.get("pageTypeCandidates", {})
+
+ lines: list[str] = [
+ f"# Template Import Summary — {source_name}",
+ "",
+ "All facts are stored in `manifest.json`; this digest is for quick scanning only.",
"",
- "## Summary",
- f"- Slide size: {slide_size['width_px']} x {slide_size['height_px']} px",
+ "## Canvas",
+ f"- Size: {slide_size['width_px']} × {slide_size['height_px']} px",
f"- Theme colors: {', '.join(sorted(theme['colors'].keys())) or 'none detected'}",
f"- Theme fonts: {', '.join(f'{k}={v}' for k, v in theme['fonts'].items()) or 'none detected'}",
- f"- Common assets: {len(common_assets)}",
"",
- "## Slide Candidates",
- ]
-
- for slide in slides:
- sample = " | ".join(slide.text_samples[:3]) if slide.text_samples else "(no text sample)"
- lines.extend(
- [
- f"- Slide {slide.index}: {slide.page_type}",
- f" - Name: {slide.name}",
- f" - Background: {slide.background_asset or 'none'} ({slide.background_source or 'n/a'})",
- f" - Images: {len(slide.image_assets)}",
- f" - Text sample: {sample}",
- ]
- )
-
- 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",
+ "## Inventory",
+ f"- Slides: {len(slides)}",
+ f"- Layouts (unique): {len(layouts)}",
+ f"- Masters (unique): {len(masters)}",
+ f"- Reusable assets (used by ≥2 parts): {len(common_assets)}",
"",
- "## Summary",
- f"- Unique layouts: {len(layouts)}",
- f"- Unique masters: {len(masters)}",
- "",
- "## Layouts",
+ "## Page-Type Candidates",
]
-
- if not layouts:
+ if page_type_map:
+ for ptype, indexes in page_type_map.items():
+ lines.append(f"- {ptype}: slides {', '.join(str(i) for i in indexes)}")
+ else:
+ lines.append("- (none classified)")
+
+ lines.extend(["", "## Layout Reuse"])
+ if layouts:
+ for layout in layouts:
+ users = layout.get("usedBySlides", [])
+ users_str = ", ".join(str(i) for i in users) if users else "n/a"
+ lines.append(f"- {layout['name']} → slides {users_str}")
+ else:
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.extend(["", "## Master Reuse"])
+ if masters:
+ for master in masters:
+ users = master.get("usedBySlides", [])
+ users_str = ", ".join(str(i) for i in users) if users else "n/a"
+ lines.append(f"- {master['name']} → slides {users_str}")
+ else:
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")
@@ -537,10 +517,8 @@ def build_manifest(pptx_path: Path, output_dir: Path) -> dict[str, Any]:
)
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],
- }
+ layouts_top = [item for item in layout_records if item]
+ masters_top = [item for item in master_records if item]
manifest = {
"source": {
@@ -554,13 +532,9 @@ 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())),
+ "layouts": layouts_top,
+ "masters": masters_top,
"slides": [
{
"index": slide.index,
@@ -580,72 +554,5 @@ def build_manifest(pptx_path: Path, output_dir: Path) -> dict[str, Any]:
],
}
- write_analysis(
- output_dir / "analysis.md",
- pptx_path.name,
- slide_size,
- theme_summary,
- 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)
+ write_summary(output_dir / "summary.md", manifest)
return manifest
-
-
-def parse_args() -> argparse.Namespace:
- parser = argparse.ArgumentParser(
- description="Extract reusable assets and style metadata from a PPTX template source."
- )
- parser.add_argument("pptx_file", help="Path to the source .pptx file")
- parser.add_argument(
- "-o",
- "--output",
- help="Output directory (default: <pptx_stem>_template_import beside the source file)",
- )
- return parser.parse_args()
-
-
-def main() -> int:
- args = parse_args()
- pptx_path = Path(args.pptx_file).expanduser().resolve()
- if not pptx_path.exists():
- print(f"Error: file does not exist: {pptx_path}")
- return 1
- if pptx_path.suffix.lower() != ".pptx":
- print(f"Error: expected a .pptx file, got: {pptx_path.name}")
- return 1
-
- output_dir = (
- Path(args.output).expanduser().resolve()
- if args.output
- else pptx_path.with_name(f"{pptx_path.stem}_template_import")
- )
- output_dir.mkdir(parents=True, exist_ok=True)
-
- try:
- manifest = build_manifest(pptx_path, output_dir)
- except Exception as exc:
- print(f"Error: failed to import template source: {exc}")
- return 1
-
- manifest_path = output_dir / "manifest.json"
- manifest_path.write_text(
- json.dumps(manifest, ensure_ascii=False, indent=2) + "\n",
- encoding="utf-8",
- )
-
- print(f"Imported PPTX template source: {pptx_path.name}")
- print(f"Output directory: {output_dir}")
- print(f"Manifest: {manifest_path.name}")
- print(f"Assets exported: {len(manifest['assets']['allAssets'])}")
- print(f"Common assets: {len(manifest['assets']['commonAssets'])}")
- print(f"Slides analyzed: {len(manifest['slides'])}")
- return 0
-
-
-if __name__ == "__main__":
- raise SystemExit(main())
diff --git a/skills/ppt-master/templates/layouts/README.md b/skills/ppt-master/templates/layouts/README.md
index f86ba7c2..f999fd5f 100644
--- a/skills/ppt-master/templates/layouts/README.md
+++ b/skills/ppt-master/templates/layouts/README.md
@@ -11,30 +11,31 @@ Pre-built PPT page layout templates supporting multiple styles and use cases.
## Quick Template Index
+<!-- quick-index:begin -->
| Template Name | Category | Use Cases | Primary Color | Design Tone |
|---------------|----------|-----------|---------------|-------------|
-| `google_style` | Brand | Annual reports, tech sharing, data presentation | Google Four Colors `#4285F4` `#EA4335` `#FBBC04` `#34A853` | Modern clean, data-driven, ample whitespace |
-| `mckinsey` | Brand | Strategic consulting, executive reports, investment analysis | McKinsey Blue `#005587` | Structured thinking, minimalist premium, MECE principle |
-| `anthropic` | Brand | AI tech sharing, developer conferences, product launches | Anthropic Orange `#D97757` | Tech-forward, conclusion-first, dark cover |
-| `china_telecom_template` | Brand | Telecom solutions, digital transformation plans,政企汇报 | Telecom Red `#C00000` | Restrained, authoritative, telecom enterprise style |
-| `中汽研_常规` | Brand | Product certification, evaluation & testing | Deep Blue `#004098` | [Standard] Professional authority, consulting style |
-| `中汽研_商务` | Brand | Business visits, technical exchanges | Blue Gradient `#003366` | [Business] Modern tech, composed and sophisticated |
-| `中汽研_现代` | Brand | Strategic launches, future tech | Deep Blue `#001529` | [Future] Future Tech, neon glow |
-| `中国电建_常规` | Brand | Power & energy, engineering, state-owned enterprise reports | PowerChina Blue `#00418D` | Craftsmanship, steady and reliable |
-| `中国电建_现代` | Brand | International engineering, premium roadshows, tech innovation | Deep Sea Blue `#001F45` | [Modern] Grand narrative, digital tech |
-| `招商银行` | Brand | Premium reports, VIP services, annual reports | CMB Red `#C41230` | Minimalist luxury, financial texture, borderless |
-| `exhibit` | General | Exhibit-driven strategic reports, executive presentations, board briefings | Gradient top bar + Gold accents | Conclusion-first, data-driven, confidential |
-| `academic_defense` | Scenario | Thesis defense, academic reports, grant proposals | Deep Blue + Red accents | Clear hierarchy, academic standards |
-| `psychology_attachment` | Scenario | Psychotherapy training, counseling lectures | Blue-green gradient + Colorful semantic colors | Warm professional, therapeutic feel |
-| `medical_university` | Scenario | Medical reports, case discussions, research presentations | Medical Blue `#0066B3` | Professional rigorous, life-affirming |
-| `government_red` | Government/Enterprise | Government work reports, party-building presentations | Government Red `#8B0000` | Solemn authority, grand and imposing |
-| `government_blue` | Government/Enterprise | Smart cities, open governance, digital transformation | Tech Blue `#0050B3` | Modern tech, rigorous and rational |
-| `ai_ops` | Government/Enterprise | Telecom AI ops, IT system overview, digital intelligence solutions | Telecom Red `#C00000` + Blue `#2E75B6` | High information density, modular layout, telecom style |
-| `pixel_retro` | Special | Git/tech introductions, retro gaming themes | Neon colors `#00FF41` `#FF0080` | Pixel art, cyberpunk |
-| `科技蓝商务` | General | Corporate reports, product launches, proposals | Tech Blue `#0078D7` | Tech, business, professional, clean |
-| `smart_red` | General | Tech company profiles, education solutions | Smart Red-Orange `#DE3545` | Modern, vibrant, geometric |
-| `重庆大学` | Scenario | Academic defense, research presentations | CQU Blue `#006BB7` | Academic solidity, mountain-city character |
----
+| `academic_defense` | General | Thesis defense, academic presentations, research progress reports, grant applications | `#003366` | Professional, rigorous, research-oriented, clear hierarchy |
+| `ai_ops` | General | Telecom AI operations architecture, IT system overviews, digital transformation proposals, smart infrastructure reports | `#C00000` | Information-dense, structured, modular zoning, telecom/enterprise style |
+| `anthropic` | General | AI tech talks, developer conferences, technical training, product launches | `#D97757` | Tech-forward, professional, modern, conclusion-first |
+| `china_telecom_template` | General | China Telecom related briefings, 政企数字化方案, 转型规划, 内部汇报 | `#C00000` | Authoritative, structured, restrained, enterprise-government hybrid |
+| `exhibit` | General | Strategic planning, executive reports, investment analysis, board presentations | `#0D1117` | Premium, refined, authoritative, data-driven, conclusion-first |
+| `google_style` | General | Annual work reports, technical sharing, project showcases, data-driven presentations | `#4285F4` | Professional, modern, clean and restrained, data-driven, generous whitespace |
+| `government_blue` | General | Key project briefings, Five-Year Plan presentations, work summaries, investment promotion, policy interpretation | `#0050B3` | Grand, tech-forward, modern, professional government style |
+| `government_red` | General | Government briefings, policy interpretation, work summaries, project introductions, investment promotion | `#8B0000` | Authoritative, dignified, professional, modern government style |
+| `mckinsey` | General | Strategic consulting, executive briefings, investment analysis, business proposals | `#005587` | Data-driven, structured thinking, professional whitespace, minimalist premium |
+| `medical_university` | General | Medical academic reports, case discussions, research presentations, hospital work reports, medical education and training | `#0066B3` | Professional, rigorous, life-affirming, tech-forward, trustworthy |
+| `pixel_retro` | General | Tech talks, programming tutorials, game introductions, geek-style showcases | `#0D1117` | Retro gaming, neon cyberpunk, geek tech, 8-bit style |
+| `psychology_attachment` | General | Psychotherapy training, academic lectures, counseling case analysis, professional sharing | `#2E5C8E` | Professional, warm, healing, trustworthy |
+| `smart_red` | General | Company introductions, product launches, solution presentations, education industry courseware | `#DE3545` | Modern, energetic, professional, geometric |
+| `中国电建_常规` | General | Engineering project reports, technical proposal presentations, business negotiations, corporate promotion, annual summaries | `#00418D` | Professional, composed, international, state-owned enterprise style |
+| `中国电建_现代` | General | Major engineering reports, international market promotion, technology achievement showcases, high-end business negotiations | `#00418D` | Grand narrative, modern precision, digital tech, international vision |
+| `中汽研_商务` | General | Product certification display, evaluation presentations, technology promotion, high-end business reporting | `#003366` | Modern tech, authoritative & professional, composed & grand |
+| `中汽研_常规` | General | Product certification display, evaluation presentations, technology promotion, business visits | `#004098` | Professional, authoritative, trustworthy, consulting style |
+| `中汽研_现代` | General | Forward-looking technology showcases, strategic releases, high-end business reporting | `#001529` | Futuristic, tech-forward, deep & refined |
+| `招商银行` | General | 交易银行产品介绍、销售收款方案汇报、客户案例拆解、分行培训材料 | `#C8152D` | Brand-consistent, structured, product-focused, refined finance |
+| `科技蓝商务` | General | Corporate reports, product launches, proposals, process standards, training materials | `#0078D7` | Tech, business, professional, clean |
+| `重庆大学` | General | Academic defense, research reports, teaching presentations, scholarly exchange | `#006BB7` | Academically grounded · Mountain City charm · Modern minimalism |
+<!-- quick-index:end -->
## Template Categories
diff --git a/skills/ppt-master/templates/layouts/layouts_index.json b/skills/ppt-master/templates/layouts/layouts_index.json
index 19d65fd1..bdc9b663 100644
--- a/skills/ppt-master/templates/layouts/layouts_index.json
+++ b/skills/ppt-master/templates/layouts/layouts_index.json
@@ -1,12 +1,12 @@
{
"academic_defense": {
- "label": "Academic Defense Template",
- "summary": "A standard template for academic defenses, research presentations, and project proposals",
+ "label": "academic_defense",
+ "summary": "For Thesis defense, academic presentations, research progress reports, grant applications.",
"keywords": [
- "Academic",
- "Defense",
- "Research",
- "Standard"
+ "Professional",
+ "rigorous",
+ "research-oriented",
+ "clear hierarchy"
],
"pages": [
"01_cover",
@@ -17,31 +17,32 @@
]
},
"ai_ops": {
- "label": "Enterprise Digital Intelligence Template",
- "summary": "For high-density scenarios such as telecom AI operations architecture, IT system overview, and digital transformation plans",
+ "label": "Enterprise Digital Intelligence",
+ "summary": "For Telecom AI operations architecture, IT system overviews, digital transformation proposals, smart infrastructure reports.",
"keywords": [
- "Telecom",
- "AI operations",
- "Digital intelligence",
- "High density",
- "Architecture view"
+ "Information-dense",
+ "structured",
+ "modular zoning",
+ "telecom",
+ "enterprise style"
],
"pages": [
"01_cover",
"02_chapter",
"02_toc",
"03_content",
- "04_ending"
+ "04_ending",
+ "reference_style"
]
},
"anthropic": {
"label": "Anthropic Style Template",
- "summary": "A tech-oriented template for AI/LLM knowledge sharing and product launches",
+ "summary": "For AI tech talks, developer conferences, technical training, product launches.",
"keywords": [
- "AI",
- "LLM",
- "Developer",
- "Technology"
+ "Tech-forward",
+ "professional",
+ "modern",
+ "conclusion-first"
],
"pages": [
"01_cover",
@@ -53,13 +54,12 @@
},
"china_telecom_template": {
"label": "中国电信模板",
- "summary": "A China Telecom style template for telecom solution proposals, digital transformation plans, and government-enterprise briefings",
+ "summary": "For China Telecom related briefings, 政企数字化方案, 转型规划, 内部汇报.",
"keywords": [
- "China Telecom",
- "Telecom",
- "Digital transformation",
- "Government-enterprise",
- "Briefing"
+ "Authoritative",
+ "structured",
+ "restrained",
+ "enterprise-government hybrid"
],
"pages": [
"01_cover",
@@ -71,13 +71,13 @@
},
"exhibit": {
"label": "Exhibit Style Template",
- "summary": "Conclusion-first layout with Exhibit takeaway bars for data-driven strategic reports and executive presentations",
+ "summary": "For Strategic planning, executive reports, investment analysis, board presentations.",
"keywords": [
- "Exhibit",
- "Board",
- "Executive",
- "Strategy",
- "Conclusion-first"
+ "Premium",
+ "refined",
+ "authoritative",
+ "data-driven",
+ "conclusion-first"
],
"pages": [
"01_cover",
@@ -89,12 +89,13 @@
},
"google_style": {
"label": "Google Style Template",
- "summary": "A Google-branded template for annual reports and technical sharing",
+ "summary": "For Annual work reports, technical sharing, project showcases, data-driven presentations.",
"keywords": [
- "Google",
- "Brand style",
- "Technical sharing",
- "Annual report"
+ "Professional",
+ "modern",
+ "clean and restrained",
+ "data-driven",
+ "generous whitespace"
],
"pages": [
"01_cover",
@@ -106,12 +107,12 @@
},
"government_blue": {
"label": "Government Blue Template",
- "summary": "A blue government-themed template for smart governance and digital transformation reports",
+ "summary": "For Key project briefings, Five-Year Plan presentations, work summaries, investment promotion, policy interpretation.",
"keywords": [
- "Government affairs",
- "Government blue",
- "Smart city",
- "Digitalization"
+ "Grand",
+ "tech-forward",
+ "modern",
+ "professional government style"
],
"pages": [
"01_cover",
@@ -123,12 +124,12 @@
},
"government_red": {
"label": "Government Red Template",
- "summary": "A red government-themed template for government reports and party-building scenarios",
+ "summary": "For Government briefings, policy interpretation, work summaries, project introductions, investment promotion.",
"keywords": [
- "Government affairs",
- "Party building",
- "Government red",
- "Authoritative"
+ "Authoritative",
+ "dignified",
+ "professional",
+ "modern government style"
],
"pages": [
"01_cover",
@@ -140,12 +141,12 @@
},
"mckinsey": {
"label": "McKinsey Style Template",
- "summary": "A McKinsey-style template for strategic consulting and investment analysis",
+ "summary": "For Strategic consulting, executive briefings, investment analysis, business proposals.",
"keywords": [
- "McKinsey",
- "Consulting",
- "Structured",
- "Executive presentation"
+ "Data-driven",
+ "structured thinking",
+ "professional whitespace",
+ "minimalist premium"
],
"pages": [
"01_cover",
@@ -156,13 +157,14 @@
]
},
"medical_university": {
- "label": "Hospital/Medical University Template",
- "summary": "A professional template for medical reports, case discussions, and research presentations",
+ "label": "Hospital / Medical University Template",
+ "summary": "For Medical academic reports, case discussions, research presentations, hospital work reports, medical education and training.",
"keywords": [
- "Medical",
- "Hospital",
- "Case study",
- "Research"
+ "Professional",
+ "rigorous",
+ "life-affirming",
+ "tech-forward",
+ "trustworthy"
],
"pages": [
"01_cover",
@@ -174,12 +176,12 @@
},
"pixel_retro": {
"label": "Pixel Retro Template",
- "summary": "A pixel-art template for tech sharing and gaming-themed content",
+ "summary": "For Tech talks, programming tutorials, game introductions, geek-style showcases.",
"keywords": [
- "Pixel art",
"Retro gaming",
- "Cyberpunk",
- "Technology"
+ "neon cyberpunk",
+ "geek tech",
+ "8-bit style"
],
"pages": [
"01_cover",
@@ -191,12 +193,12 @@
},
"psychology_attachment": {
"label": "Psychology Healing Template",
- "summary": "A warm and professional template for psychotherapy training and counseling lectures",
+ "summary": "For Psychotherapy training, academic lectures, counseling case analysis, professional sharing.",
"keywords": [
- "Psychology",
- "Healing",
- "Counseling",
- "Warm"
+ "Professional",
+ "warm",
+ "healing",
+ "trustworthy"
],
"pages": [
"01_cover",
@@ -207,13 +209,13 @@
]
},
"smart_red": {
- "label": "Smart Red-Orange Business Template",
- "summary": "A vibrant business template for tech company introductions and education solutions",
+ "label": "Smart Red-Orange Business Style",
+ "summary": "For Company introductions, product launches, solution presentations, education industry courseware.",
"keywords": [
- "Red-orange business",
- "Tech enterprise",
- "Education",
- "Vibrant"
+ "Modern",
+ "energetic",
+ "professional",
+ "geometric"
],
"pages": [
"01_cover",
@@ -224,13 +226,13 @@
]
},
"中国电建_常规": {
- "label": "PowerChina Standard Template",
- "summary": "A solid brand template for engineering construction and state-owned enterprise reports",
+ "label": "formerly powerchina",
+ "summary": "For Engineering project reports, technical proposal presentations, business negotiations, corporate promotion, annual summaries.",
"keywords": [
- "PowerChina",
- "State-owned enterprise",
- "Engineering",
- "Energy"
+ "Professional",
+ "composed",
+ "international",
+ "state-owned enterprise style"
],
"pages": [
"01_cover",
@@ -241,13 +243,13 @@
]
},
"中国电建_现代": {
- "label": "PowerChina Modern Template",
- "summary": "A modern engineering template for major projects and international business presentations",
+ "label": "formerly powerchina_v2",
+ "summary": "For Major engineering reports, international market promotion, technology achievement showcases, high-end business negotiations.",
"keywords": [
- "PowerChina",
- "International engineering",
- "Modern engineering",
- "Technology"
+ "Grand narrative",
+ "modern precision",
+ "digital tech",
+ "international vision"
],
"pages": [
"01_cover",
@@ -258,13 +260,12 @@
]
},
"中汽研_商务": {
- "label": "CATARC Business Template",
- "summary": "A CATARC brand template for certification showcase and high-end business presentations",
+ "label": "formerly zhongqiyan_v2",
+ "summary": "For Product certification display, evaluation presentations, technology promotion, high-end business reporting.",
"keywords": [
- "CATARC",
- "Certification",
- "Business",
- "Technology"
+ "Modern tech",
+ "authoritative & professional",
+ "composed & grand"
],
"pages": [
"01_cover",
@@ -275,13 +276,13 @@
]
},
"中汽研_常规": {
- "label": "CATARC Standard Template",
- "summary": "A standard CATARC template for certification and testing scenarios",
+ "label": "formerly zhongqiyan",
+ "summary": "For Product certification display, evaluation presentations, technology promotion, business visits.",
"keywords": [
- "CATARC",
- "Certification",
- "Testing",
- "Authoritative"
+ "Professional",
+ "authoritative",
+ "trustworthy",
+ "consulting style"
],
"pages": [
"01_cover",
@@ -292,13 +293,12 @@
]
},
"中汽研_现代": {
- "label": "CATARC Modern Template",
- "summary": "A futuristic tech template for cutting-edge technology showcase and premium launches",
+ "label": "CATARC_Modern_Tech",
+ "summary": "For Forward-looking technology showcases, strategic releases, high-end business reporting.",
"keywords": [
- "CATARC",
- "Future tech",
- "Cutting-edge technology",
- "Launch event"
+ "Futuristic",
+ "tech-forward",
+ "deep & refined"
],
"pages": [
"01_cover",
@@ -309,14 +309,13 @@
]
},
"招商银行": {
- "label": "China Merchants Bank Transaction Banking Template",
- "summary": "A transaction-banking template for sales collection solutions, product pitches, and branch training",
+ "label": "招商银行",
+ "summary": "For 交易银行产品介绍、销售收款方案汇报、客户案例拆解、分行培训材料.",
"keywords": [
- "China Merchants Bank",
- "Transaction banking",
- "Sales collection",
- "Finance",
- "Training"
+ "Brand-consistent",
+ "structured",
+ "product-focused",
+ "refined finance"
],
"pages": [
"01_cover",
@@ -327,13 +326,13 @@
]
},
"科技蓝商务": {
- "label": "Tech Blue Business Template",
- "summary": "A tech-business template for corporate reports and solution proposals",
+ "label": "科技蓝商务 / tech_blue_business",
+ "summary": "For Corporate reports, product launches, proposals, process standards, training materials.",
"keywords": [
- "Tech blue",
- "Business",
- "Solution proposal",
- "Corporate report"
+ "Tech",
+ "business",
+ "professional",
+ "clean"
],
"pages": [
"01_cover",
@@ -344,13 +343,10 @@
]
},
"重庆大学": {
- "label": "Chongqing University Template",
- "summary": "A university-exclusive template for academic defenses and research presentations",
+ "label": "重庆大学",
+ "summary": "For Academic defense, research reports, teaching presentations, scholarly exchange.",
"keywords": [
- "Chongqing University",
- "Academic",
- "Defense",
- "University"
+ "Academically grounded · Mountain City charm · Modern minimalism"
],
"pages": [
"01_cover",
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index 6a2519c2..dd3a2aa8 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -52,6 +52,8 @@ Items to confirm with the user:
| Assets list | Optional | Logos / background textures / reference images to include in the template package |
| Keywords | Yes | 3–5 short tags for `layouts_index.json` lookup (e.g., `McKinsey`, `Consulting`, `Structured`) |
+> **Persist the brief into `design_spec.md`**. When the Template_Designer writes `design_spec.md` in Step 3, declare a YAML frontmatter block at the top with the confirmed brief (`template_id`, `label`, `category`, `summary`, `keywords`, `primary_color`, `canvas_format`, `replication_mode`, etc.). `register_template.py` reads this in Step 5, so the brief flows directly into the index without the AI re-deriving it from prose. See Step 5 for the recommended frontmatter shape.
+
**Required outcome of Step 1** (all must be true before emitting `[TEMPLATE_BRIEF_CONFIRMED]`):
- [ ] User has been asked the Required items above in the current conversation
@@ -75,38 +77,41 @@ python3 skills/ppt-master/scripts/pptx_template_import.py "<reference_template.p
This helper reads OOXML directly via `pptx_to_svg` and produces, in one workspace:
-- `manifest.json` — slide size, theme colors, fonts, asset inventory
-- `analysis.md` — page-type guidance summary
-- `master_layout_refs.json` / `master_layout_analysis.md` — master/layout structure and inheritance
+- `manifest.json` — single source of truth: slide size, theme colors, fonts, asset inventory, per-slide / per-layout / per-master metadata, page-type candidates
+- `summary.md` — short human-readable digest derived from manifest.json (for quick scanning only)
- `assets/` — extracted reusable image assets
-- `svg/` — shape-level SVG per slide (real `<text>`, `<image>`, geometry)
+- `svg/` — shape-level SVG, **layered by default**:
+ - `svg/master_*.svg` — each unique slide master rendered once (decorative / structural shapes, no placeholders)
+ - `svg/layout_*.svg` — each unique slide layout rendered once (its own contribution; master shapes do **not** repeat here)
+ - `svg/slide_NN.svg` — each slide's own shapes; master / layout shapes are **not** inlined
+ - `svg/inheritance.json` — which layout & master each slide consumes
+ - Pass `--inheritance-mode flat` only when you specifically want self-contained slide SVGs (round-trip use cases). The default is `layered` because every slide otherwise repeats the same master decoration, which makes it hard to tell what is shared vs. unique.
It is a reconstruction aid, not a final direct template conversion.
When the reference source is `.pptx`, use the following internal priority order during template creation:
-1. `manifest.json`
-2. `master_layout_refs.json`
-3. `master_layout_analysis.md`
-4. `analysis.md`
-5. exported `assets/`
-6. cleaned slide SVG references from `svg/`
+1. `manifest.json` (factual metadata: slide size, theme, assets, layouts, masters, slide page-types)
+2. `svg/master_*.svg` and `svg/layout_*.svg` — read these **before** any slide SVG; they show the deck's shared visual language (background, headers, footers, decorative bars). This is what the new template's fixed structure should adapt from.
+3. `svg/inheritance.json` — confirms which slide uses which layout/master
+4. exported `assets/`
+5. cleaned slide SVG references `svg/slide_NN.svg` — content unique to each slide; consult after the master/layout language is understood
+6. `summary.md` only as a quick orientation aid
7. 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
+- `manifest.json` is the source of truth for slide size, theme colors, fonts, background inheritance, reusable asset inventory, unique layout/master structure, and slide reuse relationships
+- `summary.md` is a quick scan; never treat it as the canonical fact source — go back to `manifest.json` if anything is unclear
- exported `assets/` are the canonical reusable image pool — `<image>` references in `svg/` already point at these files directly
-- cleaned `svg/` slides are mandatory reference material for layout rhythm, page composition, and fixed decorative structure; read **every** exported page regardless of slide count
+- `svg/master_*.svg` / `svg/layout_*.svg` are the **primary source for fixed structural design** — recurring backgrounds, page chrome, decorative motifs that the template should preserve. The new template's `01_cover` / `02_chapter` / `03_content` / `04_ending` typically inherit elements from these layers.
+- `svg/slide_NN.svg` shows page-specific content — useful for judging composition rhythm and content density, not for fixed structure. Read every slide regardless of count.
- screenshots remain useful for judging composition and style, but should not override extracted factual metadata unless the import result is clearly incomplete
**Hard gate**:
-- Before creating any template file, the agent MUST finish reading every SVG file under `<import_workspace>/svg/`
-- The agent MUST explicitly report the read slide indexes before starting template generation
+- Before creating any template file, the agent MUST finish reading every `svg/master_*.svg`, `svg/layout_*.svg`, and `svg/slide_*.svg` file under `<import_workspace>/svg/`
+- The agent MUST explicitly report the read master / layout / slide filenames before starting template generation
Do **not** treat the imported PPTX or exported slide SVGs as direct final template assets. The goal is to reconstruct a clean, maintainable PPT Master template package, not to perform 1:1 shape translation.
@@ -134,9 +139,7 @@ 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`
+- `summary.md` (orientation only)
- exported `assets/`
- cleaned slide SVG references from `svg/`
- optional screenshots, if available
@@ -147,22 +150,12 @@ The role should use the import output to anchor objective facts such as theme co
**Sprite-sheet preservation (do NOT simplify away)**: PPTX-exported assets are often sprite sheets — a single tall/large image referenced from multiple slides, each cropping a different region via nested `<svg ... viewBox="...">` wrappers around `<image width="1" height="1">`. This nesting is **load-bearing geometry**, not redundant structure. When rebuilding, preserve the exact `viewBox` crop and the outer `<svg>` placement for every image; do not flatten to a single `<image>` with direct `x/y/width/height`. Verify by sampling: if any asset's pixel dimensions don't match the on-page display aspect, it is a sprite and the wrapper must stay.
-1. **design_spec.md** — Design specification document, with §VI listing the page roster
-2. **Page roster** — `standard` mode: `01_cover`, `02_chapter`, `03_content`, `04_ending`; `fidelity` mode: standard set + variant pages (`02a_chapter_*`, `03a_content_*`, ...) and extension pages (`05_section_break`, `06_appendix`, ...) per `manifest.json` clusters
-3. **TOC page (optional)** — `02_toc.svg`
-4. **Template assets (optional)** — Logos / PNG / JPG / reference SVG needed by the template package
-
-> **Role details**: See [template-designer.md](../references/template-designer.md)
-
-**New-template placeholder contract (mandatory for newly created library templates)**:
-
-- Cover: `{{TITLE}}`, `{{SUBTITLE}}`, `{{DATE}}`, `{{AUTHOR}}`
-- Chapter: `{{CHAPTER_NUM}}`, `{{CHAPTER_TITLE}}`
-- Content: `{{PAGE_TITLE}}`, `{{CONTENT_AREA}}`, `{{PAGE_NUM}}`
-- Ending: `{{THANK_YOU}}`, `{{CONTACT_INFO}}`
-- TOC: use indexed placeholders such as `{{TOC_ITEM_1_TITLE}}` and optional `{{TOC_ITEM_1_DESC}}`
+**Expected outputs from this step** (full spec → [template-designer.md](../references/template-designer.md)):
-**Avoid** introducing one-off placeholder families such as `{{CHAPTER_01_TITLE}}` for new templates. If an extension placeholder is truly required, define it explicitly in `design_spec.md` and keep the naming pattern consistent.
+1. `design_spec.md` (with §VI page roster matching the actual SVG files; declare brief frontmatter for `register_template.py`)
+2. Page roster — see [Page Roster](../references/template-designer.md#page-roster) for `standard` vs `fidelity` mode, variant naming, and TOC handling
+3. Placeholder vocabulary — pages should adopt the conventional names (`{{TITLE}}`, `{{CONTENT_AREA}}`, ...) when they fit. Full reference: [Placeholder Reference](../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template). When a template style legitimately needs different vocabulary (consulting → `{{KEY_MESSAGE}}`, branded cover → `{{BRAND_LOGO}}`), declare a `placeholders:` block in `design_spec.md` frontmatter so the registrar and quality checker treat it as the template's authoritative contract. **Avoid** one-off indexed families such as `{{CHAPTER_01_TITLE}}` — use the indexed TOC pattern instead.
+4. Template assets (optional) — Logos / PNG / JPG / reference SVG bundled with the template package
---
@@ -175,17 +168,24 @@ ls -la "skills/ppt-master/templates/layouts/<template_id>"
Run SVG validation on the template directory:
```bash
-python3 skills/ppt-master/scripts/svg_quality_checker.py "skills/ppt-master/templates/layouts/<template_id>" --format <canvas_format>
+python3 skills/ppt-master/scripts/svg_quality_checker.py "skills/ppt-master/templates/layouts/<template_id>" --template-mode --format <canvas_format>
```
+`--template-mode` makes the checker:
+
+- glob `*.svg` in the template directory directly (templates do not live under `svg_output/`)
+- skip `spec_lock.md` drift checks (templates do not ship a spec_lock)
+- enforce roster ↔ `design_spec.md` consistency as **errors** (orphan files / missing files break `layouts_index.json`)
+- emit advisory **warnings** when a page lacks a conventional placeholder — these are hints, not failures. Declare a `placeholders:` block in `design_spec.md` frontmatter to silence them when your template intentionally uses a different vocabulary
+
**Checklist**:
- [ ] `design_spec.md` contains complete design specification, with §VI listing every emitted page
- [ ] Every page declared in `design_spec.md §VI` exists as an SVG file in the template directory (and vice versa — no orphan files)
-- [ ] Variant filenames follow the letter-suffix convention (e.g. `03a_content_two_col.svg`); variants reuse the parent type's placeholder set
+- [ ] Variant filenames follow the letter-suffix convention (e.g. `03a_content_two_col.svg`); variants typically reuse the parent type's placeholder set unless the spec frontmatter declares otherwise
- [ ] If TOC exists, placeholder pattern uses the canonical indexed form
- [ ] SVG viewBox matches the chosen canvas format (for `ppt169`: `0 0 1280 720`)
-- [ ] Placeholder names are consistent with the new-template contract and `design_spec.md`
+- [ ] Placeholder names follow the canonical convention where applicable; templates with intentionally different vocabularies (e.g. `{{KEY_MESSAGE}}` instead of `{{PAGE_TITLE}}`) should declare a `placeholders:` frontmatter block to silence advisory warnings
- [ ] Asset files referenced by SVGs actually exist in the template package
- [ ] For `fidelity` mode: every sprite-sheet asset retains its nested `<svg viewBox=...>` crop wrapper; no image whose file aspect differs from its on-page aspect was flattened to a bare `<image>`
@@ -195,46 +195,80 @@ This step is a **hard gate**. Do not register the template into the library inde
## Step 5: Register Template in Library Index
-Add a top-level entry to `skills/ppt-master/templates/layouts/layouts_index.json`. The file is a flat map of `template_id → { label, summary, keywords, pages }`:
+Run the unified registrar; it derives the `layouts_index.json` entry and refreshes the `README.md` Quick Index from `design_spec.md` (frontmatter when present, §I / §III tables otherwise) plus the actual SVG file list:
-```json
-"<template_id>": {
- "label": "<Human-readable Name>",
- "summary": "<One-sentence description of what this template is for>",
- "keywords": ["<Tag1>", "<Tag2>", "<Tag3>"],
- "pages": ["01_cover", "02_chapter", "02_toc", "03_content", "04_ending"]
-}
+```bash
+python3 skills/ppt-master/scripts/register_template.py <template_id>
```
-`pages` lists every layout SVG (without the `.svg` suffix) the template ships, so downstream consumers can see the full roster — especially for `fidelity`-mode templates that include variant pages such as `03a_content_two_col`.
+Outputs:
-`layouts_index.json` is the lightweight lookup used when a user explicitly opts into the template flow. The main workflow defaults to free design and does not read this file unless a template trigger fires (see `SKILL.md` Step 3). A template directory that is not registered here will not be discoverable by that flow.
+- updates `skills/ppt-master/templates/layouts/layouts_index.json` — the flat `template_id → { label, summary, keywords, pages }` map
+- refreshes the auto-managed Quick Index inside `skills/ppt-master/templates/layouts/README.md` (the surrounding category sections stay hand-edited)
+- prints a "Template Creation Complete" card you can use directly for Step 6
-Also sync the summary table in `templates/layouts/README.md` (the human-facing index with categories, primary colors, and detailed tone).
+`pages` is collected by globbing `*.svg` in the template directory, so `fidelity`-mode templates that include variant pages such as `03a_content_two_col` are listed automatically.
+
+`layouts_index.json` is the lightweight lookup used when a user explicitly opts into the template flow. The main workflow defaults to free design and does not read this file unless a template trigger fires (see `SKILL.md` Step 3). A template directory that has not been run through `register_template.py` will not be discoverable by that flow.
+
+> **Recommended for new templates**: declare a YAML frontmatter block at the top of `design_spec.md`. The registrar prefers it over the §I table and lets you set `category`, `keywords`, `summary`, etc. without relying on prose extraction:
+>
+> ```yaml
+> ---
+> template_id: my_template
+> label: My Template
+> category: brand # brand | general | scenario | government | special
+> summary: For ...
+> keywords: [tag1, tag2, tag3]
+> primary_color: "#005587"
+> canvas_format: ppt169
+> replication_mode: standard
+> # Optional: per-page placeholder overrides. Templates that legitimately
+> # use a different vocabulary (e.g. consulting decks with {{KEY_MESSAGE}}
+> # in place of {{PAGE_TITLE}}, or content variants with bespoke slots)
+> # should declare them here so svg_quality_checker --template-mode does
+> # not flag them as conventional-placeholder gaps.
+> placeholders:
+> 01_cover: ["{{TITLE}}", "{{SUBTITLE}}", "{{BRAND_LOGO}}"]
+> 03_content: ["{{KEY_MESSAGE}}", "{{CONTENT_AREA}}"]
+> 03a_content_dual_col: [] # silences hints for this variant entirely
+> ---
+> ```
+
+> To rebuild every entry at once (e.g. after editing many specs), run:
+>
+> ```bash
+> python3 skills/ppt-master/scripts/register_template.py --rebuild-all
+> ```
+
+If you need to update the categorized sections lower in `README.md` (Brand Style Templates / General Style Templates / etc.), edit those by hand — the registrar deliberately leaves them alone so curated descriptions are preserved.
---
## Step 6: Output Confirmation
+`register_template.py` already printed a "Template Creation Complete" card during Step 5 — copy it verbatim into the conversation. The card includes the template name, path, category, primary color, index status, and the full SVG file roster (auto-collected from disk, so `fidelity`-mode variant pages and TOC pages are listed correctly without manual editing).
+
+For a standard-mode template the card looks like:
+
```markdown
## Template Creation Complete
**Template Name**: <template_id> (<display_name>)
-**Template Path**: `skills/ppt-master/templates/layouts/<template_id>/`
+**Template Path**: `templates/layouts/<template_id>/`
**Category**: <category>
-**Canvas Format**: <canvas_format>
+**Primary Color**: <hex>
**Index Registration**: Done
### Files Included
| File | Status |
|------|--------|
-| `design_spec.md` | Done |
| `01_cover.svg` | Done |
| `02_chapter.svg` | Done |
+| `02_toc.svg` | Done |
| `03_content.svg` | Done |
| `04_ending.svg` | Done |
-| `02_toc.svg` | Optional |
```
---
@@ -252,9 +286,9 @@ Also sync the summary table in `templates/layouts/README.md` (the human-facing i
## Notes
-1. **SVG technical constraints**: See the technical constraints section in [template-designer.md](../references/template-designer.md)
-2. **Color consistency**: All SVG files must use the same color scheme
-3. **Placeholder convention**: Use `{{}}` format and the canonical new-template placeholder contract above
-4. **Discovery requirement**: New templates must be added to `layouts_index.json`, otherwise they will not be discoverable when a user opts into the template flow
+1. **SVG technical constraints**: See [template-designer.md → SVG Technical Constraints](../references/template-designer.md)
+2. **Color consistency**: All SVG files must use the same color scheme as `design_spec.md §III`
+3. **Placeholder convention**: `{{}}` format only; default names listed in [Placeholder Reference](../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template). Override per template via `placeholders:` frontmatter when needed.
+4. **Discovery requirement**: A template directory is only discoverable after `register_template.py` has been run against it (Step 5)
-> **Detailed specification**: See [template-designer.md](../references/template-designer.md)
+> **Full role specification**: [template-designer.md](../references/template-designer.md)