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-objects): document P1 reconstruction boundaries

hugohe3d92f3ec85e82
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 8a1ae0b4..f4cef9c3 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -466,7 +466,7 @@ These direct routes share some analysis primitives with the main pipeline, espec
**Why each template SVG stays complete while still compiling to a Layout.** A generated SVG is a complete standalone preview, so it repeats inherited Master/Layout visuals together with its selectable Slide content. `page_layouts` names the input reference and `pptx_layouts` names the output Layout; both exist for every template page. Strict keeps the selected contract, while adaptive may lock a new Layout key under the same Master. Export removes repeated inherited copies and emits real Master/Layout parts, leaving actual content on the Slide.
-**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. Table metadata records the source table-style ID and supported direct solid cell fills/basic text formatting, but the SVG fallback currently resolves direct cell properties only; inherited built-in/custom table-style appearance is not guaranteed. The importer also retains 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 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. Fallback-only objects carry `data-pptx-native-status`; the quality checker and native-object export report them as warnings. A chart without a baked preview instead carries `visual=placeholder` / `route=reconstruction-only`; validation and export warn, default export keeps the placeholder, and `--native-objects` may reconstruct it when a valid active native-chart payload is available. Invalid status declarations remain errors. 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. The normalized fallback for table style `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}` resolves `wholeTbl`, `firstRow`, horizontal banding, theme colors/fonts, and direct overrides; this does not imply a full built-in/custom style registry. For supported parsed column/bar/line/area, pie/doughnut, scatter, and bubble charts, a missing baked preview is replaced by a deterministic readable SVG fallback with `visual=normalized`. Common solid/no-fill/line/marker forms and scheme colors are accepted conservatively; unknown style XML still fails closed. Native replacement may normalize style details absent from the payload, which remains part of the explicit editable-first warning. The importer also retains chart title/legend/axis titles and supported plot-level data-label flags. The default export 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 import, 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. Active types outside the current renderer, including `of_pie`, retain `visual=placeholder` / `route=reconstruction-only`; native opt-in may still reconstruct their valid payload. Every active imported marker is stamped with `data-pptx-fallback-sha256`: stale visible edits, reachable SVG fragment-definition changes, marker-local reference-target changes, or marker transforms are reported by the mandatory checker; default export keeps the SVG, while native replacement hard-fails. Hashless legacy markers remain compatible with a checker/native-route warning. ChartEx emission consumes valid payload colors in the color-style part, without claiming full source-style fidelity. Invalid status declarations remain errors. 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/technical-design.md b/docs/zh/technical-design.md
index 378ec808..d266af71 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -466,7 +466,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
**为什么模板 SVG 保持完整却仍能编译成版式。** 每张生成 SVG 都是可独立预览的完整 slide,因此会重复携带继承的 Master/Layout 视觉和可选择的 Slide 内容。`page_layouts` 指定输入参考,`pptx_layouts` 指定输出版式,两者在模板路线中逐页齐全。严格模式保持所选契约;自适应模式可在同一 Master 下锁定新 Layout。导出器移除重复继承层并生成真实 Master/Layout,实际内容仍留在 Slide。
-**为什么原生对象重建使用 marker,而不是自动替换对象。** 独立的 `pptx_to_svg.py` 导入器会为受支持的未合并表格和保守 classic-chart cache 输出 SVG fallback,并附加 `data-pptx-native` 元数据。表格元数据会记录源 table-style ID 以及受支持的单元格直接纯色填充 / 基础文字格式,但当前 SVG fallback 只解析直接单元格属性,尚不保证还原 built-in/custom table style 的继承外观;图表标题、图例、坐标轴标题和面积图 / 条形图 / 柱形图 / 折线图的 plot 级数据标签开关则在现有 schema 可表达时保留。由本 exporter 生成的规范 classic chart 还会回读规范纯色系列 / 切片,以及精确的单段或双段标题元数据。默认导出仍把 fallback 子元素当普通 DrawingML shape 处理;只有 `--native-objects` 才会启用可编辑的 PowerPoint 表格 / 图表。合并单元格、直接边框、非纯色填充、混合富文本等不支持的表格场景继续保留实际渲染的 SVG table。ChartEx、旋转 / 翻转 / 3D / 组合图表、不受支持的数据标签作用域或类型、自定义坐标轴语义、趋势线 / 误差线、不受支持的子类型参数、稀疏或非有限 cache、日期 / 格式化类别轴等不支持的图表场景,在有 baked preview 时保留预览。fallback-only 对象写入 `data-pptx-native-status`,质量检查器和 native-object 导出把它报告为 warning;没有 baked preview 的图表则写入 `visual=placeholder` / `route=reconstruction-only`。校验和导出会给出 warning,默认导出保留占位符;当存在有效 active native-chart payload 时,`--native-objects` 仍可重建可编辑图表。非法状态声明继续作为 error。这对 importer/exporter 是重建辅助能力,不能替代 `template-fill-pptx` 或 `native-enhance-pptx` 的保留型路线。
+**为什么原生对象重建使用 marker,而不是自动替换对象。** 独立的 `pptx_to_svg.py` 导入器会为受支持的未合并表格和保守 classic-chart cache 输出 SVG fallback,并附加 `data-pptx-native` 元数据。表格样式 `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}` 的规范化 fallback 会解析 `wholeTbl`、`firstRow`、横向带状行、主题颜色 / 字体和直接格式覆盖;这不代表已经实现完整 built-in/custom style registry。受支持的柱 / 条 / 折线 / 面积、饼 / 圆环、散点 / 气泡图在没有 baked preview 时会生成确定性、可读的 SVG fallback,并标记 `visual=normalized`。常见 solid/no-fill/line/marker 写法和 scheme color 会被保守解析,未知 style XML 仍 fail closed;payload 未建模的样式细节在 native 替换时仍可能归一化,并由 editable-first warning 明示。图表标题、图例、坐标轴标题和受支持的数据标签语义继续保留。默认导出把 fallback 子元素当普通 DrawingML shape 处理;只有 `--native-objects` 才启用可编辑的 PowerPoint 表格 / 图表。合并单元格、直接边框、非纯色填充、混合富文本等不支持的表格场景继续保留 SVG table。ChartEx 导入、旋转 / 翻转 / 3D / 组合图表、不受支持的数据标签、自定义坐标轴、趋势线 / 误差线、不受支持的子类型、稀疏或非有限 cache、日期 / 格式化类别轴等场景在有 baked preview 时保留预览。当前 renderer 范围之外但 payload 仍有效的类型(包括 `of_pie`)继续使用 `visual=placeholder` / `route=reconstruction-only`,native opt-in 仍可重建。每个 active imported marker 都写入 `data-pptx-fallback-sha256`:可见 fallback、可达的 SVG fragment definition、marker 内部引用目标或 marker transform 后续被改动时,强制质量检查器会报告 stale;默认导出继续保留 SVG,native replacement hard fail。无 hash 的旧 marker 仍兼容,只在 checker/native 路线提示无法检测 stale。ChartEx emitter 现在把有效 payload colors 写入 color-style part,但不承诺完整源样式保真。非法状态声明继续作为 error。这对 importer/exporter 是重建辅助能力,不能替代 `template-fill-pptx` 或 `native-enhance-pptx` 的保留型路线。
---
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index a2a0cff9..49c30e1d 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -859,7 +859,16 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> Default export keeps that placeholder with a warning; when the same group has
> a valid active `data-pptx-native="chart"` payload, `--native-objects` may still
> reconstruct the editable chart. Invalid or contradictory status declarations
-> remain export errors.
+> remain export errors. For supported parsed classic families, the importer
+> instead emits a deterministic visible fallback with
+> `data-pptx-visual-status="normalized"`; this is readable reconstruction, not
+> a claim of Office pixel parity. Active imported table/chart markers also carry
+> `data-pptx-fallback-sha256`. If their fallback, reachable SVG fragment
+> definition, local reference target, or marker transform changes later, default
+> export keeps that SVG, the mandatory quality checker warns, and
+> `--native-objects` fails rather than discard the edit. Legacy markers
+> without a baseline remain native-compatible and only warn that stale detection
+> is unavailable.
**Optional animation flags** (page transitions are on by default; per-element entrance is off by default — turn it on only when the user asks for it):
- `-t <effect>` — page transition. Default `fade`. Options: `fade` / `push` / `wipe` / `split` / `strips` / `cover` / `random` / `none`. `none` removes only the visual transition; an explicit automatic advance remains valid.
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index b8bb4a84..ccb0c198 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -1003,11 +1003,30 @@ 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
-type, and chart data shape before export.
+type, 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
+native metadata stale. The mandatory quality checker warns and the default route
+keeps the edited SVG; `--native-objects` 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.
+Hashless legacy markers remain native-compatible and warn in the checker/native
+route that stale detection is unavailable. A stale hash is an integrity mismatch,
+not a visual-parity gate on an unchanged active marker.
**Hard rule — imported visual/route status**: A PPTX chart with a complete baked preview
-may carry `data-pptx-visual-status="source-preview"`. When no preview exists,
-the importer emits its typed reconstruction aid with both
+may carry `data-pptx-visual-status="source-preview"`. Supported parsed classic
+families without a preview use a deterministic readable fallback marked
+`data-pptx-visual-status="normalized"`; it is explicitly not source-exact.
+When no current renderer exists, the importer emits its typed reconstruction aid with both
`data-pptx-visual-status="placeholder"` and
`data-pptx-route-status="reconstruction-only"`. The valid pair is diagnostic:
quality checking and export warn, default export keeps the placeholder, and
@@ -1159,6 +1178,10 @@ OOXML RGB. Bar and column series also disable PowerPoint's negative-value
inversion so negative bars keep the same series fill instead of turning into
white/theme fill.
+For ChartEx native charts, valid payload `style.colors` (or root `colors`)
+populate the ChartEx color-style part instead of being replaced by a fixed
+accent1–accent6 list. Other ChartEx style semantics remain normalized.
+
**PowerPoint chartEx schema**: `treemap`, `sunburst`, `histogram`, `pareto`,
`boxWhisker`, `waterfall`, and `funnel` use Office 2016+ chartEx parts. Use
these input shapes:
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 44b11a80..edc34cfd 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -138,7 +138,9 @@ Deck/layout template routes use explicit template structure. Each complete SVG n
Current `create-template` output always rebuilds explicit SVG structure and does not package `native_structure.json` or `source_template.pptx`. `preserve` remains available only for existing projects that already carry the legacy pair.
-`pptx_to_svg.py` annotates supported unmerged tables and conservative classic-chart caches with `data-pptx-native` metadata. Table metadata records the source table-style ID and supported direct solid cell fills/basic text formatting, but the SVG fallback currently resolves direct cell properties only; inherited built-in/custom table-style appearance is not guaranteed. 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, mixed rich-text formatting, or merges remain fallback-only, as do charts with unsupported label scopes/types, custom axis semantics, trendlines/error bars, or subtype options. Fallback-only objects keep rendered SVG content or a baked chart preview and carry `data-pptx-native-status`, which validation and `--native-objects` export report as a warning. A chart with no baked preview instead carries `data-pptx-visual-status="placeholder"` plus `data-pptx-route-status="reconstruction-only"`; validation/export warn, default export keeps the placeholder, and `--native-objects` may reconstruct it when a valid active native-chart payload is present.
+`pptx_to_svg.py` annotates supported unmerged tables and conservative classic-chart caches with `data-pptx-native` metadata. For table style `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}`, its normalized SVG fallback resolves `wholeTbl`, `firstRow`, horizontal banding, theme colors/fonts, and direct cell/run overrides; other built-in/custom style families are not implied. Supported parsed column/bar/line/area, pie/doughnut, scatter, and bubble charts without a baked preview receive a deterministic readable fallback marked `data-pptx-visual-status="normalized"`. Safe common series paint forms and theme scheme colors are resolved, while unknown style XML still fails closed. The editable native replacement remains allowed to normalize unmodeled no-fill/alpha/line/marker details and reports the route-level loss risk. Chart title/legend/axis titles and supported data-label flags are retained when the current schema can represent them. Tables with direct borders, non-solid fills, mixed rich-text formatting, or merges remain fallback-only, as do charts with unsupported label scopes/types, custom axis semantics, trendlines/error bars, or subtype options. Fallback-only objects keep rendered SVG content or a baked chart preview and carry `data-pptx-native-status`, which validation and `--native-objects` export report as a warning. A supported active marker without a renderer, such as current `of_pie`, keeps `data-pptx-visual-status="placeholder"` plus `data-pptx-route-status="reconstruction-only"`; default export keeps the placeholder and native opt-in may still reconstruct it.
+
+Active imported table/chart markers carry `data-pptx-fallback-sha256`. Visible fallback edits, reachable SVG fragment-definition changes, marker-local reference-target changes, and marker transforms make the baseline stale: the mandatory quality checker warns, default export remains available, and `--native-objects` fails instead of discarding the SVG edit. Legacy markers without a baseline remain convertible with a checker/native-route warning. ChartEx export now writes valid payload palette entries into its color-style part; it still does not promise full source ChartEx styling.
Exporter-canonical classic charts also recover canonical solid series/slice
colors and exact one- or two-paragraph title styling; two paragraphs retain
diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.md
index e1b7b880..24043f85 100644
--- a/skills/ppt-master/scripts/docs/conversion.md
+++ b/skills/ppt-master/scripts/docs/conversion.md
@@ -253,7 +253,17 @@ it may normalize styling or omit marker-local details not represented by the
payload, and export reports that risk without disabling an otherwise supported
active marker. Unsupported tables keep their
rendered SVG table; unsupported charts keep a baked preview when one exists.
-Charts without a baked preview use an explicit placeholder marked
+For the currently supported parsed classic families (column/bar/line/area,
+pie/doughnut, scatter, and bubble), a chart without a baked preview receives a
+deterministic readable fallback marked
+`data-pptx-visual-status="normalized"`. Unknown style XML still fails closed;
+common solid/no-fill/line/marker forms and scheme colors are normalized for the
+SVG fallback and core payload colors, while native opt-in may still normalize
+unmodeled alpha, line, marker, or no-fill details. Common General, decimal,
+grouped, percent, and simple currency-prefix data-label formats render
+deterministically; an unknown Excel format program keeps the active payload but
+does not claim a normalized fallback. Active types outside the
+current renderer, including `of_pie`, continue to use an explicit placeholder marked
`data-pptx-visual-status="placeholder"` and
`data-pptx-route-status="reconstruction-only"`. Validation and export report
that route as a warning. Default export keeps the placeholder; when the same
@@ -263,6 +273,25 @@ remain errors.
Fallback-only native capability uses `data-pptx-native-status` and remains a
warning when the SVG fallback itself is complete.
+Active imported markers also carry `data-pptx-fallback-sha256`, computed over
+their canonical fallback plus reachable document-level SVG fragment definitions.
+A later visible edit, reachable definition change, local reference-target
+change, or marker transform makes the native metadata stale. The mandatory
+quality checker reports the mismatch; default export keeps the edited fallback,
+while `--native-objects` fails before replacement so it cannot discard that edit.
+`visibility:hidden` content, marker-local unused definitions, and explicitly
+referenced document-level target roots (even when hidden) are included
+conservatively; marker-local `display:none` subtrees are excluded, and external
+file bytes are not read.
+A legacy marker without the hash remains native-compatible and warns in the
+checker/native route that stale detection is unavailable.
+
+For table style `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}`, the importer resolves
+the normalized `wholeTbl`, `firstRow`, `band1H`/`band2H`, theme color/font, and
+direct-format override subset. Other built-in/custom style families remain
+outside this guarantee. ChartEx native output consumes valid payload colors in
+its color-style part; other ChartEx style details remain normalized.
+
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.
diff --git a/skills/ppt-master/templates/charts/README.md b/skills/ppt-master/templates/charts/README.md
index a4234fe8..1a1f7456 100644
--- a/skills/ppt-master/templates/charts/README.md
+++ b/skills/ppt-master/templates/charts/README.md
@@ -16,7 +16,7 @@ See [`CHART_STYLE_GUIDE.md`](./CHART_STYLE_GUIDE.md) for color palette, typograp
Supported data chart templates include a `<g data-pptx-native="chart">` marker by default, and pure text-grid table templates include a `<g data-pptx-native="table">` marker the same way. The default SVG export path is unchanged: the fallback vector artwork is exported exactly as drawn. When `svg_to_pptx.py --native-objects` is enabled, that marked fallback group is replaced with an editable PowerPoint chart or table using the JSON metadata inside the child `<metadata data-pptx-native="...">` node.
-`--native-objects` is an explicit editable-first opt-in and may be lossy or visually normalized. Marker-local value labels, center KPIs, callouts, quadrant notes, fixed axis ranges, custom binning/splits, and exact ChartEx colors may not survive native replacement unless represented by the payload. Detectable information-loss risks should be reported as warnings, not handled by disabling an otherwise supported native marker. Review those warnings and compare the native export with the default SVG export before delivery.
+`--native-objects` is an explicit editable-first opt-in and may be lossy or visually normalized. Marker-local value labels, center KPIs, callouts, quadrant notes, fixed axis ranges, and custom binning/splits may not survive native replacement unless represented by the payload. ChartEx palette entries do survive when supplied through valid payload colors, but this does not preserve every ChartEx style detail. Detectable information-loss risks should be reported as warnings, not handled by disabling an otherwise supported native marker. Review those warnings and compare the native export with the default SVG export before delivery.
Native marker authoring remains active for all 23 currently supported data-chart templates: