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

feat(svg-to-pptx): convert literal page numbers to slide-number fields

hugohe3f6cf8486caad
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 123e3ca7..81b8ff95 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -427,7 +427,7 @@ These direct routes share some analysis primitives with the main pipeline, espec
**Why compatibility fallback belongs to the SVG snapshot path, not native shapes.** Native PPTX export translates supported SVG elements into DrawingML shapes and explicitly disables PNG+SVG compatibility mode in native-shapes mode. The PNG fallback is used only by the legacy SVG-image path (`--svg-snapshot` / `--only legacy`) when a renderer is available, because that path embeds SVG media that older Office builds may not display. Legacy compatibility is therefore an optional snapshot deliverable, not a fallback bundled inside the primary editable native deck.
-**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, and base-template slide layouts no generated slide references are pruned from the package. This gives ordinary decks real master/layout structure without guessing reusable layouts or placeholders from visual similarity.
+**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, base-template slide layouts no generated slide references are pruned from the package, and `pageNumber`/`slideNumber` chrome whose text exactly equals the slide's display number (honoring `firstSlideNum`) becomes an auto-updating slide-number field so reordering slides in PowerPoint renumbers pages. 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. 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/technical-design.md b/docs/zh/technical-design.md
index db3d4657..728e4386 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -427,7 +427,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份
**为什么兼容 fallback 属于 SVG snapshot 路径,而不是 native shapes。** Native PPTX 导出会把受支持的 SVG 元素翻译成 DrawingML 形状,并在 native-shapes 模式下显式关闭 PNG+SVG 兼容模式。PNG fallback 只在 legacy SVG-image 路径(`--svg-snapshot` / `--only legacy`)且本地 renderer 可用时使用,因为那条路径嵌入的是旧版 Office 可能无法显示的 SVG media。因此,旧版兼容是一份可选 snapshot 交付物,不是捆在主 editable native deck 里的兜底层。
-**为什么默认 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,基础模板中没有任何页面引用的 slide layout 也会从 package 中裁剪掉。这样普通 deck 能获得真实的 master/layout 结构,同时不根据视觉相似度猜测可复用版式或占位符。
+**为什么默认 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,基础模板中没有任何页面引用的 slide layout 也会从 package 中裁剪掉;`pageNumber`/`slideNumber` chrome 的文本若恰好等于该页应显示的页码(尊重 `firstSlideNum`),会转换为自动更新的 PowerPoint 页码字段,此后在 PowerPoint 中调整页序页码自动重算,其他编号方案保持字面文本不动。这样普通 deck 能获得真实的 master/layout 结构,同时不根据视觉相似度猜测可复用版式或占位符。
**为什么原生对象重建使用 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 acb1ab65..20a30de1 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -680,8 +680,11 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> chrome stays slide-local. Image relationships for promoted chrome are copied to
> the master. Baseline also prunes base-template slide layouts no generated
> slide references, so the PowerPoint new-slide picker only offers layouts that
-> belong to the deck. Add `--pptx-structure flat` only for debugging/comparison
-> when all generated backgrounds and chrome must remain slide-local.
+> belong to the deck, and converts `pageNumber` / `slideNumber` chrome whose
+> text exactly equals the slide's display number into an auto-updating
+> PowerPoint slide-number field (other numbering schemes keep their literal
+> text). Add `--pptx-structure flat` only for debugging/comparison when all
+> generated backgrounds and chrome must remain slide-local.
> **Paragraph editability vs line fidelity** — by default, mergeable dy-stacked
> paragraph blocks collapse into one editable PowerPoint text frame with multiple
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index a8800f94..b75b6cec 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -116,7 +116,7 @@ python3 scripts/svg_to_pptx.py <project_path>
`finalize_svg.py` optimizes raster images by default using `2x` display pixels and max `2560px`. Native `svg_to_pptx.py` defaults to `--image-sizing cap`: only oversized full source images are reduced to max `2560px`, so later PowerPoint resizing keeps more image detail. Use `svg_to_pptx.py --image-sizing display --image-scale 2` only for aggressive size reduction, or `--no-image-optimize` when the native PPTX must embed original image bytes.
-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. Baseline additionally prunes base-template slide layouts that no generated slide references. Use `--pptx-structure flat` when all generated backgrounds and chrome must remain slide-local for debugging or comparison.
+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. Baseline additionally prunes base-template slide layouts that no generated slide references, and swaps `pageNumber`/`slideNumber` chrome text for an auto-updating slide-number field when the text exactly equals the slide's display number. 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 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.
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
index 7470e8e7..672bb43b 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
@@ -671,6 +671,120 @@ def _promote_common_chrome_shapes_to_masters(
return promoted
+_PAGE_NUMBER_TOKENS = {"pagenumber", "pagenum", "slidenumber"}
+
+
+def _first_slide_number(extract_dir: Path) -> int:
+ """Read firstSlideNum from presentation.xml (defaults to 1)."""
+ presentation_path = extract_dir / "ppt" / "presentation.xml"
+ try:
+ root = ET.parse(presentation_path).getroot()
+ except (OSError, ET.ParseError):
+ return 1
+ raw = root.attrib.get("firstSlideNum")
+ if raw is None:
+ return 1
+ try:
+ return int(raw)
+ except ValueError:
+ return 1
+
+
+def _shape_with_id(root: ET.Element, shape_id: str) -> ET.Element | None:
+ """Find a p:sp anywhere in the slide tree by its cNvPr id."""
+ for shape in root.iter(f"{{{PML_NS}}}sp"):
+ cnv = shape.find(f"{{{PML_NS}}}nvSpPr/{{{PML_NS}}}cNvPr")
+ if cnv is not None and cnv.attrib.get("id") == shape_id:
+ return shape
+ return None
+
+
+def _replace_literal_run_with_slidenum_field(
+ shape: ET.Element,
+ expected_text: str,
+ field_guid: str,
+) -> bool:
+ """Swap a single literal page-number run for an a:fld slidenum field."""
+ tx_body = shape.find(f"{{{PML_NS}}}txBody")
+ if tx_body is None:
+ return False
+ a_t = f"{{{DML_NS}}}t"
+ total_text = "".join(t.text or "" for t in tx_body.iter(a_t))
+ if total_text.strip() != expected_text:
+ return False
+ text_runs = [
+ (paragraph, run)
+ for paragraph in tx_body.iter(f"{{{DML_NS}}}p")
+ for run in paragraph.findall(f"{{{DML_NS}}}r")
+ if (run.findtext(a_t) or "").strip()
+ ]
+ if len(text_runs) != 1:
+ return False
+ paragraph, run = text_runs[0]
+ if (run.findtext(a_t) or "").strip() != expected_text:
+ return False
+
+ fld = ET.Element(f"{{{DML_NS}}}fld", {"id": field_guid, "type": "slidenum"})
+ r_pr = run.find(f"{{{DML_NS}}}rPr")
+ if r_pr is not None:
+ fld.append(ET.fromstring(ET.tostring(r_pr, encoding="utf-8")))
+ fld_text = ET.SubElement(fld, a_t)
+ fld_text.text = expected_text
+ index = list(paragraph).index(run)
+ paragraph.remove(run)
+ paragraph.insert(index, fld)
+ return True
+
+
+def _convert_page_number_texts_to_fields(
+ extract_dir: Path,
+ slide_count: int,
+ conversion_traces: list[dict[str, Any]] | None,
+ *,
+ verbose: bool = False,
+) -> int:
+ """Replace literal page-number chrome text with auto-updating fields.
+
+ Only converts when the traced pageNumber/slideNumber shape's whole text
+ equals the slide's expected display number (honoring firstSlideNum), so
+ schemes like content-only numbering keep their literal text untouched.
+ """
+ if not conversion_traces:
+ return 0
+ trace_by_slide = {
+ int(trace.get("slide_num", 0)): trace
+ for trace in conversion_traces
+ if trace.get("slide_num") is not None
+ }
+ first_slide_number = _first_slide_number(extract_dir)
+ field_guid = f"{{{str(uuid.uuid4()).upper()}}}"
+
+ converted = 0
+ for slide_num in range(1, slide_count + 1):
+ tokens = _trace_chrome_shape_ids(trace_by_slide.get(slide_num))
+ shape_ids = sorted({
+ shape_id
+ for token, ids in tokens.items()
+ if token in _PAGE_NUMBER_TOKENS
+ for shape_id in ids
+ })
+ if len(shape_ids) != 1:
+ continue
+ slide_path = extract_dir / "ppt" / "slides" / f"slide{slide_num}.xml"
+ tree = ET.parse(slide_path)
+ shape = _shape_with_id(tree.getroot(), shape_ids[0])
+ if shape is None:
+ continue
+ expected_text = str(first_slide_number + slide_num - 1)
+ if _replace_literal_run_with_slidenum_field(shape, expected_text, field_guid):
+ _write_xml_tree(slide_path, tree)
+ converted += 1
+
+ if verbose and converted:
+ print(f" Baseline slide-number fields: converted {converted} page number(s)")
+ return converted
+
+
def _remove_relationship(rels_path: Path, rel_id: str) -> None:
"""Remove one relationship entry by rId."""
rels_content = rels_path.read_text(encoding="utf-8")
@@ -1928,6 +2042,12 @@ def create_pptx_with_native_svg(
and pptx_structure == "baseline"
and success_count == len(svg_files)
):
+ _convert_page_number_texts_to_fields(
+ extract_dir,
+ len(svg_files),
+ conversion_trace if conversion_trace is not None else structure_trace,
+ verbose=verbose,
+ )
_promote_common_slide_backgrounds_to_masters(
extract_dir,
structure,