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(pptx-roundtrip): align native reconstruction guidance
hugohe345ca22db0f5f
diff --git a/docs/roadmap.md b/docs/roadmap.mdindex bde1bc9a..be3f3b16 100644--- a/docs/roadmap.md+++ b/docs/roadmap.md@@ -80,7 +80,9 @@ The past two months' structural capability growth. Single flags / incremental po- **Step 4 confirmation gate restaged into a three-pass wizard + visual previews** — the single Eight-Confirmations gate became a three-stage flow in one browser session (direction anchors → design system → images / execution), each downstream stage re-derived from the user's **actual** confirmed upstream choices instead of the AI's originals — so, e.g., the image strategy fits the confirmed color system by construction. The confirm page adds visual aids for the hard-to-name picks: a bespoke real-SVG page thumbnail for each of the 18 `visual_style` options, real icon-library samples, and AI-image reference previews. `recommendations.json` now carries a canonical `stage` selector (`tier` retained only as an internal back-compat read) and user-facing wording is unified on "stage"; the chat fallback mirrors the same staged order-- **`--native-objects` hardened from dormant marker to production-quality opt-in** — the narrow native-object exception (see Non-goals below) now emits charts and pure-text tables that keep the deck's own design instead of snapping to PowerPoint's white default theme. Classic native charts write explicit chart-area / plot-area / axis-line / gridline / label-text colors — inferred from the visible SVG fallback (largest panel `<rect>` → background, fallback text → labels, fallback strokes → axis/grid) or overridden per `style` (`chart_area_fill` / `plot_area_fill` / `text_color` / `axis_color` / `grid_color`, `"none"` for transparent); the color parser normalizes named CSS colors, `#RGB` shorthand, and `rgb()` / `rgba()` to OOXML hex; bar/column series disable negative-value fill inversion so negative bars keep their series color. The activated export is named `<name>_<ts>_native_charts.pptx` to tell it apart from the default flattened-shape export. **The default route is unchanged** — charts/tables still export as SVG-derived DrawingML shapes for cross-renderer fidelity; native objects stay the deliberate opt-in trade documented under Non-goals below+- **`--native-objects` hardened from dormant marker to usable opt-in** — the narrow native-object exception (see Non-goals below) now emits charts and pure-text tables that keep the deck's own design instead of snapping to PowerPoint's white default theme. Classic native charts write explicit chart-area / plot-area / axis-line / gridline / label-text colors — inferred from the visible SVG fallback (largest panel `<rect>` → background, fallback text → labels, fallback strokes → axis/grid) or overridden per `style` (`chart_area_fill` / `plot_area_fill` / `text_color` / `axis_color` / `grid_color`, `"none"` for transparent); the color parser normalizes named CSS colors, `#RGB` shorthand, and `rgb()` / `rgba()` to OOXML hex; bar/column series disable negative-value fill inversion so negative bars keep their series color. The activated export is named `<name>_<ts>_native_charts.pptx` to tell it apart from the default flattened-shape export. **The default route is unchanged** — charts/tables still export as SVG-derived DrawingML shapes for cross-renderer fidelity; native objects stay the deliberate opt-in trade documented under Non-goals below++- **Native package structure + conservative PPTX object round-trip** — native export now keeps the base package's real blank-layout relationship and defaults to a baseline master that promotes only identical backgrounds and a safe leading prefix of repeated chrome. The standalone `pptx_to_svg.py` importer emits fallback SVG plus native metadata for supported unmerged tables and classic-chart caches; exporter-canonical solid series/slice colors and exact title/subtitle structures survive a second `--native-objects` export, while unsupported table/chart semantics remain explicit fallback-only markers---diff --git a/docs/technical-design.md b/docs/technical-design.mdindex 6ca5404c..30743719 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -429,7 +429,7 @@ These direct routes share some analysis primitives with the main pipeline, espec**Why the default native deck has a baseline master, not inferred templates.** `svg_to_pptx.py` keeps the actual blank slide layout relationship from the base package and defaults to `--pptx-structure baseline`. Baseline promotes only low-risk shared structure: identical slide backgrounds, plus a common leading prefix of repeated top-level SVG chrome whose exact id tokens say `logo`, `footer`, `header`, `watermark`, `chrome`, `pageNumber`, or `slideNumber`. Chrome promotion also requires identical generated OOXML, no slide-timing reference, and the same leading z-order across every slide sharing the master; overlay chrome stays slide-local. Image relationships for promoted chrome are copied to the slide master. This gives ordinary decks real master/layout structure without guessing reusable layouts or placeholders from visual similarity.-**Why native-object reconstruction uses markers, not automatic object replacement.** The standalone `pptx_to_svg.py` importer can emit SVG fallback content plus `data-pptx-native` metadata for supported unmerged tables and conservative classic-chart caches. It retains source table-style inheritance, supported solid cell fills/basic text formatting, chart title/legend/axis titles, and plot-level data-label flags for area/bar/column/line charts when the current schema can represent them. The default export still consumes fallback children as regular DrawingML shapes; only `--native-objects` activates editable PowerPoint tables/charts. Unsupported cases — including merged tables, direct cell borders/non-solid fills/mixed rich text, ChartEx, transformed/3D/combo charts, unsupported data-label scopes/types, custom axis semantics, trendlines/error bars, unsupported subtype options, sparse or non-finite caches, and date/formatted category axes — keep a baked preview when one exists (otherwise an explicit placeholder) and carry `data-pptx-native-status`. The quality checker and native-object export report those fallback-only objects as warnings. This importer/exporter pairing is a reconstruction aid, not a preservation-route substitute for `template-fill-pptx` or `native-enhance-pptx`.+**Why native-object reconstruction uses markers, not automatic object replacement.** The standalone `pptx_to_svg.py` importer can emit SVG fallback content plus `data-pptx-native` metadata for supported unmerged tables and conservative classic-chart caches. It retains source table-style inheritance, supported solid cell fills/basic text formatting, chart title/legend/axis titles, and plot-level data-label flags for area/bar/column/line charts when the current schema can represent them. Exporter-canonical classic charts also recover canonical solid series/slice colors and exact one- or two-paragraph title metadata. The default export still consumes fallback children as regular DrawingML shapes; only `--native-objects` activates editable PowerPoint tables/charts. Unsupported table cases — including merged cells, direct borders, non-solid fills, and mixed rich text — keep the rendered SVG table. Unsupported chart cases — including ChartEx, rotated/flipped/3D/combo charts, unsupported data-label scopes/types, custom axis semantics, trendlines/error bars, unsupported subtype options, sparse or non-finite caches, and date/formatted category axes — keep a baked preview when one exists, otherwise an explicit placeholder. Both carry `data-pptx-native-status`; the quality checker and native-object export report them as fallback-only warnings. This importer/exporter pairing is a reconstruction aid, not a preservation-route substitute for `template-fill-pptx` or `native-enhance-pptx`.---diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.mdindex 69d758d2..3afa7112 100644--- a/docs/zh/roadmap.md+++ b/docs/zh/roadmap.md@@ -82,6 +82,8 @@- **`--native-objects` 从休眠 marker 硬化为可用级 opt-in** — 那条窄「原生对象」例外(见下文 Non-goals)现在导出的图表与纯文本表格会**保留 deck 自己的设计**,不再塌回 PowerPoint 的白底默认主题。classic 原生图表显式写入 chart-area / plot-area / 轴线 / 网格线 / 标签文字颜色——从可见的 SVG fallback 推断(最大面板型 `<rect>` → 背景、fallback 文字 → 标签、fallback 描边 → 轴线/网格),或用 `style` 显式覆盖(`chart_area_fill` / `plot_area_fill` / `text_color` / `axis_color` / `grid_color`,`"none"` 表透明);颜色解析把命名色、`#RGB` 简写、`rgb()` / `rgba()` 归一为 OOXML hex;bar/column 系列关掉负值反色,负值柱保持系列色。激活导出命名为 `<name>_<ts>_native_charts.pptx` 以与默认压平形状导出区分。**默认路线不变**——图表/表格仍以 SVG 派生的 DrawingML 形状导出以保跨渲染器保真;原生对象仍是下文 Non-goals 里那条刻意的 opt-in 取舍+- **原生 package 结构 + 保守 PPTX 对象回转** — 原生导出现在保留基础 package 的真实空白版式关系,并默认使用 baseline master;只提升完全一致的背景和安全的前置重复 chrome。独立 `pptx_to_svg.py` 导入器会为受支持的未合并表格与 classic-chart cache 输出 fallback SVG 加原生元数据;由本 exporter 生成的规范纯色系列 / 切片与精确 title/subtitle 结构可经第二次 `--native-objects` 导出继续保留,无法等价表达的表格 / 图表语义则保持明确的 fallback-only marker+---## 进行中 / 下一步diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex caea29af..6d1c2a27 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -429,7 +429,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份**为什么默认 native deck 使用基线母版,而不推断模板。** `svg_to_pptx.py` 会保留基础 package 中空白版式的真实关系,并默认使用 `--pptx-structure baseline`。Baseline 只提升低风险共享结构:完全一致的页面背景,以及各页共同位于 shape 序列开头(视觉后层)、且 id 精确 token 为 `logo`、`footer`、`header`、`watermark`、`chrome`、`pageNumber` 或 `slideNumber` 的重复 SVG chrome。Chrome 还必须在共享同一母版的所有页面上生成完全一致的 OOXML、没有被页面动画引用,并保持相同的前置 z-order;覆盖在正文之上的 chrome 继续留在 slide 本地。被提升 chrome 的图片关系会复制到 slide master。这样普通 deck 能获得真实的 master/layout 结构,同时不根据视觉相似度猜测可复用版式或占位符。-**为什么原生对象重建使用 marker,而不是自动替换对象。** 独立的 `pptx_to_svg.py` 导入器会为受支持的未合并表格和保守 classic-chart cache 输出 SVG fallback,并附加 `data-pptx-native` 元数据;当现有 schema 能表达时,还会保留源表格样式继承、受支持的单元格纯色填充 / 基础文字格式,以及图表标题、图例、坐标轴标题和面积图 / 条形图 / 柱形图 / 折线图的 plot 级数据标签开关。默认导出仍把 fallback 子元素当普通 DrawingML shape 处理;只有 `--native-objects` 才会启用可编辑的 PowerPoint 表格 / 图表。合并单元格、直接边框 / 非纯色填充 / 混合富文本、ChartEx、带变换 / 3D / 组合图表、不受支持的数据标签作用域或类型、自定义坐标轴语义、趋势线 / 误差线、不受支持的子类型参数、稀疏或非有限 cache、日期 / 格式化类别轴等不支持场景,会在有 baked preview 时保留预览,否则给出明确占位符,并写入 `data-pptx-native-status`。质量检查器和 native-object 导出会把这些 fallback-only 对象报告为 warning。这对 importer/exporter 是重建辅助能力,不能替代 `template-fill-pptx` 或 `native-enhance-pptx` 的保留型路线。+**为什么原生对象重建使用 marker,而不是自动替换对象。** 独立的 `pptx_to_svg.py` 导入器会为受支持的未合并表格和保守 classic-chart cache 输出 SVG fallback,并附加 `data-pptx-native` 元数据;当现有 schema 能表达时,还会保留源表格样式继承、受支持的单元格纯色填充 / 基础文字格式,以及图表标题、图例、坐标轴标题和面积图 / 条形图 / 柱形图 / 折线图的 plot 级数据标签开关。由本 exporter 生成的规范 classic chart 还会回读规范纯色系列 / 切片,以及精确的单段或双段标题元数据。默认导出仍把 fallback 子元素当普通 DrawingML shape 处理;只有 `--native-objects` 才会启用可编辑的 PowerPoint 表格 / 图表。合并单元格、直接边框、非纯色填充、混合富文本等不支持的表格场景继续保留实际渲染的 SVG table。ChartEx、旋转 / 翻转 / 3D / 组合图表、不受支持的数据标签作用域或类型、自定义坐标轴语义、趋势线 / 误差线、不受支持的子类型参数、稀疏或非有限 cache、日期 / 格式化类别轴等不支持的图表场景,则在有 baked preview 时保留预览,否则给出明确占位符。两类对象都会写入 `data-pptx-native-status`;质量检查器和 native-object 导出将其报告为 fallback-only warning。这对 importer/exporter 是重建辅助能力,不能替代 `template-fill-pptx` 或 `native-enhance-pptx` 的保留型路线。---diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex 59409b5f..23e3e518 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -722,7 +722,8 @@ Full effect list, anchor logic, and limits: [`references/animations.md`](referen> ❌ **NEVER** substitute `cp` for `finalize_svg.py` — finalize performs multiple critical processing steps> ❌ **NEVER** force `-s output` for the legacy/preview pptx (PowerPoint's internal SVG parser drops icons and rounded corners). The default auto-split already gives native the high-fidelity source it needs without touching legacy.-> ❌ **NEVER** use `--only` (it suppresses one of the two output files)+> ❌ **NEVER** use `--only` in the standard pipeline. Keep it only for explicit+> one-product diagnostics or compatibility checks.> **Post-export annotation window**: the preview service from Step 6 typically remains running after export. If the user submitted annotations in the browser (during Executor or after export) and now asks to apply them — they may quote the browser prompt (`Changes saved to svg_output...` / `修改已保存到 svg_output...`), say "apply my annotations" / "应用注解" / equivalent — run [`live-preview`](workflows/live-preview.md) Step 2 to apply and re-export. Annotations submitted during generation are also handled here, not earlier.diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.mdindex 4c11c203..646d926b 100644--- a/skills/ppt-master/references/shared-standards.md+++ b/skills/ppt-master/references/shared-standards.md@@ -337,7 +337,7 @@ Full reference: [`animations.md`](animations.md).**Prohibited**:- NEVER use `cp` as a substitute for `finalize_svg.py`- NEVER force `-s output` for the legacy/preview pptx (PowerPoint's internal SVG parser drops icons and rounded corners). Default auto-split already gives native the high-fidelity source it needs without affecting legacy.-- NEVER use `--only` (it suppresses one of the two output files)+- NEVER use `--only` in the standard pipeline; keep it for explicit one-product diagnostics or compatibility checks> Source-directory split: by default `svg_to_pptx.py` reads `svg_output/` for the native pptx (preserves icon `<use>`, image `preserveAspectRatio` as native picture-crop metadata, rounded rect `rx/ry` → `prstGeom roundRect`) and `svg_final/` for the legacy/preview pptx (PowerPoint's internal SVG parser needs the flattened form). Pass `-s output` or `-s final` only when you specifically want both products to read from a single source.@@ -690,7 +690,7 @@ The child `<path>`'s `stroke` becomes the foreground color (the pattern's line c> `svg_quality_checker.py` warns on missing `data-pptx-pattern` and errors on values outside the enum. Catch these pre-export — PowerPoint's repair dialog hides which pattern broke.-### Native PPTX Table / Chart Markers (Experimental)+### Native PPTX Table / Chart Markers (Opt-in)Native PowerPoint tables and Excel-backed charts activate at export time only. The default chart/table route remains hand-authored SVG geometry so the deck stays pixel-stable across PowerPoint / Keynote / LibreOffice / WPS.@@ -709,7 +709,12 @@ Native PowerPoint tables and Excel-backed charts activate at export time only. T`data-pptx-x` / `data-pptx-y` / `data-pptx-width` / `data-pptx-height` on themarker group. If any bound is omitted, the exporter infers the object framefrom the visible fallback geometry; this keeps SVG fallback and native object-placement aligned.+placement aligned. Complete explicit bounds are absolute slide coordinates;+marker/ancestor `translate` and `scale` transforms apply only when at least one+bound is inferred. `x`, `y`, `width`, and `height` must be finite and resolve+inside PowerPoint's 32-bit DrawingML coordinate range; `width` and `height`+must resolve to at least one EMU. Native table frames must additionally resolve+to at least one EMU per resolved row and column.**Validation**: `svg_quality_checker.py` validates native marker kind, JSONmetadata, bounds/fallback availability, table rows/columns, supported chart@@ -735,8 +740,13 @@ type, and chart data shape before export.**Table schema**: Native tables are rectangular DrawingML grids. Use `columns`for the optional header row and `rows` for body rows; shorter rows are padded-with blank cells unless `strict_grid: true` is set. Use `column_widths` and-`row_heights` as relative weights. Cell objects accept `text`, `fill`, `color`,+with blank cells unless `strict_grid: true` is set. Tables may contain at most+1000 resolved rows and 1000 resolved columns. Use `column_widths` and+`row_heights` as relative weights. Weight lists must match the resolved grid,+contain finite non-negative numbers, and include at least one positive value.+If present, `header_rows` must be an integer from `0` through the resolved row+count. Write `strict_grid`, `style.band_row`, and cell `bold` as JSON booleans.+Cell objects accept `text`, `fill`, `color`,`align`, `valign`, `bold`, `font_size`, `padding`, `border_color`, and`border_width`; the same `padding`, `border_color`, and `border_width` keys mayalso live under `style` as table defaults. Native table typography mirrors thediff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex 2b4a9eee..f89db72d 100644--- a/skills/ppt-master/scripts/README.md+++ b/skills/ppt-master/scripts/README.md@@ -118,7 +118,13 @@ python3 scripts/svg_to_pptx.py <project_path>Native `svg_to_pptx.py` also defaults to `--pptx-structure baseline`: the generated deck keeps a standard master/layout relationship and promotes identical native slide backgrounds into the slide master. A shared leading prefix of top-level SVG elements with exact chrome id tokens such as `logo`, `footer`, `header`, `watermark`, `chrome`, `pageNumber`, or `slideNumber` may also be promoted when its generated OOXML is identical, it is not referenced by slide timing, and moving it behind slide-local content preserves z-order; image relationships are copied to the master. Use `--pptx-structure flat` when all generated backgrounds and chrome must remain slide-local for debugging or comparison.-`pptx_to_svg.py` annotates supported unmerged tables and conservative classic-chart caches with `data-pptx-native` metadata. Source table-style inheritance, supported solid cell fills/basic text formatting, chart title/legend/axis titles, and plot-level data-label flags for area/bar/column/line charts are retained when the current schema can represent them. Tables with direct borders, non-solid fills, or mixed rich-text formatting remain fallback-only, as do charts with unsupported label scopes/types, custom axis semantics, trendlines/error bars, or subtype options. Unsupported objects keep their SVG preview (or an explicit placeholder when the source has no baked preview) and carry `data-pptx-native-status`; `svg_quality_checker.py` and `svg_to_pptx.py --native-objects` report those fallback-only objects as warnings.+`pptx_to_svg.py` annotates supported unmerged tables and conservative classic-chart caches with `data-pptx-native` metadata. Source table-style inheritance, supported solid cell fills/basic text formatting, chart title/legend/axis titles, and plot-level data-label flags for area/bar/column/line charts are retained when the current schema can represent them. Tables with direct borders, non-solid fills, or mixed rich-text formatting remain fallback-only, as do charts with unsupported label scopes/types, custom axis semantics, trendlines/error bars, or subtype options. Unsupported tables keep their rendered SVG table; unsupported charts keep a baked preview or explicit placeholder. Both carry `data-pptx-native-status`, which `svg_quality_checker.py` and `svg_to_pptx.py --native-objects` report as a warning.++Exporter-canonical classic charts also recover canonical solid series/slice+colors and exact one- or two-paragraph title styling; two paragraphs retain+their `title` / `subtitle` roles. Slide-number fields resolve to the display+number defined by `firstSlideNum`; standalone master/layout SVGs retain their+literal field fallback because they are shared by multiple slides.Image generation:@@ -153,4 +159,4 @@ python3 scripts/update_repo.py --skip-pip- [Troubleshooting](./docs/troubleshooting.md)- [Skill Entry](../SKILL.md)-_Last updated: 2026-04-09_+_Last updated: 2026-07-10_diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.mdindex cf193d8e..f32f1e32 100644--- a/skills/ppt-master/scripts/docs/conversion.md+++ b/skills/ppt-master/scripts/docs/conversion.md@@ -228,6 +228,36 @@ Usage boundary:- Beautify promotes selected identity/content fields into locked constraints after confirmation.- Template-fill uses the slide library as the native PPTX fill contract.+## `pptx_to_svg.py`++Reconstruct a PPTX package as editable SVG views by reading OOXML directly.++```bash+python3 scripts/pptx_to_svg.py deck.pptx --inheritance-mode both+python3 scripts/pptx_to_svg.py deck.pptx --inheritance-mode layered+python3 scripts/pptx_to_svg.py deck.pptx --inheritance-mode flat+```++| Mode | Output |+|---|---|+| `both` (default) | Layered master/layout/slide SVGs under `svg/`, plus self-contained slides under `svg-flat/` |+| `layered` | Only the layered `svg/` view and inheritance metadata |+| `flat` | One self-contained slide SVG per page under `svg/` |++Supported unmerged tables and conservative classic-chart caches carry+`data-pptx-native` metadata beside their SVG fallback. Markers remain dormant+unless a later export uses `--native-objects`. Unsupported tables keep their+rendered SVG table; unsupported charts keep a baked preview or explicit+placeholder. Both carry `data-pptx-native-status`.++Exporter-canonical charts recover canonical solid series/slice colors and exact+one- or two-paragraph title styling; two paragraphs retain their `title` /+`subtitle` roles. This is not a general source-chart style round-trip guarantee.++Concrete slide SVGs resolve `<a:fld type="slidenum">` using the presentation's+`firstSlideNum` display numbering. Standalone master/layout SVGs keep the+literal field fallback because one shared part can serve multiple slides.+## `source_to_md/web_to_md.py`Convert web pages to Markdown and download images locally.diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.mdindex 849c36e6..4a446998 100644--- a/skills/ppt-master/scripts/docs/svg-pipeline.md+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md@@ -30,8 +30,9 @@ Convert project SVGs into PPTX.```bashpython3 scripts/svg_to_pptx.py <project_path>-python3 scripts/svg_to_pptx.py <project_path> --only native-python3 scripts/svg_to_pptx.py <project_path> --only legacy+python3 scripts/svg_to_pptx.py <project_path> --native-objects+python3 scripts/svg_to_pptx.py <project_path> --pptx-structure flat # structure diagnostic+# Template-import visual round-trip diagnostic only:python3 scripts/svg_to_pptx.py <template_import_output> --only native -s svg-flatpython3 scripts/svg_to_pptx.py <project_path> --no-notespython3 scripts/svg_to_pptx.py <project_path> -t none@@ -55,7 +56,8 @@ Behavior:- With `--no-merge`: every dy-stacked `<tspan>` becomes its own text frame — exact SVG line layout is preserved but a 12-line paragraph is 12 separate textboxes- Side effect: PowerPoint may wrap merged paragraphs to a different line count than the SVG source. Long body text (abstracts, multi-paragraph sections, reference lists) usually benefits from the default; pages with tight typographic alignment (covers, charts, tables) usually want `--no-merge`- Mergeable detection is conservative: only fires when the children form a clean paragraph block; mixed-layout `<text>` falls through to the default per-line path-- Recommended source directory: `svg_final/`+- Native export reads `svg_output/`; `--svg-snapshot` and legacy export read+ `svg_final/`. Use `-s` only as an explicit diagnostic override.- For PPTX template-import workspaces, use `-s svg-flat` when you need a visual round-trip check. The layered `svg/` tree is the machine-readable template source and intentionally does not inline inherited master / layout decoration into each slide.- Native mode is strict about unsupported visual SVG elements: if a visual element cannot be represented or safely preserved, export fails with the SVG file, element tag, and position instead of silently dropping content.- Native output uses content-hash media filenames, so identical images are reused and different images cannot overwrite each other by sharing a basename.@@ -78,7 +80,12 @@ Behavior:- Start mode is set by `--animation-trigger`, mirroring PowerPoint's Start dropdown: `after-previous` (default, cascade with `--animation-stagger` spacing on slide entry), `on-click` (presenter-paced), `with-previous` (all together on slide entry)- `on-click` is for live presentations only; recorded narration rejects it because the tool does not generate object-level click timings- Flat SVG roots without top-level groups fall back to at most 8 visible primitives; beyond that, animation is skipped on the slide-- `auto` (default) maps effect from the group's SVG id: information-dense elements get a single stable effect (chart→wipe, card-/step-/pillar-→fly, title/takeaway→fade); image-like ids (hero/figure-/image/img-/kpi) cycle through a richer visual pool (zoom/dissolve/circle/box/diamond/wheel) so multiple images vary across the deck; unmatched ids cycle through a fade/wipe/fly/zoom fallback pool+- Per-element animation defaults to `none`. `auto` is opt-in (`-a auto`) and maps+ effects from the group's SVG id: information-dense elements get a stable+ effect (chart→wipe, card-/step-/pillar-→fly, title/takeaway→fade); image-like+ ids (hero/figure-/image/img-/kpi) cycle through a richer pool+ (zoom/dissolve/circle/box/diamond/wheel), while unmatched ids cycle through+ fade/wipe/fly/zoom.- `mixed` (legacy) is deterministic: the first animated group on each slide uses `fade`, then later groups cycle through a larger 16-effect pool across the whole deck; `random` samples from that same legacy pool- `--animation-duration` controls per-element entrance length (default `0.4`); `--animation-stagger` adds gap between elements in `after-previous` mode (default `0.5`)- Optional object-level overrides live in `<project>/animations.json` or a path passed via `--animation-config`; build and validate them with `animation_config.py scaffold|validate`