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

fix(create-template): load the shape vocabulary before contours are chosen

hugohe31670c169a147
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 0839b275..6254e05c 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -848,7 +848,7 @@ PowerPoint shape target rather than one timeline record: the legacy
single-effect object creates one Animation Pane row, while `effects[]` may
create several ordered rows that all target the same shape.
-**Why page structure is auto-skipped.** Any top-level group with `data-pptx-layer` is static structure, and the current scanner also treats every explicit `data-pptx-placeholder` as static page framing; `background` / `header` / `footer` / `decoration` / `watermark` / `page-number` roles cover the remaining chrome. The ID-token fallback is not enabled or disabled per SVG: it applies to each top-level group that lacks layer, role, and placeholder markers, so a mixed new/legacy SVG may still use the legacy ID heuristic on only its unmarked groups. Separately, when an SVG has no top-level groups, no animation target has been found, and only one to eight root primitives qualify, those primitives form a bounded compatibility fallback. This is the scanner's actual scope; the animation reference's whole-page “marker-free legacy SVG” wording still needs separate alignment with the implementation.
+**Why page structure is auto-skipped.** Any top-level group with `data-pptx-layer` is static structure, and the current scanner also treats every explicit `data-pptx-placeholder` as static page framing; `background` / `header` / `footer` / `decoration` / `watermark` / `page-number` roles cover the remaining chrome. The ID-token fallback is not enabled or disabled per SVG: it applies to each top-level group that lacks layer, role, and placeholder markers, so a mixed new/legacy SVG may still use the legacy ID heuristic on only its unmarked groups. Separately, when an SVG has no top-level groups, no animation target has been found, and only one to eight root primitives qualify, those primitives form a bounded compatibility fallback. This is the scanner's actual scope.
**Why object-level animation uses a sidecar, not SVG attributes.** SVG remains
the static visual source of truth. Custom PPTX animation is export policy, so
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index cd190517..c4b4bb88 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -728,7 +728,7 @@ ChartEx 导入被有意限制为 7 个已验证数据模型:`treemap`、`sunbu
时序记录:旧单效果对象生成一条 Animation Pane 记录,`effects[]` 则可以生成
多条有序记录,并让它们共同指向同一 shape。
-**为什么页面结构自动跳过。** 顶层 group 只要带有 `data-pptx-layer`,就被视为不可动画的结构层;当前实现也把任何显式 `data-pptx-placeholder` 视为静态页框,`background` / `header` / `footer` / `decoration` / `watermark` / `page-number` 等 role 再补齐其余页面 chrome。ID token 回退不是按整份 SVG 启停,而是仅对同时缺少 layer、role 和 placeholder 的单个顶层 group 生效,因此新旧标记混合的 SVG 仍可能只在未标记 group 上使用 legacy ID 判断。另有一个有界的原语兼容回退:只有整页没有顶层 group、尚未找到任何动画目标且根原语候选为 1–8 个时,才把这些根原语作为锚点。这是当前扫描器的真实作用域;动画 reference 中“仅 marker-free legacy SVG”这一整页口径仍需另行与实现对齐。
+**为什么页面结构自动跳过。** 顶层 group 只要带有 `data-pptx-layer`,就被视为不可动画的结构层;当前实现也把任何显式 `data-pptx-placeholder` 视为静态页框,`background` / `header` / `footer` / `decoration` / `watermark` / `page-number` 等 role 再补齐其余页面 chrome。ID token 回退不是按整份 SVG 启停,而是仅对同时缺少 layer、role 和 placeholder 的单个顶层 group 生效,因此新旧标记混合的 SVG 仍可能只在未标记 group 上使用 legacy ID 判断。另有一个有界的原语兼容回退:只有整页没有顶层 group、尚未找到任何动画目标且根原语候选为 1–8 个时,才把这些根原语作为锚点。这是当前扫描器的真实作用域。
**为什么对象级动画用 sidecar,而不是 SVG 属性。** SVG 继续作为静态视觉源。
自定义 PPTX 动画属于导出策略,所以对象级覆盖放在可选的 `animations.json`,
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.md
index 6281688a..c21baa03 100644
--- a/skills/ppt-master/references/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -554,10 +554,12 @@ uses for group-select / group-move. Do not split or merge units to hit a target
count.
**Chrome stays static.** `data-pptx-layer` and explicit static
-role/placeholder markers are absolute. For marker-free legacy SVGs, chrome-like
-ids (background, header/footer, decor, watermark, page number, nav, logo, rule)
-are skipped; an explicit sidecar entry may override only this name heuristic.
-Keep wrappers and use `effect: none` for static content.
+role/placeholder markers are absolute. The legacy chrome-like ID heuristic
+(background, header/footer, decor, watermark, page number, nav, logo, rule)
+applies only to a top-level group that itself lacks `data-pptx-layer`,
+`data-pptx-role`, and `data-pptx-placeholder` semantics; an explicit sidecar
+entry may override only this name heuristic. Keep wrappers and use
+`effect: none` for static content.
**Fallback for flat SVGs** (no top-level `<g>` wrappers, only raw `<rect>` / `<text>` / `<path>` at the root):
diff --git a/skills/ppt-master/references/native-shape-authoring.md b/skills/ppt-master/references/native-shape-authoring.md
index c26b110f..83f17991 100644
--- a/skills/ppt-master/references/native-shape-authoring.md
+++ b/skills/ppt-master/references/native-shape-authoring.md
@@ -12,13 +12,18 @@ only when those constructions fail. Neither helper writes a page. The preset
helper does not create the shape's own `p:txBody`; keep visible text outside the
atomic fragment.
-**Mandatory — complete vocabulary at authoring entry**: before the first newly
-authored page or template contour in each valid context, read
+**Mandatory — complete vocabulary before contour selection**: In Create
+Template, load this reference and
[`preset-shape-vocabulary.md`](./preset-shape-vocabulary.md) completely and
-retain it. It exposes all 187 exact preset names under the Office gallery and
-objective contour families. This is Executor-side capability knowledge, never
-a Strategist task or Design Spec field. Reread only after context invalidation
-or a known file change; a filtered query cannot replace the complete read.
+retain both as soon as `replication_mode` resolves to `standard` or `fidelity`,
+before selecting any newly authored page or template contour. Do not load this
+authored-construction bundle for `mirror`; it preserves source-owned geometry.
+In every other valid authoring context, read the preset vocabulary completely
+at authoring entry before selecting the first newly authored contour. It exposes
+all 187 exact preset names under the Office gallery and objective contour
+families. This is authoring-side capability knowledge, never a Strategist task
+or Design Spec field. Reread only after context invalidation or a known file
+change; a filtered query cannot replace the complete read.
**Hard rule — direct structured calls**: `${SKILL_DIR}` below is the retained
absolute Skill root. After choosing a concrete lookup or authoring operation,
diff --git a/skills/ppt-master/references/template-designer.md b/skills/ppt-master/references/template-designer.md
index 7daae93c..bf147975 100644
--- a/skills/ppt-master/references/template-designer.md
+++ b/skills/ppt-master/references/template-designer.md
@@ -48,6 +48,14 @@ Input priority for PPTX-backed template creation depends on the AI-derived inter
| `standard` / `fidelity` | Finalized brief for the newly designed output; `manifest.json` for factual canvas/theme/assets | `authoring-svg/authoring_summary.json`, layered authoring SVGs, optional flat spot checks, and exported assets as visual references. Do not read `authoring_manifest.json`. Source Master/Layout topology is informational only and is not mined into output structure. |
| `mirror` | `manifest.json`, `native_structure.json`, and `svg/inheritance.json`; the compiler validates the tool-only authoring manifest | `authoring-svg/authoring_summary.json` plus layered authoring SVGs as the editable preservation IR; optional `authoring-svg-flat/` for complete-page verification; matching lossless `svg/` and optional `svg-flat/` only as immutable backing. |
+**Mandatory — authored construction bundle**: As soon as `replication_mode`
+resolves to `standard` or `fidelity`, and before selecting any page or template
+contour, read [`native-shape-authoring.md`](./native-shape-authoring.md) and
+[`preset-shape-vocabulary.md`](./preset-shape-vocabulary.md) completely and
+retain both for the active authoring context. Do not load this bundle for
+`mirror`; it preserves source-owned geometry and never selects or authors
+replacement contours.
+
Use the compact facts in `manifest.json` for orientation. Open screenshots or the original PPTX only for visual cross-checking.
**Native structure output**: Always set `native_structure_mode: structured`.
diff --git a/skills/ppt-master/scripts/docs/pptx-animations.md b/skills/ppt-master/scripts/docs/pptx-animations.md
index d6fa0822..1b25b6c4 100644
--- a/skills/ppt-master/scripts/docs/pptx-animations.md
+++ b/skills/ppt-master/scripts/docs/pptx-animations.md
@@ -141,8 +141,9 @@ start/end remain derived rather than duplicated.
## 4. Target Resolution
Generated object animation targets top-level SVG content groups. Explicit SVG
-semantics are authoritative; the group-id chrome heuristic is only a fallback
-for marker-free legacy SVGs.
+semantics are authoritative; the group-id chrome heuristic applies only to a
+top-level group that itself lacks `data-pptx-layer`, `data-pptx-role`, and
+`data-pptx-placeholder` semantics.
| Target state | Behavior |
|---|---|
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index abf1a0df..15325e4e 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -97,10 +97,10 @@
"skills/ppt-master/templates/README.md",
"skills/ppt-master/templates/styles/README.md"
],
- "max_tokens": 37000
+ "max_tokens": 38000
},
"route.create-template.deck": {
- "description": "Create Deck path through Template_Designer, SVG core, and the structured PPTX interface.",
+ "description": "Create Deck standard/fidelity path through Template_Designer, the strategy-triggered native-shape bundle, SVG core, and the structured PPTX interface; mirror excludes the authored bundle.",
"scope": "cumulative",
"include": [
"bootstrap.routing"
@@ -109,16 +109,18 @@
"skills/ppt-master/workflows/create-template.md",
"skills/ppt-master/workflows/create-template/create-deck.md",
"skills/ppt-master/references/template-designer.md",
+ "skills/ppt-master/references/native-shape-authoring.md",
+ "skills/ppt-master/references/preset-shape-vocabulary.md",
"skills/ppt-master/references/shared-standards-core.md",
"skills/ppt-master/references/pptx-structure-interface.md",
"skills/ppt-master/references/canvas-formats.md",
"skills/ppt-master/templates/README.md",
"skills/ppt-master/templates/decks/README.md"
],
- "max_tokens": 67000
+ "max_tokens": 75000
},
"route.create-template.layout": {
- "description": "Create Layout path through Template_Designer, SVG core, and the structured PPTX interface.",
+ "description": "Create Layout standard/fidelity path through Template_Designer, the strategy-triggered native-shape bundle, SVG core, and the structured PPTX interface; mirror excludes the authored bundle.",
"scope": "cumulative",
"include": [
"bootstrap.routing"
@@ -127,13 +129,15 @@
"skills/ppt-master/workflows/create-template.md",
"skills/ppt-master/workflows/create-template/create-layout.md",
"skills/ppt-master/references/template-designer.md",
+ "skills/ppt-master/references/native-shape-authoring.md",
+ "skills/ppt-master/references/preset-shape-vocabulary.md",
"skills/ppt-master/references/shared-standards-core.md",
"skills/ppt-master/references/pptx-structure-interface.md",
"skills/ppt-master/references/canvas-formats.md",
"skills/ppt-master/templates/README.md",
"skills/ppt-master/templates/layouts/README.md"
],
- "max_tokens": 67000
+ "max_tokens": 76000
},
"route.enhance-native-pptx": {
"description": "Finished-PPTX native enhancement route.",
@@ -990,7 +994,7 @@
"max_tokens": 1000
},
"stage.create-template.authored-preset": {
- "description": "Conditional complete preset vocabulary plus native preset and Boolean shape authoring authority for Create Layout/Create Deck. Ceiling raised after BUDGET_LOAD_SET reported 9139 tokens.",
+ "description": "Conditional native-shape and complete preset-vocabulary bundle loaded when Create Layout/Create Deck resolves to standard/fidelity, before any contour selection; mirror excludes it. Ceiling raised after BUDGET_LOAD_SET reported 9139 tokens.",
"scope": "incremental",
"files": [
"skills/ppt-master/references/native-shape-authoring.md",
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index 0ad0a80f..72e2a013 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -527,6 +527,15 @@ The preflight is atomic at the Create Template parent level: settle every output
**Create Layout/Create Deck branch**: continue in the selected child workflow, switch to the Template_Designer role, and generate per role definition. Bind the role's `<template_workspace>` to `<authoring_workspace>` and pass `<design_spec_path>`, the finalized brief from Step 3, and the Step-1 analysis bundle with accepted norms.
+**Mandatory — authored construction bundle**: Immediately after the confirmed
+creation strategy resolves to `standard` or `fidelity`, and before
+Template_Designer selects any page or template contour, read
+[`native-shape-authoring.md`](../references/native-shape-authoring.md) and
+[`preset-shape-vocabulary.md`](../references/preset-shape-vocabulary.md)
+completely and retain both for the active authoring context. Do not load this
+bundle for `mirror`; it preserves source-owned geometry and does not select or
+author replacement contours.
+
When the bundle includes Type A, pass the following internal package to the role:
- finalized brief from Step 3