Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

fix(slide-order): sort SVG rosters numerically

hugohe367adbc6e9228
diff --git a/docs/rules/code-style.md b/docs/rules/code-style.md
index 4312d29c..b9b3fc50 100644
--- a/docs/rules/code-style.md
+++ b/docs/rules/code-style.md
@@ -222,6 +222,7 @@ Common functionality lives in these designated submodules. New scripts use these
| [`image_backends/backend_common.py`](../../skills/ppt-master/scripts/image_backends/backend_common.py) | HTTP download, retry, image format detection, save-with-Pillow-transcode |
| [`image_sources/provider_common.py`](../../skills/ppt-master/scripts/image_sources/provider_common.py) | License classification, query simplification, scoring, attribution text, dataclasses |
| [`project_utils.py`](../../skills/ppt-master/scripts/project_utils.py) | Canvas formats, project path conventions |
+| [`slide_roster.py`](../../skills/ppt-master/scripts/slide_roster.py) | Numeric slide-filename ordering and SVG roster discovery |
| [`error_helper.py`](../../skills/ppt-master/scripts/error_helper.py) | User-facing error message templates |
| [`console_encoding.py`](../../skills/ppt-master/scripts/console_encoding.py) | `configure_utf8_stdio()` — force UTF-8 console for CLI entries (§4) |
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index a2f1d197..82687a8f 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -222,9 +222,7 @@ redirect, loop, or batch helper output into `svg_output/`.
### SVG File Naming Convention
-Format: `<NN>_<page_name>.svg` (two-digit number from 01; name matches the deck's language and the page title in the Design Spec).
-
-Examples: `01_封面.svg` / `02_目录.svg` / `03_核心优势.svg`; `01_cover.svg` / `02_agenda.svg` / `03_key_benefits.svg`.
+Format: `<index>_<page_name>.svg`. Use one roster-wide zero-padded index width sized for the Design Spec §IX roster, such as `01_cover.svg` through `12_end.svg` or `001_cover.svg` through `120_end.svg`; match the deck language and page title.
---
diff --git a/skills/ppt-master/references/executor-structured.md b/skills/ppt-master/references/executor-structured.md
index 88f82840..312b6748 100644
--- a/skills/ppt-master/references/executor-structured.md
+++ b/skills/ppt-master/references/executor-structured.md
@@ -56,7 +56,7 @@ When `spec_lock.md` records the AI-derived `template_reuse_scope: mirror`, Execu
4. **What you must not touch** — element positions, sizes, fonts, colors, fills, strokes, gradients, **which image each `<image>` points at**, `<g>` grouping, sprite-sheet `<svg viewBox>` wrappers, decorative `<rect>` / `<path>` / `<circle>` / `<polygon>` shapes, `<use data-icon="...">` markers, embedded chart data structures. Mirror's value is preserving the source deck's visual identity — any geometric / decorative drift defeats the purpose. **The `href` path is not the image**: normalizing a bare `href="cover_bg.png"` to `href="../images/<name>"` (when Step 3 relocated the asset to `images/`) points at the *same* image and changes nothing visual — that is an allowed path fix, not a fidelity edit. Leaving the bare href as-is is also fine; the exporter and live preview resolve bare hrefs against `images/` either way.
5. **Content fit** — if the replacement needs a different number of text segments/items, do not merge/split nodes, drop sourced content, or restructure the grid. Report `warning: P<NN> content does not fit mirror reference <basename>; choose another prototype or change template_reuse_scope to layout/style`, then return to Strategist to select the prototype or scope and update the planning mappings.
6. **Visible text editing** — mirror SVGs may keep literal source text rather than `{{...}}` authoring markers. Edit values in place while retaining imported semantic `data-pptx-placeholder` identity and exact text topology.
-7. **Output filename** — follow the standard project SVG naming convention (`<NN>_<page_name>.svg` where `<NN>` matches the project page index, not the mirror source index). The mirror filename is the *reference*, not the *output*.
+7. **Output filename** — follow the standard project SVG naming convention (`<index>_<page_name>.svg` where `<index>` matches the project page index, not the mirror source index). The mirror filename is the *reference*, not the *output*.
**Detecting mirror mode**: read `template_reuse_scope` from the retained lock. `replication_mode: mirror` in the installed template only determines whether that scope is legal; it must never force mirror behavior when the lock records `layout` or `style`.
diff --git a/skills/ppt-master/scripts/check_annotations.py b/skills/ppt-master/scripts/check_annotations.py
index c9599457..79d509d6 100644
--- a/skills/ppt-master/scripts/check_annotations.py
+++ b/skills/ppt-master/scripts/check_annotations.py
@@ -24,6 +24,7 @@ from pathlib import Path
from typing import Optional
from console_encoding import configure_utf8_stdio
+from slide_roster import discover_slide_svgs
configure_utf8_stdio()
@@ -65,7 +66,7 @@ def scan_directory(dir_path: Path) -> dict[str, list[dict]]:
return {}
results = {}
- for svg_file in sorted(svg_dir.glob('*.svg')):
+ for svg_file in discover_slide_svgs(svg_dir):
annotations = scan_svg_file(svg_file)
if annotations:
results[svg_file.name] = annotations
diff --git a/skills/ppt-master/scripts/notes_to_audio.py b/skills/ppt-master/scripts/notes_to_audio.py
index 790dc2b3..8e2324b0 100644
--- a/skills/ppt-master/scripts/notes_to_audio.py
+++ b/skills/ppt-master/scripts/notes_to_audio.py
@@ -35,6 +35,7 @@ from pathlib import Path
from console_encoding import configure_utf8_stdio
from config import load_prefixed_env_file
+from slide_roster import discover_slide_svgs
from tts_backends import (
backend_cosyvoice,
backend_edge,
@@ -132,7 +133,7 @@ def _prepare_audio_jobs(
def _expected_note_roster(project: Path) -> list[NoteRosterEntry]:
"""Resolve the owning route's complete per-slide notes roster."""
notes_dir = project / "notes"
- svg_files = sorted((project / "svg_output").glob("*.svg"))
+ svg_files = discover_slide_svgs(project / "svg_output")
if svg_files:
aliases: dict[int, list[Path]] = {}
for path in sorted(notes_dir.glob("*.md")):
diff --git a/skills/ppt-master/scripts/project_utils.py b/skills/ppt-master/scripts/project_utils.py
index 4f277f92..4a3295e1 100644
--- a/skills/ppt-master/scripts/project_utils.py
+++ b/skills/ppt-master/scripts/project_utils.py
@@ -13,6 +13,7 @@ from datetime import datetime
from typing import Dict, List, Optional, Tuple
from console_encoding import configure_utf8_stdio
+from slide_roster import discover_slide_svgs
from svg_to_pptx.canvas_contract import (
CanvasContractError,
parse_project_viewbox,
@@ -222,7 +223,7 @@ def get_project_info(project_path: str) -> Dict:
# Count SVG files
svg_output = project_path / 'svg_output'
if svg_output.exists():
- svg_files = sorted(svg_output.glob('*.svg'))
+ svg_files = discover_slide_svgs(svg_output)
info['svg_count'] = len(svg_files)
info['svg_files'] = [f.name for f in svg_files]
diff --git a/skills/ppt-master/scripts/slide_roster.py b/skills/ppt-master/scripts/slide_roster.py
new file mode 100644
index 00000000..89022e6b
--- /dev/null
+++ b/skills/ppt-master/scripts/slide_roster.py
@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""
+PPT Master - Slide Roster Helpers
+
+Orders slide SVG filenames by numeric segments for consistent page rosters.
+
+Usage:
+ Imported by export, validation, preview, animation, and narration tools.
+
+Examples:
+ discover_slide_svgs(Path("projects/demo/svg_output"))
+
+Dependencies:
+ None (only uses standard library)
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+_NUMBER_RE = re.compile(r"(\d+)")
+
+
+def _slide_filename_sort_key(
+ path: Path,
+) -> tuple[tuple[tuple[int, int | str], ...], str]:
+ """Order numeric filename segments by value, then break ties by name."""
+ name = path.name
+ folded = name.casefold()
+ segments = tuple(
+ (0, int(segment)) if segment.isdigit() else (1, segment)
+ for segment in _NUMBER_RE.split(folded)
+ )
+ return segments, name
+
+
+def discover_slide_svgs(directory: Path) -> list[Path]:
+ """Return direct child SVG files in numeric filename order."""
+ return sorted(
+ directory.glob("*.svg"),
+ key=_slide_filename_sort_key,
+ )
diff --git a/skills/ppt-master/scripts/svg_editor/server.py b/skills/ppt-master/scripts/svg_editor/server.py
index 71306e71..a130b520 100644
--- a/skills/ppt-master/scripts/svg_editor/server.py
+++ b/skills/ppt-master/scripts/svg_editor/server.py
@@ -61,6 +61,7 @@ if str(_ROOT_SCRIPTS_DIR) not in sys.path:
from console_encoding import configure_utf8_stdio # noqa: E402
from resource_paths import icon_search_dirs_for_project # noqa: E402
+from slide_roster import discover_slide_svgs # noqa: E402
from server_common import ( # noqa: E402
claim_lock as _claim_lock,
clear_lock as _clear_lock,
@@ -575,7 +576,7 @@ def create_app(
annotations = app.config['ANNOTATIONS']
slides = []
- for svg_file in sorted(svg_dir.glob('*.svg')):
+ for svg_file in discover_slide_svgs(svg_dir):
path_str = str(svg_file)
try:
mtime = svg_file.stat().st_mtime
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.py
index db23e574..81903628 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -25,6 +25,7 @@ from xml.etree import ElementTree as ET
from console_encoding import configure_utf8_stdio
from native_payloads import NativePayloadError, hydrate_native_payload_refs
+from slide_roster import discover_slide_svgs
configure_utf8_stdio()
@@ -5715,7 +5716,7 @@ class SVGQualityChecker:
for reference in structure_lock.prototypes
}
if target_path.is_file():
- sibling_files = sorted(target_path.parent.glob('*.svg'))
+ sibling_files = discover_slide_svgs(target_path.parent)
resolved_target = target_path.resolve()
slide_num = next(
(
@@ -5821,12 +5822,12 @@ class SVGQualityChecker:
else:
if self.template_mode:
# Template directories live at templates/{layouts,decks}/<id>/.
- svg_files = sorted(dir_path.glob('*.svg'))
+ svg_files = discover_slide_svgs(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'))
+ svg_files = discover_slide_svgs(svg_output)
if not svg_files:
print(f"[ERROR] No SVG files found in: {directory}")
@@ -6052,7 +6053,7 @@ class SVGQualityChecker:
complete_roster = target_path.is_dir()
try:
if not complete_roster and target_path.is_file():
- sibling_files = sorted(target_path.parent.glob('*.svg'))
+ sibling_files = discover_slide_svgs(target_path.parent)
resolved_target = target_path.resolve()
slide_num = next(
(
@@ -6617,7 +6618,7 @@ class SVGQualityChecker:
str,
List[Tuple[Path, str, Tuple[str, ...]]],
] = defaultdict(list)
- for svg_path in sorted(svg_dir.glob('*.svg')):
+ for svg_path in discover_slide_svgs(svg_dir):
try:
root = ET.parse(svg_path).getroot()
except (OSError, ET.ParseError):
@@ -8142,7 +8143,7 @@ def _first_page_target(target: str) -> str:
if path.is_file():
return str(path)
svg_root = path / 'svg_output' if (path / 'svg_output').is_dir() else path
- svg_files = sorted(svg_root.glob('*.svg')) if svg_root.is_dir() else []
+ svg_files = discover_slide_svgs(svg_root) if svg_root.is_dir() else []
return str(svg_files[0]) if svg_files else target
diff --git a/skills/ppt-master/scripts/svg_to_pptx/animation_config.py b/skills/ppt-master/scripts/svg_to_pptx/animation_config.py
index 75e5f21a..3adbb289 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/animation_config.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/animation_config.py
@@ -29,6 +29,7 @@ from pptx_transitions import (
normalize_transition_effect_request,
validate_seconds,
)
+from slide_roster import discover_slide_svgs
from .drawingml.utils import SVG_NS
from .pptx_package.narration import AUDIO_CONTENT_TYPES
@@ -198,7 +199,7 @@ def scan_project_targets(
svg_dir = project_path / 'svg_output'
if not svg_dir.is_dir():
return targets_by_slide, [f'svg_output directory not found: {svg_dir}']
- svg_files = sorted(svg_dir.glob('*.svg'))
+ svg_files = discover_slide_svgs(svg_dir)
for svg_path in svg_files:
targets, anonymous = scan_svg_targets(svg_path)
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/discovery.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/discovery.py
index 85838a52..9cd91c7a 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/discovery.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/discovery.py
@@ -5,6 +5,8 @@ from __future__ import annotations
import re
from pathlib import Path
+from slide_roster import discover_slide_svgs
+
class NotesFileReadError(RuntimeError):
"""Report a matched notes file that cannot be decoded or read."""
@@ -52,7 +54,7 @@ def find_svg_files(
else:
return [], ''
- return sorted(svg_dir.glob('*.svg')), dir_name
+ return discover_slide_svgs(svg_dir), dir_name
def find_notes_files(
diff --git a/skills/ppt-master/scripts/total_md_split.py b/skills/ppt-master/scripts/total_md_split.py
index 2e6375ca..cd8cac24 100644
--- a/skills/ppt-master/scripts/total_md_split.py
+++ b/skills/ppt-master/scripts/total_md_split.py
@@ -29,6 +29,7 @@ import re
from pathlib import Path
from console_encoding import configure_utf8_stdio
+from slide_roster import discover_slide_svgs
configure_utf8_stdio()
@@ -122,7 +123,7 @@ def find_svg_files(project_path: Path) -> list[Path]:
project_path: Project directory path
Returns:
- List of SVG files (sorted by filename)
+ List of SVG files in numeric filename order
"""
svg_dir = project_path / 'svg_output'
@@ -130,7 +131,7 @@ def find_svg_files(project_path: Path) -> list[Path]:
print(f"Error: {svg_dir} directory does not exist")
return []
- return sorted(svg_dir.glob('*.svg'))
+ return discover_slide_svgs(svg_dir)
def parse_total_md(
diff --git a/skills/ppt-master/scripts/visual_review.py b/skills/ppt-master/scripts/visual_review.py
index 8a3e32b9..859f5955 100644
--- a/skills/ppt-master/scripts/visual_review.py
+++ b/skills/ppt-master/scripts/visual_review.py
@@ -40,6 +40,7 @@ from contextlib import contextmanager
from pathlib import Path
from console_encoding import configure_utf8_stdio
+from slide_roster import discover_slide_svgs
configure_utf8_stdio()
@@ -197,7 +198,7 @@ def discover_pages(project_path: Path, requested: list[str] | None) -> list[str]
svg_dir = project_path / 'svg_output'
if not svg_dir.is_dir():
raise FileNotFoundError(f'no svg_output/ in {project_path}')
- all_svgs = sorted(p.name for p in svg_dir.glob('*.svg'))
+ all_svgs = [path.name for path in discover_slide_svgs(svg_dir)]
if not requested:
return all_svgs
selected: list[str] = []