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(prompts): move exporter behavior out of animations.md and customize-animations.md
hugohe30f85a558dbd6
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.mdindex b2c54ded..0050966f 100644--- a/skills/ppt-master/references/animations.md+++ b/skills/ppt-master/references/animations.md@@ -71,18 +71,7 @@ Sparse sidecar (unlisted slides inherit resolved defaults):}```-**Contract**:--- `slides` keys are SVG stems; `groups` keys are top-level `<g id>` anchors. A populated group is either the legacy single-effect object or `{ "effects": [row, …] }` (non-empty, each row naming `effect`, mutually exclusive with legacy fields); `{}` is a neutral placeholder; legacy `effect: none` removes the group from the sequence and overrides inherited generic animation.-- `effects[]` lets one shape carry several Animation Pane rows; `order` sorts rows across the slide (ties keep SVG group order, then array order), `trigger_shape` rows sort within their own interactive sequence, and ordering never changes layering.-- `delay` adds seconds to the resolved Start; `trigger` per row otherwise inherits the slide Start mode; `trigger_shape` references another unique triggerable top-level group (PowerPoint **Trigger → On Click of**), makes only that row interactive, uses `delay` as `TriggerDelayTime`, and implies `on-click`.-- `duration` overrides the row schedule (`entrance_appear` stays a 1 ms flip and instantaneous native emphasis keeps its authored duration, but the configured value still spaces the next `after-previous` row).-- `effect_options` requires an explicit canonical `effect` and accepts only what PowerPoint exposes: `direction` (directional entrance/exit effects), `amount` (wheel spokes `1`/`2`/`3`/`4`/`8`, spin degrees, transparency ratio), `color` (`#RRGGBB` or `theme:<scheme-color>`), `font_name` (required for `emphasis_change_font`; one installed face), `size` (grow/shrink), `relative` (motion paths). `python3 skills/ppt-master/scripts/pptx_animations.py --describe <effect>` prints each effect's exact contract.-- Any block or row may set `repeat_count` or `repeat_duration` (exclusive), `auto_reverse`, `rewind`, `accelerate`, `decelerate` (ratios `0..1`; `bounce_end` needs an interpolated behavior and excludes `decelerate`), `restart` (`always` / `when-not-active` / `never`), `after_effect` (`none` / `dim` with `color` / `hide` / `hide-on-next-click`), and `sound` (project-relative or absolute `.m4a` / `.mp3` / `.wav`; new output uses a project-relative path synced under §2.2, never `templates/sounds/`). `Speed` and smooth start/end derive from `duration` and `accelerate`/`decelerate`.-- This is the complete surface for the top-level-group model: no paragraph/text-range builds (grouped SVG is not emitted as paragraph builds), no media commands (audio/video workflows own them).-- `--animation none` overrides the sidecar and disables all per-element animation; a sidecar group may override the legacy chrome-name heuristic but never `data-pptx-layer` or an explicit static role/placeholder; unknown effects, modes, triggers, or invalid numeric/order fields fail validation with no fallback.--**Inheritance**: sidecar and `defaults` are optional; unlisted slides and omitted fields inherit `defaults.transition` / `defaults.animation`, then CLI resolution. Explicit CLI flags override the corresponding sidecar default/slide fields; explicit group overrides remain unless `-a none`. Groups inherit the resolved slide duration, Start, timing modifiers, after-effect, and sound; `effect_options` stays coupled to an explicit effect; `trigger_shape` is never inherited; omitted `order`/`delay` use exporter defaults.+**Contract**: `slides` keys are SVG stems and `groups` keys are top-level `<g id>` anchors. A populated group is either the legacy single-effect object or `{ "effects": [row, …] }`, never both; `{}` is a neutral placeholder; legacy `effect: none` removes the group from the sequence. Rows carry `effect`, `order`, `delay`, `duration`, `trigger` / `trigger_shape`, `effect_options`, and the repeat / reverse / timing-ratio / restart / after-effect / sound modifiers; unlisted slides and omitted fields inherit `defaults` and then the CLI. The complete field grammar, inheritance, and validation are [`pptx-animations.md`](../scripts/docs/pptx-animations.md) §8; `pptx_animations.py --describe <effect>` prints each effect's exact options. `--animation none` disables all per-element animation; `--no-animations` also removes transitions.### 2.1 Deterministic Morph Object Pairing@@ -100,7 +89,7 @@ When one semantic object continues across adjacent slides, the destination slide}```-`morph` belongs to the destination and `morph.from` is the immediately preceding stem in export order; `scaffold` never guesses identity — add pairs from the motion plan after inspecting final direct-root ids. Each pair key is a stable identity whose `from`/`to` are unique direct-root ids on the two slides, written without `!!` (export writes the Selection Pane name `!!<key>` on both). A destination with pairs sets `effect: morph` explicitly (`morph_by` omitted or `object`; `word`/`character` rejected; a CLI override that changes the effect fails). A middle slide may continue an object into another Morph under the same key; one key never names two objects on a slide, one object never carries two keys, and every `!!` key shared by adjacent Morph pages must be declared. Pairing coexists with in-slide animation and survives `-a none`; `--no-animations` disables everything. The exporter resolves both ids to final Slide-local shapes, writes names after Master/Layout processing, then reopens the package to verify adjacency, Morph by object, one name per slide, and matching object types — missing, structural, moved, ambiguous, or mismatched targets fail rather than falling back.+`morph` belongs to the destination and `morph.from` is the immediately preceding stem in export order; `scaffold` never guesses identity — add pairs from the motion plan after inspecting final direct-root ids. Each pair key is a stable identity whose `from`/`to` are unique direct-root ids on the two slides, written without `!!` (export writes the Selection Pane name `!!<key>` on both). A destination with pairs sets `effect: morph` explicitly (`morph_by` omitted or `object`; `word`/`character` rejected; a CLI override that changes the effect fails). A middle slide may continue an object into another Morph under the same key; one key never names two objects on a slide, one object never carries two keys, and every `!!` key shared by adjacent Morph pages must be declared. Pairing coexists with in-slide animation and survives `-a none`; `--no-animations` disables everything. Export verifies every pair and fails rather than falling back ([`pptx-transitions.md`](../scripts/docs/pptx-transitions.md) §3.2).### 2.2 On-Demand Sound Selection@@ -141,7 +130,7 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none --auto-advance 5```-The registry covers PowerPoint's complete Subtle, Exciting, and Dynamic Content gallery — 48 canonical keys (`pptx_animations.py --list`); eight old low-level names desugar to a native key plus options (`diamond` → `shape` + `shape: diamond`, `wedge` → `clock` + `style: wedge`) and are never selected for new output. `transition.effect_options` exposes the real Effect Options (Push/Wipe direction, Morph by object/word/character, Reveal through black, Shape geometry, Page Curl direction/pages, Glitter pattern, Fly Through bounce; `pptx_animations.py --describe-transition <effect>`); unknown options fail. Effects needing newer namespaces carry a `mc:Choice` plus a `fade` fallback that validation never accepts as a substitute. `transition.sound` (a sidecar field, `.wav`, synced under §2.2) may accompany `effect: none`; a slide-level `transition.sound: null` clears an inherited default transition sound. Flags: `-t/--transition` (native key, compatibility input, or `none`; default `fade`; `none` keeps an explicit auto-advance), `--transition-duration` (default `0.4`), `--auto-advance` (seconds; click still advances). **Hard rule — no silent downgrade**: an unknown effect, unsupported option, or invalid duration fails export and is never replaced by `fade`; `-t none --recorded-narration …` writes narration-driven advance without restoring a visual effect.+The registry covers PowerPoint's complete Subtle, Exciting, and Dynamic Content gallery — 48 canonical keys (`pptx_animations.py --list`); old low-level names normalize to a native key plus options and are never selected for new output. `transition.effect_options` exposes each effect's real Effect Options (`pptx_animations.py --describe-transition <effect>`); `transition.sound` (a `.wav` synced under §2.2) may accompany `effect: none`. Flags: `-t/--transition` (default `fade`; `none` keeps an explicit auto-advance), `--transition-duration` (default `0.4`), `--auto-advance` (seconds; click still advances). **Hard rule — no silent downgrade**: an unknown effect, unsupported option, or invalid duration fails export and is never replaced by `fade`. Carrier XML, MCE fallbacks, and read-back: [`pptx-transitions.md`](../scripts/docs/pptx-transitions.md).### 3.1 Morph — author an action as the difference between two pages@@ -167,7 +156,7 @@ Off by default; enable with `-a auto` (or another effect), select a canonical ef**Default — restrained entrance-led choreography (may override for content, tone, or the request)**: entrances for ordinary builds; emphasis or exit only for a real duty; several `effects[]` rows only for several duties.-The registry has **203 native object presets** — 53 `entrance_*`, 33 `emphasis_*`, 64 `path_*`, 53 `exit_*` (e.g. `entrance_bounce`, `emphasis_spin`, `path_circle`, `exit_faded_zoom`), each carrying the complete PowerPoint behavior tree — plus 29 legacy compatibility inputs that normalize before selection (`fade` → `entrance_fade`, old Fly/Wipe direction names → `entrance_fly` / `entrance_wipe` with the direction in `effect_options`, `cut` → `entrance_appear`, `wheel` → `entrance_wheel` with four spokes) and are never written. `python3 skills/ppt-master/scripts/pptx_animations.py --list` prints the categorized keys; media play/pause/stop belong to the audio/video workflows. Modes handle generic `enter` only: `auto` maps semantic ids to canonical entrances (charts/tables/timelines `entrance_wipe`, cards/steps `entrance_fly`, titles/takeaways `entrance_fade`, image-like ids a richer pool, others fade/wipe/fly/zoom); `mixed` is deterministic (`entrance_fade` first, then a 16-effect canonical pool); `random` samples the same pool, seeded from the effective deck input so results repeat; `entrance_appear` is excluded from every pool; none satisfies an adopted `emphasize`, `move`, or `exit`. Flags: `-a/--animation`, `--animation-trigger`, `--animation-duration`, `--animation-stagger`, `--animation-config <sidecar>`, `--no-animations` (kills page/object motion, keeps narration audio and recorded advance). `--recorded-narration` rejects `on-click` and `trigger_shape`; narration-cue sync uses `narration_animations.json` and blocks on a bare canonical sidecar; narration-independent custom motion passes `--animation-config animations.json` explicitly; with no sidecar pass `--inherit-motion-from <base_postflight_report>`.+The registry has **203 native object presets** — `entrance_*`, `emphasis_*`, `path_*`, `exit_*` (`pptx_animations.py --list` prints the categorized keys); 29 legacy short names normalize before selection and are never written. Modes handle generic `enter` only: `auto` maps semantic ids to canonical entrances, `mixed` cycles a deterministic pool, `random` samples it with a stable seed; none satisfies an adopted `emphasize`, `move`, or `exit`. Flags (`-a`, `--animation-trigger`, `--animation-duration`, `--animation-stagger`, `--animation-config`, `--no-animations`) and their narration interactions: [`pptx-animations.md`](../scripts/docs/pptx-animations.md) §3 and [`svg-pipeline.md`](../scripts/docs/svg-pipeline.md).### 4.1 Slow ambient motion — the page that breathes@@ -184,19 +173,19 @@ The registry has **203 native object presets** — 53 `entrance_*`, 33 `emphasis## 5. Anchor Logic — Top-Level `<g id="...">`-Animations anchor on unique top-level `<g id>` content groups (`cover-title`, `card-1`); a single-effect group yields one Animation Pane row, `effects[]` several, each inheriting the slide Start unless it declares `trigger`; nested groups stay anonymous and untargeted. **Hard rule — existing groups are not custom-animation intent**: during the custom stage derive one group per logical motion unit from claims, comparisons, sequence, causality, and narration — splitting coarse wrappers and merging fragments without changing appearance, never to hit a count — and run `list-groups` only after that rewrite. **Chrome stays static**: `data-pptx-layer` and explicit static role/placeholder markers are absolute; the legacy chrome-name heuristic (background, header/footer, decor, watermark, page number, nav, logo, rule) applies only to unmarked top-level groups and only it may be overridden by a sidecar entry. Flat SVGs with no top-level `<g>`: ≤8 visible root primitives each become an anchor, more skips animation on that slide. Wrap logical sections in `<g id>` regardless ([`shared-standards-core.md`](./shared-standards-core.md)).+Animations anchor on unique top-level `<g id>` content groups (`cover-title`, `card-1`); a single-effect group yields one Animation Pane row, `effects[]` several, each inheriting the slide Start unless it declares `trigger`; nested groups stay anonymous and untargeted. **Hard rule — existing groups are not custom-animation intent**: during the custom stage derive one group per logical motion unit from claims, comparisons, sequence, causality, and narration — splitting coarse wrappers and merging fragments without changing appearance, never to hit a count — and run `list-groups` only after that rewrite. **Chrome stays static**: `data-pptx-layer` and explicit static role/placeholder markers are absolute; the legacy chrome-name heuristic (background, header/footer, decor, watermark, page number, nav, logo, rule) applies only to unmarked top-level groups and only it may be overridden by a sidecar entry. Wrap logical sections in `<g id>` ([`shared-standards-core.md`](./shared-standards-core.md) §4.3); a root with no top-level group falls back to a bounded primitive set ([`svg-pipeline.md`](../scripts/docs/svg-pipeline.md)).---## 6. Validation and Read-Back-Export fails on an unknown effect, mode, or trigger; invalid timing or order; a missing slide, group, or `trigger_shape`; a self-trigger; or animating or triggering from a structural layer — never downgrading or omitting a target. It reads each slide's timing tree back (row count and order including repeats on one shape, trigger, trigger shape, target, preset class, effect tuple, behavior signature, duration, offset), validates root timing placement, unique `p:cTn` ids, and every `p:spTgt`, and for deterministic Morph checks the adjacent parts for the `!!` names, one-to-one uniqueness, compatible types, and a real Morph-by-object transition. The writer emits no `p:bldP` for groups or pictures (preserve mode tolerates legacy ones). Narration injection preserves animation and keeps p14 Choice/Fallback in sync; direct-PPTX routes fingerprint source timing before and after their edits and never author effects. `pptx_to_svg.py` projects supported source `p:transition` (registry effect, options, exact duration, auto-advance, WAV sound; sidecar default `none`) and only current generated `p:timing` trees (registry effect, pane order, Start, exact duration, relative delay, unique top-level targets) into `animations.json`; unknown carriers, missing durations, advanced modifiers, sounds, builds, and unmapped targets stay diagnosed/direct-preserve with no inferred value. These checks prove PPTX timing and embedded sound parts, not final-video audio: the native-export branch needs a `video_sound_mix.py` receipt and the capture branch the human acceptance owned by `generate-audio`.+Export rejects an unknown effect, mode, or trigger, invalid timing or order, a missing slide, group, or `trigger_shape`, and any structural-layer target, then reads every slide back and compares it with the request; nothing is downgraded or omitted. The complete rules, the reverse projection `pptx_to_svg.py` writes into `animations.json`, and what read-back does not prove (final-video audio) are [`pptx-animations.md`](../scripts/docs/pptx-animations.md) §6 and [`pptx-transitions.md`](../scripts/docs/pptx-transitions.md) §6.---## 7. Video Adaptation Contract-Video renderers consume the resolved conversion trace through `video_motion_plan.py` ([`video-motion-plan.md`](../scripts/docs/video-motion-plan.md)), never a raw sidecar or delay inference; the plan locks identity, order, effect, direction, and timing, video refines only its declared renderer parameters, and unsupported families fail visibly. The native-export mix uses the final trace for cue order and offsets, the final PPTX relationships for the embedded bytes, and page-level narration correlation for the clock; the slideshow-capture branch records real-time playback and does not consume the trace.+Video renderers consume the resolved conversion trace through `video_motion_plan.py` ([`video-motion-plan.md`](../scripts/docs/video-motion-plan.md)), never a raw sidecar; the plan locks identity, order, effect, direction, and timing.## 8. Limitationsdiff --git a/skills/ppt-master/workflows/stages/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.mdindex d4f60e39..d711c56a 100644--- a/skills/ppt-master/workflows/stages/customize-animations.md+++ b/skills/ppt-master/workflows/stages/customize-animations.md@@ -80,11 +80,11 @@ After any regrouping, rerun the final gate (`svg_quality_checker.py <project_pat### 3.1 Supported Page Transitions-One of the 48 canonical native effects in `animations.md` §3 (the complete Subtle, Exciting, and Dynamic Content gallery); the eight old names are compatibility inputs only and normalize to a canonical effect plus `effect_options`; `none` removes the visual effect while timed advance remains. Fields: `effect`; `effect_options` (only the selected effect's native options — run `pptx_animations.py --describe-transition <effect>` first and never infer another effect's fields); `duration` (> 0 s); `auto_advance` (non-negative seconds, click still enabled, valid with `effect: none`); `sound` (project-relative `.wav`, selected only after the transition is resolved). For a cross-slide continuation that must not depend on PowerPoint's automatic matching, put one `morph` block on the destination whose `from` is the immediately preceding SVG and whose pair keys bind one source direct-root group to one destination group (the exporter supplies `!!`); Morph by object only.+One of the 48 canonical native effects in [`animations.md`](../../references/animations.md) §3 (`pptx_animations.py --list`); old names are compatibility inputs only. Fields — `effect`, `effect_options` (only the selected effect's native options: run `pptx_animations.py --describe-transition <effect>` first), `duration`, `auto_advance`, `sound` — follow [`pptx-animations.md`](../../scripts/docs/pptx-animations.md) §8. A cross-slide continuation that must not depend on PowerPoint's automatic matching declares one `morph` block on the destination ([`animations.md`](../../references/animations.md) §2.1).### 3.2 Supported In-Slide Animations-The 203 canonical keys — 53 `entrance_*`, 33 `emphasis_*`, 64 `path_*`, 53 `exit_*` (`pptx_animations.py --list`), each preserving PowerPoint's complete behavior tree. `auto` / `mixed` / `random` apply to generic `enter` only (`auto` maps roles to canonical entrances with a richer pool for image-like ids; `mixed` cycles 16 presets by group order; `random` selects deterministically from the same pool) and never choose emphasis, path, or exit implicitly; `none` excludes the object or slide. The 29 old short names are compatibility inputs (Fly/Wipe directions → `entrance_fly` / `entrance_wipe` with `effect_options.direction`, `cut` → `entrance_appear`, legacy `wheel` keeps its four-spoke amount). **Hard rule — explicit semantic choreography**: when a plan depends on a specific lifecycle, relationship, or order, target real groups with explicit canonical effects and order; generic modes are valid only when generic entrance treatment suffices. Start modes: `after-previous` (click-free cascade), `with-previous` (one coordinated beat), `on-click` (controlled reveal).+The 203 canonical keys of [`animations.md`](../../references/animations.md) §4 (`pptx_animations.py --list`); `auto` / `mixed` / `random` supply generic entrances only and never choose emphasis, path, or exit. **Hard rule — explicit semantic choreography**: when a plan depends on a specific lifecycle, relationship, or order, target real groups with explicit canonical effects and order; generic modes are valid only when generic entrance treatment suffices. Start modes: `after-previous` (click-free cascade), `with-previous` (one coordinated beat), `on-click` (controlled reveal).### 3.3 Optional Sound Pass@@ -96,7 +96,7 @@ Only after visual transition, lifecycle, effect, order, and timing are complete,**Hard rule — sparse overrides reference real targets**: write only affected slides and only fields that differ from exporter or sidecar defaults; an unlisted SVG inherits deck-wide settings; a listed slide carries only the `transition`, `animation`, `groups`, or `morph` fields it overrides; `defaults` is optional and deck-wide only; chrome groups stay out (the exporter pins them to `none`), and a legacy chrome-like id is named only on explicit reviewed intent with no structural marker. **Forbidden**: a slide absent from `svg_output/`; a missing, ambiguous, or structural group; enumerating every group to restate the slide default; listing a group with `data-pptx-layer` or a static role/placeholder marker; animation `data-*` attributes in SVG.-**Hard rule — one group representation**: a populated `groups.<id>` uses either the legacy single-effect fields or `effects[]` (non-empty, every row naming `effect`), never both; an untouched scaffold `{}` is neutral; omitted row duration, Start, timing/completion controls, and sound inherit the resolved slide values. `effect_options` may hold `direction`, `amount`, `color`, `font_name`, `relative`, or `size`, but only fields the selected effect supports — run `pptx_animations.py --describe <canonical_effect>` before writing a parameterized effect; `duration` owns Speed and `accelerate` / `decelerate` own smooth start/end (no duplicate fields); Change Font's `font_name` is one target-installed face, never a CSS stack. The complete field reference — transition, morph, slide animation defaults, per-row trigger, order, delay, duration, `trigger_shape`, repeat, reverse/rewind, timing ratios, restart, after-effect, sound — is [`pptx-animations.md`](../../scripts/docs/pptx-animations.md) §8. Use the multi-category `effects[]` example in `animations.md` §2 and the two-slide Morph example in §2.1 (never copy the source group into the destination `groups` to establish identity); keep the legacy object for one-row overrides and never convert old sidecars mechanically.+**Hard rule — one group representation**: a populated `groups.<id>` uses either the legacy single-effect fields or `effects[]`, never both; an untouched scaffold `{}` is neutral; omitted row values inherit the resolved slide values. Every field, its range, and its inheritance are [`pptx-animations.md`](../../scripts/docs/pptx-animations.md) §8; run `pptx_animations.py --describe <canonical_effect>` before writing a parameterized effect, and give Change Font one target-installed face, never a CSS stack. Use the multi-category `effects[]` example in `animations.md` §2 and the two-slide Morph example in §2.1 (never copy the source group into the destination `groups` to establish identity); keep the legacy object for one-row overrides and never convert old sidecars mechanically.---@@ -104,7 +104,7 @@ Only after visual transition, lifecycle, effect, order, and timing are complete,When `animations.json` was created or changed after §1, run `python3 skills/ppt-master/scripts/animation_config.py validate <project_path>`, then return to the owning export path — Default [`generate-pptx.md`](../generate-pptx.md) Step 7.1; Quick [`quick-generate.md`](../profiles/quick-generate.md) §4 — both of which read the sidecar automatically. If §2 changed `svg_output/`, complete the owning route's final SVG rerun before returning; never finalize or export from this stage.-**Validation**: unknown effects/modes/triggers; unsupported options; incompatible, boolean, non-finite, or out-of-range timing; non-positive durations; negative delay/stagger; invalid order; missing slides/groups; structural targets; and Morph pairs with non-adjacent sources, missing or ambiguous groups, conflicting or undeclared keys, non-object Morph, or a target that does not remain one compatible Slide-local object all fail — never replaced by a fallback or silently dropped. `--animation none` still disables all per-element animation. A passing sidecar, timing-tree read-back, and sound relationship check prove the PPTX configuration, not an exported MP4 audio track. Step 7 export reads back row order, trigger, target, effect, duration, offset, placement, IDs, and shape references; narration preserves them; direct-PPTX routes preserve source animation and never author it.+**Validation**: every invalid field, target, or Morph pair fails rather than falling back ([`pptx-animations.md`](../../scripts/docs/pptx-animations.md) §6). A passing sidecar and read-back prove the PPTX configuration, not an exported MP4 audio track.### 5.1 Optional Video Motion Handoff