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(svg-authoring): encourage native-preset adoption and correct paragraph-merge guidance

hugohe35137b02277f4
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 615f51c1..441a94d1 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -146,7 +146,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>` that reset `x` to the block's left edge and advance `dy` by 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 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.
- **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.
@@ -226,11 +226,15 @@ Before drawing each page, look up its entry in `page_charts` to decide which cha
### 3.0 Native Preset Shape Selection
-**Default — use one native preset when it exactly expresses one object (may
-override for page-specific geometry)**: apply the decision gate in
-[`native-shape-authoring.md`](./native-shape-authoring.md) before drawing a
-literal stock shape, block arrow, standard flowchart node, connector, callout,
-ribbon, or Office symbol.
+**Reach for a native preset whenever one expresses a complete object — this is
+the default, not the exception.** Block arrows, chevrons, banners / ribbons,
+callouts, flowchart nodes, stars, and other Office symbols should be **authored
+as presets** via `preset_shape_svg.py`, not drawn as plain `<path>`s or faked
+with rectangles: presets are what give the slide real PowerPoint shapes with
+adjustment handles and the designed, non-flat-card look. When a page calls for
+one of these, use the preset. Apply the decision gate in
+[`native-shape-authoring.md`](./native-shape-authoring.md) to pick the right
+shape and to keep only the exceptions below as ordinary SVG.
| Decision | Action |
|---|---|
diff --git a/skills/ppt-master/references/native-shape-authoring.md b/skills/ppt-master/references/native-shape-authoring.md
index cb1c041d..cb5a2474 100644
--- a/skills/ppt-master/references/native-shape-authoring.md
+++ b/skills/ppt-master/references/native-shape-authoring.md
@@ -11,6 +11,11 @@ atomic fragment.
Apply this decision order before drawing a stock geometric object.
+> This gate is for picking the **right** native shape, not for avoiding presets.
+> When a page needs an arrow, chevron, callout, banner, flowchart node, or a
+> literal Office symbol, authoring it as a preset is the **default** — the
+> ordinary-SVG rows below are deliberate exceptions, not the norm.
+
| Condition | Action |
|---|---|
| Plain rectangle, symmetric rounded rectangle, circle, or ellipse | Write the ordinary SVG primitive; the exporter already emits an editable native shape. |
@@ -27,6 +32,10 @@ carrier, preview, or fingerprint attributes to a hand-written path.
## 2. Semantic Preset Candidate Guide
+Use the table below as the **go-to menu**: match the page's visual intent to a
+candidate preset *before* defaulting to a plain rect or path. Reaching here
+first is exactly how presets get used instead of forgotten.
+
"Automatic" means the Executor independently applies this semantic decision
gate before drawing a new object. It does not scan existing SVG, classify
paths or contours, or upgrade ordinary SVG during export.
@@ -111,6 +120,12 @@ and one complete visible preview.
**Hard rule**: treat the returned group as atomic. Put labels, icons, or other
decorations beside it in a parent `<g>`, never inside the preset group.
+**Frame coordinate space**: `--frame x y w h` is expressed in the coordinate
+space where you insert the fragment. At the page root that is page coordinates;
+inside a `<g transform="translate(…)">` use **group-local** coordinates — the
+ancestor transform stacks on top, so page-absolute values would double-offset
+the shape off-canvas.
+
**Regeneration rule**: rerun the helper when preset, frame, adjustment, fill,
stroke, or stroke width changes. Moving, scaling, rotating, or flipping the
complete logical group is allowed; zero-scale transforms and shear/skew are
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index 2247bd75..b8bb4a84 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -414,7 +414,7 @@ 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>` and use non-positional `<tspan>` children. A `tspan` with `x`, `y`, or `dy` starts a new positioned line and is flattened to another text frame. Separate `<text>` elements remain 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** (the default paragraph-merge), 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. |
| Free-design page family/chrome extraction | Use the semantic markers in §4.1. Marker-free pages retain conservative filename/id fallbacks, but no visual content is inferred. |