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(formula): describe the preview fallback for non-PowerPoint clients

hugohe37e4f855e83ee
diff --git a/docs/faq.md b/docs/faq.md
index 4e92d92b..a5ffe894 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -212,8 +212,8 @@ assets. A block uses a formula group; inline math uses a leaf
`<tspan data-pptx-inline-formula="...">preview</tspan>` among ordinary text
runs. Matrices, multiline derivations, and other high-structure expressions
remain blocks. Raw LaTeX does not render in SVG, so each marker carries an
-ordinary visible preview that native export replaces without adding an image
-fallback.
+ordinary visible preview; native export keeps it as a native-shape fallback
+for clients without Office Math, never an image.
Forward compilation covers every explicitly named input in Microsoft's
documented Microsoft 365 2606 / Mac 16.110 LaTeX profile and 2605 / 16.109
@@ -231,8 +231,8 @@ executable source profile is pinned to the Microsoft documentation versions
above. Repository verification covers compiler behavior, OMML structure, and
PPTX packaging rather than complete Microsoft 365 UI rendering/editability
certification. Formula display and editability in Keynote, WPS, LibreOffice,
-and other non-PowerPoint clients are not supported; PPT Master does not add an
-image fallback for them.
+and other non-PowerPoint clients are not supported; those clients show the
+SVG preview fallback as ordinary shapes and text, not editable math.
## Q: Can generated slides contain clickable links?
diff --git a/docs/powerpoint-svg-mapping.md b/docs/powerpoint-svg-mapping.md
index cd387dae..eb21073a 100644
--- a/docs/powerpoint-svg-mapping.md
+++ b/docs/powerpoint-svg-mapping.md
@@ -215,15 +215,16 @@ The exhaustive chart/table schemas and supported family list intentionally remai
| Editable block equation | One `<g data-pptx-replace-with="formula">` with explicit bounds, source LaTeX in `<metadata type="application/json">`, and visible SVG preview children | PowerPoint text shape containing `a14:m > m:oMathPara > m:oMath` | See the input-profile row | Matrices, multiline derivations, and other standalone high-structure formulas use the registered block contract |
| Editable inline formula | A leaf `<tspan data-pptx-inline-formula="canonical LaTeX body">preview text</tspan>` among ordinary text runs | The same DrawingML `a:p` retains surrounding runs and inserts `a14:m > m:oMath` | See the input-profile row | Direct non-empty preview text only; no child element, positional `x/y/dx/dy`, structured placeholder/Master/Layout ownership, preserved imported `txBody`, or native-replacement ancestor |
| PPTX formula reverse import | Validator-clean `m:oMathPara` becomes a block marker; validator-clean `m:oMath` remains an inline marker with surrounding runs | Re-export recompiles the canonicalized LaTeX to editable OMML | `Native-normalized` for PPT Master-owned closed OMML vocabulary | The original LaTeX spelling is not recoverable; unknown third-party OMML gets `formula-not-reconstructed`, readable text, and relationship-free opaque `txBody` retention in tolerant mode |
-| Browser / live preview | Ordinary SVG children inside a block marker, or the inline marker's direct text | Only the registered preview is discarded when native math is written | Raw LaTeX does not render in SVG | Preview content must express the same formula; it is not a PPTX fallback |
+| Browser / live preview | Ordinary SVG children inside a block marker, or the inline marker's direct text | The registered preview becomes the native-shape `mc:Fallback` beside the native math | Raw LaTeX does not render in SVG | Preview content must express the same formula; non-PowerPoint clients show it |
| Formula typography | Block payload style, or computed inline text-run style | Math inherits size and visible solid fill, then uses the project text language and Cambria Math; local `\color` / `\textcolor` scopes override the inherited fill on selectable runs and structural controls, while `\boldsymbol` / `\bm` also styles structural control glyphs | PowerPoint 2010+ OMML | High-structure or multiline math remains block-level |
-| Non-PowerPoint formula playback | The same native markers; no picture branch | No compatibility fallback is added | Keynote, WPS, LibreOffice, and other clients are outside the formula contract | Do not claim cross-client rendering or editability |
+| Non-PowerPoint formula playback | The same native markers | `mc:Fallback` carries the SVG preview as ordinary shapes and text; no picture branch | Keynote, WPS, LibreOffice, and other clients are outside the formula contract | The fallback is visible, not editable math; do not claim cross-client rendering or editability |
Formula replacement is always active and does not use
`--native-charts-and-tables`. It creates no `formula_manifest.json`, formula
PNG, media relationship, or `mc:Fallback` picture. Block JSON and inline
`data-pptx-inline-formula` values are the native formula sources; SVG preview
-content exists only so the authored page remains visible before export.
+content keeps the authored page visible before export and becomes the
+native-shape `mc:Fallback` after it. Import reads the `mc:Choice` branch only.
`pptx_to_svg.py` performs the narrow inverse only for OMML accepted by the same
closed validator, and its output is canonical LaTeX rather than the author's
original spelling. It does not claim arbitrary Office Math conversion.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 367a746a..0a5f5f2c 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -45,7 +45,7 @@ A presentation is four layers: what is on the slide, how it is arranged, how it
| Charts | Systematized | Dedicated authoring reference; SVG by default, native Chart replacement available as an explicit opt-in |
| Tables | Systematized | Dedicated authoring reference; six reusable cell-grid references, with custom grids still available; native Table replacement uses the same opt-in |
| Diagrams | Systematized | Six relationship atoms — `order`, `link`, `parent`, `membership`, `contrast`, `overlap` |
-| Formulas | Systematized | Standalone block and same-paragraph inline formulas compile every explicitly documented Microsoft 365 LaTeX / mhchem input to editable OMML, with documented native normalizations and fail-closed handling outside the profile. PPTX import rebuilds validator-clean, PPT Master-owned OMML into normalized formula markers with visible SVG previews; arbitrary third-party OMML and original LaTeX spelling recovery remain outside the contract. No image fallback is emitted. The package target remains PowerPoint 2010+; the executable profile is pinned to the stated Microsoft documentation versions, while repository verification is compiler/OMML/package-level rather than complete Microsoft 365 UI certification. Non-PowerPoint clients remain outside the contract |
+| Formulas | Systematized | Standalone block and same-paragraph inline formulas compile every explicitly documented Microsoft 365 LaTeX / mhchem input to editable OMML, with documented native normalizations and fail-closed handling outside the profile. PPTX import rebuilds validator-clean, PPT Master-owned OMML into normalized formula markers with visible SVG previews; arbitrary third-party OMML and original LaTeX spelling recovery remain outside the contract. Non-PowerPoint clients get the SVG preview as a native-shape `mc:Fallback`, never an image. The package target remains PowerPoint 2010+; the executable profile is pinned to the stated Microsoft documentation versions, while repository verification is compiler/OMML/package-level rather than complete Microsoft 365 UI certification. Non-PowerPoint clients remain outside the contract |
| Narration & animation audio | Systematized | Per-slide narration audio, plus native transition and object sounds drawn from the bundled CC0 catalog |
| Arbitrary video & background music | Not planned | A one-off, content-specific insert that is faster to place by hand in PowerPoint, and the AI cannot pick the file for you. Background music additionally pulls in narration-mixing decisions that are out of scope. Media already present in a source deck is preserved unchanged through Edit Native PPTX |
| SmartArt | Asymmetric by design | Source diagram parts are read for their content and structure; generated decks redraw that content through the ordinary shape pipeline. DiagramML is never edited and native SmartArt regeneration is not promised |
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index a211a5a3..6507a319 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -210,7 +210,8 @@ PPT Master 没有文档化的 `wireframe` 运行模式,也没有跨版本视
group;行内公式使用夹在普通文本 run 中的叶子
`<tspan data-pptx-inline-formula="...">preview</tspan>`。矩阵、多行推导等
高结构表达仍使用块级形式。原始 LaTeX 不能直接在 SVG 中显示,因此每个
-marker 都携带普通可见预览;原生导出会替换该预览,不增加图片兜底。
+marker 都携带普通可见预览;原生导出把它保留为原生形状兜底,供不支持 Office Math
+的客户端显示,不使用图片。
前向编译覆盖 Microsoft 文档中 Microsoft 365 2606 / Mac 16.110 LaTeX
档位与 2605 / 16.109 mhchem 档位明确点名的全部输入,包括符号、结构、环境、
@@ -224,8 +225,8 @@ fallback 保留。
生成的 OMML 仍以 PowerPoint 2010+ 包为目标,可执行输入档位锁定到上述
Microsoft 文档版本。仓库验证覆盖编译器行为、OMML 结构与 PPTX 打包,不等同于
完整的 Microsoft 365 UI 显示 / 编辑认证。Keynote、WPS、LibreOffice 等非
-PowerPoint 客户端中的公式显示与编辑能力不在支持范围内;PPT Master 不为这些
-客户端附加公式图片兜底。
+PowerPoint 客户端中的公式显示与编辑能力不在支持范围内;这些客户端显示以普通
+形状和文字写入的 SVG 预览兜底,而不是可编辑公式。
## Q: 生成的页面可以带可点击链接吗?
diff --git a/docs/zh/powerpoint-svg-mapping.md b/docs/zh/powerpoint-svg-mapping.md
index 37da6094..3489655c 100644
--- a/docs/zh/powerpoint-svg-mapping.md
+++ b/docs/zh/powerpoint-svg-mapping.md
@@ -210,14 +210,15 @@ PowerPoint 原生 Chart/Table 对象是可选功能。默认导出保留 SVG fal
| 可编辑块级公式 | 一个带显式边界、在 `<metadata type="application/json">` 中保存源 LaTeX、并含可见 SVG 预览子元素的 `<g data-pptx-replace-with="formula">` | 含 `a14:m > m:oMathPara > m:oMath` 的 PowerPoint 文本 shape | 见输入档位行 | 矩阵、多行推导等独立高结构公式使用块级合同 |
| 可编辑行内公式 | 普通文本 run 中的叶子 `<tspan data-pptx-inline-formula="规范 LaTeX body">preview text</tspan>` | 同一 DrawingML `a:p` 保留前后 run,并插入 `a14:m > m:oMath` | 见输入档位行 | 只允许非空直接预览文本;禁止子元素、`x/y/dx/dy`、结构化 placeholder / Master / Layout 归属、保留的导入 `txBody` 或原生替换祖先 |
| PPTX 公式反向导入 | 通过校验的 `m:oMathPara` 变为块级 marker;通过校验的 `m:oMath` 与前后 run 一起保留为行内 marker | 再导出时把规范化 LaTeX 编译回可编辑 OMML | 对 PPT Master 自有封闭 OMML 词汇为 `Native-normalized` | 无法恢复原 LaTeX 写法;未知第三方 OMML 在 tolerant 模式下产生 `formula-not-reconstructed`、可读文本,并在无 relationship 时以不透明 `txBody` 保留 |
-| 浏览器 / 实时预览 | 块级 marker 内的普通 SVG 子元素,或行内 marker 的直接文本 | 写入原生公式时只丢弃已登记预览 | 原始 LaTeX 不能直接在 SVG 中渲染 | 预览必须表达同一公式;它不是 PPTX 兜底 |
+| 浏览器 / 实时预览 | 块级 marker 内的普通 SVG 子元素,或行内 marker 的直接文本 | 已登记预览转为原生公式旁的原生形状 `mc:Fallback` | 原始 LaTeX 不能直接在 SVG 中渲染 | 预览必须表达同一公式;非 PowerPoint 客户端显示它 |
| 公式字体 | 块级 payload 样式,或行内文本 run 的计算样式 | 公式继承字号与可见纯色填充,并使用项目文本语言和 Cambria Math;局部 `\color` / `\textcolor` 作用域会覆盖可选中文字 run 与结构控制符的继承填充,`\boldsymbol` / `\bm` 也会设置结构控制字形的样式 | PowerPoint 2010+ OMML | 高结构或多行数学内容仍使用块级形式 |
-| 非 PowerPoint 客户端播放 | 同一类原生 marker;没有图片分支 | 不附加兼容兜底 | Keynote、WPS、LibreOffice 等客户端不在公式合同内 | 不宣称跨客户端显示或编辑能力 |
+| 非 PowerPoint 客户端播放 | 同一类原生 marker | `mc:Fallback` 以普通形状和文字承载 SVG 预览;没有图片分支 | Keynote、WPS、LibreOffice 等客户端不在公式合同内 | 兜底只可见、不是可编辑公式;不宣称跨客户端显示或编辑能力 |
公式替换始终启用,不使用 `--native-charts-and-tables`。该路径不会创建
`formula_manifest.json`、公式 PNG、media relationship 或作为图片的
`mc:Fallback`。块级 JSON 和行内 `data-pptx-inline-formula` 的值是原生公式源;
-SVG 预览内容只负责让导出前的作者页面保持可见。
+SVG 预览内容让导出前的作者页面保持可见,导出后成为原生形状 `mc:Fallback`。
+导入只读取 `mc:Choice` 分支。
`pptx_to_svg.py` 只对通过同一封闭校验器的 OMML 执行窄反向导入,产出的是
规范化 LaTeX,而不是作者原始写法;它不宣称任意 Office Math 转换。
可执行闭合集与锁定的 Microsoft 来源修订记录在 `formula_profile.py`;Microsoft
diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.md
index 90e189ab..d24fa81a 100644
--- a/docs/zh/roadmap.md
+++ b/docs/zh/roadmap.md
@@ -45,7 +45,7 @@
| 图表 | 系统化 | 有专属创作 reference;默认 SVG,原生 Chart 替换为显式 opt-in |
| 表格 | 系统化 | 有专属创作 reference;六种可复用的单元格网格参考,仍可自定义网格;原生 Table 替换走同一 opt-in |
| 关系图 | 系统化 | 六个关系原子——`order`、`link`、`parent`、`membership`、`contrast`、`overlap` |
-| 公式 | 系统化 | 独立块级公式与同段行内公式可把 Microsoft 365 LaTeX / mhchem 文档中所有明确点名的输入编译为可编辑 OMML,并遵循文档规定的原生归一化,档位外输入直接失败。PPTX 导入可把通过校验的 PPT Master 自有 OMML 恢复为带可见 SVG 预览的规范公式 marker;任意第三方 OMML 与原始 LaTeX 写法恢复仍不在合同内。不生成图片兜底。包目标仍为 PowerPoint 2010+;可执行档位锁定到所述 Microsoft 文档版本,仓库验证覆盖编译器、OMML 与包结构,不等同于完整的 Microsoft 365 UI 认证。非 PowerPoint 客户端仍不在合同内 |
+| 公式 | 系统化 | 独立块级公式与同段行内公式可把 Microsoft 365 LaTeX / mhchem 文档中所有明确点名的输入编译为可编辑 OMML,并遵循文档规定的原生归一化,档位外输入直接失败。PPTX 导入可把通过校验的 PPT Master 自有 OMML 恢复为带可见 SVG 预览的规范公式 marker;任意第三方 OMML 与原始 LaTeX 写法恢复仍不在合同内。非 PowerPoint 客户端得到以原生形状写入 `mc:Fallback` 的 SVG 预览,不生成图片兜底。包目标仍为 PowerPoint 2010+;可执行档位锁定到所述 Microsoft 文档版本,仓库验证覆盖编译器、OMML 与包结构,不等同于完整的 Microsoft 365 UI 认证。非 PowerPoint 客户端仍不在合同内 |
| 旁白与动画音效 | 系统化 | 逐页旁白音频,以及取自内置 CC0 音效库的原生转场与对象音效 |
| 任意视频与背景音乐 | 暂不考虑 | 属于一次性、内容特定的插入动作,在 PowerPoint 里手动放进去更快,AI 也无法替你挑文件。背景音乐还会牵出旁白混音决策,那在范围之外。来源 deck 中已有的媒体在 Edit Native PPTX 路线中原样保留 |
| SmartArt | 有意的不对称 | 读取来源 diagram part 的内容与结构;生成 deck 用普通形状管线把这些内容重画出来。从不编辑 DiagramML,也不承诺原生 SmartArt 再生 |
diff --git a/skills/ppt-master/references/native-formula.md b/skills/ppt-master/references/native-formula.md
index 89bdeec1..8ad0398c 100644
--- a/skills/ppt-master/references/native-formula.md
+++ b/skills/ppt-master/references/native-formula.md
@@ -57,7 +57,7 @@ Formula handling is not a user-confirmed policy, image resource, manifest, or `s
**Hard rule — block metadata is truth**: one direct `<metadata type="application/json">` child with non-empty `latex`, `display: block`, `font_size` in `(0, 400]`, a visible `color`, and `align: left|center|right`; finite `data-pptx-x/y`, positive `data-pptx-width/height`, and matching root-coordinate `data-pptx-bounds`. Export replaces the whole group with `a14:m > m:oMathPara > m:oMath`.
-**Hard rule — preview is SVG, never fallback**: every preview is semantically equivalent ordinary SVG text/shapes/lines/paths — no `<image>`, `<foreignObject>`, visible raw LaTeX, or runtime renderer. The exporter discards the preview and emits no picture branch.
+**Hard rule — preview is ordinary SVG**: every preview is semantically equivalent ordinary SVG text/shapes/lines/paths — no `<image>`, `<foreignObject>`, visible raw LaTeX, or runtime renderer. Export keeps it as the native-shape fallback that non-PowerPoint clients show in place of the math.
---
@@ -67,4 +67,4 @@ Formula handling is not a user-confirmed policy, image resource, manifest, or `s
**Hard rule — repair LaTeX upstream**: unsupported source or an invalid marker blocks the page. Rewrite within the profile without changing the planned mathematics, or return it to the content owner. Never substitute a PNG, flatten structural math into ordinary text, hand-write OMML, or leave raw LaTeX visible.
-**Validation**: planned LaTeX can be compile-checked before authoring ([`svg-pipeline.md`](../scripts/docs/svg-pipeline.md) § svg_to_pptx); the early/final SVG checker validates every marker, compiles its LaTeX, and applies the shared native-height envelope to page/module text bounds; native export repeats validation and uses that envelope for the generated text frame. Output is standard editable Office Math for PowerPoint 2010+; WPS, Keynote, and LibreOffice receive no embedded fallback and are outside the rendering/editability contract.
+**Validation**: planned LaTeX can be compile-checked before authoring ([`svg-pipeline.md`](../scripts/docs/svg-pipeline.md) § svg_to_pptx); the early/final SVG checker validates every marker, compiles its LaTeX, and applies the shared native-height envelope to page/module text bounds; native export repeats validation and uses that envelope for the generated text frame. Output is standard editable Office Math for PowerPoint 2010+; WPS, Keynote, and LibreOffice show the preview fallback and remain outside the rendering/editability contract.
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 6dc41369..a6dcddd3 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -820,9 +820,14 @@ python3 -c "import sys; sys.path.insert(0, 'skills/ppt-master/scripts'); from sv
Matrices, multiline derivations, and other high-structure expressions remain
blocks. Formula replacement is always active, independent of
`--native-charts-and-tables`: export replaces only the registered SVG preview
-and writes editable PowerPoint 2010+ Office Math. It emits no formula PNG, media
-relationship, or compatibility fallback, and makes no rendering/editability
-promise for Keynote, WPS, LibreOffice, or another non-PowerPoint client.
+and writes editable PowerPoint 2010+ Office Math in `mc:Choice Requires="a14"`.
+The same `mc:AlternateContent` carries an `mc:Fallback` built from the SVG
+preview as ordinary native shapes (block) or the same text box with the preview
+run in place of the math (inline), with fresh shape ids; no formula PNG or media
+relationship is created. A round-trip shape that restores source Office Math
+from its unchanged txBody gets the same branch from its visible SVG text. Clients without a14 math, such as LibreOffice, show
+that fallback; no rendering/editability promise is made for Keynote, WPS,
+LibreOffice, or another non-PowerPoint client.
```bash
python3 scripts/svg_to_pptx.py <project_path>
@@ -1035,7 +1040,7 @@ Behind [`native-formula.md`](../../references/native-formula.md) §3. The compil
**Fail-closed**: unknown commands or environments, Microsoft's explicitly unsupported commands, unsupported mhchem arrows, unescaped `%` comments, invalid macros, and resource-limit overflow block conversion — stricter than Microsoft 365's literal-text passthrough and macro-limit behavior.
-**Compatibility**: the package uses standard editable Office Math and keeps the PowerPoint 2010+ target; the executable profile is pinned to the documentation versions above. Repository verification covers compilation, OMML structure, and PPTX packaging, not a Microsoft 365 UI rendering/editability certification. Earlier PowerPoint versions are not the source-profile baseline; WPS, Keynote, LibreOffice, and other clients receive no embedded fallback. Reverse import is described in [`conversion.md`](conversion.md#native-formula-reverse-import).
+**Compatibility**: the package uses standard editable Office Math and keeps the PowerPoint 2010+ target; the executable profile is pinned to the documentation versions above. Repository verification covers compilation, OMML structure, and PPTX packaging, not a Microsoft 365 UI rendering/editability certification. Earlier PowerPoint versions are not the source-profile baseline; WPS, Keynote, LibreOffice, and other clients receive only the native-shape preview fallback. Reverse import is described in [`conversion.md`](conversion.md#native-formula-reverse-import).
## `visual_review.py`