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
docs(customize-animations): derive animation groups from slide semantics
hugohe3d6a6371801db
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.mdindex 0232c897..6dc258e7 100644--- a/skills/ppt-master/references/animations.md+++ b/skills/ppt-master/references/animations.md@@ -17,12 +17,22 @@ To regenerate a deck with different settings, rerun `svg_to_pptx.py` against the## 2. Custom Object-Level Animation-Per-element animation is off by default. To enable it deck-wide, pass `-a auto` at export (no config needed). When a deck instead needs specific object timing — for example title first, chart second, annotation last — use the optional `animations.json` sidecar. The SVG remains static visual source; the sidecar only controls PPTX export behavior.+Per-element animation is off by default. To enable it deck-wide, pass `-a auto` at export (no config needed). When a deck instead needs specific object timing — for example title first, chart second, annotation last — use the optional `animations.json` sidecar. The SVG remains the visual source; the custom stage may rewrite its grouping hierarchy, ids, and bounds to create better semantic anchors without changing visible output, while the sidecar controls PPTX animation behavior.Run the [`customize-animations`](../workflows/stages/customize-animations.md) post-processing stage when the user asks to tune animation order, effects, timing, or object-level reveals.+**Hard rule — semantic anchors before sidecar**: for custom object-level+animation, do not scaffold or choreograph directly from the SVG's pre-existing+`<g>` list. First derive reveal units from page meaning and narration, audit+every page, and rewrite coarse or fragmented ordinary Slide-local groups+without changing visible output. Only the post-regroup top-level ids are valid+custom-animation anchors.+```bash-# Build an editable scaffold from real top-level <g id> anchors+# Inspect the real anchors after the semantic regrouping pass+python3 skills/ppt-master/scripts/animation_config.py list-groups <project>++# Build an editable scaffold from the post-regroup anchors when usefulpython3 skills/ppt-master/scripts/animation_config.py scaffold <project># Validate references before export@@ -159,7 +169,14 @@ Flags:Per-element animations are anchored on **top-level `<g id="...">` content groups** in the SVG (e.g. `<g id="cover-title">`, `<g id="card-1">`). IDs must be unique within the page. One group produces one animation-pane entrance row; whether that row needs a click depends on the selected Start mode. Nested implementation groups may remain anonymous because the sidecar does not target them.-Use one content group per logical page unit. This is also the granularity PowerPoint uses for group-select / group-move, so semantic grouping improves editing ergonomics regardless of animation; do not split or merge units to hit a target count.+**Hard rule — existing groups are not custom-animation intent**: the+pre-existing SVG hierarchy is implementation evidence, not an authoritative+reveal plan. During the custom-animation stage, derive one group per logical+page unit from claims, comparisons, sequence, causality, and narration beats;+split coarse wrappers and merge fragmented atoms when needed, then use+`list-groups` only after that rewrite. This is also the granularity PowerPoint+uses for group-select / group-move. Do not split or merge units to hit a target+count.**Chrome groups skip the cascade automatically.** Explicit SVG role and placeholder semantics are authoritative. A group with `data-pptx-layer` or an explicit static role/placeholder marker can never animate. For marker-free legacy SVGs only, top-level groups whose id tokens look like page chrome (background, header/footer, decorations, watermark, page number, nav, logo, dividing rule) are excluded and appear with the slide. An explicit `animations.json` group entry may override this id-name heuristic, but never an explicit structural marker. Examples that auto-skip by legacy id: `<g id="background">`, `<g id="bg-texture">`, `<g id="cover-footer">`, `<g id="p03-header">`, `<g id="bottom-decor">`, `<g id="watermark">`, `<g id="nav">`, `<g id="logo-area">`, `<g id="column-rule">`. Examples that still animate: `<g id="card-1">`, `<g id="cover-title">`, `<g id="step-discover">`, `<g id="timeline-track">`. Do not strip the `<g>` wrapper to avoid animation — keep it for PowerPoint group selection and use `effect: none` when the content should remain static.diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.jsonindex 5a0c423e..94030fda 100644--- a/skills/ppt-master/scripts/prompt_audit_manifest.json+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json@@ -619,7 +619,7 @@"skills/ppt-master/scripts/docs/pptx-transitions.md","skills/ppt-master/scripts/docs/svg-pipeline.md"],- "max_tokens": 18600+ "max_tokens": 21300},"stage.generate.animation-options": {"description": "Conditional deck-wide transition, auto-advance, and entrance-animation options.",diff --git a/skills/ppt-master/workflows/stages/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.mdindex 3e1c8234..8b05e1f7 100644--- a/skills/ppt-master/workflows/stages/customize-animations.md+++ b/skills/ppt-master/workflows/stages/customize-animations.md@@ -23,41 +23,22 @@ description: Optional post-processing stage for per-slide and per-object animati----## 1. Get Real Group IDs (do NOT dump the full scaffold)+## 1. Resolve Intent and Read Semantic Context-**Mandatory**: use real SVG group ids. Do not invent slide or group keys.--**Default path — `list-groups`** (cheap, ~1KB of output even on a long deck):--```bash-python3 skills/ppt-master/scripts/animation_config.py list-groups <project_path>-```--Output is one line per slide: `<slide_basename>: id1, id2, id3` — default-chrome groups (`bg` / `*-header` / `*-footer` / `*-decor` / `nav` /-`watermark` / `logo` / `pagenumber`) are excluded from the ordinary target-list. Use this as the source of truth when planning §3 and editing §4-— **do not read the full scaffold file unless you need it as an editing-starting point**.--An explicit sidecar entry may override only the marker-free legacy id-name-heuristic. A group carrying `data-pptx-layer` or an explicit static-role/placeholder marker can never animate, even when it is named explicitly.--If `animations.json` does not exist and you want a starting file to edit:--```bash-python3 skills/ppt-master/scripts/animation_config.py scaffold <project_path>-```+**Context read**: before editing `animations.json`, read every semantic planning file below that exists.-Scaffold output also excludes chrome and includes a `defaults` stub.+| File | Use |+|---|---|+| `<project_path>/design_spec.md` | Understand each slide's content intent, narrative role, and visual emphasis |+| `<project_path>/spec_lock.md` | Confirm page rhythm, layout role, chart/template constraints, and execution contract |+| `<project_path>/notes/total.md` or `<project_path>/notes/*.md` | Use speaker flow to tune reveal order, delays, and emphasis |**Existing sidecar intent gate**:| User intent | Action ||---|---|-| Explicit regeneration / rewrite / replacement | Read the current semantic context and real group ids, then replace `animations.json`; the previous choreography is not a constraint |-| Explicit adjustment / tuning / repair | Validate first, then preserve and edit the existing choreography |+| Explicit regeneration / rewrite / replacement | Rebuild the semantic grouping plan and replace `animations.json`; the previous choreography is not a constraint |+| Explicit adjustment / tuning / repair | Validate first, preserve the existing choreography where its semantic units remain valid, and migrate affected group references after any required regrouping || Ambiguous generation request | Ask whether to regenerate from scratch or modify the current animation; do not choose on the user's behalf |When the existing sidecar will be modified:@@ -66,21 +47,88 @@ When the existing sidecar will be modified:python3 skills/ppt-master/scripts/animation_config.py validate <project_path>```+**Hard rule**: semantic files determine both animation intent and animation+unit boundaries. The current `svg_output/*.svg` supplies visible content and+implementation structure, but its existing `<g>` hierarchy is not accepted as+the animation plan merely because it already exists.++**Optional-context fallback**: these semantic files inform this supporting stage but are not its gate artifacts. If any are absent, state what is missing and proceed with every remaining file plus visible SVG content. If all three context inputs are absent, use only explicit user instructions, visible SVG content, and the resolution rules in [`animations.md`](../../references/animations.md); do not infer detailed choreography beyond what the page itself expresses.+----## 2. Read Semantic Context+## 2. Rebuild Semantic Animation Groups, Then List IDs-**Context read**: before editing `animations.json`, read every semantic planning file below that exists.+**Mandatory — content-first grouping audit**: inspect every slide's visible+content against its communication job and speaker flow before treating any+top-level `<g>` as an animation anchor. Existing groups are implementation+evidence only. Keep a current group unchanged only after confirming that it+already represents exactly one audience-facing reveal unit.-| File | Use |+| Content condition | Required grouping action ||---|---|-| `<project_path>/design_spec.md` | Understand each slide's content intent, narrative role, and visual emphasis |-| `<project_path>/spec_lock.md` | Confirm page rhythm, layout role, chart/template constraints, and execution contract |-| `<project_path>/notes/total.md` or `<project_path>/notes/*.md` | Use speaker flow to tune reveal order, delays, and emphasis |+| One current group contains several independently narrated rows, cards, steps, claims, or stages | Split it into descriptive direct-root sibling groups, one per reveal unit |+| One reveal unit is scattered across groups or root primitives | Merge or wrap its background, icon, label, value, and supporting text into one direct-root group |+| A connector or arrow explains entry into a node or stage | Reveal it with the relationship or target unit that makes the connection intelligible |+| A hero visual, overview graphic, takeaway, or warning has its own communication role | Give it its own semantic group |+| Several atoms express one inseparable idea | Keep them together; do not animate the atoms separately |+| Page chrome, structural layers, or static framing | Preserve their structure and exclude them from ordinary animation targets |++**Hard rule — visual equivalence**: regrouping changes object boundaries only.+Preserve all visible content, paint order, coordinates, transforms, inherited+paint, opacity, clipping, filters, references, and native metadata. Keep+rendering-bearing implementation wrappers nested inside the new semantic group+when flattening or distributing their attributes could change appearance.++**Hard rule — structural boundary**: never split or merge across+`data-pptx-layer`, `data-pptx-placeholder`, native chart/table carrier, native+preset, or imported logical-object boundaries. Structural/static objects remain+non-animatable. Ordinary Slide-local content groups follow+[`shared-standards-core.md`](../../references/shared-standards-core.md) §4.3:+every visible direct-root group has a descriptive unique `id` and positive+root-coordinate `data-pptx-bounds`; nested implementation groups carry no+bounds.++**Forbidden — group-list-first choreography**:++- Choosing effects or order from the pre-existing `list-groups` output before the content-first audit+- Keeping a coarse wrapper only because it already has an `id`+- Splitting one semantic idea into individual shapes or text lines to increase animation count+- Merging unrelated ideas to reduce animation count+- Adding animation-specific `data-*` attributes to SVG++There is no target group count. Granularity follows the page's actual claims,+comparisons, sequence, causality, and narration beats.++After any regrouping, rerun the final SVG quality gate because `svg_output/`+changed:++```bash+python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path> --stage final --json+```++Then list the **post-regroup** anchors:++```bash+python3 skills/ppt-master/scripts/animation_config.py list-groups <project_path>+```-**Hard rule**: semantic files determine animation intent; `svg_output/*.svg` determines valid animation targets. Never reference a slide or group id that is absent from the scaffold / SVG scan.+Output is one line per slide: `<slide_basename>: id1, id2, id3`. Default chrome+groups (`bg` / `*-header` / `*-footer` / `*-decor` / `nav` / `watermark` /+`logo` / `pagenumber`) are excluded. This post-regroup list is the source of+truth when planning §3 and editing §4; never invent a slide or group key.-**Optional-context fallback**: these semantic files inform this supporting stage but are not its gate artifacts. If any are absent, state what is missing and proceed with every remaining file plus real SVG group ids. If all three context inputs are absent, use only explicit user instructions, real SVG group ids, and the resolution rules in [`animations.md`](../../references/animations.md); do not infer detailed object choreography.+An explicit sidecar entry may override only the marker-free legacy id-name+heuristic. A group carrying `data-pptx-layer` or an explicit static+role/placeholder marker can never animate, even when it is named explicitly.++If `animations.json` does not exist and a starting file is useful, scaffold+only after semantic regrouping:++```bash+python3 skills/ppt-master/scripts/animation_config.py scaffold <project_path>+```++Do not read the full scaffold unless it is needed as an editing starting point.---@@ -291,7 +339,7 @@ Notes:----## 5. Validate and Export+## 5. Validate, Refresh Derived SVGs, and ExportRun sequentially:@@ -299,13 +347,18 @@ Run sequentially:python3 skills/ppt-master/scripts/animation_config.py validate <project_path>```+```bash+python3 skills/ppt-master/scripts/finalize_svg.py <project_path>+```+```bashpython3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>```**Validation**: the exported native PPTX must reflect the per-slide and-per-object overrides. `--animation none` still disables all per-element-animation and overrides `animations.json`. Unknown animation+per-object overrides, and `svg_final/` must reflect any semantic regrouping+performed in §2. `--animation none` still disables all per-element animation+and overrides `animations.json`. Unknown animationeffects/modes/triggers; boolean, NaN, or Infinity numeric values; non-positivedurations; negative delay/stagger; invalid order; missing slides/groups; andstructural-layer targets fail validation. Transition validation remains strict@@ -343,6 +396,9 @@ source effect or reduce the choreography to delay values. See- [x] `animations.json` exists only because per-slide or per-object customization was requested- [x] `design_spec.md`, `spec_lock.md`, and available speaker notes were checked before editing animation overrides+- [x] Every slide's existing `<g>` hierarchy was audited against content and narration before it was accepted or rewritten+- [x] Every animation anchor is one post-regroup semantic reveal unit with a descriptive real SVG id+- [x] Any regrouped SVG passed the final SVG quality gate and `svg_final/` was refreshed- [x] Every slide in `svg_output/` appears under `slides` with explicit `transition` + `animation` blocks- [x] Group-level entries were added only for groups that diverge from the slide's `animation` block- [x] Page transitions and in-slide object animations were planned together