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(svg-export): default conversion traces to validation

hugohe3bbffa6ebe908
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.md
index bf25aaa2..0232c897 100644
--- a/skills/ppt-master/references/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -224,7 +224,7 @@ and renderer contract.
| All groups animate together | `-a auto --animation-trigger with-previous` |
| Slower per-element reveal | `-a auto --animation-duration 0.5` |
| Wider gap in after-previous | `-a auto --animation-stagger 0.7` |
-| Derive effect-aware video motion | `video_motion_plan.py <output>.pptx.trace.json --force` |
+| Derive effect-aware video motion | `video_motion_plan.py <project>/validation/<output_stem>.trace.json --force` |
See also:
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index ce104495..b4446af7 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -349,6 +349,7 @@ Behavior:
- Native output uses content-hash media filenames, so identical images are reused and different images cannot overwrite each other by sharing a basename.
- `[Content_Types].xml` is generated from the actual media extensions written into the PPTX. Unknown media extensions fail unless Python's `mimetypes` can identify them.
- Native export writes to a temporary file first and publishes the requested PPTX only after conversion succeeds. A failed conversion does not replace the main output file.
+- `--conversion-trace` without a path writes `validation/<output_stem>.trace.json`. `--conversion-trace <path>` respects the explicit destination; relative paths are resolved from the project root, so `exports/<name>.trace.json` remains available when intentionally requested.
- After publication, native export writes `validation/<output_stem>.report.json`. The report distinguishes authored Slides from internal Layout definitions, reruns ZIP integrity and published Slide-count checks, records slide/layout/master/notes part counts, labels relationship/structured/transition/animation validation as enforced at build time, links the final SVG quality report only when its SHA-256 source fingerprint matches the exact export inputs, and surfaces stale/unverified gates, unresolved template tokens, generic-only font stacks, and external image references. A matching final quality report with introduced warnings yields `passed-with-warnings` and a `quality_introduced_warnings=<N>` receipt instead of a clean `passed` claim.
- By default, a successful command also prints a compact receipt instead of requiring a report read: `[POSTFLIGHT] status=<...> quality_gate=<...> slides=<N> warning_categories=<N>`, followed by one compact line per warning category and the `[PPTX]` / `[REPORT]` paths. Resource-warning lines carry counts; a non-passing quality gate carries its status. Routine agents use this receipt and do not load either complete validation JSON into model context. Full reports remain cold audit artifacts; failure investigation and explicit audits extract only the required fields. `--quiet` keeps suppressing successful-run output.
- Before publishing structured template output, export reopens the temporary PPTX and validates the Slide → Layout → Master graph and registrations, Layout identity, placeholder identity, reusable bounds, and prompt/level-one sizes. A mismatch aborts publication. Flat release instead validates its single referenced Master/Layout shell and exact date/footer/slide-number hook roster before packaging.
diff --git a/skills/ppt-master/scripts/docs/video-motion-plan.md b/skills/ppt-master/scripts/docs/video-motion-plan.md
index d573538e..00286820 100644
--- a/skills/ppt-master/scripts/docs/video-motion-plan.md
+++ b/skills/ppt-master/scripts/docs/video-motion-plan.md
@@ -28,7 +28,7 @@ Then build the motion plan:
```bash
python3 skills/ppt-master/scripts/video_motion_plan.py \
- <project_path>/validation/video_motion_source.pptx.trace.json \
+ <project_path>/validation/video_motion_source.trace.json \
-o <project_path>/validation/video_motion_plan.json \
--style adaptive \
--force
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 b3da5a76..fdd6dd34 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
@@ -720,10 +720,16 @@ Recorded narration:
help='Disable paragraph merging. Every dy-stacked line becomes '
'its own text frame for strict SVG line-layout fidelity.')
parser.set_defaults(merge_paragraphs=True)
- parser.add_argument('--conversion-trace', action='store_true', default=False,
- help='Write a JSON diagnostics report next to the native PPTX '
- '(<output>.trace.json). Records per-slide SVG element '
- 'conversion decisions for debugging.')
+ parser.add_argument(
+ '--conversion-trace',
+ nargs='?',
+ const='',
+ default=None,
+ metavar='PATH',
+ help='Write per-slide SVG conversion diagnostics. Without PATH, write '
+ '<project>/validation/<output_stem>.trace.json; relative PATHs '
+ 'are resolved from the project root.',
+ )
parser.add_argument(
'--native-charts-and-tables',
dest='native_objects',
@@ -1452,10 +1458,19 @@ Recorded narration:
print(f" Output file: {native_path}")
print()
- conversion_trace_path = (
- native_path.with_name(native_path.name + '.trace.json')
- if args.conversion_trace else None
- )
+ conversion_trace_path: Path | None = None
+ if args.conversion_trace is not None:
+ if args.conversion_trace:
+ requested_trace_path = Path(args.conversion_trace).expanduser()
+ conversion_trace_path = (
+ requested_trace_path
+ if requested_trace_path.is_absolute()
+ else project_path / requested_trace_path
+ )
+ else:
+ conversion_trace_path = (
+ project_path / 'validation' / f'{native_path.stem}.trace.json'
+ )
try:
success = create_pptx_with_native_svg(
output_path=native_path,
diff --git a/skills/ppt-master/scripts/video_motion_plan.py b/skills/ppt-master/scripts/video_motion_plan.py
index b0f0c144..a5b6b905 100644
--- a/skills/ppt-master/scripts/video_motion_plan.py
+++ b/skills/ppt-master/scripts/video_motion_plan.py
@@ -10,8 +10,8 @@ Usage:
python3 scripts/video_motion_plan.py <conversion_trace.json> [options]
Examples:
- python3 scripts/video_motion_plan.py exports/deck.pptx.trace.json --force
- python3 scripts/video_motion_plan.py exports/deck.pptx.trace.json \
+ python3 scripts/video_motion_plan.py validation/deck.trace.json --force
+ python3 scripts/video_motion_plan.py validation/deck.trace.json \
--style dynamic -o validation/video_motion_plan.json --force
Dependencies:
@@ -568,7 +568,10 @@ def build_parser() -> argparse.ArgumentParser:
),
formatter_class=argparse.RawDescriptionHelpFormatter,
)
- parser.add_argument("trace", help="Path to <output>.pptx.trace.json")
+ parser.add_argument(
+ "trace",
+ help="Path to validation/<output_stem>.trace.json",
+ )
parser.add_argument(
"-o",
"--output",
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index bca69b5c..817d0ad5 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -458,6 +458,7 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
- `exports/<project_name>_<timestamp>.pptx`
- `validation/<project_name>_<timestamp>.report.json` with `passed` or `passed-with-warnings` package/resource postflight status
+- `validation/<project_name>_<timestamp>.trace.json` when bare `--conversion-trace` is enabled; an explicit `--conversion-trace <path>` uses that destination instead
The command prints a compact `[POSTFLIGHT]` receipt containing `status`, `quality_gate`, Slide count, warning-category counts, and the PPTX/report paths. Use that receipt as completion evidence and disclose its material warnings to the user. Do not open or `cat` the complete report on routine success; use targeted field extraction only for failure investigation, an explicit audit request, or information absent from the receipt. A failed report or missing PPTX is not success.
diff --git a/skills/ppt-master/workflows/stages/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.md
index f27c4f44..3facb94a 100644
--- a/skills/ppt-master/workflows/stages/customize-animations.md
+++ b/skills/ppt-master/workflows/stages/customize-animations.md
@@ -314,7 +314,7 @@ When a downstream video renderer will enhance the deck, export with
```bash
python3 skills/ppt-master/scripts/video_motion_plan.py \
- <output>.pptx.trace.json \
+ <project_path>/validation/<output_stem>.trace.json \
-o <project_path>/validation/video_motion_plan.json \
--style adaptive \
--force