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

feat(pptx-layouts): register complete reusable structure

hugohe371f0fda2f375
diff --git a/docs/roadmap.md b/docs/roadmap.md
index e1044cd1..0a29c285 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -84,7 +84,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 + mode-specific template creation** — deck/layout-template SVG pages declare their final Master/Layout identity while they are authored. Fixed Master/Layout visuals are root-level atoms, reusable slots are bounded top-level groups with real carriers or an explicit composite proxy, and zero-slot Layouts remain valid. Structured export deterministically compiles only that contract and performs final package read-back; it never promotes repeated chrome or infers placeholders. Flat free-design/brand-only export keeps all content Slide-local while replacing the stock Office scaffold with one clean project-owned Master and Blank Layout plus a deck-named current-lock theme. It removes title/body and other stock content, prunes unused Layouts, and retains only the standard date/footer/slide-number capability hooks. Both generated routes write locked title/body sizes into Master `p:txStyles`. `standard` / `fidelity` author new SVG rosters and new Master/Layout systems without preserving or distilling source topology. `mirror` restores source page order, Master/Layout identities and parentage, placeholder facts, and supported visuals without semantic synthesis; fixed-layer source groups are mechanically expanded into direct atoms. Lossless imports stay in analysis and lightweight projections stay inspection-only. Library and project outputs share required `templates/`, optional `images/` / `icons/`, and optional on-demand review output in `exports/`; only library registration differs. Legacy baseline/template/preserve SVG packages first run `restore-pptx-structure`. Raw one-off PPTX filling remains `template-fill-pptx`.
+- **Native package structure + mode-specific template creation** — deck/layout-template SVG pages declare their final Master/Layout identity while they are authored. Fixed Master/Layout visuals are root-level atoms, reusable slots are bounded top-level groups with real carriers or an explicit composite proxy, and zero-slot Layouts remain valid. Structured export deterministically compiles only that contract and performs final package read-back; it never promotes repeated chrome or infers placeholders. Flat free-design/brand-only export keeps all content Slide-local while replacing the stock Office scaffold with one clean project-owned Master and Blank Layout plus a deck-named current-lock theme. It removes title/body and other stock content, prunes unused Layouts, and retains only the standard date/footer/slide-number capability hooks. Both generated routes write the locked title plus a deterministic nine-level body hierarchy into Master `p:txStyles`, preserving paragraph and bullet settings. `standard` / `fidelity` author new SVG rosters and new Master/Layout systems without preserving or distilling source topology. `mirror` restores the complete supported source graph—including definition-only prototypes for unused Layouts—without semantic synthesis; fixed-layer source groups are mechanically expanded into direct atoms. Lossless imports stay in analysis and lightweight projections stay inspection-only. Library and project outputs share required `templates/`, optional `images/` / `icons/`, and optional on-demand review output in `exports/`; only library registration differs. Legacy baseline/template/preserve SVG packages first run `restore-pptx-structure`. Raw one-off PPTX filling remains `template-fill-pptx`.
- **Native-preset authoring guidance strengthened across roles** — using a real PowerPoint preset (`prstGeom`, with adjustment handles and the non-flat-card look) is reaffirmed as the default for stock geometry (block arrows, chevrons, banners, callouts, flowchart nodes, stars), not an exception. Presets are helper-generated per page (`preset_shape_svg.py`), so the guidance lives in the prompt layer, not in template exemplars: the Executor now reaches for presets inside the per-page authoring ritual — decided by object intent at draw time, never by scanning finished paths — with the accurate paint boundary spelled out (a gradient fill/stroke or pattern fill stays ordinary SVG because the helper paints `none` or a solid HEX on both fill and stroke only). The Strategist primes it upstream by appending a non-destructive `native-preset candidate` note to a §VII page's Usage, triggered by the page plan rather than a template's name; the Executor still selects the exact preset, frame, and paint. Baking preset fragments into `templates/charts/` was evaluated and rejected — a frozen frame/fingerprint invites verbatim copy, which the authoring contract forbids
@@ -117,7 +117,7 @@ The directions below come up repeatedly and have been evaluated as **not on the
**Issues**: [#53](https://github.com/hugohe3/ppt-master/issues/53), [#118](https://github.com/hugohe3/ppt-master/issues/118)
-PPT Master's main route is "AI generates SVG from scratch → DrawingML", with the whole pipeline built around full control of every shape / text / layout. A structured PPTX can now become a reviewed reusable package in two explicit ways: `standard` / `fidelity` author a new SVG and Master/Layout system from visual evidence, while `mirror` restores the reachable supported source graph. Generic "open any PPTX and blindly refill every placeholder" remains a different product shape.
+PPT Master's main route is "AI generates SVG from scratch → DrawingML", with the whole pipeline built around full control of every shape / text / layout. A structured PPTX can now become a reviewed reusable package in two explicit ways: `standard` / `fidelity` author a new SVG and Master/Layout system from visual evidence, while `mirror` restores the complete supported source graph, including unused Layout definitions. Generic "open any PPTX and blindly refill every placeholder" remains a different product shape.
**The basic need is actually simple**: if you just need "replace Excel data into fixed positions in a PPT template", have the AI write a few lines of `python-pptx`. You don't need this pipeline.
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 451fd31f..6003140a 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -332,7 +332,7 @@ The Strategist phase produces two artifacts that look redundant but serve differ
Why both? Without `spec_lock.md`, the Executor would re-read `design_spec.md` per page during long decks and the LLM's context-compression drift would gradually mutate colors and fonts mid-deck. `spec_lock.md` is the **anti-drift mechanism** — the SKILL.md mandates `read_file <project>/spec_lock.md` before every page, so values stay verbatim across 20+ slides.
-The lock is also the per-page routing table. Beyond global colors and typography, it carries `page_rhythm` (`anchor` / `dense` / `breathing`), `page_charts` (which chart template should be adapted), image rows with placement/cropping contracts, and the locked `mode` / `visual_style` references that decide which execution rule files are loaded. Structured deck/layout-template projects additionally carry `page_layouts` (which input template SVG each page inherits) and the `pptx_masters` / `pptx_layouts` output mappings; flat free-design/brand-only projects keep only `pptx_structure.mode: flat` and omit those sections entirely rather than writing empty values. Empty entries elsewhere are meaningful signals: no chart or no image is often a design decision rather than missing data.
+The lock is also the per-page routing table. Beyond global colors and typography, it carries `page_rhythm` (`anchor` / `dense` / `breathing`), `page_charts` (which chart template should be adapted), image rows with placement/cropping contracts, and the locked `mode` / `visual_style` references that decide which execution rule files are loaded. Structured deck/layout-template projects additionally carry `page_layouts` (which input template SVG each page inherits), unique `pptx_masters` / `pptx_layouts` definitions, and `page_pptx_layouts` assignments; flat free-design/brand-only projects keep only `pptx_structure.mode: flat` and omit those sections entirely rather than writing empty values. Empty entries elsewhere are meaningful signals: no chart or no image is often a design decision rather than missing data.
`update_spec.py` propagates a post-generation change in two coordinated steps: write the new value to `spec_lock.md`, then literal-replace it across every `svg_output/*.svg`. The tool's scope is deliberately narrow — only `colors.*` (HEX values, case-insensitive replacement) and `typography.font_family` (attribute-scoped). Other fields (font sizes, icons, images, canvas) are intentionally **not supported** because their replacements would need attribute-scoped or semantic awareness whose risk/benefit doesn't justify bulk propagation. For those, edit `spec_lock.md` and re-author the affected pages.
@@ -468,7 +468,7 @@ These direct routes share some analysis primitives with the main pipeline, espec
**Why there is only one PPTX compiler route.** Native export reads authored SVGs and translates supported SVG elements into DrawingML shapes. The normal deck path reads `svg_output/`; when requested, create-template invokes the same structured compiler on validated template prototypes to produce `exports/<id>_template_preview.pptx` as review evidence. The project does not package whole-slide SVG media or alternate raster renderings into a second PPTX. `svg_final/` is still generated on every standard deck run, but it is a self-contained visual-preview artifact rather than a PPTX source; users may insert it as an SVG picture, while PowerPoint's manual Convert to Shape command remains outside the supported contract.
-**Why structure is authored before visual generation on template routes.** Master and Layout are not post-processing discoveries. On a structured deck/layout-template route, the Strategist writes the Master roster and complete page mapping before SVG generation; the Executor writes those identities, fixed atoms, and slots while composing each page, and export only compiles declared structure. Free-design and brand-only decks make the opposite trade: they stay on `mode: flat`, keep every object Slide-local, author no structure metadata, and receive only a clean project-owned Master/Blank-Layout shell at export — reusable structure is a template-route deliverable, not a free-design authoring tax. Legacy structured/template projects enter `restore-pptx-structure`; neither route triggers heuristic Master/Layout promotion or placeholder inference.
+**Why structure is authored before visual generation on template routes.** Master and Layout are not post-processing discoveries. On a structured deck/layout-template route, the Strategist writes unique Master/Layout definitions and complete page assignments before SVG generation; the Executor writes those identities, fixed atoms, and slots while composing each page, and export only compiles declared structure. Free-design and brand-only decks make the opposite trade: they stay on `mode: flat`, keep every object Slide-local, author no structure metadata, and receive only a clean project-owned Master/Blank-Layout shell at export — reusable structure is a template-route deliverable, not a free-design authoring tax. Legacy structured/template projects enter `restore-pptx-structure`; neither route triggers heuristic Master/Layout promotion or placeholder inference.
**Why Master/Layout visuals are atomic.** A Master or fixed Layout object must be one direct root child. Group-level transforms, opacity, styles, and z-order from imported PPTX objects are pushed into individual atoms during reconstruction. This deliberately gives up source group-editing hierarchy in exchange for a simple, deterministic ownership model that can be compared across pages and rebuilt into native parts without nested structural ambiguity.
@@ -476,11 +476,11 @@ These direct routes share some analysis primitives with the main pipeline, espec
**Why reusable bounds are design zones, not measured text boxes.** Slot bounds come from the intended safe area, column, panel inset, or picture frame—not glyph width, line count, or the current content's tight box. The current Slide retains its own authored carrier geometry, so 4:6, 3:7, and 5:5 instances may share one Layout when they express the same semantic composition. Text length therefore cannot accidentally split or mutate the reusable Layout contract.
-**Why strict and adaptive templates share one structured route.** `page_layouts` records the complete input prototype, while `pptx_masters` and `pptx_layouts` record output ownership from planning onward. Strict preserves the declared prototype contract. Adaptive retains its Master and assigns a new Layout key only when fixed Layout atoms or slot topology/bounds change; that mapping is updated during page authoring rather than inferred later. Non-mirror skin remains project-controlled, while mirror keeps restored output visual identities.
+**Why strict and adaptive templates share one structured route.** `page_layouts` records the complete authoring prototype, `pptx_masters` / `pptx_layouts` record unique reusable definitions, and `page_pptx_layouts` records page assignment. Strict preserves the declared prototype contract. Adaptive retains its Master and defines a new Layout only when fixed Layout atoms or slot topology/bounds change; the assignment is updated during page authoring rather than inferred later. A template-backed definition may remain unused and still register in the final package. Non-mirror skin remains project-controlled, while mirror keeps restored output visual identities.
-**Why explicit-Layout text defaults are split between Master and Layout.** Both flat and structured export write locked title/body sizes into Master text defaults. On structured routes, each generated Layout text slot additionally copies its carrier's first run size into the level-one default while retaining the prompt's direct size. This preserves Layout-specific scale when placeholder text is inserted or reset; direct runs on generated Slides remain unchanged.
+**Why explicit-Layout text defaults are split between Master and Layout.** Both flat and structured export write the locked title size and a deterministic nine-level body hierarchy into Master defaults while preserving indentation and bullet settings. On structured routes, each generated Layout text slot additionally copies its carrier's first run size into the level-one default while retaining the prompt's direct size. This preserves Layout-specific scale when placeholder text is inserted or reset; direct runs on generated Slides remain unchanged.
-**Why structured output is read back before publication.** Metadata preflight cannot prove package serialization preserved every relationship and registration. Export therefore reopens the temporary PPTX and validates Presentation → Master → Layout → Slide registration, physical part/content-type rosters, picker identities, exact static-object order, placeholder type/effective index/bounds, carrier bindings, hidden proxies, and zero-slot Layouts before publishing the file.
+**Why structured output is read back before publication.** Metadata preflight cannot prove package serialization preserved every relationship and registration. Export therefore reopens the temporary PPTX and validates published Slides separately from the complete Master/Layout roster, including definitions unused by all Slides. It checks Presentation → Master → Layout → Slide registration, physical part/content-type rosters, picker identities, exact static-object order, placeholder type/effective index/bounds, carrier bindings, hidden proxies, and zero-slot Layouts before publishing the file.
**Why template creation has authored and restoration modes.** `pptx_template_import.py` emits layered Master/Layout/Slide references plus native structure facts. `standard` / `fidelity` use those assets and visuals as references, then author a new topology from the confirmed reusable behavior. Mirror instead restores the source roster and topology one-to-one, allowing only mechanical normalization required by the explicit structured contract. The original PPTX remains analysis evidence, not a packaged export dependency.
diff --git a/docs/templates-guide.md b/docs/templates-guide.md
index ee3e8212..0d4ed3e0 100644
--- a/docs/templates-guide.md
+++ b/docs/templates-guide.md
@@ -174,7 +174,7 @@ This is the most easily confused decision when deriving a template.
**About native PowerPoint shapes**: the lossless import SVG stays in the temporary analysis workspace, while the model works from a lightweight projection that omits opaque payload and duplicate hidden carriers. The projection is never an export source. Authored modes use compact canonical metadata. Mirror may reuse converter-supported metadata on unchanged Slide-local/slot objects; fixed Master/Layout layers remain direct atoms, and unsupported or edited objects keep the current SVG fallback.
-**Current mirror boundary**: every source Layout must be used by at least one source slide, and every source Master must be reachable through those Layouts. The structured template roster cannot yet materialize an unused picker-only identity without inventing an extra page, so preflight reports the exact unused identities and stops instead of silently dropping them.
+**Mirror graph boundary**: mirror preserves the complete supported source Master/Layout graph. It emits one complete prototype per source slide and one definition-only `layout_<layout_key>.svg` prototype for every source Layout unused by those slides. The latter registers in PowerPoint through the independent Layout roster without becoming a published page; its parent Master is retained with it. Preflight stops only when required source facts or supported geometry are missing, never merely because a Layout is unused.
**How mirror is consumed**: the Strategist picks one mirror page per project page, and the Executor copies that complete SVG and edits visible text in place while preserving decoration, sprite crops, geometry, and the normalized structured declarations. Mirror preserves supported appearance, not the source PPTX group-editing hierarchy.
diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.md
index bf479fa8..d3736d6a 100644
--- a/docs/zh/roadmap.md
+++ b/docs/zh/roadmap.md
@@ -84,7 +84,7 @@
- **`--native-objects` 从休眠 marker 硬化为可用级 opt-in** — 那条窄「原生对象」例外(见下文 Non-goals)现在导出的图表与纯文本表格会**保留 deck 自己的设计**,不再塌回 PowerPoint 的白底默认主题。classic 原生图表显式写入 chart-area / plot-area / 轴线 / 网格线 / 标签文字颜色——从可见的 SVG fallback 推断(最大面板型 `<rect>` → 背景、fallback 文字 → 标签、fallback 描边 → 轴线/网格),或用 `style` 显式覆盖(`chart_area_fill` / `plot_area_fill` / `text_color` / `axis_color` / `grid_color`,`"none"` 表透明);颜色解析把命名色、`#RGB` 简写、`rgb()` / `rgba()` 归一为 OOXML hex;bar/column 系列关掉负值反色,负值柱保持系列色。激活导出命名为 `<name>_<ts>_native_charts.pptx` 以与默认压平形状导出区分。**默认路线不变**——图表/表格仍以 SVG 派生的 DrawingML 形状导出以保跨渲染器保真;原生对象仍是下文 Non-goals 里那条刻意的 opt-in 取舍
-- **原生 package 结构 + 按模式创建模板** — deck/layout-template SVG 页面在创作时就声明最终 Master/Layout 身份。固定 Master/Layout 视觉是根级原子,可复用槽位是带真实 carrier 或显式 composite proxy 的有界顶层 group,零槽位 Layout 也合法。`structured` 导出只确定性编译该合同并执行最终 package 回读;不提升重复 chrome,也不推断 placeholder。`flat` 自由设计 / brand-only 导出则保持所有内容 Slide-local,同时把 stock Office 脚手架替换成一个属于项目的干净 Master、一个 Blank Layout 和按 deck 命名的当前 lock 主题;删除 title/body 等 stock 内容、裁掉未使用 Layout,仅保留标准日期、页脚和页码能力钩子。两条生成路线都把锁定 title/body 字号写入母版 `p:txStyles`。`standard` / `fidelity` 重新创作 SVG roster 和新的 Master/Layout 系统,不保留、也不蒸馏来源拓扑。`mirror` 按来源页序恢复 Master/Layout 身份与父子关系、placeholder 事实和受支持视觉,不做语义归纳;固定结构层的来源 group 只允许机械展开成直接原子。无损导入保留在分析区,轻量 projection 仅供检查。`library` 与 `project` 都要求 `templates/`,`images/` / `icons/` 可选,`exports/` 仅在按需生成评审文件时出现;只有全局注册不同。旧 baseline/template/preserve SVG 包先运行 `restore-pptx-structure`;原始 PPTX 的一次性回填仍走 `template-fill-pptx`。
+- **原生 package 结构 + 按模式创建模板** — deck/layout-template SVG 页面在创作时就声明最终 Master/Layout 身份。固定 Master/Layout 视觉是根级原子,可复用槽位是带真实 carrier 或显式 composite proxy 的有界顶层 group,零槽位 Layout 也合法。`structured` 导出只确定性编译该合同并执行最终 package 回读;不提升重复 chrome,也不推断 placeholder。`flat` 自由设计 / brand-only 导出则保持所有内容 Slide-local,同时把 stock Office 脚手架替换成一个属于项目的干净 Master、一个 Blank Layout 和按 deck 命名的当前 lock 主题;删除 title/body 等 stock 内容、裁掉未使用 Layout,仅保留标准日期、页脚和页码能力钩子。两条生成路线都把锁定 title 与确定性的九级 body 层级写入母版 `p:txStyles`,同时保留段落和项目符号设置。`standard` / `fidelity` 重新创作 SVG roster 和新的 Master/Layout 系统,不保留、也不蒸馏来源拓扑。`mirror` 恢复完整且受支持的来源图谱,包括未使用 Layout 的定义专用原型;固定结构层的来源 group 只允许机械展开成直接原子,不做语义归纳。无损导入保留在分析区,轻量 projection 仅供检查。`library` 与 `project` 都要求 `templates/`,`images/` / `icons/` 可选,`exports/` 仅在按需生成评审文件时出现;只有全局注册不同。旧 baseline/template/preserve SVG 包先运行 `restore-pptx-structure`;原始 PPTX 的一次性回填仍走 `template-fill-pptx`。
- **原生预设授权引导跨角色强化** — 用真正的 PowerPoint 预设(`prstGeom`,带调节手柄、非扁平卡片外观)被重申为库存几何(块箭头、chevron、横幅、标注、流程节点、星形)的**默认**而非例外。预设是每页由 helper(`preset_shape_svg.py`)现生成的,所以引导落在提示词层而非模板示范:Executor 现在在逐页作图仪式内主动够预设——按对象意图在画图当下决定,绝不扫描已完成路径——并写明准确的 paint 边界(渐变填充/描边或 pattern 填充保持普通 SVG,因为 helper 只对 fill 和 stroke 画 `none` 或纯色 HEX)。Strategist 在上游预热:给 §VII 页面的 Usage **追加**一条非破坏性的 `native-preset candidate` 注记,按页面计划而非模板名触发;Executor 仍自定具体预设、frame 与 paint。把预设片段烤进 `templates/charts/` 经评估否决——冻死的 frame/fingerprint 会诱导原样复制,违反授权契约
@@ -117,7 +117,7 @@
**对应 Issue**:[#53](https://github.com/hugohe3/ppt-master/issues/53)、[#118](https://github.com/hugohe3/ppt-master/issues/118)
-PPT Master 主路线是「AI 从零生成 SVG → DrawingML」,整条管线围绕完全可控的形状/文字/版式构建。结构完整的 PPTX 现在可以通过两种显式方式形成经过确认的可复用模板包:`standard` / `fidelity` 以视觉证据为参考,创作新的 SVG 与 Master/Layout 系统;`mirror` 恢复当前可达且受支持的来源结构。但「打开任意 PPTX 后不经规范化就盲填所有占位框」仍是另一种产品形态。
+PPT Master 主路线是「AI 从零生成 SVG → DrawingML」,整条管线围绕完全可控的形状/文字/版式构建。结构完整的 PPTX 现在可以通过两种显式方式形成经过确认的可复用模板包:`standard` / `fidelity` 以视觉证据为参考,创作新的 SVG 与 Master/Layout 系统;`mirror` 恢复完整且受支持的来源结构,包括未使用的 Layout 定义。但「打开任意 PPTX 后不经规范化就盲填所有占位框」仍是另一种产品形态。
**基础诉求其实很简单**:如果只是「固定位置替换 Excel 数据到 PPT 模板」,直接让 AI 写一段 `python-pptx` 脚本即可,几行代码搞定,不需要本项目这套管线。
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index a6ec26b9..985d5c48 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -332,7 +332,7 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
为什么两份都要?没有 `spec_lock.md` 的话,Executor 在长 deck 里会逐页重读 `design_spec.md`,LLM 上下文压缩漂移会逐渐扭曲色值和字体。`spec_lock.md` 是**抗漂移机制**——SKILL.md 强制要求生成每一页前 `read_file <project>/spec_lock.md`,让数值在 20+ 页里保持字面一致。
-这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_charts`(某页应适配哪个图表模板)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。结构化 deck/layout 模板项目额外承载 `page_layouts`(每页继承哪个输入模板 SVG)和 `pptx_masters` / `pptx_layouts` 输出映射;flat 自由设计 / brand-only 项目只保留 `pptx_structure.mode: flat`,那些段整段省略,而不是写成空值。其余字段的空值本身仍是信号:没有图表、没有图片,很多时候是设计选择,而不是漏填。
+这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_charts`(某页应适配哪个图表模板)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。结构化 deck/layout 模板项目额外承载 `page_layouts`(每页继承哪个输入模板 SVG)、唯一的 `pptx_masters` / `pptx_layouts` 定义,以及 `page_pptx_layouts` 页面分配;flat 自由设计 / brand-only 项目只保留 `pptx_structure.mode: flat`,那些段整段省略,而不是写成空值。其余字段的空值本身仍是信号:没有图表、没有图片,很多时候是设计选择,而不是漏填。
`update_spec.py` 把生成后的修改用两个协调步骤传播:把新值写入 `spec_lock.md`,然后字面替换到每一份 `svg_output/*.svg`。工具的范围**故意收得很窄**——只支持 `colors.*`(HEX 值,大小写不敏感替换)和 `typography.font_family`(属性级)。其他字段(字号、图标、图片、画布)**有意不支持**——它们的替换需要属性级或语义级理解,风险/收益不值得做批量传播。这些情况手动改 `spec_lock.md` 然后重做受影响的页面。
@@ -468,7 +468,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
**为什么只有一条 PPTX 编译路线。** Native 导出把作者 SVG 中受支持的元素逐个翻译成 DrawingML 形状。常规 deck 路线读取 `svg_output/`;用户需要时,create-template 对通过校验的模板原型调用同一 structured 编译器,生成 `exports/<id>_template_preview.pptx` 作为审阅证据。项目不会把整页 SVG 媒体或另一套位图渲染打包成第二类 PPTX。`svg_final/` 仍由常规 deck 的强制后处理生成,但只承担自包含视觉预览和 SVG 图片插入,不为 PowerPoint 手工“转换为形状”提供兼容兜底。
-**为什么模板路线的结构必须在视觉生成前确定。** Master 和 Layout 不是后处理阶段才发现的结果。在结构化 deck/layout 模板路线上,Strategist 在 SVG 生成前写出 Master roster 和完整页面 mapping;Executor 在构图时同步写入这些身份、固定原子元素和槽位,导出器只编译声明。自由设计与 brand-only deck 做的是相反的取舍:保持 `mode: flat`,所有对象留在 Slide 本地,不写任何结构 metadata,导出时只获得一个属于本项目的干净 Master/Blank-Layout 壳——可复用结构是模板路线的交付物,不是自由设计的创作税。legacy structured/template 项目进入 `restore-pptx-structure`;两条路线都不会触发启发式 Master/Layout 提升或 placeholder 推断。
+**为什么模板路线的结构必须在视觉生成前确定。** Master 和 Layout 不是后处理阶段才发现的结果。在结构化 deck/layout 模板路线上,Strategist 在 SVG 生成前写出唯一 Master/Layout 定义和完整页面分配;Executor 在构图时同步写入这些身份、固定原子元素和槽位,导出器只编译声明。自由设计与 brand-only deck 做的是相反的取舍:保持 `mode: flat`,所有对象留在 Slide 本地,不写任何结构 metadata,导出时只获得一个属于本项目的干净 Master/Blank-Layout 壳——可复用结构是模板路线的交付物,不是自由设计的创作税。legacy structured/template 项目进入 `restore-pptx-structure`;两条路线都不会触发启发式 Master/Layout 提升或 placeholder 推断。
**为什么 Master/Layout 视觉必须原子化。** 一个 Master 或固定 Layout 对象必须是根节点的直接子元素。导入 PPTX 时,group 的 transform、opacity、style 和 z-order 会下推到各个原子对象。这个选择有意放弃来源 group 的整体编辑层级,换取简单、可比较、可确定重建的结构归属,避免嵌套结构歧义。
@@ -476,11 +476,11 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
**为什么可复用 bounds 是设计区域,不是量出来的文本框。** bounds 来自安全区、分栏、面板内框或图片框,而不是字形宽度、行数或当前内容紧包围盒。当前 Slide 保留自己的 carrier 几何,因此只要语义构图相同,4:6、3:7、5:5 的实例都可复用同一 Layout。文本长度不会意外拆分或改变可复用合同。
-**为什么 strict 与 adaptive 模板共享一条 structured 路线。** `page_layouts` 记录完整输入原型,`pptx_masters` 与 `pptx_layouts` 从规划阶段起记录输出归属。strict 保持声明的原型合同;adaptive 保持原型 Master,只有固定 Layout 原子或槽位 topology/bounds 改变时才使用新 Layout key,并在页面创作时立即更新 mapping,而不是事后推断。非 mirror 的皮肤由项目控制;mirror 保持已恢复的输出视觉身份。
+**为什么 strict 与 adaptive 模板共享一条 structured 路线。** `page_layouts` 记录完整创作原型,`pptx_masters` / `pptx_layouts` 记录唯一可复用定义,`page_pptx_layouts` 记录页面分配。strict 保持声明的原型合同;adaptive 保持原型 Master,只有固定 Layout 原子或槽位 topology/bounds 改变时才定义新 Layout,并在页面创作时立即更新分配,而不是事后推断。模板定义即使暂时没有页面使用,也能注册进最终文件。非 mirror 的皮肤由项目控制;mirror 保持已恢复的输出视觉身份。
-**为什么显式版式把文字默认值分在 Master 与 Layout 两层。** Flat 与 structured 导出都会把锁定的 title/body 字号写入 Master 文本默认值;在 structured 路线上,每个 Layout 文字槽位还会把 carrier 首个 run 的字号写入一级默认值,同时保留提示文字的直接字号。这样,插入或重置 placeholder 时仍能继承 Layout 特定尺度,而生成 Slide 上的直接 run 不变。
+**为什么显式版式把文字默认值分在 Master 与 Layout 两层。** Flat 与 structured 导出都会把锁定的 title 字号和确定性的九级 body 层级写入 Master 文本默认值,同时保留原有缩进与项目符号设置;在 structured 路线上,每个 Layout 文字槽位还会把 carrier 首个 run 的字号写入一级默认值,同时保留提示文字的直接字号。这样,插入或重置 placeholder 时仍能继承 Layout 特定尺度,而生成 Slide 上的直接 run 不变。
-**为什么 structured 输出要在发布前回读。** 元数据预检不能证明 package 序列化保留了所有 relationship 与注册信息。导出器会重新打开临时 PPTX,校验 Presentation → Master → Layout → Slide 注册链、物理 part/content-type roster、选择器身份、固定对象顺序、placeholder 类型/有效索引/bounds、carrier 绑定、隐藏 proxy 与零槽 Layout,只有通过后才发布。
+**为什么 structured 输出要在发布前回读。** 元数据预检不能证明 package 序列化保留了所有 relationship 与注册信息。导出器会重新打开临时 PPTX,把已发布 Slide 与完整 Master/Layout roster 分开校验,包括没有任何 Slide 使用的定义;同时核对 Presentation → Master → Layout → Slide 注册链、物理 part/content-type roster、选择器身份、固定对象顺序、placeholder 类型/有效索引/bounds、carrier 绑定、隐藏 proxy 与零槽 Layout,只有通过后才发布。
**为什么模板创建分为创作模式和恢复模式。** `pptx_template_import.py` 输出分层 Master/Layout/Slide 参考和 native 结构事实。`standard` / `fidelity` 把这些素材和视觉当参考,再按照确认后的可复用行为创作新拓扑。Mirror 则一对一恢复来源 roster 与拓扑,只允许显式 structured 合同要求的机械归一化。原始 PPTX 保留为分析证据,不成为最终模板依赖。
diff --git a/docs/zh/templates-guide.md b/docs/zh/templates-guide.md
index 15d05fa5..2e737dd4 100644
--- a/docs/zh/templates-guide.md
+++ b/docs/zh/templates-guide.md
@@ -174,7 +174,7 @@ PPT Master 的“模板”是一份**结构 + 风格**的预设包:每张 SVG
**关于 PowerPoint 原生形状**:完整导入 SVG 保留在临时分析工作区,模型读取的是移除 opaque payload 和重复 carrier 的轻量 projection;projection 永远不是导出源。创作模式使用紧凑 canonical metadata。Mirror 可在未改的 Slide-local/slot 对象上复用转换器已支持的 metadata;固定 Master/Layout 层保持直接原子,不支持或已修改的对象保留当前 SVG fallback。
-**当前 mirror 边界**:每个来源 Layout 都必须至少被一张来源 Slide 使用,每个来源 Master 也必须能通过这些 Layout 到达。当前 structured 模板 roster 还不能在不虚构额外页面的情况下物化只存在于选择器里的未使用身份,因此预检会列出具体未使用身份并停止,而不是静默丢弃。
+**Mirror 图谱边界**:mirror 保留完整且受支持的来源 Master/Layout 图谱。它为每张来源 Slide 输出一个完整原型,并为未被任何来源 Slide 使用的 Layout 额外输出一个定义专用的 `layout_<layout_key>.svg`。后者通过独立 Layout roster 注册进 PowerPoint,不会变成发布页面;其父 Master 也随之保留。预检只在必要来源事实或受支持几何缺失时停止,不会仅因 Layout 未使用而停止。
**`mirror` 模板怎么消费**:Strategist 为每个项目页选择一张 mirror 参考,Executor 复制完整 SVG 并原位修改可见文字,同时保留装饰、精灵图裁剪、几何坐标和全部 `data-pptx-*` 结构声明。
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index d736bf39..0bb8d27d 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -38,7 +38,7 @@ description: >
> 5. **NO SPECULATIVE EXECUTION** — "Pre-preparing" content for subsequent Steps is FORBIDDEN (e.g., writing SVG code during the Strategist phase)
> 6. **NO SUB-AGENT SVG GENERATION** — Executor Step 6 SVG generation is context-dependent and MUST be completed by the current main agent end-to-end. Delegating page SVG generation to sub-agents is FORBIDDEN
> 7. **SEQUENTIAL PAGE GENERATION ONLY** — In Executor Step 6, after the global design context is confirmed, SVG pages MUST be generated sequentially page by page in one continuous pass. Grouped page batches (for example, 5 pages at a time) are FORBIDDEN
-> 8. **SPEC_LOCK RE-READ PER PAGE** — Before generating each SVG page, Executor MUST `read_file <project_path>/spec_lock.md`. All colors / fonts / icons / images MUST come from this file — no values from memory or invented on the fly. Executor MUST also read `pptx_structure.mode`, the current page's `page_rhythm` (`anchor` / `dense` / `breathing`), and `page_charts`. Only a deck/layout template route (`mode: structured`) looks up `page_layouts` (the input template SVG), `pptx_masters`, `pptx_layouts`, and `template_adherence`; free-design and brand-only routes use `mode: flat` and omit those sections. This rule exists to resist context-compression drift on long decks and to break the uniform "every page is a card grid" default
+> 8. **SPEC_LOCK RE-READ PER PAGE** — Before generating each SVG page, Executor MUST `read_file <project_path>/spec_lock.md`. All colors / fonts / icons / images MUST come from this file — no values from memory or invented on the fly. Executor MUST also read `pptx_structure.mode`, the current page's `page_rhythm` (`anchor` / `dense` / `breathing`), and `page_charts`. Only a deck/layout template route (`mode: structured`) looks up `page_layouts` (the input template SVG), `page_pptx_layouts` (the page assignment), `pptx_masters`, `pptx_layouts` (the unique reusable roster), and `template_adherence`; free-design and brand-only routes use `mode: flat` and omit those sections. This rule exists to resist context-compression drift on long decks and to break the uniform "every page is a card grid" default
> 9. **SVG MUST BE HAND-WRITTEN, NOT SCRIPT-GENERATED** — Every SVG page is written by the main agent directly, one page at a time (see rules 6 and 7). Writing or running a Python / Node / shell script that produces the SVG files in batch — looping over pages, templating from data, or emitting them via a generator — is FORBIDDEN, including under "save tokens", "quick draft", or "user is in a hurry" pretexts. The script-generation path was tried on a feature branch and abandoned: cross-page visual consistency depends on per-page authoring with full upstream context, which a generator script cannot reproduce. **Narrow exception**: `preset_shape_svg.py` may print one deterministic stock-shape fragment to stdout after the main agent has selected its semantic role, frame, and paint. It cannot write `svg_output/`, choose layout, batch shapes, or generate a page; the main agent reads the fragment and inserts it through the normal hand-authored page edit
> 10. **FOLLOW DETERMINISTIC ROUTING RULES** — Do not add blocking routing questions when this skill defines a route. If the user request violates a route precondition, state the required prerequisite and stop that route instead of asking the user to choose around the rule. Ordinary finite options, stylistic preferences, and recoverable details are surfaced with a recommended value plus alternatives at the next existing confirmation gate.
@@ -145,11 +145,12 @@ keep model context small. Mechanical normalization may express the source facts
in the current explicit SVG contract and expand fixed-layer group wrappers into
direct atoms, but it MUST NOT merge, split, promote, demote, rename, or
re-parent source structure. Export compiles the selected contract and never
-infers a different one. Because the current structured roster materializes only
-identities referenced by emitted page prototypes, `mirror` is available only
-when every source Layout is used by a source Slide and every source Master is
-reachable through those Layouts. Otherwise stop and report the exact
-unreachable identities; never drop them or invent a carrier page.
+infers a different one. Mirror emits one complete page prototype per source
+Slide plus one definition-only `layout_<layout_key>.svg` prototype for every
+source Layout unused by those Slides. The independent Master/Layout roster then
+registers the complete supported source graph without publishing synthetic
+carrier pages. Stop only when required native evidence is missing or unsupported;
+never silently drop or merge an identity.
**FALLBACK**: Ambiguous requests such as "make this PPT more professional" require exactly one discriminator question: preserve original page count/order and slide wording, or treat the deck as source material and restructure it?
@@ -307,7 +308,7 @@ A project-scoped workspace has the same portable routing as a library workspace.
Legacy template packages may ship `native_structure.json` + `source_template.pptx`, omit root Master identity, use direct atomic placeholders, or carry old baseline/distillation metadata. Do not copy or consume those semantic contracts through Step 3. Run [`restore-pptx-structure`](workflows/restore-pptx-structure.md) on the package first, then return with the migrated workspace path. Old flat packaging remains readable when its SVG structure is already current.
-The Strategist confirmation stage decides whether the selected deck/layout template is used `strict` or `adaptive`. Those template projects use `pptx_structure.mode: structured`, map every page to one input SVG in `page_layouts`, and write complete `pptx_masters` / `pptx_layouts` output mappings before SVG generation. Brand-only projects remain on the free-design `mode: flat` route. Strict preserves the template's declared Master/Layout/slot contract. Adaptive keeps the template Master and may assign a new Layout key during authoring when the composition genuinely changes. Non-mirror paint and typography follow the project skin rules.
+The Strategist confirmation stage decides whether the selected deck/layout template is used `strict` or `adaptive`. Those template projects use `pptx_structure.mode: structured`, map every page to one input SVG in `page_layouts`, declare unique reusable identities in `pptx_masters` / `pptx_layouts`, and assign each page through `page_pptx_layouts` before SVG generation. A Layout definition may remain unused by generated pages when it names an installed template SVG as its prototype source. Brand-only projects remain on the free-design `mode: flat` route. Strict preserves the template's declared Master/Layout/slot contract. Adaptive keeps the template Master and may define and assign a new Layout key during authoring when the composition genuinely changes. Non-mirror paint and typography follow the project skin rules.
#### Multi-path fusion
@@ -625,7 +626,7 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon
> Image facts: trust the `analysis/image_analysis.csv` regenerated at the end of Step 5. If `images/` changed since (the user swapped or added files), re-run `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` before laying images out — facts are re-derived on use, never a stale store (Step 4 image-facts note).
-**Per-page spec_lock re-read (Mandatory)**: before **each** SVG page, `read_file <project_path>/spec_lock.md` and use only its colors / fonts / icons / images, plus `pptx_structure.mode` and the per-page `page_rhythm` / `page_charts` lookups. Read `page_layouts` / `pptx_masters` / `pptx_layouts` only on a structured deck/layout template route; they are absent in flat free-design and brand-only projects. Resists context-compression drift on long decks. See executor-base.md §2.1.
+**Per-page spec_lock re-read (Mandatory)**: before **each** SVG page, `read_file <project_path>/spec_lock.md` and use only its colors / fonts / icons / images, plus `pptx_structure.mode` and the per-page `page_rhythm` / `page_charts` lookups. Read `page_layouts` / `page_pptx_layouts` / `pptx_masters` / `pptx_layouts` only on a structured deck/layout template route; they are absent in flat free-design and brand-only projects. Resists context-compression drift on long decks. See executor-base.md §2.1.
> ⚠️ **Main-agent only**: SVG generation MUST stay in the current main agent — page design depends on full upstream context. Do NOT delegate to sub-agents.
> ⚠️ **Generation rhythm**: generate pages sequentially, one at a time, in the same continuous context. Do NOT batch (e.g., 5 per group).
@@ -636,7 +637,7 @@ Each completed SVG MUST be a standalone, complete representation of that slide's
Template pages MUST start from the complete `page_layouts` SVG, keep all inherited visible objects in `svg_output/`, and preserve the locked root Master/Layout identity plus stable atomic Master/Layout and slot ids. Strict keeps the prototype structure unchanged. Adaptive keeps its Master contract and, when Layout atoms or slot topology/bounds genuinely evolve, assigns a new key/name and updates `spec_lock.md` immediately. Non-mirror fill/stroke/effects/font sizes still follow `spec_lock`.
-Free-design and brand-only pages use `pptx_structure.mode: flat`. Draw the complete page directly: keep backgrounds, repeated chrome, headings, text, images, and decoration as ordinary Slide-local SVG content. Do not plan `pptx_masters` / `pptx_layouts`, do not add root Master/Layout identity, and do not add `data-pptx-layer` or `data-pptx-placeholder` metadata. Group logical content normally with top-level `<g id>` elements. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme colors/fonts/title-body defaults, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks. It does not promote or deduplicate page content.
+Free-design and brand-only pages use `pptx_structure.mode: flat`. Draw the complete page directly: keep backgrounds, repeated chrome, headings, text, images, and decoration as ordinary Slide-local SVG content. Do not plan `pptx_masters` / `pptx_layouts` / `page_pptx_layouts`, do not add root Master/Layout identity, and do not add `data-pptx-layer` or `data-pptx-placeholder` metadata. Group logical content normally with top-level `<g id>` elements. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme colors/fonts/title-body defaults, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks. It does not promote or deduplicate page content.
Do not duplicate specialized identity with `data-pptx-role`. Add it 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).
@@ -745,15 +746,18 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> **PPTX structure mode** — release export reads the explicit route from
> `spec_lock.md`. Free-design and brand-only projects use
> `pptx_structure.mode: flat`, omit `pptx_masters` / `pptx_layouts` /
-> `page_layouts`, and author no Master/Layout/layer/placeholder metadata in
+> `page_pptx_layouts` / `page_layouts`, and author no Master/Layout/layer/placeholder metadata in
> SVG. Export keeps every represented object Slide-local while materializing
> one clean project-owned Master and one Blank Layout from the current lock;
> stock content placeholders and unused built-in Layouts are removed; only the
> standard date/footer/slide-number capability hooks remain.
>
> Deck/layout template projects use `pptx_structure.mode: structured`, a
-> complete `pptx_masters` roster, and exactly one `pptx_layouts` row per page
-> in `<master_key> | <layout_key> | <PowerPoint layout name>` form. Every SVG
+> complete `pptx_masters` roster, one unique `pptx_layouts` definition per
+> reusable Layout, and exactly one `page_pptx_layouts` assignment per page.
+> A Layout definition records Master key, PowerPoint picker name, and either a
+> `P<NN>` or `template:<basename>` prototype source; an unused Layout uses a template prototype
+> and is registered without a published carrier slide. Every SVG
> root repeats the Master/Layout keys and picker names. Master/Layout fixed
> visuals are direct root atoms; a `<g data-pptx-layer="master|layout">` is
> forbidden. Reusable slots are direct root `<g id>` elements with positive
@@ -778,8 +782,9 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> **Template structured export** — `page_layouts` records the complete
-> input prototype per page while `pptx_masters` / `pptx_layouts` record the
-> output structure from planning onward. Strict keeps the prototype
+> input prototype per page, `pptx_masters` / `pptx_layouts` record the unique
+> reusable output roster, and `page_pptx_layouts` records page assignment.
+> Strict keeps the prototype
> Master/Layout/slot contract. Adaptive keeps its Master and may assign a new
> Layout identity during page authoring only when fixed Layout atoms or slot
> topology/bounds change; the lock is updated immediately. Non-mirror skin
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.md
index 48794a3d..c9f9789f 100644
--- a/skills/ppt-master/references/artifact-ownership.md
+++ b/skills/ppt-master/references/artifact-ownership.md
@@ -42,8 +42,8 @@ Global artifact ownership rules for PPT Master projects.
| Sources read policy | In `sources/`, read content-type files (`.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml`) and judge by content — a `.json` / `.csv` may be core content or just data. Exclude known sidecars: `*.conversion_profile.json` and `*_files/image_manifest.json`. `analysis/` facts (`source_profile.json`, `<stem>.slide_library.json`) are read per Step 4 / direct-PPTX workflow, not in the `sources/` content scan. |
| PPTX structure | `slide_library.json` owns native geometry, slot facts, and SmartArt layout/relationships for direct PPTX workflows. |
| Design contract | `design_spec.md` explains; `spec_lock.md` executes. Executor must not infer execution values from prose. |
-| Free-design / brand-only packaging authority | `spec_lock.md` declares `pptx_structure.mode: flat` and omits `pptx_masters`, `pptx_layouts`, and `page_layouts`. `svg_output/` owns the complete Slide-local visual design without root Master/Layout identity, fixed-layer ownership, or placeholder metadata. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme defaults, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. |
-| Template structure authority | `page_layouts` owns the per-page input prototype. `pptx_masters` and `pptx_layouts` own the complete output structure from planning onward; strict keeps the prototype contract, while adaptive may create a new Layout identity during page authoring and updates the lock immediately. Templates validate provenance but never add missing visible objects during export. |
+| Free-design / brand-only packaging authority | `spec_lock.md` declares `pptx_structure.mode: flat` and omits `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`. `svg_output/` owns the complete Slide-local visual design without root Master/Layout identity, fixed-layer ownership, or placeholder metadata. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme defaults, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. |
+| Template structure authority | `page_layouts` owns each page's authoring-input prototype. `pptx_masters` / `pptx_layouts` own the unique reusable output definitions, while `page_pptx_layouts` owns page assignment. Strict keeps the prototype contract; adaptive may create a new Layout definition during page authoring and updates its assignment immediately. Unused definitions may register without a published Slide. Templates validate provenance but never add missing visible page objects during export. |
| Legacy structure migration | [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) owns conversion of old unmapped/distilled/preserve structured projects and legacy template packages into the current template contract. An intentional free-design or brand-only `flat` project is not a migration input. The exporter does not migrate or visually cluster legacy template structure. |
| Image facts | `images/` is live state; `analysis/image_analysis.csv` is a regenerated view, not a durable cache. |
| SVG source | `svg_output/` is the only author source for generated pages. |
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index cf288c02..2d72cafd 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -92,11 +92,11 @@ Before generating each page, output which template is used:
### 1.2 PowerPoint Master / Layout Mapping
-This section applies only to deck/layout template routes. `page_layouts` selects the input SVG prototype, and `pptx_masters` / `pptx_layouts` declare the structured output before the first page is drawn. Free-design and brand-only routes use `pptx_structure.mode: flat`, omit all three sections, skip the rest of §1.2, and keep every SVG object Slide-local.
+This section applies only to deck/layout template routes. `page_layouts` selects the input SVG prototype, `pptx_masters` / `pptx_layouts` declare unique reusable output definitions, and `page_pptx_layouts` assigns every generated page before the first page is drawn. Free-design and brand-only routes use `pptx_structure.mode: flat`, omit all four sections, skip the rest of §1.2, and keep every SVG object Slide-local.
**Hard rule — template mode only**: A deck/layout template project uses `pptx_structure.mode: structured`. Missing mode or legacy values (`baseline`, `template`, `preserve`), `layout_strategy`, Layout-kind fields, partial mappings, and old direct placeholders must stop generation and route to [`restore-pptx-structure`](../workflows/restore-pptx-structure.md). `flat` is valid only when no deck/layout template is active.
-**Hard rule — root identity**: A row `P<NN>: <master_key> | <layout_key> | <layout name>` binds the page to a Master listed in `pptx_masters`. Put that Master key/name and Layout key/name on the root SVG. A Layout key belongs to exactly one Master and remains globally unique.
+**Hard rule — root identity**: A `page_pptx_layouts` row binds the page to one key in `pptx_layouts`; that unique definition supplies its Master key, Layout picker name, and prototype source. Put the declared Master key/name and Layout key/name on the root SVG. A Layout key belongs to exactly one Master and remains globally unique.
**Hard rule — atomic fixed layers**: Every `data-pptx-layer="master|layout"` visual is one direct root child that compiles to one DrawingML object. A marked `<g>` is forbidden. When reconstructing source PPTX groups, recursively push supported transforms, paint, opacity, and z-order into atomic children. Repeat the identical ordered Master atom contract on every page using that Master and the identical ordered Layout atom contract on every page sharing that `(master, layout)` pair.
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index 8abdbe7e..eb688902 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -437,7 +437,7 @@ These forms are needed only when the stated PPT behavior matters:
| Stable object grouping or object-level animation anchor | Wrap the intended object in `<g id="...">`. Content grouping is **mandatory** per §4.3 — a top-level `<g id>` is also the animation anchor; it is not an optional convenience. |
| Native PowerPoint background promotion | Use a direct, full-canvas, solid `<rect>` without transform, filter, clip, rounding, or visible stroke. Other SVG backgrounds remain ordinary slide shapes. Template routes add the ownership metadata in §7. |
| Free-design / brand-only PowerPoint structure | Use `pptx_structure.mode: flat`. Keep every represented object Slide-local; export materializes one clean project-owned Master plus one Blank Layout from the current lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. Do not author Master/Layout identities, layers, or placeholder slots. |
-| Reusable template-based PowerPoint Layout | Select one complete input SVG per page in `page_layouts` and declare the output Master/Layout mapping at planning time. Strict preserves the prototype contract; adaptive retains its Master and may assign a new explicit Layout key during page authoring. Non-mirror skin follows `spec_lock`. |
+| Reusable template-based PowerPoint Layout | Select one complete authoring SVG per page in `page_layouts`, declare each unique Master/Layout definition once, and assign pages through `page_pptx_layouts`. Strict preserves the prototype contract; adaptive retains its Master and may define and assign a new explicit Layout key during page authoring. Non-mirror skin follows `spec_lock`. |
**Hard rule — supported shape conversion**: Every PPT editability claim in this specification refers to the project converter reading `svg_output/` and emitting native DrawingML. `svg_final/` is a self-contained visual preview that may be inserted into PowerPoint as an SVG picture. PowerPoint's manual Convert-to-Shape operation is unsupported; do not narrow the authoring contract to its undocumented SVG subset.
@@ -1342,7 +1342,7 @@ defaults to `bottom` and accepts `top`, `left`, or `right`.
### PPTX Structure Routing
-Every new SVG project declares one deterministic route. Free-design and brand-only projects use `pptx_structure.mode: flat`, omit `pptx_masters` / `pptx_layouts` / `page_layouts`, and author no Master/Layout/layer/placeholder metadata. Export keeps all represented content Slide-local while materializing one clean project-owned Master plus one Blank Layout from the current color/typography lock; stock content placeholders and unused built-in Layouts are removed, while the standard date/footer/slide-number capability hooks remain. Deck/layout template projects use `mode: structured`; `standard` / `fidelity` templates use their authored contract, while mirror templates use restored source identities and parentage.
+Every new SVG project declares one deterministic route. Free-design and brand-only projects use `pptx_structure.mode: flat`, omit `pptx_masters` / `pptx_layouts` / `page_pptx_layouts` / `page_layouts`, and author no Master/Layout/layer/placeholder metadata. Export keeps all represented content Slide-local while materializing one clean project-owned Master plus one Blank Layout from the current color/typography lock; stock content placeholders and unused built-in Layouts are removed, while the standard date/footer/slide-number capability hooks remain. Deck/layout template projects use `mode: structured`; `standard` / `fidelity` templates use their authored contract, while mirror templates use restored source identities and parentage.
**Hard rule — no structure inference**: Flat export performs no promotion or deduplication; every object stays Slide-local. Structured template export compiles only declared root identities, atomic fixed layers, and slot groups—it does not assign Layout families, cluster pages, infer placeholders, or repair missing metadata. Legacy structured/template projects must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) first.
@@ -1354,26 +1354,30 @@ Every new SVG project declares one deterministic route. Free-design and brand-on
### Explicit PPTX Master / Layout / Placeholder Metadata
-**Trigger**: This explicit metadata interface applies only to deck/layout template projects and structure-restoration workflows. `spec_lock.md` declares `pptx_structure.mode: structured`, a complete `pptx_masters` roster, one `pptx_layouts` row per page, and `page_layouts` as input-prototype provenance. Flat free-design/brand-only SVGs use none of these metadata fields.
+**Trigger**: This explicit metadata interface applies only to deck/layout template projects and structure-restoration workflows. `spec_lock.md` declares `pptx_structure.mode: structured`, complete unique `pptx_masters` / `pptx_layouts` rosters, one `page_pptx_layouts` assignment per generated page, and `page_layouts` as authoring-prototype provenance. Flat free-design/brand-only SVGs use none of these metadata fields.
-**Project lock**: A Master row is `<master_key>: <PowerPoint picker name>`. A page row is `P<NN>: <master_key> | <layout_key> | <PowerPoint layout name>`. The SVG root values MUST match those rows. A Layout key belongs to exactly one Master and must be globally unique. Reuse one key only when pages share identical ordered Layout atoms and slot ids/types/effective indices/default bounds/binding modes. Every structured route requires numeric `spec_lock.md` typography `title` / `body` rows.
+**Project lock**: A Master row is `<master_key>: <PowerPoint picker name>`. A unique Layout row is `<layout_key>: <master_key> | <PowerPoint picker name> | <prototype source>`, where the source is a generated `P<NN>` or installed `template:<basename>`. A page assignment is `P<NN>: <layout_key>` under `page_pptx_layouts`. The SVG root values MUST match the assigned definition. A Layout key belongs to exactly one Master and must be globally unique. Reuse one key only when prototypes share identical ordered Layout atoms and slot ids/types/effective indices/default bounds/binding modes. An unused Layout uses a template SVG source and remains registered without a published carrier slide. Every structured route requires numeric `spec_lock.md` typography `title` / `body` rows.
**Template behavior**: Strict preserves the selected prototype's declared Master/Layout/slot contract. Adaptive retains its Master and may allocate a new Layout key/name only when fixed Layout atoms or slot topology/bounds change; update the lock during authoring. Mirror-created prototypes preserve restored source identity, literal paint, typography, effects, atomic geometry, and referenced assets. `standard` / `fidelity` never make source topology authoritative; mirror does not synthesize a replacement topology.
**Master text-style contract**: Flat and structured export map the
-locked `title` size to every `a:defRPr` in Master `p:titleStyle`, and map the
-locked `body` size to every level in both `p:bodyStyle` and `p:otherStyle`.
+locked `title` size to every `a:defRPr` in Master `p:titleStyle`. Level 1 in
+both `p:bodyStyle` and `p:otherStyle` uses the locked `body` size; levels 2–9
+use a deterministic descending hierarchy from `15/16` through `8/16` of that
+size, rounded to 0.5 pt and floored at the smaller of 8 pt or the body size.
+Existing per-level indentation and bullet properties remain unchanged.
| Master style | Locked source | XML field changed |
|---|---|---|
| `p:titleStyle` | `typography.title` | Every `a:defRPr@sz` |
-| `p:bodyStyle` | `typography.body` | Every `a:defRPr@sz` |
-| `p:otherStyle` | `typography.body` | Every `a:defRPr@sz` |
+| `p:bodyStyle` | `typography.body` | Level 1 plus derived level 2–9 `a:defRPr@sz` |
+| `p:otherStyle` | `typography.body` | Level 1 plus derived level 2–9 `a:defRPr@sz` |
**Hard rule — narrow scope**: This Master update changes only Master
-`p:txStyles//a:defRPr@sz`. It does not rewrite direct run sizes on generated
-slides, so the initial slide rendering remains controlled by the authored SVG.
-Missing `title` or `body` rows fail flat or structured export.
+`p:txStyles//a:defRPr@sz`; it preserves level indentation, bullet, margin, and
+paragraph settings. It does not rewrite direct run sizes on generated slides,
+so the initial slide rendering remains controlled by the authored SVG. Missing
+`title` or `body` rows fail flat or structured export.
**Layout level-one text-default contract**: For every text-bearing placeholder
whose first prototype run has a direct `a:rPr@sz`, explicit Layout export copies that
@@ -1444,15 +1448,14 @@ Because an omitted `p:ph@idx` has the effective value `0`, an omitted-index
title reserves `0`; no other placeholder on that Layout may use the same
effective index.
-**Slot prototype**: The first slide using a Layout key supplies that Layout's placeholder formatting. `data-pptx-placeholder-bounds` supplies the reusable default frame and is mandatory on every slot. Derive it from
+**Slot prototype**: The prototype source declared by the unique Layout definition supplies that Layout's placeholder formatting. `data-pptx-placeholder-bounds` supplies the reusable default frame and is mandatory on every slot. Derive it from
the intended design zone, column, panel inset, safe area, or picture frame —
never from text length, glyph width, line count, or a tight content bounding
box. Repeat the same slot ids/types/effective indices/default bounds/binding modes on every slide using that Layout. The Layout owns the reusable `p:ph`; normal visible carriers keep a matching Slide binding so approved rendering stays identical. A composite `object` proxy adds one hidden transparent binding shape to suppress empty inherited placeholder paint. Bounds define the Layout default only; actual Slide content and local carrier geometry may differ.
**Final-package read-back gate**: After writing a temporary structured PPTX and before publishing it, export reopens the package and
-verifies that
-each Slide targets exactly one Layout, one layout key always resolves to the
-same part, different keys do not collapse onto one part, and every Layout is
+verifies that each published Slide targets exactly one Layout, one Layout key always resolves to the
+same part, different keys do not collapse onto one part, and every declared Layout—including one unused by all published Slides—is
registered through its Master and the Presentation. Physical Slide/Layout/
Master part rosters, their content-type overrides, and their Presentation/
Master registrations must be exact. It also verifies the Layout picker name,
@@ -1481,7 +1484,7 @@ video or audio media from a decorative SVG group.
Existing structured/template projects or packages that carry `native_structure.json` / `source_template.pptx`, `pptx_structure.mode: baseline|template|preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled` / `utility`, direct atomic placeholders, or an incomplete root Master identity must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before generation or export. A project explicitly declaring `pptx_structure.mode: flat` is the current free-design/brand-only route and does not require restoration merely because it has no Master/Layout metadata.
-When original PPTX/native facts exist, migration preserves the reachable source Master roster, Layout parent relationships and picker names, placeholder type/index/bounds, and visible supported geometry while normalizing the package into the explicit contract. Source Master/Layout groups are recursively flattened into atomic SVG elements. The current structured roster cannot materialize a source Layout that no output page references, or a Master reachable only through such Layouts; stop and report those identities instead of silently dropping them or inventing a carrier page. A subsequent `create-template` run treats the result according to its selected mode: `standard` / `fidelity` author a new topology, while mirror keeps the restored source topology only when the source graph satisfies that reachability boundary. When no native facts exist, the main Agent explicitly derives a structured contract from the complete SVG pages; the exporter never performs that derivation.
+When original PPTX/native facts exist, migration preserves the complete source Master roster, Layout parent relationships and picker names, placeholder type/index/bounds, and visible supported geometry while normalizing the package into the explicit contract. Source Master/Layout groups are recursively flattened into atomic SVG elements. Create one reusable prototype SVG for every retained Layout, including Layouts unused by source slides; downstream `pptx_layouts` definitions can register those prototypes without manufacturing generated pages. A subsequent `create-template` run treats the result according to its selected mode: `standard` / `fidelity` author a new topology, while mirror keeps the restored source topology. When no native facts exist, the main Agent explicitly derives a structured contract from the complete SVG pages; the exporter never performs that derivation.
---
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 86bb4bdc..f40c0982 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -847,19 +847,20 @@ This is what makes the axis meaningful: a `presentation` deck and a `text` deck
1. Read reference template: `templates/design_spec_reference.md`
2. Generate complete spec from scratch based on analysis
3. Save to: `projects/<project_name>.../design_spec.md`
-4. **Generate execution lock**: read `templates/spec_lock_reference.md` and produce `projects/<project_name>.../spec_lock.md` — a compact, machine-readable form of the color / typography / icon / image / **page_rhythm** / **page_charts** and route-specific PowerPoint structure decisions above. Within the PowerPoint structure portion, free-design and brand-only routes write only `pptx_structure.mode: flat`; deck/layout template routes additionally write `page_layouts`, `pptx_masters`, and `pptx_layouts`. This file is what the Executor re-reads before every page (see [executor-base.md](executor-base.md) §2.1). The values in `spec_lock.md` MUST exactly match the decisions recorded in `design_spec.md`; if they ever diverge, `spec_lock.md` wins and `design_spec.md` should be treated as historical narrative.
+4. **Generate execution lock**: read `templates/spec_lock_reference.md` and produce `projects/<project_name>.../spec_lock.md` — a compact, machine-readable form of the color / typography / icon / image / **page_rhythm** / **page_charts** and route-specific PowerPoint structure decisions above. Within the PowerPoint structure portion, free-design and brand-only routes write only `pptx_structure.mode: flat`; deck/layout template routes additionally write `page_layouts`, `page_pptx_layouts`, `pptx_masters`, and `pptx_layouts`. This file is what the Executor re-reads before every page (see [executor-base.md](executor-base.md) §2.1). The values in `spec_lock.md` MUST exactly match the decisions recorded in `design_spec.md`; if they ever diverge, `spec_lock.md` wins and `design_spec.md` should be treated as historical narrative.
- **page_rhythm is mandatory**: Based on the page list in §IX Content Outline, assign each page one of `anchor` / `dense` / `breathing` (see `spec_lock_reference.md` for the full vocabulary). This is what breaks the uniform "every page is a card grid" feel — without it the Executor defaults all pages to `dense`.
- **Rhythm follows narrative, not quota**: `breathing` pages mark natural pauses — chapter transitions, standalone emphasis (hero quote / big number), SCQA bridges. Dense decks may legitimately be all `dense`. **Do NOT invent filler pages** ("Thank you", empty dividers) to pad rhythm — every `breathing` page must say something independent. Delivery purpose biases the overall lean (`presentation` toward more `anchor` / `breathing`, `text` toward `dense`; see §6.1) — a bias, never a quota.
- **Cover impact is mandatory**: Page `P01` is the deck's first visual contract, not a generic title slide. In `design_spec.md §IX`, add a `Cover impact` line for `P01` that names one concrete hook and one concrete composition strategy. Use the source's strongest available signal: a provocative core claim, object / scene metaphor, hero number, founder / product / audience moment, or a distilled conflict. Pair it with one concrete composition strategy — such as `full-bleed image + floating title`, `typographic poster`, `hero object`, `data hook`, `editorial scene`, `high-contrast abstract geometry`, or a fresh composition the deck's subject suggests (these are starting points, not the allowed set). If no external or AI image is available, still specify a native-SVG visual hook; do not fall back to "title + subtitle + decorative background". (Beautify / template-fill keep the source cover verbatim — this rule does not apply on those preservation paths.)
- **Cover rhythm lock**: `P01` remains `anchor` in `spec_lock.md page_rhythm`, but its §IX `Cover impact` must prevent content-page patterns. Do not plan multi-card grids, agenda-like bullets, or equal-weight columns on the cover unless a template explicitly requires that structure, or a preservation path (beautify / template-fill) is transcribing the source cover verbatim.
- **Closing impact (only when the deck closes)**: the deck's last page is its final visual contract — the strongest impression after the cover. When the deck genuinely lands on a conclusion / call-to-action / final-takeaway page, give it a `Closing impact` line in §IX: name the one thing the audience should leave with (a distilled takeaway, a forward call, a memorable restatement of the core claim) + one composition that delivers it — never a generic "Thank you" / contact-only slide or a centered-title reprise of the cover. **Do NOT invent a closing page to satisfy this** — the filler-page ban above still holds; apply it only to the page where the deck actually resolves. Same exemptions as the cover: skip on template / beautify / template-fill preservation paths.
- **pptx_structure is mandatory**: Free-design and brand-only routes write `mode: flat`. Deck/layout template routes write `mode: structured` plus `template_adherence: strict|adaptive`. Do not write legacy `baseline`, `template`, `preserve`, `layout_strategy`, or Layout-kind rows into a new project.
- - **Flat-route boundary**: With `mode: flat`, omit the complete `pptx_masters`, `pptx_layouts`, and `page_layouts` sections. Do not plan native Master/Layout families or reusable placeholder slots. Every generated SVG object remains Slide-local: omit root Master/Layout identity, `data-pptx-layer`, and `data-pptx-placeholder*` metadata. Export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks.
+ - **Flat-route boundary**: With `mode: flat`, omit `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`. Do not plan native Master/Layout families or reusable placeholder slots. Every generated SVG object remains Slide-local: omit root Master/Layout identity, `data-pptx-layer`, and `data-pptx-placeholder*` metadata. Export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks.
- **Master roster (deck/layout templates only)**: Write one `pptx_masters` row per Master as `<master_key>: <picker name>` and copy the restored prototype roster. Master visuals are root-level atomic elements and may never be `<g>`.
- - **pptx_layouts (deck/layout template output contract)**: Write exactly one row per page before generation as `<master_key> | <layout_key> | <PowerPoint layout name>`. Plan semantic Layout families from the outline and reuse a key only when fixed Layout atoms plus slot ids/types/indices/bounds/binding modes are identical. Name each key after its composition (`timeline-spine`, `kpi-band-trio`, `content-image-right`), never after a PowerPoint stock role or the page's topic. A Layout may intentionally have zero slots; never manufacture an empty `utility` kind or full-page fake slot. **Self-check before writing the section**: compare distinct keys against the distinct compositions in §IX. Distinct compositions collapsing into a handful of stock-role keys (`cover` / `title-content` / `section`) means pages were clustered by role; one shared skeleton splitting into per-topic keys (`allocation-fengqing` / `allocation-luoping`) means pages were split by topic. Both misstate the roster — re-derive from composition.
+ - **pptx_layouts (deck/layout template reusable roster)**: Write every unique reusable Layout once as `<layout_key>: <master_key> | <PowerPoint layout name> | <prototype source>`. Copy the installed template roster with `template:<basename>` sources, including Layouts no generated page currently uses. A genuinely new adaptive Layout uses its first generated `P<NN>` as the source. Reuse a key only when fixed Layout atoms plus slot ids/types/indices/bounds/binding modes are identical. Name authored keys after composition (`timeline-spine`, `kpi-band-trio`, `content-image-right`), never after page topic. A Layout may intentionally have zero slots; never manufacture an empty `utility` kind or full-page fake slot.
+ - **page_pptx_layouts (deck/layout template page assignment)**: Write exactly one `P<NN>: <layout_key>` row per generated page. The key must exist in `pptx_layouts`; Master and picker name are inherited from that unique definition. **Self-check before writing the section**: compare distinct assigned keys against distinct compositions in §IX. Distinct compositions collapsing into a handful of role-only keys means pages were clustered by topic label; one shared skeleton splitting into topic-specific keys means pages were split by content wording. Both misstate the roster.
- **Slot planning (deck/layout templates only)**: Each reusable slot is a direct root `<g id>` with `data-pptx-placeholder`, positive design-zone bounds, and exactly one compatible direct carrier. Bounds come from the intended safe area, column, panel inset, or media frame—not sample text ink. A genuinely composite region may use only the explicit `object` + `proxy` downgrade.
- - **Adaptive refinement boundary (deck/layout templates only)**: The initial mapping is complete, not provisional. If actual adaptive construction genuinely changes reusable framing or slot topology/bounds, Executor creates a new Layout key and updates `spec_lock.md` while authoring that first page. It never mutates a reused contract silently. Export only compiles declared structure and never discovers or clusters Layouts.
- - **page_layouts (deck/layout templates only)**: Add one `P<NN>: <svg_basename>` row for every page. This is the complete input-prototype mapping. Strict preserves that SVG's structural contract; adaptive keeps its Master and may explicitly assign a new output Layout identity during page authoring. Omit the whole section for free-design and brand-only routes.
+ - **Adaptive refinement boundary (deck/layout templates only)**: The initial definitions and assignments are complete, not provisional. If actual adaptive construction genuinely changes reusable framing or slot topology/bounds, Executor creates one new `pptx_layouts` definition sourced from that page and updates its `page_pptx_layouts` assignment while authoring the first page. It never mutates a reused contract silently. Export only compiles declared structure and never discovers or clusters Layouts.
+ - **page_layouts (deck/layout templates only)**: Add one `P<NN>: <svg_basename>` row for every page. This is the complete authoring-input prototype mapping. Strict preserves that SVG's structural contract; adaptive keeps its Master and may explicitly define and assign a new output Layout identity during page authoring. Omit the whole section for free-design and brand-only routes.
- **page_charts (write only for chart pages that match a catalog template)**: For each page in `design_spec.md §VII` whose `reference template path` points to `templates/charts/<name>.svg`, add `P<NN>: <chart_name>`. Pages with `no-template-match` in §VII MUST NOT appear here (Executor would look for a non-existent reference). If the deck has no data-visualization pages, omit the section.
- **Hard rule**: Use both `page_layouts` and `page_charts` only with a compatible template shell. For a chart page without an exact roster match, adaptive mode selects the closest neutral input prototype and assigns an explicit output Layout key in the planning map; strict mode must select an existing compatible Layout or revise the outline. Never omit `page_layouts` inside a new deck/layout template route.
diff --git a/skills/ppt-master/references/template-designer.md b/skills/ppt-master/references/template-designer.md
index 15ffde6d..070eea6a 100644
--- a/skills/ppt-master/references/template-designer.md
+++ b/skills/ppt-master/references/template-designer.md
@@ -58,14 +58,14 @@ Use `summary.md` only for orientation. Open screenshots or the original PPTX onl
Every page remains a complete standalone SVG preview.
-**Hard rule — mirror graph reachability**: The current structured template
-compiler materializes only Master/Layout identities referenced by emitted SVG
-prototypes. Before accepting `mirror`, verify that every source Layout has a
-non-empty `usedBySlides` set and that every source Master owns at least one such
-Layout. If the source package contains an unused Layout or an otherwise
-unreachable Master, stop and report that full-graph mirror is not representable
-by the current template roster. Never silently drop it, merge it, or invent a
-carrier page.
+**Hard rule — complete mirror graph**: Restore every supported source Layout,
+including Layouts unused by source Slides. Emit one complete source-page
+prototype per source Slide and one definition-only
+`layout_<layout_key>.svg` prototype for each otherwise unrepresented Layout.
+The definition prototype carries the exact parent Master identity, Layout
+identity, fixed atoms, and placeholder contract but is not a generated page.
+This also retains a source Master that is reachable only through unused Layouts.
+Never silently drop or merge an identity, and never invent a carrier page.
**Hard rule — no duplicate authored Layout contracts**: In `standard` / `fidelity`, distinct output Layout keys must differ in fixed Layout atoms or slot topology/type/index/bounds/binding. Topic, sample wording, or Slide-local content alone never justifies another authored key. Mirror keeps source Layout identities even when two source contracts are visibly equivalent.
@@ -129,12 +129,12 @@ Extension page types beyond the canonical four (transition / appendix / disclaim
When the brief sets `Replication mode: mirror`, restore the imported template rather than designing a new one:
- Restoration source: lossless `svg/master_*.svg`, `svg/layout_*.svg`, `svg/slide_NN.svg`, `svg-flat/slide_NN.svg`, `svg/inheritance.json`, and `native_structure.json`. Use matching lightweight projections only to inspect the result without loading opaque payload into model context.
-- Precondition: every source Layout is referenced by at least one source slide, and every source Master is reachable through those referenced Layouts. Otherwise report that full-graph mirror is currently unsupported and stop before writing output.
-- Output: `<template_workspace>/templates/<NNN>_<page_type>.svg` in both scopes. `<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.
+- Precondition: the import evidence identifies every source Master/Layout, parent relationship, picker name, placeholder contract, and fixed visual layer. Stop only when required facts or supported geometry are missing; unused identities are not a stop condition.
+- Output: `<template_workspace>/templates/<NNN>_<page_type>.svg` for every source slide, plus `layout_<layout_key>.svg` for every source Layout unused by all source slides. `<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; definition-only files are not generated pages.
- Required restoration: preserve source Master/Layout keys and picker names, Layout-to-Master parentage, slide assignments, placeholder type/index/bounds, supported native-object metadata, geometry, decoration, sprite-sheet wrappers, original example text, chart previews, fonts, effects, and paint order whenever the importer represents them.
- Allowed normalization: add or normalize explicit root declarations and asset paths, and recursively expand fixed Master/Layout group wrappers into direct atoms. The mapping must remain one-to-one at the ownership level and must not change paint order or appearance.
- Forbidden: commonality extraction, semantic synthesis, merging, splitting, promotion, demotion, renaming, re-parenting, decorative simplification, placeholder invention, or replacement of supported source-native metadata / SVG fallback with a model-authored approximation.
-- `design_spec.md` §V Page Roster lists every emitted file, and `Source Restoration Map` records the preserved source Master/Layout assignment.
+- `design_spec.md` §V Page Roster lists every emitted file and marks definition-only prototypes explicitly. `Source Restoration Map` records each source-slide assignment plus every unused Layout definition and its parent Master.
**Mirror consumption boundary**: `mirror` applies only while creating the template package from the source deck. Once created, the package is consumed as an ordinary deck / layout template roster: downstream generation may select, repeat, skip, reorder, or adapt pages according to the new content. The `replication_mode: mirror` field must not force the generated deck to preserve the source page count, source order, or one-output-slide-per-template-slide mapping.
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index da1667bf..f8bba05d 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -148,11 +148,11 @@ 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.
-Native `svg_to_pptx.py` release export reads the project's explicit structure mode. Free-design and brand-only projects use `flat`, omit Master/Layout mappings and SVG structure metadata, keep every represented object Slide-local, and materialize one clean project-owned Master plus one Blank Layout from the current color/typography lock. Stock content placeholders and unused built-in Layouts are removed; only the standard date/footer/slide-number capability hooks remain. Deck/layout template projects use `structured`: each such project supplies a complete Master roster and page-to-Master/Layout mapping before SVG generation, and every SVG root repeats that identity. Fixed Master/Layout visuals are direct atomic children; reusable slots are top-level groups with positive design-zone bounds plus one compatible carrier. Composite `object` regions use explicit proxy binding, and zero-slot Layouts are valid.
+Native `svg_to_pptx.py` release export reads the project's explicit structure mode. Free-design and brand-only projects use `flat`, omit Master/Layout mappings and SVG structure metadata, keep every represented object Slide-local, and materialize one clean project-owned Master plus one Blank Layout from the current color/typography lock. Stock content placeholders and unused built-in Layouts are removed; only the standard date/footer/slide-number capability hooks remain. Deck/layout template projects use `structured`: each project supplies unique Master/Layout definitions and one Layout assignment per generated page before SVG generation, and every SVG root repeats its assigned identity. A template-backed definition may remain unused and still register without a published carrier slide. Fixed Master/Layout visuals are direct atomic children; reusable slots are top-level groups with positive design-zone bounds plus one compatible carrier. Composite `object` regions use explicit proxy binding, and zero-slot Layouts are valid.
Structured template export compiles only the declared structure, maps locked typography/colors into PowerPoint defaults, creates the named Master/Layout parts, and reads the package back before publication. It never clusters pages, promotes repeated chrome heuristically, or invents placeholders. Flat export is the normal free-design/brand-only route: it creates only the clean project-owned shell and performs no promotion or deduplication of Slide content.
-Template `page_layouts` records input provenance. Strict preserves its Master/Layout/slot contract; adaptive retains its Master and may use a new Layout key only when fixed Layout atoms or slot topology/bounds change. `standard` / `fidelity` author new SVGs and a new Master/Layout/slot contract. `mirror` restores the source identities and parentage without semantic synthesis, while mechanically expanding fixed-layer group wrappers into the direct atoms required by the structured contract.
+Template `page_layouts` records authoring-input provenance, `pptx_masters` / `pptx_layouts` own unique reusable definitions, and `page_pptx_layouts` owns page assignment. Strict preserves its Master/Layout/slot contract; adaptive retains its Master and may use a new Layout key only when fixed Layout atoms or slot topology/bounds change. `standard` / `fidelity` author new SVGs and a new Master/Layout/slot contract. `mirror` restores the complete source identity graph—including unused Layout definitions—without semantic synthesis, while mechanically expanding fixed-layer group wrappers into the direct atoms required by the structured contract.
Legacy structured/template contracts using `baseline`, `template`, `preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, or incomplete root Master identity must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before release export. Explicit flat free-design/brand-only projects intentionally omit root Master identity.
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 523f1d95..1fdd9804 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -101,7 +101,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`. Free-design and brand-only releases declare `mode: flat`, omit Master/Layout mappings and SVG structure metadata, and materialize one clean project-owned Master plus one Blank Layout from the current lock. Deck/layout template releases declare `mode: structured` with a complete `pptx_masters` roster and one `pptx_layouts` row per page.
+- Omitting `--pptx-structure` reads `spec_lock.md`. Free-design and brand-only releases declare `mode: flat`, omit Master/Layout mappings and SVG structure metadata, and materialize one clean project-owned Master plus one Blank Layout from the current lock. Deck/layout template releases declare `mode: structured` with complete unique `pptx_masters` / `pptx_layouts` rosters and one `page_pptx_layouts` assignment per page. A template-backed Layout definition may remain unused by pages and still register in the final package.
- On structured template routes, every page root repeats Master/Layout keys and picker names. Master/Layout fixed visuals are direct atomic children; layer `<g>` elements are invalid.
- On structured template routes, each normal slot is a direct root `<g id>` with semantic type, positive design-zone bounds, and exactly one compatible carrier. Composite `object` slots use explicit proxy binding; zero-slot Layouts are valid. Flat pages keep all SVG objects Slide-local.
- Flat export maps locked typography/colors into a clean project-owned theme/Master, removes stock content placeholders and unused built-in Layouts, retains only the standard date/footer/slide-number capability hooks, and keeps one Blank Layout without promoting Slide content. Structured export additionally creates one reusable Layout per declared key and reopens the package to verify the full Presentation → Master → Layout → Slide graph, fixed-object order, placeholder identities/bounds, carrier bindings, hidden proxies, and zero-slot Layouts.
diff --git a/skills/ppt-master/scripts/register_template.py b/skills/ppt-master/scripts/register_template.py
index 68cf929e..103657cc 100644
--- a/skills/ppt-master/scripts/register_template.py
+++ b/skills/ppt-master/scripts/register_template.py
@@ -43,8 +43,10 @@ import re
import sys
from collections import OrderedDict
from pathlib import Path
+from xml.etree import ElementTree as ET
from console_encoding import configure_utf8_stdio
+from config import CANVAS_FORMATS
try:
import yaml # type: ignore
@@ -342,6 +344,140 @@ def _validate_brand_spec(
raise SpecParseError(f"invalid brand specification:\n{details}")
+def _validate_svg_template_spec(
+ kind: str,
+ template_id: str,
+ template_dir: Path,
+ frontmatter: dict,
+ pages: list[str],
+) -> None:
+ """Reject Layout/Deck workspaces whose registry facts drift from SVGs."""
+ errors: list[str] = []
+ id_key = KIND_CONFIG[kind]["id_key"]
+ declared_id = str(frontmatter.get(id_key) or "").strip()
+ if declared_id != template_id:
+ errors.append(
+ f"frontmatter {id_key} must match directory {template_id!r}, "
+ f"got {declared_id!r}"
+ )
+ declared_kind = str(frontmatter.get("kind") or "").strip()
+ if declared_kind != kind:
+ errors.append(
+ f"frontmatter kind must be {kind!r}, got {declared_kind!r}"
+ )
+ if not str(frontmatter.get("summary") or "").strip():
+ errors.append("frontmatter summary must be non-empty")
+ if not pages:
+ errors.append(f"{kind} workspace must contain at least one template SVG")
+
+ raw_page_count = frontmatter.get("page_count")
+ if isinstance(raw_page_count, bool) or not isinstance(raw_page_count, int):
+ errors.append("frontmatter page_count must be an integer")
+ elif raw_page_count != len(pages):
+ errors.append(
+ f"frontmatter page_count is {raw_page_count}, but templates/ "
+ f"contains {len(pages)} SVG files"
+ )
+
+ canvas_format = str(frontmatter.get("canvas_format") or "").strip()
+ canvas = CANVAS_FORMATS.get(canvas_format)
+ if canvas is None:
+ errors.append(
+ "frontmatter canvas_format must be one of: "
+ + ", ".join(sorted(CANVAS_FORMATS))
+ )
+ else:
+ expected_canvas_fields = {
+ "canvas_width": canvas["width"],
+ "canvas_height": canvas["height"],
+ "canvas_viewbox": canvas["viewbox"],
+ }
+ for field, expected in expected_canvas_fields.items():
+ actual = frontmatter.get(field)
+ if str(actual) != str(expected):
+ errors.append(
+ f"frontmatter {field} must be {expected!r} for "
+ f"{canvas_format}, got {actual!r}"
+ )
+
+ if frontmatter.get("native_structure_mode") != "structured":
+ errors.append(
+ "frontmatter native_structure_mode must be 'structured'"
+ )
+ if frontmatter.get("replication_mode") not in {
+ "standard",
+ "fidelity",
+ "mirror",
+ }:
+ errors.append(
+ "frontmatter replication_mode must be standard, fidelity, or mirror"
+ )
+
+ if kind == "layout":
+ raw_page_types = frontmatter.get("page_types")
+ expected_page_types = _derive_page_types(pages)
+ if not isinstance(raw_page_types, list) or not all(
+ isinstance(item, str) and item.strip()
+ for item in raw_page_types
+ ):
+ errors.append("frontmatter page_types must be a non-empty string list")
+ elif raw_page_types != expected_page_types:
+ errors.append(
+ "frontmatter page_types must exactly match the SVG filename "
+ f"roster: expected {expected_page_types!r}, got {raw_page_types!r}"
+ )
+ else:
+ primary_color = str(frontmatter.get("primary_color") or "").strip()
+ if _HEX_COLOR_RE.fullmatch(primary_color) is None:
+ errors.append(
+ "frontmatter primary_color must use #RRGGBB, "
+ f"got {primary_color!r}"
+ )
+
+ svg_paths = [template_dir / f"{page}.svg" for page in pages]
+ if canvas is not None:
+ expected_viewbox = str(canvas["viewbox"])
+ for svg_path in svg_paths:
+ try:
+ root = ET.parse(svg_path).getroot()
+ except (OSError, ET.ParseError) as exc:
+ errors.append(f"{svg_path.name} is not valid SVG XML: {exc}")
+ continue
+ actual_canvas = (
+ root.get("width"),
+ root.get("height"),
+ root.get("viewBox"),
+ )
+ expected_canvas = (
+ str(canvas["width"]),
+ str(canvas["height"]),
+ expected_viewbox,
+ )
+ if actual_canvas != expected_canvas:
+ errors.append(
+ f"{svg_path.name} canvas is {actual_canvas!r}, expected "
+ f"{expected_canvas!r}"
+ )
+
+ if svg_paths:
+ try:
+ from svg_to_pptx.pptx_package.template_structure import (
+ TemplateStructureError,
+ parse_template_slides,
+ )
+ except ImportError as exc:
+ errors.append(f"structured SVG roster is invalid: {exc}")
+ else:
+ try:
+ parse_template_slides(svg_paths)
+ except TemplateStructureError as exc:
+ errors.append(f"structured SVG roster is invalid: {exc}")
+
+ if errors:
+ details = "\n".join(f" - {error}" for error in errors)
+ raise SpecParseError(f"invalid {kind} specification:\n{details}")
+
+
# ---------------------------------------------------------------------------
# Per-kind extraction
# ---------------------------------------------------------------------------
@@ -388,20 +524,32 @@ def _extract_entry(kind: str, template_id: str, template_dir: Path) -> dict:
primary_color=str(primary_color),
)
elif kind == "layout":
- page_types = fm.get("page_types") or _derive_page_types(pages)
- if isinstance(page_types, str):
- page_types = [t.strip() for t in re.split(r"[,,]", page_types) if t.strip()]
+ _validate_svg_template_spec(
+ kind,
+ template_id,
+ template_dir,
+ fm,
+ pages,
+ )
+ page_types = fm["page_types"]
entry = OrderedDict(
summary=summary,
- canvas_format=str(fm.get("canvas_format", "ppt169")),
- page_count=int(fm.get("page_count", len(pages))),
+ canvas_format=str(fm["canvas_format"]),
+ page_count=int(fm["page_count"]),
page_types=list(page_types),
)
elif kind == "deck":
+ _validate_svg_template_spec(
+ kind,
+ template_id,
+ template_dir,
+ fm,
+ pages,
+ )
entry = OrderedDict(
summary=summary,
- canvas_format=str(fm.get("canvas_format", "ppt169")),
- page_count=int(fm.get("page_count", len(pages))),
+ canvas_format=str(fm["canvas_format"]),
+ page_count=int(fm["page_count"]),
primary_color=str(primary_color),
)
else:
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.py
index 8684f410..48c08494 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -239,12 +239,9 @@ HEX_VALUE_RE = re.compile(
# authority. Flat projects only receive the negative guard that rejects authored
# structure metadata. Template roster/placeholder checks always run. Current
# bundled templates opt in to complete structure validation through their
-# native_structure_mode: structured declaration.
+# native_structure_mode: structured declaration. Legacy template-mode packages
+# fail closed and must run the explicit restoration workflow.
_CHECK_PPTX_STRUCTURED_PROJECT = True
-_CHECK_PPTX_TEMPLATE_MODE = False
-# Compatibility hook for historical packages. The bundled library has no
-# remaining structure-validation exemptions.
-_BUNDLED_LEGACY_TEMPLATE_DIRS = frozenset()
_BARE_HEX_VALUE_RE = re.compile(
r"(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})"
@@ -653,33 +650,9 @@ def _declared_template_structure_mode(target_path: Path) -> str | None:
return match.group(1).lower() if match else None
-def _is_bundled_legacy_template(target_path: Path) -> bool:
- """Return whether a template is in the explicit bundled migration set."""
- directory = target_path.parent if target_path.is_file() else target_path
- library_root = Path(__file__).resolve().parents[1] / 'templates'
- try:
- relative_path = directory.resolve().relative_to(library_root.resolve())
- except ValueError:
- return False
- return relative_path.as_posix() in _BUNDLED_LEGACY_TEMPLATE_DIRS
-
-
-def _legacy_template_structure_deferred(target_path: Path) -> bool:
- """Return whether a known bundled legacy template may defer structure."""
- return bool(
- not _CHECK_PPTX_TEMPLATE_MODE
- and _declared_template_structure_mode(target_path) == 'template'
- and _is_bundled_legacy_template(target_path)
- )
-
-
def _template_structure_checks_enabled(target_path: Path) -> bool:
"""Return whether positive structure checks apply to this template."""
- declared_mode = _declared_template_structure_mode(target_path)
- return bool(
- declared_mode == 'structured'
- or (_CHECK_PPTX_TEMPLATE_MODE and declared_mode == 'template')
- )
+ return _declared_template_structure_mode(target_path) == 'structured'
def _local_name(elem: ET.Element) -> str:
@@ -2606,12 +2579,6 @@ class SVGQualityChecker:
if self.template_mode:
check_structure = _template_structure_checks_enabled(dir_path)
- if _legacy_template_structure_deferred(dir_path):
- print(
- "[INFO] Legacy native_structure_mode: template detected; "
- "roster and placeholder checks remain active while positive "
- "structure checks await library migration."
- )
if check_structure:
self._check_pptx_structure_contract(dir_path, svg_files)
if dir_path.is_dir():
@@ -2810,18 +2777,31 @@ class SVGQualityChecker:
master.master_key: master.master_name
for master in structure_lock.masters
}
+ definitions = {
+ definition.layout_key: definition
+ for definition in structure_lock.layout_definitions
+ }
errors: List[str] = []
for spec in specs:
page = f"P{spec.slide_num:02d}"
reference = references.get(spec.slide_num)
if reference is None:
- errors.append(f"spec_lock.md pptx_layouts is missing {page}")
+ errors.append(
+ f"spec_lock.md page_pptx_layouts is missing {page}"
+ )
+ continue
+ definition = definitions.get(reference.layout_key)
+ if definition is None:
+ errors.append(
+ f"spec_lock.md pptx_layouts is missing Layout "
+ f"{reference.layout_key!r}"
+ )
continue
- if spec.master_key != reference.master_key:
+ if spec.master_key != definition.master_key:
errors.append(
f"{spec.svg_path.name}: data-pptx-master={spec.master_key!r} "
- f"does not match spec_lock {page} Master key "
- f"{reference.master_key!r}"
+ f"does not match spec_lock Layout {reference.layout_key!r} "
+ f"Master key {definition.master_key!r}"
)
if spec.layout_key != reference.layout_key:
errors.append(
@@ -2829,11 +2809,11 @@ class SVGQualityChecker:
f"does not match spec_lock {page} layout key "
f"{reference.layout_key!r}"
)
- if spec.layout_name != reference.layout_name:
+ if spec.layout_name != definition.layout_name:
errors.append(
f"{spec.svg_path.name}: data-pptx-layout-name="
- f"{spec.layout_name!r} does not match spec_lock {page} "
- f"layout name {reference.layout_name!r}"
+ f"{spec.layout_name!r} does not match spec_lock Layout "
+ f"{reference.layout_key!r} name {definition.layout_name!r}"
)
expected_master_name = master_names.get(spec.master_key)
if expected_master_name != spec.master_name:
@@ -3429,8 +3409,8 @@ class SVGQualityChecker:
stale roster will produce a wrong ``layouts_index.json`` entry.
- **Explicit structure gaps** are errors when positive structure checks
are enabled: every current reusable SVG declares its Master and Layout
- identity. Zero-placeholder Layouts are valid. Legacy library templates
- still receive roster and placeholder checks while awaiting migration.
+ identity. Zero-placeholder Layouts are valid. Legacy template-mode
+ packages fail and must run the structure-restoration workflow.
- **Placeholder gaps** are reported as *warnings*. Templates may
legitimately omit conventional placeholders or swap them out (e.g.
``{{CLOSING_MESSAGE}}`` instead of ``{{THANK_YOU}}``), and a content
@@ -3444,26 +3424,15 @@ class SVGQualityChecker:
spec_path = dir_path / 'design_spec.md'
spec_text = spec_path.read_text(encoding='utf-8') if spec_path.exists() else ""
declared_structure_mode = _declared_template_structure_mode(dir_path)
- legacy_structure_deferred = _legacy_template_structure_deferred(dir_path)
mode_error_recorded = False
- if declared_structure_mode != 'structured' and not legacy_structure_deferred:
+ if declared_structure_mode != 'structured':
mode_error_recorded = True
- if declared_structure_mode == 'template':
- mode_error = (
- "legacy native_structure_mode: template is accepted only for "
- "the explicit bundled-library migration set; restore this "
- "workspace to native_structure_mode: structured"
- )
- else:
- mode_error = (
- "design_spec.md frontmatter must declare "
- "native_structure_mode: structured; only the explicit bundled "
- "legacy migration set may temporarily declare template"
- )
self._template_issues.append((
'error',
'explicit_structure_mode',
- mode_error,
+ "design_spec.md frontmatter must declare "
+ "native_structure_mode: structured; legacy template-mode "
+ "workspaces must run restore-pptx-structure",
))
if check_structure:
native_contract_path = dir_path / 'native_structure.json'
@@ -3583,15 +3552,9 @@ class SVGQualityChecker:
))
elif spec_path.exists():
# design_spec.md is present but the roster parser found nothing —
- # current structured templates fail closed; allowlisted legacy
- # library specs retain the historical warning until migration.
- severity = (
- 'error'
- if declared_structure_mode == 'structured'
- else 'warning'
- )
+ # reusable template workspaces always fail closed.
self._template_issues.append((
- severity,
+ 'error',
'roster_unknown',
f"could not extract page roster from {spec_path.name}; "
"skipping orphan/missing checks",
@@ -4075,8 +4038,8 @@ def print_usage() -> None:
print(" always enforce roster consistency and emit placeholder hints.")
print(" native_structure_mode: structured also enables complete")
print(" per-file and cross-page structure validation. Legacy")
- print(" native_structure_mode: template defers only those structure")
- print(" checks until the bundled template library is migrated.")
+ print(" native_structure_mode: template fails and must run")
+ print(" restore-pptx-structure before validation.")
def main() -> None:
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml/theme_fonts.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml/theme_fonts.py
index 3a7815a7..4e00da36 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml/theme_fonts.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml/theme_fonts.py
@@ -53,6 +53,17 @@ class MasterTextStyleSpec:
title_hpt: int
body_hpt: int
+ @property
+ def body_levels_hpt(self) -> tuple[int, ...]:
+ """Return a deterministic nine-level PowerPoint body-size hierarchy."""
+ factors = (16, 15, 14, 13, 12, 11, 10, 9, 8)
+ minimum = min(self.body_hpt, 800)
+ sizes = []
+ for factor in factors:
+ scaled = round((self.body_hpt * factor / 16) / 50) * 50
+ sizes.append(max(minimum, scaled))
+ return tuple(sizes)
+
def _font_face(font_family: str) -> ThemeFontFace:
fonts = parse_font_family(font_family)
@@ -213,6 +224,24 @@ def _style_run_properties(style: ET.Element, label: str) -> list[ET.Element]:
return run_properties
+def _style_level_run_properties(
+ style: ET.Element,
+ label: str,
+) -> tuple[ET.Element, ...]:
+ """Return direct level 1-9 defaults from one Master text style."""
+ levels: list[ET.Element] = []
+ for level in range(1, 10):
+ run_properties = style.find(
+ f"{{{DML_NS}}}lvl{level}pPr/{{{DML_NS}}}defRPr"
+ )
+ if run_properties is None:
+ raise ThemeFontError(
+ f"slide master {label} has no level-{level} a:defRPr"
+ )
+ levels.append(run_properties)
+ return tuple(levels)
+
+
def apply_master_text_style_spec(
extract_dir: Path,
spec: MasterTextStyleSpec,
@@ -234,23 +263,39 @@ def apply_master_text_style_spec(
if text_styles is None:
raise ThemeFontError(f"Slide master has no p:txStyles: {master_path}")
- style_sizes = (
- ("titleStyle", spec.title_hpt),
- ("bodyStyle", spec.body_hpt),
- ("otherStyle", spec.body_hpt),
- )
- for style_name, size in style_sizes:
+ title_style = text_styles.find(f"{{{PML_NS}}}titleStyle")
+ if title_style is None:
+ raise ThemeFontError(
+ f"Slide master has no p:titleStyle: {master_path}"
+ )
+ for run_properties in _style_run_properties(
+ title_style,
+ "p:titleStyle",
+ ):
+ run_properties.set("sz", str(spec.title_hpt))
+
+ body_levels = spec.body_levels_hpt
+ for style_name in ("bodyStyle", "otherStyle"):
style = text_styles.find(f"{{{PML_NS}}}{style_name}")
if style is None:
raise ThemeFontError(
f"Slide master has no p:{style_name}: {master_path}"
)
- for run_properties in _style_run_properties(
- style,
- f"p:{style_name}",
+ for run_properties, size in zip(
+ _style_level_run_properties(
+ style,
+ f"p:{style_name}",
+ ),
+ body_levels,
):
run_properties.set("sz", str(size))
+ style_sizes = (
+ ("titleStyle", (spec.title_hpt,)),
+ ("bodyStyle", body_levels),
+ ("otherStyle", body_levels),
+ )
+
tree.write(master_path, encoding="utf-8", xml_declaration=True)
try:
@@ -264,20 +309,27 @@ def apply_master_text_style_spec(
raise ThemeFontError(
f"Slide master lost p:txStyles after update: {master_path}"
)
- for style_name, expected_size in style_sizes:
+ for style_name, expected_sizes in style_sizes:
style = read_back_styles.find(f"{{{PML_NS}}}{style_name}")
- actual_sizes = (
- {
+ if style is None:
+ actual_sizes: tuple[str | None, ...] = ()
+ elif style_name == "titleStyle":
+ actual_sizes = tuple(
item.get("sz")
for item in _style_run_properties(
style,
f"p:{style_name}",
)
- }
- if style is not None
- else set()
- )
- if actual_sizes != {str(expected_size)}:
+ )
+ else:
+ actual_sizes = tuple(
+ item.get("sz")
+ for item in _style_level_run_properties(
+ style,
+ f"p:{style_name}",
+ )
+ )
+ if actual_sizes != tuple(str(size) for size in expected_sizes):
raise ThemeFontError(
f"Slide master p:{style_name} size read-back failed: "
f"{master_path}"
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
index 00a9fcec..481b86e1 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
@@ -101,6 +101,7 @@ from .template_structure import (
TemplateElementSpec,
TemplateSlideSpec,
TemplateStructureError,
+ flat_structure_metadata_errors,
is_proxy_placeholder,
match_native_placeholders,
parse_preserve_slides,
@@ -112,6 +113,9 @@ from .template_validation import validate_pptx_template_package
SLIDE_LAYOUT_REL_TYPE = (
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout"
)
+SLIDE_REL_TYPE = (
+ "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide"
+)
SLIDE_MASTER_REL_TYPE = (
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideMaster"
)
@@ -2630,7 +2634,12 @@ def _apply_explicit_layout_structure(
*,
use_layout_placeholder_frames: bool = False,
verbose: bool = False,
-) -> tuple[dict[str, str | None], dict[str, tuple[str, ...]]]:
+) -> tuple[
+ dict[str, str | None],
+ dict[str, tuple[str, ...]],
+ dict[str, str],
+ dict[str, str],
+]:
"""Materialize explicit SVG master/layout/placeholder metadata into OOXML."""
master_parts_by_key = _assign_structured_masters(
extract_dir,
@@ -2674,6 +2683,7 @@ def _apply_explicit_layout_structure(
placeholder_count = 0
layout_shape_count = 0
created_layout_parts: set[str] = set()
+ layout_parts_by_key: dict[str, str] = {}
for layout_key, layout_specs in specs_by_layout.items():
layout_states = [states_by_slide[spec.slide_num] for spec in layout_specs]
master_parts = {
@@ -2700,6 +2710,7 @@ def _apply_explicit_layout_structure(
layout_path = extract_dir / layout_part
layout_rels_path = _relationships_path_for_part(extract_dir, layout_part)
created_layout_parts.add(layout_part)
+ layout_parts_by_key[layout_key] = layout_part
placeholder_bindings = {
binding.element.element_id: binding
@@ -2815,7 +2826,12 @@ def _apply_explicit_layout_structure(
f"{len(slide_backgrounds)} slide background(s), "
f"{placeholder_count} placeholder definition(s)"
)
- return expected_backgrounds, expected_shape_rosters
+ return (
+ expected_backgrounds,
+ expected_shape_rosters,
+ layout_parts_by_key,
+ master_parts_by_key,
+ )
def _apply_preserved_structure(
@@ -3254,6 +3270,132 @@ def _remove_content_type_override(content_types_path: Path, part_name: str) -> N
content_types_path.write_text(new_content, encoding="utf-8")
+def _remove_trailing_layout_definition_slides(
+ extract_dir: Path,
+ public_slide_count: int,
+ total_slide_count: int,
+) -> int:
+ """Remove internal carrier slides after their Layouts are registered."""
+ if total_slide_count <= public_slide_count:
+ return 0
+ presentation_part = "ppt/presentation.xml"
+ presentation_path = extract_dir / presentation_part
+ presentation_rels = _relationships_path_for_part(
+ extract_dir,
+ presentation_part,
+ )
+ tree = ET.parse(presentation_path)
+ root = tree.getroot()
+ slide_list = root.find(f"{{{PML_NS}}}sldIdLst")
+ if slide_list is None:
+ raise RuntimeError("presentation.xml has no p:sldIdLst")
+ entries_by_rel_id = {
+ entry.get(f"{{{REL_NS}}}id", ""): entry
+ for entry in slide_list.findall(f"{{{PML_NS}}}sldId")
+ }
+ relationships = _read_relationships(presentation_rels)
+ content_types_path = extract_dir / "[Content_Types].xml"
+ removed = 0
+ for slide_num in range(public_slide_count + 1, total_slide_count + 1):
+ slide_part = f"ppt/slides/slide{slide_num}.xml"
+ rel_ids = [
+ rel_id
+ for rel_id, attrs in relationships.items()
+ if attrs.get("Type") == SLIDE_REL_TYPE
+ and _resolve_package_target(
+ presentation_part,
+ attrs.get("Target", ""),
+ ) == slide_part
+ ]
+ if len(rel_ids) != 1:
+ raise RuntimeError(
+ f"Internal Layout carrier {slide_part} must have exactly one "
+ "Presentation relationship"
+ )
+ rel_id = rel_ids[0]
+ entry = entries_by_rel_id.get(rel_id)
+ if entry is None:
+ raise RuntimeError(
+ f"presentation.xml has no p:sldId entry for {slide_part}"
+ )
+ slide_list.remove(entry)
+ _remove_relationship(presentation_rels, rel_id)
+ slide_path = extract_dir / slide_part
+ slide_rels = _relationships_path_for_part(extract_dir, slide_part)
+ if not slide_path.is_file() or not slide_rels.is_file():
+ raise RuntimeError(
+ f"Internal Layout carrier package parts are incomplete: {slide_part}"
+ )
+ slide_path.unlink()
+ slide_rels.unlink()
+ _remove_content_type_override(content_types_path, slide_part)
+ removed += 1
+ _write_xml_tree(presentation_path, tree)
+ return removed
+
+
+def _prune_unreferenced_definition_payload_parts(extract_dir: Path) -> int:
+ """Remove generated native/media payload left by deleted carrier slides.
+
+ Definition-only SVGs are first converted as ordinary slides so their
+ reusable structure can be promoted. Removing those internal slides may
+ leave chart, workbook, or media parts with no remaining relationship. Run
+ an iterative incoming-reference sweep so chart-owned workbooks/styles are
+ removed after their orphan chart part and relationship sidecar disappear.
+ """
+ candidate_prefixes = (
+ "ppt/charts/",
+ "ppt/embeddings/",
+ "ppt/media/",
+ )
+ content_types_path = extract_dir / "[Content_Types].xml"
+ removed = 0
+ while True:
+ referenced_parts: set[str] = set()
+ for rels_path in extract_dir.rglob("*.rels"):
+ rels_rel = rels_path.relative_to(extract_dir).as_posix()
+ try:
+ root = ET.parse(rels_path).getroot()
+ except ET.ParseError as exc:
+ raise RuntimeError(
+ f"Invalid relationships XML while pruning {rels_rel}: {exc}"
+ ) from exc
+ for elem in root:
+ attrs = _relationship_attrs(elem)
+ if attrs.get("TargetMode", "").lower() == "external":
+ continue
+ target = attrs.get("Target")
+ if not target:
+ continue
+ resolved = _resolve_internal_opc_target(rels_rel, target)
+ if resolved is not None:
+ referenced_parts.add(resolved)
+
+ orphan_paths: list[tuple[Path, str]] = []
+ for path in extract_dir.rglob("*"):
+ if not path.is_file():
+ continue
+ part_name = path.relative_to(extract_dir).as_posix()
+ if "/_rels/" in part_name:
+ continue
+ if not part_name.startswith(candidate_prefixes):
+ continue
+ canonical = _canonical_opc_part_path(part_name)
+ if canonical is not None and canonical not in referenced_parts:
+ orphan_paths.append((path, part_name))
+ if not orphan_paths:
+ break
+
+ for path, part_name in orphan_paths:
+ rels_path = _relationships_path_for_part(extract_dir, part_name)
+ if rels_path.is_file():
+ rels_path.unlink()
+ path.unlink()
+ _remove_content_type_override(content_types_path, part_name)
+ removed += 1
+ return removed
+
+
def _prune_unused_slide_layouts(
extract_dir: Path,
structure: PptxStructureContext,
@@ -4317,12 +4459,16 @@ def create_pptx_with_native_svg(
theme_color_spec: ThemeColorSpec | None = None,
structured_baseline: bool = False,
baseline_layout_specs: list[TemplateSlideSpec] | None = None,
+ layout_definition_files: list[Path] | None = None,
) -> bool:
"""Create a PPTX file with native DrawingML shapes.
Args:
svg_files: List of SVG files.
output_path: Output PPTX path.
+ layout_definition_files: Optional structured SVG prototypes for Layouts
+ that no generated page uses. They are converted on internal carrier
+ slides, registered, and removed before the package is published.
canvas_format: Canvas format key.
verbose: Whether to output detailed information.
transition: Transition effect name.
@@ -4382,18 +4528,48 @@ def create_pptx_with_native_svg(
Returns:
Whether all slides were successfully created.
"""
+ public_svg_files = list(svg_files)
+ definition_svg_files = list(layout_definition_files or [])
+ if definition_svg_files and pptx_structure != "structured":
+ raise ValueError(
+ "layout_definition_files requires pptx_structure='structured'"
+ )
+ public_paths = {path.resolve() for path in public_svg_files}
+ seen_definition_paths: set[Path] = set()
+ for path in definition_svg_files:
+ resolved = path.resolve()
+ if not path.is_file():
+ raise ValueError(f"Layout definition SVG does not exist: {path}")
+ if resolved in public_paths:
+ raise ValueError(
+ f"Layout definition SVG is already a generated page: {path}"
+ )
+ if resolved in seen_definition_paths:
+ raise ValueError(f"Layout definition SVG is repeated: {path}")
+ seen_definition_paths.add(resolved)
+ public_slide_count = len(public_svg_files)
+ svg_files = public_svg_files + definition_svg_files
+ total_slide_count = len(svg_files)
+
if not use_native_shapes:
raise ValueError(
"SVG-image PPTX export is no longer supported; use svg_final/ "
"directly for preview and native DrawingML PPTX for delivery"
)
- if not svg_files:
+ if not public_svg_files:
print("Error: No SVG files found")
return False
use_compat_mode = False
if pptx_structure not in {"baseline", "structured", "preserve", "flat"}:
raise ValueError(f"Unsupported pptx_structure: {pptx_structure}")
+ if pptx_structure == "flat":
+ flat_errors = flat_structure_metadata_errors(public_svg_files)
+ if flat_errors:
+ details = "\n".join(f" - {error}" for error in flat_errors)
+ raise TemplateStructureError(
+ "Flat PPTX structure validation failed:\n" + details
+ )
if use_layout_placeholder_frames and pptx_structure != "structured":
raise ValueError(
"use_layout_placeholder_frames requires pptx_structure='structured'"
@@ -4413,6 +4589,7 @@ def create_pptx_with_native_svg(
)
if use_native_shapes and pptx_structure == "structured":
template_specs = parse_template_slides(svg_files)
+ public_template_specs = template_specs[:public_slide_count]
elif use_native_shapes and pptx_structure == "preserve":
if native_structure_contract is None:
raise TemplateStructureError(
@@ -4421,12 +4598,16 @@ def create_pptx_with_native_svg(
template_specs = parse_preserve_slides(svg_files)
for spec in template_specs:
native_structure_contract.layout(spec.layout_key)
+ public_template_specs = template_specs
else:
template_specs = None
+ public_template_specs = None
template_background_expectations: dict[str, str | None] | None = None
template_shape_roster_expectations: (
dict[str, tuple[str, ...]] | None
) = None
+ template_layout_parts_by_key: dict[str, str] | None = None
+ template_master_parts_by_key: dict[str, str] | None = None
if template_specs is not None and not native_objects:
native_placeholders = sorted({
item.placeholder
@@ -4475,7 +4656,12 @@ def create_pptx_with_native_svg(
if verbose:
print(f" Slide dimensions: {pixel_width} x {pixel_height} px")
- print(f" SVG file count: {len(svg_files)}")
+ print(f" SVG file count: {public_slide_count}")
+ if definition_svg_files:
+ print(
+ " Unused Layout definitions: "
+ f"{len(definition_svg_files)} internal prototype(s)"
+ )
if use_native_shapes:
print(f" Mode: Native DrawingML shapes (directly editable)")
print(
@@ -4617,6 +4803,7 @@ def create_pptx_with_native_svg(
for i, svg_path in enumerate(svg_files, 1):
slide_num = i
+ is_layout_definition = slide_num > public_slide_count
expected_animation_targets: list[tuple[int, int, str, float]] = []
expected_animation_duration = animation_duration
expected_animation_trigger = normalize_animation_trigger(animation_trigger)
@@ -4624,29 +4811,44 @@ def create_pptx_with_native_svg(
try:
# ---- Native shapes mode ----
if use_native_shapes:
- slide_cfg = _slide_config(animation_config, svg_path.stem)
- slide_transition, slide_transition_duration, slide_auto_advance = (
- _slide_transition_settings(
+ slide_cfg = (
+ {}
+ if is_layout_definition
+ else _slide_config(animation_config, svg_path.stem)
+ )
+ if is_layout_definition:
+ slide_transition = None
+ slide_transition_duration = transition_duration
+ slide_auto_advance = None
+ slide_animation = None
+ slide_animation_duration = animation_duration
+ slide_animation_stagger = animation_stagger
+ slide_animation_trigger = animation_trigger
+ else:
+ (
+ slide_transition,
+ slide_transition_duration,
+ slide_auto_advance,
+ ) = _slide_transition_settings(
slide_cfg,
transition,
transition_duration,
auto_advance,
animation_cli_overrides,
)
- )
- (
- slide_animation,
- slide_animation_duration,
- slide_animation_stagger,
- slide_animation_trigger,
- ) = _slide_animation_settings(
- slide_cfg,
- animation,
- animation_duration,
- animation_stagger,
- animation_trigger,
- animation_cli_overrides,
- )
+ (
+ slide_animation,
+ slide_animation_duration,
+ slide_animation_stagger,
+ slide_animation_trigger,
+ ) = _slide_animation_settings(
+ slide_cfg,
+ animation,
+ animation_duration,
+ animation_stagger,
+ animation_trigger,
+ animation_cli_overrides,
+ )
groups_value = slide_cfg.get('groups', {})
if not isinstance(groups_value, dict):
raise ValueError(
@@ -4891,7 +5093,7 @@ def create_pptx_with_native_svg(
# --- Process notes (shared between native and legacy mode) ---
notes_content = ''
- if enable_notes:
+ if enable_notes and not is_layout_definition:
svg_stem = svg_path.stem
notes_content = notes.get(svg_stem, '') if notes else ''
notes_text = markdown_to_plain_text(notes_content) if notes_content else ''
@@ -4922,7 +5124,11 @@ def create_pptx_with_native_svg(
# --- Process narration audio (shared between native and legacy mode) ---
svg_stem = svg_path.stem
- audio_path = narration_audio.get(svg_stem) if narration_audio else None
+ audio_path = (
+ narration_audio.get(svg_stem)
+ if narration_audio and not is_layout_definition
+ else None
+ )
if audio_path:
slide_xml_path = extract_dir / 'ppt' / 'slides' / f'slide{slide_num}.xml'
rels_path = extract_dir / 'ppt' / 'slides' / '_rels' / f'slide{slide_num}.xml.rels'
@@ -5027,7 +5233,13 @@ def create_pptx_with_native_svg(
has_notes = slide_num in notes_slides_created
notes_str = " +notes" if has_notes else ""
narration_str = " +narration" if slide_num in narration_slides_created else ""
- print(f" [{i}/{len(svg_files)}] {svg_path.name}{mode_str}{notes_str}{narration_str}")
+ definition_str = (
+ " [Layout definition]" if is_layout_definition else ""
+ )
+ print(
+ f" [{i}/{len(svg_files)}] {svg_path.name}{mode_str}"
+ f"{notes_str}{narration_str}{definition_str}"
+ )
success_count += 1
@@ -5114,6 +5326,8 @@ def create_pptx_with_native_svg(
(
template_background_expectations,
template_shape_roster_expectations,
+ template_layout_parts_by_key,
+ template_master_parts_by_key,
) = _apply_explicit_layout_structure(
extract_dir,
structure,
@@ -5132,7 +5346,9 @@ def create_pptx_with_native_svg(
" Structured master text styles: "
f"{master_count} master(s), "
f"title {master_text_style_spec.title_hpt / 100:g}pt, "
- f"body {master_text_style_spec.body_hpt / 100:g}pt"
+ "body levels "
+ f"{master_text_style_spec.body_levels_hpt[0] / 100:g}–"
+ f"{master_text_style_spec.body_levels_hpt[-1] / 100:g}pt"
)
_prune_unused_slide_layouts(
extract_dir,
@@ -5165,6 +5381,33 @@ def create_pptx_with_native_svg(
verbose=verbose,
)
+ if (
+ use_native_shapes
+ and pptx_structure == "structured"
+ and definition_svg_files
+ and success_count == total_slide_count
+ ):
+ removed = _remove_trailing_layout_definition_slides(
+ extract_dir,
+ public_slide_count,
+ total_slide_count,
+ )
+ pruned_payload_parts = _prune_unreferenced_definition_payload_parts(
+ extract_dir
+ )
+ for slide_num in range(public_slide_count + 1, total_slide_count + 1):
+ slide_part = f"ppt/slides/slide{slide_num}.xml"
+ if template_background_expectations is not None:
+ template_background_expectations.pop(slide_part, None)
+ if template_shape_roster_expectations is not None:
+ template_shape_roster_expectations.pop(slide_part, None)
+ if verbose:
+ print(
+ " Layout definition carriers: "
+ f"removed {removed} internal slide(s), pruned "
+ f"{pruned_payload_parts} orphan payload part(s)"
+ )
+
# Update [Content_Types].xml
content_types_path = extract_dir / '[Content_Types].xml'
with open(content_types_path, 'r', encoding='utf-8') as f:
@@ -5244,7 +5487,7 @@ def create_pptx_with_native_svg(
# author, 2013 dates, "generated using python-pptx", Slides=0) with
# accurate, tool-neutral document properties.
pres_format = _presentation_format(width_emu, height_emu)
- _stamp_docprops(extract_dir, len(svg_files), pres_format, doc_metadata)
+ _stamp_docprops(extract_dir, public_slide_count, pres_format, doc_metadata)
# Repackage PPTX to a temporary file first. The public output path is
# replaced only after every slide and relationship has succeeded.
@@ -5259,14 +5502,17 @@ def create_pptx_with_native_svg(
and pptx_structure == "structured"
and success_count == len(svg_files)
):
- if template_specs is None:
+ if template_specs is None or public_template_specs is None:
raise TemplateStructureError(
"Explicit Layout metadata was not parsed before validation"
)
try:
validate_pptx_template_package(
temp_output_path,
- template_specs,
+ public_template_specs,
+ layout_specs=template_specs,
+ expected_layout_parts=template_layout_parts_by_key,
+ expected_master_parts=template_master_parts_by_key,
expected_backgrounds=template_background_expectations,
expected_shape_rosters=template_shape_roster_expectations,
)
@@ -5299,8 +5545,12 @@ def create_pptx_with_native_svg(
conversion_trace_path.parent.mkdir(parents=True, exist_ok=True)
payload = {
'output': str(output_path),
- 'slide_count': len(svg_files),
- 'slides': conversion_trace,
+ 'slide_count': public_slide_count,
+ 'slides': [
+ entry
+ for entry in conversion_trace
+ if int(entry.get('slide_num', 0)) <= public_slide_count
+ ],
}
conversion_trace_path.write_text(
json.dumps(payload, ensure_ascii=False, indent=2),
@@ -5314,7 +5564,10 @@ def create_pptx_with_native_svg(
print(f" [warn] {warning}")
if conversion_trace_path and conversion_trace is not None:
print(f" Trace: {conversion_trace_path}")
- print(f" Succeeded: {success_count}, Failed: {len(svg_files) - success_count}")
+ print(
+ f" Slides: {public_slide_count}; "
+ f"Layout definitions: {len(definition_svg_files)}"
+ )
if use_compat_mode and has_any_image:
print(f" Mode: Office compatibility mode (supports all Office versions)")
if PNG_RENDERER == 'svglib' and renderer_hint:
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
index 82f893df..c08ba1df 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
@@ -51,6 +51,7 @@ from .template_structure import (
TemplateStructureError,
load_pptx_structure_lock,
parse_template_slides,
+ structured_layout_definition_files,
template_lock_errors,
template_prototype_errors,
)
@@ -507,6 +508,7 @@ Recorded narration:
# parameters are removed. Structured export never activates either path.
structured_baseline = False
baseline_layout_specs = None
+ layout_definition_files: list[Path] = []
if pptx_structure == 'structured' and structure_lock is not None:
try:
template_specs = parse_template_slides(native_files)
@@ -519,6 +521,14 @@ Recorded narration:
for message in lock_errors:
print(f" {message}", file=sys.stderr)
return 1
+ try:
+ layout_definition_files = structured_layout_definition_files(
+ template_specs,
+ structure_lock,
+ )
+ except TemplateStructureError as exc:
+ print(f"Error: {exc}", file=sys.stderr)
+ return 1
prototype_errors = template_prototype_errors(
template_specs,
structure_lock,
@@ -902,6 +912,7 @@ Recorded narration:
pptx_structure=pptx_structure,
structured_baseline=structured_baseline,
baseline_layout_specs=baseline_layout_specs,
+ layout_definition_files=layout_definition_files,
native_structure_contract=native_structure_contract,
theme_font_spec=theme_font_spec,
master_text_style_spec=master_text_style_spec,
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/template_structure.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/template_structure.py
index 8aecca97..3bfd33e7 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/template_structure.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/template_structure.py
@@ -47,6 +47,9 @@ _STRUCTURE_ATTRS = frozenset({
"data-pptx-placeholder-idx",
"data-pptx-editable",
})
+_FLAT_FORBIDDEN_STRUCTURE_ATTRS = frozenset(
+ _STRUCTURE_ATTRS - {"data-pptx-editable"}
+)
_LAYERS = frozenset({"master", "layout", "slide"})
_PLACEHOLDERS = frozenset({
"title",
@@ -150,7 +153,7 @@ class TemplateStructureError(RuntimeError):
@dataclass(frozen=True)
class PptxLayoutReference:
- """One spec_lock page-to-PowerPoint-layout declaration."""
+ """One spec_lock page-to-PowerPoint-layout assignment."""
slide_num: int
layout_key: str
@@ -158,6 +161,17 @@ class PptxLayoutReference:
master_key: str | None = None
+@dataclass(frozen=True)
+class PptxLayoutDefinition:
+ """One reusable PowerPoint Layout declared by a structured project lock."""
+
+ layout_key: str
+ master_key: str
+ layout_name: str
+ prototype_slide_num: int | None = None
+ prototype_svg_path: Path | None = None
+
+
@dataclass(frozen=True)
class PptxMasterReference:
"""One named Master declared by the structured project lock."""
@@ -183,6 +197,7 @@ class PptxStructureLock:
mode: str
template_adherence: str | None = None
masters: tuple[PptxMasterReference, ...] = ()
+ layout_definitions: tuple[PptxLayoutDefinition, ...] = ()
layouts: tuple[PptxLayoutReference, ...] = ()
prototypes: tuple[PptxPrototypeReference, ...] = ()
source_template: Path | None = None
@@ -480,6 +495,37 @@ def _template_replication_mode(template_dir: Path) -> str | None:
return None
+def _template_svg_path(
+ template_dir: Path,
+ raw_basename: str,
+ context: str,
+) -> tuple[str, Path]:
+ """Resolve one flat template SVG basename inside the project workspace."""
+ basename = (
+ raw_basename[:-4]
+ if raw_basename.lower().endswith(".svg")
+ else raw_basename
+ )
+ if (
+ not basename
+ or basename in {".", ".."}
+ or "/" in basename
+ or "\\" in basename
+ or any(ord(char) < 0x20 for char in basename)
+ ):
+ raise TemplateStructureError(
+ f"spec_lock.md {context} has invalid template SVG basename "
+ f"{raw_basename!r}"
+ )
+ svg_path = (template_dir / f"{basename}.svg").resolve()
+ if svg_path.parent != template_dir or not svg_path.is_file():
+ raise TemplateStructureError(
+ f"spec_lock.md {context} references missing template SVG "
+ f"templates/{basename}.svg"
+ )
+ return basename, svg_path
+
+
def load_pptx_structure_lock(project_path: Path) -> PptxStructureLock | None:
"""Load optional native-structure sections from spec_lock.md."""
lock_path = project_path / "spec_lock.md"
@@ -502,6 +548,7 @@ def load_pptx_structure_lock(project_path: Path) -> PptxStructureLock | None:
"pptx_structure",
"pptx_masters",
"pptx_layouts",
+ "page_pptx_layouts",
"page_layouts",
}:
continue
@@ -512,19 +559,23 @@ def load_pptx_structure_lock(project_path: Path) -> PptxStructureLock | None:
structure_rows = sections.get("pptx_structure", [])
master_rows = sections.get("pptx_masters", [])
layout_rows = sections.get("pptx_layouts", [])
+ page_layout_rows = sections.get("page_pptx_layouts", [])
prototype_rows = sections.get("page_layouts", [])
structure_section_present = "pptx_structure" in sections
master_section_present = "pptx_masters" in sections
layout_section_present = "pptx_layouts" in sections
+ page_layout_section_present = "page_pptx_layouts" in sections
prototype_section_present = "page_layouts" in sections
if (
not structure_rows
and not master_rows
and not layout_rows
+ and not page_layout_rows
and not prototype_rows
and not structure_section_present
and not master_section_present
and not layout_section_present
+ and not page_layout_section_present
and not prototype_section_present
):
return None
@@ -658,28 +709,11 @@ def load_pptx_structure_lock(project_path: Path) -> PptxStructureLock | None:
)
seen_prototype_slides.add(slide_num)
raw_basename = raw_value.strip()
- basename = (
- raw_basename[:-4]
- if raw_basename.lower().endswith(".svg")
- else raw_basename
+ basename, svg_path = _template_svg_path(
+ template_dir,
+ raw_basename,
+ f"page_layouts P{slide_num:02d}",
)
- if (
- not basename
- or basename in {".", ".."}
- or "/" in basename
- or "\\" in basename
- or any(ord(char) < 0x20 for char in basename)
- ):
- raise TemplateStructureError(
- f"spec_lock.md P{slide_num:02d} has invalid template SVG basename "
- f"{raw_basename!r}"
- )
- svg_path = (template_dir / f"{basename}.svg").resolve()
- if svg_path.parent != template_dir or not svg_path.is_file():
- raise TemplateStructureError(
- f"spec_lock.md P{slide_num:02d} references missing template SVG "
- f"templates/{basename}.svg"
- )
prototypes.append(PptxPrototypeReference(
slide_num=slide_num,
template_basename=basename,
@@ -696,98 +730,164 @@ def load_pptx_structure_lock(project_path: Path) -> PptxStructureLock | None:
"spec_lock.md page_layouts requires template_adherence: strict or adaptive"
)
+ layout_definitions: list[PptxLayoutDefinition] = []
references: list[PptxLayoutReference] = []
- seen_slides: set[int] = set()
- for page_key, raw_value in layout_rows:
- page_match = _LOCK_PAGE_RE.fullmatch(page_key)
- if not page_match or int(page_match.group(1)) <= 0:
- raise TemplateStructureError(
- f"spec_lock.md pptx_layouts key {page_key!r} must be P<NN>"
- )
- slide_num = int(page_match.group(1))
- if slide_num in seen_slides:
+ if mode == "structured":
+ if not layout_rows:
raise TemplateStructureError(
- f"spec_lock.md pptx_layouts repeats page P{slide_num:02d}"
+ "spec_lock.md structured mode requires a non-empty "
+ "pptx_layouts definition section"
)
- seen_slides.add(slide_num)
- parts = [part.strip() for part in raw_value.split("|")]
- master_key: str | None = None
- if mode == "structured":
+ seen_layout_keys: set[str] = set()
+ for layout_key, raw_value in layout_rows:
+ if not _LAYOUT_KEY_RE.fullmatch(layout_key):
+ raise TemplateStructureError(
+ f"spec_lock.md has invalid Layout key {layout_key!r}; use 1-64 "
+ "ASCII letters, digits, dots, underscores, or hyphens"
+ )
+ if layout_key in seen_layout_keys:
+ raise TemplateStructureError(
+ f"spec_lock.md pptx_layouts repeats Layout key {layout_key!r}"
+ )
+ seen_layout_keys.add(layout_key)
+ parts = [part.strip() for part in raw_value.split("|")]
if len(parts) != 3 or not all(parts):
raise TemplateStructureError(
- f"spec_lock.md P{slide_num:02d} structured mapping must be "
- "'<master_key> | <layout_key> | <PowerPoint layout name>'"
+ f"spec_lock.md Layout {layout_key!r} must be "
+ "'<master_key> | <PowerPoint layout name> | "
+ "<P<NN> or template:<basename>>'"
)
- master_key, layout_key, layout_name = parts
+ master_key, layout_name, raw_source = parts
if not _MASTER_KEY_RE.fullmatch(master_key):
raise TemplateStructureError(
- f"spec_lock.md P{slide_num:02d} has invalid Master key "
+ f"spec_lock.md Layout {layout_key!r} has invalid Master key "
f"{master_key!r}"
)
if master_key not in seen_master_keys:
raise TemplateStructureError(
- f"spec_lock.md P{slide_num:02d} references undeclared Master "
- f"{master_key!r}"
+ f"spec_lock.md Layout {layout_key!r} references undeclared "
+ f"Master {master_key!r}"
)
- else:
- if len(parts) not in {1, 2} or not parts[0]:
+ prototype_slide_num: int | None = None
+ prototype_svg_path: Path | None = None
+ page_match = _LOCK_PAGE_RE.fullmatch(raw_source)
+ if page_match and int(page_match.group(1)) > 0:
+ prototype_slide_num = int(page_match.group(1))
+ elif raw_source.startswith("template:"):
+ raw_basename = raw_source.split(":", 1)[1].strip()
+ _basename, prototype_svg_path = _template_svg_path(
+ template_dir,
+ raw_basename,
+ f"pptx_layouts Layout {layout_key!r}",
+ )
+ else:
raise TemplateStructureError(
- f"spec_lock.md P{slide_num:02d} preserve mapping must be "
- "'<layout_key>' or '<layout_key> | <PowerPoint layout name>'"
+ f"spec_lock.md Layout {layout_key!r} prototype source must be "
+ "P<NN> or template:<basename>"
)
- layout_key = parts[0]
- layout_name = parts[1] if len(parts) == 2 else None
- if not _LAYOUT_KEY_RE.fullmatch(layout_key):
- raise TemplateStructureError(
- f"spec_lock.md P{slide_num:02d} has invalid layout key "
- f"{layout_key!r}"
- )
- references.append(PptxLayoutReference(
- slide_num=slide_num,
- layout_key=layout_key,
- layout_name=layout_name,
- master_key=master_key,
- ))
+ layout_definitions.append(PptxLayoutDefinition(
+ layout_key=layout_key,
+ master_key=master_key,
+ layout_name=layout_name,
+ prototype_slide_num=prototype_slide_num,
+ prototype_svg_path=prototype_svg_path,
+ ))
- if mode in {"structured", "preserve"} and not references:
- raise TemplateStructureError(
- f"spec_lock.md {mode} mode requires one pptx_layouts row per page"
- )
- if mode == "structured" and layout_section_present and not layout_rows:
- raise TemplateStructureError(
- "spec_lock.md structured pptx_layouts section cannot be empty"
- )
- layout_contracts: dict[str, tuple[str | None, str | None]] = {}
- for reference in references:
- contract = (reference.master_key, reference.layout_name)
- previous = layout_contracts.setdefault(reference.layout_key, contract)
- if previous != contract:
+ seen_slides: set[int] = set()
+ for page_key, raw_value in page_layout_rows:
+ page_match = _LOCK_PAGE_RE.fullmatch(page_key)
+ if not page_match or int(page_match.group(1)) <= 0:
+ raise TemplateStructureError(
+ f"spec_lock.md page_pptx_layouts key {page_key!r} must be P<NN>"
+ )
+ slide_num = int(page_match.group(1))
+ if slide_num in seen_slides:
+ raise TemplateStructureError(
+ "spec_lock.md page_pptx_layouts repeats page "
+ f"P{slide_num:02d}"
+ )
+ seen_slides.add(slide_num)
+ layout_key = raw_value.strip()
+ if not _LAYOUT_KEY_RE.fullmatch(layout_key):
+ raise TemplateStructureError(
+ f"spec_lock.md P{slide_num:02d} has invalid Layout key "
+ f"{layout_key!r}"
+ )
+ if layout_key not in seen_layout_keys:
+ raise TemplateStructureError(
+ f"spec_lock.md P{slide_num:02d} references undeclared Layout "
+ f"{layout_key!r}"
+ )
+ references.append(PptxLayoutReference(
+ slide_num=slide_num,
+ layout_key=layout_key,
+ ))
+ if not references:
raise TemplateStructureError(
- f"spec_lock.md layout key {reference.layout_key!r} must be globally "
- "unique to one Master and one Layout name"
+ "spec_lock.md structured mode requires one page_pptx_layouts "
+ "assignment per generated page"
)
- if mode == "structured":
unused_masters = sorted(
seen_master_keys - {
- reference.master_key
- for reference in references
- if reference.master_key is not None
+ definition.master_key for definition in layout_definitions
}
)
if unused_masters:
raise TemplateStructureError(
- "spec_lock.md pptx_masters contains unreferenced Master key(s): "
- + ", ".join(unused_masters)
+ "spec_lock.md pptx_masters contains Master key(s) without a "
+ "Layout definition: " + ", ".join(unused_masters)
+ )
+ elif mode == "preserve":
+ if page_layout_section_present:
+ raise TemplateStructureError(
+ "spec_lock.md page_pptx_layouts is reserved for structured mode; "
+ "preserve mode maps source Layouts directly in pptx_layouts"
+ )
+ seen_slides: set[int] = set()
+ for page_key, raw_value in layout_rows:
+ page_match = _LOCK_PAGE_RE.fullmatch(page_key)
+ if not page_match or int(page_match.group(1)) <= 0:
+ raise TemplateStructureError(
+ f"spec_lock.md pptx_layouts key {page_key!r} must be P<NN>"
+ )
+ slide_num = int(page_match.group(1))
+ if slide_num in seen_slides:
+ raise TemplateStructureError(
+ f"spec_lock.md pptx_layouts repeats page P{slide_num:02d}"
+ )
+ seen_slides.add(slide_num)
+ parts = [part.strip() for part in raw_value.split("|")]
+ if len(parts) not in {1, 2} or not parts[0]:
+ raise TemplateStructureError(
+ f"spec_lock.md P{slide_num:02d} preserve mapping must be "
+ "'<layout_key>' or '<layout_key> | <PowerPoint layout name>'"
+ )
+ layout_key = parts[0]
+ if not _LAYOUT_KEY_RE.fullmatch(layout_key):
+ raise TemplateStructureError(
+ f"spec_lock.md P{slide_num:02d} has invalid Layout key "
+ f"{layout_key!r}"
+ )
+ references.append(PptxLayoutReference(
+ slide_num=slide_num,
+ layout_key=layout_key,
+ layout_name=parts[1] if len(parts) == 2 else None,
+ ))
+ if not references:
+ raise TemplateStructureError(
+ "spec_lock.md preserve mode requires one pptx_layouts row per page"
+ )
+ else:
+ if layout_section_present or page_layout_section_present:
+ raise TemplateStructureError(
+ "spec_lock.md pptx_layouts/page_pptx_layouts sections are not "
+ "allowed when pptx_structure.mode is flat"
)
- if mode == "flat" and layout_section_present:
- raise TemplateStructureError(
- "spec_lock.md pptx_layouts section is not allowed when "
- "pptx_structure.mode is flat"
- )
return PptxStructureLock(
mode=mode,
template_adherence=template_adherence,
masters=tuple(masters),
+ layout_definitions=tuple(layout_definitions),
layouts=tuple(sorted(references, key=lambda item: item.slide_num)),
prototypes=tuple(sorted(prototypes, key=lambda item: item.slide_num)),
source_template=source_template,
@@ -1446,17 +1546,10 @@ def parse_template_slide(
return spec
-def parse_template_slides(svg_files: list[Path]) -> list[TemplateSlideSpec]:
- """Parse a deck and enforce cross-slide master/layout contracts."""
- specs = [
- parse_template_slide(svg_path, slide_num)
- for slide_num, svg_path in enumerate(svg_files, start=1)
- ]
- if not specs:
- raise TemplateStructureError(
- "Explicit Layout export requires at least one SVG slide"
- )
-
+def _validate_template_slide_contracts(
+ specs: list[TemplateSlideSpec],
+) -> None:
+ """Enforce cross-prototype Master and Layout structure identity."""
by_master: dict[str, list[TemplateSlideSpec]] = {}
for spec in specs:
by_master.setdefault(spec.master_key, []).append(spec)
@@ -1505,6 +1598,19 @@ def parse_template_slides(svg_files: list[Path]) -> list[TemplateSlideSpec]:
f"from prototype {prototype.svg_path.name}; repeat the same layout "
"layers and placeholder ids/types in the same order"
)
+
+
+def parse_template_slides(svg_files: list[Path]) -> list[TemplateSlideSpec]:
+ """Parse a deck and enforce cross-slide master/layout contracts."""
+ specs = [
+ parse_template_slide(svg_path, slide_num)
+ for slide_num, svg_path in enumerate(svg_files, start=1)
+ ]
+ if not specs:
+ raise TemplateStructureError(
+ "Explicit Layout export requires at least one SVG slide"
+ )
+ _validate_template_slide_contracts(specs)
return specs
@@ -1579,6 +1685,33 @@ def parse_optional_layout_slides(
return parse_template_slides(svg_files)
+def flat_structure_metadata_errors(svg_files: list[Path]) -> list[str]:
+ """Return every Master/Layout marker forbidden by flat export."""
+ errors: list[str] = []
+ for svg_path in svg_files:
+ try:
+ root = ET.parse(svg_path).getroot()
+ except (OSError, ET.ParseError) as exc:
+ errors.append(
+ f"{svg_path.name}: unable to inspect flat-mode metadata: {exc}"
+ )
+ continue
+ for elem in root.iter():
+ attrs = sorted(
+ attr
+ for attr in _FLAT_FORBIDDEN_STRUCTURE_ATTRS
+ if elem.get(attr) is not None
+ )
+ if not attrs:
+ continue
+ element_id = (elem.get("id") or _local_tag(elem)).strip()
+ errors.append(
+ f"{svg_path.name}: flat mode forbids Master/Layout structure "
+ f"metadata on {element_id!r}: " + ", ".join(attrs)
+ )
+ return errors
+
+
def parse_preserve_slides(svg_files: list[Path]) -> list[TemplateSlideSpec]:
"""Parse preserve-mode slides before source master grouping is known."""
specs = [
@@ -1590,6 +1723,74 @@ def parse_preserve_slides(svg_files: list[Path]) -> list[TemplateSlideSpec]:
return specs
+def structured_layout_definition_files(
+ specs: list[TemplateSlideSpec],
+ structure_lock: PptxStructureLock,
+) -> list[Path]:
+ """Validate the unique Layout roster and return unused prototype SVGs.
+
+ A generated page can be the carrier for a used Layout definition. A Layout
+ with no generated page must point at one installed template SVG; the builder
+ converts that SVG on an internal trailing slide and removes the carrier slide
+ after registering the reusable Layout.
+ """
+ if structure_lock.mode != "structured":
+ return []
+ definitions = {
+ definition.layout_key: definition
+ for definition in structure_lock.layout_definitions
+ }
+ specs_by_slide = {spec.slide_num: spec for spec in specs}
+ used_layout_keys = {spec.layout_key for spec in specs}
+ master_names = {
+ master.master_key: master.master_name
+ for master in structure_lock.masters
+ }
+ combined_specs = list(specs)
+ definition_files: list[Path] = []
+ next_slide_num = max(specs_by_slide, default=0) + 1
+ for definition in structure_lock.layout_definitions:
+ if definition.prototype_slide_num is not None:
+ prototype = specs_by_slide.get(definition.prototype_slide_num)
+ if prototype is None:
+ raise TemplateStructureError(
+ f"spec_lock.md Layout {definition.layout_key!r} uses missing "
+ f"prototype page P{definition.prototype_slide_num:02d}"
+ )
+ elif definition.prototype_svg_path is not None:
+ prototype = parse_template_slide(
+ definition.prototype_svg_path,
+ next_slide_num,
+ )
+ next_slide_num += 1
+ combined_specs.append(prototype)
+ if definition.layout_key not in used_layout_keys:
+ definition_files.append(definition.prototype_svg_path)
+ else:
+ raise TemplateStructureError(
+ f"spec_lock.md Layout {definition.layout_key!r} has no prototype"
+ )
+ expected_master_name = master_names.get(definition.master_key)
+ if (
+ prototype.layout_key != definition.layout_key
+ or prototype.layout_name != definition.layout_name
+ or prototype.master_key != definition.master_key
+ or prototype.master_name != expected_master_name
+ ):
+ raise TemplateStructureError(
+ f"spec_lock.md Layout {definition.layout_key!r} definition does "
+ f"not match prototype {prototype.svg_path.name} root identity"
+ )
+ missing_definitions = sorted(used_layout_keys - set(definitions))
+ if missing_definitions:
+ raise TemplateStructureError(
+ "spec_lock.md pptx_layouts is missing generated Layout key(s): "
+ + ", ".join(missing_definitions)
+ )
+ _validate_template_slide_contracts(combined_specs)
+ return definition_files
+
+
def template_lock_errors(
specs: list[TemplateSlideSpec],
structure_lock: PptxStructureLock,
@@ -1606,15 +1807,22 @@ def template_lock_errors(
expected_slides = set(references)
missing = sorted(actual_slides - expected_slides)
extra = sorted(expected_slides - actual_slides)
+ assignment_section = (
+ "page_pptx_layouts"
+ if structure_lock.mode == "structured"
+ else "pptx_layouts"
+ )
if missing:
pages = ", ".join(f"P{slide_num:02d}" for slide_num in missing)
errors.append(
- f"spec_lock.md pptx_layouts is missing generated page(s): {pages}"
+ f"spec_lock.md {assignment_section} is missing generated page(s): "
+ f"{pages}"
)
if extra:
pages = ", ".join(f"P{slide_num:02d}" for slide_num in extra)
errors.append(
- f"spec_lock.md pptx_layouts references absent page(s): {pages}"
+ f"spec_lock.md {assignment_section} references absent page(s): "
+ f"{pages}"
)
for spec in specs:
reference = references.get(spec.slide_num)
@@ -1623,26 +1831,40 @@ def template_lock_errors(
if spec.layout_key != reference.layout_key:
errors.append(
f"{spec.svg_path.name}: data-pptx-layout={spec.layout_key!r} "
- f"does not match spec_lock P{spec.slide_num:02d} layout key "
+ f"does not match spec_lock P{spec.slide_num:02d} Layout key "
f"{reference.layout_key!r}"
)
- if reference.layout_name and spec.layout_name != reference.layout_name:
- errors.append(
- f"{spec.svg_path.name}: data-pptx-layout-name={spec.layout_name!r} "
- f"does not match spec_lock P{spec.slide_num:02d} layout name "
- f"{reference.layout_name!r}"
- )
- if reference.master_key and spec.master_key != reference.master_key:
- errors.append(
- f"{spec.svg_path.name}: data-pptx-master={spec.master_key!r} "
- f"does not match spec_lock P{spec.slide_num:02d} Master key "
- f"{reference.master_key!r}"
- )
+ if structure_lock.mode == "preserve":
+ if reference.layout_name and spec.layout_name != reference.layout_name:
+ errors.append(
+ f"{spec.svg_path.name}: data-pptx-layout-name="
+ f"{spec.layout_name!r} does not match spec_lock "
+ f"P{spec.slide_num:02d} Layout name "
+ f"{reference.layout_name!r}"
+ )
if structure_lock.mode == "structured":
+ definitions = {
+ definition.layout_key: definition
+ for definition in structure_lock.layout_definitions
+ }
master_names = {
master.master_key: master.master_name for master in structure_lock.masters
}
for spec in specs:
+ definition = definitions.get(spec.layout_key)
+ if definition is not None:
+ if spec.layout_name != definition.layout_name:
+ errors.append(
+ f"{spec.svg_path.name}: data-pptx-layout-name="
+ f"{spec.layout_name!r} does not match Layout "
+ f"{spec.layout_key!r} name {definition.layout_name!r}"
+ )
+ if spec.master_key != definition.master_key:
+ errors.append(
+ f"{spec.svg_path.name}: data-pptx-master="
+ f"{spec.master_key!r} does not match Layout "
+ f"{spec.layout_key!r} Master {definition.master_key!r}"
+ )
expected_name = master_names.get(spec.master_key)
if expected_name is not None and spec.master_name != expected_name:
errors.append(
@@ -1650,6 +1872,10 @@ def template_lock_errors(
f"{spec.master_name!r} does not match spec_lock Master "
f"{spec.master_key!r} name {expected_name!r}"
)
+ try:
+ structured_layout_definition_files(specs, structure_lock)
+ except TemplateStructureError as exc:
+ errors.append(str(exc))
return errors
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/template_validation.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/template_validation.py
index c6e1db89..82fd22fd 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/template_validation.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/template_validation.py
@@ -867,23 +867,32 @@ def validate_pptx_template_package(
pptx_path: str | Path,
specs: list[TemplateSlideSpec],
*,
+ layout_specs: list[TemplateSlideSpec] | None = None,
+ expected_layout_parts: dict[str, str] | None = None,
+ expected_master_parts: dict[str, str] | None = None,
expected_backgrounds: dict[str, str | None] | None = None,
expected_shape_rosters: dict[str, tuple[str, ...]] | None = None,
) -> None:
"""Validate a finished structured PPTX against its explicit SVG contract.
- Export supplies pre-packaging background and shape expectations for exact
- serialization read-back. Callers that only have the finished package still
- receive the portable structure, ownership, and relationship checks.
+ ``specs`` describes published slides. ``layout_specs`` may additionally
+ include internal prototypes for unused Layouts. Export supplies exact part,
+ background, and shape expectations for deterministic serialization
+ read-back. Callers with only published-slide specs retain the original
+ portable relationship checks.
"""
if not specs:
raise ValueError("structured package validation requires at least one slide spec")
+ structure_specs = layout_specs or specs
specs_by_layout: dict[str, list[TemplateSlideSpec]] = {}
+ public_specs_by_layout: dict[str, list[TemplateSlideSpec]] = {}
bindings_by_layout: dict[str, tuple[TemplatePlaceholderBinding, ...]] = {}
try:
- for spec in specs:
+ for spec in structure_specs:
specs_by_layout.setdefault(spec.layout_key, []).append(spec)
+ for spec in specs:
+ public_specs_by_layout.setdefault(spec.layout_key, []).append(spec)
for layout_key, layout_specs in specs_by_layout.items():
bindings_by_layout[layout_key] = template_placeholder_bindings(
layout_specs[0]
@@ -931,8 +940,22 @@ def validate_pptx_template_package(
exact=True,
ordered=True,
)
- layout_parts_by_key: dict[str, str] = {}
- keys_by_layout_part: dict[str, str] = {}
+ layout_parts_by_key = dict(expected_layout_parts or {})
+ keys_by_layout_part = {
+ part: key for key, part in layout_parts_by_key.items()
+ }
+ if len(keys_by_layout_part) != len(layout_parts_by_key):
+ errors.append(
+ "expected Layout part mapping assigns one part to multiple keys"
+ )
+ if expected_layout_parts is not None and (
+ set(expected_layout_parts) != set(specs_by_layout)
+ ):
+ errors.append(
+ "expected Layout key roster differs from the SVG contract; "
+ f"missing={sorted(set(specs_by_layout) - set(expected_layout_parts))}, "
+ f"extra={sorted(set(expected_layout_parts) - set(specs_by_layout))}"
+ )
slide_roots: dict[int, ET.Element] = {}
for spec in specs:
@@ -958,10 +981,7 @@ def validate_pptx_template_package(
)
continue
reader.xml(layout_part)
- previous_part = layout_parts_by_key.setdefault(
- spec.layout_key,
- layout_part,
- )
+ previous_part = layout_parts_by_key.setdefault(spec.layout_key, layout_part)
if previous_part != layout_part:
errors.append(
f"layout key {spec.layout_key!r} targets both {previous_part} "
@@ -980,8 +1000,25 @@ def validate_pptx_template_package(
used_master_parts: set[str] = set()
layout_parts_by_master: dict[str, set[str]] = {}
master_specs_by_part: dict[str, TemplateSlideSpec] = {}
- master_parts_by_key: dict[str, str] = {}
- keys_by_master_part: dict[str, str] = {}
+ master_parts_by_key = dict(expected_master_parts or {})
+ keys_by_master_part = {
+ part: key for key, part in master_parts_by_key.items()
+ }
+ expected_master_keys = {
+ spec.master_key for spec in structure_specs
+ }
+ if len(keys_by_master_part) != len(master_parts_by_key):
+ errors.append(
+ "expected Master part mapping assigns one part to multiple keys"
+ )
+ if expected_master_parts is not None and (
+ set(expected_master_parts) != expected_master_keys
+ ):
+ errors.append(
+ "expected Master key roster differs from the SVG contract; "
+ f"missing={sorted(expected_master_keys - set(expected_master_parts))}, "
+ f"extra={sorted(set(expected_master_parts) - expected_master_keys)}"
+ )
for layout_key, layout_specs in specs_by_layout.items():
prototype = layout_specs[0]
layout_part = layout_parts_by_key.get(layout_key)
@@ -1070,7 +1107,7 @@ def validate_pptx_template_package(
"for exact read-back"
)
slide_placeholders: dict[int, dict[int, _Placeholder]] = {}
- for spec in layout_specs:
+ for spec in public_specs_by_layout.get(layout_key, []):
slide_root = slide_roots.get(spec.slide_num)
if slide_root is None:
continue
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index d595b572..4b9acaed 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -308,7 +308,7 @@ Catalog read: 76 templates
## IX. Content Outline
-> **Native Layout boundary**: Each `Layout` line below always describes visual composition intent. On free-design and brand-only routes, it does not create native Master/Layout identity: `spec_lock.md` uses `pptx_structure.mode: flat`, omits `pptx_masters` / `pptx_layouts` / `page_layouts`, and every SVG object stays Slide-local. Export materializes one clean project-owned Master plus one Blank Layout from the current lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. Deck/layout template routes use `mode: structured`: Strategist writes the Master roster and exactly one `<master_key> | <layout_key> | <PowerPoint layout name>` row per page, and also selects an input prototype through `page_layouts`. Strict preserves the prototype contract. Adaptive keeps its Master and may assign a new Layout key during page authoring only when fixed Layout atoms or slot topology/bounds change. Legacy prototypes first run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md); no deferred distillation or immediate-compatibility fallback exists.
+> **Native Layout boundary**: Each `Layout` line below always describes visual composition intent. On free-design and brand-only routes, it does not create native Master/Layout identity: `spec_lock.md` uses `pptx_structure.mode: flat`, omits `pptx_masters` / `pptx_layouts` / `page_pptx_layouts` / `page_layouts`, and every SVG object stays Slide-local. Export materializes one clean project-owned Master plus one Blank Layout from the current lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. Deck/layout template routes use `mode: structured`: Strategist writes each unique Master/Layout definition once, assigns every page through `page_pptx_layouts`, and selects its authoring prototype through `page_layouts`. Strict preserves the prototype contract. Adaptive keeps its Master and may define and assign a new Layout key during page authoring only when fixed Layout atoms or slot topology/bounds change. Legacy prototypes first run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md); no deferred distillation or immediate-compatibility fallback exists.
### Part 1: [Chapter Name]
diff --git a/skills/ppt-master/templates/layouts/layouts_index.json b/skills/ppt-master/templates/layouts/layouts_index.json
index 5fb4c52c..8ac7827d 100644
--- a/skills/ppt-master/templates/layouts/layouts_index.json
+++ b/skills/ppt-master/templates/layouts/layouts_index.json
@@ -2,7 +2,7 @@
"presentation_core": {
"summary": "A structure-first presentation layout system combining familiar PowerPoint defaults with advanced editorial, image, and data compositions.",
"canvas_format": "ppt169",
- "page_count": 18,
+ "page_count": 20,
"page_types": [
"title_slide",
"title_content",
@@ -21,7 +21,9 @@
"data_story",
"title_picture",
"two_picture_caption",
- "screenshot_focus"
+ "screenshot_focus",
+ "chart_insight",
+ "table_summary"
]
}
}
diff --git a/skills/ppt-master/templates/layouts/presentation_core/templates/19_chart_insight.svg b/skills/ppt-master/templates/layouts/presentation_core/templates/19_chart_insight.svg
new file mode 100644
index 00000000..a8089845
--- /dev/null
+++ b/skills/ppt-master/templates/layouts/presentation_core/templates/19_chart_insight.svg
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720"
+ data-pptx-master="presentation_core_master" data-pptx-master-name="Presentation Core"
+ data-pptx-layout="chart_insight" data-pptx-layout-name="Chart and Insight">
+ <rect id="master-background" x="0" y="0" width="1280" height="720" fill="#FFFFFF"
+ data-pptx-layer="master" data-pptx-editable="false"/>
+ <rect id="chart-insight-chart-panel" x="64" y="152" width="760" height="456" rx="12"
+ fill="#F4F6F8" stroke="#D6DCE3" stroke-width="1"
+ data-pptx-layer="layout" data-pptx-editable="false"/>
+ <rect id="chart-insight-message-panel" x="856" y="152" width="360" height="456" rx="12"
+ fill="#F4F6F8" stroke="#D6DCE3" stroke-width="1"
+ data-pptx-layer="layout" data-pptx-editable="false"/>
+ <g id="chart-insight-title-slot" data-pptx-placeholder="title"
+ data-pptx-placeholder-bounds="64 40 1152 72">
+ <text id="chart-insight-title-carrier" data-pptx-placeholder-carrier="true"
+ x="64" y="90" fill="#1E293B" font-family="Arial, Microsoft YaHei, sans-serif"
+ font-size="36" font-weight="700">{{PAGE_TITLE}}</text>
+ </g>
+ <g id="chart-insight-chart-slot" data-pptx-placeholder="chart" data-pptx-placeholder-idx="1"
+ data-pptx-placeholder-bounds="88 176 712 408">
+ <g id="chart-insight-chart-carrier" data-pptx-placeholder-carrier="true"
+ data-pptx-native="chart"
+ data-pptx-fallback-sha256="e39e729fbcd88647bc948bf86f6974592347d171897ee0568376b13330fdb95b">
+ <metadata data-pptx-native="chart">{"name":"chart_insight","x":88,"y":176,"width":712,"height":408,"type":"column","categories":["Q1","Q2","Q3","Q4"],"series":[{"name":"Actual","values":[42,55,63,78]},{"name":"Plan","values":[48,58,68,74]}],"show_legend":true,"legend_position":"bottom","style":{"colors":["#64748B","#CBD5E1"],"chart_area_fill":"#F4F6F8","plot_area_fill":"#FFFFFF","text_color":"#475569","axis_color":"#CBD5E1","grid_color":"#E2E8F0","font_family":"Arial"}}</metadata>
+ <rect x="88" y="176" width="712" height="408" rx="8" fill="#FFFFFF"/>
+ <rect x="586" y="202" width="12" height="12" rx="2" fill="#64748B"/>
+ <text x="606" y="213" fill="#64748B" font-family="Arial, sans-serif" font-size="14">Actual</text>
+ <rect x="676" y="202" width="12" height="12" rx="2" fill="#CBD5E1"/>
+ <text x="696" y="213" fill="#64748B" font-family="Arial, sans-serif" font-size="14">Plan</text>
+ <line x1="144" y1="520" x2="752" y2="520" stroke="#CBD5E1" stroke-width="2"/>
+ <line x1="144" y1="440" x2="752" y2="440" stroke="#E2E8F0" stroke-width="1"/>
+ <line x1="144" y1="360" x2="752" y2="360" stroke="#E2E8F0" stroke-width="1"/>
+ <line x1="144" y1="280" x2="752" y2="280" stroke="#E2E8F0" stroke-width="1"/>
+ <rect x="190" y="394" width="34" height="126" rx="3" fill="#64748B"/>
+ <rect x="228" y="376" width="34" height="144" rx="3" fill="#CBD5E1"/>
+ <rect x="330" y="355" width="34" height="165" rx="3" fill="#64748B"/>
+ <rect x="368" y="346" width="34" height="174" rx="3" fill="#CBD5E1"/>
+ <rect x="470" y="331" width="34" height="189" rx="3" fill="#64748B"/>
+ <rect x="508" y="316" width="34" height="204" rx="3" fill="#CBD5E1"/>
+ <rect x="610" y="286" width="34" height="234" rx="3" fill="#64748B"/>
+ <rect x="648" y="298" width="34" height="222" rx="3" fill="#CBD5E1"/>
+ <text x="224" y="554" text-anchor="middle" fill="#64748B" font-family="Arial, sans-serif" font-size="15">Q1</text>
+ <text x="364" y="554" text-anchor="middle" fill="#64748B" font-family="Arial, sans-serif" font-size="15">Q2</text>
+ <text x="504" y="554" text-anchor="middle" fill="#64748B" font-family="Arial, sans-serif" font-size="15">Q3</text>
+ <text x="644" y="554" text-anchor="middle" fill="#64748B" font-family="Arial, sans-serif" font-size="15">Q4</text>
+ </g>
+ </g>
+ <g id="chart-insight-message-slot" data-pptx-placeholder="body" data-pptx-placeholder-idx="2"
+ data-pptx-placeholder-bounds="888 184 296 360">
+ <text id="chart-insight-message-carrier" data-pptx-placeholder-carrier="true"
+ x="888" y="232" fill="#334155" font-family="Arial, Microsoft YaHei, sans-serif"
+ font-size="24" font-weight="700">{{KEY_MESSAGE}}</text>
+ </g>
+ <g id="chart-insight-source-slot" data-pptx-placeholder="footer" data-pptx-placeholder-idx="3"
+ data-pptx-placeholder-bounds="888 552 296 32">
+ <text id="chart-insight-source-carrier" data-pptx-placeholder-carrier="true"
+ x="888" y="576" fill="#94A3B8" font-family="Arial, Microsoft YaHei, sans-serif"
+ font-size="14">{{SOURCE}}</text>
+ </g>
+</svg>
diff --git a/skills/ppt-master/templates/layouts/presentation_core/templates/20_table_summary.svg b/skills/ppt-master/templates/layouts/presentation_core/templates/20_table_summary.svg
new file mode 100644
index 00000000..f0299ca5
--- /dev/null
+++ b/skills/ppt-master/templates/layouts/presentation_core/templates/20_table_summary.svg
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720"
+ data-pptx-master="presentation_core_master" data-pptx-master-name="Presentation Core"
+ data-pptx-layout="table_summary" data-pptx-layout-name="Table and Summary">
+ <rect id="master-background" x="0" y="0" width="1280" height="720" fill="#FFFFFF"
+ data-pptx-layer="master" data-pptx-editable="false"/>
+ <rect id="table-summary-table-panel" x="64" y="152" width="824" height="456" rx="12"
+ fill="#F4F6F8" stroke="#D6DCE3" stroke-width="1"
+ data-pptx-layer="layout" data-pptx-editable="false"/>
+ <rect id="table-summary-message-panel" x="920" y="152" width="296" height="456" rx="12"
+ fill="#F4F6F8" stroke="#D6DCE3" stroke-width="1"
+ data-pptx-layer="layout" data-pptx-editable="false"/>
+ <g id="table-summary-title-slot" data-pptx-placeholder="title"
+ data-pptx-placeholder-bounds="64 40 1152 72">
+ <text id="table-summary-title-carrier" data-pptx-placeholder-carrier="true"
+ x="64" y="90" fill="#1E293B" font-family="Arial, Microsoft YaHei, sans-serif"
+ font-size="36" font-weight="700">{{PAGE_TITLE}}</text>
+ </g>
+ <g id="table-summary-table-slot" data-pptx-placeholder="table" data-pptx-placeholder-idx="1"
+ data-pptx-placeholder-bounds="88 176 776 408">
+ <g id="table-summary-table-carrier" data-pptx-placeholder-carrier="true"
+ data-pptx-native="table"
+ data-pptx-fallback-sha256="6537e9228a8e8691fd1870f794329de56b7c51a8c6c40fe4e37d2d8963659f61">
+ <metadata data-pptx-native="table">{"name":"table_summary","x":88,"y":176,"width":776,"height":408,"strict_grid":true,"column_widths":[3,2,2],"row_heights":[1,1,1,1,1],"style":{"font_family":"Arial","font_size":17,"header_font_size":16,"header_fill":"#E2E8F0","header_text":"#334155","body_fill":"#FFFFFF","body_text":"#475569","band_fill":"#F8FAFC","border_color":"#D6DCE3","border_width":1,"padding":{"left":12,"right":12,"top":6,"bottom":6},"valign":"middle"},"columns":[{"text":"Metric","bold":true},{"text":"Current","align":"r","bold":true},{"text":"Target","align":"r","bold":true}],"rows":[[{"text":"Adoption"},{"text":"68%","align":"r","bold":true},{"text":"80%","align":"r"}],[{"text":"Cycle time"},{"text":"12 d","align":"r","bold":true},{"text":"8 d","align":"r"}],[{"text":"Quality"},{"text":"94%","align":"r","bold":true},{"text":"97%","align":"r"}],[{"text":"Cost index"},{"text":"1.08","align":"r","bold":true},{"text":"1.00","align":"r"}]]}</metadata>
+ <rect x="88" y="176" width="776" height="408" rx="8" fill="#FFFFFF" stroke="#D6DCE3" stroke-width="1"/>
+ <rect x="88" y="176" width="776" height="72" rx="8" fill="#E2E8F0"/>
+ <rect x="88" y="248" width="776" height="84" fill="#FFFFFF"/>
+ <rect x="88" y="332" width="776" height="84" fill="#F8FAFC"/>
+ <rect x="88" y="416" width="776" height="84" fill="#FFFFFF"/>
+ <rect x="88" y="500" width="776" height="84" rx="8" fill="#F8FAFC"/>
+ <line x1="480" y1="176" x2="480" y2="584" stroke="#D6DCE3" stroke-width="1"/>
+ <line x1="672" y1="176" x2="672" y2="584" stroke="#D6DCE3" stroke-width="1"/>
+ <line x1="88" y1="248" x2="864" y2="248" stroke="#D6DCE3" stroke-width="1"/>
+ <line x1="88" y1="332" x2="864" y2="332" stroke="#D6DCE3" stroke-width="1"/>
+ <line x1="88" y1="416" x2="864" y2="416" stroke="#D6DCE3" stroke-width="1"/>
+ <line x1="88" y1="500" x2="864" y2="500" stroke="#D6DCE3" stroke-width="1"/>
+ <text x="112" y="222" fill="#334155" font-family="Arial, sans-serif" font-size="16" font-weight="700">Metric</text>
+ <text x="648" y="222" text-anchor="end" fill="#334155" font-family="Arial, sans-serif" font-size="16" font-weight="700">Current</text>
+ <text x="840" y="222" text-anchor="end" fill="#334155" font-family="Arial, sans-serif" font-size="16" font-weight="700">Target</text>
+ <text x="112" y="300" fill="#475569" font-family="Arial, sans-serif" font-size="17">Adoption</text>
+ <text x="648" y="300" text-anchor="end" fill="#334155" font-family="Arial, sans-serif" font-size="17" font-weight="700">68%</text>
+ <text x="840" y="300" text-anchor="end" fill="#475569" font-family="Arial, sans-serif" font-size="17">80%</text>
+ <text x="112" y="384" fill="#475569" font-family="Arial, sans-serif" font-size="17">Cycle time</text>
+ <text x="648" y="384" text-anchor="end" fill="#334155" font-family="Arial, sans-serif" font-size="17" font-weight="700">12 d</text>
+ <text x="840" y="384" text-anchor="end" fill="#475569" font-family="Arial, sans-serif" font-size="17">8 d</text>
+ <text x="112" y="468" fill="#475569" font-family="Arial, sans-serif" font-size="17">Quality</text>
+ <text x="648" y="468" text-anchor="end" fill="#334155" font-family="Arial, sans-serif" font-size="17" font-weight="700">94%</text>
+ <text x="840" y="468" text-anchor="end" fill="#475569" font-family="Arial, sans-serif" font-size="17">97%</text>
+ <text x="112" y="552" fill="#475569" font-family="Arial, sans-serif" font-size="17">Cost index</text>
+ <text x="648" y="552" text-anchor="end" fill="#334155" font-family="Arial, sans-serif" font-size="17" font-weight="700">1.08</text>
+ <text x="840" y="552" text-anchor="end" fill="#475569" font-family="Arial, sans-serif" font-size="17">1.00</text>
+ </g>
+ </g>
+ <g id="table-summary-message-slot" data-pptx-placeholder="body" data-pptx-placeholder-idx="2"
+ data-pptx-placeholder-bounds="952 184 232 344">
+ <text id="table-summary-message-carrier" data-pptx-placeholder-carrier="true"
+ x="952" y="232" fill="#334155" font-family="Arial, Microsoft YaHei, sans-serif"
+ font-size="24" font-weight="700">{{KEY_MESSAGE}}</text>
+ </g>
+ <g id="table-summary-source-slot" data-pptx-placeholder="footer" data-pptx-placeholder-idx="3"
+ data-pptx-placeholder-bounds="952 552 232 32">
+ <text id="table-summary-source-carrier" data-pptx-placeholder-carrier="true"
+ x="952" y="576" fill="#94A3B8" font-family="Arial, Microsoft YaHei, sans-serif"
+ font-size="14">{{SOURCE}}</text>
+ </g>
+</svg>
diff --git a/skills/ppt-master/templates/layouts/presentation_core/templates/design_spec.md b/skills/ppt-master/templates/layouts/presentation_core/templates/design_spec.md
index 6379c0aa..1ee64c31 100644
--- a/skills/ppt-master/templates/layouts/presentation_core/templates/design_spec.md
+++ b/skills/ppt-master/templates/layouts/presentation_core/templates/design_spec.md
@@ -13,7 +13,7 @@ source_canvas_height: 720
source_viewbox: "0 0 1280 720"
replication_mode: fidelity
native_structure_mode: structured
-page_count: 18
+page_count: 20
page_types:
- title_slide
- title_content
@@ -33,6 +33,8 @@ page_types:
- title_picture
- two_picture_caption
- screenshot_focus
+ - chart_insight
+ - table_summary
placeholders:
01_title_slide: ["{{TITLE}}", "{{SUBTITLE}}"]
02_title_content: ["{{PAGE_TITLE}}", "{{CONTENT_AREA}}"]
@@ -52,6 +54,8 @@ placeholders:
16_title_picture: ["{{PAGE_TITLE}}"]
17_two_picture_caption: ["{{PAGE_TITLE}}", "{{LEFT_CAPTION}}", "{{RIGHT_CAPTION}}"]
18_screenshot_focus: ["{{PAGE_TITLE}}", "{{ANNOTATION}}", "{{SOURCE}}"]
+ 19_chart_insight: ["{{PAGE_TITLE}}", "{{KEY_MESSAGE}}", "{{SOURCE}}"]
+ 20_table_summary: ["{{PAGE_TITLE}}", "{{KEY_MESSAGE}}", "{{SOURCE}}"]
---
# Presentation Core — Design Specification
@@ -76,6 +80,7 @@ identity decisions and are not owned by this layout.
| Regular vocabulary | Nine familiar PowerPoint layouts preserve the expected title, content, comparison, caption, picture, and blank starting points. |
| Editorial rhythm | Hero, split, card, process, and data layouts alternate breathing and dense structures instead of repeating one card grid. |
| Image system | Picture layouts use explicit native picture regions for one-image, paired-image, captioned-image, and screenshot scenarios. |
+| Native data system | Dedicated chart and table layouts use real native object slots plus a concise interpretation rail, while retaining complete SVG fallbacks. |
| Text entry | General body and object slots begin at the upper-left; centered alignment is reserved for KPI values, short process nodes, and focused statements. |
| Neutral framing | Pale panels and hairlines reveal intended zones in the prototype; downstream deck or brand skin controls final paint. |
@@ -101,3 +106,5 @@ identity decisions and are not owned by this layout.
| `16_title_picture.svg` | `title_picture` | Title and Picture | Page title over one large native picture region |
| `17_two_picture_caption.svg` | `two_picture_caption` | Two Pictures with Captions | Two equal native pictures with independent captions |
| `18_screenshot_focus.svg` | `screenshot_focus` | Screenshot Focus | Screenshot frame with annotation and source rail |
+| `19_chart_insight.svg` | `chart_insight` | Chart and Insight | Native chart region with interpretation and source rails |
+| `20_table_summary.svg` | `table_summary` | Table and Summary | Native table region with summary and source rails |
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index fe994db1..b48b7f0f 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -75,7 +75,7 @@
>
> **Size slots are anchors, not a closed menu.** Common slots (`title` / `subtitle` / `annotation`) cover frequent cases. Add role-specific slots (e.g. `cover_title: 88`, `hero_number: 56`, `subheading: 32`, `lead: 30`, `footnote: 16`, `chart_annotation: 16`) for the roles the deck actually uses — common for cover-heavy decks, consulting-style hero numbers, dense pages. **Mandatory — scan `§IX` and declare a slot for every role that recurs across pages, not just the four defaults.** A report / `text`-mode deck almost always recurs a per-page **core-message / lead line** and **page numbers / source credits / footnotes** → declare `lead` and `footnote` for them. `subheading` and `lead` sit between `subtitle` and `body` (their bands overlap `subtitle`) — pick by role, not size — and the core-message `lead` is a **primary** line, **always ≥ `body`**, never smaller. Leaving a recurring lead / footnote undeclared forces the Executor to improvise an unlocked size (and a core line improvised below `body` inverts the hierarchy). **Structural roles (title / body / subtitle / annotation / footnote) render at their locked size on every page — one role, one size, deck-wide.** Intermediate in-band sizes are for special / feature elements only (hero number, display title, one-off emphasis); declare a recurring one as its own slot so it stays consistent too.
>
-> **Generated Master defaults**: `pptx_structure.mode: flat` and `mode: structured` require unitless `title` and `body`. Native export writes `title` into every generated Master `titleStyle` default and `body` into every `bodyStyle` / `otherStyle` default, changing only `a:defRPr@sz`. Direct page-run sizes and role-specific structured-Layout placeholder prototype sizes remain unchanged.
+> **Generated Master defaults**: `pptx_structure.mode: flat` and `mode: structured` require unitless `title` and `body`. Native export writes `title` into every generated Master `titleStyle` default and derives a deterministic nine-level, non-increasing size hierarchy from `body` for `bodyStyle` / `otherStyle`. It changes only each level's `a:defRPr@sz`, preserving indentation, bullets, and paragraph settings. Direct page-run sizes and role-specific structured-Layout placeholder prototype sizes remain unchanged.
>
> **⚠️ PPT-safe stack discipline (HARD rule).** Flat and structured export map `title_family` to the PowerPoint theme major font and `body_family` (or `font_family`) to the theme minor font. Runs whose resolved face matches either role use `+mj-*` / `+mn-*` theme tokens; other role families remain concrete per-run typefaces. Every exported Latin / EA face MUST therefore resolve to cross-platform pre-installed fonts: `"Microsoft YaHei"` / `SimSun` / `Arial` / `"Times New Roman"` / `Consolas`. Stacks that resolve to non-preinstalled typefaces (Inter / Google Fonts / brand typefaces) may be used only when the Design Spec notes the font-install or embedding requirement.
>
@@ -129,7 +129,7 @@
> One deck-wide native PowerPoint structure policy. Free-design and brand-only routes use `flat`; deck/layout template routes use `structured`.
>
-> `flat` keeps every SVG object Slide-local. Export materializes one clean project-owned Master plus one Blank Layout, maps the current color/typography lock into the theme and Master defaults, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks. In this mode, omit the complete `pptx_masters`, `pptx_layouts`, and `page_layouts` sections, and do not add root Master/Layout identity, `data-pptx-layer`, or `data-pptx-placeholder*` metadata to generated pages.
+> `flat` keeps every SVG object Slide-local. Export materializes one clean project-owned Master plus one Blank Layout, maps the current color/typography lock into the theme and Master defaults, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks. In this mode, omit `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`, and do not add root Master/Layout identity, `data-pptx-layer`, or `data-pptx-placeholder*` metadata to generated pages.
>
> When Step 3 loaded a deck/layout template, replace the `flat` row above with exactly one of:
> ```
@@ -141,7 +141,7 @@
> - mode: structured
> - template_adherence: strict
> ```
-> Both values require complete `page_layouts`, `pptx_masters`, and `pptx_layouts` sections. Existing legacy template SVGs that lack the current root Master identity, grouped slot/carrier contract, or positive bounds must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before they can be selected.
+> Both values require complete `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts` sections. Existing legacy template SVGs that lack the current root Master identity, grouped slot/carrier contract, or positive bounds must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before they can be selected.
## pptx_masters
- master-default: Default Master
@@ -149,16 +149,16 @@
> Deck/layout template routes only. One row per Master: `<master_key>: <PowerPoint picker name>`. Keys are deck-unique and stable. Omit this entire section when `pptx_structure.mode: flat`.
## pptx_layouts
-- P01: master-default | cover-hero-split | Cover — Hero Split
-- P02: master-default | kpi-band-trio | KPI Band Trio
-- P03: master-default | content-two-column | Two Column
-- P04: master-default | content-two-column | Two Column
+- cover-hero-split: master-default | Cover — Hero Split | template:01_cover
+- kpi-band-trio: master-default | KPI Band Trio | P02
+- content-two-column: master-default | Two Column | template:03a_content_abstract
+- quote-focus: master-default | Quote Focus | template:04_quote_focus
-> Deck/layout template routes only. Include exactly one row per page before SVG generation. Value format: `<master_key> | <layout_key> | <PowerPoint layout name>`. Omit this entire section when `pptx_structure.mode: flat`.
+> Deck/layout template routes only. This is the unique reusable Layout roster, not a page roster. Value format: `<master_key> | <PowerPoint layout name> | <prototype source>`. A prototype source is either `P<NN>` for one generated page carrying that exact Layout contract, or `template:<basename>` for an installed `templates/<basename>.svg`. Omit this section when `pptx_structure.mode: flat`.
>
-> The page SVG repeats all three identities on its root through `data-pptx-master`, `data-pptx-master-name`, `data-pptx-layout`, and `data-pptx-layout-name`. A Layout key belongs to exactly one Master and must be globally unique even when two source Masters use the same picker name.
+> Every Layout key appears exactly once, belongs to exactly one declared Master, and is globally unique even when two Masters use the same picker name. Every declared Master owns at least one Layout definition. A Layout may remain unused by generated pages; such a Layout must use `template:<basename>` so export can register it without manufacturing a published slide.
>
-> Strategist plans the initial family roster. Executor writes the declared structure while drawing each page. If adaptive template use genuinely changes the reusable framing or slot topology/bounds, create a new Layout key and update this mapping immediately; never silently mutate a reused key.
+> The definition prototype repeats its identity through root `data-pptx-master`, `data-pptx-master-name`, `data-pptx-layout`, and `data-pptx-layout-name`. Strategist plans the initial roster. If adaptive use genuinely changes reusable framing or slot topology/bounds, Executor adds a new definition and updates the page assignment immediately; never mutate a reused key silently.
>
> Reuse one `(master_key, layout_key)` only when its ordered Layout atoms and slot ids/types/indices/bounds/binding modes are identical. Current text, imagery, crop, or Slide-local geometry does not define Layout identity.
>
@@ -166,12 +166,20 @@
>
> A Layout may have zero slots. Do not create an empty `utility` kind or a full-page fake `object` slot; the named Layout and its fixed atoms are sufficient.
+## page_pptx_layouts
+- P01: cover-hero-split
+- P02: kpi-band-trio
+- P03: content-two-column
+- P04: content-two-column
+
+> Deck/layout template routes only. Include exactly one row per generated page. The value is one key declared in `pptx_layouts`; Master and picker name come from that unique definition and are not repeated per page. The generated SVG root must match the assigned definition. Omit this section when `pptx_structure.mode: flat`.
+
## page_layouts
- P01: 01_cover
- P03: 02a_chapter
- P04: 03a_content_abstract
-> For a deck/layout template route, include one entry per page. Key: `P<NN>` matching §IX. Value: the template SVG basename without extension. This is the input prototype mapping; `pptx_layouts` is the output mapping and is present at the same time. Strict preserves the prototype Master/Layout/slot contract. Adaptive retains its Master contract and may explicitly assign a new Layout key while authoring. Non-mirror skin follows the project lock.
+> For a deck/layout template route, include one entry per page. Key: `P<NN>` matching §IX. Value: the template SVG basename without extension. This is the authoring-input prototype mapping; `page_pptx_layouts` is the output page assignment, while `pptx_layouts` defines the unique reusable roster. Strict preserves the prototype Master/Layout/slot contract. Adaptive retains its Master contract and may explicitly define and assign a new Layout key while authoring. Non-mirror skin follows the project lock.
>
> **No entry for a page** is an error in structured template mode.
>
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index 60f87df5..05d78b73 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -171,13 +171,13 @@ Interpretation rule (carries forward into Steps 2 and 4):
- cleaned complete-page projections are optional composition spot checks for authored modes and verification views for mirror. They are never the lossless restoration source.
- screenshots remain useful for judging composition and style, but should not override extracted factual metadata unless the import result is clearly incomplete
-**Mirror reachability gate**: compare every `native_structure.json.layouts[*].usedBySlides`
-entry with the source Master roster before offering `mirror`. The current
-structured template compiler materializes only identities referenced by emitted
-SVG prototypes. If any source Layout is unused, or any source Master is not
-reachable through a referenced Layout, full-graph mirror is currently
-unsupported. Report the exact keys and stop; do not silently omit them or create
-a synthetic carrier page.
+**Mirror complete-graph gate**: compare every `native_structure.json` Layout
+and Master with the layered projection inventory before offering `mirror`.
+Every source Layout—including one unused by all source slides—must have a
+lossless Layout projection from which a reusable definition SVG can be restored.
+Every source Master must own at least one retained Layout. Missing projections
+or ambiguous parentage are blocking; unused identities themselves are supported
+and must not be dropped.
### Basic norm extraction (mandatory when reference content exists)
@@ -281,7 +281,7 @@ Items to surface:
| Tone summary | Yes | `[suggested]` from analysis (e.g. `Modern, restrained, data-driven`) |
| Theme mode | Yes | A: `[fact]` from `manifest.json` background colors. B: `[fact]` from SVG `fill`. C: `[suggested]` from visual estimate. D: `[decision]` |
| Canvas format and dimensions | Yes | A/B: `[fact]` from slide size or SVG `width` / `height` / `viewBox`; show `canvas_format`, `canvas_width`, `canvas_height`, `canvas_viewbox`, and `source_viewbox`. C: `[suggested]` from image aspect ratio. D: `[decision]`, default `ppt169` (`1280x720`, `0 0 1280 720`) |
-| Replication mode | Yes | `[decision]` — `standard` always available; `fidelity` is available for A/B; `mirror` is available for A only when every source Master/Layout is reachable from a source slide, and only for B sources with a complete explicit structure contract whose declared identities are all page-referenced. `standard` / `fidelity` author new SVG semantics, while mirror retains one restored prototype per source slide in source order. Reject `fidelity` / `mirror` for C/D. |
+| Replication mode | Yes | `[decision]` — `standard` always available; `fidelity` is available for A/B; `mirror` is available for A and for B sources with a complete explicit structure contract. `standard` / `fidelity` author new SVG semantics. Mirror retains one restored prototype per source slide in source order and adds definition-only prototypes for source Layouts unused by those slides. Reject `fidelity` / `mirror` for C/D. |
| Native structure facts | Type A and structured Type B | `[fact]` from `native_structure.json` / source SVG contract: master/layout counts, parentage, page assignments, placeholder identities, and multi-master status. Mirror restores these facts; authored modes do not use them as output topology. |
| Mode-specific ownership | Yes | `standard` / `fidelity`: `[decision]` newly authored Master/Layout ownership, including the reusable-family reason for every additional Master. `mirror`: `[fact]` source ownership restored without synthesis. Every Master must own at least one emitted Layout and every Layout must have at least one emitted prototype; export never infers either contract. |
| Visual fidelity for fixed pages | Yes for `standard` / `fidelity` when reference exists; **N/A for `mirror`** (mirror restores the source visual) | `[decision]` — `literal` (closely reproduce reference geometry / decoration / sprite crops within a newly authored structure) or `adapted` (use reference tone/composition but allow design evolution). Different page types may take different settings. |
@@ -323,7 +323,7 @@ Skipping this gate — including silently inferring values from the reference so
- [ ] Output scope is confirmed; both scopes use the same workspace shape, while `project` includes an explicit initialized target-project path
- [ ] The canvas format is fixed before SVG generation
- [ ] Replication mode is consistent with the input type (`fidelity` allowed for A/B; `mirror` allowed for A and structured B only; both forbidden for C/D)
-- [ ] Before offering `mirror`, every source Layout has at least one source-slide reference and every source Master is reachable through those Layouts; otherwise the exact unsupported identities were reported and mirror was not selected
+- [ ] Before offering `mirror`, the source graph and supported geometry are complete; every source Layout absent from the source-slide roster is planned as a definition-only prototype, and any genuinely missing/unsupported facts were reported
- [ ] Basic template norms from prior content have been surfaced and accepted, or explicitly marked N/A when no reference exists
- [ ] Mode-specific ownership policy is explicit: `standard` / `fidelity` author a new structure without source-topology distillation; `mirror` restores source ownership one-to-one
- [ ] For `library`, metadata is complete enough to register into the relevant index; for `project`, the same portable template metadata is complete and no global registration is planned
@@ -401,7 +401,7 @@ Do not package `native_structure.json` or `source_template.pptx` as template inp
**Native-shape metadata boundary**: The lightweight authoring projection removes opaque payload only from model context; it never becomes the restoration source. `standard` / `fidelity` use compact canonical shapes and assets rather than copied source payload. `mirror` reuses only native metadata already supported by the converter on unchanged Slide-local/slot objects. Fixed layers are normalized to direct atoms; unsupported or edited objects keep the current SVG fallback and are reported rather than silently replaced by stale metadata.
-Downstream, both template-adherence choices use `pptx_structure.mode: structured`. `page_layouts` selects one complete input prototype per page, while `pptx_masters` and `pptx_layouts` declare the output mapping before the first SVG. Strict preserves the selected prototype contract. Adaptive keeps its Master and may explicitly create a new Layout key/name while authoring the page that needs it. A mirror-created package does not force a future generated deck to keep the source page count or order.
+Downstream, both template-adherence choices use `pptx_structure.mode: structured`. `page_layouts` selects one complete authoring prototype per page, `pptx_masters` / `pptx_layouts` declare unique reusable definitions, and `page_pptx_layouts` assigns generated pages. Strict preserves the selected prototype contract. Adaptive keeps its Master and may explicitly create and assign a new Layout key/name while authoring the page that needs it. A retained Layout may remain unassigned while still registering through its definition SVG. A mirror-created package does not force a future generated deck to keep the source page count or order.
**Apply the visual-fidelity decision from Step 3 to authored modes**: in `standard` / `fidelity`, pages marked `literal` reproduce the selected reference geometry and decoration while still using a newly designed structure; pages marked `adapted` may evolve the composition. Mirror restores every supported source visual and does not use this authored-page distinction.
@@ -412,6 +412,7 @@ Downstream, both template-adherence choices use `pptx_structure.mode: structured
1. **Restores one output SVG per source page** in `<template_workspace>/templates/`. Use lightweight projections for inspection, but materialize from the matching lossless source and native structure facts. Preserve source Master/Layout keys and picker names, Layout parentage, slide assignment, placeholder type/index/bounds, ownership, paint order, and supported native metadata. Mechanical namespace, root-declaration, asset-path, and fixed-layer group normalization is allowed only when source ownership and appearance remain unchanged.
- Type A restoration source: `<import_workspace>/svg/`, `<import_workspace>/svg-flat/`, `svg/inheritance.json`, and `native_structure.json`
- Type B restoration source: the complete explicit source SVG contract; `authoring-svg/` remains inspection-only
+ - For every source Layout unused by all source slides, additionally restore one definition-only SVG named `layout_<layout_key>.svg` from its lossless Master/Layout projections. It carries the exact root identity, fixed atoms, and placeholder contract but is not a generated page assignment. Use source placeholder prompts/carriers; do not invent business content. This definition SVG lets downstream export register the Layout and any otherwise-unused parent Master without retaining an internal carrier slide.
2. **Renames each file** using the source-order-first convention `<NNN>_<page_type>.svg`, where `<NNN>` is the source-order index zero-padded to 3 digits and `<page_type>` is typically `cover` / `toc` / `chapter` / `content` / `ending` (fall back to `content` when the type cannot be confidently classified). Examples: `001_cover.svg`, `002_toc.svg`, `003_content.svg`, ..., `050_ending.svg`.
- Type A: derive `<page_type>` from `manifest.json.pageTypeCandidates`
- Type B: derive `<page_type>` from the source filename when it follows the PPT Master convention (`01_cover.svg` → `cover`, `03a_content_two_col.svg` → `content`); otherwise infer from page content or fall back to `content`
@@ -429,7 +430,7 @@ Mirror mode does not simplify the visual target or synthesize layer ownership. T
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 portable brief frontmatter; `register_template.py` consumes it only in library scope. **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 Master/Layout key/name, direct atomic Master/Layout elements, and direct slot `<g>` elements with explicit design-zone bounds plus exactly one compatible carrier. Composite regions use only the explicit `object` + `proxy` downgrade. Minimal structural `data-pptx-role` hints are added only when specialized metadata cannot express required behavior. Both strict and adaptive downstream set `mode: structured` and require complete `page_layouts`, `pptx_masters`, and `pptx_layouts` from planning onward.
+ - `{{...}}` placeholders are the authoring vocabulary used to generate final slide content. Each emitted SVG also carries the native reconstruction contract: root Master/Layout key/name, direct atomic Master/Layout elements, and direct slot `<g>` elements with explicit design-zone bounds plus exactly one compatible carrier. Composite regions use only the explicit `object` + `proxy` downgrade. Minimal structural `data-pptx-role` hints are added only when specialized metadata cannot express required behavior. Both strict and adaptive downstream set `mode: structured` and require complete `page_layouts`, `page_pptx_layouts`, `pptx_masters`, and `pptx_layouts` from planning onward.
4. Template assets (optional) — both scopes apply the same `templates/` / `images/` / dual-icon routing defined above
**Hard rule — placeholder examples are executable defaults**: In authored
@@ -492,12 +493,12 @@ This checker validates the authoring contract, not the compiled OOXML package. T
- [ ] `standard` / `fidelity` output SVGs and their Master/Layout/slot contracts were newly authored without preserving or distilling source topology
- [ ] Every additional authored Master represents a distinct reusable design family, not one Layout or an equivalent duplicate; every declared Master owns at least one emitted Layout and every declared Layout has at least one emitted prototype
- [ ] Mirror output preserves source slide order, Master/Layout identity and parentage, placeholder facts, and ownership; fixed-layer group expansion is mechanical and pixel-equivalent, and the Source Restoration Map lists every source slide
-- [ ] Mirror preflight proved that the source graph has no unused Layout or unreachable Master that the one-prototype-per-source-slide roster would silently omit
+- [ ] Mirror preflight covered the complete source graph; each unused Layout has one `layout_<layout_key>.svg` definition prototype and each otherwise-unused Master is retained through at least one such Layout
- [ ] For `standard` / `fidelity`, no duplicate-Layout-contract warning remains; mirror may keep equivalent source Layout identities when the restoration map explains them
- [ ] Lightweight projections were used only for inspection. Mirror materialized from lossless sources, reused only converter-supported metadata on unchanged Slide-local/slot objects, and kept fixed Master/Layout visuals as direct atoms
- [ ] If any SVG references an extracted vector `data-icon`, the corresponding SVG asset exists under `<template_workspace>/templates/icons/` and the identical runtime copy exists under `<template_workspace>/icons/`; 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: `<template_source>/*_*.svg` matches the lossless `<import_workspace>/svg-flat/slide_*.svg` count; type B: matches the source SVG count); filenames follow the `<NNN>_<page_type>.svg` convention; **no new `{{...}}` authoring placeholders were inserted into restored SVGs**; §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
+- [ ] For `mirror` mode: source-page SVG count equals source page count, while additional files are exactly the required `layout_<layout_key>.svg` definitions for unused source Layouts; source-page filenames follow the `<NNN>_<page_type>.svg` convention; **no new `{{...}}` authoring placeholders were inserted into restored source-page SVGs**; §V Page Roster lists every emitted file and marks definition-only prototypes explicitly
This step is a **hard gate**. Do not generate a review PPTX, register, or hand the workspace to the main pipeline until validation passes. A one-Master template may skip Step 6 when no review was requested; a multi-Master template must continue to Step 6 and may not register or complete before that package gate passes.
diff --git a/skills/ppt-master/workflows/refine-spec.md b/skills/ppt-master/workflows/refine-spec.md
index 1791d806..b8cabc85 100644
--- a/skills/ppt-master/workflows/refine-spec.md
+++ b/skills/ppt-master/workflows/refine-spec.md
@@ -49,7 +49,7 @@ These overlap with what the locked `mode`, visual style, and §6.1 already shape
**Keep both files in sync on every change.** Any revision the user approves must land in both `design_spec.md` and `spec_lock.md`; on divergence `spec_lock.md` wins (see [`strategist.md`](../references/strategist.md) §6.2). Iterate as many rounds as the user wants. The loop ends only when the user explicitly approves the spec.
-**Re-run the structured-template preflight after structural revisions.** If the user changes `template_adherence`, `page_layouts`, the Master roster, or any page Layout choice, repeat the Strategist preflight in [`strategist.md`](../references/strategist.md) §6.2 before approval and hand-back. Every newly selected prototype must declare root Master/Layout identity, direct atomic Master/Layout visuals, and valid top-level slot groups with positive bounds plus one compatible carrier or explicit composite `object` proxy. A zero-slot Layout is valid. Update `pptx_masters` and the complete per-page `pptx_layouts` mapping in both artifacts immediately. A legacy prototype must run [`restore-pptx-structure`](./restore-pptx-structure.md); do not create a fallback mode inside refinement.
+**Re-run the structured-template preflight after structural revisions.** If the user changes `template_adherence`, `page_layouts`, the Master/Layout definition roster, or any `page_pptx_layouts` assignment, repeat the Strategist preflight in [`strategist.md`](../references/strategist.md) §6.2 before approval and hand-back. Every newly selected prototype must declare root Master/Layout identity, direct atomic Master/Layout visuals, and valid top-level slot groups with positive bounds plus one compatible carrier or explicit composite `object` proxy. A zero-slot Layout is valid. Update `pptx_masters`, unique `pptx_layouts` definitions, and complete `page_pptx_layouts` assignments in both artifacts immediately. A legacy prototype must run [`restore-pptx-structure`](./restore-pptx-structure.md); do not create a fallback mode inside refinement.
---
diff --git a/skills/ppt-master/workflows/restore-pptx-structure.md b/skills/ppt-master/workflows/restore-pptx-structure.md
index 8cc2fa91..dcee5e28 100644
--- a/skills/ppt-master/workflows/restore-pptx-structure.md
+++ b/skills/ppt-master/workflows/restore-pptx-structure.md
@@ -60,11 +60,13 @@ Use this evidence priority:
| 2 | Legacy template SVGs or explicit legacy structure metadata | Preserve stable identities and reusable geometry after removing legacy-only fields |
| 3 | Completed SVG pages only | Classify deliberately across the full deck; do not let the exporter infer structure |
-**Hard rule — reachable native graph only**: The current structured contract
-materializes Master/Layout identities through output-page references. If native
-evidence contains a Layout unused by every output page, or a Master reachable
-only through such Layouts, stop and list the exact identities. Do not silently
-drop them, synthesize a carrier page, or claim full source-graph restoration.
+**Hard rule — complete native graph**: Preserve every supported native Layout,
+including one unused by every output page. Create a definition-only
+`layout_<layout_key>.svg` prototype for each otherwise unrepresented Layout and
+record it in the unique `pptx_layouts` roster with a
+`template:<basename>` source. A Master reachable only through such Layouts is
+retained through their parent relationship. Do not silently drop identities or
+synthesize a generated carrier page.
**Hard rule**: Decide from SVG/lock semantics, never from whether `design_spec.md` is at the workspace root or under `templates/`.
@@ -148,11 +150,15 @@ After every SVG has its final metadata, replace the legacy structure sections as
- master-default: Default Master
## pptx_layouts
-- P01: master-default | cover-visual | Cover Visual
-- P02: master-default | content-two-column | Two Column
+- cover-visual: master-default | Cover Visual | P01
+- content-two-column: master-default | Two Column | P02
+
+## page_pptx_layouts
+- P01: cover-visual
+- P02: content-two-column
```
-**Hard rule**: `pptx_masters` contains every referenced Master key exactly once. `pptx_layouts` contains exactly one row for every generated page. Each row must match that page root's Master key, Layout key, and Layout name.
+**Hard rule**: `pptx_masters` contains every Master key exactly once. `pptx_layouts` contains every unique reusable Layout exactly once and declares its Master, picker name, and definition source. `page_pptx_layouts` contains exactly one assignment for every generated page. Each page root must match its assigned Layout definition. A Layout unused by generated pages uses `template:<basename>` as its definition source.
**Layout identity**: A Layout key is globally unique. Pages may reuse it only when their Layout atoms and slot id/type/index/bounds/binding/carrier contracts are identical. The same display name under two Masters still uses two different keys.
diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.md
index 3784c366..3716c278 100644
--- a/skills/ppt-master/workflows/routing.md
+++ b/skills/ppt-master/workflows/routing.md
@@ -68,7 +68,7 @@ Route selection authority for PPT Master. Use this file before entering the main
| Brand identity setup | Brand asset, brand site URL, branded PPTX/PDF, or explicit brand setup request | [`create-brand`](./create-brand.md) | Brand source exists or can be inspected | Complete identity-only workspace under `templates/brands/<id>/` | Stop if no brand source or brand intent exists |
| Continue a split-mode project | "Continue generating `projects/<name>`" after the planning session | [`resume-execute`](./resume-execute.md) | Project has planning-session artifacts | Execution-session SVG generation and export | Stop if required planning artifacts are missing |
| Refine spec before generation | User explicitly asks to refine/review/revise the spec before SVG work, or confirms `refine_spec: true` | [`refine-spec`](./refine-spec.md) | Strategist confirmation stage completed | Revised `design_spec.md` and `spec_lock.md` before Step 5/6 | Stop until user approves the refined spec |
-| Restore legacy PowerPoint structure | Existing structured/template SVGs use unmapped `baseline`, `preserve`, `layout_strategy: distill`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, or an incomplete root Master identity | [`restore-pptx-structure`](./restore-pptx-structure.md) before generation/export or before Step 3 template consumption | Legacy structured SVG project/package exists; original PPTX/native facts are used when available; an explicit `mode: flat` free-design/brand-only project and a flat package directory are not triggers | Current structured SVG contract plus complete `pptx_masters`/`pptx_layouts` mapping | Stop if structure cannot be restored without an explicit design decision |
+| Restore legacy PowerPoint structure | Existing structured/template SVGs use unmapped `baseline`, `preserve`, `layout_strategy: distill`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, or an incomplete root Master identity | [`restore-pptx-structure`](./restore-pptx-structure.md) before generation/export or before Step 3 template consumption | Legacy structured SVG project/package exists; original PPTX/native facts are used when available; an explicit `mode: flat` free-design/brand-only project and a flat package directory are not triggers | Current structured SVG contract plus unique `pptx_masters` / `pptx_layouts` definitions and complete `page_pptx_layouts` assignments | Stop if structure cannot be restored without an explicit design decision |
| Data chart calibration | Generated deck contains data charts | [`verify-charts`](./verify-charts.md) between Step 6 and Step 7 | SVG pages exist | Calibrated chart coordinates before export | Stop on chart geometry errors until fixed |
| Object-level animation tuning | User asks for animation order, timing, effects, or object reveal behavior | [`customize-animations`](./customize-animations.md) | SVG groups / exported context exist | `animations.json` or validated animation config | Stop if requested target objects cannot be identified |
| Live preview / element selection / annotations | User mentions live preview, preview, visual check in browser, clicking/selecting an element, or applying browser annotations | [`live-preview`](./live-preview.md) | Project exists; for annotation apply, generated SVGs exist | Running preview service or applied annotations plus re-export | Stop only if project path or SVGs are missing |