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(prompts): overlays live inside the picture group, inspection is per asset, §4.2 wording matches the checker

hugohe331a600a8cc89
diff --git a/skills/ppt-master/references/executor-image.md b/skills/ppt-master/references/executor-image.md
index 34e28751..53ac2b49 100644
--- a/skills/ppt-master/references/executor-image.md
+++ b/skills/ppt-master/references/executor-image.md
@@ -24,7 +24,7 @@ Conditional Executor authority for image status handling, placement, crop behavi
**Hard rule — visible-layer timing**: every crop, lens, scrim, comparison, evidence, or annotation layer an adopted motion plan needs already exists in the final SVG; the motion stage may regroup ordinary Slide-local content but never invents or modifies visible content. When no legal unit can serve a non-binding suggestion, simplify to available units, a page transition, or `none`; an unrepresentable explicit requirement follows failure recovery.
-**Hard rule — narrow visual-inspection scope**: start from §VIII `Reference` plus dimensions; inspect one asset (or its review copy) once only when focal-safe crop, overlay contrast, a quiet region, or the planned subject relationship stays ambiguous — a `Generated` asset only when its intent and dimensions cannot resolve the ambiguity, never routinely. Inspection never reopens selection, changes identity or must-use, infers provenance, substitutes, or invents focus; uncertain `adaptive` focus uses `meet`, and conflicting binding constraints return upstream.
+**Hard rule — narrow visual-inspection scope**: start from §VIII `Reference` plus dimensions; inspect an asset (or its review copy) once, and only while its focal-safe crop, overlay contrast, quiet region, or planned subject relationship stays ambiguous — on a photo-led page that may be each of several assets, still once each and never the folder; a `Generated` asset only when its intent and dimensions cannot resolve the ambiguity, never routinely. Inspection never reopens selection, changes identity or must-use, infers provenance, substitutes, or invents focus; uncertain `adaptive` focus uses `meet`, and conflicting binding constraints return upstream.
## 1. Image Composition
diff --git a/skills/ppt-master/references/image-layout-patterns.md b/skills/ppt-master/references/image-layout-patterns.md
index be3939f7..291c83f2 100644
--- a/skills/ppt-master/references/image-layout-patterns.md
+++ b/skills/ppt-master/references/image-layout-patterns.md
@@ -73,7 +73,7 @@ Compact composition vocabulary for prepared images and illustrations. Use the pa
### 3.2 P2 · Image as Canvas with Native Overlay
-**Reference — not a constraint**: use `P2` when native annotations, data, or process nodes bind to locations inside the prepared visual; an ordinary side image or inset remains `P1` / `P3`.
+**Reference — not a constraint**: use `P2` when native annotations, data, or process nodes bind to locations inside the prepared visual; an ordinary side image or inset remains `P1` / `P3`. The overlay lives inside the picture's root group ([`shared-standards-core.md`](./shared-standards-core.md) §4.3), so it costs no page area.
- **#P2-01 · Annotated evidence** — place compact annotation cards with routed leaders over the visual.
- **#P2-02 · Hotspots with sidebar legend** — pair numbered points on the visual with a matching native legend.
diff --git a/skills/ppt-master/references/shared-standards-core.md b/skills/ppt-master/references/shared-standards-core.md
index ada5d1f3..6a4406be 100644
--- a/skills/ppt-master/references/shared-standards-core.md
+++ b/skills/ppt-master/references/shared-standards-core.md
@@ -175,7 +175,7 @@ These forms are needed only when the stated PPT behavior matters:
| Desired behavior | Required form |
|---|---|
-| One editable PPT text frame with mixed formatting or multiline prose | Use one `<text>` per logical paragraph and non-positional `<tspan>` children for inline runs. Per-run `fill` / `font-weight` / `font-size` is retained: export walks nested runs and emits one DrawingML run per styled segment, so an emphasised phrase stays inside the same editable frame, and a positioned line-break `<tspan>` may itself contain inline runs. Keep the first line as direct text; later lines use direct positioned `<tspan>` children that repeat parent `x` with positive relative `dy`; an all-`<tspan>` form may start at `dy="0"`. Default retains these breaks without PowerPoint wrapping; `--reflow-text` may join eligible lines. A font-size change, list marker, or larger accepted gap starts another paragraph. Sibling `<text>` elements are forbidden as one paragraph's line breaks; they remain valid for independent frames. |
+| One editable PPT text frame with mixed formatting or multiline prose | Use one `<text>` per logical paragraph and non-positional `<tspan>` children for inline runs. Per-run `fill` / `font-weight` / `font-size` is retained: export walks nested runs and emits one DrawingML run per styled segment, so an emphasised phrase stays inside the same editable frame, and a positioned line-break `<tspan>` may itself contain inline runs. Keep the first line as direct text; later lines use direct positioned `<tspan>` children that repeat parent `x` with positive relative `dy`; an all-`<tspan>` form may start at `dy="0"`. Default retains these breaks without PowerPoint wrapping; `--reflow-text` may join eligible lines. A font-size change, list marker, or larger accepted gap starts another paragraph. Sibling `<text>` elements are not a paragraph's line breaks — the checker reports likely cases as a warning because the detection is heuristic, and they are repaired before export; sibling frames remain valid for independent text. |
| 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 | Outside structured mode, make the first visual layer a direct full-canvas `<rect>` (or one inside a simple single-child group) with a solid, linear/radial gradient, or preset-pattern fill and no transform, filter, clip, rounding, or visible stroke; export writes it as Slide `p:bg`. Structured routes follow [`pptx-structure-interface.md`](./pptx-structure-interface.md). |
| Free-design / brand-only PowerPoint structure | Use `pptx_structure.mode: flat`: keep objects Slide-local and author no Master/Layout identities, layers, or slots; export emits one clean Master plus Blank Layout. |
@@ -187,7 +187,7 @@ These forms are needed only when the stated PPT behavior matters:
### 4.3 Element Grouping (Mandatory)
-**Hard rule — root groups protect body-text layout**: every visible direct root `<g>` except a compact helper-authored preset atom declares positive root-coordinate `data-pptx-bounds="x y width height"` sized as the intended module zone. On flat pages, maximize ordinary zones within canvas/sibling space without overlap; the checker fails root-group overlap beyond `1px`, warns on module text overflow through `5%` and fails above it, and fails any larger root-`viewBox` text overflow. Bounds do not clip or reflow. Structured slots, structural-role groups, and a wholly off-canvas Morph endpoint marked `data-pptx-morph-staging="true"` are the only exemptions; thresholds and estimator detail: [`svg-contract.md`](../scripts/docs/svg-contract.md) §4.
+**Hard rule — root groups protect body-text layout**: every visible direct root `<g>` except a compact helper-authored preset atom declares positive root-coordinate `data-pptx-bounds="x y width height"` sized as the intended module zone. On flat pages, maximize ordinary zones within canvas/sibling space without overlap; the checker fails root-group overlap beyond `1px`, warns on module text overflow through `5%` and fails above it, and fails any larger root-`viewBox` text overflow. Bounds do not clip or reflow. A native plate, caption, or label laid over a picture belongs inside that picture's root group — one group is the image plus its overlay — so it takes no separate zone and creates no root-group overlap; shrinking the picture to free a text zone is not the repair. Structured slots, structural-role groups, and a wholly off-canvas Morph endpoint marked `data-pptx-morph-staging="true"` are the only exemptions; thresholds and estimator detail: [`svg-contract.md`](../scripts/docs/svg-contract.md) §4.
Wrap each logical Slide-local body unit in one descriptive top-level `<g id>`; group count follows the page's semantic units, and each group becomes one stable animation target when animation is enabled. Nested implementation groups may remain anonymous, need no bounds, and create no animation step; use them only when internal subunits (icon + title, value + label, repeated rows) are useful to edit — there is no default nesting pattern, depth, or quota. Titles, direct atomic Master/Layout elements, and canvas-level static framing — background images and full-canvas scrim/decoration rectangles — may remain root primitives; on flat pages give such framing a stable `id` plus `data-pptx-role="background"` / `"decoration"` and never add a `<g>` solely to silence an ungrouped-element advisory.
diff --git a/skills/ppt-master/references/strategist-image.md b/skills/ppt-master/references/strategist-image.md
index 6251cc41..e8de5714 100644
--- a/skills/ppt-master/references/strategist-image.md
+++ b/skills/ppt-master/references/strategist-image.md
@@ -16,7 +16,7 @@ Run this module inside [`strategist.md`](./strategist.md)'s one-pass resource-ne
**Illustration**: confirmed `none` stops and explicit user intent wins; otherwise the locked style's `Illus.` propensity (`core` / `supportive` / `sparse`) tunes centrality and recurrence after the per-page scan without restricting page types, element scale, or carrier combinations. Prefer one coherent family that serves the actual jobs — recurring title/corner chrome, dominant anchors, supporting figures, accents; a compact icon cue does not discharge a scene, subject, or visual-weight job a photo or family would serve.
-**Context-first understanding of provided assets**: never scan `images/` for inspiration or bulk-open it. Infer identity, role, and crop/focus needs from source position, surrounding prose, captions/alt/titles, filename, user notes and `image_notes`, existing records, and CSV geometry; inspect one specific image only when a remaining ambiguity would change selection, identity, page role, crop safety, or focal placement, never inferring external facts or provenance from pixels. Record the result in §VIII; leave an optional unresolved asset unused and route a must-use one through failure recovery.
+**Context-first understanding of provided assets**: never scan `images/` for inspiration or bulk-open it. Infer identity, role, and crop/focus needs from source position, surrounding prose, captions/alt/titles, filename, user notes and `image_notes`, existing records, and CSV geometry; inspect a specific image, once, only when a remaining ambiguity would change selection, identity, page role, crop safety, or focal placement — several images when several carry such an ambiguity, never the folder — and never infer external facts or provenance from pixels. Record the result in §VIII; leave an optional unresolved asset unused and route a must-use one through failure recovery.
**Default — Illustration Sheets for a compatible group (may split for geometry, detail, or quality)**: illustration elements, illustrated-icon cues, and lettering share one generation context under [`image-generator.md`](./image-generator.md) §4.3. Plan one unplaced `ai` Illustration Sheet row plus one placed `slice` row per used element (only slice rows enter the lock; one element may serve several pages), stating each element's communication job, placement/reuse relationship, relative weight, energy, family, and shape without prescribing an effect stack. Glyph-native expression is the default; a lettering-plus-illustration lockup only on explicit request or when the confirmed direction requires it. Lettering sheets use `text_policy: embedded` — the asset may carry the complete display title while any searchable, selectable, or outline-visible title stays a separate native frame. §§4.3 and 5.3 own the controlled-default/high-expression boundary, grid, key field, slicing, and execution; Stage 2 chooses the AI path under §7, never re-picked here.
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index de988fac..fc076299 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -1023,7 +1023,8 @@ the SVG quality checker.
`validation/text_calibration.json`, and prints a compact table or JSON. The
estimator is additive across scripts, so a line mixing CJK with Latin words
or digits is estimated as (CJK chars ÷ CJK rate + other chars ÷ Latin rate)
- × 100; spaces, digits, and punctuation count as Latin. The checker's overflow
+ × 100; spaces, digits, and punctuation count as Latin. Rates are rounded, so
+ the estimate carries a few percent of slack; leave that margin in the zone. The checker's overflow
diagnostic prints that line's average px per character, which is not a
reusable rate. A lock role without its own
`<role>_family` resolves to `title_family` when the role name contains
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index d0a8282b..69bc5ac2 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -12,7 +12,7 @@ Compose the entire document in active context, then create `<project_path>/desig
## 2. Exact document contract
-Angle-bracketed text is authoring notation. Resolve every universal value before writing; omit only rows marked conditional; keep every required `##` heading (§VII omitted without a catalog reference; §VIII present even with no data rows); copy no examples, notation, or schema prose into the artifact.
+Angle-bracketed text is authoring notation. Resolve every universal value before writing; omit only rows marked conditional; keep every required `##` heading (§VII is conditional: drop the whole section, heading included, when no page carries a catalog reference; §VIII present even with no data rows); copy no examples, notation, or schema prose into the artifact.
### 2.1 Header and project contract