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): restore heuristic authoring guidance

hugohe3e5b39afff260
diff --git a/docs/faq.md b/docs/faq.md
index 3aa80a9b..b3d1c248 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 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.
+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 need strict line-layout fidelity, re-export with `--no-merge`:
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index 8765ce64..ae30bcb9 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"` 的文字才会在导出时拼接视觉行——Executor 绘制页面时会给连续叙述的正文段默认写上该标记,因此普通段落编辑时按整段自然回流;而标题、诗行、对齐标签这类有意设计的断行仍保留为硬换行。文本框仍保留 PowerPoint 的正常自动换行,因此删除硬换行或修改文字后,会按文本框宽度重新排版。
+默认会把可合并的正文段落导出成一个可编辑的 PowerPoint 文本框,内部保留多个段落。**拉伸框时文字会在框内自动重排**。
如果你需要严格保持逐行版式,重新导出时加上 `--no-merge`:
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 108e6835..51d4c6e9 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -777,16 +777,12 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> reusable template creation goes through `create-template`.
> **Paragraph editability vs line fidelity** — by default, mergeable dy-stacked
-> 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 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
-> conservative; mixed-layout text falls back to per-line frames. A multiline
+> 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.
+> A multiline
> text carrier inside a slot must remain one native text frame; do not combine
> it with `--no-merge`. Strict-line text stays Slide-local rather than claiming
> one PowerPoint placeholder.
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 3960bf4e..1b6e36be 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -141,7 +141,6 @@ 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 b905cf9a..2f395d45 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -434,46 +434,12 @@ 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; 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. |
+| 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 as multiple paragraphs, while an irregular gap or a 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 | Strategist declares the Master roster and complete page-to-Layout map before drawing. Executor writes the root identities, atomic fixed layers, and grouped slots while authoring each page. Export compiles only those declarations. |
| Reusable template-based PowerPoint Layout | Select one complete input SVG per page in `page_layouts` and declare the output Master/Layout mapping at planning time. Strict preserves the prototype contract; adaptive retains its Master and may assign a new explicit Layout key during page authoring. 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)
@@ -1463,8 +1429,8 @@ by this solid-background rule.
| `media` | one `<image>` or supported imported crop `<svg>`, marked as carrier | `media` |
**Text slot carrier**: A multiline text placeholder must remain one
-native text frame. Use the default paragraph merge; `--no-merge` and explicit
-`data-pptx-text-mode="lines"` cannot supply several line shapes as one
+native text frame. Use the default paragraph merge; `--no-merge` cannot supply
+several line shapes as one
PowerPoint placeholder prototype/binding. Leave strict-line text Slide-local
when separate frames are the required result.
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index bdd219be..2690723d 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -87,7 +87,7 @@ python3 scripts/template_preview_pptx.py <legacy_template_workspace> --visual-on
```
`svg_authoring_view.py` creates a lightweight, non-destructive inspection copy
-of PPTX-imported SVGs. It removes embedded `txbody` / `text-carrier` payloads,
+of PPTX-imported SVGs. It removes embedded `txbody` payloads,
duplicate hidden geometry carriers, and import-identity attributes from the
copy while retaining visible fallback geometry, text, images, stable element
ids, root Master/Layout markers, and supported compact native-shape intent.
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 85ba4a2e..14815cab 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -21,7 +21,7 @@ on stdout records original/projected byte counts and removals by category.
The projected copy:
-- removes embedded `txbody` and `text-carrier` metadata;
+- removes embedded `txbody` metadata;
- removes hidden native geometry carriers while retaining and unwrapping their
visible preview geometry;
- removes source-object identity/style/hash attributes that are only useful to
@@ -87,10 +87,10 @@ Behavior:
- `backup/<timestamp>/svg_output/` — copy of Executor SVG source, always written so the pptx can be rebuilt via `finalize_svg → svg_to_pptx` without re-running the LLM
- `finalize_svg.py` always creates `svg_final/` before export. This directory is the self-contained SVG visual preview; it is not packaged as a second PPTX.
- Explicit `-o/--output` changes the native PPTX destination and skips `backup/`.
-- Paragraph merging is enabled by default and preserves authored line boundaries inside one editable PowerPoint text frame:
- - Default: evenly spaced visual lines become hard `<a:br>` boundaries inside one `<a:p>`; larger accepted gaps and list items start new `<a:p>` elements with precise `<a:lnSpc>` / `<a:spcBef>`.
- - Only explicit `data-pptx-break="soft"` content joins authored rows without a break. The merged frame still uses normal PowerPoint wrapping, so deleting a hard break or editing the text reflows it within the frame.
+- 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
- Native release export reads `svg_output/`. `-s final` is an explicit diagnostic override for comparing conversion behavior against post-processed SVGs; it does not change artifact ownership or create a supported release path.
- `svg_final/` may be opened directly or inserted into PowerPoint as an SVG picture. PowerPoint's manual Convert-to-Shape operation is outside the compatibility contract.