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(quick-generate): preserve export capabilities behind final SVG gate

hugohe38cb118e78417
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.py
index da78eca4..db23e574 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -1140,8 +1140,14 @@ class SVGQualityChecker:
"ending": (), # ending pages legitimately use varied vocabularies
}
- def __init__(self, *, template_mode: bool = False):
+ def __init__(
+ self,
+ *,
+ template_mode: bool = False,
+ quick_generate: bool = False,
+ ):
self.template_mode = template_mode
+ self.quick_generate = quick_generate
self.results = []
self.summary = {
'total': 0,
@@ -4707,6 +4713,20 @@ class SVGQualityChecker:
result: Dict,
) -> None:
"""Validate the intrinsic structured Master/Layout SVG contract."""
+ if self.quick_generate:
+ forbidden_attrs = sorted({
+ attr
+ for elem in root.iter()
+ for attr in _PPTX_STRUCTURE_ATTRS
+ if elem.get(attr) is not None
+ })
+ if forbidden_attrs:
+ result['errors'].append(
+ f"{svg_path.name}: Quick Generate uses flat export and "
+ "forbids Master/Layout/layer/placeholder metadata; remove "
+ + ', '.join(forbidden_attrs)
+ )
+ return
if not self.template_mode and svg_path.parent.name == 'svg_output':
declared_mode = _declared_pptx_structure_mode(
self._resolve_project_path(svg_path)
@@ -4975,6 +4995,8 @@ class SVGQualityChecker:
common layouts: SVG directly under <project>/ or under
<project>/svg_output/). Results are cached per lock path.
"""
+ if self.quick_generate:
+ return None
if _parse_spec_lock is None:
return None
for candidate in (svg_path.parent / 'spec_lock.md',
@@ -5668,7 +5690,11 @@ class SVGQualityChecker:
'warning_count': 0,
'by_code': {},
}
- if self.template_mode or _load_pptx_structure_lock is None:
+ if (
+ self.template_mode
+ or self.quick_generate
+ or _load_pptx_structure_lock is None
+ ):
return
project_path = self._resolve_project_path(target_path)
try:
@@ -5882,10 +5908,18 @@ class SVGQualityChecker:
)
elif _CHECK_PPTX_STRUCTURED_PROJECT:
self._check_pptx_structure_contract(dir_path, svg_files)
- if not self.template_mode and dir_path.is_dir():
+ if (
+ not self.template_mode
+ and not self.quick_generate
+ and dir_path.is_dir()
+ ):
self._check_animation_config_contract(dir_path)
self._check_illustration_resource_contract(dir_path)
- if not self.template_mode and validate_communication_trace is not None:
+ if (
+ not self.template_mode
+ and not self.quick_generate
+ and validate_communication_trace is not None
+ ):
project_path = self._resolve_project_path(dir_path)
self._communication_trace_issues.extend(
('error', message)
@@ -5900,6 +5934,8 @@ class SVGQualityChecker:
svg_files: List[Path],
) -> None:
"""Validate the all-page structured lock and reusable contracts."""
+ if self.quick_generate:
+ return
project_path = self._resolve_project_path(target_path)
standard_project = bool(
not self.template_mode
@@ -8153,6 +8189,8 @@ def print_usage() -> None:
print(" requires the complete declared page roster.")
print(" --json Write a machine-readable quality report")
print(" --json-output <path> Override the JSON report path")
+ print(" --quick-generate Validate lockless flat Quick Generate SVGs;")
+ print(" ignore design_spec.md and spec_lock.md.")
print(" --template-mode Validate a template workspace's templates/ directory:")
print(" Brand validates design_spec.md and referenced assets;")
print(" Layout/Deck glob *.svg directly, skip spec_lock checks,")
@@ -8181,7 +8219,14 @@ def main() -> None:
sys.exit(1)
template_mode = '--template-mode' in sys.argv
- checker = SVGQualityChecker(template_mode=template_mode)
+ quick_generate = '--quick-generate' in sys.argv
+ if template_mode and quick_generate:
+ print("[ERROR] --template-mode cannot be combined with --quick-generate")
+ sys.exit(1)
+ checker = SVGQualityChecker(
+ template_mode=template_mode,
+ quick_generate=quick_generate,
+ )
# Parse arguments
target = sys.argv[1]
@@ -8204,6 +8249,9 @@ def main() -> None:
# Execute check
if target == '--all':
+ if quick_generate:
+ print("[ERROR] --quick-generate does not support --all")
+ sys.exit(1)
if stage != 'final':
print("[ERROR] --stage first-page does not support --all")
sys.exit(1)
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
index 495afce1..927ebd15 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
@@ -311,6 +311,38 @@ def _quality_report_context(
}
+def _quality_gate_status(
+ quality: dict[str, object],
+) -> tuple[str, int]:
+ """Return final-gate status and introduced-warning count."""
+ categories = quality.get('categories')
+ blocking_count = None
+ introduced_warning_count = 0
+ if isinstance(categories, dict):
+ blocking = categories.get('blocking')
+ if isinstance(blocking, dict):
+ blocking_count = blocking.get('count')
+ introduced = categories.get('introduced')
+ if (
+ isinstance(introduced, dict)
+ and isinstance(introduced.get('count'), int)
+ ):
+ introduced_warning_count = int(introduced['count'])
+ if quality.get('status') != 'loaded':
+ return str(quality.get('status') or 'not-provided'), introduced_warning_count
+ if quality.get('stage') != 'final':
+ return 'non-final', introduced_warning_count
+ if not isinstance(blocking_count, int):
+ return 'unverified', introduced_warning_count
+ if blocking_count > 0:
+ return 'failed', introduced_warning_count
+ if quality.get('source_match') == 'mismatch':
+ return 'stale', introduced_warning_count
+ if quality.get('source_match') != 'passed':
+ return 'unverified', introduced_warning_count
+ return 'passed', introduced_warning_count
+
+
def _postflight_warning_summaries(
*,
quality_gate: str,
@@ -367,30 +399,7 @@ def _write_postflight_report(
source_audit = _source_resource_audit(svg_files)
source_fingerprint = _svg_source_fingerprint(svg_files)
quality = _quality_report_context(project_path, source_fingerprint)
- quality_categories = quality.get('categories')
- blocking_count = None
- introduced_warning_count = 0
- if isinstance(quality_categories, dict):
- blocking = quality_categories.get('blocking')
- if isinstance(blocking, dict):
- blocking_count = blocking.get('count')
- introduced = quality_categories.get('introduced')
- if isinstance(introduced, dict) and isinstance(introduced.get('count'), int):
- introduced_warning_count = int(introduced['count'])
- if quality.get('status') != 'loaded':
- quality_gate = str(quality.get('status') or 'not-provided')
- elif quality.get('stage') != 'final':
- quality_gate = 'non-final'
- elif not isinstance(blocking_count, int):
- quality_gate = 'unverified'
- elif blocking_count > 0:
- quality_gate = 'failed'
- elif quality.get('source_match') == 'mismatch':
- quality_gate = 'stale'
- elif quality.get('source_match') != 'passed':
- quality_gate = 'unverified'
- else:
- quality_gate = 'passed'
+ quality_gate, introduced_warning_count = _quality_gate_status(quality)
unresolved_tokens = source_audit['unresolved_template_tokens']
external_image_count = source_audit['images']['external']
generic_only_font_stacks = source_audit['fonts']['generic_only_stacks']
@@ -551,31 +560,6 @@ def _print_postflight_receipt(receipt: _PostflightReceipt) -> None:
print(f' [REPORT] {receipt.report_path}')
-def _validate_quick_generate_output(
- output_path: Path,
- *,
- expected_slide_count: int,
-) -> dict[str, object]:
- """Validate a quick-generated PPTX without writing a report sidecar."""
- try:
- package = _package_part_counts(output_path)
- except (OSError, zipfile.BadZipFile) as exc:
- raise PptxPostflightValidationError(
- f"quick-generated PPTX is not a readable ZIP package: {exc}"
- ) from exc
- if package['zip_integrity'] != 'passed':
- raise PptxPostflightValidationError(
- "quick-generated PPTX ZIP integrity failed at "
- f"{package['corrupt_member']}"
- )
- if package['slides'] != expected_slide_count:
- raise PptxPostflightValidationError(
- "Quick-generated Slide count does not match authored SVG count: "
- f"{package['slides']} != {expected_slide_count}"
- )
- return package
-
-
def _declared_pptx_structure_mode(project_path: Path) -> str | None:
"""Return the explicitly locked SVG export mode, if the lock declares one."""
lock_path = project_path / 'spec_lock.md'
@@ -813,7 +797,7 @@ def main(argv: list[str] | None = None) -> int:
Examples:
%(prog)s examples/ppt169_demo # Default: native pptx -> exports/, svg_output -> backup/<ts>/
%(prog)s examples/ppt169_demo -o out.pptx # Explicit path (no backup/)
- %(prog)s projects/quick_generate_demo --quick-generate # Direct: svg_output/ -> PPTX, no export sidecars
+ %(prog)s projects/quick_generate_demo --quick-generate # Lockless flat export with normal postflight
# Disable transition / change transition effect
%(prog)s examples/ppt169_demo -t none
@@ -854,12 +838,13 @@ Per-element object animation (-a/--animation, native shapes mode):
Use "-a none" to disable
element builds explicitly.
-Speaker notes (enabled by default):
+Speaker notes:
- Automatically reads Markdown notes files from the notes/ directory
- Supports two naming conventions:
1. Match by filename (recommended): 01_cover.md corresponds to 01_cover.svg
2. Match by index: slide01.md corresponds to the 1st SVG (backward compatible)
- - Use --no-notes to disable
+ - Enabled by default outside Quick Generate; use --no-notes to disable
+ - Disabled by default in Quick Generate; use --with-notes to enable
Recorded narration:
%(prog)s examples/ppt169_demo --recorded-narration audio \\
@@ -894,11 +879,10 @@ Recorded narration:
'--quick-generate',
action='store_true',
help=(
- 'Direct export of an authored SVG roster from svg_output/. Infer '
- 'one consistent canvas from the SVGs, use a flat '
- 'package with converter defaults, and skip spec_lock.md, notes, '
- 'animations, backup, conversion trace, and validation report '
- 'artifacts.'
+ 'Export a Quick Generate SVG roster from svg_output/ without '
+ 'spec_lock.md. Require a matching final quality report, infer one '
+ 'consistent canvas, use a flat package with converter defaults, '
+ 'and support normal export capabilities.'
),
)
@@ -1071,8 +1055,17 @@ Recorded narration:
),
)
- parser.add_argument('--no-notes', action='store_true',
- help='Disable speaker notes embedding (enabled by default)')
+ notes_mode = parser.add_mutually_exclusive_group()
+ notes_mode.add_argument(
+ '--with-notes',
+ action='store_true',
+ help='Embed speaker notes. Required to opt in during Quick Generate.',
+ )
+ notes_mode.add_argument(
+ '--no-notes',
+ action='store_true',
+ help='Disable speaker notes embedding (enabled by default outside Quick Generate)',
+ )
parser.add_argument('--narration-audio-dir', type=str, default=None,
help='Low-level audio embedding from this directory; allows partial matches. '
'Default-flow exports get the _narrated name suffix.')
@@ -1129,32 +1122,6 @@ Recorded narration:
conflicts.append('--source must be omitted or output')
if args.pptx_structure not in {None, 'flat'}:
conflicts.append('--pptx-structure must be omitted or flat')
- if args.conversion_trace is not None:
- conflicts.append('--conversion-trace')
- if args.native_objects:
- conflicts.append('--native-charts-and-tables')
- if args.animation_config:
- conflicts.append('--animation-config')
- if args.recorded_narration:
- conflicts.append('--recorded-narration')
- if args.narration_audio_dir:
- conflicts.append('--narration-audio-dir')
- if args.use_narration_timings:
- conflicts.append('--use-narration-timings')
- if args.auto_advance is not None:
- conflicts.append('--auto-advance')
- if args.transition is not None or args.transition_duration is not None:
- conflicts.append('transition overrides')
- if any(
- value is not None
- for value in (
- args.animation,
- args.animation_duration,
- args.animation_trigger,
- args.animation_stagger,
- )
- ):
- conflicts.append('animation overrides')
if conflicts:
print(
"Error: --quick-generate cannot be combined with: "
@@ -1162,8 +1129,8 @@ Recorded narration:
file=sys.stderr,
)
return 1
- args.no_notes = True
- args.no_animations = True
+ if not args.with_notes:
+ args.no_notes = True
args.pptx_structure = 'flat'
project_path = Path(args.project_path)
@@ -1325,6 +1292,23 @@ Recorded narration:
print("Error: No SVG files found", file=sys.stderr)
return 1
+ if args.quick_generate:
+ source_fingerprint = _svg_source_fingerprint(native_files)
+ quality = _quality_report_context(project_path, source_fingerprint)
+ quality_gate, _ = _quality_gate_status(quality)
+ if quality_gate != 'passed':
+ print(
+ "Error: --quick-generate requires a passing final SVG quality "
+ f"report for the current svg_output/; found {quality_gate}.",
+ file=sys.stderr,
+ )
+ print(
+ "Run: python3 skills/ppt-master/scripts/svg_quality_checker.py "
+ f'"{project_path}" --quick-generate --stage final --json',
+ file=sys.stderr,
+ )
+ return 1
+
# Compatibility kwargs remain until the builder's old baseline-specific
# parameters are removed. Structured export never activates either path.
structured_baseline = False
@@ -1439,9 +1423,8 @@ Recorded narration:
native_tag = "_native_charts_tables" if args.native_objects else ""
narrated_tag = "_narrated" if (args.recorded_narration or args.narration_audio_dir) else ""
native_path = exports_dir / f"{project_name}_{timestamp}{native_tag}{narrated_tag}.pptx"
- # Preserve the authored svg_output/ beside every default-flow export.
- if not args.quick_generate:
- backup_dir = project_path / "backup" / timestamp
+ # Preserve the authored svg_output/ beside every default-path export.
+ backup_dir = project_path / "backup" / timestamp
native_path.parent.mkdir(parents=True, exist_ok=True)
@@ -1848,7 +1831,7 @@ Recorded narration:
# are still stamped at export; only the authored fields stay blank.
doc_metadata = None
metadata_path = project_path / 'metadata.json'
- if metadata_path.is_file() and not args.quick_generate:
+ if metadata_path.is_file():
try:
loaded = json.loads(metadata_path.read_text(encoding='utf-8'))
except (json.JSONDecodeError, OSError) as exc:
@@ -1973,31 +1956,6 @@ Recorded narration:
print(f" [info] svg_output/ not found, backup skipped")
if success:
- if args.quick_generate:
- try:
- package = _validate_quick_generate_output(
- native_path,
- expected_slide_count=len(native_files),
- )
- except PptxPostflightValidationError as exc:
- print(
- "Error: quick-generated PPTX failed in-memory validation and "
- f"must not be used: {exc}",
- file=sys.stderr,
- )
- print(
- f" Invalid output remains at: {native_path}",
- file=sys.stderr,
- )
- return 1
- if verbose:
- print(
- " [QUICK-GENERATE] "
- f"status=passed slides={package['slides']} "
- "export_sidecars=none"
- )
- print(f" [PPTX] {native_path}")
- return 0
try:
receipt = _write_postflight_report(
output_path=native_path,