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

feat(svg_to_pptx): auto-skip chrome groups in animation cascade

hugohe352692d076739
diff --git a/docs/animations.md b/docs/animations.md
index 4f66ff7b..04a81226 100644
--- a/docs/animations.md
+++ b/docs/animations.md
@@ -62,9 +62,11 @@ Flags:
## Anchor Logic — Top-Level `<g id="...">`
-Per-element animations are anchored on **top-level `<g id="...">` groups** in the SVG (e.g. `<g id="cover-title">`, `<g id="card-1">`). One group = one click reveal.
+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">`). One group = one click reveal.
-Aim for **3–8 semantic groups per slide**. This is also the granularity PowerPoint uses for group-select / group-move, so it improves editing ergonomics regardless of animation.
+Aim for **3–8 content groups per slide**. This is also the granularity PowerPoint uses for group-select / group-move, so it improves editing ergonomics regardless of animation.
+
+**Chrome groups skip the cascade automatically.** Top-level groups that look like page chrome (background, header/footer, decorations, watermark, page number) are excluded from the click sequence and appear together with the slide. Detection is done on the `id`: after splitting on `-` and `_`, if any token matches `background` / `bg` / `decoration` / `decorations` / `decor` / `header` / `footer` / `chrome` / `watermark` / `pagenumber` / `pagenum`, the group is treated as chrome. Examples that auto-skip: `<g id="background">`, `<g id="bg-texture">`, `<g id="cover-footer">`, `<g id="p03-header">`, `<g id="bottom-decor">`, `<g id="watermark">`. Examples that still animate: `<g id="card-1">`, `<g id="cover-title">`, `<g id="step-discover">`. Don't strip the `<g>` wrapper to avoid animation — keep it (PowerPoint group-select needs it) and just name it appropriately.
**Fallback for flat SVGs** (no top-level `<g>` wrappers, only raw `<rect>` / `<text>` / `<path>` at the root):
diff --git a/docs/zh/animations.md b/docs/zh/animations.md
index a75866b9..49a09d41 100644
--- a/docs/zh/animations.md
+++ b/docs/zh/animations.md
@@ -62,9 +62,11 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade --an
## 锚点机制 — 顶层 `<g id="...">`
-页内动画锚定在 SVG 的**顶层 `<g id="...">` 组**上(如 `<g id="cover-title">`、`<g id="card-1">`),一个组对应一次点击入场。
+页内动画锚定在 SVG 的**顶层 `<g id="...">` 内容组**上(如 `<g id="cover-title">`、`<g id="card-1">`),一个组对应一次点击入场。
-每页建议 **3–8 个语义组**。这同时也是 PowerPoint 框选 / 整体移动的颗粒度,与是否启用动画无关,都能改善编辑体验。
+每页建议 **3–8 个内容组**。这同时也是 PowerPoint 框选 / 整体移动的颗粒度,与是否启用动画无关,都能改善编辑体验。
+
+**装饰类分组自动跳过。** 顶层中看起来属于页面装饰的组(背景、页头页脚、装饰元素、水印、页码)会被排除在点击序列外,跟随页面立即显示。识别基于 `id`:按 `-` 和 `_` 切分后,若任一 token 命中 `background` / `bg` / `decoration` / `decorations` / `decor` / `header` / `footer` / `chrome` / `watermark` / `pagenumber` / `pagenum`,则视为装饰类。会自动跳过的例子:`<g id="background">`、`<g id="bg-texture">`、`<g id="cover-footer">`、`<g id="p03-header">`、`<g id="bottom-decor">`、`<g id="watermark">`。仍会动画的例子:`<g id="card-1">`、`<g id="cover-title">`、`<g id="step-discover">`。**不要为了规避动画去掉 `<g>` 包裹**——保留分组(PowerPoint 框选需要),只要给个合适的 id 即可。
**扁平 SVG 的回退逻辑**(顶层没有 `<g>`,只有裸 `<rect>` / `<text>` / `<path>`):
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index f013c3dd..1d8fdcb7 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -249,7 +249,9 @@ Wrap logically related elements in top-level `<g id="...">` groups. Produces Pow
> ⚠️ Only `<g opacity="...">` is banned (§2). Plain `<g>` for grouping is required.
-**Animation-ready rule**: direct children of `<svg>` should be semantic groups, not raw drawing atoms. Aim for **3–8 top-level `<g id>` groups per slide**; each group should correspond to one presenter click if page-level animation is enabled.
+**Animation-ready rule**: direct children of `<svg>` should be semantic groups, not raw drawing atoms. Aim for **3–8 top-level content `<g id>` groups per slide** (the 3–8 budget excludes page chrome — see below); each content group should correspond to one presenter click if page-level animation is enabled.
+
+**Chrome groups are excluded automatically.** The exporter treats top-level groups whose id contains chrome tokens as page chrome and skips them in the animation cascade — they appear together with the slide rather than requiring a click. Tokens (matched against id after splitting on `-` / `_`): `background`, `bg`, `decoration` / `decorations` / `decor`, `header`, `footer`, `chrome`, `watermark`, `pagenumber` / `pagenum` / `page-number`. So `<g id="bg-texture">`, `<g id="cover-footer">`, `<g id="p03-header">`, `<g id="bottom-decor">` all skip animation while keeping their `<g>` wrapper for editing/grouping. Use these naming conventions for chrome — do **not** strip the `<g>` wrapper.
**What to group**:
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
index 49cbe728..72998204 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
@@ -20,6 +20,34 @@ from .drawingml_elements import (
)
+# ---------------------------------------------------------------------------
+# Animation anchor selection
+# ---------------------------------------------------------------------------
+
+# Tokens that mark a top-level <g id="..."> as page chrome rather than animated
+# content. When any token (after splitting id on '-' and '_') matches, the group
+# is excluded from the per-element entrance animation cascade so background,
+# header/footer, decorations etc. appear together with the slide instead of
+# requiring presenter clicks.
+_CHROME_ID_TOKENS = frozenset({
+ 'background', 'bg',
+ 'decoration', 'decorations', 'decor',
+ 'header', 'footer',
+ 'chrome', 'watermark',
+ 'pagenumber', 'pagenum',
+})
+
+
+def _is_chrome_id(elem_id: str | None) -> bool:
+ if not elem_id:
+ return False
+ lower = elem_id.lower()
+ if lower.replace('-', '').replace('_', '') in _CHROME_ID_TOKENS:
+ return True
+ tokens = re.split(r'[-_]', lower)
+ return any(t in _CHROME_ID_TOKENS for t in tokens if t)
+
+
# ---------------------------------------------------------------------------
# Transform & layout helpers
# ---------------------------------------------------------------------------
@@ -119,7 +147,7 @@ def convert_g(elem: ET.Element, ctx: ConvertContext) -> ShapeResult | None:
# <p:grpSp> to anchor a timing target on, and nested groups are
# ignored to keep the animation budget at ~per-section granularity.
elem_id = elem.get('id')
- if ctx.depth == 0 and elem_id:
+ if ctx.depth == 0 and elem_id and not _is_chrome_id(elem_id):
ctx.anim_targets.append((group_id, elem_id))
group_effect = ''