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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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 --daemonEach 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:```bashpython3 ${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.mdindex 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.mdnew file mode 100644index 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.mdindex 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 beenconverted. 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 alreadyused 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 hidesthe 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 andimage relationships must match exactly, no animation may target the shapes,and moving them behind Slide content must preserve z-order. Keep page numbersand every non-identical object Slide-local.diff --git a/skills/ppt-master/references/template-designer.md b/skills/ppt-master/references/template-designer.mdindex 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.mdindex 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.mdindex 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 slidediff --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.svgindex 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.svgindex 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.svgindex 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.svgindex 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.svgindex 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.svgindex 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.svgindex 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.svgindex 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.mdindex 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.mdindex 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 o1. `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 handling3. 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