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(native-shapes): move preset selection to authoring
hugohe3e792af0fd9a0
diff --git a/docs/rules/prompt-style.md b/docs/rules/prompt-style.mdindex 5503e8a0..a1cda2ee 100644--- a/docs/rules/prompt-style.md+++ b/docs/rules/prompt-style.md@@ -102,8 +102,17 @@ Constraint strength and decision ownership are independent. Preserve this chain| Layer | Owns ||---|---|| User / initial materials | Supplied facts/assets, desired outcome, exclusions, and permission boundaries remain authoritative |-| Strategist / plan + preparation | Assess material sufficiency; trigger permitted topic research and retain its research/provenance pair without expanding adopted webpage URLs; decide the approved content, resources, keys, identity anchors, and exact page roster; record optional capability/expression recommendations; materialize the planned project-local inventory or record an explicit `Needs-Manual` dependency before execution. For icons, prepare a curated project pool with broad semantic fit rather than assigning files to pages |-| Executor / realization | Use only prepared project-local assets; preserve approved content, resources, and identity anchors; realize them through geometry, composition, hierarchy, and treatment. Fields explicitly labeled `suggestion` or Reference are preferred expression rather than binding selections: Executor may adapt or decline them when content and explicit constraints remain intact. For icons, the complete `<project>/icons/` pool is prepared material; `icons.inventory` is a curated bundled-pool index, not a page-use plan or whitelist, and Executor chooses prepared icons per page without a coverage quota. Sparse local font/color garnish is allowed only while non-structural and non-recurring |+| Strategist / plan + preparation | Assess material sufficiency; trigger permitted topic research and retain its research/provenance pair without expanding adopted webpage URLs; decide the approved content, resources, keys, identity anchors, and exact page roster; record only recommendations that affect content, resource preparation, sequencing, or explicit user/template constraints; materialize the planned project-local inventory or record an explicit `Needs-Manual` dependency before execution. For icons, prepare a curated project pool with broad semantic fit rather than assigning files to pages |+| Executor / realization | Use only prepared project-local assets; preserve approved content, resources, and identity anchors; realize them through geometry, composition, hierarchy, and treatment. Discover and invoke local deterministic authoring capabilities without an upstream capability suggestion. Fields explicitly labeled `suggestion` or Reference remain preferred expression rather than binding selections when their owning contract permits adaptation. For icons, the complete `<project>/icons/` pool is prepared material; `icons.inventory` is a curated bundled-pool index, not a page-use plan or whitelist, and Executor chooses prepared icons per page without a coverage quota. Sparse local font/color garnish is allowed only while non-structural and non-recurring |++**Hard rule — native shapes are authoring capabilities, not prepared+resources**: a prepared resource needs a stable project-local file/path before+realization because page authoring cannot acquire or generate it in place.+Office presets, SVG primitives, Connectors, Boolean helpers, and necessary+freeform geometry are locally callable construction capabilities. Strategist+never selects, inventories, or suggests them, and the Design Spec / lock create+no native-shape field. Executor discovers the complete current preset registry+and chooses the page-fit construction during realization.**Preparation timing**: In the default pipeline, topic research and import ofits two-artifact research pair may run before final confirmation. Facts JSONdiff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.mdindex e99841f1..e610fcdd 100644--- a/skills/ppt-master/references/executor-base.md+++ b/skills/ppt-master/references/executor-base.md@@ -186,11 +186,10 @@ materialize that contour with Boolean semantics, and use freeform last. Blockarrows, chevrons, banners / ribbons, callouts, flowchart nodes, stars, and otherOffice symbols use `preset_shape_svg.py`, not plain paths or fake rectangles.-§IX `Native shape suggestion` records a semantic opportunity, not a literal-tool command. Decide from the actual page construction which page-fit native-contour and simplest exact authoring form, independent compound construction,-Boolean result, or necessary freeform best realizes it; a different-implementation is valid when it preserves the intended object and content.+Before the first page, complete [`native-shape-authoring.md`](./native-shape-authoring.md)'s+unfiltered full-registry discovery. Decide every page-fit contour and its+simplest exact authoring form directly from the page content and visual system;+no Design Spec capability suggestion or material inventory gates this choice.**Mandatory — independent per-page compound-shape decision**: after theStructure result and any applicable topology resolve, decide whether two or morediff --git a/skills/ppt-master/references/native-shape-authoring.md b/skills/ppt-master/references/native-shape-authoring.mdindex 1d24657b..c648f848 100644--- a/skills/ppt-master/references/native-shape-authoring.md+++ b/skills/ppt-master/references/native-shape-authoring.md@@ -12,6 +12,20 @@ only when those constructions fail. Neither helper writes a page. The presethelper does not create the shape's own `p:txBody`; keep visible text outside theatomic fragment.+**Mandatory — complete registry discovery at authoring entry**: before the+first newly authored page or template contour in each valid context, run the+following command unfiltered and retain its complete output (currently 187+names). This is authoring-time capability discovery, never a Strategist task or+Design Spec field. Rerun only after context invalidation or a registry change.++```bash+python3 ${SKILL_DIR}/scripts/preset_shape_svg.py list+```++Choose from that full inventory by page job. Use `list --search` only to narrow+the already-read inventory and `describe <name>` only after identifying a+candidate; neither replaces the complete initial read.+## 1. Contour Selection and Materialization Gate**Hard rule — contour before encoding**: choose the page-fit contour from the@@ -45,10 +59,10 @@ rerun the helper whenever its geometry, paint, or filter reference changes.## 2. Semantic Preset Candidate Guide-Use the table below as a high-frequency entry, not a whitelist: match the-page's visual intent to a candidate contour before settling on a neutral-rectangle / ellipse or a freeform path. Search the registry when the job calls-for a more specific contour rather than letting authoring convenience decide.+Use the table below as semantic navigation, not a shortlist: match the page's+visual intent against the complete inventory already loaded above before+settling on a neutral rectangle / ellipse or a freeform path. Do not let the+examples or authoring convenience hide a more specific registered contour."Automatic" means the Executor independently applies this semantic decisiongate before drawing a new object. It does not scan existing SVG, classify@@ -65,7 +79,7 @@ paths or contours, or upgrade ordinary SVG during export.| Standalone math symbol | `mathPlus`, `mathMinus`, `mathMultiply`, `mathDivide`, `mathEqual`, `mathNotEqual` | Use only when the symbol itself is a diagram shape; simple notation remains text, while non-trivial inline or block mathematics follows [`native-formula.md`](./native-formula.md). || Literal Office symbol | `heart`, `sun`, `moon`, `lightningBolt`, `gear6`, `gear9` | Never replace an icon required by `spec_lock.icons`. |-Use registry search for a less common literal shape:+Narrow and inspect candidates from the already-loaded inventory:```bashpython3 ${SKILL_DIR}/scripts/preset_shape_svg.py list --search arrow@@ -278,9 +292,9 @@ freshness contract.**Trigger**: Current page construction has two or more supported shape/text operandswhose faithful result calls for PowerPoint-style Union, Combine, Fragment,-Intersect, or Subtract. A §IX `Native shape suggestion` is a semantic candidate,-not a prerequisite or tool command; Executor may adopt, adapt, or decline it-from the actual content and explicit user/template constraints.+Intersect, or Subtract. Executor decides this directly from the actual content,+complete native inventory, and explicit user/template constraints; no upstream+suggestion or planning field is required.```bashpython3 ${SKILL_DIR}/scripts/shape_boolean_svg.py render <svg-file> \diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex 33001a74..0da37af4 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -58,7 +58,7 @@ Do not force communication intent into one catalog label; Stage 1 records compos| Reference | Preserve the selected direction or role; adapt its realization to context. || Permission / default | An allowed candidate/source boundary or preference; Strategist may leave it unused, with no quota. |-**Authority chain — materials → Strategist preparation → realization.** User inputs set materials/acquisition bounds. Strategist owns sufficiency, gap-filling, and selection: roster/content, resources, page-local visualization/Layout references, fonts, palette anchors, the icon library/stroke plus curated project pool, and crop bans. Topic research and import of its two-artifact research pair may precede confirmation; facts URLs are not auto-expanded. Only after normal image search fails may one adopted webpage become a reviewable Markdown + companion-image source package, with accepted files promoted individually. Independent AI/web/slice acquisition follows final confirmation plus completed §VIII/lock; icons are synced/validated during authoring without page assignment. Before Executor, each resource has a path and terminal/`Needs-Manual` state. Executor owns geometry, composition, hierarchy, spacing, treatment, and per-page choice among prepared icons; it never searches, generates, syncs, invents, or substitutes resources. Missing material/reselection returns upstream. Specificity defines freedom; References flex realization, never selection.+**Authority chain — materials → Strategist preparation → realization.** User inputs set materials/acquisition bounds. Strategist owns sufficiency, gap-filling, and selection: roster/content, semantic relationships, prepared resources/paths, Chart/Table and structured-template routing references, fonts, palette anchors, the icon library/stroke plus curated project pool, and crop bans. Topic research and import of its two-artifact research pair may precede confirmation; facts URLs are not auto-expanded. Only after normal image search fails may one adopted webpage become a reviewable Markdown + companion-image source package, with accepted files promoted individually. Independent AI/web/slice acquisition follows final confirmation plus completed §VIII/lock; icons are synced/validated during authoring without page assignment. Before Executor, each resource has a path and terminal/`Needs-Manual` state. Locally callable native construction is an Executor capability—not a resource or planning output. Executor owns its discovery and selection plus geometry, composition, hierarchy, spacing, treatment, and per-page choice among prepared icons; it never searches, generates, syncs, invents, or substitutes resources. Missing material/reselection returns upstream. Specificity defines freedom; References flex realization, never selection.Explicit *must*, *only*, *exactly*, *verbatim*, *do not*, or `no-crop` wording may strengthen only the named property into the appropriate Literal or Semantic requirement. Accepting an AI recommendation keeps the field's default type; it does not promote a Reference or Permission into a Literal requirement.@@ -348,18 +348,19 @@ The module owns AI rendering alternatives, acquisition paths, resource rows, pro**Per-page capability recall**: Before §IX, consider this menu without a usagequota. Use existing fields for semantic intent; omit unused lines and-implementation parameters. Executor may adapt/decline the-two non-literal suggestions while preserving content and intent; explicit-user/template requirements bind.+implementation parameters. Executor may adapt/decline a `Motion suggestion`+while preserving content and intent; explicit user/template requirements bind.-**Reference — carriers compose, not compete**: Any page may combine a suitable subset of background paint, native shapes, editable text, photos/scenes, transparent illustration elements, decorative lettering, icons, and visualizations. Select only what improves communication and composition; outside explicit requirements, no carrier is mandatory or mutually exclusive.+**Hard rule — native construction stays downstream**: record the page's+semantic relationships and any prepared resource roles; add no native-+construction recommendation. Executor independently discovers and selects local+construction from the actual page content and visual system.| Capability | Opportunity signal | Design Spec handoff ||---|---|---|| Image composition | Image-as-canvas, editorial crop, collage, cutout, or meaningful focus / comparison / evidence units carry the page better than an adjacent rectangle | Propose a permitted source; when selected, apply the already-loaded [`strategist-image.md`](./strategist-image.md) resource contract plus the conditional image-layout references, record a concise §VIII `Layout pattern` suggestion, and describe page-level image/overlay relationships in §IX `Layout` / `Images` || Composable illustration family | One or more pages benefit from coherent reusable title/corner ornaments, dominant anchors, supporting figures, compact illustrated-icon cues, or accents that can mix with text, shapes, photos, or lettering | Apply [`strategist-image.md`](./strategist-image.md): plan transparent elements by compatible family, record fixed reuse or adaptive variation in §VIII `Reference`, and describe each used page's carrier relationships in §IX `Layout` / `Images` || Native paint / overlay | Gradient, translucency, scrim, vignette, or wash supports focus, hierarchy, depth, legibility, or image integration | Record purpose/layering in §IX `Layout`, plus `Images` when imagery participates; no new field or type/stops/opacity/coordinates—Executor chooses realization |-| Native shape system / Merge Shapes | A page field, outline carrier, visual nesting, literal Office symbol, stock bent/curved contour, or compound silhouette/cutout/overlap region strengthens the visual idea | Add an optional §IX `Native shape suggestion` with the semantic geometry jobs and relationship; identify independent atom roles, a candidate preset/Connector family, or Boolean operation/operands only where useful || AI decorative lettering asset | Any stable display string in the deck — including a complete long or multi-line title, cover hook, chapter word, place or product name, dish or exhibit name, year, hero number, pull quote, or motif word — reads better with a material, dimensional, hand-rendered, or otherwise illustrative treatment than as ordinary text | Apply [`strategist-image.md`](./strategist-image.md): preserve every complete exact string, group compatible marks when useful, and keep chrome/body as native text. The lettering asset may carry the complete long or multi-line title as its display layer; keep an ordinary native title/subtitle in a separate text frame wherever the page needs a searchable, selectable, or outline-visible heading. Never shorten copy to make it look more like a wordmark || Page transition | A section/state change, spatial continuity, recorded/self-running flow, or the same semantic object changing position, scale, crop, or state across adjacent pages benefits from motion | Add an optional §IX `Motion suggestion` describing the communication job and any continuing object's initial state → action → end state; leave effect, ids, pairing names, and timing to Executor || Object animation | Progressive reveal, emphasis, movement, removal, or deliberate stillness clarifies sequence, causality, comparison, hierarchy, narration order, full-view → detail, atmosphere → evidence, or hotspot/annotation order | Add an optional §IX `Motion suggestion` naming each relevant semantic unit's lifecycle duty and initial state → communication action → end state, plus any meaningful order/relationship; leave group ids, effects, options, and timing to Executor |@@ -427,19 +428,6 @@ Correct failed selections by recall; `no-template-match` never enters `page_visu| P03 | chart | line_chart | Compare the source metrics over time |```-**Native-geometry candidate detail**: Add `Native shape suggestion` when a-page-level field, boundary, direction, reveal, visual nesting, literal stock-shape, or stock bent/curved Connector contour may strengthen the page. Describe-the semantic jobs and whether atoms should remain independent, not coordinates,-an exact preset key, endpoint/site metadata, or attachment promises. Only when-one contour, cutout, common region, or meaningful fragmentation is intended,-name the candidate Union / Combine / Fragment / Intersect / Subtract operation,-semantic operands, and result.-Executor still decides the exact page-fit native contour and authoring form,-independent compound construction, Boolean result, or necessary freeform under-its native-shape branch; the recommendation never creates a §VII row or lock-field.-### Speaker Notes RequirementsResolve the effective Speaker Notes outcome from the latest explicit userdiff --git a/skills/ppt-master/scripts/docs/advanced-image-motion-smoke.md b/skills/ppt-master/scripts/docs/advanced-image-motion-smoke.mdindex 7884115d..1c610eaf 100644--- a/skills/ppt-master/scripts/docs/advanced-image-motion-smoke.md+++ b/skills/ppt-master/scripts/docs/advanced-image-motion-smoke.md@@ -10,13 +10,14 @@ a test file or public example deck.The fixture deliberately closes the full planning and execution chain:-- `design_spec.md` carries `Motion suggestion`, `Native shape suggestion`, one- current §VIII image row, and `Crop Policy`;+- `design_spec.md` carries `Motion suggestion`, one current §VIII image row,+ and `Crop Policy`, with no native-shape planning field;- `spec_lock.md` projects that row with optional layout pattern `#M1-11`;- both pages reuse one raster through ordinary, ellipse-preset, and custom-pathindependent nested crops;- `animations.json` pairs the main crop across adjacent Morph pages;-- one helper-authored `rightArrow` verifies native preset discovery and export.+- one complete registry read plus a helper-authored `rightArrow` verifies+ Executor-local native preset discovery and export.```bashpython3 - <<'PY'@@ -68,6 +69,10 @@ draw.rectangle((860, 0, 1280, 720), fill="#0F172A")draw.ellipse((460, 150, 820, 510), fill="#F8FAFC")scene.save(images / "scene.png")+preset_inventory = run_tool("preset_shape_svg.py", "list").splitlines()+assert len(preset_inventory) == 187+assert "rightArrow" in preset_inventory+preset = run_tool("preset_shape_svg.py","render",@@ -139,12 +144,11 @@ preset = (#### Slide 01 - Overview- **Audience move**: See separate source views as one editable image system.-- **Layout**: Ordinary crop, shaped crop, and one native directional preset.+- **Layout**: Ordinary crop and shaped detail establish the first visual state.- **Title**: Overview crop state- **Core message**: One source can support independent native picture objects.- **Content**: Show the wide crop and shaped detail together.- **Images**: Use `scene.png` for both visible crop objects.-- **Native shape suggestion**: Use the PowerPoint `rightArrow` preset to indicate continuation.- **Motion suggestion**: Continue the primary crop into Slide 02 as one deterministic Morph object.#### Slide 02 - Detaildiff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.mdindex 5bc82d2e..eb05d069 100644--- a/skills/ppt-master/templates/design_spec_reference.md+++ b/skills/ppt-master/templates/design_spec_reference.md@@ -220,15 +220,14 @@ When an explicit final/literal narration script will become notes or generatedaudio, make §X `Content` name that source and say `preserve verbatim`; keep thefull segmented script in `notes/total.md`, not in §IX or this Design Spec.-Append either or both optional lines only when the capability earns a place;-never write an empty or `none` placeholder:+Append the optional line only when the capability earns a place; never write an+empty or `none` placeholder:```markdown-- **Native shape suggestion**: <semantic page/object geometry jobs plus independent atom roles, candidate preset/Connector family, or Boolean operation/operand roles as applicable>- **Motion suggestion**: <communication job plus desired page-entry or reveal relationship/order>```-Add `Mathematical content` whenever a Slide needs a mathematical expression preserved exactly. Store the expression body as valid LaTeX without `$...$`, `$$...$$`, `\(...\)`, or `\[...\]` source delimiters; the field does not classify inline versus structural use. This is content authority for [`native-formula.md`](../references/native-formula.md), not a formula policy, marker, or implementation request; Executor chooses ordinary text, inline native math, or block native math. Add `Visualization` / `Images` when a Slide consumes §VII/§VIII or uses a page-local visual model. Name every value-driven geometry, qualitative relationship, cell grid, and child visual here; only independent Chart/Table entries use object keys. Describe qualitative order, linkage, hierarchy, grouping, contrast, overlap, and reading path freely—not as a model name or grammar enum. §IX may choose a custom Chart/Table fallback. Add `Native shape suggestion` only when a page-level shape system, preset, stock Connector, or compound silhouette/cutout/intersection/fragment may help; name semantic geometry jobs and relationships plus independent atom roles, a candidate family, or Boolean operands as applicable, never implementation geometry or keys. Executor chooses the page-fit native contour and exact authoring form, independent compound construction, Boolean result, or necessary freeform. Add `Motion suggestion` whenever transition/reveal advice strengthens communication, regardless of the Custom Animations outcome; state purpose and semantic order/relationship, not registry keys, options, timing, ids, or coverage. The suggestion never activates animation execution by itself, creates content, or binds implementation. Describe required visible image states in `Layout` / `Images` only for an explicit motion requirement or an enabled Custom Animations outcome. Add keyed `Native-ready` only for independent data charts or pure text-grid tables, `Fact IDs` for sourced claims, and `Data class: scenario` for invented demo values. Except on preservation paths, `Cover impact` carries a binding hook and adaptable composition; apply the same split to `Closing impact` only when the deck genuinely resolves. Roster/order/content stay authoritative. §VIII image layout is non-empty free prose with optional library ids; §VII Chart/Table rows are references. Executor owns geometry, hierarchy, treatment, and sparse local garnish.+Add `Mathematical content` whenever a Slide needs a mathematical expression preserved exactly. Store the expression body as valid LaTeX without `$...$`, `$$...$$`, `\(...\)`, or `\[...\]` source delimiters; the field does not classify inline versus structural use. This is content authority for [`native-formula.md`](../references/native-formula.md), not a formula policy, marker, or implementation request; Executor chooses ordinary text, inline native math, or block native math. Add `Visualization` / `Images` when a Slide consumes §VII/§VIII or uses a page-local visual model. Name every value-driven geometry, qualitative relationship, cell grid, and child visual here; only independent Chart/Table entries use object keys. Describe qualitative order, linkage, hierarchy, grouping, contrast, overlap, and reading path freely—not as a model name or grammar enum. §IX may choose a custom Chart/Table fallback. Native construction creates no Design Spec field; Executor discovers and selects it independently during realization. Add `Motion suggestion` whenever transition/reveal advice strengthens communication, regardless of the Custom Animations outcome; state purpose and semantic order/relationship, not registry keys, options, timing, ids, or coverage. The suggestion never activates animation execution by itself, creates content, or binds implementation. Describe required visible image states in `Layout` / `Images` only for an explicit motion requirement or an enabled Custom Animations outcome. Add keyed `Native-ready` only for independent data charts or pure text-grid tables, `Fact IDs` for sourced claims, and `Data class: scenario` for invented demo values. Except on preservation paths, `Cover impact` carries a binding hook and adaptable composition; apply the same split to `Closing impact` only when the deck genuinely resolves. Roster/order/content stay authoritative. §VIII image layout is non-empty free prose with optional library ids; §VII Chart/Table rows are references. Executor owns geometry, hierarchy, treatment, and sparse local garnish.For free-design pages, describe `Layout` through relationships, hierarchy, regions, and column spans; do not prescribe element-level `x`, `y`, `width`, or `height` or duplicate the global geometry in §II/§V. Exact coordinates belong to Executor SVG authoring. Preserve literal geometry only when the user explicitly requires it or a mirror/template preservation contract owns it.diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex 7dc74d52..d965028e 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -652,7 +652,7 @@ sidecars, or guessed family paths.**Visual Construction Phase**: generate SVG pages sequentially, one at a time, in one continuous pass → `<project_path>/svg_output/`-Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Treat §IX `Native shape suggestion` as a candidate, not a command: inspect the actual page construction, then follow [`native-shape-authoring.md`](../references/native-shape-authoring.md) — choose page-fit contours from the full native vocabulary before their authoring forms, keep exact native atoms independent when possible, materialize a Merge Shapes Boolean result only where contour semantics require it, and use necessary freeform last. Diagram relationships follow the same Shape-first gate; do not infer a preset from contour similarity.+Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Native shapes are Executor-local authoring capabilities, not planned resources: follow [`native-shape-authoring.md`](../references/native-shape-authoring.md), load its complete current preset inventory before the first page, choose page-fit contours before their authoring forms, keep exact native atoms independent when possible, materialize a Merge Shapes Boolean result only where contour semantics require it, and use necessary freeform last. Diagram relationships follow the same Shape-first gate; do not infer a preset from contour similarity.**Motion-ready image composition**: Only when an explicit user motioninstruction, the effective Custom Animations outcome in `design_spec.md §I` is