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

chore(svg-semantics): align templates and authoring contracts

hugohe3ba97ac5f1fa1
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 1ff0358a..ac0577fa 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -82,7 +82,7 @@ The past two months' structural capability growth. Single flags / incremental po
- **`--native-objects` hardened from dormant marker to usable opt-in** — the narrow native-object exception (see Non-goals below) now emits charts and pure-text tables that keep the deck's own design instead of snapping to PowerPoint's white default theme. Classic native charts write explicit chart-area / plot-area / axis-line / gridline / label-text colors — inferred from the visible SVG fallback (largest panel `<rect>` → background, fallback text → labels, fallback strokes → axis/grid) or overridden per `style` (`chart_area_fill` / `plot_area_fill` / `text_color` / `axis_color` / `grid_color`, `"none"` for transparent); the color parser normalizes named CSS colors, `#RGB` shorthand, and `rgb()` / `rgba()` to OOXML hex; bar/column series disable negative-value fill inversion so negative bars keep their series color. The activated export is named `<name>_<ts>_native_charts.pptx` to tell it apart from the default flattened-shape export. **The default route is unchanged** — charts/tables still export as SVG-derived DrawingML shapes for cross-renderer fidelity; native objects stay the deliberate opt-in trade documented under Non-goals below
-- **Native package structure + conservative PPTX object round-trip** — free-design baseline export promotes only safe shared backgrounds/chrome, assigns filename-backed Layout families, and may lift exact family-wide leading chrome without inferring placeholders. Template export deterministically compiles complete SVG pages whose Master/Layout/placeholder ownership is explicit. `create-template` uses imported source structure as analysis input and always rebuilds explicit SVG structure; strict keeps a selected Layout, adaptive may add a new Layout under the same Master. Legacy `preserve` remains compatibility-only. Raw one-off PPTX filling remains `template-fill-pptx`.
+- **Native package structure + conservative PPTX object round-trip** — free-design baseline export promotes only safe shared backgrounds/chrome, assigns marker-backed Layout families, and may lift exact family-wide leading structurally marked chrome without inferring placeholders; marker-free legacy SVGs retain filename/id fallback. Template export deterministically compiles complete SVG pages whose Master/Layout/placeholder ownership is explicit. `create-template` uses imported source structure as analysis input and always rebuilds explicit SVG structure; strict keeps a selected Layout, adaptive may add a new Layout under the same Master. Legacy `preserve` remains compatibility-only. Raw one-off PPTX filling remains `template-fill-pptx`.
---
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 7d6b0387..d19edeaf 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -59,6 +59,8 @@ Output:
For every workflow that authors or redesigns visual slides through SVG, `svg_output/` is the complete page-design authority. Every visible text, image, shape, diagram, chart/table fallback, background, and template-derived layout element that should appear on a slide must already exist in that page SVG or be explicitly referenced by it. Templates, `design_spec.md`, and `spec_lock.md` guide SVG authoring; the exporter does not use them as a second visual layer that fills in missing page content.
+Minimal semantic markers do not weaken that closure. Existing Layout/Layer/Placeholder/Native metadata remains authoritative. On baseline/free-design pages, root `data-pptx-page-role` replaces filename-only family inference; `data-pptx-role` is reserved for the few structural page-frame objects whose package or animation behavior is not already expressed by specialized metadata. Ordinary titles, body text, cards, KPIs, diagrams, charts, icons, and images are not duplicated into a metadata ontology.
+
| Domain | Authority |
|---|---|
| Visible page content and layout on SVG-authoring routes | Final page SVG in `svg_output/` |
@@ -440,7 +442,7 @@ These direct routes share some analysis primitives with the main pipeline, espec
**Why compatibility fallback belongs to the SVG snapshot path, not native shapes.** Native PPTX export translates supported SVG elements into DrawingML shapes and explicitly disables PNG+SVG compatibility mode in native-shapes mode. The PNG fallback is used only by the legacy SVG-image path (`--svg-snapshot` / `--only legacy`) when a renderer is available, because that path embeds SVG media that older Office builds may not display. Legacy compatibility is therefore an optional snapshot deliverable, not a fallback bundled inside the primary editable native deck.
-**Why the default native deck has a baseline master, not inferred templates.** `svg_to_pptx.py` starts from the actual blank slide layout relationship in the base package and defaults to `--pptx-structure baseline`. Baseline promotes only low-risk shared structure: the strict-majority identical slide background plus a common leading prefix of repeated top-level SVG chrome whose exact id tokens say `logo`, `footer`, `header`, `watermark`, `chrome`, `pageNumber`, or `slideNumber`. Promotion requires identical generated OOXML, no timing reference, and z-order safety; minority pages keep their shapes slide-local and use a `Cover` layout with `showMasterSp="0"`. A later export-only pass assigns `Cover`, `Agenda`, `Section`, `Closing`, or fallback `Content`. It moves an exact family-wide background and an exact leading family-wide chrome prefix into that Layout, but never compares visual similarity or infers placeholders. Actual content remains on the Slide. This gives free-design decks useful Master/Layout structure without constraining SVG authoring.
+**Why the default native deck has a baseline master, not inferred templates.** `svg_to_pptx.py` starts from the actual blank slide layout relationship in the base package and defaults to `--pptx-structure baseline`. Baseline promotes only low-risk shared structure: the strict-majority identical slide background plus a common leading prefix of repeated top-level SVG chrome explicitly marked as `logo`, `footer`, `header`, `watermark`, `chrome`, or `page-number`. Exact id tokens remain a fallback for marker-free legacy SVGs. Promotion requires identical generated OOXML, no timing reference, and z-order safety; minority pages keep their shapes slide-local and use a `Cover` layout with `showMasterSp="0"`. A later export-only pass maps root `data-pptx-page-role` to `Cover`, `Agenda`, `Section`, `Closing`, or `Content`, falling back to conservative filename tokens only when the root marker is absent. It moves an exact family-wide background and an exact leading family-wide chrome prefix into that Layout, but never compares visual similarity or infers placeholders. Actual content remains on the Slide. This gives free-design decks useful Master/Layout structure without constraining SVG authoring.
**Why reusable layouts require explicit SVG metadata.** `--pptx-structure template` is the opt-in path for a generated deck that must remain reusable as a PowerPoint template. The final slide SVGs declare a layout key at the root, mark only direct root children as master/layout layers, and attach typed placeholder semantics to the slide-local prototypes that should become layout placeholders. Export validates that shared master and same-key layout declarations are structurally and visually identical, then emits real layout parts and `p:ph` references while leaving every unmarked object slide-local. This is deterministic structure compilation, not visual-template inference.
@@ -458,7 +460,7 @@ The interesting design choice is the animation **anchor**, not the effect list.
**Why anchor entrance animations on top-level `<g>` groups.** PowerPoint's animation timeline is shape-keyed — each animated object needs a stable shape ID. Animating individual primitives would produce 30+ separately-flying-in atoms per slide (a kinetic mess), while animating only the slide as a whole loses visual storytelling. Top-level groups are the natural granularity: Executor is required to use `<g id="...">` to mark logical content blocks, and these blocks are exactly the units a viewer reads as "one thing arriving" — animation matches the existing logical structure rather than imposing a new one.
-**Why page chrome is auto-skipped.** Groups named `background` / `header` / `footer` / `decoration` / `watermark` / `page_number` represent the static slide frame, not content; flying them in would feel jarring (the page itself materializing every transition) and is virtually never what the user wants. Filtering by id-token is brittle in principle but reliable in practice because the token vocabulary is small and the Executor controls naming.
+**Why page chrome is auto-skipped.** Existing Layer and slide-number Placeholder semantics identify static structure first; minimal `background` / `header` / `footer` / `decoration` / `watermark` / `page-number` roles fill only the remaining gaps. Flying page framing in would feel jarring (the page itself materializing every transition) and is virtually never what the user wants. Exact id-token matching remains only as a compatibility fallback when all explicit markers are absent.
**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 per-object overrides live in optional `animations.json` keyed by slide stem and top-level group id. This avoids polluting SVG with PowerPoint-specific metadata while still letting users tune order, effect, delay, and duration when the default global animation is not enough.
diff --git a/docs/templates-architecture.md b/docs/templates-architecture.md
index 38e8fe5f..6d5c6a2a 100644
--- a/docs/templates-architecture.md
+++ b/docs/templates-architecture.md
@@ -14,7 +14,7 @@
| **Layout** | `templates/layouts/<id>/` | Structure segment only: canvas / page structure / page types / SVG roster | No brand identity (no logo, no locked brand color) | `workflows/create-template.md` (layout branch) |
| **Deck** | `templates/decks/<id>/` | All segments: identity + structure + middle (template overview) | — | `workflows/create-template.md` (deck branch, default) |
-Every Layout/Deck SVG is a complete preview with explicit `data-pptx-layout`, Master/Layout layers, and semantic placeholders. PPTX-import artifacts are analysis inputs only and are not packaged into new templates. The template guides authoring of a complete generated page SVG; export never reaches back into the template to overlay visible content missing from that generated SVG. Strict use keeps the selected Layout contract; adaptive use may create a new Layout under the same Master. Both export through `pptx_structure.mode: template`; legacy `preserve` remains compatibility-only.
+Every Layout/Deck SVG is a complete preview with explicit `data-pptx-layout`, Master/Layout layers, and semantic placeholders. These specialized markers are authoritative; minimal `data-pptx-role` hints are added only for structural page-frame behavior they cannot express, and ordinary content is not duplicated into a metadata taxonomy. PPTX-import artifacts are analysis inputs only and are not packaged into new templates. The template guides authoring of a complete generated page SVG; export never reaches back into the template to overlay visible content missing from that generated SVG. Strict use keeps the selected Layout contract; adaptive use may create a new Layout under the same Master. Both export through `pptx_structure.mode: template`; legacy `preserve` remains compatibility-only.
The three are **parallel reference bundles**. The physical directory and the frontmatter `kind` field correspond one-to-one:
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 89322cd3..2a924919 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -59,6 +59,8 @@
凡是通过 SVG 创作或重新设计页面的工作流,`svg_output/` 都是完整的页面设计权威。最终幻灯片中应出现的文字、图片、形状、图示、图表 / 表格 fallback、背景和模板派生布局元素,都必须已经存在于对应页面 SVG 中,或被它明确引用。模板、`design_spec.md` 和 `spec_lock.md` 负责指导 SVG 创作;导出器不能把它们当成第二层画面来源,在导出阶段补入 SVG 缺失的页面内容。
+最小语义标记不会削弱这条闭包。现有 Layout、Layer、Placeholder 与 Native metadata 始终优先。Baseline / 自由设计页面用根节点 `data-pptx-page-role` 取代仅靠文件名判断页面家族;`data-pptx-role` 只补充专用 metadata 尚未表达的少量页面框架、package 或动画行为。普通标题、正文、卡片、KPI、图示、图表、图标和图片不会被重复抄入一套 metadata 本体。
+
| 领域 | 权威来源 |
|---|---|
| SVG 创作路线中的可见页面内容与布局 | `svg_output/` 中的最终页面 SVG |
@@ -440,7 +442,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份
**为什么兼容 fallback 属于 SVG snapshot 路径,而不是 native shapes。** Native PPTX 导出会把受支持的 SVG 元素翻译成 DrawingML 形状,并在 native-shapes 模式下显式关闭 PNG+SVG 兼容模式。PNG fallback 只在 legacy SVG-image 路径(`--svg-snapshot` / `--only legacy`)且本地 renderer 可用时使用,因为那条路径嵌入的是旧版 Office 可能无法显示的 SVG media。因此,旧版兼容是一份可选 snapshot 交付物,不是捆在主 editable native deck 里的兜底层。
-**为什么默认 native deck 使用基线母版,而不推断模板。** `svg_to_pptx.py` 默认使用 `--pptx-structure baseline`。它只提升低风险共享结构:严格多数页面完全一致的背景,以及 id 明确标记为 `logo`、`footer`、`header`、`watermark`、`chrome`、`pageNumber` 或 `slideNumber` 的共同前置 chrome。提升还要求 OOXML 完全一致、无动画引用且 z-order 安全;少数派页面继续使用隐藏母版图形的 `Cover` 版式。导出后处理再按文件名分配 `Cover`、`Agenda`、`Section`、`Closing` 或 `Content`,并把一家族所有页面完全一致的背景与前置 chrome 提升到该 Layout。它不做视觉相似度比较、不猜占位符,实际内容始终留在 Slide。
+**为什么默认 native deck 使用基线母版,而不推断模板。** `svg_to_pptx.py` 默认使用 `--pptx-structure baseline`。它只提升低风险共享结构:严格多数页面完全一致的背景,以及显式标记为 `logo`、`footer`、`header`、`watermark`、`chrome` 或 `page-number` 的共同前置 chrome;没有结构角色的旧 SVG 才回退到精确 id token。提升还要求 OOXML 完全一致、无动画引用且 z-order 安全;少数派页面继续使用隐藏母版图形的 `Cover` 版式。导出后处理优先按根节点 `data-pptx-page-role` 分配 `Cover`、`Agenda`、`Section`、`Closing` 或 `Content`,只有缺少根标记的旧 SVG 才回退到保守文件名判断。它可以把一家族所有页面完全一致的背景与前置 chrome 提升到该 Layout,但不做视觉相似度比较、不猜占位符,实际内容始终留在 Slide。
**为什么可复用版式必须依赖显式 SVG 元数据。** `--pptx-structure template` 是生成型 deck 需要继续作为 PowerPoint 模板复用时的 opt-in 路径。最终 slide SVG 在根节点声明 layout key,只允许根节点的直接子元素标记 master/layout layer,并在应成为版式占位框的 slide-local 原型上附加类型语义。导出器会验证共享 master 与同 key layout 的声明在结构和视觉上完全一致,再生成真实 layout part 与 `p:ph` 引用;所有未标记对象仍保持 slide-local。这是确定性的结构编译,不是根据视觉相似度猜模板。
@@ -458,7 +460,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份
**为什么把入场动画锚在顶层 `<g>` group。** PowerPoint 的动画时序基于形状 ID——每个被动画的对象需要稳定的 shape ID。给单个原语做动画会产出每页 30+ 个分别飞入的原子(动感泛滥),只给整页做动画又损失视觉叙事。顶层 group 是自然粒度:Executor 本来就被强制要求用 `<g id="...">` 标记逻辑内容块,而这些块正是观众读作「一个东西到达」的单位——动画对齐了已有的逻辑结构,而不是另立门户。
-**为什么页面装饰自动跳过。** 名为 `background` / `header` / `footer` / `decoration` / `watermark` / `page_number` 的 group 代表静态页面框架,不是内容;让它们飞入会让人出戏(页面本身在每次切换时具象化),几乎不会是用户想要的。按 id token 过滤原则上脆弱,实际上可靠——因为 token 词表很小,命名权又掌握在 Executor 手里。
+**为什么页面装饰自动跳过。** 现有 Layer 与 slide-number Placeholder 语义首先识别静态结构;最小 `background` / `header` / `footer` / `decoration` / `watermark` / `page-number` role 只补其余缺口。让页面框架飞入会让人出戏(页面本身在每次切换时具象化),几乎不会是用户想要的。只有所有显式标记都缺失的旧 SVG 才回退到精确 id token。
**为什么对象级动画用 sidecar,而不是 SVG 属性。** SVG 继续作为静态视觉源。自定义 PPTX 动画属于导出策略,所以对象级覆盖放在可选的 `animations.json`,按 slide stem 和顶层 group id 关联。这样不会把 PowerPoint 专用元数据塞进 SVG,同时仍能在默认全局动画不够用时调整顺序、效果、延迟和时长。
diff --git a/docs/zh/templates-architecture.md b/docs/zh/templates-architecture.md
index c1044d76..b4795476 100644
--- a/docs/zh/templates-architecture.md
+++ b/docs/zh/templates-architecture.md
@@ -14,7 +14,7 @@
| **Layout** | `templates/layouts/<id>/` | 仅结构段:canvas / page structure / page types / SVG roster | 不写品牌身份(无 logo、无品牌色硬约束) | `workflows/create-template.md`(layout 分支)|
| **Deck** | `templates/decks/<id>/` | 全段:身份段 + 结构段 + 中间段(template overview) | —— | `workflows/create-template.md`(deck 分支,默认)|
-Layout/Deck 的每张 SVG 都是完整预览,同时显式声明 `data-pptx-layout`、Master/Layout 层和语义 placeholder。PPTX 导入产生的 `native_structure.json` 与 `source_template.pptx` 只用于分析源结构,不进入新模板包。模板负责指导生成完整的页面 SVG;导出时不得再回读模板,向生成 SVG 叠加其中缺失的可见内容。下游 `strict` 保持所选 Layout 契约,`adaptive` 可在同一 Master 下创建新 Layout;两者都使用 `pptx_structure.mode: template`。旧 `preserve` 契约仅保留兼容读取。
+Layout/Deck 的每张 SVG 都是完整预览,同时显式声明 `data-pptx-layout`、Master/Layout 层和语义 placeholder。这些专用标记具有最高优先级;最小 `data-pptx-role` 只补充它们无法表达的页面框架行为,普通内容不会被重复分类到 metadata 词表。PPTX 导入产生的 `native_structure.json` 与 `source_template.pptx` 只用于分析源结构,不进入新模板包。模板负责指导生成完整的页面 SVG;导出时不得再回读模板,向生成 SVG 叠加其中缺失的可见内容。下游 `strict` 保持所选 Layout 契约,`adaptive` 可在同一 Master 下创建新 Layout;两者都使用 `pptx_structure.mode: template`。旧 `preserve` 契约仅保留兼容读取。
三者是**三种并列的 reference bundle**,物理目录与 frontmatter `kind` 字段双向对齐:
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 9a8a3af1..fb31fd83 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -19,6 +19,7 @@ description: >
|---|---|
| Any route that authors or regenerates slide visuals through SVG | `svg_output/` is the complete page-design source: every visible text, image, shape, chart/table fallback, and layout element that should appear on the exported slide is present in that page SVG or referenced by it. |
| Templates, `design_spec.md`, and `spec_lock.md` | Authoring/control inputs. They guide SVG creation but MUST NOT supply visible slide content that is absent from the completed SVG during export. |
+| Semantic SVG markers | Minimal rendering-neutral compiler hints used only after existing Layout/Layer/Placeholder/Native metadata has been considered. They never replace native SVG geometry, text, styles, grouping, or asset references. |
| SVG-to-PPTX export | Translation only: map SVG content to DrawingML/native objects and reorganize represented content into Master/Layout/Slide structure without inventing new visible page content. |
| Direct PPTX and presentation-behavior workflows | Remain separate. `template-fill-pptx`, `native-enhance-pptx`, animations, transitions, speaker notes, narration, and package relationships are not required to round-trip through SVG. |
@@ -602,6 +603,8 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon
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.
+Every `baseline` / free-design page root MUST declare one canonical `data-pptx-page-role`; `template` / `preserve` pages already declare `data-pptx-layout` and MUST NOT duplicate that identity merely to satisfy this rule. Add `data-pptx-role` only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by `data-pptx-layer`, `data-pptx-placeholder`, or `data-pptx-native`; such an element needs a stable unique `id`. Do not add generic content roles to ordinary titles, body text, cards, KPIs, diagrams, charts, icons, or images. Full contract: [`references/semantic-svg.md`](references/semantic-svg.md).
+
**Quality Check Gate (Mandatory)** — after all SVGs, BEFORE annotation handling and speaker notes:
```bash
python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>
@@ -701,17 +704,20 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> native slide background into the slide master (every slide must carry an
> explicit background; minority slides keep their own, which overrides the
> master fill). Baseline may also promote a shared **leading** prefix of
-> top-level SVG elements whose exact id tokens mark page chrome (`logo`,
-> `footer`, `header`, `watermark`, `chrome`, `pageNumber` / `slideNumber`).
+> top-level SVG elements whose explicit `data-pptx-role` marks page chrome
+> (`logo`, `footer`, `header`, `watermark`, `chrome`, `page-number`). Exact id
+> tokens remain a compatibility fallback only when the role marker is absent.
> Promotion requires identical generated OOXML on a strict majority of slides
> sharing the master, no slide-timing reference, and z-order safety; overlay
> chrome stays slide-local. Minority slides (covers, section pages) keep every
> shape slide-local and are bound to a generated `Cover` layout with
> `showMasterSp="0"`, so promoted master chrome never appears on them. Image
> relationships for promoted chrome are copied to the master. After the SVG
-> pages are complete, baseline assigns conservative filename-backed layout
-> families: explicit cover / agenda / section / closing names become `Cover`,
-> `Agenda`, `Section`, and `Closing`; every other page becomes `Content`. It also
+> pages are complete, baseline assigns conservative semantic layout families:
+> root `data-pptx-page-role` values `cover` / `toc` / `section` / `ending` become
+> `Cover` / `Agenda` / `Section` / `Closing`, while `content` becomes `Content`.
+> Filename tokens remain a compatibility fallback for marker-free legacy SVGs.
+> It also
> preserves an existing safety `Cover` assignment made while hiding promoted
> Master chrome. It does not inspect visual similarity or infer placeholders,
> and all actual page content remains slide-local. When every slide in one
@@ -724,9 +730,10 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> unchanged. Baseline also prunes base-template slide layouts no generated slide
> references, so the PowerPoint new-slide picker only offers layouts that belong
> to the deck, and
-> converts `pageNumber` / `slideNumber` chrome whose text exactly equals the
+> converts `data-pptx-role="page-number"` chrome whose text exactly equals the
> slide's display number into an auto-updating PowerPoint slide-number field
-> (other numbering schemes keep their literal text). For projects with a
+> (legacy page-number id tokens remain a fallback; other numbering schemes keep
+> their literal text). For projects with a
> `spec_lock.md` typography contract, baseline also installs `title_family` as
> the PowerPoint theme major font and `body_family` / `font_family` as the minor
> font; matching SVG runs use theme tokens so later theme edits can cascade
@@ -846,6 +853,7 @@ Before switching roles, **MUST first read** the corresponding reference file. Ou
| Resource | Path |
|----------|------|
| Shared technical constraints | `references/shared-standards.md` |
+| Semantic SVG marker contract | `references/semantic-svg.md` |
| Canvas format specification | `references/canvas-formats.md` |
| Image-text layout patterns (Primary structures + Modifier layers — combine freely) | `references/image-layout-patterns.md` |
| Image layout sizing (math for side-by-side container dimensions) | `references/image-layout-spec.md` |
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 53a48ea6..8e3e3378 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -4,6 +4,8 @@
**Hard rule — complete page SVG**: Every visible object intended for the exported slide MUST exist in the final page SVG or be explicitly referenced by it. Templates and `spec_lock.md` guide construction; they are not export-time overlays for missing visible content.
+**Hard rule — minimal semantics without semantic loss**: `baseline` / free-design roots declare `data-pptx-page-role`; `template` / `preserve` roots already use `data-pptx-layout` and do not duplicate that identity. Add `data-pptx-role` only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by layer, placeholder, or native-object metadata; the marked element uses a stable unique `id`. Ordinary page content keeps normal SVG structure without duplicate semantic classification. See [`semantic-svg.md`](./semantic-svg.md).
+
> Note: this rule covers page design only. Speaker notes, animations, transitions, narration, and direct native-PPTX workflows retain their separate artifacts and package-level processing.
---
@@ -104,7 +106,7 @@ Before generating each page, output which template is used:
| `pptx_structure.mode` | Executor behavior |
|---|---|
-| `baseline` or missing | Free design or brand-only route. Author ordinary standalone SVG pages; export assigns conservative filename-backed Layout families after generation. |
+| `baseline` or missing | Free design or brand-only route. Author complete standalone SVG pages with root page-role and only necessary structural hints; export assigns conservative marker-backed Layout families after generation. |
| `template` | Every generated SVG MUST implement the matching `pptx_layouts` row and the explicit structure contract below. |
| `preserve` | Legacy strict-only compatibility. Use the locked source layout key/name and retain marked preview layers for source-package reuse. |
@@ -112,7 +114,7 @@ Before generating each page, output which template is used:
**Hard rule — PowerPoint paint order**: Direct visual children appear in this order: Master background, Layout background, optional Slide background, shared Master shapes, same-key Layout shapes, then slide-local content/placeholders. Backgrounds are the special plane beneath all inherited shapes. Repeat the same Master contract on every page and the same Layout contract on every page sharing a key.
-**Placeholder ownership**: Keep actual title/subtitle/body/picture/chart/table/object/media/date/footer/slide-number content on the Slide and add the matching `data-pptx-placeholder`. Do not move actual content into a Layout. A reconstructed `title` normally omits `data-pptx-placeholder-idx`; preserve an explicit imported title index when present. Every indexed placeholder on one layout uses a unique index. Chart/table placeholders require native markers and a later `--native-objects` export; object/media placeholders must each resolve to one top-level DrawingML object.
+**Placeholder ownership**: Keep actual title/subtitle/body/picture/chart/table/object/media/date/footer/slide-number content on the Slide and add the matching `data-pptx-placeholder`. Do not duplicate placeholder identity with `data-pptx-role`; in particular, `data-pptx-placeholder="slide-number"` already owns page-number field behavior. A reconstructed `title` normally omits `data-pptx-placeholder-idx`; preserve an explicit imported title index when present. Every indexed placeholder on one layout uses a unique index. Chart/table placeholders require native markers and a later `--native-objects` export; object/media placeholders must each resolve to one top-level DrawingML object.
**Adaptive Layout creation**: Start from the selected template SVG, keep every Master element identical, and change only the Layout layer/placeholder contract needed for the new composition. Pages sharing the new key repeat the same static Layout elements and placeholder ids/types in the same order.
@@ -193,7 +195,7 @@ Do **not** invent a layout entry, and do **not** assume a template just because
**Per-page PowerPoint layout lookup — `pptx_layouts` section**:
- `pptx_structure.mode: template` or `preserve` → a `P<NN>` row is mandatory; apply §1.2 to the root and direct children. Preserve mode uses the exact source key/name and placeholder indices.
-- `pptx_structure.mode: baseline` or missing → omit explicit PPTX structure metadata; baseline export owns conservative Master/background/chrome promotion plus filename-backed Layout family assignment.
+- `pptx_structure.mode: baseline` or missing → omit explicit PPTX layer/layout metadata, but keep the root page role and only necessary structural hints. Baseline export owns conservative Master/background/chrome promotion plus page-role-backed Layout family assignment; filenames and ids are legacy fallbacks only when the corresponding marker is absent.
- A layout key may repeat across non-adjacent pages. Reuse is based on identical static/placeholder contracts, not page proximity or content wording.
**Per-page chart reference — `page_charts` section**:
diff --git a/skills/ppt-master/references/semantic-svg.md b/skills/ppt-master/references/semantic-svg.md
new file mode 100644
index 00000000..e37ebb8f
--- /dev/null
+++ b/skills/ppt-master/references/semantic-svg.md
@@ -0,0 +1,126 @@
+# Minimal Semantic SVG Markers
+
+PPT Master uses a small set of rendering-neutral compiler hints only where
+ordinary SVG cannot reliably express a required PowerPoint packaging decision.
+These markers are not a second content model and do not abbreviate SVG.
+
+## 1. Boundary
+
+| Marker | Placement | Purpose |
+|---|---|---|
+| `data-pptx-page-role` | Root `<svg>` | Select the baseline PowerPoint Layout family. Required on newly generated baseline/free-design pages; template/preserve pages already use `data-pptx-layout`. |
+| `data-pptx-role` | A structural page-frame element | Identify the few objects whose package or animation behavior is not already expressed by specialized metadata. The element also needs a stable unique `id`. |
+
+The complete geometry, text, styles, grouping, and asset references remain in
+ordinary SVG. Removing these markers must not change browser rendering. Do not
+copy visible values into metadata, and do not mark ordinary titles, body text,
+cards, KPIs, diagrams, charts, icons, or images merely to describe their
+content.
+
+Use the existing specialized contracts for specialized facts:
+
+- `data-pptx-layout` and `data-pptx-layer` own Master/Layout/Slide structure;
+- `data-pptx-placeholder` owns PowerPoint placeholder identity;
+- `data-pptx-native` owns native chart/table reconstruction.
+
+Do not duplicate those facts with `data-pptx-role`. Consumers resolve semantics
+in this order: specialized metadata, minimal compiler hints, then legacy
+filename/id conventions.
+
+## 2. Canonical Values
+
+### Page roles
+
+| Value | Meaning | Baseline Layout |
+|---|---|---|
+| `cover` | Opening cover | `Cover` |
+| `toc` | Agenda or contents page | `Agenda` |
+| `section` | Chapter divider or transition | `Section` |
+| `content` | Ordinary information page | `Content` |
+| `ending` | Closing, thanks, Q&A, or contact page | `Closing` |
+
+### Structural roles
+
+| Value | Compiler behavior |
+|---|---|
+| `background` | Treat an otherwise unmarked background as static page framing for animation purposes. |
+| `decoration` | Treat decorative page framing as static for animation purposes. |
+| `header` | Eligible for conservative repeated-chrome promotion; skip automatic entrance animation. |
+| `footer` | Eligible for conservative repeated-chrome promotion; skip automatic entrance animation. |
+| `logo` | Eligible for conservative repeated-chrome promotion; skip automatic entrance animation. |
+| `watermark` | Eligible for conservative repeated-chrome promotion; skip automatic entrance animation. |
+| `chrome` | Generic repeated page-frame object eligible for conservative promotion. |
+| `page-number` | Identify a free-design page-number object; template `data-pptx-placeholder="slide-number"` already owns this behavior. |
+
+`background` and `decoration` do not by themselves authorize Master/Layout
+promotion. The existing background and exact-shared-structure safety checks
+continue to own that decision.
+
+## 3. Examples
+
+### Free-design page
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg"
+ viewBox="0 0 1280 720"
+ data-pptx-page-role="content">
+ <rect id="page-bg" data-pptx-role="background"
+ x="0" y="0" width="1280" height="720" fill="#F7F9FC"/>
+
+ <!-- Ordinary content keeps normal SVG structure; no duplicate role needed. -->
+ <g id="growth-story">
+ <text x="72" y="82" font-size="32" fill="#172033">Quarterly growth</text>
+ </g>
+
+ <text id="slide-number" data-pptx-role="page-number"
+ x="1200" y="680" font-size="14" fill="#667085">7</text>
+</svg>
+```
+
+### Reusable template page
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg"
+ viewBox="0 0 1280 720"
+ data-pptx-layout="content-default"
+ data-pptx-layout-name="Content Default">
+ <rect id="master-bg"
+ data-pptx-layer="master"
+ data-pptx-editable="false"
+ x="0" y="0" width="1280" height="720" fill="#FFFFFF"/>
+
+ <g id="layout-header"
+ data-pptx-layer="layout"
+ data-pptx-editable="false">
+ <!-- Complete reusable header drawing remains here. -->
+ </g>
+
+ <!-- Placeholder identity is already sufficient; no generic title role. -->
+ <text id="title-slot" data-pptx-placeholder="title"
+ x="72" y="92" font-size="32" fill="#172033">{{PAGE_TITLE}}</text>
+
+ <!-- Logo has no specialized marker, so the minimal structural hint is useful. -->
+ <text id="brand-mark" data-pptx-role="logo"
+ x="1180" y="46" text-anchor="end">ACME</text>
+
+ <!-- The placeholder already owns slide-number behavior; do not add a role. -->
+ <text id="page-number" data-pptx-placeholder="slide-number"
+ x="1200" y="680" text-anchor="end">7</text>
+</svg>
+```
+
+## 4. Validation and Compatibility
+
+The quality checker validates marker placement, canonical values, and stable
+unique IDs. Baseline export consumes explicit markers before compatibility
+heuristics:
+
+- root page role is preferred over filename-based Layout classification;
+- `data-pptx-placeholder="slide-number"` is preferred over a generic role or id;
+- explicit structural role is preferred over id-token chrome detection;
+- animation target scanning uses the structural role before id-token fallback.
+
+Filename and id heuristics remain compatibility fallbacks only for older SVGs
+that lack the corresponding marker. A canonical page role is authoritative over
+the filename. Any explicit structural role prevents id-based reinterpretation;
+an unknown role remains renderable but produces a quality-check warning.
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index 924a0bf0..1decf297 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -180,6 +180,18 @@ One offending character invalidates the file and aborts export. Numeric refs (`&
**Hard rule — page-design closure**: A final page SVG is the sole visual/design authority for that page on every SVG-authoring route. SVG is not the authority for the entire PPTX package.
+### 4.1 Semantic SVG Marker Contract
+
+Semantic markers are minimal compiler hints orthogonal to native SVG semantics.
+Existing `data-pptx-layout` / layer / placeholder / native-object metadata is
+authoritative and read first. A `baseline` / free-design root declares
+`data-pptx-page-role`; template/preserve roots already declare their Layout.
+Add `data-pptx-role` only when no specialized marker expresses the required
+page-frame behavior; the element also uses a stable unique `id`. Do not classify
+ordinary page content or move visible facts out of SVG attributes/text into
+metadata. See
+[`semantic-svg.md`](semantic-svg.md) for the canonical vocabulary and examples.
+
- **viewBox** MUST match the canvas dimensions; it is the single source of truth for canvas size. Root `width`/`height` are optional compatibility attributes and are not used as PPT Master canvas authority.
- **Background**: Use `<rect>` to define the page background color
- **`<tspan>`** has two purposes: (1) manual line breaks (use `dy` or explicit `y`); (2) inline run formatting on the same line (color/weight/size). `<foreignObject>` is FORBIDDEN. See "Single logical line" rule below.
@@ -264,9 +276,9 @@ Wrap logically related elements in top-level `<g id="...">` groups. Produces Pow
**Animation-ready rule**: direct children of `<svg>` should be semantic groups, not raw drawing atoms. Aim for **3–8 top-level content `<g id>` groups per slide** (the 3–8 budget excludes page chrome — see below); each content group becomes one entrance step under the chosen `--animation-trigger` mode (one click in `on-click`, one cascade slot in `after-previous`, parallel in `with-previous`).
-**Chrome groups are excluded automatically.** The exporter treats top-level groups whose id contains chrome tokens as page chrome and skips them in the animation sequence — they appear together with the slide. Tokens (matched against id after splitting on `-` / `_`): `background`, `bg`, `decoration` / `decorations` / `decor`, `header`, `footer`, `chrome`, `watermark`, `pagenumber` / `pagenum` / `page-number`, `nav`, `logo`, `rule`. So `<g id="bg-texture">`, `<g id="cover-footer">`, `<g id="p03-header">`, `<g id="bottom-decor">`, `<g id="nav">`, `<g id="logo-area">`, `<g id="column-rule">` all skip animation while keeping their `<g>` wrapper for editing/grouping. Use these naming conventions for chrome — do **not** strip the `<g>` wrapper.
+**Chrome groups are excluded automatically.** Existing `data-pptx-layer` and `data-pptx-placeholder="slide-number"` semantics are read first. Otherwise, explicit `data-pptx-role` values `background`, `decoration`, `header`, `footer`, `chrome`, `watermark`, `page-number`, and `logo` identify static page framing. For marker-free legacy SVGs, ids remain a compatibility fallback using these tokens after splitting on `-` / `_`: `background`, `bg`, `decoration` / `decorations` / `decor`, `header`, `footer`, `chrome`, `watermark`, `pagenumber` / `pagenum` / `page-number`, `nav`, `logo`, `rule`. Keep the `<g>` wrapper for editing/grouping.
-These ids also drive slide-master promotion in the default native export: `logo` / `footer` / `header` / `watermark` / `chrome` / `pageNumber` chrome that is drawn **before** content and repeated **verbatim** across pages moves into the slide master (pages without it, like covers, are isolated automatically), and a `pageNumber` text whose content is exactly the page's display number becomes a self-renumbering PowerPoint field.
+Minimal structural roles also drive slide-master promotion in the default native export: `logo` / `footer` / `header` / `watermark` / `chrome` elements drawn **before** content and repeated **verbatim** across pages may move into the slide master (pages without them, like covers, are isolated automatically). A `data-pptx-placeholder="slide-number"` text, or a free-design `data-pptx-role="page-number"` text, whose content exactly equals the page's display number becomes a self-renumbering PowerPoint field. Exact id tokens remain a fallback only when specialized/minimal markers are absent.
**What to group**:
@@ -941,13 +953,18 @@ steal plot area in PPT. Add `show_legend: true` only when the legend is needed;
Native `baseline` export assigns layout families after every SVG page has been
converted. This package-only pass does not change SVG authoring or live preview.
-| Filename evidence | Output layout |
+| Root `data-pptx-page-role` | Output layout |
|---|---|
-| `cover`, `frontcover`, `封面` | `Cover` |
-| `agenda`, `contents`, `outline`, `toc`, `目录`, `议程` | `Agenda` |
-| `chapter`, `divider`, `section`, `transition`, `章节`, `过渡页` | `Section` |
-| `closing`, `end`, `ending`, `qa`, `thankyou`, `thanks`, `封底`, `结束`, `结尾`, `结语`, `致谢`, `谢谢` | `Closing` |
-| No exact role token | `Content` |
+| `cover` | `Cover` |
+| `toc` | `Agenda` |
+| `section` | `Section` |
+| `ending` | `Closing` |
+| `content` | `Content` |
+
+Marker-free legacy SVGs retain conservative filename-token fallback: explicit
+cover / agenda / section / closing tokens select those families, and every
+other page becomes `Content`. When a valid root marker exists, it is
+authoritative even if the filename suggests another family.
Keep an existing `Cover` assignment when the Master chrome safety pass already
used it to hide promoted Master shapes from a minority page.
@@ -962,8 +979,9 @@ keep each background on its Slide. Preserve whether each family shows or hides
the parent Master shape tree.
**Layout chrome rule**: After family assignment, move only the identical
-leading prefix of explicitly named chrome (`logo`, `footer`, `header`,
-`watermark`, `chrome`) carried by every family member. Generated OOXML and
+leading prefix of explicitly marked chrome (`logo`, `footer`, `header`,
+`watermark`, `chrome`) carried by every family member. Legacy id tokens are
+consulted only when `data-pptx-role` is absent. Generated OOXML and
image relationships must match exactly, no animation may target the shapes,
and moving them behind Slide content must preserve z-order. Keep page numbers
and every non-identical object Slide-local.
diff --git a/skills/ppt-master/references/template-designer.md b/skills/ppt-master/references/template-designer.md
index a87e477b..8a537575 100644
--- a/skills/ppt-master/references/template-designer.md
+++ b/skills/ppt-master/references/template-designer.md
@@ -104,7 +104,7 @@ When the brief sets `Replication mode: mirror`, preserve literal page appearance
- Visual source: `<import_workspace>/svg-flat/slide_NN.svg` (the self-contained "what PowerPoint shows" view). Structural source: `svg/master_*.svg`, `svg/layout_*.svg`, and `svg/inheritance.json`.
- Output: `templates/<kind_dir>/<template_id>/<NNN>_<page_type>.svg`, where `<NNN>` is the zero-padded source slide index (3 digits) and `<page_type>` is derived from `manifest.json` `pageTypeCandidates` — `cover` / `toc` / `chapter` / `content` / `ending`. When the page-type heuristic is ambiguous, fall back to `content`. Preserve source slide order via the numeric prefix.
-- Required metadata rewrite: declare the output Layout on the root, mark inherited Master/Layout visuals as direct preview layers, and map source content slots to semantic `data-pptx-placeholder` markers where the imported contract exposes them.
+- Required metadata rewrite: declare the output Layout on the root, mark inherited Master/Layout visuals as direct preview layers, and map source content slots to semantic `data-pptx-placeholder` markers where the imported contract exposes them. Add `data-pptx-role` only to structural page-frame objects whose behavior is not already expressed by those specialized markers.
- Other allowed modifications: rewrite `<image href="...">` paths to local assets and rename assets semantically. Keep geometry, decoration, sprite-sheet wrappers, original example text, chart previews, and fonts visually unchanged.
- Forbidden: simplifying decorative complexity, merging similar slides, or dropping inherited preview chrome.
- `design_spec.md` §V Page Roster lists every emitted file with a one-line content-fit description; SVG metadata owns native reconstruction.
@@ -247,10 +247,11 @@ Do not:
| Rebuilt master/layout visual | Direct preview child with `data-pptx-layer="master|layout"` and `data-pptx-editable="false"` |
| Semantic content slot | Direct content child with `data-pptx-placeholder`; add `data-pptx-placeholder-idx` when same-role slots require stable disambiguation |
| Page-only background | Direct full-canvas solid rect with `data-pptx-layer="slide"` |
+| Structural page-frame hint | Optional `data-pptx-role` only when background/decoration/header/footer/logo/watermark/chrome/page-number behavior is not already expressed by layer/placeholder metadata; stable unique `id` required |
Repeat inherited visuals in every standalone SVG so browser preview remains complete. Template export validates their equality, moves one copy into the generated Master/Layout parts, and removes the repeated Slide copies. Do not flatten inherited visuals into unmarked slide content.
-Use the imported semantic roles verbatim: `title`, `subtitle`, `body`,
+Use the imported placeholder types verbatim: `title`, `subtitle`, `body`,
`picture`, `chart`, `table`, `object`, `media`, `date`, `footer`, and
`slide-number`. In particular, do not collapse source `subTitle`, `obj`,
`media`, or `dt` placeholders into a generic body marker. A reconstructed
@@ -265,13 +266,16 @@ Use clear placeholder markers for replaceable content:
```xml
<!-- Text placeholder -->
-<text x="80" y="320" fill="#FFFFFF" font-size="48" font-weight="bold">
+<text id="title-slot" data-pptx-placeholder="title"
+ x="80" y="320" fill="#FFFFFF" font-size="48" font-weight="bold">
{{TITLE}}
</text>
<!-- Content area placeholder (content page only) -->
<rect x="40" y="90" width="1200" height="550" fill="#FFFFFF" rx="8"/>
-<text x="640" y="365" text-anchor="middle" fill="#CBD5E1" font-size="16">
+<text id="body-slot" data-pptx-placeholder="body"
+ data-pptx-placeholder-bounds="40 90 1200 550"
+ x="640" y="365" text-anchor="middle" fill="#CBD5E1" font-size="16">
{{CONTENT_AREA}}
</text>
```
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 07805b14..9fef3b2f 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -118,7 +118,7 @@ python3 scripts/svg_to_pptx.py <project_path>
For SVG-authoring routes, `svg_output/` is the complete visible page-design source: every exported text, image, shape, background, and template-derived layout element is present in the page SVG or explicitly referenced by it. Export may translate represented content into Master/Layout/Slide parts or native objects, but it does not retrieve missing visible content from templates or planning files. Speaker notes, animation, narration, transitions, `template-fill-pptx`, and `native-enhance-pptx` remain separately owned capabilities.
-When `spec_lock.md` has no `pptx_structure` section, native `svg_to_pptx.py` falls back to `baseline`: the generated deck keeps a standard Master/Layout relationship and promotes only exact, z-order-safe shared backgrounds/chrome. It then assigns filename-backed `Cover`, `Agenda`, `Section`, `Closing`, or fallback `Content` layouts. A family-wide exact background and an exact leading chrome prefix may move into that Layout; actual titles, body content, pictures, charts, tables, page numbers, and page-specific shapes remain on Slide. No visual-similarity or placeholder inference is performed. Baseline also prunes unused layouts and maps locked typography/colors into the PowerPoint theme. Use `--pptx-structure flat` for slide-local diagnostics.
+When `spec_lock.md` has no `pptx_structure` section, native `svg_to_pptx.py` falls back to `baseline`: the generated deck keeps a standard Master/Layout relationship and promotes only exact, z-order-safe shared backgrounds/chrome. Root `data-pptx-page-role` selects `Cover`, `Agenda`, `Section`, `Closing`, or `Content`; filenames are a fallback for marker-free legacy SVGs. A family-wide exact background and an exact leading structurally marked chrome prefix may move into that Layout; ids are consulted only when the structural role is absent. Actual titles, body content, pictures, charts, tables, page numbers, and page-specific shapes remain on Slide. No visual-similarity or placeholder inference is performed. Baseline also prunes unused layouts and maps locked typography/colors into the PowerPoint theme. Use `--pptx-structure flat` for slide-local diagnostics.
Deck/layout template routes use explicit template structure. Each complete SVG names its output Layout, repeats inherited Master/Layout preview layers, and marks supported content placeholders. Strict keeps the selected Layout contract; adaptive may create a new Layout while retaining the Master. The exporter validates cross-slide equality, creates one reusable Layout per key, removes repeated inherited copies, and keeps actual content Slide-local. The complete contract lives in [`references/shared-standards.md`](../references/shared-standards.md#explicit-pptx-master--layout--placeholder-metadata-template-export).
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 64975f6f..a82b9a94 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -67,7 +67,7 @@ Behavior:
inputs and package-level processing.
- For PPTX template-import workspaces, use `-s svg-flat` when you need a visual round-trip check. The layered `svg/` tree is the machine-readable template source and intentionally does not inline inherited master / layout decoration into each slide.
- Native mode is strict about unsupported visual SVG elements: if a visual element cannot be represented or safely preserved, export fails with the SVG file, element tag, and position instead of silently dropping content.
-- Omitting `--pptx-structure` reads `spec_lock.md` and falls back to `baseline`. Baseline assigns filename-backed layout families, keeps content Slide-local, and promotes only exact family-wide backgrounds plus exact leading named chrome; it never infers placeholders or visual similarity. Template mode builds reusable PowerPoint structure only from explicit SVG metadata and validates every `pptx_layouts` row plus cross-slide equality. Both strict and adaptive template adherence use this mode; adaptive may introduce a new Layout key under the same Master.
+- Omitting `--pptx-structure` reads `spec_lock.md` and falls back to `baseline`. Baseline assigns Layout families from root `data-pptx-page-role`, keeps content Slide-local, and promotes only exact family-wide backgrounds plus exact leading structurally marked chrome; filenames and ids are compatibility fallbacks for marker-free legacy SVGs. It never infers placeholders or visual similarity. Template mode builds reusable PowerPoint structure only from explicit SVG metadata and validates every `pptx_layouts` row plus cross-slide equality. Both strict and adaptive template adherence use this mode; adaptive may introduce a new Layout key under the same Master.
- Template/preserve placeholder semantics distinguish title, subtitle, body, picture, chart, table, generic object, media, date, footer, and slide number. Reconstructed titles are normally type-matched without an index; explicit imported title indices and all other source indices are retained. Imported `subTitle`, `obj`, `media`, and `dt` identities remain distinct through `manifest.json`, `native_structure.json`, Layout XML, and Slide XML.
- Baseline/template native export reads `spec_lock.md` typography into the PowerPoint theme: `title_family` becomes the major font and `body_family` / `font_family` becomes the minor font. Matching SVG text emits `+mj-*` / `+mn-*` tokens, while unrelated emphasis/code/brand families stay concrete. Preserve mode keeps the imported source theme; flat mode keeps fixed-font diagnostic output.
- Baseline/template native export also maps canonical `spec_lock.md` color roles into the PowerPoint color scheme and emits context-safe `schemeClr` tokens for exact matches in SVG fills/text/strokes, gradients/patterns/bullets, native tables, and native-chart accent series. Local colors, inverse white/black, and effects stay concrete. Preserve mode keeps the imported source color scheme; flat mode keeps fixed-color diagnostic output.
@@ -88,7 +88,7 @@ Behavior:
- Long-audio import and automatic long-audio splitting are not supported; keep narration assets page-level
- Voice choices can be listed with `python3 scripts/notes_to_audio.py --list-common-voices`, `python3 scripts/notes_to_audio.py --list-voices --locale zh-CN`, or provider-specific `--provider <name> --list-voices`
- Page transitions are controlled by `-t/--transition`; per-element entrance animations are controlled by `-a/--animation`
-- Per-element animation applies to top-level SVG `<g id="...">` groups in z-order; aim for 3–8 content groups per slide. Page chrome (background / header / footer / decorations / watermark / page number, by id token) is skipped automatically
+- Per-element animation applies to top-level SVG `<g id="...">` groups in z-order; aim for 3–8 content groups per slide. Existing layer/slide-number placeholder semantics are read before minimal structural roles; exact id tokens remain a fallback only when all explicit markers are absent
- Start mode is set by `--animation-trigger`, mirroring PowerPoint's Start dropdown: `after-previous` (default, cascade with `--animation-stagger` spacing on slide entry), `on-click` (presenter-paced), `with-previous` (all together on slide entry)
- `on-click` is for live presentations only; recorded narration rejects it because the tool does not generate object-level click timings
- Flat SVG roots without top-level groups fall back to at most 8 visible primitives; beyond that, animation is skipped on the slide
diff --git "a/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/01_cover.svg" "b/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/01_cover.svg"
index 36a5db06..bfe13501 100644
--- "a/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/01_cover.svg"
+++ "b/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/01_cover.svg"
@@ -8,7 +8,7 @@
<!-- 背景层 - 使用封面背景图(AI生成或用户提供) -->
<image href="../images/{{COVER_BG_IMAGE}}" x="0" y="0" width="1280" height="720"
- preserveAspectRatio="xMidYMid slice" />
+ preserveAspectRatio="xMidYMid slice" id="semantic-01_cover-background-1" data-pptx-role="background" />
<!-- 半透明遮罩层 - 增强文字可读性 -->
<rect id="cover-overlay" x="0" y="0" width="1280" height="720"
@@ -19,7 +19,7 @@
<!-- 大型Logo - 居中偏上 -->
<image href="../images/{{LOGO_LARGE}}" x="344" y="120" width="592" height="238"
- preserveAspectRatio="xMidYMid meet" />
+ preserveAspectRatio="xMidYMid meet" id="semantic-01_cover-logo-1" data-pptx-role="logo" />
<!-- 主标题区域 -->
<text x="640" y="440" text-anchor="middle" font-family="Microsoft YaHei, SimHei, sans-serif" font-size="48"
diff --git "a/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/02_toc.svg" "b/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/02_toc.svg"
index ae3f5d63..573ef4a8 100644
--- "a/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/02_toc.svg"
+++ "b/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/02_toc.svg"
@@ -12,7 +12,7 @@
<rect x="60" y="30" width="50" height="50" fill="#004098"/>
<text x="85" y="65" text-anchor="middle" font-family="Arial, sans-serif" font-size="24" font-weight="bold" fill="#FFFFFF">目</text>
<text x="130" y="65" font-family="Microsoft YaHei, SimHei, sans-serif" font-size="28" font-weight="bold" fill="#333333">目 录</text>
- <image href="../images/{{LOGO_HEADER}}" x="1107" y="30" width="113" height="50" preserveAspectRatio="xMidYMid meet"/>
+ <image href="../images/{{LOGO_HEADER}}" x="1107" y="30" width="113" height="50" preserveAspectRatio="xMidYMid meet" id="semantic-02_toc-logo-1" data-pptx-role="logo"/>
<!-- 左侧装饰竖线 -->
<rect x="300" y="140" width="4" height="480" fill="#004098"/>
diff --git "a/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/03_content.svg" "b/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/03_content.svg"
index 24cfefc9..2ed8376f 100644
--- "a/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/03_content.svg"
+++ "b/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/03_content.svg"
@@ -20,7 +20,7 @@
<!-- 右上角Logo -->
<image href="../images/{{LOGO_HEADER}}" x="1107" y="30" width="113" height="50"
- preserveAspectRatio="xMidYMid meet" />
+ preserveAspectRatio="xMidYMid meet" id="semantic-03_content-logo-1" data-pptx-role="logo" />
<!-- 内容区域 - 灵活布局,由 Executor 根据实际内容自由设计 -->
<!-- 可使用的布局模式:
diff --git "a/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/04_ending.svg" "b/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/04_ending.svg"
index d4f9ccfc..1fddae3f 100644
--- "a/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/04_ending.svg"
+++ "b/skills/ppt-master/templates/decks/\344\270\255\346\261\275\347\240\224/04_ending.svg"
@@ -23,7 +23,7 @@
<!-- 大型Logo - 居中 -->
<image href="../images/{{LOGO_LARGE}}" x="344" y="160" width="592" height="238"
- preserveAspectRatio="xMidYMid meet" />
+ preserveAspectRatio="xMidYMid meet" id="semantic-04_ending-logo-1" data-pptx-role="logo" />
<!-- 感谢语(中文) -->
<text x="640" y="480" text-anchor="middle" font-family="Microsoft YaHei, SimHei, sans-serif" font-size="56"
diff --git a/skills/ppt-master/templates/layouts/academic_defense/01_cover.svg b/skills/ppt-master/templates/layouts/academic_defense/01_cover.svg
index 4f93a298..07b45bd4 100644
--- a/skills/ppt-master/templates/layouts/academic_defense/01_cover.svg
+++ b/skills/ppt-master/templates/layouts/academic_defense/01_cover.svg
@@ -11,7 +11,7 @@
<!-- 右上角 Logo 区域占位 -->
<rect x="1080" y="25" width="160" height="50" fill="none" stroke="#FFFFFF" stroke-width="1" stroke-opacity="0.3" rx="4"/>
- <text x="1160" y="58" text-anchor="middle" fill="#FFFFFF" font-family="Microsoft YaHei, Arial, sans-serif" font-size="18" font-weight="bold">
+ <text x="1160" y="58" text-anchor="middle" fill="#FFFFFF" font-family="Microsoft YaHei, Arial, sans-serif" font-size="18" font-weight="bold" id="semantic-01_cover-logo-1" data-pptx-role="logo">
{{LOGO}}
</text>
diff --git a/skills/ppt-master/templates/layouts/academic_defense/02_toc.svg b/skills/ppt-master/templates/layouts/academic_defense/02_toc.svg
index dc374b0c..4301801d 100644
--- a/skills/ppt-master/templates/layouts/academic_defense/02_toc.svg
+++ b/skills/ppt-master/templates/layouts/academic_defense/02_toc.svg
@@ -13,7 +13,7 @@
</text>
<!-- 右上角 Logo -->
- <text x="1200" y="46" text-anchor="end" fill="#FFFFFF" font-family="Microsoft YaHei, Arial, sans-serif" font-size="18" font-weight="bold">
+ <text x="1200" y="46" text-anchor="end" fill="#FFFFFF" font-family="Microsoft YaHei, Arial, sans-serif" font-size="18" font-weight="bold" id="semantic-02_toc-logo-1" data-pptx-role="logo">
{{LOGO}}
</text>
diff --git a/skills/ppt-master/templates/layouts/academic_defense/03_content.svg b/skills/ppt-master/templates/layouts/academic_defense/03_content.svg
index 7c7ce0ae..7180d958 100644
--- a/skills/ppt-master/templates/layouts/academic_defense/03_content.svg
+++ b/skills/ppt-master/templates/layouts/academic_defense/03_content.svg
@@ -16,7 +16,7 @@
<!-- 右上角 Logo -->
<rect x="1100" y="20" width="140" height="30" fill="none"/>
- <text x="1220" y="46" text-anchor="end" fill="#FFFFFF" font-family="Microsoft YaHei, Arial, sans-serif" font-size="18" font-weight="bold">
+ <text x="1220" y="46" text-anchor="end" fill="#FFFFFF" font-family="Microsoft YaHei, Arial, sans-serif" font-size="18" font-weight="bold" id="semantic-03_content-logo-1" data-pptx-role="logo">
{{LOGO}}
</text>
diff --git a/skills/ppt-master/templates/layouts/academic_defense/04_ending.svg b/skills/ppt-master/templates/layouts/academic_defense/04_ending.svg
index 88659b02..75047dbc 100644
--- a/skills/ppt-master/templates/layouts/academic_defense/04_ending.svg
+++ b/skills/ppt-master/templates/layouts/academic_defense/04_ending.svg
@@ -8,7 +8,7 @@
<rect x="0" y="0" width="6" height="100" fill="#CC0000"/>
<!-- 右上角 Logo -->
- <text x="1200" y="58" text-anchor="end" fill="#FFFFFF" font-family="Microsoft YaHei, Arial, sans-serif" font-size="18" font-weight="bold">
+ <text x="1200" y="58" text-anchor="end" fill="#FFFFFF" font-family="Microsoft YaHei, Arial, sans-serif" font-size="18" font-weight="bold" id="semantic-04_ending-logo-1" data-pptx-role="logo">
{{LOGO}}
</text>
diff --git a/skills/ppt-master/templates/layouts/medical_university/01_cover.svg b/skills/ppt-master/templates/layouts/medical_university/01_cover.svg
index ce54ef3e..ca1c3df5 100644
--- a/skills/ppt-master/templates/layouts/medical_university/01_cover.svg
+++ b/skills/ppt-master/templates/layouts/medical_university/01_cover.svg
@@ -17,7 +17,7 @@
<rect x="1080" y="25" width="160" height="50" fill="none" stroke="#FFFFFF" stroke-width="1" stroke-opacity="0.3"
rx="4" />
<text x="1160" y="58" text-anchor="middle" fill="#FFFFFF" font-family="Microsoft YaHei, Arial, sans-serif"
- font-size="16" font-weight="bold">
+ font-size="16" font-weight="bold" id="semantic-01_cover-logo-1" data-pptx-role="logo">
{{LOGO}}
</text>
diff --git a/skills/ppt-master/templates/layouts/medical_university/02_toc.svg b/skills/ppt-master/templates/layouts/medical_university/02_toc.svg
index 86117e6d..a74ab669 100644
--- a/skills/ppt-master/templates/layouts/medical_university/02_toc.svg
+++ b/skills/ppt-master/templates/layouts/medical_university/02_toc.svg
@@ -21,7 +21,7 @@
<!-- 右上角 Logo -->
<text x="1200" y="46" text-anchor="end" fill="#FFFFFF" font-family="Microsoft YaHei, Arial, sans-serif"
- font-size="16" font-weight="bold">
+ font-size="16" font-weight="bold" id="semantic-02_toc-logo-1" data-pptx-role="logo">
{{LOGO}}
</text>
diff --git a/skills/ppt-master/templates/layouts/medical_university/03_content.svg b/skills/ppt-master/templates/layouts/medical_university/03_content.svg
index a5cb8ecb..fde25a1a 100644
--- a/skills/ppt-master/templates/layouts/medical_university/03_content.svg
+++ b/skills/ppt-master/templates/layouts/medical_university/03_content.svg
@@ -18,7 +18,7 @@
<!-- 右上角 Logo -->
<rect x="1100" y="20" width="140" height="30" fill="none" />
<text x="1220" y="46" text-anchor="end" fill="#FFFFFF" font-family="Microsoft YaHei, Arial, sans-serif"
- font-size="16" font-weight="bold">
+ font-size="16" font-weight="bold" id="semantic-03_content-logo-1" data-pptx-role="logo">
{{LOGO}}
</text>
diff --git a/skills/ppt-master/templates/layouts/medical_university/04_ending.svg b/skills/ppt-master/templates/layouts/medical_university/04_ending.svg
index fe7776df..beceadbf 100644
--- a/skills/ppt-master/templates/layouts/medical_university/04_ending.svg
+++ b/skills/ppt-master/templates/layouts/medical_university/04_ending.svg
@@ -13,7 +13,7 @@
<!-- 右上角 Logo -->
<text x="1200" y="58" text-anchor="end" fill="#FFFFFF" font-family="Microsoft YaHei, Arial, sans-serif"
- font-size="16" font-weight="bold">
+ font-size="16" font-weight="bold" id="semantic-04_ending-logo-1" data-pptx-role="logo">
{{LOGO}}
</text>
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index b93d6bbb..f44f25d9 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -134,7 +134,7 @@
> ```
> Omit the row for free design and brand-only templates. Both values require one `page_layouts` and one `pptx_layouts` row per page. `strict` keeps the selected Layout contract; `adaptive` may create a new explicit Layout under the same template Master.
>
-> - `baseline` — default for free design and brand-only routes. Preserve conservative shared Master/background/chrome behavior, then assign filename-backed Cover/Agenda/Section/Closing/Content layouts. It may also promote exact family-wide leading chrome into a Layout. Actual content stays slide-local; no placeholders or visual-similarity inference are authored.
+> - `baseline` — default for free design and brand-only routes. Preserve conservative shared Master/background/chrome behavior, then assign Cover/Agenda/Section/Closing/Content from root `data-pptx-page-role`. It may also promote exact family-wide leading structurally marked chrome into a Layout. Marker-free legacy SVGs retain filename/id fallback. Actual content stays slide-local; no placeholders or visual-similarity inference are authored.
> - `template` — required whenever Step 3 loaded a deck/layout template. Requires complete `page_layouts` and `pptx_layouts` sections plus explicit SVG structure metadata on every generated page.
> - `preserve` — legacy strict-only compatibility for an existing project that already ships `native_structure.json` + `source_template.pptx`. Do not select it for newly created templates.
> - `flat` — diagnostic escape hatch. Do not lock this in a normal project; pass it on the CLI when comparing slide-local output.
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index 18b79dc1..e4f3052c 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -302,7 +302,7 @@ For type D, pass only the finalized brief.
The role uses the analysis bundle to anchor objective facts such as theme colors, fonts, reusable backgrounds, common branding assets, layout grammar, image-placement rules, density rhythm, and page-slot semantics, then rebuilds the final SVG templates in a simplified, maintainable form.
-**Native structure reconstruction**: Do not copy `native_structure.json` or `source_template.pptx` into the final template directory. Use their master/layout/placeholder facts to reconstruct one clean Master plus semantic Layouts through the explicit SVG metadata contract. Every emitted SVG is a complete standalone preview: repeat the identical Master layer, repeat the selected Layout layer for pages sharing a key, and keep actual content on the Slide with semantic placeholder markers.
+**Native structure reconstruction**: Do not copy `native_structure.json` or `source_template.pptx` into the final template directory. Use their master/layout/placeholder facts to reconstruct one clean Master plus semantic Layouts through the explicit SVG metadata contract. Every emitted SVG is a complete standalone preview: declare its output Layout, repeat the identical Master layer, repeat the selected Layout layer for pages sharing a key, and keep actual content on the Slide with semantic placeholder markers. Add `data-pptx-role` only to structural page-frame objects whose package/page-number/animation behavior is not already expressed by specialized metadata; do not classify ordinary template content.
Downstream, both template-adherence choices stay on `pptx_structure.mode: template`. `strict` preserves the selected template Layout contract. `adaptive` still references one template SVG per page, keeps the same Master contract, and may author a new explicit Layout key when the source roster has no suitable composition. It never falls back to baseline inside a template deck.
@@ -331,7 +331,7 @@ Mirror mode does not simplify the visual page, but it still reconstructs layer o
1. `design_spec.md` — **personality only**. Required sections: Template Overview, Color Scheme, Signature Design Elements, Page Roster (matching the actual SVG files on disk). Skip Typography / Assets / Placeholder Overrides when they would just restate defaults. Declare brief frontmatter for `register_template.py`. **Do not** restate generic SVG constraints, layout pattern libraries, font-size ratio bands, the canonical placeholder table, or content methodology — those are sourced from `shared-standards.md` / `design_spec_reference.md` / `strategist.md` and are already in the downstream reader's context. Full scope rule and skeleton: [template-designer.md §1](../references/template-designer.md#1-must-generate-design_specmd).
2. Page roster — see [Page Roster](../references/template-designer.md#page-roster) for `standard` / `fidelity` / `mirror` mode rosters, variant naming, and TOC handling
3. Placeholder vocabulary — pages should adopt the conventional names (`{{TITLE}}`, `{{CONTENT_AREA}}`, ...) when they fit. Full reference: [Placeholder Reference](../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template). When a template style legitimately needs different vocabulary (consulting → `{{KEY_MESSAGE}}`, branded cover → `{{BRAND_LOGO}}`), declare a `placeholders:` block in `design_spec.md` frontmatter so the registrar and quality checker treat it as the template's authoritative contract. **Avoid** one-off indexed families such as `{{CHAPTER_01_TITLE}}` — use the indexed TOC pattern instead.
- - `{{...}}` placeholders are the authoring vocabulary used to generate final slide content. Each emitted SVG also carries the native reconstruction contract: root `data-pptx-layout` / `data-pptx-layout-name`, direct Master/Layout layers, and direct semantic `data-pptx-placeholder` markers. Both strict and adaptive downstream use set `mode: template` and require `page_layouts` plus `pptx_layouts` for every page.
+ - `{{...}}` placeholders are the authoring vocabulary used to generate final slide content. Each emitted SVG also carries the native reconstruction contract: root `data-pptx-layout` / `data-pptx-layout-name`, direct Master/Layout layers, and direct semantic `data-pptx-placeholder` markers. Minimal structural `data-pptx-role` hints are added only when those specialized markers cannot express required behavior. Both strict and adaptive downstream use set `mode: template` and require `page_layouts` plus `pptx_layouts` for every page.
4. Template assets (optional) — Logos / PNG / JPG / reference SVG bundled with the template package
---
@@ -369,7 +369,7 @@ python3 skills/ppt-master/scripts/svg_quality_checker.py "skills/ppt-master/temp
- [ ] Placeholder names follow the canonical convention where applicable; templates with intentionally different vocabularies (e.g. `{{KEY_MESSAGE}}` instead of `{{PAGE_TITLE}}`) should declare a `placeholders:` frontmatter block to silence advisory warnings
- [ ] Asset files referenced by SVGs actually exist in the template package
- [ ] `design_spec.md` frontmatter declares `native_structure_mode: template`; no `native_structure.json` or `source_template.pptx` is packaged
-- [ ] Every SVG root declares `data-pptx-layout` and `data-pptx-layout-name`; direct Master/Layout elements and semantic placeholders obey the explicit paint-order contract
+- [ ] Every SVG root declares `data-pptx-layout` and `data-pptx-layout-name`; direct Master/Layout elements and semantic placeholders obey the explicit paint-order contract. Structural `data-pptx-role` is used only when specialized metadata cannot express required package/page-number/animation behavior
- [ ] If any SVG references an extracted vector `data-icon`, the corresponding SVG asset exists directly under the package's `icons/` directory; do not add a separate illustration embedding script
- [ ] For `fidelity` mode: every sprite-sheet asset retains its nested `<svg viewBox=...>` crop wrapper; no image whose file aspect differs from its on-page aspect was flattened to a bare `<image>`
- [ ] For `mirror` mode: file count equals source page count (type A: `ls templates/<kind_dir>/<id>/*_*.svg | wc -l` matches the cleaned flat `<import_workspace>/svg-flat/slide_*.svg | wc -l`; type B: matches the source SVG count); filenames follow the `<NNN>_<page_type>.svg` convention; **no `{{...}}` placeholder strings appear in any copied SVG** (`grep -l "{{" templates/<kind_dir>/<id>/*.svg` should return nothing — if the type B source itself contains placeholders, the user should be in `standard` mode, not `mirror`); §V Page Roster in `design_spec.md` lists every emitted file with a one-line description of what the page contains and what content slot it suits