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(text-layout): guide Executor to author reflowable prose contracts

hugohe34d14749e4c35
diff --git a/docs/faq.md b/docs/faq.md
index 4123656f..55d6cdbb 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -81,7 +81,7 @@ Yes. The only PPTX export route in the SVG pipeline is PPT Master's own `svg_out
## Q: Why is one paragraph split into multiple text boxes? Can I get one text box per paragraph instead?
-By default, mergeable body text exports as one editable PowerPoint text frame. Authored SVG visual lines remain hard line breaks inside that frame; larger gaps and list items remain separate paragraphs. Only text explicitly marked with `data-pptx-break="soft"` joins authored rows during export. The frame still uses normal PowerPoint wrapping, so deleting a hard break or editing the text reflows it within the frame.
+By default, mergeable body text exports as one editable PowerPoint text frame. Authored SVG visual lines remain hard line breaks inside that frame; larger gaps and list items remain separate paragraphs. Only text explicitly marked with `data-pptx-break="soft"` joins authored rows during export — the Executor declares that marker on flowing body prose at draw time, so ordinary paragraphs edit as one reflowing paragraph while deliberately designed line breaks (titles, verse, aligned labels) stay hard breaks. The frame still uses normal PowerPoint wrapping, so deleting a hard break or editing the text reflows it within the frame.
If you need strict line-layout fidelity, re-export with `--no-merge`:
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index 9db945cb..59e3458f 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -83,7 +83,7 @@ Step 7 仍会强制生成 `svg_final/`。其中每页都是自包含的视觉预
## Q: 为什么一段正文被拆成了好几个文本框?能不能一段一个文本框?
-默认会把可合并的正文导出成一个可编辑的 PowerPoint 文本框。SVG 中已经排好的视觉行会在框内保留为硬换行;较大行距和列表项保留为独立段落。只有显式标记 `data-pptx-break="soft"` 的文字才会在导出时拼接视觉行。文本框仍保留 PowerPoint 的正常自动换行,因此删除硬换行或修改文字后,会按文本框宽度重新排版。
+默认会把可合并的正文导出成一个可编辑的 PowerPoint 文本框。SVG 中已经排好的视觉行会在框内保留为硬换行;较大行距和列表项保留为独立段落。只有显式标记 `data-pptx-break="soft"` 的文字才会在导出时拼接视觉行——Executor 绘制页面时会给连续叙述的正文段默认写上该标记,因此普通段落编辑时按整段自然回流;而标题、诗行、对齐标签这类有意设计的断行仍保留为硬换行。文本框仍保留 PowerPoint 的正常自动换行,因此删除硬换行或修改文字后,会按文本框宽度重新排版。
如果你需要严格保持逐行版式,重新导出时加上 `--no-merge`:
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index c18419ec..26e12d42 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -910,7 +910,9 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> text collapses into one editable PowerPoint text frame. Evenly spaced authored
> visual lines stay in one paragraph as hard line breaks; larger gaps and list
> items start new paragraphs. Only an explicit `data-pptx-break="soft"` joins
-> SVG-authored rows during export. The merged frame keeps normal PowerPoint
+> SVG-authored rows during export; the Executor declares that contract on
+> flowing prose blocks at draw time (see `references/executor-base.md` §2.1),
+> while designed breaks stay hard. The merged frame keeps normal PowerPoint
> wrapping, so deleting a hard break or editing the text reflows it within the
> frame. Add `--no-merge` only when the user explicitly asks for every
> dy-stacked line to remain its own text frame. The merge detector is
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 73c5226e..3acf8cb2 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -166,6 +166,7 @@ Before the first SVG page, output a confirmation listing: canvas dimensions, bod
**Per-block expression**: render each `design_spec.md §IX Content` block in its written texture — a full-sentence block as wrapped prose, a fragment/label block as bullets/keywords. **Never split a full-sentence block into a bullet list** — splitting loses the information that the block was continuous reasoning, not a set of parallel points; not because a bullet lays out easier, and not because an inherited template slot is shaped as a list. If a block carries no clear texture, infer the mode from its wording and the page layout.
- **Prose render recipe**: one `<text>` per paragraph; wrap lines with sibling `<tspan>` where the first line uses `dy="0"` and every subsequent line repeats the parent `<text>`'s **exact `x`** and the **same positive relative `dy`** (the line-height). Equal relative `dy` + matching `x` is what merges the lines into one editable PowerPoint text frame; a growing/cumulative `dy`, an irregular gap, or a mismatched `x` (e.g. `x="0"` under `<text x="60">`) splits them into separate single-line boxes. Set the line-height `dy` from the font size × a line-height factor. **Default — line-height by density (may override per content fit)**: ~1.4–1.5× for dense / small-body blocks (CLReq comfortable minimum), 1.6–2.0× for large-type, sparse, or `breathing` blocks. Fit about width ÷ font-size CJK glyphs per line (Latin fits roughly twice that); the last line runs short. Use the body ramp size, not a new one.
+- **Prose reflow contract**: authored rows otherwise export as hard line breaks, so every full-sentence prose block written with the recipe above also declares the explicit paragraph contract — `data-pptx-text-mode="paragraph"` plus `data-pptx-text-bounds="x y w h"` on the `<text>` (the design zone the prose was fitted to; its width becomes the exported wrap width, `y` ≈ `0.9 × font-size` above the first baseline, bottom below the last baseline), and `data-pptx-break="soft"` + `data-pptx-join` (`none` between CJK glyphs, `space` for Latin) on every continuation `<tspan>`. The exported frame then edits as one reflowing paragraph. Do **not** mark titles, verse, quotes, or aligned label stacks — those break positions are design and stay hard. Full recipe and validation rules: [shared-standards.md §4.2](shared-standards.md).
- **Template precedence**: when an inherited template slot is a bullet list but the §IX block is prose, the prose wins — widen or reflow the container to hold the paragraph, or drop that card; do not pour the sentence back into the list slot.
- **Mode precedence**: the locked mode shapes voice / register, not §IX's authored titles or page order. When a `§IX` title is a user-authored topic label, keep it — do not upgrade it to an assertion just because the mode (e.g. `pyramid`) favors them; mode title-tendencies apply only to AI-drafted titles.
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index dd0a9528..b75db67d 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -420,12 +420,46 @@ These forms are needed only when the stated PPT behavior matters:
| Desired behavior | Required form |
|---|---|
-| One editable PPT text frame with mixed inline formatting | Put the logical line in one `<text>` with non-positional `<tspan>` children. A `<tspan>` with `x`/`y`/`dy` starts a new positioned line; evenly `dy`-stacked lines that repeat the parent `<text>`'s `x` merge into one frame with hard line breaks. A larger accepted gap or list marker starts a new paragraph; `data-pptx-break="soft"` explicitly joins authored rows. The merged frame keeps normal PowerPoint wrapping for later edits. An unmergeable gap or mismatched `x` flattens to separate frames. Separate `<text>` elements stay valid when separate frames are intended. |
+| One editable PPT text frame with mixed inline formatting | Put the logical line in one `<text>` with non-positional `<tspan>` children. A `<tspan>` with `x`/`y`/`dy` starts a new positioned line; evenly `dy`-stacked lines that repeat the parent `<text>`'s `x` merge into one frame with hard line breaks. A larger accepted gap or list marker starts a new paragraph; flowing prose opts into reflow via the explicit paragraph contract below. The merged frame keeps normal PowerPoint wrapping for later edits. An unmergeable gap or mismatched `x` flattens to separate frames. Separate `<text>` elements stay valid when separate frames are intended. |
| Stable object grouping or object-level animation anchor | Wrap the intended object in `<g id="...">`. Content grouping is **mandatory** per §4.3 — a top-level `<g id>` is also the animation anchor; it is not an optional convenience. |
| Native PowerPoint background promotion | Use a direct, full-canvas, solid `<rect>` without transform, filter, clip, rounding, or visible stroke. Other SVG backgrounds remain ordinary slide shapes. Template routes add the ownership metadata in §7. |
| Reusable free-design PowerPoint Layout | Finish the free design first, then run [`distill-layouts`](../workflows/distill-layouts.md) on pages explicitly selected by the user. The workflow writes the complete `pptx_layouts` mapping and §7 metadata; the exporter itself never infers visual similarity. Before distillation, an unmapped baseline project uses §4.1 compatibility routing. |
| Reusable template-based PowerPoint Layout | Select one complete input SVG per page in `page_layouts`, finish every visible page, then run [`distill-layouts`](../workflows/distill-layouts.md). Strict restores prototype structure/bounds; adaptive keeps Master ids/topology/geometry and may finalize an evolved Layout. Non-mirror skin follows `spec_lock`. |
+**Explicit paragraph contract — reflowable prose**: authored rows export as
+hard line breaks unless the block declares otherwise. When a block is flowing
+prose whose wrap positions carry no design intent, declare the contract so the
+exported frame edits as one reflowing paragraph:
+
+```xml
+<text id="p04-body" data-pptx-text-mode="paragraph"
+ data-pptx-text-bounds="80 224 520 120"
+ x="80" y="238" font-size="16" fill="#334155">
+ <tspan x="80" dy="0">Continuous narrative text that was</tspan>
+ <tspan x="80" dy="24" data-pptx-break="soft" data-pptx-join="space">wrapped to the column width and now</tspan>
+ <tspan x="80" dy="24" data-pptx-break="soft" data-pptx-join="space">reflows freely after export.</tspan>
+</text>
+```
+
+- The contract is all-or-nothing and checker-validated (`[TEXT_*]` codes): a
+ unique `id`, `data-pptx-text-mode="paragraph"`, and
+ `data-pptx-text-bounds="x y w h"` on the `<text>`; every line after the
+ first declares `data-pptx-break` — `soft` joins into the same reflowing
+ paragraph, `line` keeps an authored hard break, `paragraph` starts a new
+ paragraph whose extra `dy` over the base line-height becomes paragraph
+ spacing. `soft` also declares `data-pptx-join`: `none` between CJK glyphs,
+ `space` for Latin words.
+- Bounds are the exported text frame verbatim, so take them from the design
+ zone the prose was fitted to: `x` matches the line anchor (frame left for
+ `text-anchor="start"`, frame center for `middle`), width is the intended
+ wrap width, `y` sits about `0.9 × font-size` above the first baseline, and
+ the frame bottom covers the last baseline. `soft`/`line` rows keep the base
+ line-height `dy`; ancestors allow pure-translate transforms only, and
+ `dx`/`rotate`/`textLength`/baseline shifts stay out of contracted text.
+- Keep designed breaks — titles, verse, aligned label stacks — out of `soft`;
+ without the contract those rows stay hard breaks, which preserves layout but
+ makes later prose edits line-by-line.
+
**Hard rule — supported shape conversion**: Every PPT editability claim in this specification refers to the project converter reading `svg_output/` and emitting native DrawingML. `svg_final/` is a self-contained visual preview that may be inserted into PowerPoint as an SVG picture. PowerPoint's manual Convert-to-Shape operation is unsupported; do not narrow the authoring contract to its undocumented SVG subset.
### 4.3 Element Grouping (Mandatory)