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

docs(pptx-roundtrip): align native reconstruction guidance

hugohe345ca22db0f5f
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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 the
marker group. If any bound is omitted, the exporter infers the object frame
from 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, JSON
metadata, 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 may
also live under `style` as table defaults. Native table typography mirrors the
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 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.md
index 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.md
index 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.
```bash
python3 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-flat
python3 scripts/svg_to_pptx.py <project_path> --no-notes
python3 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`