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-to-svg): separate import recovery from authoring rules
hugohe3f46bdb690b83
diff --git a/docs/powerpoint-svg-mapping.md b/docs/powerpoint-svg-mapping.mdindex c96b03f9..8894c10c 100644--- a/docs/powerpoint-svg-mapping.md+++ b/docs/powerpoint-svg-mapping.md@@ -6,7 +6,7 @@This guide answers one question from the PowerPoint user's point of view: **for a PowerPoint feature, what project representation owns it, and what survives export or import?** PowerPoint semantics are therefore the primary index. SVG elements appear only as the implementation of a specific PowerPoint capability.-This is a public capability map, not a second syntax specification and not a promise to convert arbitrary SVG or arbitrary OOXML. The normative contract remains [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md). When this guide and that contract differ, the contract wins. A feature not listed here is not implicitly supported.+This is a public capability and import-behavior map, not a second generated-SVG syntax specification and not a promise to convert arbitrary SVG or arbitrary OOXML. The canonical generated-authoring contract remains [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md); when generated syntax differs, that contract wins. PPTX import recovery modes and user-visible degradation belong to §11 here and to the [conversion command reference](../skills/ppt-master/scripts/docs/conversion.md), while the parser implementation remains the exact source of truth. A feature not listed here is not implicitly supported.The main route compiles **project-canonical SVG**, not general browser SVG:@@ -154,9 +154,9 @@ preset selection and authoring behavior are documented in| Pattern fill | Annotated project pattern definition | Native `a:pattFill` | `Native-normalized` | Only registered PowerPoint preset patterns are supported || No outline | `stroke="none"` or the registered absence of a line | `a:noFill` under `a:ln` | `Native-stable` | Do not simulate absence with zero-width ambiguous CSS || Solid outline | Registered `stroke` and width | Native `a:ln` | `Native-stable` | Width and paint must use canonical units/grammar |-| Compound outline | No registered single-stroke SVG representation | Explicit geometry alternative or baked asset | `Bake-required` for the compound-line identity | PPTX import accepts only omitted/`sng` `cmpd`; other source values stop instead of becoming a single line |-| Inside-aligned outline | No registered ordinary SVG stroke representation | Explicit inset geometry or baked asset | `Bake-required` for exact outline alignment | PPTX import accepts only omitted/`ctr` `algn`; `in` stops instead of becoming a centered stroke |-| Pattern, image, or group-derived outline paint | No registered line-paint SVG mapping | Explicit geometry alternative or baked asset | `Bake-required` | PPTX import stops instead of substituting a default solid line color |+| Compound outline | No registered single-stroke SVG representation | Explicit geometry alternative or baked asset | `Bake-required` for the compound-line identity | Tolerant PPTX import omits the unsupported outline and reports it; strict import rejects non-`sng` `cmpd` |+| Inside-aligned outline | No registered ordinary SVG stroke representation | Explicit inset geometry or baked asset | `Bake-required` for exact outline alignment | Tolerant PPTX import omits the unsupported outline and reports it; strict import rejects non-`ctr` `algn` |+| Pattern, image, or group-derived outline paint | No registered line-paint SVG mapping | Explicit geometry alternative or baked asset | `Bake-required` | Tolerant PPTX import omits the unsupported outline and reports it; strict import rejects it instead of inventing a solid color || Outline scaling under transforms | Exact `vector-effect="none"` or `vector-effect="non-scaling-stroke"` | Choice resolved into native line width | `Native-normalized` | Other values are rejected; generated spelling is exact and lowercase || Dashed or dotted outline | Registered dash array | Preset or custom DrawingML dash | `Native-normalized` | Unsupported dash semantics are rejected || Line cap and join | Registered cap/join values | Native line cap/join properties | `Native-stable` within the fixed join contract | Import accepts one join; miter requires exact `lim="800000"` |@@ -242,17 +242,32 @@ The importer reconstructs supported PowerPoint semantics into the same project vThis is semantic reconstruction, not a syntax round trip. Master/Layout restoration belongs to the template-structure workflows; an ordinary visual import does not infer reusable topology from slide appearance.+### Import operating modes and recovery boundary++`pptx_to_svg.py` defaults to tolerant import because its inputs are user-owned or third-party PPTX files. `--strict` is available for parser development, contract verification, and reproducing the first source violation. Strict generated-SVG validation and export remain unchanged.++| Source condition | Default tolerant import | `--strict` | Diagnostic result |+|---|---|---|---|+| Recognized color semantics with unrelated source metadata | Canonicalize the recognized color and modifiers | Reject the noncanonical structure | Warning with part, slide, and shape context where available |+| Unsupported fill, outline, effect, image fill, text body, or style property | Keep the object and omit only the unsupported property or feature | Stop at the first violation | Warning names the omitted feature and fallback |+| Unsupported object that cannot be recovered property-by-property | Replace that object with a visible diagnostic placeholder; omit it only when it has no usable frame | Stop at the first violation | Warning identifies the source object |+| Unsupported slide or part background | Omit that background and continue the page/part | Stop at the first violation | Warning identifies the owning part |+| Corrupt package/XML or missing required package structure | Stop; no safe page-level recovery exists | Stop | Clean command error; no raw Python traceback |++Every successful run writes `<output>/conversion-report.json`. The report records the mode, slide and warning counts, stable reason code, source message, chosen fallback, package part, and—when available—slide index plus shape id/name/kind. Tolerant import is therefore not silent: it maximizes usable output while making every contract recovery reviewable.+## 12. Validation ownership-The three layers have deliberately different jobs:+The four layers have deliberately different jobs:| Layer | Responsibility ||---|---|| Prompt, template, and examples | Generate only the canonical representation for each PowerPoint feature || `svg_quality_checker.py` | Reject invalid/unsupported mappings; warn but allow registered compatible spellings or fidelity risks || `svg_to_pptx.py` and package read-back | Normalize compatible input, compile DrawingML, and reject any result that would be ambiguous, structurally inconsistent, or invalid |+| `pptx_to_svg.py` | In default tolerant mode, preserve the usable deck and report source-owned degradation at the narrowest safe boundary; in `--strict` mode, stop at the first unsupported or malformed source construct |-A warning is not permission to guess. It is reserved for a deterministic supported mapping whose spelling or fidelity deserves attention. Missing mappings, invalid units, malformed metadata, broken structure contracts, and potentially repair-triggering DrawingML are errors.+A generated-SVG warning is not permission to guess. It is reserved for a deterministic supported mapping whose spelling or fidelity deserves attention. Missing mappings, invalid units, malformed metadata, broken structure contracts, and potentially repair-triggering generated DrawingML remain errors. Import diagnostics describe explicit loss or normalization of source-owned content; they never authorize the importer to invent unsupported semantics.## 13. Adding or changing a mappingdiff --git a/docs/technical-design.md b/docs/technical-design.mdindex ef9b8ddd..92f4cd92 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -200,7 +200,7 @@ SVG wins because it shares the same world view as DrawingML: both are absolute-cThis table shows conceptual counterparts, not a commitment to the entire SVG standard or a promise of lossless semantics. Every supported capability must have an explicit mapping in [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md) that identifies its project-canonical spelling, accepted compatible inputs, target DrawingML expression, fidelity, and rejection boundary; capabilities that support PPTX import must also identify the source PPTX/OOXML semantics. A mapping may be exact, deterministically normalized, an explicit fallback, a sidecar, or unsupported. Package semantics such as notes, animations, and relationships do not need to be forced into SVG, but their owning route must be explicit.-For a PowerPoint-first, feature-by-feature view of those relationships, see the [PowerPoint Feature ↔ Project SVG Mapping Guide](./powerpoint-svg-mapping.md). It is an explanatory capability map; `shared-standards.md` remains the normative contract.+For a PowerPoint-first, feature-by-feature view of those relationships, see the [PowerPoint Feature ↔ Project SVG Mapping Guide](./powerpoint-svg-mapping.md). It owns the public capability and PPTX-import recovery map; `shared-standards.md` remains the generated-authoring contract.The main generation route uses **canonical narrow writes and controlled compatible reads**. New `svg_output/` and reusable templates use only project-canonical spellings—for example, uppercase opaque `#RRGGBB`, with transparency carried by the matching `fill-opacity`, `stroke-opacity`, `stop-opacity`, `flood-opacity`, or atomic-element `opacity`. Historical or manual input proceeds only when the compatibility contract documents it, the conversion has one meaning, and the output is valid. The checker emits a non-blocking warning for such input, and the converter normalizes it at the compilation boundary. Anything that requires guessing, lacks a mapping, or could produce a damaged PPTX is an error.diff --git a/docs/zh/powerpoint-svg-mapping.md b/docs/zh/powerpoint-svg-mapping.mdindex f89741f1..4ac30d6f 100644--- a/docs/zh/powerpoint-svg-mapping.md+++ b/docs/zh/powerpoint-svg-mapping.md@@ -6,7 +6,7 @@本指南从 PowerPoint 使用者的视角回答一个问题:**对于某项 PowerPoint 功能,项目中由什么表达承载,导出或回导时能保留什么?** 因此,PowerPoint 语义是唯一主索引,SVG 元素只作为某项 PowerPoint 能力的具体实现出现。-这是一份公开的能力映射表,不是第二份语法规范,也不承诺转换任意 SVG 或任意 OOXML。规范权威仍属于 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md);如果本指南与该规范不一致,以规范为准。本指南未列出的功能不会因此被默认为受支持。+这是一份公开的能力与导入行为映射表,不是第二份生成 SVG 语法规范,也不承诺转换任意 SVG 或任意 OOXML。规范生成合同仍属于 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md);生成语法出现差异时,以该合同为准。PPTX 导入的恢复模式与用户可见降级由本文 §11 和[转换命令文档](../../skills/ppt-master/scripts/docs/conversion.md)负责,精确 parser 行为仍以实现代码为真值。本指南未列出的功能不会因此被默认为受支持。主路线编译的是**项目规范化 SVG**,而不是通用浏览器 SVG:@@ -149,9 +149,9 @@ PowerPoint 意图| 图案填充 | 带注解的项目 pattern 定义 | 原生 `a:pattFill` | `Native-normalized` | 仅支持已登记 PowerPoint 预设 pattern || 无轮廓 | `stroke="none"` 或已登记线缺省 | `a:ln` 内的 `a:noFill` | `Native-stable` | 不得用零线宽模糊 CSS 模拟缺省 || 实线轮廓 | 已登记 `stroke` 与宽度 | 原生 `a:ln` | `Native-stable` | 宽度与 paint 必须使用规范单位/语法 |-| 复合轮廓线 | 无已登记的单一 SVG stroke 表达 | 显式几何替代或烘焙资产 | 复合线身份为 `Bake-required` | PPTX 回导仅接受省略/`sng` 的 `cmpd`;其他源值会阻断,不得退化为单线 |-| 内侧对齐轮廓 | 无已登记的普通 SVG stroke 表达 | 显式内缩几何或烘焙资产 | 精确轮廓对齐为 `Bake-required` | PPTX 回导仅接受省略/`ctr` 的 `algn`;`in` 会阻断,不得退化为居中描边 |-| 图案、图片或组派生轮廓 paint | 无已登记的线条 paint SVG 映射 | 显式几何替代或烘焙资产 | `Bake-required` | PPTX 回导会阻断,不得替换为默认纯色线 |+| 复合轮廓线 | 无已登记的单一 SVG stroke 表达 | 显式几何替代或烘焙资产 | 复合线身份为 `Bake-required` | 容错回导省略不支持的轮廓并报告;严格回导拒绝非 `sng` 的 `cmpd` |+| 内侧对齐轮廓 | 无已登记的普通 SVG stroke 表达 | 显式内缩几何或烘焙资产 | 精确轮廓对齐为 `Bake-required` | 容错回导省略不支持的轮廓并报告;严格回导拒绝非 `ctr` 的 `algn` |+| 图案、图片或组派生轮廓 paint | 无已登记的线条 paint SVG 映射 | 显式几何替代或烘焙资产 | `Bake-required` | 容错回导省略不支持的轮廓并报告;严格回导拒绝该输入,不虚构纯色线 || transform 下的轮廓缩放 | 精确的 `vector-effect="none"` 或 `vector-effect="non-scaling-stroke"` | 选择被解析为原生线宽 | `Native-normalized` | 拒绝其他取值;生成拼法必须精确且为小写 || 虚线或点线轮廓 | 已登记 dash array | 预设或自定义 DrawingML dash | `Native-normalized` | 拒绝不支持的 dash 语义 || 线端与连接样式 | 已登记 cap/join 值 | 原生 line cap/join 属性 | 固定 join 合同内为 `Native-stable` | 回导仅接受一个 join;miter 必须精确使用 `lim="800000"` |@@ -237,17 +237,32 @@ sidecar 工作流见 [`animations.md`](../../skills/ppt-master/references/animat这是语义重建,不是语法往返。Master/Layout 恢复属于模板结构工作流;普通视觉导入不会从 Slide 外观推断可复用拓扑。+### 导入运行模式与恢复边界++`pptx_to_svg.py` 默认采用容错导入,因为输入来自用户或第三方 PPTX。`--strict` 用于 parser 开发、合同核验和复现第一个源文件违规点。生成 SVG 的严格校验与导出边界保持不变。++| 源文件情况 | 默认容错导入 | `--strict` | 诊断结果 |+|---|---|---|---|+| 可识别颜色语义带无关源 metadata | 规范化已识别颜色与 modifier | 拒绝非规范结构 | warning;可用时包含 part、Slide 与 shape 上下文 |+| 不支持的填充、轮廓、效果、图片填充、文字体或样式属性 | 保留对象,只省略不支持的属性或功能 | 在第一个违规点停止 | warning 说明省略内容与 fallback |+| 无法按属性恢复的不支持对象 | 只把该对象替换为可见诊断占位;没有可用 frame 时才省略 | 在第一个违规点停止 | warning 标识源对象 |+| 不支持的 Slide 或 part 背景 | 省略该背景,继续当前页面/part | 在第一个违规点停止 | warning 标识所属 part |+| 损坏的包/XML 或缺失必需包结构 | 停止;不存在安全的页面级恢复 | 停止 | 整洁的命令错误,不输出裸 Python traceback |++每次成功转换都会写入 `<output>/conversion-report.json`。报告记录运行模式、Slide 与 warning 数量、稳定原因码、源错误消息、采用的 fallback、包 part,以及可用时的 Slide 序号和 shape id/name/kind。因此,容错导入不是静默吞错:它尽可能保留可用输出,同时让每一次合同恢复都可复核。+## 12. 校验职责-三层有意承担不同职责:+四层有意承担不同职责:| 层 | 职责 ||---|---|| 提示词、模板与示例 | 对每项 PowerPoint 功能只生成规范表达 || `svg_quality_checker.py` | 拒绝非法/不支持映射;对已登记兼容拼法或保真风险给出 warning 但允许继续 || `svg_to_pptx.py` 与最终包读回 | 归一化兼容输入、编译 DrawingML,并拒绝任何会产生歧义、结构不一致或非法结果的输出 |+| `pptx_to_svg.py` | 默认容错模式在最窄安全边界保留可用 deck 并报告源内容降级;`--strict` 模式在第一个不支持或格式错误的源结构处停止 |-warning 不是猜测许可。它只适用于拥有唯一结果的受支持映射,但其拼法或保真度值得注意的情况。缺失映射、非法单位、格式错误 metadata、破损的结构合同,以及可能触发 PowerPoint 修复的 DrawingML 都是 error。+生成 SVG 的 warning 不是猜测许可。它只适用于拥有唯一结果的受支持映射,但其拼法或保真度值得注意的情况。缺失映射、非法单位、格式错误 metadata、破损的结构合同,以及可能触发 PowerPoint 修复的生成 DrawingML 仍是 error。导入诊断描述对源内容的显式丢失或规范化,绝不授权导入器虚构不支持的语义。## 13. 新增或修改映射diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex c0a502f4..db164055 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -201,7 +201,7 @@ SVG 胜出,因为它与 DrawingML 拥有相同的世界观:两者都是绝这张表只展示概念对应关系,不是对整个 SVG 标准的承诺,也不承诺所有映射语义无损。每项受支持能力都必须在 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 中拥有明确的映射记录,说明项目规范写法、允许的兼容输入、目标 DrawingML 表达、保真度和拒绝条件;涉及 PPTX 回导的能力还要说明来源 PPTX / OOXML 语义。映射状态可以是精确、确定性归一化、显式 fallback、sidecar 或 unsupported;讲稿、动画、relationships 等 package 语义不必强行塞进 SVG,但必须明确由哪条路线承载。-如需从 PowerPoint 功能出发逐项查看这些关系,请参阅 [PowerPoint 功能 ↔ 项目 SVG 映射指南](./powerpoint-svg-mapping.md)。该文档是解释性能力表,规范权威仍属于 `shared-standards.md`。+如需从 PowerPoint 功能出发逐项查看这些关系,请参阅 [PowerPoint 功能 ↔ 项目 SVG 映射指南](./powerpoint-svg-mapping.md)。该文档负责公开能力与 PPTX 导入恢复映射;`shared-standards.md` 继续负责生成 SVG 创作合同。主生成路线采用**规范窄写入、受控兼容读取**。新生成的 `svg_output/` 与可复用模板只使用项目规范写法,例如不透明的六位大写 `#RRGGBB`,透明度放在对应的 `fill-opacity`、`stroke-opacity`、`stop-opacity`、`flood-opacity` 或原子元素 `opacity` 中。历史或人工输入只有在兼容合同明确登记、转换结果唯一且输出合法时才可继续导出;Checker 对这类写法给出非阻塞 warning,转换器在编译边界统一归一化。任何需要猜测、没有映射或可能产生损坏 PPTX 的表达都必须报 error。diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.mdindex 667775cc..3021387d 100644--- a/skills/ppt-master/references/shared-standards.md+++ b/skills/ppt-master/references/shared-standards.md@@ -178,17 +178,11 @@ the open arrow form requires `<path>`. Four-vertex shapes must be simple andnon-degenerate: convex geometry maps to diamond and concave geometry maps tostealth. Checker and exporter preflight consume this same contract; othermarker shapes have no native mapping and block export instead of being silently-dropped. PPTX import likewise accepts only these five DrawingML line-end types-(plus `none`); an unknown source value stops import instead of being relabeled-as a supported shape. Optional DrawingML `w` and `len` values default to `med`;-explicit values must be `sm`, `med`, or `lg`, and invalid source buckets stop-import instead of being normalized to `med`.-Each imported line contains at most one direct, empty `a:headEnd` and one direct,-empty `a:tailEnd`, carrying only optional `type`, `w`, and `len`. Omitted `type`-means `none`; an explicitly empty token, duplicate endpoint, unknown attribute,-or child payload stops import instead of being ignored. A non-`none` endpoint-also requires a visible resolved line paint; a `noFill` line/end combination-stops import instead of producing a project-invalid invisible marker.+dropped.++PPTX import compatibility, tolerant recovery, strict-mode rejection, and+diagnostic behavior are indexed in+[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §11.---@@ -714,114 +708,11 @@ preflight; neither substitutes an opaque default for unknown intent.plus alpha when a painted transparent layer must remain represented. Preferdescendant alpha over group opacity when isolated compositing matters (§2.2).-On PPTX-to-SVG import, a non-line DrawingML fill-bearing container has at most-one direct fill choice among `a:noFill`, `a:solidFill`, `a:gradFill`,-`a:blipFill`, `a:pattFill`, and `a:grpFill`. Competing choices and-foreign-namespace aliases stop import instead of being selected by-implementation priority. Explicit `a:grpFill` also stops import until group-fill inheritance has a registered SVG mapping; an omitted fill continues to-use the owning container's inheritance/default contract.-Every imported `a:noFill`, including line paint, is an attribute-free empty-leaf. Attributes, child elements, or text payload stop import instead of being-discarded while the paint is normalized to `none`.-The general fill and line-paint import routes require an attribute-free-`a:solidFill` to contain exactly one direct registered DrawingML color child-with no interleaved text. Although Office can merge an omitted solid color from-style/master inheritance and ultimately default it to `schemeColor(bg1)`, the-local SVG mapping does not guess that external context: empty, malformed,-ambiguous, or unresolvable solid fills stop import instead of being treated as-an omitted fill or reduced to the first recognizable color.-Other imported color-choice containers, including style references,-background references, pattern foreground/background wrappers, gradient stops,-and table text styles, use the same direct-child selector. An omitted color is-retained only where the owning container permits omission; otherwise the-surrounding structure contract requires one. Multiple registered colors,-including duplicate color types, and foreign-namespace elements that reuse a-registered color local name stop import. Selection never depends on color-type-priority or silently discards a competing child.-Imported `a:srgbClr` uses exactly one `val` attribute containing six ASCII-hexadecimal digits. SVG/CSS conveniences such as three-digit shorthand, a-leading `#`, alpha-bearing eight-digit tokens, extra attributes, and-interleaved text stop import instead of being normalized into a different-DrawingML token. Lowercase hexadecimal digits remain equivalent input and-normalize to uppercase SVG paint.-Imported `a:schemeClr` likewise has exactly one `val` attribute and accepts only-the DrawingML scheme enum: `bg1`, `tx1`, `bg2`, `tx2`, `accent1..6`, `hlink`,-`folHlink`, `phClr`, `dk1`, `lt1`, `dk2`, or `lt2`. Unknown/case-altered-references, extra attributes, namespace aliases, and interleaved text stop-import. A registered reference that cannot be resolved from the active theme-or `phClr` placeholder context remains a resolution failure, not an unknown-enum fallback.-Imported `a:sysClr` requires a registered DrawingML system-color `val` and a-six-digit `lastClr` fallback. The latter is optional in OOXML but mandatory for-this portable mapping because the converter cannot reproduce the source-machine's dynamic system palette. Missing/unknown system identities, malformed-fallbacks, extra attributes, namespace aliases, and interleaved text stop-import; a valid `lastClr` is normalized into static SVG paint, so this route is-`Native-normalized` rather than system-color-preserving.-Imported `a:prstClr` has exactly one `val` attribute selected from the complete-190-value DrawingML preset-color enum, all of which have a registered static-RGB mapping. Missing/unknown/case-altered values, extra attributes, namespace-aliases, and interleaved text stop import instead of falling back to black or-an adjacent CSS color name.-Imported `a:hslClr` has exactly the required `hue`, `sat`, and `lum`-attributes. The registered mapping accepts integer DrawingML units only:-`hue` is `0..21599999` in 1/60000 degree, while `sat` and `lum` are-`0..100000` in thousandths of a percent. Missing, malformed, percentage-literal,-or out-of-range channels, extra attributes, namespace aliases, and interleaved-text stop import instead of receiving zero defaults or being clamped into a-different color.-Imported `a:scrgbClr` has exactly the required `r`, `g`, and `b` attributes,-each using an integer `0..100000` DrawingML channel. Because scRGB channels are-linear-light values while SVG hexadecimal paint is sRGB-encoded, import applies-the sRGB transfer function before quantization; for example, linear-`50000/50000/50000` normalizes to `#BCBCBC`, not `#808080`. Missing, malformed,-percentage-literal, or out-of-range channels, extra attributes, namespace-aliases, and interleaved text stop import instead of receiving zero defaults or-being clamped into another color. This route is `Native-normalized` because the-SVG retains the displayed sRGB color rather than the source color-space model.-Theme palette import is closed around the DrawingML color-scheme contract. A-loaded theme part must have an `a:theme` root, exactly one direct-`a:themeElements`, and exactly one direct `a:clrScheme`. The scheme has only its-required `name` attribute and the 12 required slots in schema order: `dk1`,-`lt1`, `dk2`, `lt2`, `accent1..6`, `hlink`, and `folHlink`. Each attribute-free-slot contains exactly one concrete `a:srgbClr`, `a:sysClr`, `a:prstClr`,-`a:hslClr`, or `a:scrgbClr` child accepted by the registered base-color and-modifier contracts above. The resolved slot must be opaque because the current-palette model stores RGB only. Missing, duplicate, reordered, ambiguous,-non-opaque, or extension-bearing schemes stop import instead of being reduced-to the first recognizable color.--A loaded slide master likewise has a `p:sldMaster` root and exactly one direct,-empty `p:clrMap`. Its exact 12-attribute source set is `bg1`, `tx1`, `bg2`,-`tx2`, `accent1..6`, `hlink`, and `folHlink`; every value is one of the 12 theme-slots above. Missing or extra mappings, unknown/case-altered targets, text, and-extension children stop import rather than falling back to aliases. A-theme-only palette with no master still uses the registered `bg`/`tx` aliases.-Theme slot colors normalize to static SVG paint, so this route is-`Native-normalized` rather than preserving the source color model or mapping-record.-Imported base colors apply only the following DrawingML modifier subset, in-document order:--| Modifier | Registered integer contract |-|---|---|-| `tint`, `shade`, `alpha` | `0..100000` fixed percentage |-| `alphaMod`, `hueMod` | `0..2147483647` positive percentage |-| `alphaOff` | `-100000..100000` fixed offset |-| `lumMod`, `lumOff`, `satMod`, `satOff` | signed 32-bit percentage |-| `hueOff` | signed 32-bit angle in 1/60000 degree |-| `comp`, `gray`, `inv` | empty flag element |--Value modifiers are exact DrawingML-namespace leaves with only a required-integer `val`; flag modifiers are empty leaves with no attributes. Missing,-malformed, percentage-literal, or out-of-range values, extra attributes, nested-payload, foreign-namespace aliases, and unsupported transforms such as-`gamma`, `invGamma`, or direct RGB-channel transforms stop import. They are-never ignored or treated as zero. Luminance, saturation, hue, and alpha results-retain the existing registered normalization and saturation behavior after each-modifier.-+PPTX import is a user-input boundary, not generated authoring. Tolerant mode+retains recognized color semantics, omits only unsupported paint properties,+and records the decision in `conversion-report.json`; `--strict` keeps the+closed parser checks. See+[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §11.---### 6.3 Gradients and Paint Effects@@ -845,73 +736,10 @@ Linear export preserves stops/alpha/direction but reduces coordinates to anangle. Radial export becomes a centered circular gradient and does not preserve`cx/cy/r/fx/fy`. Gradient strokes remain editable, but PPTX-to-SVG re-import mayretain only the first stop. Stop alpha and element opacity multiply.-Non-line PPTX gradient-fill import writes stop offsets with five decimal places,-and export parses the shared unitless/percentage grammar before half-up-quantization to 1/100000. Thus small positions and values such as `1%`-round-trip without truncation or percentage reinterpretation. In that non-line-import mapping, each `a:gs` requires an integer `pos` from `0` through `100000`.-Missing, malformed, or out-of-range source positions stop import instead of-being silently relocated to the start of the gradient.-Source positions must be nondecreasing in document order; equal positions stay-valid for hard transitions. Descending positions stop import instead of being-silently clamped by SVG rendering.-An explicit non-line imported `a:gradFill` requires exactly one attribute-free-`a:gsLst` with at least two direct `a:gs` children and no other payload. Every-stop must provide a resolvable color. Missing or duplicate lists, undersized or-malformed lists, and unresolvable stops stop import instead of becoming an-inherited fill or a partial gradient.-Each imported `a:gs` has exactly the required `pos` attribute and exactly one-direct registered DrawingML color child, with no interleaved text. Extra or-namespaced attributes, missing/multiple/foreign color children, and text payload-stop import instead of being reduced to the first recognizable color.-The direct children of an imported non-line `a:gradFill` follow the closed-DrawingML sequence `a:gsLst`, optional `a:lin` or `a:path`, then optional-`a:tileRect`, with no text payload. Unknown children, foreign-namespace aliases,-and out-of-order registered children stop import instead of being ignored.-An imported non-line `a:lin@ang` may be omitted for the schema-defined zero-default. When present, it must be an integer from `0` through `21599999`-(1/60000 degree); malformed or out-of-range values stop import instead of-silently becoming a horizontal gradient.-The imported `a:lin` is a leaf with only optional `ang` and `scaled`-attributes. Extra or namespaced attributes, child elements, and text payload-stop import instead of being discarded.-The normalized SVG endpoint mapping preserves `a:lin@scaled="1"` / `"true"`-at every angle. The schema default (`scaled` omitted) and explicit `"0"` /-`"false"` are accepted only at cardinal angles, where aspect-ratio scaling-cannot change the direction. Other unscaled angles and malformed boolean values-stop import instead of producing a direction that varies with shape geometry.-An imported non-line `a:gradFill` contains at most one direct `a:lin` or-`a:path` direction. Omitting both uses the schema-defined horizontal linear-default; duplicate or mixed direction elements stop import instead of being-selected by implementation priority.-For the registered path-gradient approximation, omitted `a:path@path` uses the-schema default `rect`; explicit `circle`, `rect`, and `shape` are normalized to-the centered radial SVG form. Unknown or malformed enum values stop import-instead of being mislabeled as a supported radial gradient.-The imported `a:path` permits only its optional `path` attribute and zero or one-direct `a:fillToRect` child. Extra or namespaced attributes, foreign children,-and interleaved text payload stop import instead of being discarded.-The local SVG gradient rotates with its containing geometry. Imported-`a:gradFill@rotWithShape` may therefore be omitted for the documented Office-base default or be the exact XML booleans `1` / `true`. Explicit `0` / `false`-and malformed booleans stop import instead of detaching the gradient direction-from the shape during rotation.-The imported `a:gradFill` attribute set is closed to `flip` and-`rotWithShape`; unknown, namespaced, or misspelled attributes stop import rather-than being ignored as if their semantics were already supported.-Project SVG has no gradient-tile flip mapping. Imported `a:gradFill@flip` may-therefore be omitted for the documented Office `none` baseline or be exactly-`none`; `x`, `y`, `xy`, malformed, and unknown values stop import instead of-becoming an ordinary unflipped gradient.-An imported `a:tileRect` may be absent or occur once as an empty/full-area-relative rectangle. Explicit `l/t/r/b` values use strict DrawingML percentage-syntax and must resolve to zero. Duplicate or malformed rectangles and non-zero-tile offsets stop import because project SVG has no gradient tiling model.-Within an imported `a:path`, zero or one leaf `a:fillToRect` is accepted. Its-optional `l/t/r/b` edges must use the same strict DrawingML percentage syntax;-the registered `Approximate` mapping validates but normalizes the focus rectangle-to the centered radial SVG form. Duplicate or malformed focus rectangles stop-import instead of being silently discarded.+PPTX import normalizes compatible gradients and records any property-level+degradation without aborting the deck; `--strict` keeps the closed parser+contract. See+[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §11.The quality checker and exporter preflight both validate definition location,references, gradient structure, and paint context from the same closed contract.@@ -967,55 +795,11 @@ The sole `<g filter>` exception is the hash-lockedof an imported preset object and reference the same filter as that object's onehidden geometry carrier. The preview is render-only and never becomes a secondPowerPoint object; this exception does not authorize filters on ordinary groups.-PPTX shape/connector import emits a public filter only for exactly one source-`outerShdw` with a meaningful non-zero offset, or exactly one source `glow`.-Glow import uses the registered Gaussian/flood/composite graph and preserves-its radius conversion. Zero-offset outer shadow, duplicate or foreign-namespace-effect containers, multiple effects, `effectDag`, unknown effects, and invalid-numeric or color data receive the blocking §1.4 effect-status metadata instead-of being reclassified or silently omitted.-Each supported source effect must contain exactly one resolvable DrawingML-color choice. Malformed choices and valid color semantics outside the-registered color/modifier subset also receive effect-status metadata; the-importer never substitutes black or drops an unhandled modifier.-DrawingML color alpha transforms are evaluated in document order. Each-`alpha`, `alphaMod`, or `alphaOff` result saturates into `0..100%` before the-next transform, and the importer writes that effective value to the SVG-`flood-opacity` channel.-Picture and group targets do not expose the public filter mapping: any source-effect DAG or non-empty effect list on `p:pic/p:spPr` or `p:grpSp/p:grpSpPr`-keeps the base object but receives effect-status metadata instead of attaching-an invalid filter to `<image>` or ordinary `<g>`.-Imported metadata-backed logical shapes preserve slide-local run-level effects-only inside an unchanged `metadata[data-pptx-part="txbody"]` payload. If-visible text, typography, or child topology invalidates that payload, checker-and exporter stop when the source `rPr` / `defRPr` / `endParaRPr` contains a-non-empty `effectLst` or `effectDag`; effect-free edited text keeps the normal-fallback.-Effects found in the inherited Layout/Master list-style chain are outside that-slide-local payload. Horizontal import keeps the visible fallback and payload-but stamps the logical shape and native carrier with-`unsupported-run-effect-route:inherited-text-style`.-The separate vertical-text output cannot carry that payload. When its source-text body or inherited list-style chain contains the same non-empty run-effect-containers, import keeps the normalized geometry and visible vertical text but-stamps the logical shape and native carrier with the blocking §1.4 effect-status; effect-free and empty effect containers keep the existing normalized-fallback.-Relationship-bearing text bodies also cannot carry the opaque payload across-parts. When such a body or its inherited list-style chain contains a non-empty-run effect, import keeps its rebuilt visible text but stamps the same two-blocking object markers; relationship-bearing text without a run effect keeps-the existing visual fallback.-Table-cell text bodies use neither the opaque payload nor the public filter-mapping. A non-empty run effect disables the native Table replacement payload,-keeps the visible table fallback, and stamps its imported `p:graphicFrame`-logical group with the blocking effect status. The existing replacement status-still records any independent table fallback reason; empty effect containers-and effect-free cells remain eligible for the closed native Table schema.-If a shape has both an unsupported shape-level effect and one of these run-level-fallback reasons, the canonical compound marker records both reasons.-This conditional guard is not a public run-effect authoring surface.+PPTX import preserves one registered shape/connector shadow or glow and records+unsupported object/run effects as import diagnostics instead of exposing a new+authoring surface. See+[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §11 for+tolerant, strict, and release-handling behavior.The quality checker and exporter preflight enforce the same definition,reference, primitive, target, and numeric-value contract. Missing requiredgeometry and malformed values are never replaced by effect defaults during@@ -1170,47 +954,10 @@ fidelity.| Gradient stroke | §6.3; re-import may flatten to first stop || `marker-start` / `marker-end` | §1.1 native line end; type `Native-normalized`, size `Approximate` (`sm/med/lg`) |-PPTX import formats normalized paint and text alpha with five decimal places,-matching DrawingML's 1/100000 target precision. The smallest positive source-alpha therefore remains non-zero and quantizes back instead of becoming fully-transparent. Export uses one clamped half-up quantizer for every DrawingML-`alpha`, `alphaMod`, and `alphaModFix` channel; it never truncates a decimal-ratio one unit below its intended value.--PPTX import accepts `a:ln@w` only as an integer DrawingML `ST_LineWidth` value-from `0` through `20116800` EMU. Malformed, negative, or oversized source widths-stop import instead of being dropped and replaced by a default SVG line width.-The EMU-to-pixel token retains enough decimal precision for the smallest-positive legal width to remain non-zero and quantize back to its source EMU.-PPTX import accepts an omitted `a:ln@cmpd` or explicit `sng`. Other compound-line values (`dbl`, `thickThin`, `thinThick`, `tri`) have no registered-single-stroke SVG mapping and stop import instead of becoming an ordinary line.-PPTX import likewise accepts an omitted `a:ln@algn` or explicit `ctr`.-Inside-aligned (`in`) and unknown source values stop import because an ordinary-SVG stroke is centered and cannot preserve the source outline boundary.-An imported line contains at most one direct paint. The registered import-choices are `a:noFill`, a resolvable `a:solidFill`, and `a:gradFill` normalized-to its first resolvable stop. Ambiguous paint, unresolved registered paint, and-pattern/image/group line paint stop import instead of becoming a default color.-An explicit source `a:ln@cap` must be `flat`, `rnd`, or `sq`, which map to SVG-`butt`, `round`, and `square`; unknown values stop import instead of falling-back to the SVG default cap.-An imported line has at most one direct `a:round`, `a:bevel`, or `a:miter`-join. Round and bevel are empty; miter requires the project's fixed-`lim="800000"`. Ambiguous joins, payload-bearing join elements, a missing-limit, and other miter limits stop import rather than losing corner geometry.-PPTX import maps only the registered DrawingML `prstDash` values; `solid`-remains an intentional line with no SVG dash array, while an unknown source-value stops import instead of being mistaken for `solid`. A line contains at-most one direct `a:prstDash` or `a:custDash`; preset dash has exactly one `val`-attribute and no payload. Duplicate, mixed, or payload-bearing dash definitions-stop import instead of being resolved by document order.-An imported `a:custDash` contains one or more direct, empty `a:ds` children;-each stop has exactly `d` and `sp`, both positive OOXML integers. Missing or-extra fields, foreign children, malformed numbers, and values outside the-positive 32-bit integer range stop import instead of being skipped. Import-formats converted dash lengths with enough decimal precision that a legal-positive source value never becomes a zero SVG dash or gap.+PPTX import treats unsupported line properties as source diagnostics: tolerant+mode retains the object and omits only the unsupported outline; `--strict`+retains the closed rejection behavior. See+[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §11.The dash grammar is closed: exact lowercase `none`, or at least two finiteunitless numbers separated by whitespace or one comma. Generated SVG uses@@ -1585,23 +1332,9 @@ halftone and route dense full-slide texture to §6.12.glow; it does not blur the object or backdrop. Use a low-alpha raster for densegrain and explicit circles/paths only for sparse editable marks.-**Hard rule — unsupported imported object effects remain explicit**:-`pptx_to_svg.py` keeps the underlying object but stamps blocking effect-status-metadata for unsupported shape/connector effects and for every picture/group-effect DAG or non-empty effect list.-Before release export, rasterize the affected object from the source PPTX or-rebuild its effect with supported explicit geometry; baking the effect-less-analysis SVG alone cannot recover the source appearance. This diagnostic path-covers `p:sp`, `p:cxnSp`, `p:pic`, and `p:grpSp` source effects. Text-run source-effects follow the route-specific §6.4 contract: unchanged metadata-backed-horizontal text preserves slide-local effects in its native `txBody`, while a-lossy edit blocks from that payload and inherited list-style effects receive a-separate blocking marker; vertical and relationship-bearing shape-text routes-keep their visible fallback and stamp the logical shape plus carrier with-effect-status; table-cell text keeps the visible table fallback, disables-native Table replacement, and stamps the imported `p:graphicFrame` group.-Handled object or text-run effects must never become a different effect or-disappear without a diagnostic.+Unsupported source effects remain visible where possible and retain their+import diagnostics. Resolve those diagnostics before release export; see+[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §11.---@@ -1703,60 +1436,11 @@ to at least one EMU per resolved row and column.metadata, bounds/fallback availability, table rows/columns, supported charttype, chart data shape, and any imported fallback baseline before export.-**Hard rule — imported fallback freshness**: active table/chart markers emitted-by `pptx_to_svg.py` carry `data-pptx-fallback-sha256`, a canonical hash of the-marker fallback plus reachable document-level SVG fragment definitions. Editing-geometry/text/paint, switching a local `url(#...)` or `href="#..."` target,-changing a reachable definition, or changing the marker transform makes the-replacement metadata stale. The mandatory quality checker warns and the default route-keeps the edited SVG; `--native-charts-and-tables` hard-fails before replacement so it-cannot discard that edit. Metadata/title/description nodes, `data-pptx-*`-runtime attributes, marker-local stable ID renames, and marker-local-`display:none` subtrees are excluded. `visibility:hidden` content,-marker-local unused definitions, and explicitly referenced document-level-target roots (even when hidden) remain conservatively hashed. External-image/font file bytes are not read.-Generated authoring and reusable templates omit import provenance and do not-preseed a static fallback baseline; that hashless authored state is normal and-does not warn. A hashless legacy imported marker that still carries PPTX import-provenance remains native-compatible and warns in the checker/native route that-stale detection is unavailable. An explicitly sealed authored marker that does-carry a baseline is validated by the same integrity rule; only a missing-authored baseline is silent. A stale hash is an integrity mismatch, not a-visual-parity gate on an unchanged active marker.--**Hard rule — imported fallback kind**: A PPTX chart with a complete baked-preview may carry `data-pptx-fallback-kind="source-preview"`. Supported parsed-classic families without a preview use a deterministic readable fallback-marked `data-pptx-fallback-kind="normalized"`; it is explicitly not-source-exact. When no current renderer exists, the importer emits its typed-reconstruction aid with `data-pptx-fallback-kind="placeholder"`. That value-alone records the diagnostic reconstruction-only fallback: quality checking-and export warn, default export keeps the placeholder, and-`--native-charts-and-tables` may reconstruct a PowerPoint-native chart when the same-group has a valid active `data-pptx-replace-with="chart"` payload. The allowed-values remain closed; unknown, whitespace-padded, or contradictory values fail.-`data-pptx-replacement-status` records the closed reason code when imported-content has a complete visual fallback but cannot make an active replacement-claim. It and `data-pptx-replace-with` are mutually exclusive on the same-visible group.--**Imported replacement provenance**: A table/chart group created by-`pptx_to_svg.py` under this contract—whether it has an active replacement claim-or a fallback-only status—carries `data-pptx-import-source="pptx"`. This records-provenance for the imported-style normalization path; it does not identify the-replacement kind, and generated authoring omits it.--**Legacy read compatibility**: The converter and checker continue to read-`data-pptx-native`, `data-pptx-native-status`, `data-pptx-native-source`, and-`data-pptx-visual-status`. The legacy pair-`data-pptx-visual-status="placeholder"` plus-`data-pptx-route-status="reconstruction-only"` maps to canonical-`data-pptx-fallback-kind="placeholder"`; canonical authoring has no route-status-attribute. `--native-objects` remains a compatibility alias for-`--native-charts-and-tables`. New generated SVG and documented commands MUST-use the canonical spellings. If a legacy and canonical attribute are both-present, they must resolve to the same value; a conflict fails validation.+Imported marker freshness, fallback classification, provenance, and legacy+read compatibility are operational import concerns. Keep generated authoring+free of those attributes; use the exact behavior and field index in+[`conversion.md`](../scripts/docs/conversion.md#pptx_to_svgpy) and+[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §7/§11.```xml<g id="p03-revenue-chart" data-pptx-replace-with="chart">@@ -2065,19 +1749,10 @@ Every new SVG project declares one deterministic route. Free-design and brand-on**Template behavior**: Strict preserves the selected prototype's declared Master/Layout/slot contract. Adaptive retains its Master and may allocate a new Layout key/name only when fixed Layout atoms or slot topology/bounds change; update the lock during authoring. Mirror-created prototypes preserve restored source identity, literal paint, typography, effects, atomic geometry, and referenced assets. `standard` / `fidelity` never make source topology authoritative; mirror does not synthesize a replacement topology.-**Imported inherited-shape visibility**: PPTX import reads-`p:sld@showMasterSp` and `p:sldLayout@showMasterSp` as XML Schema booleans;-an absent value, `1`, or `true` enables the relevant inherited shapes, while-`0` or `false` disables them. A disabled Slide value suppresses both Layout-and Master drawable shapes on that page. A disabled Layout value suppresses-only its parent Master's drawable shapes; the Layout's own shapes remain.-Neither flag changes background inheritance, Slide-local objects,-placeholder geometry/style inheritance, or the Master/Layout relationship-graph. Flat SVG import bakes the effective visibility. Layered import keeps-every standalone part SVG and records the source-owned booleans as-`slides[].showInheritedShapes` and `layouts[].showMasterShapes` in-`inheritance.json`, `manifest.json`, and `native_structure.json`. This is an-import/analysis fact; it does not introduce a generated-authoring SVG marker.+Imported inherited-shape visibility is an analysis fact, not generated SVG+authoring syntax; see+[`powerpoint-svg-mapping.md`](../../../docs/powerpoint-svg-mapping.md) §2 and+[`conversion.md`](../scripts/docs/conversion.md#pptx_to_svgpy).**Master text-style contract**: Flat and structured export map thelocked `title` size to every `a:defRPr` in Master `p:titleStyle`. Level 1 indiff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.mdindex 6089ba2b..75b0bc71 100644--- a/skills/ppt-master/scripts/docs/conversion.md+++ b/skills/ppt-master/scripts/docs/conversion.md@@ -238,6 +238,7 @@ Reconstruct a PPTX package as editable SVG views by reading OOXML directly.python3 scripts/pptx_to_svg.py deck.pptx --inheritance-mode bothpython3 scripts/pptx_to_svg.py deck.pptx --inheritance-mode layeredpython3 scripts/pptx_to_svg.py deck.pptx --inheritance-mode flat+python3 scripts/pptx_to_svg.py deck.pptx --strict```| Mode | Output |@@ -246,6 +247,27 @@ python3 scripts/pptx_to_svg.py deck.pptx --inheritance-mode flat| `layered` | Only the layered `svg/` view and inheritance metadata || `flat` | One self-contained slide SVG per page under `svg/` |+Import is tolerant by default because the source deck is user-owned or comes+from third-party authoring tools. Recovery happens at the narrowest safe+boundary: first omit only an unsupported property or feature; if that is not+possible, replace only the affected object with a visible diagnostic+placeholder; omit a background without discarding its page. Corrupt ZIP/XML or+missing required package structure remains fatal because no safe local recovery+exists. Pass `--strict` for parser development or contract verification when+the first unsupported/malformed source construct should stop conversion.++Every successful run writes `<output>/conversion-report.json`. Its stable+top-level fields are `schemaVersion`, `source`, `mode`, `summary`, and+`diagnostics`. Each diagnostic records a reason `code`, source `message`, chosen+`fallback`, package `part_path`, and—when available—`slide_index`, `shape_id`,+`shape_name`, and `shape_kind`. The command also prints a bounded warning+summary instead of a raw Python traceback.++In the detailed native-object notes below, “fails closed” or “error” describes+the native replacement claim or strict mode. Default tolerant deck import+retains the usable fallback/object and records the degradation; it does not+discard unrelated shapes, pages, or the entire deck.+Supported text-grid tables and conservative classic-chart caches carry a`data-pptx-replace-with` claim beside their SVG fallback, with the replacementpayload in a child `<metadata type="application/json">`. The parent claim@@ -273,7 +295,8 @@ rendered SVG table; unsupported charts keep a baked preview when one exists.For the currently supported parsed classic families (column/bar/line/area,pie/doughnut, scatter, and bubble), a chart without a baked preview receives adeterministic readable fallback marked-`data-pptx-fallback-kind="normalized"`. Unknown style XML still fails closed;+`data-pptx-fallback-kind="normalized"`. Unknown style XML disables the native+replacement claim or falls back to a diagnostic object in tolerant mode;common solid/no-fill/line/marker forms and scheme colors are normalized for theSVG fallback and core payload colors, while native opt-in may still normalizeunmodeled alpha, line, marker, or no-fill details. Common General, decimal,@@ -332,7 +355,8 @@ axis fields. The importer also accepts radar, safe `of_pie` `serLines`, theclosed axis/title/legend normalization cases, and bar/column `gapWidth` /`overlap`. `gapWidth` must be one integer in `0..500` and `overlap` one integerin `-100..100`; both normalize in native output, while malformed, duplicate, or-out-of-range values fail closed. These additions do not expand the normalized+out-of-range values disable the native replacement claim in tolerant mode and+stop strict import. These additions do not expand the normalizedrenderer.Safe stock series style may pass the structural gate, while stock series,`hiLowLines`, and up-down bar local styling can still normalize under the