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(pptx): merge paragraphs by default

hugohe337dabd3feb41
diff --git a/docs/faq.md b/docs/faq.md
index dedcadab..96a787bc 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -48,19 +48,19 @@ Yes. The main `.pptx` (native PowerPoint shapes — all text, graphics, and colo
## Q: Why is one paragraph split into multiple text boxes? Can I get one text box per paragraph instead?
-By default yes — every visual line of body text becomes its own PowerPoint text frame. This preserves the SVG's exact line layout pixel-for-pixel, which matters for covers, charts, tables, and any page with tight typographic alignment.
+By default, mergeable body-text paragraphs export as one editable PowerPoint text frame with multiple paragraphs. Resizing the box reflows text inside it.
-If you'd rather edit body text as whole paragraphs, re-export with `--merge-paragraphs`:
+If you need strict line-layout fidelity, re-export with `--no-merge`:
```bash
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --merge-paragraphs
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --no-merge
```
-Mergeable paragraph blocks (same x, dy clustered around one line-height, optional larger gap for paragraph breaks) collapse into one editable text frame with multiple `<a:p>` and precise line-spacing. Resizing the box reflows text inside it.
+With `--no-merge`, every visual line becomes its own PowerPoint text frame. This preserves the SVG's exact line layout pixel-for-pixel, which matters for covers, charts, tables, and any page with tight typographic alignment.
-**Trade-off**: PowerPoint may wrap the merged paragraphs to a different line count than the SVG source — so the page won't match the original layout exactly. Best for long-form body text (abstracts, multi-paragraph sections, reference lists); keep the default for layout-tight pages. The detection is conservative — mixed-layout `<text>` falls through to the default per-line path automatically.
+**Trade-off**: default paragraph merging lets PowerPoint wrap merged paragraphs to a different line count than the SVG source. Best for long-form body text (abstracts, multi-paragraph sections, reference lists); use `--no-merge` for layout-tight pages. The detection is conservative — mixed-layout `<text>` falls through to the per-line path automatically.
-When you're chatting with the AI, you can also just ask: "I want to edit the abstract as one block" / "make text boxes resizable" — the AI will turn this on for you. Defaults stay off so existing decks aren't affected.
+When you're chatting with the AI, you can also just ask for strict line fidelity on layout-sensitive pages — the AI will add `--no-merge` when re-exporting.
## Q: What's the difference between the three Executors?
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index d4fca82d..0e54c482 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -48,19 +48,19 @@ PPT Master 可以在任何能读取文件和执行命令的 AI 编程代理中
## Q: 为什么一段正文被拆成了好几个文本框?能不能一段一个文本框?
-默认就是按行拆框——SVG 里的每一视觉行都会变成一个独立的 PowerPoint 文本框。这样做是为了**逐像素保留 SVG 的版式**,对封面、图表、表格、以及任何对版式精度敏感的页面来说是必要的。
+默认会把可合并的正文段落导出成一个可编辑的 PowerPoint 文本框,内部保留多个段落。**拉伸框时文字会在框内自动重排**。
-如果你希望按整段编辑正文,重新导出时加上 `--merge-paragraphs`:
+如果你需要严格保持逐行版式,重新导出时加上 `--no-merge`:
```bash
-python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --merge-paragraphs
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --no-merge
```
-可合并的段落块(同 x、dy 围绕同一行距聚集、段间允许更大间距)会合并成一个可编辑的文本框,内部为多个 `<a:p>`,并精确保留行距。**拉伸框时文字会在框内自动重排**。
+使用 `--no-merge` 时,SVG 里的每一视觉行都会变成一个独立的 PowerPoint 文本框。这样能**逐像素保留 SVG 的版式**,适合封面、图表、表格、以及任何对版式精度敏感的页面。
-**代价**:PowerPoint 自动换行后,行数可能与原 SVG 不一致——页面版式会与原 SVG 有偏差。适合正文密集型页面(abstract、多段落章节、参考文献等);版式敏感的页面继续用默认。判定足够保守——非段落型 `<text>` 会自动落回默认的按行拆框路径。
+**代价**:默认段落合并后,PowerPoint 自动换行的行数可能与原 SVG 不一致。默认更适合正文密集型页面(abstract、多段落章节、参考文献等);版式敏感页面使用 `--no-merge`。判定足够保守——非段落型 `<text>` 会自动落回按行拆框路径。
-跟 AI 对话时也可以直接说:"我想整段编辑 abstract" / "让文本框能自适应" —— AI 会替你打开这个开关。默认关闭,不影响已有项目。
+跟 AI 对话时也可以直接说:"这个页面要严格保持逐行版式" —— AI 重新导出时会加上 `--no-merge`。
## Q: 三种执行师有什么区别?
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index aab4ada1..05f05a93 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -497,13 +497,12 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> SVG visual reference, so it's only needed when you want a self-contained file
> to share. Pass `-s output` or `-s final` to force a single source if you need it.
-> **Paragraph editability vs line fidelity** — by default every dy-stacked line is
-> its own PowerPoint text frame, preserving exact SVG layout. Add `--merge-paragraphs`
-> only when the user explicitly asks for an editable / wrap-friendly export (e.g.
-> "I want to edit the abstract as one block", "make text boxes resizable / reflow"):
-> mergeable paragraph blocks collapse into one editable text frame with multiple
-> `<a:p>`, at the cost of PowerPoint re-wrapping inside each box. Default off keeps
-> pixel-fidelity; turn it on per the user's request, not on your own judgement.
+> **Paragraph editability vs line fidelity** — by default, mergeable dy-stacked
+> paragraph blocks collapse into one editable PowerPoint text frame with multiple
+> `<a:p>`, improving body-text editing and resize/reflow behavior. Add `--no-merge`
+> only when the user explicitly asks for strict line-layout fidelity or when a
+> layout-tight page must keep every dy-stacked line as its own text frame. The
+> merge detector is conservative; mixed-layout text falls back to per-line frames.
**Optional animation flags** (the defaults already enable rich entrance animations — adjust only when the user asks for something different):
- `-t <effect>` — page transition. Default `fade`. Options: `fade` / `push` / `wipe` / `split` / `strips` / `cover` / `random` / `none`.
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 2c4ea366..7b36b18a 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -39,7 +39,7 @@ python3 scripts/svg_to_pptx.py <project_path> --no-notes
python3 scripts/svg_to_pptx.py <project_path> -t none
python3 scripts/svg_to_pptx.py <project_path> --auto-advance 3
python3 scripts/svg_to_pptx.py <project_path> --animation mixed --animation-duration 0.8
-python3 scripts/svg_to_pptx.py <project_path> --merge-paragraphs # editability-first mode (see below)
+python3 scripts/svg_to_pptx.py <project_path> --no-merge # strict line-fidelity mode (see below)
python3 scripts/notes_to_audio.py <project_path> --voice zh-CN-XiaoxiaoNeural
python3 scripts/svg_to_pptx.py <project_path> --recorded-narration audio
```
@@ -52,10 +52,10 @@ Behavior:
- `exports/<project_name>_<timestamp>_svg.pptx` — SVG snapshot pptx for visual reference, sibling of the native pptx
- Live preview already serves as the SVG visual reference for day-to-day use; the snapshot pptx is for distribution or frozen-state archival
- Explicit `-o/--output` skips `backup/`; pair with `--svg-snapshot` to also emit the side-by-side `_svg.pptx` next to the chosen path
-- `--merge-paragraphs` (opt-in) trades SVG line-layout fidelity for PowerPoint editability:
- - Default: every dy-stacked `<tspan>` becomes its own text frame — exact SVG line layout is preserved but a 12-line paragraph is 12 separate textboxes
- - With the flag: mergeable paragraph blocks (same x, dy clustered around one base line-height, optional larger gap for paragraph breaks) collapse into one editable text frame with multiple `<a:p>` and precise `<a:lnSpc>` / `<a:spcBef>`. Resizing the box reflows text inside it.
- - Side effect: PowerPoint may wrap merged paragraphs to a different line count than the SVG source. Pages with tight typographic alignment (covers, charts, tables) usually want the default; long body text (abstracts, multi-paragraph sections, reference lists) usually benefits from the flag
+- Paragraph merging is enabled by default and trades some SVG line-layout fidelity for PowerPoint editability:
+ - Default: mergeable paragraph blocks (same x, dy clustered around one base line-height, optional larger gap for paragraph breaks) collapse into one editable text frame with multiple `<a:p>` and precise `<a:lnSpc>` / `<a:spcBef>`. Resizing the box reflows text inside it.
+ - With `--no-merge`: every dy-stacked `<tspan>` becomes its own text frame — exact SVG line layout is preserved but a 12-line paragraph is 12 separate textboxes
+ - Side effect: PowerPoint may wrap merged paragraphs to a different line count than the SVG source. Long body text (abstracts, multi-paragraph sections, reference lists) usually benefits from the default; pages with tight typographic alignment (covers, charts, tables) usually want `--no-merge`
- Mergeable detection is conservative: only fires when the children form a clean paragraph block; mixed-layout `<text>` falls through to the default per-line path
- Recommended source directory: `svg_final/`
- For PPTX template-import workspaces, use `-s svg-flat` when you need a visual round-trip check. The layered `svg/` tree is the machine-readable template source and intentionally does not inline inherited master / layout decoration into each slide.
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py
index 36476c9e..373cb3b5 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py
@@ -47,10 +47,9 @@ class ConvertContext:
# Top-level <g id="..."> groups, recorded as (shape_id, svg_id) in z-order.
# Used by the PPTX builder to emit per-element entrance timing.
anim_targets: list = field(default_factory=list)
- # Opt-in flag (default off): merge mergeable paragraph blocks into one
- # editable text frame with multiple <a:p>. Off preserves the original
- # one-line-per-textbox behavior and the SVG's exact pixel layout.
- merge_paragraphs: bool = False
+ # Default-on flag: merge mergeable paragraph blocks into one editable
+ # text frame with multiple <a:p>. Disable it for strict line fidelity.
+ merge_paragraphs: bool = True
# Optional per-element conversion diagnostics. Shared by child contexts so
# callers can inspect native / skipped / unsupported decisions per slide.
trace_events: list[dict[str, Any]] | None = None
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
index bb69d0f8..b58245b3 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
@@ -420,7 +420,7 @@ def convert_svg_to_slide_shapes(
svg_path: Path,
slide_num: int = 1,
verbose: bool = False,
- merge_paragraphs: bool = False,
+ merge_paragraphs: bool = True,
trace_out: list[dict[str, Any]] | None = None,
) -> tuple[str, dict[str, bytes], list[dict[str, str]], list]:
"""Convert an SVG file to a complete DrawingML slide XML.
@@ -429,10 +429,10 @@ def convert_svg_to_slide_shapes(
svg_path: Path to the SVG file.
slide_num: Slide number (for naming).
verbose: Print progress info.
- merge_paragraphs: Opt-in. When True, mergeable paragraph blocks
- (same x, dy clustered around one base line-height) become a
- single editable text frame with multiple <a:p>. Default False
- preserves the SVG's exact line layout (one textbox per line).
+ merge_paragraphs: When True, mergeable paragraph blocks (same x,
+ dy clustered around one base line-height) become a single
+ editable text frame with multiple <a:p>. Disable it to preserve
+ the SVG's exact line layout (one textbox per line).
trace_out: Optional list populated with one per-slide trace dictionary.
Returns:
@@ -469,8 +469,8 @@ def convert_svg_to_slide_shapes(
# and an x-anchored tspan would render in the wrong column. finalize_svg
# does the same flattening on disk; doing it here keeps native pptx output
# correct when reading raw svg_output/.
- # merge_paragraphs (opt-in) additionally folds mergeable paragraph blocks
- # into a single annotated <text> for downstream multi-<a:p> conversion.
+ # merge_paragraphs additionally folds mergeable paragraph blocks into a
+ # single annotated <text> for downstream multi-<a:p> conversion.
from .tspan_flattener import flatten_positional_tspans
flattened = flatten_positional_tspans(tree, merge_paragraphs=merge_paragraphs)
if flattened:
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml_elements.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml_elements.py
index 9304543e..28a55572 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml_elements.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml_elements.py
@@ -1050,7 +1050,7 @@ def convert_text(elem: ET.Element, ctx: ConvertContext) -> ShapeResult | None:
# <a:p> so the paragraph survives as a single editable text frame.
# Per-line data-paragraph-space-before encodes paragraph gaps (extra dy
# above the base line-height) for the corresponding <a:p>.
- # Paragraph mode is opt-in via ctx.merge_paragraphs. When off, ignore
+ # Paragraph mode is controlled by ctx.merge_paragraphs. When off, ignore
# any data-paragraph-* markers and fall through to the original
# one-text-per-tspan path so the SVG's pixel layout is preserved.
line_height_attr = elem.get('data-paragraph-line-height') if ctx.merge_paragraphs else None
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
index 9bc427cc..42cddb98 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
@@ -350,7 +350,7 @@ def create_pptx_with_native_svg(
narration_padding: float = 0.5,
cache_dir: Path | None = None,
workers: int | None = None,
- merge_paragraphs: bool = False,
+ merge_paragraphs: bool = True,
conversion_trace_path: Path | None = None,
) -> bool:
"""Create a PPTX file with native SVG.
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
index 32a6bd1d..cb30db77 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
@@ -154,13 +154,14 @@ Recorded narration:
help='Only generate one version: native (editable shapes) or legacy (SVG image)')
mode_group.add_argument('--native', action='store_true', default=False,
help='(Deprecated, now default) Convert SVG to native DrawingML shapes')
- parser.add_argument('--merge-paragraphs', action='store_true', default=False,
- help='Opt-in: merge mergeable paragraph blocks (same x, dy clustered '
- 'around one base line-height) into a single editable text frame '
- 'with multiple <a:p>. Improves editability of paragraph text in '
- 'PowerPoint (one textbox per paragraph instead of per line) at '
- 'the cost of strict SVG line layout fidelity — PowerPoint re-wraps '
- 'merged paragraphs to fit the box width. Off by default.')
+ merge_group = parser.add_mutually_exclusive_group()
+ merge_group.add_argument('--merge-paragraphs', action='store_true', dest='merge_paragraphs',
+ help='Compatibility no-op: mergeable paragraph blocks are merged '
+ 'by default.')
+ merge_group.add_argument('--no-merge', action='store_false', dest='merge_paragraphs',
+ help='Disable paragraph merging. Every dy-stacked line becomes '
+ 'its own text frame for strict SVG line-layout fidelity.')
+ parser.set_defaults(merge_paragraphs=True)
parser.add_argument('--conversion-trace', action='store_true', default=False,
help='Write a JSON diagnostics report next to the native PPTX '
'(<output>.trace.json). Records per-slide SVG element '