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

docs(pptx-layouts): author structure from the first SVG

hugohe3c79d2c6a5cbd
diff --git a/docs/faq.md b/docs/faq.md
index 55d6cdbb..296b509b 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -240,7 +240,7 @@ Want to turn a PPT you love into a reusable template for PPT Master? Here's how:
**Step 1 — Prepare Reference Material**
-The recommended input is the original `.pptx`. PPT Master extracts theme identity, every Master/Layout, placeholder metadata, and reusable assets, then rebuilds one clean Master plus semantic Layouts as complete, explicitly annotated SVG pages. When that template is used, `adaptive` may create a new explicit Layout under the same Master; `strict` keeps the selected Layout contract unchanged. Both routes reconstruct native structure from the SVGs.
+The recommended input is the original `.pptx`. PPT Master extracts theme identity, the complete Master/Layout topology, placeholder metadata, and reusable assets, then reconstructs every source Master and Layout as complete structured SVG pages. Source Master/Layout groups are flattened object by object into direct atomic layer elements; supported appearance, parent relationships, picker names, placeholder type/index/bounds, and stacking order are retained, but the source group-editing hierarchy is not. When that template is used, `adaptive` may create a new explicit Layout under the retained Master; `strict` preserves the selected Master/Layout/slot contract.
If no source PPTX exists, screenshots of the key page types still work — cover, TOC, chapter, content, and closing — but geometry, fonts, and inheritance must then be inferred visually.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 633f57cb..fe5c3b5a 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 + conservative PPTX object round-trip** — free-design baseline export promotes only safe shared backgrounds/chrome, assigns marker-backed Layout families, and may lift exact family-wide leading structurally marked chrome without inferring placeholders; marker-free legacy SVGs retain filename/id fallback. Template export deterministically compiles complete SVG pages whose Master/Layout/placeholder ownership is explicit and writes locked title/body sizes into Master `p:txStyles` without changing direct slide-run sizes. `create-template` uses imported source structure as analysis input and always rebuilds explicit SVG structure; strict keeps a selected Layout, adaptive may add a new Layout under the same Master. Its default library output remains indexed, while project scope installs the same thin contract directly into one initialized project's template root with no global registration. Legacy `preserve` remains compatibility-only. Raw one-off PPTX filling remains `template-fill-pptx`.
+- **Native package structure + conservative PPTX object round-trip** — every new SVG page declares its final Master/Layout identity while it is 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. Export deterministically compiles only that contract, writes locked title/body sizes into Master `p:txStyles`, and performs final package read-back; it never promotes repeated chrome or infers placeholders. `create-template` restores the source Master/Layout topology into the same explicit SVG model; strict keeps a selected Layout, while adaptive may add a new Layout under the same Master. Legacy baseline/template/preserve SVG packages first run `restore-pptx-structure`. Raw one-off PPTX filling remains `template-fill-pptx`.
---
@@ -118,7 +118,7 @@ PPT Master's main route is "AI generates SVG from scratch → DrawingML", with t
**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.
-> **Supported boundaries**: `template-fill-pptx` directly refills selected source slides. `create-template` turns source Master/Layout facts into reviewed, complete, explicitly layered SVG templates. Strict and adaptive downstream use both reconstruct native structure from those SVG contracts. What remains out of scope is unreviewed, schema-free substitution against arbitrary third-party placeholder systems.
+> **Supported boundaries**: `template-fill-pptx` directly refills selected source slides. `create-template` turns source Master/Layout facts into reviewed, complete, explicitly layered SVG templates. Strict and adaptive downstream use both to reconstruct native structure from those SVG contracts. What remains out of scope is unreviewed, schema-free substitution against arbitrary third-party placeholder systems.
### Switch to native PowerPoint charts (Excel-native chart)
diff --git a/docs/technical-design.md b/docs/technical-design.md
index e3695aa6..079eb496 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -41,8 +41,6 @@ User Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text)
↓
[Visual self-check (optional, opt-in)] → visual-review workflow (only when the user explicitly requests it)
↓
-[Reusable Layout distillation (baseline: explicit selection; template: mandatory deferred finalization)] → distill-layouts workflow
- ↓
[Post-processing] → total_md_split.py (split notes) → finalize_svg.py → svg_to_pptx.py
↓
Output:
@@ -64,7 +62,7 @@ Output:
For every workflow that authors or redesigns visual slides through SVG, `svg_output/` is the complete page-design authority. Every visible text, image, shape, diagram, chart/table fallback, background, and template-derived layout element that should appear on a slide must already exist in that page SVG or be explicitly referenced by it. Templates, `design_spec.md`, and `spec_lock.md` guide SVG authoring; the exporter does not use them as a second visual layer that fills in missing page content.
-Minimal semantic markers do not weaken that closure. Existing Layout/Layer/Placeholder/Native metadata remains authoritative. Baseline/free-design pages stay unmapped while their visual design is being created and may use root `data-pptx-page-role` for compatibility routing. Deferred template pages carry the selected `page_layouts` prototype but do not finalize `pptx_layouts` or root kind during design. After the complete pages exist, `distill-layouts` writes the all-page output contract: explicit baseline selections plus utility mappings, or strict/adaptive template reconciliation for every page. `data-pptx-role` is reserved for the few structural page-frame objects whose package or animation behavior is not already expressed by specialized metadata.
+Minimal semantic markers do not weaken that closure. Every new page declares its Master/Layout identity from the first SVG draft. Fixed Master/Layout visuals are direct atomic root children, while reusable content slots are top-level groups with explicit design-zone bounds and one compatible carrier; composite `object` regions use an explicit proxy fallback, and zero-slot Layouts are valid. `data-pptx-role` is reserved for the few structural page-frame objects whose package or animation behavior is not already expressed by specialized metadata. Legacy or unmapped SVGs first run `restore-pptx-structure`; export never infers structure.
| Domain | Authority |
|---|---|
@@ -100,7 +98,7 @@ Use this table before reasoning about implementation details. Most failed runs s
| Existing PPTX, preserve page count/order/wording 1:1, improve layout | `beautify-pptx` | regenerate through SVG; content and pagination are locked |
| Finished PPTX, keep content/layout stable, add notes/audio/timings/transitions | `native-enhance-pptx` | direct OOXML patch; no design regeneration |
| User wants a reusable template package from a PPTX or design reference | `create-template` or `create-brand` | outputs a directory that later triggers Step 3 |
-| User supplies an explicit `templates/.../<id>/` directory with `kind: brand/layout/deck` | main SVG pipeline Step 3 | template segment ownership and fusion rules apply |
+| User supplies an explicit `templates/.../<id>/` directory with `kind: brand/layout/deck` | main SVG pipeline Step 3 | deck/layout SVGs must satisfy the current structured contract; legacy packages first run `restore-pptx-structure` |
| User asks to tune object-level animation order/effect/timing | `customize-animations` | optional export policy via `animations.json` |
| User asks to preview, select, annotate, or re-export browser edits | `live-preview` | browser workflow; annotations apply only at defined handoff points |
@@ -454,21 +452,25 @@ These direct routes share some analysis primitives with the main pipeline, espec
**Why there is only one PPTX export route.** Native export reads `svg_output/` and translates supported SVG elements into DrawingML shapes. 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 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 baseline has explicit and compatibility routes instead of visual inference.** `svg_to_pptx.py` starts from the actual blank slide-layout relationship in the base package and defaults to `--pptx-structure baseline`. Free-design and brand-only projects initially omit `pptx_layouts`, so the visual pass is not constrained by precomputed compositions and the compatibility route keeps actual content Slide-local. When the user explicitly selects completed pages, `distill-layouts` atomically writes one mapping row for every page: selected pages use `distilled` Layouts and unselected pages share an empty `utility` Layout. The exporter deterministically compiles those declarations but never selects or clusters pages itself. Existing unmapped projects keep the compatibility pass: strict-majority background/chrome promotion plus coarse `data-pptx-page-role` families, with filename/id fallbacks.
+**Why structure is authored before visual generation.** Master and Layout are not post-processing discoveries. Strategist writes the Master roster and complete page mapping before SVG generation; Executor writes those identities, fixed atoms, and slots while composing each page. This keeps free design unconstrained at the visual level while making PowerPoint ownership explicit. Export only compiles declared structure. Legacy or unmapped projects enter `restore-pptx-structure`; they never trigger an exporter heuristic.
+
+**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.
+
+**Why Layout slots use groups.** A reusable slot is a top-level `<g>` with semantic type and design-zone bounds. A normal slot contains exactly one compatible carrier; export unwraps it into the real Slide placeholder binding. A genuinely composite `object` region uses an explicit proxy downgrade: the visible group stays ordinary and a hidden transparent placeholder supplies PowerPoint binding. Layouts may also have zero slots, so fixed visual pages do not need fake full-page placeholders.
-**Why reusable layouts require explicit SVG metadata.** Post-design distilled baseline and template routes use the same compiler. Final mapped SVGs declare a Layout key/name/kind at the root, mark only direct children as Master/Layout layers, and attach typed placeholder semantics to Slide-local prototypes. Export validates that shared Master and same-key Layout declarations are structurally identical, then emits real Layout parts and `p:ph` references. In every new distilled contract, including template-based output, the Layout owns the reusable placeholder. Atomic carriers keep matching Slide bindings for rendering fidelity; a final distilled composite object region remains an ordinary visible group and receives one hidden transparent binding proxy. Template mode additionally compares the output with `page_layouts`: strict requires matching key/name, Master/Layout ids/topology/geometry, and placeholder bounds; adaptive requires matching Master structure, and an evolved Layout receives a new key/name rather than mutating an existing identity. Non-mirror paint and typography remain project-controlled; mirror preserves Master and Slide-local non-text visuals plus referenced asset identity, allowing only visible text replacement unless adaptive assigns a genuinely evolved Layout identity. Mirror compares referenced definitions and applicable embedded-style rules through each layer's dependency closure, so private resources of a new adaptive Layout do not falsely count as Slide-local drift. Package read-back verifies exact Slide/Layout/Master shape rosters and order, exact background ownership/payload, physical part and content-type rosters, carrier/proxy roles, placeholder identities, and default bounds. Legacy immediate-template contracts retain Slide binding.
+**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 reusable bounds are design zones, not measured text boxes.** Every distilled placeholder carries explicit `data-pptx-placeholder-bounds` for the Layout's default semantic region. The value comes 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 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 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 reused visual identities except for the intentional flattening of source Master/Layout groups.
-**Why explicit-Layout text defaults are split between Master and Layout.** Structured baseline and template export write the locked `typography.title` size to every Master `p:titleStyle` level and the locked `typography.body` size to every `p:bodyStyle` / `p:otherStyle` level. Each generated Layout text placeholder additionally copies its prototype's first direct run size into `a:lstStyle/a:lvl1pPr/a:defRPr@sz` while retaining the prompt's direct size. This preserves Layout-specific scale when level-one placeholder text is inserted or reset; direct runs on generated Slides remain unchanged. Missing title/body locks fail explicit Layout export, while unmapped baseline, `preserve`, and `flat` retain their previous behavior.
+**Why explicit-Layout text defaults are split between Master and Layout.** Structured export writes locked title/body sizes into Master text defaults. Each generated Layout text slot also 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 output is read back before publication.** Metadata preflight can prove the authoring contract but cannot prove that package serialization preserved every relationship and registration. Structured baseline and template mode therefore reopen the temporary PPTX and validate the Slide → Layout → Master graph, exact physical part/content-type rosters, Layout identity, placeholder type/effective index, reusable frame, prompt/level-one sizes, and the exact top-level shape roster/order captured before packaging. Background validation compares the zero-or-one payload of every Slide/Layout/Master part against the pre-promotion expectation, including the untouched base Master background when no authored replacement exists. Distilled output additionally proves that atomic carriers own their expected binding while composite carriers remain ordinary and use hidden transparent proxies. Only a package that passes is moved to the requested output; unmapped baseline, `preserve`, and `flat` skip this gate.
+**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 reusable templates rebuild explicit SVG structure.** `pptx_template_import.py` emits layered Master/Layout/Slide references plus source structure facts. `create-template` uses them to rebuild one clean Master and semantic Layouts as complete annotated SVG pages, including at least one page for every retained source Layout (mirror records unused Layouts instead of changing its source-slide count). A source-to-output consolidation table in the template `design_spec.md` makes every retained, merged, or unused Layout auditable. The workflow does not package the original PPTX. Downstream `page_layouts` selects these complete prototypes; only after final SVG construction does strict restore the structural contract or adaptive distill a new Layout under matching Master structure. Legacy `preserve` remains readable for existing projects only. Raw PPTX plus one-off generated content still routes to `template-fill-pptx`.
+**Why reusable templates reconstruct the source topology.** `pptx_template_import.py` emits layered Master/Layout/Slide references plus native structure facts. `create-template` reconstructs every source Master and Layout, including unused Layouts, as complete annotated SVG prototypes. Source Master/Layout groups are flattened into atoms; parent relationships, picker names, placeholder identities, and bounds remain auditable in the template specification. The original PPTX remains an analysis input, not a packaged export dependency.
-**Why project-scoped thin templates are an output policy, not another structure mode.** `create-template` keeps `library` as its default indexed output and may instead write the same validated contract directly into an initialized project's `templates/` root. Project bitmaps go to `images/`, extracted icons keep a package copy plus a runtime copy, and no global index is touched. Main-pipeline Step 3 detects that the source and target template roots are identical and consumes the bundle in place. Both scopes use the same template state machine; a bounds-missing strict legacy prototype takes the immediate compatibility branch, while distillation-capable strict/adaptive projects defer output structure. The exporter has no project-local branch.
+**Why project-scoped thin templates are an output policy, not another structure mode.** `create-template` keeps `library` as its default indexed output and may instead write the same validated contract directly into an initialized project's `templates/` root. Project bitmaps go to `images/`, extracted icons keep a package copy plus a runtime copy, and no global index is touched. Both scopes use the same `structured` contract.
-**Why each template SVG stays complete while still compiling to a Layout.** A template SVG is a complete standalone prototype, so it repeats inherited Master/Layout visuals together with selectable Slide content. During generation, `page_layouts` names that input and the output page remains visually complete; `pptx_layouts` is intentionally absent. Post-design distillation then writes the output mapping for every page. Strict copies prototype structure/bounds; adaptive may finalize a new Layout under matching Master structure. Export removes repeated inherited copies and emits real Master/Layout parts, leaving actual content on the Slide.
+**Why each template SVG stays complete while still compiling to native structure.** A template SVG repeats the inherited Master/Layout visuals together with sample Slide content so it opens as a complete standalone page. During generation, `page_layouts` selects that prototype and the output SVG remains complete. Export removes repeated inherited atoms, emits real Master/Layout parts, and leaves actual slot carriers and Slide-local content on the Slide.
**Why native-object reconstruction uses markers, not automatic object replacement.** The standalone `pptx_to_svg.py` importer emits visible SVG fallback plus `data-pptx-native` metadata only for validated table/chart subsets. Table import covers exact physical row/grid topology, canonical rectangular merges with empty slaves, safe solid/no-fill per-side borders, plain multi-paragraph cells, and a closed run-rich paragraph form. A rich paragraph contains non-empty `runs`; every run requires `text` and may use only `bold`, `italic`, `underline`, `strike`, `color`, `font_size`, one `font_family`, `lang`, and `alt_lang`. Unknown source presentation-only run XML normalizes into that schema, while relationship-bearing text, extensions, line breaks, fields, tabs, bullets, malformed text topology, noncanonical merges, unsafe borders, and non-solid fills remain fallback-only. The normalized fallback for table style `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}` resolves `wholeTbl`, `firstRow`, horizontal banding, theme colors/fonts, and direct overrides; this is not a full built-in/custom style registry.
diff --git a/docs/templates-architecture.md b/docs/templates-architecture.md
index 0916d405..75404c2d 100644
--- a/docs/templates-architecture.md
+++ b/docs/templates-architecture.md
@@ -14,7 +14,7 @@
| **Layout** | `templates/layouts/<id>/` | Structure segment only: canvas / page structure / page types / SVG roster | No brand identity (no logo, no locked brand color) | `workflows/create-template.md` (layout branch) |
| **Deck** | `templates/decks/<id>/` | All segments: identity + structure + middle (template overview) | — | `workflows/create-template.md` (deck branch, default) |
-Every Layout/Deck SVG is a complete preview with explicit `data-pptx-layout`, Master/Layout layers, and semantic placeholders. These specialized markers are authoritative; minimal `data-pptx-role` hints are added only for structural page-frame behavior they cannot express, and ordinary content is not duplicated into a metadata taxonomy. PPTX-import artifacts are analysis inputs only and are not packaged into new templates. The template guides authoring of a complete generated page SVG; export never reaches back into the template to overlay visible content missing from that generated SVG. Strict use keeps the selected Layout contract; adaptive use may create a new Layout under the same Master. Both export through `pptx_structure.mode: template`; legacy `preserve` remains compatibility-only.
+Every newly created or restored Layout/Deck SVG is a complete preview with root Master/Layout key and picker names, direct atomic Master/Layout elements, and top-level semantic slot groups. A normal slot has positive design-zone bounds and exactly one compatible carrier; composite `object` regions use explicit proxy binding, and zero-slot Layouts are valid. These specialized markers are authoritative; minimal `data-pptx-role` hints are added only for structural page-frame behavior they cannot express. PPTX-import artifacts are analysis inputs only and are not packaged into new templates. Strict keeps the selected Layout contract; adaptive retains the Master and may create a new Layout identity while authoring. Both export through `pptx_structure.mode: structured`. Legacy packages first run `restore-pptx-structure`.
The three are **parallel reference bundles**. In library scope, the physical directory and the frontmatter `kind` field correspond one-to-one:
@@ -28,14 +28,14 @@ kind: brand
# templates/layouts/academic_defense/design_spec.md
---
kind: layout
-native_structure_mode: template
+native_structure_mode: structured
...
---
# templates/decks/招商银行/design_spec.md
---
kind: deck
-native_structure_mode: template
+native_structure_mode: structured
...
---
```
@@ -109,7 +109,7 @@ primary_color: "<HEX>"
---
layout_id: <slug>
kind: layout
-native_structure_mode: template
+native_structure_mode: structured
summary: <one-line use cases>
canvas_format: <ppt169 | ppt43 | a4 | ...>
page_count: <N>
@@ -137,7 +137,7 @@ page_types: [<cover, toc, chapter, content, ending, ...>]
---
deck_id: <slug>
kind: deck
-native_structure_mode: template
+native_structure_mode: structured
summary: <one-line use cases>
canvas_format: <ppt169 | ...>
page_count: <N>
@@ -281,7 +281,7 @@ This lets both AI and humans trace which segment came from where.
## 5. Relationship with SKILL.md Step 3
-**Trigger rule stays path-based** — an explicit directory path is still required (see [[feedback-template-explicit-path-only]]), and bare names never trigger. The only narrow handoff exception is a project-scoped `create-template` run in the current conversation: after validation, it may pass its exact `<project>/templates/` output directly into Step 3. The `kind` field decides **how AI handles the path after triggering**:
+**Trigger rule stays path-based** — an explicit directory path is still required (see [[feedback-template-explicit-path-only]]), and bare names never trigger. Before copying a Layout/Deck package, Step 3 validates the current structured contract; an old `native_structure_mode: template`, missing Master identity, direct atomic placeholder, or distillation-era package first runs `restore-pptx-structure`. The only narrow handoff exception is a project-scoped `create-template` run in the current conversation: after validation, it may pass its exact `<project>/templates/` output directly into Step 3. The `kind` field decides **how AI handles the path after triggering**:
| User path's `kind` | Step 3 action (per-kind branch) |
|---|---|
@@ -315,4 +315,4 @@ In library scope, the frontmatter `kind` field determines whether the file lands
- **No field-level override syntax in the fusion layer** — field-level adjustment uses the existing Strategist confirmation stage path
- **No batch conflict resolution for three or more of the same kind** — ask the user to narrow it down in chat first
- **No bilingual name mapping table** — templates are named in their brand / scenario's native language (Chinese templates use Chinese names; English templates use snake_case); no forced unification
-- **No new structure mode or output CLI flag** — output scope is a `create-template` brief decision; both layout/deck scopes still declare `native_structure_mode: template`
+- **No output-scope structure fork or CLI flag** — output scope is a `create-template` brief decision; both layout/deck scopes declare `native_structure_mode: structured`
diff --git a/docs/templates-guide.md b/docs/templates-guide.md
index f970b058..1e6310ef 100644
--- a/docs/templates-guide.md
+++ b/docs/templates-guide.md
@@ -1,6 +1,6 @@
# Templates Guide: Use, Derive, and Boundaries
-A PPT Master "template" is a **structure + style** preset bundle: complete standalone SVG pages whose metadata explicitly identifies Master, Layout, Slide, and placeholders, plus `design_spec.md` and matching assets. Export deterministically reconstructs native PowerPoint structure from those SVGs.
+A PPT Master "template" is a **structure + style** preset bundle: complete standalone SVG pages whose metadata explicitly identifies one Master and Layout, atomic fixed-layer objects, and grouped content slots, plus `design_spec.md` and matching assets. Export deterministically reconstructs native PowerPoint structure from those SVGs.
This guide answers three questions:
@@ -24,7 +24,9 @@ Send a path to a template directory in your initial message. Anywhere in the sen
> "用这个模板做汇报:`projects/last_deck/templates/`" ✅
> "做一份产品介绍,模板用 `/Users/me/Desktop/our_brand_v3/`" ✅
-The AI installs that directory's SVGs, `design_spec.md`, and assets into your project, then proceeds to the Strategist phase. The path may point to the built-in library under `skills/ppt-master/templates/layouts/` or another self-contained template directory. When the path already is the current project's own `<project>/templates/` root, the workflow consumes it in place instead of copying it onto itself. A project-scoped create-template run may hand this exact validated path directly to Step 3 in the same conversation; this is the only exception to the initial-message rule. Do not use a different project's `templates/` root as an external package: its `../images/` and runtime icon references are owner-local. Promote that design through library scope first.
+The AI first validates that directory's structured SVG contract, then installs its SVGs, `design_spec.md`, and assets into your project and proceeds to Strategist. The path may point to the built-in library under `skills/ppt-master/templates/layouts/` or another self-contained template directory. When the path already is the current project's own `<project>/templates/` root, the workflow consumes it in place instead of copying it onto itself. A project-scoped create-template run may hand this exact validated path directly to Step 3 in the same conversation; this is the only exception to the initial-message rule. Do not use a different project's `templates/` root as an external package: its `../images/` and runtime icon references are owner-local. Promote that design through library scope first.
+
+> **Legacy package preflight:** existing built-in or external SVG packages may still use the former atomic-placeholder/unmapped contract. Before first use, run [`restore-pptx-structure`](../skills/ppt-master/workflows/restore-pptx-structure.md). Step 3 does not copy a legacy package and defer migration.
### What does NOT trigger the template flow
@@ -48,7 +50,7 @@ Full data model + fusion / conflict-resolution rules: [`docs/zh/templates-archit
### Free design vs template
-Free design is **not** "no style" — the AI designs a fresh visual system **for that specific deck** based on its content. A template **reuses an already-defined structure and style**. Both involve real design work; the difference is whether the style is improvised or preset.
+Free design is **not** "no structure" or "no style" — the AI plans a fresh Master/Layout system and visual language **for that specific deck** before drawing the SVG pages. A template reuses an already-defined structure and style. Both use the same structured output contract; the difference is where the structure originates.
> Rule of thumb: clear content direction + strong brand or scenario constraints (consulting reports, government briefings, defenses) → use a template. Essay-like content where atmosphere matters more (magazine, documentary narrative) → free design usually works better.
@@ -121,7 +123,7 @@ The workflow will then **mandatorily** confirm a template brief with you before
### Step 1 — Prepare reference material
-**Strongly recommended: hand over the original `.pptx` file.** The importer reads OOXML directly and extracts every Master, Layout, placeholder, theme, and reusable asset into layered analysis references. Template_Designer uses those facts to rebuild one clean Master plus semantic Layouts as complete, explicitly annotated SVG pages. The original PPTX remains analysis input and is not packaged into the new template.
+**Strongly recommended: hand over the original `.pptx` file.** The importer reads OOXML directly and extracts every Master, Layout, placeholder, theme, and reusable asset into layered analysis references. Template_Designer reconstructs the source Master roster, Layout parent graph, picker names, and placeholder identities as complete annotated SVG pages. Source Master/Layout groups are flattened object by object into direct atomic layer elements. The original PPTX remains analysis input and is not packaged into the new template.
You can also design from scratch from a brand guideline: provide a logo, primary color HEX, fonts, tone description, and a few mood references — the AI will design the page skeletons on the spot. This suits brands that don't yet have a finished PPT, only a VI manual.
@@ -143,7 +145,7 @@ The workflow does not silently infer values — before generation it lists these
| **Theme mode** | Light / dark / gradient / ... |
| **Canvas format** | Default `ppt169` (16:9); specify other formats up front |
| **Replication mode** | `standard` (default 5-page roster) / `fidelity` (one variant per visually distinct cluster) / `mirror` (literal visual copy of every source slide plus explicit layer ownership) |
-| **Native structure facts** | The brief reports source Master/Layout counts, placeholder identities, and multi-master status. Output is always rebuilt explicit SVG structure (`template`). |
+| **Native structure facts** | The brief reports source Master/Layout counts, parent relationships, placeholder identities, and multi-master status. Output uses the current `structured` SVG contract and preserves that topology. |
| **Visual fidelity** | (required for `standard` / `fidelity` when a reference exists) `literal` (reproduce original geometry / decoration / sprite crops as-is) or `adapted` (use reference for tone and structure but allow design evolution). Cover / chapter / ending are usually `literal`. **Not asked for `mirror`** — mirror is implicitly literal |
| **Keywords** | 3–5 tags for index lookup |
| Theme color / design notes / asset list | Optional — can be auto-extracted from the source |
@@ -161,7 +163,7 @@ This is the most easily confused decision when deriving a template.
| | **standard** | **fidelity** | **mirror** |
|---|---|---|---|
| Output pages | 5 (cover / chapter / TOC / content / ending) | one variant per visually distinct cluster — count driven by the source | one page per source slide (1:1) |
-| Abstraction | High — clean, reusable skeleton | Medium — clusters preserved with cleanup | **Zero** — verbatim copy |
+| Abstraction | High — clean, reusable skeleton | Medium — source variants retained with cleanup | Visual copy — source Master/Layout groups are still flattened into atoms |
| Authoring placeholders | Yes (`{{TITLE}}`, `{{CONTENT_AREA}}`, …) | Yes | Literal text may remain, but imported native content slots still carry semantic metadata |
| Best for | You want "tone + basic skeleton" to generate brand-new decks later | The source PPTX itself is a customized layout library and every variant matters | Someone else's polished deck is great as-is, you want every page available as a reference |
| Typical use | Building a base brand template | Replicating a 20-variant government briefing layout set | Reusing a 50-page McKinsey-style deck verbatim |
@@ -170,7 +172,7 @@ This is the most easily confused decision when deriving a template.
**About sprite sheets**: PPTX-exported assets are often a single large image referenced from multiple slides, each cropping a different region via nested `<svg viewBox=...>` wrappers. In `fidelity` and `mirror` modes this nesting must be preserved — you cannot flatten it to a bare `<image>`, or the crop is lost and the page misaligns. The workflow validates this automatically.
-**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 every `data-pptx-*` structure declaration.
+**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.
### Step 4 — Validation, registration, and discovery
@@ -185,8 +187,8 @@ Library registration makes the template **discoverable** — when someone asks "
When a deck/layout template is selected, the Strategist confirmation stage asks how it should be used:
-- **adaptive** — choose one template SVG per page; when no Layout fits, keep the same Master and create a new explicit Layout
-- **strict** — choose one template SVG per page and keep its Master/Layout/Placeholder contract unchanged
+- **adaptive** — choose one template SVG per page; keep its Master and assign a new explicit Layout key during authoring when fixed Layout atoms or slot topology/bounds must change
+- **strict** — choose one template SVG per page and keep its Master/Layout/slot contract unchanged
### What a derived template looks like
@@ -205,7 +207,7 @@ skills/ppt-master/templates/layouts/<your_template_id>/
└── bg_pattern.jpg
```
-`standard` and `fidelity` SVGs use a unified placeholder convention (`{{TITLE}}`, `{{CHAPTER_TITLE}}`, `{{PAGE_TITLE}}`, `{{CONTENT_AREA}}`, ...) that the Strategist phase fills with content.
+`standard` and `fidelity` SVGs use a unified authoring-placeholder vocabulary (`{{TITLE}}`, `{{CHAPTER_TITLE}}`, `{{PAGE_TITLE}}`, `{{CONTENT_AREA}}`, ...). Each native slot is a top-level `<g>` with semantic type and positive bounds; a normal slot contains exactly one carrier. Fixed Master/Layout visuals are direct root atoms and never layer `<g>` elements. A Layout may intentionally expose zero slots.
A `mirror` template emits one SVG per source slide, named by source order. It may keep literal example text instead of `{{...}}` markers, but imported native slots still carry semantic metadata:
@@ -258,7 +260,7 @@ Common misconceptions to avoid:
- **A template is not a "style skin".** It bundles structure (which blocks per page, how information is hierarchized) with style (colors, fonts, decoration). Trying to swap "skin" without structure tends to put the information architecture and the visuals at odds
- **A template does not make content decisions for you.** The Strategist still decides per-page which layout to use and whether to extend a variant. Templates offer candidates, not predetermined results
- **`fidelity` mode is not pixel-perfect copying.** Even with `literal` fidelity, the AI still strips noise and unnecessary repetition — geometry stays, redundancy goes
-- **`mirror` mode IS pixel-perfect copying — but it inherits the source's import limitations.** Charts, SmartArt, OLE objects, and EMF / WMF media that don't round-trip through `pptx_template_import.py` will fail the same way in mirror. The flat SVG is the source of truth; if it looks broken in `<workspace>/svg-flat/`, the mirror template will too
+- **`mirror` targets literal supported appearance, not byte-identical OOXML.** It inherits the source import limitations, and Master/Layout groups are normalized into atoms. Charts, SmartArt, OLE objects, and EMF / WMF media that do not round-trip through `pptx_template_import.py` fail the same way in mirror. The flat SVG is the visual source of truth
---
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index a981e92a..7366d385 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -41,8 +41,6 @@
↓
[视觉自检(可选,opt-in)] → visual-review 工作流(仅在用户明确请求时触发)
↓
-[可复用 Layout 提炼(baseline 需明确选页;template 为强制后置定稿)] → distill-layouts 工作流
- ↓
[后处理] → total_md_split.py(拆分讲稿)→ finalize_svg.py → svg_to_pptx.py
↓
输出:
@@ -63,7 +61,7 @@
凡是通过 SVG 创作或重新设计页面的工作流,`svg_output/` 都是完整的页面设计权威。最终幻灯片中应出现的文字、图片、形状、图示、图表 / 表格 fallback、背景和模板派生布局元素,都必须已经存在于对应页面 SVG 中,或被它明确引用。模板、`design_spec.md` 和 `spec_lock.md` 负责指导 SVG 创作;导出器不能把它们当成第二层画面来源,在导出阶段补入 SVG 缺失的页面内容。
-最小语义标记不会削弱这条闭包。现有 Layout、Layer、Placeholder 与 Native metadata 始终优先。Baseline / 自由设计页面在视觉创作期间保持 unmapped,可用根节点 `data-pptx-page-role` 做兼容路由。延后蒸馏的模板页在设计阶段携带 `page_layouts` 选中的完整原型,但不提前定稿 `pptx_layouts` 或根节点 kind。完整页面完成后,`distill-layouts` 才写入全页输出合同:baseline 提升用户选中的成品页并补 utility,template 则逐页执行 strict/adaptive 对照。`data-pptx-role` 只补充专用 metadata 尚未表达的少量页面框架、package 或动画行为。
+最小语义标记不会削弱这条闭包。每张新页面从第一版 SVG 起就声明 Master/Layout 身份。固定 Master/Layout 视觉是根节点直接原子元素;可复用内容槽位是顶层 group,带显式设计区域 bounds 和一个兼容 carrier;复合 `object` 区域走显式 proxy 降级,Layout 也允许零槽。`data-pptx-role` 只补充专用 metadata 尚未表达的少量页面框架、package 或动画行为。旧结构或 unmapped SVG 必须先运行 `restore-pptx-structure`,导出器不做结构推断。
| 领域 | 权威来源 |
|---|---|
@@ -101,7 +99,7 @@
| 现有 PPTX,页数 / 页序 / 措辞 1:1 保留,只改善排版 | `beautify-pptx` | 通过 SVG 重新生成;内容和分页锁定 |
| 已完成 PPTX,保持内容 / 布局稳定,只加讲稿、音频、计时、转场 | `native-enhance-pptx` | 直接 OOXML patch;不重新设计 |
| 用户想从 PPTX 或设计参考构建可复用模板包 | `create-template` 或 `create-brand` | 输出后续能触发 Step 3 的目录 |
-| 用户提供明确的 `templates/.../<id>/` 目录且声明 `kind: brand/layout/deck` | 主 SVG 流水线 Step 3 | 应用模板片段所有权和融合规则 |
+| 用户提供明确的 `templates/.../<id>/` 目录且声明 `kind: brand/layout/deck` | 主 SVG 流水线 Step 3 | Deck/Layout SVG 必须满足当前 structured 合同;旧包先运行 `restore-pptx-structure` |
| 用户要求调整对象级动画顺序 / 效果 / 计时 | `customize-animations` | 通过 `animations.json` 控制可选导出策略 |
| 用户要求预览、选择、注解或重导出浏览器编辑 | `live-preview` | 浏览器工作流;注解只在规定交接点应用 |
@@ -454,21 +452,25 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
**为什么只有项目转换器产出的 native PPTX。** Native 导出把 `svg_output/` 中受支持的 SVG 元素逐个翻译成 DrawingML 形状;这是唯一受支持的 SVG→PPTX 路线。`svg_final/` 仍由强制后处理生成,但只承担自包含视觉预览和 SVG 图片插入,不会再被封装成另一份 PPTX,也不为 PowerPoint 手工“转换为形状”提供兼容兜底。
-**为什么 baseline 分为显式版式与兼容回退,而不做视觉推断。** `svg_to_pptx.py` 默认使用 `--pptx-structure baseline`。自由设计与纯品牌项目起初省略 `pptx_layouts`,因此视觉设计不会被预先计算的构图限制,兼容路线会把实际内容保留在 Slide。用户明确从成品页中选出可复用页面后,`distill-layouts` 才会原子地为每页写入 mapping:选中页使用 `distilled` Layout,未选页共享空的 `utility` Layout。导出器只确定性编译这些声明,绝不自行选页或聚类。已有 unmapped 项目继续走兼容路径:严格多数背景/chrome 提升,加上粗粒度 `data-pptx-page-role` 家族与文件名/id fallback。
+**为什么结构必须在视觉生成前确定。** Master 和 Layout 不是后处理阶段才发现的结果。Strategist 在 SVG 生成前写出 Master roster 和完整页面 mapping;Executor 在构图时同步写入这些身份、固定原子元素和槽位。这样,自由设计在视觉层面仍然开放,PowerPoint 归属却从一开始就是显式合同。导出器只编译声明;旧项目或 unmapped 项目进入 `restore-pptx-structure`,不会触发导出期启发式推断。
+
+**为什么 Master/Layout 视觉必须原子化。** 一个 Master 或固定 Layout 对象必须是根节点的直接子元素。导入 PPTX 时,group 的 transform、opacity、style 和 z-order 会下推到各个原子对象。这个选择有意放弃来源 group 的整体编辑层级,换取简单、可比较、可确定重建的结构归属,避免嵌套结构歧义。
+
+**为什么 Layout 槽位使用 group。** 一个可复用槽位是顶层 `<g>`,携带语义类型和设计区域 bounds。普通槽位恰好包含一个兼容 carrier;导出时 carrier 被解包并绑定成真实 Slide placeholder。无法由单一 placeholder 表示的复合 `object` 区域走显式 proxy 降级:可见 group 保持普通 Slide 对象,隐藏透明 placeholder 负责 PowerPoint 绑定。Layout 也可以零槽,因此纯视觉页面无需制造假全页槽位。
-**为什么可复用版式必须依赖显式 SVG 元数据。** 成品后提炼的 baseline 与 template 复用同一套编译器。最终 mapped SVG 在根节点声明 Layout key/name/kind,只允许直接子元素标记 Master/Layout layer,并在 Slide-local 原型上附加占位符类型。导出器验证共享 Master 与同 key Layout 声明一致,再生成真实 Layout part 与 `p:ph`。所有新 distilled 合同(包括模板路线)都由 Layout 持有可复用 placeholder;原子 carrier 保留匹配的 Slide 绑定以维持渲染一致,最终 distilled 的复合对象区域则保持可见 group 为普通对象,并增加一个隐藏透明的绑定代理。Template 还会对照 `page_layouts`:strict 要求 key/name、Master/Layout 的 id/topology/geometry 和 placeholder bounds 一致;adaptive 要求 Master 结构一致,演化后的 Layout 必须使用新 key/name,不能偷换旧身份。非 mirror 的颜色与排版仍由项目控制;mirror 保留 Master、Slide-local 非文本视觉与引用资产身份,只有可见文本允许变化,除非 adaptive 确实建立了演化后的新 Layout 身份。Mirror 会按各层实际依赖闭包比较被引用的定义与适用的内嵌样式规则,因此新 adaptive Layout 的私有资源不会被误判为 Slide-local 漂移。包回读会验证 Slide/Layout/Master 的精确 shape roster 与顺序、背景 ownership 与完整 payload、物理 part 与 content-type roster、carrier/代理职责、占位符身份与默认 bounds。旧 immediate-template 合同继续保留 Slide 绑定行为。
+**为什么可复用 bounds 是设计区域,不是量出来的文本框。** bounds 来自安全区、分栏、面板内框或图片框,而不是字形宽度、行数或当前内容紧包围盒。当前 Slide 保留自己的 carrier 几何,因此只要语义构图相同,4:6、3:7、5:5 的实例都可复用同一 Layout。文本长度不会意外拆分或改变可复用合同。
-**为什么可复用 bounds 是设计区域,不是量出来的文本框。** 每个 distilled placeholder 都必须显式携带 `data-pptx-placeholder-bounds`,表示 Layout 的默认语义区域。它来自安全区、分栏、面板内框或图片框,而不是字形宽度、行数或当前内容的紧包围盒。当前 Slide 仍保留自己的实际几何,因此只要语义构图相同,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 保持复用视觉身份,但来源 Master/Layout group 仍会按合同原子化。
-**为什么显式版式把文字默认值分在 Master 与 Layout 两层。** Structured baseline 与 template 导出都会把锁定的 `typography.title` 字号写入 Master `p:titleStyle` 的全部层级,把锁定的 `typography.body` 字号写入 `p:bodyStyle` / `p:otherStyle` 的全部层级。每个生成的 Layout 文字占位符还会把原型首个直接 run 的字号写入 `a:lstStyle/a:lvl1pPr/a:defRPr@sz`,同时保留提示文字的直接字号。这样,一级占位符文字在插入或重置后仍继承版式特定的字号;生成 Slide 上的直接 run 保持不变。缺少 title/body 锁会让显式版式导出失败,unmapped baseline、`preserve`、`flat` 则维持原有行为。
+**为什么显式版式把文字默认值分在 Master 与 Layout 两层。** Structured 导出把锁定的 title/body 字号写入 Master 文本默认值;每个 Layout 文字槽位也把 carrier 首个 run 的字号写入一级默认值,同时保留提示文字的直接字号。这样,插入或重置 placeholder 时仍能继承 Layout 特定尺度,而生成 Slide 上的直接 run 不变。
-**为什么显式 Layout 导出要在发布前回读候选包。** 元数据预检可以证明作者合同成立,却不能证明 package 序列化完整保留了所有 relationship 与注册信息。因此 structured baseline 与 template 模式都会重新打开临时 PPTX,校验 Slide → Layout → Master 关系链、精确的物理 part/content-type roster、Layout 身份、占位符类型与有效索引、可复用边界、提示文字与一级默认字号,以及封包前捕获的顶层 shape roster/顺序。背景校验会把每个 Slide/Layout/Master part 的零或一个 payload 与提升前期望精确比较;没有作者 Master 背景时,基础 Master 背景也必须原样保留。Distilled 输出还会验证原子 carrier 持有预期绑定、复合 carrier 保持普通对象,并使用隐藏透明代理。只有通过读回校验的候选包才会移动到目标输出;unmapped baseline、`preserve`、`flat` 跳过该门禁。
+**为什么 structured 输出要在发布前回读。** 元数据预检不能证明 package 序列化保留了所有 relationship 与注册信息。导出器会重新打开临时 PPTX,校验 Presentation → Master → Layout → Slide 注册链、物理 part/content-type roster、选择器身份、固定对象顺序、placeholder 类型/有效索引/bounds、carrier 绑定、隐藏 proxy 与零槽 Layout,只有通过后才发布。
-**为什么可复用模板统一重建显式 SVG 结构。** `pptx_template_import.py` 输出分层的 Master/Layout/Slide 参考和源结构事实;`create-template` 据此重建一个干净 Master 与语义 Layout,并为每个保留的源 Layout 至少物化一张可独立预览的完整模板页;mirror 为保持源 Slide 数量,会记录未使用 Layout。模板 `design_spec.md` 中的源到输出合并表让保留、合并与未使用项都可审计。主管线用 `page_layouts` 选中完整原型;最终 SVG 完成后,strict 才恢复原型结构合同,adaptive 才在相同 Master 结构下蒸馏新 Layout。`preserve` 只为旧项目保留兼容读取。
+**为什么可复用模板要重建来源拓扑。** `pptx_template_import.py` 输出分层 Master/Layout/Slide 参考和 native 结构事实;`create-template` 重建每一个来源 Master 和 Layout,包括未使用 Layout,并生成完整注释 SVG 原型。来源 Master/Layout group 被原子化;父子关系、选择器名称、placeholder 身份和 bounds 在模板规格中保持可审计。原 PPTX 只是分析输入,不再成为打包依赖。
-**为什么项目本地薄模板只是输出政策,不是另一种结构模式。** `create-template` 仍以写入索引的 `library` 为默认,也可以把同一份已校验合同直接写到已初始化项目的 `templates/` 根目录。项目位图进入 `images/`,抽取图标同时保留 package 副本与运行时副本,且不修改任何全局索引。主管线 Step 3 发现模板源目录与目标根目录相同时原地消费。两种输出范围使用同一模板状态机:缺少 bounds 的 strict 旧原型走 immediate 兼容分支,具备蒸馏条件的 strict/adaptive 项目延后定稿输出结构。导出器没有项目本地分支。
+**为什么项目本地薄模板只是输出政策,不是另一种结构模式。** `create-template` 仍以写入索引的 `library` 为默认,也可把同一份已校验合同直接写入已初始化项目的 `templates/` 根目录。项目位图进入 `images/`,抽取图标保留 package 副本与运行时副本,且不修改全局索引。两种范围都使用同一 `structured` 合同。
-**为什么模板 SVG 保持完整却仍能编译成版式。** 每张模板 SVG 都是可独立预览的完整原型,因此会重复携带继承的 Master/Layout 视觉和可选择的 Slide 内容。生成阶段只有 `page_layouts` 指定输入原型,输出页面保持视觉完整,`pptx_layouts` 刻意缺席。成品后蒸馏再为每页写入输出 mapping:strict 复制原型结构与 bounds,adaptive 可在相同 Master 结构下定稿新 Layout。导出器移除重复继承层并生成真实 Master/Layout,实际内容仍留在 Slide。
+**为什么模板 SVG 保持完整却仍能编译成原生结构。** 模板 SVG 会重复携带继承的 Master/Layout 视觉和示例 Slide 内容,因此可独立打开。生成时由 `page_layouts` 选择该原型,输出 SVG 仍保持视觉闭包。导出器移除重复继承原子、生成真实 Master/Layout part,并把槽位 carrier 与 Slide-local 内容留在 Slide。
**为什么原生对象重建使用 marker,而不是自动替换对象。** 独立的 `pptx_to_svg.py` 导入器只为已验证的表格 / 图表子集输出可见 SVG fallback 与 `data-pptx-native` 元数据。表格导入覆盖精确的物理行列 topology、slave 为空的规范矩形 merge、安全的 solid/no-fill 逐边 border、纯文本多段落,以及封闭的 run 级富文本段落。富文本段落包含非空 `runs`;每个 run 必须有 `text`,并且只能使用 `bold`、`italic`、`underline`、`strike`、`color`、`font_size`、单一 `font_family`、`lang` 和 `alt_lang`。来源中未建模但只影响表现的 run XML 会归一化到该 schema;带 relationship 的文本、扩展节点、换行、字段、tab、项目符号、破损文本 topology、非规范 merge、不安全 border 与非纯色填充仍保持 fallback-only。表格样式 `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}` 的规范化 fallback 会解析 `wholeTbl`、`firstRow`、横向带状行、主题颜色 / 字体和直接格式覆盖;这不代表完整 built-in/custom style registry。
diff --git a/docs/zh/templates-architecture.md b/docs/zh/templates-architecture.md
index fa50381f..60b53869 100644
--- a/docs/zh/templates-architecture.md
+++ b/docs/zh/templates-architecture.md
@@ -14,7 +14,7 @@
| **Layout** | `templates/layouts/<id>/` | 仅结构段:canvas / page structure / page types / SVG roster | 不写品牌身份(无 logo、无品牌色硬约束) | `workflows/create-template.md`(layout 分支)|
| **Deck** | `templates/decks/<id>/` | 全段:身份段 + 结构段 + 中间段(template overview) | —— | `workflows/create-template.md`(deck 分支,默认)|
-Layout/Deck 的每张 SVG 都是完整预览,同时显式声明 `data-pptx-layout`、Master/Layout 层和语义 placeholder。这些专用标记具有最高优先级;最小 `data-pptx-role` 只补充它们无法表达的页面框架行为,普通内容不会被重复分类到 metadata 词表。PPTX 导入产生的 `native_structure.json` 与 `source_template.pptx` 只用于分析源结构,不进入新模板包。模板负责指导生成完整的页面 SVG;导出时不得再回读模板,向生成 SVG 叠加其中缺失的可见内容。下游 `strict` 保持所选 Layout 契约,`adaptive` 可在同一 Master 下创建新 Layout;两者都使用 `pptx_structure.mode: template`。旧 `preserve` 契约仅保留兼容读取。
+每张新建或已恢复的 Layout/Deck SVG 都是完整预览,并在根节点声明 Master/Layout key 与选择器名称;固定 Master/Layout 视觉是直接原子元素;语义槽位是顶层 group。普通槽位必须有正数设计区域 bounds 和恰好一个兼容 carrier;复合 `object` 区域走显式 proxy 绑定,零槽 Layout 也合法。这些专用标记具有最高优先级;最小 `data-pptx-role` 只补充它们无法表达的页面框架行为。PPTX 导入产物只用于分析,不进入新模板包。下游 `strict` 保持所选 Layout 契约,`adaptive` 保持 Master 并可在创作时建立新 Layout 身份;两者都使用 `pptx_structure.mode: structured`。旧包必须先运行 `restore-pptx-structure`。
三者是**三种并列的 reference bundle**。在全局库范围内,物理目录与 frontmatter `kind` 字段双向对齐:
@@ -30,14 +30,14 @@ kind: brand
# templates/layouts/academic_defense/design_spec.md
---
kind: layout
-native_structure_mode: template
+native_structure_mode: structured
...
---
# templates/decks/招商银行/design_spec.md
---
kind: deck
-native_structure_mode: template
+native_structure_mode: structured
...
---
```
@@ -111,7 +111,7 @@ primary_color: "<HEX>"
---
layout_id: <slug>
kind: layout
-native_structure_mode: template
+native_structure_mode: structured
summary: <一句话描述用途>
canvas_format: <ppt169 | ppt43 | a4 | ...>
page_count: <N>
@@ -139,7 +139,7 @@ page_types: [<cover, toc, chapter, content, ending, ...>]
---
deck_id: <slug>
kind: deck
-native_structure_mode: template
+native_structure_mode: structured
summary: <一句话描述用途>
canvas_format: <ppt169 | ...>
page_count: <N>
@@ -281,7 +281,7 @@ AI: 你给了两个 brand,检测到段级冲突:
## 五、与 SKILL.md Step 3 的关系
-**触发规则仍以路径为准**——仍需显式目录路径(见 [[feedback-template-explicit-path-only]]),裸名称绝不触发。唯一的窄例外是当前对话刚完成项目范围 `create-template`:验证通过后可把精确的 `<project>/templates/` 输出直接交给 Step 3。`kind` 字段决定**触发后 AI 怎么处理**:
+**触发规则仍以路径为准**——仍需显式目录路径(见 [[feedback-template-explicit-path-only]]),裸名称绝不触发。复制 Layout/Deck 包之前,Step 3 会验证当前 structured 合同;旧 `native_structure_mode: template`、缺 Master 身份、原子 placeholder 或蒸馏时代的包必须先运行 `restore-pptx-structure`。唯一的窄例外是当前对话刚完成项目范围 `create-template`:验证通过后可把精确的 `<project>/templates/` 输出直接交给 Step 3。`kind` 字段决定**触发后 AI 怎么处理**:
| 用户路径指向 | Step 3 行为(按 kind 分支)|
|---|---|
@@ -315,4 +315,4 @@ Deck 路径下用户已经拿到完整方案,策略师确认阶段收窄到"
- **不在 fusion 层支持字段级覆盖语法** —— 字段级微调走 策略师确认阶段这条已有路径
- **不为同类三份及以上设计批量冲突解决** —— 用户先在 chat 里收敛到两份
- **不引入双名映射表** —— 模板命名按其品牌/场景母语(中文模板用中文名,英文模板用 snake_case),不强制统一
-- **不新增结构模式或输出 CLI flag** —— 输出范围是 `create-template` 简报里的执行选择;两种范围的 Layout/Deck 都继续声明 `native_structure_mode: template`
+- **不为输出范围新增结构分支或 CLI flag** —— 输出范围是 `create-template` 简报里的执行选择;两种范围的 Layout/Deck 都声明 `native_structure_mode: structured`
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 26e12d42..1a39c1d6 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -11,7 +11,7 @@ description: >
> AI-driven multi-format SVG content generation system. Converts source documents into high-quality SVG pages through multi-role collaboration and exports to PPTX.
-**Core Pipeline**: `Source Document → Create Project → [Template] → Strategist → [Image_Generator] → Executor Live Preview → Quality Check → [Layout Distillation] → Post-processing → Export`
+**Core Pipeline**: `Source Document → Create Project → [Template] → Strategist Structured Plan → [Image_Generator] → Executor Live Preview → Quality Check → Post-processing → Export`
### SVG Page-Design Boundary
@@ -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 look up `pptx_structure.template_adherence` when present, the current page's `page_rhythm` (`anchor` / `dense` / `breathing`), `page_layouts` (the input template SVG), `page_charts`, and `pptx_layouts` only after it has been finalized. New baseline and template-distillation routes intentionally omit the output mapping during visual generation; [`distill-layouts`](workflows/distill-layouts.md) writes it only from complete SVG pages. Legacy immediate-template and preserve locks retain pre-authored mappings. 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 look up the complete `pptx_masters` / `pptx_layouts` structure, `pptx_structure.template_adherence` when present, the current page's `page_rhythm` (`anchor` / `dense` / `breathing`), `page_layouts` (the input template SVG), and `page_charts`. Master/Layout structure exists before drawing; export never infers it later. 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.
@@ -233,6 +233,8 @@ Do **not** reinterpret this boundary as 1:1 redesign or free SVG generation. Use
There is no slug matching, no name lookup, no fuzzy resolution. A name without a path does not trigger — the user must give a path the AI can `cd` into.
+**Structured-template preflight (before copy)**: For every deck/layout path, inspect all template SVG roots and slots. Every page must declare root Master/Layout key and picker names; Master/Layout visuals must be direct atoms rather than `<g>`; every slot must be a top-level `<g>` with positive bounds and exactly one compatible carrier, or an explicit composite `object` proxy. A zero-slot Layout is valid. If the package uses a legacy contract, run [`restore-pptx-structure`](workflows/restore-pptx-structure.md) first and return to Step 3 with the migrated directory. Do not copy a legacy package into the project and defer migration.
+
> Style descriptions ("麦肯锡风格" / "Keynote 风" / "极简风" / etc.) never trigger Step 3. They flow into the Strategist confirmation stage as a style brief (color / typography / tone in fields e–g).
> Bare names ("academic_defense", "招商银行", "anthropic") do NOT trigger Step 3 even if a matching directory exists in the library. The user must give a path. AI must not "helpfully" resolve a name to a path.
@@ -302,9 +304,9 @@ template root. Do not copy another project's `templates/` root as an external
bundle. For cross-project reuse, recreate/promote the design with
`create-template` library scope so the package is self-contained.
-Legacy template packages may ship `native_structure.json` + `source_template.pptx`; keep the pair together in `<project>/templates/` for backward-compatible `preserve` export. Current `create-template` output does not package this pair: it rebuilds complete, explicitly layered SVG templates instead. During fusion, never mix one legacy contract with another template's source package.
+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 them through Step 3. Run [`restore-pptx-structure`](workflows/restore-pptx-structure.md) on the package first, then return with the migrated directory path. This applies to the repository's existing built-in legacy SVG packages until their assets are explicitly migrated.
-The Strategist confirmation stage decides whether the selected template is used `strict` or `adaptive`. New projects map every page to one input SVG in `page_layouts` and normally use `pptx_structure.mode: template` plus `layout_strategy: distill`, deferring `pptx_layouts` until the complete SVG pages exist. Before locking, inspect every selected prototype placeholder for explicit bounds. A bounds-missing strict legacy template uses immediate compatibility instead: omit the strategy and prewrite the kindless mapping; adaptive may still distill new design-zone bounds. Deferred strict restores the referenced structural contract; adaptive may distill a new Layout while keeping the template Master ids/topology/geometry. Non-mirror paint and typography follow the project skin rules. Legacy `preserve` remains compatible.
+The Strategist confirmation stage decides whether the selected template is used `strict` or `adaptive`. New 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. Strict preserves the referenced 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.
#### Multi-path fusion
@@ -622,7 +624,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 the per-page `page_rhythm` / `page_layouts` / `page_charts` lookups and the route-specific `pptx_structure` contract. Read `pptx_layouts` only when already finalized. New baseline and deferred-template routes omit it during visual construction; legacy immediate-template and preserve routes retain it. 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 the complete `pptx_masters` / `pptx_layouts` structure and the per-page `page_rhythm` / `page_layouts` / `page_charts` lookups. 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).
@@ -631,9 +633,9 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon
Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Before drawing a literal stock shape, apply [`native-shape-authoring.md`](references/native-shape-authoring.md): use the stdout-only helper when one PowerPoint preset exactly matches, keep basic SVG primitives for rect/round-rect/ellipse, and keep free SVG for custom semantics. Never infer a preset from contour similarity.
-Deferred template pages MUST start from the complete `page_layouts` SVG, keep all inherited visible objects in `svg_output/`, preserve provisional root key/name and stable direct-child Master/Layout/placeholder ids, and omit `data-pptx-layout-kind` until post-design distillation. Strict keeps the prototype structure unchanged; adaptive keeps its Master ids/topology/geometry while the Layout may evolve. Non-mirror fill/stroke/effects/font sizes still follow `spec_lock`. Preserve and legacy immediate-template pages continue to implement their locked output mapping while generated.
+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/brand-only baseline pages MUST remain visually free at this stage: omit explicit Layout/layer/placeholder metadata and do not pre-compute rich Layouts from the page plan. They may use the canonical root `data-pptx-page-role` for compatibility routing. Without committing to any future Layout, keep a likely replaceable atomic title, standalone body frame, or picture in its own top-level one-carrier group when the design permits; keep accents and labels in sibling groups. If the user later selects finished pages for reuse, [`distill-layouts`](workflows/distill-layouts.md) adds the complete root contract, safe direct prototypes, design-zone bounds, and optional shared framing without changing the visible design.
+Free-design and brand-only pages are also structured from the first draft. Use the planned Master roster and page Layout mapping, author Master/Layout fixed visuals only as direct root atoms (never `<g>`), and author reusable content zones as top-level slot groups with positive bounds plus exactly one compatible carrier. A Layout may intentionally have zero slots. Do not add `data-pptx-layout-kind`, `distilled`, `utility`, or a full-page fake slot.
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).
@@ -667,20 +669,6 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>
> **Visual self-check (opt-in)?** If the user explicitly asked for a per-page visual re-pass on the SVGs ("跑一下视觉自检 / 视觉回看", "visual review", "check pages visually", etc.), run the standalone [`visual-review`](workflows/visual-review.md) workflow before Step 7. Do NOT run it by default and do NOT recommend it based on inferred model capability or deck size — trigger is user request only.
-> **Reusable Layout distillation**: Run
-> [`distill-layouts`](workflows/distill-layouts.md) after the full SVG quality
-> gate when either condition holds: the user selected finished baseline pages
-> for reuse, or the template lock carries `layout_strategy: distill` while
-> `pptx_layouts` is absent. A complete mapping is already finalized and only
-> needs normal validation unless the user explicitly requests re-distillation.
-> Baseline
-> promotes only the user's pages and maps the rest to one empty `utility`
-> Layout. Template distillation processes every `page_layouts` prototype:
-> strict restores the exact structural contract, adaptive keeps the Master structure and may
-> finalize an evolved Layout. Both derive explicit design-zone bounds and keep
-> current Slide geometry independent. If invoked after Step 7, rerun Step
-> 7.2–7.3 with the same export flags.
-
---
### Step 7: Post-processing & Export
@@ -718,9 +706,6 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
# Output (default-flow mode):
# exports/<project_name>_<timestamp>.pptx ← native pptx (canonical output, reads svg_output/)
# backup/<timestamp>/svg_output/ ← Executor SVG source backup (always written)
-# backup/<timestamp>/templates/{native_structure.json,source_template.pptx}
-# ← preserve mode only
-# backup/<timestamp>/spec_lock.md ← preserve mode only
# Add --native-objects to emit real editable chart/table objects instead of flattened shapes:
# exports/<project_name>_<timestamp>_native_charts.pptx ← native chart/table objects (data-pptx-native markers)
# Re-export with --recorded-narration audio (generate-audio workflow) embeds per-slide narration:
@@ -742,9 +727,8 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> snapshot in `backup/<timestamp>/` is always written so the project can be
> re-exported from frozen SVG sources without re-running the LLM. The SVG-rendered
> preview remains the mandatory `svg_final/` artifact from Step 7.2; it is not
-> packaged as a second PPTX. Preserve mode also backs up the paired native
-> structure/source files and `spec_lock.md` under the same timestamp. Use the
-> default source selection for release exports. `-s final` is diagnostic-only
+> packaged as a second PPTX. Use the default source selection for release
+> exports. `-s final` is diagnostic-only
> when comparing conversion behavior against the post-processed SVGs; it does
> not change `svg_output/` ownership or establish a supported release route.
@@ -755,156 +739,41 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> pages remain ordinary SVG pictures unless the user independently accepts the
> results of an unsupported Office conversion.
-> **PPTX structure mode** — native export first reads
-> `spec_lock.md` `pptx_structure.mode`, then falls back to `baseline` when the
-> section is absent. An explicit `--pptx-structure` CLI value overrides the
-> lock for diagnostics. Free-design and brand-only baseline projects initially
-> omit `pptx_layouts`: the visual pass stays unconstrained and all actual
-> content remains Slide-local. When the user explicitly selects completed pages
-> for reuse, [`distill-layouts`](workflows/distill-layouts.md) adds
-> `layout_strategy: distill` and an atomic all-page mapping. Selected pages use
-> `distilled` contracts; unselected pages share one empty `utility` Layout.
-> Every mapped SVG repeats its key/name/kind. Every distilled placeholder has
-> explicit design-zone bounds, while its current Slide frame may use different
-> geometry. Export then uses the same deterministic Layout compiler and
-> final-package read-back gate as template mode. `page_layouts` stays absent
-> because no input template was selected. Existing structured baseline projects
-> remain readable. If any baseline page declares a Layout, every page must
-> declare one and match the lock; partial or unlocked metadata fails export.
-> The exporter never selects, clusters, or visually infers reusable pages.
->
-> An unmapped baseline project — either a new free-design deck before
-> distillation or a legacy deck — keeps
-> the real slide master/layout relationship from the base deck and promotes the
-> strict-majority identical
-> native slide background into the slide master (every slide must carry an
-> explicit background; minority slides keep their own, which overrides the
-> master fill). Baseline may also promote a shared **leading** prefix of
-> top-level SVG elements whose explicit `data-pptx-role` marks page chrome
-> (`logo`, `footer`, `header`, `watermark`, `chrome`, `page-number`). Exact id
-> tokens remain a compatibility fallback only when the role marker is absent.
-> Promotion requires identical generated OOXML on a strict majority of slides
-> sharing the master, no slide-timing reference, and z-order safety; overlay
-> chrome stays slide-local. Minority slides (covers, section pages) keep every
-> shape slide-local and are bound to a generated `Cover` layout with
-> `showMasterSp="0"`, so promoted master chrome never appears on them. Image
-> relationships for promoted chrome are copied to the master. After the SVG
-> pages are complete, baseline assigns conservative semantic layout families:
-> root `data-pptx-page-role` values `cover` / `toc` / `section` / `ending` become
-> `Cover` / `Agenda` / `Section` / `Closing`, while `content` becomes `Content`.
-> Filename tokens remain a compatibility fallback for marker-free SVGs.
-> It also
-> preserves an existing safety `Cover` assignment made while hiding promoted
-> Master chrome. This unmapped route does not inspect visual similarity or infer
-> placeholders,
-> and all actual page content remains slide-local. When every slide in one
-> family carries the exact same explicit background, that background moves to
-> the family layout. The same family may also promote an identical leading
-> prefix of explicitly named chrome when every family member carries the same
-> generated OOXML, relationships are safe, no timing targets it, and z-order is
-> preserved. This is
-> an export-only package pass: SVG authoring, live preview, and model context are
-> unchanged. Baseline also prunes base-template slide layouts no generated slide
-> references, so the PowerPoint new-slide picker only offers layouts that belong
-> to the deck, and
-> converts `data-pptx-role="page-number"` chrome whose text exactly equals the
-> slide's display number into an auto-updating PowerPoint slide-number field
-> (legacy page-number id tokens remain a fallback; other numbering schemes keep
-> their literal text). For projects with a
-> `spec_lock.md` typography contract, baseline also installs `title_family` as
-> the PowerPoint theme major font and `body_family` / `font_family` as the minor
-> font; matching SVG runs use theme tokens so later theme edits can cascade
-> without changing initial rendering. Baseline/template export likewise maps
-> the locked background, text, primary/accent, and border roles into the
-> PowerPoint color scheme. Exact matching SVG/native-object colors use
-> context-safe theme tokens; unrelated local colors, inverse white/black, and
-> effects stay concrete, so the first rendering remains the SVG design while
-> later theme edits can cascade selectively. Add
-> `--pptx-structure flat` only for debugging/comparison when all generated
-> backgrounds and chrome must remain slide-local and fonts must stay concrete.
-
-> **Legacy preserved source-template export** — an existing template package
-> from a structured PPTX may ship `native_structure.json` plus
-> `source_template.pptx`. This pair records a reusable capability; it does not
-> select the downstream route by itself. Only a confirmed
-> `template_adherence: strict` deck may set `pptx_structure.mode: preserve`.
-> Add project-relative
-> `source_template` / `native_structure` rows, and map every page in
-> `pptx_layouts` to an exact imported layout key/name. Native export verifies the
-> source SHA-256 and package parts, creates the generated slides against the
-> original layouts (including multiple source masters), removes SVG-only preview
-> copies of inherited master/layout visuals, and binds slide content to the
-> original placeholder type/index. Preserve mode keeps the source layout picker
-> roster; it does not prune unused source layouts.
+> **PPTX structure mode** — release export requires
+> `spec_lock.md` `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
+> 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
+> design-zone bounds and exactly one compatible carrier. A composite region
+> uses only the explicit `object` + `proxy` fallback, and a Layout may
+> intentionally have zero slots.
>
-> Current template creation no longer emits this pair. `preserve` is retained
-> only so existing template packages and projects remain exportable; do not
-> select it for newly created templates.
-
-> **Explicit reusable Layout export** — deck/layout template routes set
-> `spec_lock.md` `pptx_structure.mode: template`. Distillation-capable template
-> projects and post-design free-layout reuse set `layout_strategy: distill`;
-> template planning owns `page_layouts` but defers `pptx_layouts` until every
-> complete SVG page exists. A bounds-missing strict legacy prototype instead
-> uses the kindless immediate compatibility contract. Every final mapped root
-> declares `data-pptx-layout`; distilled roots also declare
-> `data-pptx-layout-kind`. Direct children
-> explicitly declare master/layout layers, an optional Slide background, or
-> PowerPoint placeholders. This
-> mode builds named reusable layouts and placeholder mappings. Structured
-> baseline uses the same metadata and compiler without an input template. A
-> `utility` Layout is the narrow baseline-only exception for unselected pages;
-> its page-specific visible design remains entirely Slide-local.
-> A distilled placeholder always creates `p:ph` in the reusable Layout. Atomic
-> carriers keep matching Slide bindings for rendering fidelity. A final
-> distilled composite object region remains an ordinary visible group and gets
-> one hidden transparent binding proxy, preventing an empty inherited object
-> slot from painting over a page the user already approved visually. Legacy
-> immediate/pre-authored contracts keep their historical binding behavior.
-> Neither route infers from visual similarity. Static master/layout elements
-> must be
-> repeated consistently in PowerPoint paint order. Chart/table placeholders
-> additionally require `--native-objects`. The metadata contract and authoring
-> example live in
-> [`references/shared-standards.md`](references/shared-standards.md#explicit-pptx-master--layout--placeholder-metadata).
-> Raw PPTX templates still route to `template-fill-pptx`; `template` structure
-> mode is for complete explicitly annotated SVG authoring. Both `strict` and
-> `adaptive` stay on this deterministic route. `page_layouts` selects the input
-> prototype; the post-design checker requires strict key/name/Master/Layout/
-> placeholder structural equality, or adaptive Master-structure equality plus one internally
-> consistent evolved Layout/placeholder contract under a new key/name. Adaptive
-> may retain a prototype identity only while that Layout contract is unchanged.
-> Non-mirror skin remains project-controlled; mirror compares literal Master,
-> reused-Layout, and Slide-local non-text visuals plus referenced asset identity,
-> and permits only visible text replacement unless adaptive proves a genuinely
-> evolved Layout contract under a new identity.
-> The exporter never reads a
-> template to add missing visible objects.
-> Structured baseline and template export also install the locked
-> `typography.title` size into every
-> Master `titleStyle` level and the locked `typography.body` size into every
-> `bodyStyle` and `otherStyle` level. Each text-bearing Layout placeholder also
-> writes its prototype run size to `a:lstStyle/a:lvl1pPr/a:defRPr@sz`, so a
-> newly inserted or reset placeholder keeps that Layout's local size before it
-> falls back to the Master. Generated slide runs and Layout prompt runs keep
-> their direct sizes. Missing or invalid locked title/body sizes fail explicit
-> Layout export. Unmapped baseline, preserve, and flat modes do not apply either
-> text-default update.
-> Before publishing the temporary PPTX, structured baseline and template export
-> reopen the finished
-> package and verify `Presentation → Master ↔ Layout ← Slide` registration,
-> named custom Layout parts and content types, named Master/Layout static-object
-> rosters, explicit reusable backgrounds, distilled carrier/proxy roles,
-> collision-free placeholder identities, reusable default bounds, and prompt/level-one sizes. This read-back gate
-> also verifies atomic carrier bindings, ordinary composite carriers, hidden
-> transparent composite binding proxies, and that a `utility` Layout has no
-> background, shape, or placeholder. It does not
-> compare later same-Layout slides' local geometry
-> or direct text formatting.
-> In every mapped deck, `pptx_layouts` contains exactly one locked Layout row per
-> page; reuse a key for a shared contract instead of creating one key per content
-> instance. A free-design baseline deck omits the whole section until explicit
-> distillation and may use page-role compatibility families in the meantime.
+> Export creates the declared Masters and Layouts, promotes the represented
+> atoms, binds slot carriers, installs the locked theme/text defaults, and
+> reopens the candidate package to verify Presentation → Master → Layout →
+> Slide registration, picker names, static-object rosters, placeholder
+> type/index/bounds, carrier bindings, hidden proxies, and zero-slot Layouts.
+> It never selects pages, clusters visuals, promotes repeated chrome by
+> heuristic, or invents missing structure. Legacy `baseline`, `template`,
+> `preserve`, `layout_strategy`, `data-pptx-layout-kind`,
+> `distilled`/`utility`, direct atomic placeholders, or missing Master
+> identity must run
+> [`restore-pptx-structure`](workflows/restore-pptx-structure.md) before
+> export.
+
+
+> **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
+> 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
+> remains project-controlled, mirror preserves the reused visual identities,
+> and the exporter never reads a template to add visible objects missing from
+> `svg_output/`. Raw PPTX templates still route to `template-fill-pptx`;
+> reusable template creation goes through `create-template`.
> **Paragraph editability vs line fidelity** — by default, mergeable dy-stacked
> text collapses into one editable PowerPoint text frame. Evenly spaced authored
@@ -917,9 +786,9 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> frame. Add `--no-merge` only when the user explicitly asks for every
> dy-stacked line to remain its own text frame. The merge detector is
> conservative; mixed-layout text falls back to per-line frames. A multiline
-> `data-pptx-placeholder` must remain one native text frame; do not combine it
-> with `--no-merge`. Strict-line text stays Slide-local rather than claiming one
-> PowerPoint placeholder.
+> text carrier inside a slot must remain one native text frame; do not combine
+> it with `--no-merge`. Strict-line text stays Slide-local rather than claiming
+> one PowerPoint placeholder.
> **Native table/chart objects** — supported data charts and pure text-grid
> tables carry `data-pptx-native` markers by default (Executor transcribes
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.md
index b537dbc4..9d08f526 100644
--- a/skills/ppt-master/references/artifact-ownership.md
+++ b/skills/ppt-master/references/artifact-ownership.md
@@ -18,7 +18,7 @@ Global artifact ownership rules for PPT Master projects.
| `analysis/<stem>.slide_library.json` | Native PPTX structure facts | Text slots, geometry, native tables, native chart caches, SmartArt nodes/connections | Direct PPTX workflows use as native fill/structure contract |
| `analysis/image_analysis.csv` | Regenerated image fact view | Measured facts about the current `images/` folder | Re-run `analyze_images.py` before reading image facts after changes |
| `design_spec.md` | Human design narrative | Explains design intent, outline, rationale, and resource plan | Strategist writes; humans and later roles read for intent |
-| `spec_lock.md` | Execution contract | Literal colors, typography, icons, images, page rhythm, input template prototypes, charts, and any finalized native Layout mapping | Strategist writes the planning contract; Executor re-reads it before every page; only `distill-layouts` may add/finalize a deferred baseline or template `pptx_layouts` contract |
+| `spec_lock.md` | Execution contract | Literal colors, typography, icons, images, page rhythm, input template prototypes, charts, Master roster, and complete page-to-Master/Layout mapping | Strategist writes the initial structured contract; Executor re-reads it before every page and may add a new adaptive Layout identity only while authoring the page that first needs it; `restore-pptx-structure` owns legacy migration |
| `images/` | Runtime image pool | User, extracted, AI, web, formula, slice, EMF/WMF assets | Step 5 writes here; `analysis/image_analysis.csv` derives from current contents |
| `icons/` | Project icon inventory | Icons copied by `icon_sync.py` for this project | Executor uses locked project icons; exporter may fall back to global library only as documented |
| `templates/` | Project template reference | Step 3 imported specs, template SVGs, and non-image assets | Strategist/Executor read only when Step 3 is triggered |
@@ -42,8 +42,9 @@ 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 Layout authority | Before distillation, absence of `pptx_layouts` is intentional. After explicit user selection, `spec_lock.md` owns the complete page-to-Layout mapping and `svg_output/` owns the matching root/layer/placeholder/bounds metadata. Do not add a second manifest or infer Layouts during export. |
-| Template Layout authority | `page_layouts` owns the per-page input prototype. On a deferred template route, absence of `pptx_layouts` means pending visual construction; after distillation, `spec_lock.md` owns the complete output mapping and `svg_output/` owns the final structure. Templates validate provenance but never add missing visible objects during export. |
+| Free-design structure authority | Strategist plans the Master roster and complete page-to-Master/Layout mapping before SVG generation. `spec_lock.md` owns that mapping; `svg_output/` owns the matching root identities, atomic Master/Layout visuals, slot groups, bounds, and carriers. Export never infers structure. |
+| 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. |
+| Legacy structure migration | [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) owns conversion of old unmapped/distilled/preserve SVG projects and legacy template packages into the current structured contract. The exporter does not migrate or visually cluster them. |
| 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. |
| Page-design closure | On SVG-authoring routes, every visible exported-slide object exists in the corresponding page SVG or an explicitly referenced visual asset. |
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 3acf8cb2..3960bf4e 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -4,7 +4,7 @@
**Hard rule — complete page SVG**: Every visible object intended for the exported slide MUST exist in the final page SVG or be explicitly referenced by it. Templates and `spec_lock.md` guide construction; they are not export-time overlays for missing visible content.
-**Hard rule — minimal semantics without semantic loss**: Any page with a locked `pptx_layouts` row declares `data-pptx-layout` and `data-pptx-layout-name` on the root and does not duplicate that identity with `data-pptx-page-role`. Free-design and brand-only baseline pages normally have no mapping while their visual composition is being authored; keep structure metadata absent until the user explicitly runs [`distill-layouts`](../workflows/distill-layouts.md). Add `data-pptx-role` only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by layer, placeholder, or native-object metadata; the marked element uses a stable unique `id`. Ordinary page content keeps normal SVG structure without duplicate semantic classification. See [`semantic-svg.md`](./semantic-svg.md).
+**Hard rule — structure from the first page draft**: Every new page reads its locked Master/Layout row and declares `data-pptx-master`, `data-pptx-master-name`, `data-pptx-layout`, and `data-pptx-layout-name` on the root. Do not add `data-pptx-layout-kind` or duplicate identity with `data-pptx-page-role`. Add `data-pptx-role` only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by layer, placeholder, or native-object metadata; the marked element uses a stable unique `id`. See [`semantic-svg.md`](./semantic-svg.md).
**Hard rule — supported PPTX route**: The only supported generated-PPTX path is `svg_output/` through the project SVG-to-DrawingML converter. Step 7.2 still generates `svg_final/` as a mandatory self-contained visual preview that may be inserted as an SVG picture. Do not treat PowerPoint's manual Convert-to-Shape operation as an authoring target or compatibility requirement.
@@ -21,7 +21,6 @@
| Source list | Read path |
|---|---|
| Chosen template's `design_spec.md` (read frontmatter to detect `replication_mode`) | `templates/design_spec.md` |
-| Legacy preserve-mode native layout/placeholder contract, when present | `templates/native_structure.json` |
| Every distinct `<basename>` in `spec_lock.md page_layouts` | `templates/<basename>.svg` |
| Every distinct chart name in `spec_lock.md page_charts` | `templates/charts/<chart_name>.svg` |
| Chart types in `design_spec.md §VII` not covered above | `templates/charts/<chart_name>.svg` |
@@ -36,17 +35,16 @@
> Note: batched prefix reads stay in the cached prompt prefix; per-page `spec_lock.md` re-reads append below and benefit from that cache. Scattered on-demand reads of layout/chart SVGs would invalidate downstream cache and sit in the compression-vulnerable mid-context region.
-Resolve the per-page template SVG via `spec_lock.md page_layouts` (authoritative). The legacy page-type table below is a **last-resort fallback** for legacy decks where `page_layouts` is missing.
+Resolve the per-page template SVG via `spec_lock.md page_layouts` (authoritative). There is no filename/page-type fallback.
**Resolution order (per page):**
1. **Mirror-mode template** (template's `design_spec.md` frontmatter has `replication_mode: mirror`) → see §1.1 below. The page is consumed as a **visual reference**, not as a placeholder shell.
2. `spec_lock.md page_layouts` has `P<NN>: <basename>` for this page → inherit the structure of `templates/<basename>.svg` (already in context from §1.0).
-3. `pptx_structure.mode: template` but this page has no `page_layouts` entry → stop; the template contract is incomplete. Adaptive mode must still select a reference SVG.
-4. `page_layouts` section absent in a legacy project and `templates/` exists → fall back to the page-type table below, matching by SVG filename keyword. Read the matched file at first use if §1.0 did not cover it.
-5. No deck/layout template at all → free design.
+3. `template_adherence` is present but this page has no `page_layouts` entry → stop; the template contract is incomplete. Adaptive mode must still select a reference SVG.
+4. No deck/layout template at all → free design using the complete `pptx_masters` / `pptx_layouts` contract already planned in `spec_lock.md`.
-> Note: `page_layouts` disambiguates the multiple content variants modern templates ship (e.g., `graduation_defense` has 8); the legacy table cannot.
+> Note: `page_layouts` disambiguates the multiple content variants a template may ship; missing mappings are contract errors.
**Templates supply structure, not skin (non-mirror)**: a chart or layout template's gradients, drop-shadows, palette, **and font sizes** are placeholder. Inherit its geometry, label / legend placement, and series-encoding logic; re-skin every fill / stroke to the deck's `visual_style` + `spec_lock.colors` — flat styles strip the gradients and shadows, gradient / glass styles repaint their own. Forbidden — shipping a template's default `<linearGradient>` / `cardShadow` / Tailwind fills unchanged. Mirror templates are the exception: §1.1 preserves their visuals verbatim.
@@ -78,15 +76,7 @@ When the project's chosen template is a `mirror` template (`design_spec.md` fron
**Mirror + chart pages**: chart structures inside a mirror SVG are already drawn (axis, series, labels). Treat them as visual references — replace the data labels and series text content to match the project's chart spec, but do not redraw the chart from a `templates/charts/<name>.svg` baseline. A mirror template's `page_charts` entries are normally absent for this reason.
-**Legacy fallback table** (used only when `page_layouts` is absent):
-
-| Page Type | Corresponding Template | Adherence Rules |
-|-----------|----------------------|-----------------|
-| Cover | `01_cover.svg` | Inherit background, decorative elements, layout structure; replace placeholder content |
-| Chapter | `02_chapter.svg` | Inherit numbering style, title position, decorative elements |
-| Content | `03_content.svg` | Inherit header/footer styles; **content area may be freely laid out** |
-| Ending | `04_ending.svg` | Inherit background, thank-you message position, contact info layout |
-| TOC | `02_toc.svg` | **Optional**: Inherit TOC title, list styles |
+**Legacy template boundary**: A template with missing root Master identity, direct atomic placeholders, `data-pptx-layout-kind`, unmapped `baseline`, `preserve`, or `layout_strategy: distill` is not a fallback input. Stop and run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before generation.
### Page-Template Mapping Declaration (Required Output)
@@ -102,44 +92,29 @@ Before generating each page, output which template is used:
### 1.2 PowerPoint Master / Layout Mapping
-`page_layouts` selects the input SVG prototype and exists only for a deck/layout template route. `pptx_layouts` declares the native PowerPoint Layout produced at export. New baseline and template-distillation routes write the output mapping only after complete SVG pages exist. Legacy immediate-template and preserve routes retain their pre-authored mapping.
-
-`pptx_structure.template_adherence` records the confirmed template-use policy. Both `strict` and `adaptive` require one real `page_layouts` reference per page. With `layout_strategy: distill`, strict restores the referenced contract after design; adaptive may distill a new explicit Layout while retaining the template Master.
-
-| `pptx_structure.mode` | Executor behavior |
-|---|---|
-| `baseline` | Free design or brand-only route. While `pptx_layouts` is absent, author unconstrained Slide visuals and omit explicit Layout/layer/placeholder metadata. When [`distill-layouts`](../workflows/distill-layouts.md) writes a complete mapping, implement that final contract while remaining in baseline mode. |
-| Missing | Legacy compatibility. Use root page role; a new explicit Layout contract also writes `mode: baseline`. |
-| `template` | With `layout_strategy: distill`, generate a complete page from the selected `page_layouts` prototype, preserve its structural provenance, and defer the final `pptx_layouts` mapping until post-design distillation. A legacy template lock without the strategy implements its pre-authored mapping immediately. |
-| `preserve` | Legacy strict-only compatibility. Use the locked source layout key/name and retain marked preview layers for source-package reuse. |
-
-**Hard rule — every final mapped page references one Layout**: Whenever `pptx_layouts` contains `P<NN>: <layout_key> | <layout name>`, put both values on the root SVG. A distilled row also ends in `| <layout_kind>` and repeats it as `data-pptx-layout-kind`. Baseline accepts `distilled` or `utility`; template distillation accepts only `distilled`. Do not also add `data-pptx-page-role`. Distiller writes post-design identity; Executor must not predict a final adaptive key from the outline.
-
-**Template construction provenance**: While deferred template distillation is pending, copy the selected complete template SVG as the page's visual/structural prototype. Preserve its root key/name provisionally and retain stable direct-child ids plus Master/Layout/placeholder metadata as the design evolves. Do not add `data-pptx-layout-kind` or `pptx_layouts` yet. Strict keeps the structural contract unchanged; adaptive keeps the Master ids/topology/geometry and may evolve the Layout/placeholder contract. Apply the non-mirror skin rules in §1.0. Distillation validates and finalizes these declarations after all visible geometry is complete.
-
-**Free-design carrier hygiene**: While baseline is unmapped, do not add placeholder metadata or default bounds. When the composition permits, keep each likely replaceable atomic title, standalone body frame, or picture in its own top-level one-carrier group, with accents/labels in sibling groups. This satisfies normal grouping while allowing `distill-layouts` to lift the carrier later without dismantling a complex composition; it does not predeclare a Layout or constrain local geometry.
+`page_layouts` selects an input SVG prototype only on deck/layout template routes. `pptx_masters` and `pptx_layouts` always declare the output PowerPoint structure before the first page is drawn.
-**Hard rule — PowerPoint paint order**: Direct visual children appear in this order: Master background, Layout background, optional Slide background, shared Master shapes, same-key Layout shapes, then slide-local content/placeholders. Backgrounds are the special plane beneath all inherited shapes. Repeat the same Master contract on every page and the same Layout contract on every page sharing a key.
+**Hard rule — current mode only**: `pptx_structure.mode` is `structured`. Missing mode or legacy values (`baseline`, `template`, `preserve`, `flat`), `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).
-**Mandatory — per-page placeholder coverage**: On every template/pre-authored mapped page, mark each standard slot the page actually has. On a `distilled` page, mark only safe direct atomic carriers chosen from the completed design and give every placeholder explicit `data-pptx-placeholder-bounds`. A `utility` page intentionally has zero placeholders. Pages sharing one layout key ship the same placeholder ids/types/indices/default bounds; their Slide-local geometry may differ.
+**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.
-**Mandatory — reusable layer coverage**: Mark only genuinely stable deck-wide background/chrome as `master` and only reusable behind-content framing as `layout`. A placeholder-only distilled Layout is valid; do not manufacture a divider or panel merely to make the Layout non-empty. A `utility` Layout has neither Layout elements nor placeholders.
+**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.
-**Mandatory — Layout identity**: Different keys differ in reusable static framing or placeholder topology/default bounds. Their current text length, image crop, and Slide-local x/y/width/height never define identity. Identical reusable contracts should share one key; the quality checker reports duplicates.
+**Hard rule — PowerPoint paint order**: Direct children appear in this order: Master background atoms, Layout background atoms, optional Slide background, remaining Master atoms, remaining Layout atoms, then slot groups and Slide-local content groups. Backgrounds are the inheritance plane beneath all shapes.
-**Placeholder ownership**: Keep actual title/subtitle/body/picture/chart/table/object/media/date/footer/slide-number content on the Slide and add the matching `data-pptx-placeholder`. In any `distilled` contract, including a deferred template route, the generated Layout owns the reusable placeholder. Atomic carriers retain a matching Slide binding to preserve their approved rendering. A final distilled `object` may instead mark one direct composite `<g>` as a region proxy: that visible group remains ordinary and export creates a hidden transparent matching binding shape. Legacy immediate/pre-authored template contracts retain their historical binding behavior. Do not duplicate placeholder identity with `data-pptx-role`; in particular, `data-pptx-placeholder="slide-number"` already owns page-number field behavior. A reconstructed `title` normally omits `data-pptx-placeholder-idx`; preserve an explicit imported title index when present. Every indexed placeholder on one Layout uses a unique index. Chart/table placeholders require native markers and a later `--native-objects` export; object/media placeholders must each resolve to one top-level DrawingML object unless the final distilled object-region exception applies.
+**Mandatory — slot authoring**: A reusable content slot is one direct root `<g id>` carrying `data-pptx-placeholder` and positive `data-pptx-placeholder-bounds`. A normal slot contains exactly one compatible direct drawable child marked `data-pptx-placeholder-carrier="true"`. Export unwraps that child into the real Slide placeholder binding. Decorations do not belong in the slot; move reusable decoration to a root Layout atom and keep page-specific labels/captions in another slot or Slide-local group.
-**Atomic placeholder carrier exception**: A normal title/subtitle/body/date/footer/slide-number placeholder is one direct `<text>`; picture/media is one direct `<image>` or imported crop `<svg>`; object is one direct supported atomic object. These direct carriers are the narrow exception to the mandatory top-level `<g>` rule and do not count against the 3–8 content-group budget. The post-design distiller has one additional final-state exception: a direct completed `<g>` may be marked `object` with explicit design-zone bounds when the reusable slot is the whole composition region. It is a Layout-only proxy, not a promise to replace the group in-place, and is forbidden in a reusable template prototype, pending template page, utility page, or legacy immediate contract. The separately specified chart/table native-marker group remains its own specialized contract. Any other complex `<g>` composition stays Slide-local without placeholder metadata.
+**Mandatory — slot identity**: Preserve imported `data-pptx-placeholder-idx` values where available; otherwise omit the title index and assign unique indices only where repeated roles need disambiguation. Pages sharing one Layout key repeat the same slot ids/types/effective indices/default bounds/binding modes. Current text, crop, and Slide-local carrier geometry may differ.
-**Layout-content boundary**: Mark only genuinely reusable static framing as `data-pptx-layer="master|layout"`. Never promote concrete titles, body copy, metrics, chart marks, images, or complex page-specific groups into a Layout. The exporter never infers or clusters. [`distill-layouts`](../workflows/distill-layouts.md) finalizes user-selected baseline pages or every deferred template page before export.
+**Composite proxy fallback**: A genuinely composite region may use a direct `<g data-pptx-placeholder="object" data-pptx-placeholder-binding="proxy">` with positive bounds. Its visible group remains Slide-local and export creates one hidden transparent matching placeholder proxy. This downgrade is valid only for `object`; do not use it for an ordinary title, body, picture, chart, table, or media slot.
-**Adaptive Layout creation**: Start from the selected complete template SVG, keep every Master element and stable id identical, and evolve only the Layout/placeholder contract needed by the completed composition. Do not finalize the new key or default bounds until post-design distillation. An unchanged reusable contract must keep the prototype key/name; changing only its label is not a new Layout. Pages sharing the final key repeat the same static Layout elements and placeholder ids/types/default bounds.
+**Zero-slot Layout**: A Layout may have no slot groups. Covers, posters, and fixed visual pages still declare their named Master/Layout and fixed atoms. Do not manufacture a full-page `object` slot or empty `utility` identity.
-**Deferred template Layout creation**: Keep `page_layouts` as the immutable input-prototype mapping. After every complete page exists, run [`distill-layouts`](../workflows/distill-layouts.md). Strict restores the prototype key/name, Master/Layout ids/topology/geometry, and explicit placeholder bounds. Adaptive validates the Master structure and may finalize a new Layout from the completed design. Project skin remains governed by §1.0. Every template page becomes `distilled`; none becomes `utility`.
+**Layout identity**: Different keys differ in fixed Layout atoms or slot topology/default bounds/binding modes. Identical contracts should share one key. Current wording, imagery, crop, and Slide-local geometry never define identity.
-**Distilled baseline Layout creation**: Do not derive a native Layout key from §IX before free-design SVG generation. After the user selects completed pages, follow [`distill-layouts`](../workflows/distill-layouts.md): keep visible geometry unchanged, derive default placeholder bounds from design zones rather than text ink, map unselected pages to one empty utility Layout, and write the complete final lock atomically.
+**Template adherence**: Strict copies the prototype Master/Layout/slot contract exactly. Adaptive keeps the prototype Master and may change reusable Layout atoms or slots only under a new explicit Layout key/name. When the completed composition genuinely needs that change, update `spec_lock.md pptx_layouts` immediately while authoring the first affected page; later pages may reuse the new key only by repeating its exact contract. Changing only a label is not a new Layout.
-**Legacy preserve identity**: In `preserve` mode only, copy source `data-pptx-placeholder-idx` values and retain the source placeholder type/index pairing. Master/Layout preview elements keep `data-pptx-layer` plus `data-pptx-editable="false"`.
+**Layout-content boundary**: Mark only genuinely reusable fixed framing as a Master/Layout atom. Concrete titles, body copy, metrics, chart marks, images, and page-specific groups remain inside slot groups or ordinary Slide-local content groups. The exporter never infers or clusters structure.
**Background ownership**:
@@ -209,46 +184,48 @@ Before drawing each page, look up its entry in `page_layouts` to decide which ba
- Entry present (e.g., `P04: 03a_content_image_text`) → inherit the corresponding SVG already in context. The basename **must match** an actual file in the chosen template directory. If it does not, stop before drawing and report the invalid mapping; neither `strict` nor `adaptive` may fall back to free design inside a template deck.
- No entry for this page with `template_adherence: strict|adaptive` → stop before drawing and report the missing Strategist mapping. Adaptive mode still requires one selected complete template SVG; flexibility applies to the post-design output Layout, not to whether an input prototype exists.
-- Whole section absent with `pptx_structure.mode: template` → stop before drawing; the current template contract is incomplete.
-- Whole section absent only in a legacy project without the current template contract → see §1 fallback (legacy page-type matching).
+- Whole section absent while `template_adherence` is present → stop before drawing; the current template contract is incomplete.
-Do **not** invent a layout entry, and do **not** assume a template just because `templates/` exists. For either template-adherence value, a missing or invalid `page_layouts` row is an upstream contract error. Free design is a separate deck route, never a per-page fallback inside template mode.
+Do **not** invent a prototype entry, and do **not** assume a template just because `templates/` exists. For either template-adherence value, a missing or invalid `page_layouts` row is an upstream contract error. Free design is a separate deck route, never a per-page fallback.
**Per-page PowerPoint layout lookup — `pptx_layouts` section**:
-- `pptx_structure.mode: baseline` with `layout_strategy: distill` → post-design distillation is complete; a `P<NN>` row and matching root key/name/kind are mandatory. Do not read or create `page_layouts`.
-- `pptx_structure.mode: baseline` with `pptx_layouts` but no `layout_strategy` → existing structured-baseline compatibility. A key/name row and matching root metadata are mandatory; do not invent a kind segment.
-- `pptx_structure.mode: template` with `layout_strategy: distill` and no `pptx_layouts` → normal template visual construction. Use `page_layouts`, preserve provisional root key/name plus structural provenance, omit root kind, and do not export yet.
-- `pptx_structure.mode: template` with `layout_strategy: distill` and complete `pptx_layouts` → post-design distillation is complete; every row/root ends in `distilled` and must pass the selected-prototype comparison.
-- `pptx_structure.mode: template` without `layout_strategy`, or `preserve` → legacy immediate/pre-authored behavior; a `P<NN>` row is mandatory. Preserve uses the exact source key/name and placeholder indices.
-- `pptx_structure.mode: baseline` with the whole `pptx_layouts` section absent → normal free-design visual construction or undistilled compatibility export. Omit explicit PPTX Layout/layer/placeholder metadata; a root page role may guide conservative compatibility families without constraining composition.
-- A layout key may repeat across non-adjacent pages. Reuse is based on identical static/placeholder contracts, not page proximity or content wording.
+- `pptx_structure.mode` must equal `structured`; any other or missing value routes to legacy restoration.
+- Read the current page row as `<master_key> | <layout_key> | <layout name>` and resolve `master_key` in `pptx_masters`. Missing, malformed, or partial mappings stop before drawing.
+- Write matching root Master/Layout key and picker names. Do not write `data-pptx-layout-kind` or `data-pptx-page-role`.
+- On strict template use, the row and SVG contract match the selected prototype exactly.
+- On adaptive template use, retain the prototype Master. If the final composition changes fixed Layout atoms or slot topology/bounds, allocate a new key/name and update this row before completing the page.
+- A Layout key may repeat across non-adjacent pages only when its fixed atoms and slot contracts are identical.
-**Distilled-page scaffold — use only after `distill-layouts`.** It applies to selected baseline pages and every deferred template page. Legacy immediate-template, preserve, and kindless structured-baseline pages do not add `data-pptx-layout-kind` by imitation.
+**Structured-page scaffold**:
```xml
-<svg viewBox="…" data-pptx-layout="<key>" data-pptx-layout-name="<name>"
- data-pptx-layout-kind="distilled">
- <rect id="master-bg" data-pptx-layer="master" …/> <!-- deck background -->
- <g id="footer-chrome" data-pptx-layer="master" …>…</g> <!-- every-page chrome -->
- <g id="zone-framing" data-pptx-layer="layout" …>…</g> <!-- this key's framing -->
- <text id="page-title" data-pptx-placeholder="title"
- data-pptx-placeholder-bounds="60 36 1160 64" …>…</text>
- <text id="main-body" data-pptx-placeholder="body"
- data-pptx-placeholder-idx="1"
- data-pptx-placeholder-bounds="60 120 470 500" …>…</text>
- <image id="hero-image" data-pptx-placeholder="picture"
- data-pptx-placeholder-idx="2"
- data-pptx-placeholder-bounds="570 120 650 500" …/>
- <text id="page-number" data-pptx-placeholder="slide-number"
- data-pptx-placeholder-idx="3"
- data-pptx-placeholder-bounds="1170 670 50 24" …>…</text>
+<svg viewBox="…"
+ data-pptx-master="<master-key>" data-pptx-master-name="<master-name>"
+ data-pptx-layout="<layout-key>" data-pptx-layout-name="<layout-name>">
+ <rect id="master-bg" data-pptx-layer="master" …/> <!-- one atomic Master object -->
+ <text id="master-footer" data-pptx-layer="master" …>…</text> <!-- no Master/Layout g -->
+ <path id="layout-rule" data-pptx-layer="layout" …/> <!-- one atomic Layout object -->
+ <g id="title-slot" data-pptx-placeholder="title"
+ data-pptx-placeholder-bounds="60 36 1160 64">
+ <text id="title-carrier" data-pptx-placeholder-carrier="true" …>…</text>
+ </g>
+ <g id="body-slot" data-pptx-placeholder="body"
+ data-pptx-placeholder-idx="1"
+ data-pptx-placeholder-bounds="60 120 470 500">
+ <text id="body-carrier" data-pptx-placeholder-carrier="true" …>…</text>
+ </g>
+ <g id="picture-slot" data-pptx-placeholder="picture"
+ data-pptx-placeholder-idx="2"
+ data-pptx-placeholder-bounds="570 120 650 500">
+ <image id="picture-carrier" data-pptx-placeholder-carrier="true" …/>
+ </g>
<g id="content-block-1">…</g> <!-- 3–8 content groups -->
<g id="content-block-2">…</g>
</svg>
```
-Master/layout layers and placeholders are always direct children of the root and precede every content group; a placeholder written inside a content `<g>` fails export.
+Master/Layout atoms and slot groups are direct root children and precede ordinary content groups. Structural metadata nested inside an ordinary content group fails export.
**Per-page chart reference — `page_charts` section**:
@@ -263,7 +240,7 @@ Before drawing each page, look up its entry in `page_charts` to decide which cha
## 3. Execution Guidelines
- **Proximity**: group related elements with tight spacing; separate unrelated groups
-- **Element grouping (Mandatory)**: wrap every logical content unit — title, core-message line, each content block, card, list item, diagram, and footer chrome — in a top-level `<g id="...">` with a descriptive id. This is a hard requirement per [`shared-standards.md`](shared-standards.md) §4.3, not an optional convenience: aim for 3–8 content groups per slide (chrome excluded), because ungrouped top-level `<text>` / `<rect>` / `<path>` loses real PowerPoint groups and per-element animation anchors, and degrades select/move/edit. The narrow exception is one direct atomic carrier with `data-pptx-placeholder` under §1.2: it stays ungrouped so one native object can supply the Layout prototype or pre-authored Slide binding, and it is excluded from the group budget. Only the post-design distiller may additionally mark one completed top-level group as a final `distilled` object-region proxy; authoring-time template and legacy routes cannot imitate it. Authored native preset fragments (`preset_shape_svg.py`) already are one atomic `<g id>` each and count as one group; keep their labels in a sibling parent `<g>`.
+- **Element grouping (Mandatory)**: wrap every logical Slide-local content unit — title, core-message line, each content block, card, list item, and diagram — in a top-level `<g id="...">` with a descriptive id. Slot `<g>` elements are already semantic groups and are excluded from the 3–8 ordinary content-group budget. Direct Master/Layout atoms are the required exception to grouping and may never be wrapped in a layer `<g>`. Authored native preset fragments (`preset_shape_svg.py`) already are one atomic `<g id>` each and count as one ordinary content group; keep their labels in a sibling parent `<g>`.
- **Spec adherence**: follow color, layout, canvas format, and typography in the spec
- **Template structure**: if templates exist, inherit the visual framework
- **Main-agent ownership**: SVG generation must run in the main agent (not sub-agents) — pages share upstream context for cross-page visual continuity
diff --git a/skills/ppt-master/references/semantic-svg.md b/skills/ppt-master/references/semantic-svg.md
index 41ce36ec..6a60767e 100644
--- a/skills/ppt-master/references/semantic-svg.md
+++ b/skills/ppt-master/references/semantic-svg.md
@@ -1,204 +1,126 @@
# Minimal Semantic SVG Markers
-PPT Master uses a small set of rendering-neutral compiler hints only where
-ordinary SVG cannot reliably express a required PowerPoint packaging decision.
-These markers are not a second content model and do not abbreviate SVG.
+PPT Master uses rendering-neutral compiler hints only where ordinary SVG cannot express PowerPoint Master, Layout, placeholder, native-object, or package behavior.
## 1. Boundary
| Marker | Placement | Purpose |
|---|---|---|
-| `data-pptx-page-role` | Root `<svg>` | Select the compatibility Layout family for an unmapped baseline page, including free design before Layout distillation and legacy projects without `pptx_layouts`. |
-| `data-pptx-role` | A structural page-frame element | Identify the few objects whose package or animation behavior is not already expressed by specialized metadata. The element also needs a stable unique `id`. |
-
-The complete geometry, text, styles, grouping, and asset references remain in
-ordinary SVG. Removing these markers must not change browser rendering. Do not
-copy visible values into metadata, and do not mark ordinary titles, body text,
-cards, KPIs, diagrams, charts, icons, or images merely to describe their
-content.
-
-Use the existing specialized contracts for specialized facts:
-
-- `data-pptx-layout`, `data-pptx-layout-name`, `data-pptx-layout-kind`, and
- `data-pptx-layer` own Master/Layout/Slide structure. A free-design page uses
- them only after explicit post-design distillation. A deferred template page
- carries the selected prototype key/name and layer provenance during design,
- then adds the final kind only after distillation;
-- `data-pptx-placeholder` owns the Layout placeholder prototype. A distilled
- carrier remains an ordinary object on the completed Slide. Legacy immediate
- template and pre-authored structured routes may also bind the Slide shape;
-- `data-pptx-native` owns native chart/table reconstruction.
-- `data-pptx-object`, `data-pptx-prst`, `data-pptx-frame`, `data-pptx-av-*`,
- `data-pptx-geometry-*`, `data-pptx-authoring`, and `data-pptx-part` own
- imported round-trip and authored preset-shape semantics under
- [`shared-standards.md`](./shared-standards.md) §§1.4–1.5.
-
-Authored preset metadata comes only from `preset_shape_svg.py`; ordinary SVG
-paths are never scanned, classified, or automatically upgraded to a preset.
-
-Do not duplicate those facts with `data-pptx-role`. Consumers resolve semantics
-in this order: specialized metadata, minimal compiler hints, then legacy
-filename/id conventions.
-
-The exporter consumes Layout structure; it never discovers or clusters it.
-[`distill-layouts`](../workflows/distill-layouts.md) is the explicit authoring
-workflow that converts user-selected baseline pages or every deferred template
-page into final metadata before export. On template routes, `page_layouts`
-selects the input prototype and `pptx_layouts` records the post-design output.
-Reuse a key only when its placeholder default frames and static Layout layer
-match. Do not move concrete content into a Layout or mark a complex
-page-specific group merely to manufacture reuse.
-
-Ordinary placeholder carriers are direct atomic objects: one text frame, image,
-crop SVG, or other supported atomic shape. This is a narrow exception to the
-top-level content-group budget, and the carrier does not count toward that
-budget. A final post-design `distilled` page may additionally mark one direct
-completed `<g>` as an `object` region proxy with explicit design-zone bounds;
-the visible group remains ordinary and export adds a hidden transparent binding
-proxy. Reusable template SVGs, pending template pages, utility pages, and legacy
-immediate contracts may not use this exception. Native chart/table marker
-groups remain governed by their separate specialized contract.
-
-## 2. Canonical Values
-
-### Page roles
-
-| Value | Meaning | Baseline Layout |
-|---|---|---|
-| `cover` | Opening cover | `Cover` |
-| `toc` | Agenda or contents page | `Agenda` |
-| `section` | Chapter divider or transition | `Section` |
-| `content` | Ordinary information page | `Content` |
-| `ending` | Closing, thanks, Q&A, or contact page | `Closing` |
-
-### Layout kinds
+| `data-pptx-master` / `data-pptx-master-name` | Root `<svg>` | Bind the page to one named PowerPoint Slide Master. |
+| `data-pptx-layout` / `data-pptx-layout-name` | Root `<svg>` | Bind the page to one named Layout under that Master. |
+| `data-pptx-layer="master"` | Direct atomic child of root | Promote one fixed visual object to the named Master. |
+| `data-pptx-layer="layout"` | Direct atomic child of root | Promote one fixed visual object to the named Layout. |
+| `data-pptx-placeholder` | Direct child `<g id>` of root | Declare one reusable Layout slot whose visible content remains Slide-local. |
+| `data-pptx-role` | Structural page-frame element | Supply package, page-number, or animation behavior not already expressed by specialized metadata. |
-| Value | Meaning |
-|---|---|
-| `distilled` | A completed baseline selection or deferred template page distilled into reusable placeholder defaults and optional static framing. Every placeholder has explicit `data-pptx-placeholder-bounds`. |
-| `utility` | The empty Freeform Layout shared by baseline pages not selected for distillation. It is forbidden on deferred template routes. |
+The completed SVG remains the full visible page. Removing the metadata must not change browser rendering. Do not copy visible text, geometry, style, or asset values into metadata.
-### Structural roles
+**Hard rule — structure exists at design time**: Every newly generated page declares its final Master and Layout before drawing begins. The exporter compiles this contract; it never selects, clusters, distills, or visually infers it.
-| Value | Compiler behavior |
-|---|---|
-| `background` | Treat an otherwise unmarked background as static page framing for animation purposes. |
-| `decoration` | Treat decorative page framing as static for animation purposes. |
-| `header` | Eligible for conservative repeated-chrome promotion; skip automatic entrance animation. |
-| `footer` | Eligible for conservative repeated-chrome promotion; skip automatic entrance animation. |
-| `logo` | Eligible for conservative repeated-chrome promotion; skip automatic entrance animation. |
-| `watermark` | Eligible for conservative repeated-chrome promotion; skip automatic entrance animation. |
-| `chrome` | Generic repeated page-frame object eligible for conservative promotion. |
-| `page-number` | Identify a free-design page-number object; template `data-pptx-placeholder="slide-number"` already owns this behavior. |
+**Hard rule — specialized metadata wins**: Use Master/Layout/placeholder metadata for native structure, `data-pptx-native` for chart/table reconstruction, and the imported/authored shape metadata defined in [`shared-standards.md`](./shared-standards.md) §§1.4–1.5. Do not duplicate those facts with `data-pptx-role`.
-`background` and `decoration` do not by themselves authorize Master/Layout
-promotion. The existing background and exact-shared-structure safety checks
-continue to own that decision.
+---
-## 3. Examples
+## 2. Master and Layout Atoms
-### Unmapped baseline fallback page
+Master and fixed Layout visuals are atomic root children:
```xml
<svg xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 1280 720"
- data-pptx-page-role="content">
- <rect id="page-bg" data-pptx-role="background"
- x="0" y="0" width="1280" height="720" fill="#F7F9FC"/>
-
- <!-- Ordinary content keeps normal SVG structure; no duplicate role needed. -->
- <g id="growth-story">
- <text x="72" y="82" font-size="32" fill="#172033">Quarterly growth</text>
- </g>
-
- <text id="slide-number" data-pptx-role="page-number"
- x="1200" y="680" font-size="14" fill="#667085">7</text>
+ data-pptx-master="master-default"
+ data-pptx-master-name="Default Master"
+ data-pptx-layout="content-two-column"
+ data-pptx-layout-name="Two Column">
+ <rect id="master-bg" data-pptx-layer="master"
+ x="0" y="0" width="1280" height="720" fill="#F8FAFC"/>
+ <path id="layout-rule" data-pptx-layer="layout"
+ d="M72 132H1208" stroke="#CBD5E1"/>
</svg>
```
-### Post-design distilled Layout page
+| Requirement | Rule |
+|---|---|
+| Placement | Every Master/Layout atom is a direct child of the root SVG and has a stable unique `id`. |
+| Grouping | A `<g>` may not carry `data-pptx-layer="master|layout"`. Imported PowerPoint groups are recursively flattened and their transform/style/opacity/z-order semantics are pushed into atomic children. |
+| Atomicity | One marked child must compile to one DrawingML object. A nested crop `<svg>` is allowed only when it is the supported single-picture carrier, not an arbitrary container. |
+| Consistency | Pages sharing one Master key repeat the identical ordered Master atom contract. Pages sharing one `(master, layout)` pair repeat the identical ordered Layout atom contract. |
+| Ownership | Concrete titles, body text, metrics, charts, tables, images, and page-specific decoration stay Slide-local or inside a declared slot. |
+
+> Note: Flattening a source PPTX group preserves supported appearance and native-layer ownership, but intentionally does not preserve the source group-editing hierarchy.
-This form applies after the user selects a completed free-design/brand-only
-baseline page, or after a deferred template page is reconciled with its
-`page_layouts` prototype. Baseline does not imply an input prototype; template
-does. Bounds are Layout defaults while current Slide geometry may differ. The
-atomic carriers keep their matching Slide bindings, while a composite object
-region remains an ordinary visible group with a hidden transparent binding
-proxy. The generated Layout receives the reusable PowerPoint placeholders.
+---
+
+## 3. Layout Slots
+
+### 3.1 Carrier-bound slot
+
+Use one direct root group as the authoring boundary and one compatible direct child as the visible PowerPoint placeholder carrier:
```xml
-<svg xmlns="http://www.w3.org/2000/svg"
- viewBox="0 0 1280 720"
- data-pptx-layout="editorial-visual"
- data-pptx-layout-name="Editorial Visual"
- data-pptx-layout-kind="distilled">
- <path id="layout-rule" data-pptx-layer="layout"
- data-pptx-editable="false"
- d="M72 132H1208" stroke="#D0D5DD"/>
-
- <!-- Current x/y may differ from the reusable design-zone bounds. -->
- <text id="title-slot" data-pptx-placeholder="title"
- data-pptx-placeholder-bounds="72 48 1136 64"
- x="88" y="104" font-size="32" fill="#172033">Quarterly growth</text>
-
- <text id="body-slot" data-pptx-placeholder="body"
- data-pptx-placeholder-idx="1"
- data-pptx-placeholder-bounds="72 160 432 472"
- x="80" y="190" font-size="20" fill="#344054">Main narrative</text>
-
- <image id="picture-slot" data-pptx-placeholder="picture"
- data-pptx-placeholder-idx="2"
- data-pptx-placeholder-bounds="544 160 664 472"
- href="../images/quarterly-growth.png"
- x="576" y="176" width="616" height="440"
- preserveAspectRatio="xMidYMid slice"/>
-
- <!-- Logo has no specialized marker, so the minimal structural hint is useful. -->
- <text id="brand-mark" data-pptx-role="logo"
- x="1180" y="46" text-anchor="end">ACME</text>
-
- <!-- The placeholder already owns slide-number behavior; do not add a role. -->
- <text id="page-number" data-pptx-placeholder="slide-number"
- data-pptx-placeholder-idx="3"
- data-pptx-placeholder-bounds="1152 664 56 24"
- x="1200" y="680" text-anchor="end">7</text>
-</svg>
+<g id="title-slot"
+ data-pptx-placeholder="title"
+ data-pptx-placeholder-bounds="72 48 1136 72">
+ <text id="title-carrier"
+ data-pptx-placeholder-carrier="true"
+ x="72" y="100">Actual title</text>
+</g>
```
-### Unselected page after distillation
+| Requirement | Rule |
+|---|---|
+| Placement | The slot `<g id>` is a direct root child. Structural metadata may not be nested below it. |
+| Bounds | `data-pptx-placeholder-bounds="x y width height"` is mandatory, finite, and positive. It describes the reusable design zone, not the current glyph/content tight bounds. |
+| Carrier | The group contains exactly one compatible direct drawable child marked `data-pptx-placeholder-carrier="true"`. Export unwraps that child into the real Slide placeholder binding. |
+| Identity | `data-pptx-placeholder-idx` is optional; effective indices must be unique within one Layout. Preserve a source index when reconstructing an existing PPTX. |
+| Fixed decoration | Reusable decoration does not belong in the slot. Author it as a root Layout atom. Page-specific labels/captions use another slot or remain Slide-local. |
+
+Canonical placeholder values are `title`, `subtitle`, `body`, `picture`, `chart`, `table`, `object`, `media`, `date`, `footer`, and `slide-number`. Carrier compatibility is defined in [`shared-standards.md`](./shared-standards.md) §7.
-The page declares the complete project mapping but keeps every page-specific
-visible object Slide-local. No child may carry Layout or placeholder metadata;
-an exact shared Master contract is allowed when every page repeats it.
+### 3.2 Explicit composite proxy
+
+When one reusable region is a composite object that cannot bind to one real PowerPoint placeholder, declare the downgrade explicitly:
```xml
-<svg xmlns="http://www.w3.org/2000/svg"
- viewBox="0 0 1280 720"
- data-pptx-layout="freeform-unselected"
- data-pptx-layout-name="Freeform"
- data-pptx-layout-kind="utility">
- <g id="page-content">
- <!-- The complete free-form design remains ordinary SVG. -->
- </g>
-</svg>
+<g id="hero-composite-slot"
+ data-pptx-placeholder="object"
+ data-pptx-placeholder-binding="proxy"
+ data-pptx-placeholder-bounds="544 160 664 472">
+ <rect x="544" y="160" width="664" height="472" fill="#E2E8F0"/>
+ <text x="576" y="214">Visible composite content</text>
+</g>
```
-## 4. Validation and Compatibility
-
-The quality checker validates marker placement, canonical values, and stable
-unique IDs. Export consumes explicit authored Layout metadata before baseline
-compatibility hints and heuristics:
-
-- root `data-pptx-layout` is authoritative when the page has a locked mapping;
-- post-design distillation also requires root `data-pptx-layout-kind` to match the lock;
-- a deferred template project with no `pptx_layouts` is pending and cannot enter release export;
-- on an unmapped baseline page, root page role is preferred over filename-based Layout classification;
-- `data-pptx-placeholder="slide-number"` is preferred over a generic role or id;
-- explicit structural role is preferred over id-token chrome detection;
-- animation target scanning uses the structural role before id-token fallback.
-
-Filename and id heuristics remain compatibility fallbacks only for older SVGs
-that lack the corresponding marker. On an unmapped baseline page, a
-canonical page role is authoritative over the filename. Any explicit structural
-role prevents id-based reinterpretation; an unknown role remains renderable but
-produces a quality-check warning.
+The visible group stays Slide-local. Export creates one hidden transparent matching placeholder proxy. Proxy binding is valid only for `object`; it is an explicit fallback, not the default slot form.
+
+### 3.3 Zero-slot Layout
+
+A Layout may contain no slot groups. Cover, poster, full-visual, or other fixed-composition pages still declare their Master/Layout root identity and any fixed atoms; do not manufacture a full-page `object` placeholder merely to make the Layout non-empty.
+
+---
+
+## 4. Minimal Structural Roles
+
+Use `data-pptx-role` only when no specialized marker owns the behavior:
+
+| Value | Compiler behavior |
+|---|---|
+| `background` | Treat an otherwise unmarked background as static page framing for animation. |
+| `decoration` | Exclude decorative framing from automatic entrance animation. |
+| `header`, `footer`, `logo`, `watermark`, `chrome` | Identify Slide-local static framing without claiming Master/Layout ownership. |
+| `page-number` | Identify a Slide-local number when no `slide-number` placeholder exists. |
+
+Do not add structural roles to ordinary titles, body copy, cards, KPIs, diagrams, charts, icons, or images.
+
+---
+
+## 5. Validation and Migration
+
+The quality checker rejects:
+
+- a missing root Master/Layout identity or a page-to-lock mismatch;
+- a Master/Layout `<g>`, nested structure marker, missing/stale id, or inconsistent shared atom contract;
+- a slot without positive bounds, a carrier-bound slot without exactly one compatible carrier, or a proxy binding on a non-`object` slot;
+- incomplete page mappings, cross-Master Layout-key reuse, or conflicting same-key Layout contracts.
+
+Legacy SVGs using unmapped `baseline`, `preserve`, `layout_strategy: distill`, `data-pptx-layout-kind`, `distilled`, `utility`, direct atomic placeholders, or missing Master identity are not a second supported authoring contract. Run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before generation or export. When original PPTX/native facts exist, migration restores those identities first; otherwise the main Agent explicitly derives a structure from the complete SVG pages. Export never performs that derivation.
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index b75db67d..c0fc934a 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -388,20 +388,7 @@ table/chart markers are rejected; omit that flag to export their SVG fallback.
### 4.1 Semantic SVG Marker Contract
Semantic markers are minimal compiler hints orthogonal to native SVG semantics.
-Existing `data-pptx-layout` / layer / placeholder / native-object metadata is
-authoritative and read first. Deferred template pages carry the selected
-prototype structure while authored but do not finalize `pptx_layouts` or root
-kind until the complete design exists. Legacy immediate-template/preserve pages
-declare their locked output Layout while authored. Free-design/brand-only
-baseline pages remain unmapped during visual design; only the explicit post-design
-[`distill-layouts`](../workflows/distill-layouts.md) workflow adds a complete
-Layout mapping after the user selects reusable pages or after every deferred
-template page is complete. An unmapped baseline page
-may use `data-pptx-page-role` for compatibility routing. Add `data-pptx-role`
-only when no specialized marker expresses the required page-frame behavior;
-the element also uses a stable unique `id`. Do not classify ordinary page
-content or move visible facts out of SVG attributes/text into metadata. See
-[`semantic-svg.md`](semantic-svg.md) for the canonical vocabulary and examples.
+Root Master/Layout identity, atomic layer elements, grouped slots, and native-object metadata are authoritative and read first. Every new page carries its final structured contract from the start of SVG authoring. Add `data-pptx-role` only when no specialized marker expresses the required page-frame behavior; the element also uses a stable unique `id`. Do not classify ordinary page content or move visible facts out of SVG attributes/text into metadata. See [`semantic-svg.md`](semantic-svg.md) for the canonical vocabulary and examples.
- **Canvas authority**: `viewBox` MUST match the selected canvas dimensions.
Root `width` and `height` are optional and do not override it. Root `<svg>`
@@ -423,8 +410,8 @@ These forms are needed only when the stated PPT behavior matters:
| One editable PPT text frame with mixed inline formatting | Put the logical line in one `<text>` with non-positional `<tspan>` children. A `<tspan>` with `x`/`y`/`dy` starts a new positioned line; evenly `dy`-stacked lines that repeat the parent `<text>`'s `x` merge into one frame with hard line breaks. A larger accepted gap or list marker starts a new paragraph; flowing prose opts into reflow via the explicit paragraph contract below. The merged frame keeps normal PowerPoint wrapping for later edits. An unmergeable gap or mismatched `x` flattens to separate frames. Separate `<text>` elements stay valid when separate frames are intended. |
| 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. |
-| Reusable free-design PowerPoint Layout | Finish the free design first, then run [`distill-layouts`](../workflows/distill-layouts.md) on pages explicitly selected by the user. The workflow writes the complete `pptx_layouts` mapping and §7 metadata; the exporter itself never infers visual similarity. Before distillation, an unmapped baseline project uses §4.1 compatibility routing. |
-| Reusable template-based PowerPoint Layout | Select one complete input SVG per page in `page_layouts`, finish every visible page, then run [`distill-layouts`](../workflows/distill-layouts.md). Strict restores prototype structure/bounds; adaptive keeps Master ids/topology/geometry and may finalize an evolved Layout. Non-mirror skin follows `spec_lock`. |
+| Reusable free-design PowerPoint Layout | Strategist declares the Master roster and complete page-to-Layout map before drawing. Executor writes the root identities, atomic fixed layers, and grouped slots while authoring each page. Export compiles only those declarations. |
+| 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`. |
**Explicit paragraph contract — reflowable prose**: authored rows export as
hard line breaks unless the block declares otherwise. When a block is flowing
@@ -464,11 +451,11 @@ exported frame edits as one reflowing paragraph:
### 4.3 Element Grouping (Mandatory)
-Wrap logically related elements in top-level `<g id="...">` groups. This is **required on every generated page**, not an optional convenience: it produces real PowerPoint groups in the exported PPTX (easier to select / move / edit) and gives each content unit a stable anchor for optional per-element entrance animation. Plain `<g>` is the normal grouping primitive; `<g opacity="0..1">` additionally maps to the per-descendant alpha approximation in §2.2. A direct structural background/layer atom or one direct atomic object carrying `data-pptx-placeholder` is the narrow exception defined in §7; the placeholder must remain one native carrier and neither form counts toward the group budget.
+Wrap logically related Slide-local elements in top-level `<g id="...">` groups. This is **required on every generated page**, not an optional convenience: it produces real PowerPoint groups in the exported PPTX and gives each content unit a stable animation anchor. Plain `<g>` is the normal grouping primitive; `<g opacity="0..1">` additionally maps to the per-descendant alpha approximation in §2.2. Direct atomic Master/Layout elements are the required exception and may never be layer groups. A top-level slot `<g>` is already a semantic group and is excluded from the ordinary content-group budget.
-**Semantic-group rule**: direct children of `<svg>` are semantic content groups, **not** raw drawing atoms. Aim for **3–8 top-level content `<g id>` groups per slide** (the budget excludes page chrome and direct atomic placeholder carriers — see below); each content group becomes one entrance step under the chosen animation trigger (one click in `on-click`, one cascade slot in `after-previous`, parallel in `with-previous`). Leaving titles, body lines, list items, cards, or decorative clusters as ungrouped top-level `<text>` / `<rect>` / `<path>` is a contract violation unless that one direct atom is an explicit supported placeholder carrier.
+**Semantic-group rule**: apart from atomic Master/Layout objects and the optional Slide background, direct Slide content uses semantic groups. Aim for **3–8 ordinary top-level content `<g id>` groups per slide**; slot groups and structural atoms are excluded. Each ordinary group becomes one entrance step under the chosen animation trigger. Leaving Slide-local titles, body lines, list items, cards, or decorative clusters as ungrouped top-level atoms is a contract violation.
-**Chrome and placeholder carriers are excluded automatically.** Existing `data-pptx-layer` and `data-pptx-placeholder` semantics are read first; otherwise explicit `data-pptx-role` values (`background`, `decoration`, `header`, `footer`, `chrome`, `watermark`, `page-number`, `logo`) mark static framing (§4.1, [`semantic-svg.md`](semantic-svg.md)). Marker-free legacy SVGs keep id-token fallbacks. Keep the `<g>` wrapper on chrome for editing/grouping even though it does not count against the 3–8 content budget. Do not wrap several drawing atoms in an arbitrary `<g>` and claim that composite as one placeholder; complex groups stay Slide-local. Native chart/table marker groups retain their specialized §7 contract.
+**Structural atoms and slots are excluded automatically.** `data-pptx-layer` and `data-pptx-placeholder` semantics are read first; otherwise explicit `data-pptx-role` values (`background`, `decoration`, `header`, `footer`, `chrome`, `watermark`, `page-number`, `logo`) mark Slide-local static framing (§4.1, [`semantic-svg.md`](semantic-svg.md)). A normal slot group has exactly one direct compatible carrier; several drawing atoms require the explicit composite `object` proxy fallback. Native chart/table carrier groups retain their specialized §7 contract.
**What to group** (one `<g id>` per unit):
@@ -487,7 +474,7 @@ An authored native preset fragment (§1.5) is already an atomic `<g id>` and cou
**Forbidden**:
- One giant `<g>` around the whole slide (collapses to a single animation step).
-- Many ungrouped top-level `<rect>` / `<text>` / `<path>` without supported placeholder metadata — fallback animation caps at 8 primitives, dense pages may skip animation, and selection/editing degrades.
+- Many ungrouped Slide-local `<rect>` / `<text>` / `<path>` atoms — fallback animation caps at 8 primitives, dense pages may skip animation, and selection/editing degrades.
- One group per icon / text line / mark (too many steps).
- Anonymous top-level groups — every top-level semantic group needs a descriptive `id`.
@@ -1361,111 +1348,27 @@ defaults to `bottom` and accepts `top`, `left`, or `right`.
**Forbidden — native marker transforms**: Do not rotate, skew, or matrix-transform native table/chart marker groups. Translate / scale is accepted; complex transforms fail export because PowerPoint native table/chart frames do not preserve arbitrary SVG transforms.
-### Baseline Layout Routing
-
-Native `baseline` export has two deterministic routes. A new free-design or
-brand-only project initially omits `pptx_layouts` and keeps all page geometry
-Slide-local while the visual design is still free. If the user later selects
-finished pages for reuse, [`distill-layouts`](../workflows/distill-layouts.md)
-atomically writes one mapping row for every page: selected pages use explicit
-`distilled` contracts and unselected pages share an empty `utility` Layout.
-Existing structured baseline projects remain readable. An unmapped project uses
-the compatibility family pass below. Mixing declared and undeclared pages is
-invalid. The authoring workflow may distill a user-selected design; the exporter
-never performs visual clustering.
-
-**Explicit baseline route**: Reuse one distilled Layout key only when pages have
-the same reusable placeholder type/index/default-bounds contract and any static
-Layout layer is identical. A distilled Layout may be placeholder-only; it does
-not need decorative Layout shapes. Different wording, data, imagery, or
-Slide-local geometry stays on the Slide and does not create a new Layout. For
-example, 4:6, 3:7, and 5:5 members may share one Layout when their semantic
-zones are the same; the Layout stores one default frame while each Slide keeps
-its authored local frame. A genuinely different reusable composition gets a
-different key, even when both pages have the semantic role `content`.
-
-**Utility Layout**: In a distilled project, every unselected page maps to the
-same `utility` Layout. That Layout has no Layout shapes and no
-placeholders; every page-specific visible object remains Slide-local. A shared
-deck Master contract may still repeat on the page. The utility Layout exists only
-to keep the post-distillation mapping complete and must not be used as evidence
-that the page itself was distilled.
-
-**Unmapped compatibility route**: Before free-design distillation, or when
-reading a legacy project whose whole mapping section is absent, assign the
-coarse page families below after every unstructured SVG page has been converted.
-This does not change SVG authoring or live preview.
-
-| Root `data-pptx-page-role` | Output layout |
-|---|---|
-| `cover` | `Cover` |
-| `toc` | `Agenda` |
-| `section` | `Section` |
-| `ending` | `Closing` |
-| `content` | `Content` |
-
-Marker-free legacy SVGs retain conservative filename-token fallback: explicit
-cover / agenda / section / closing tokens select those families, and every
-other page becomes `Content`. When a valid root marker exists, it is
-authoritative even if the filename suggests another family.
-
-Keep an existing `Cover` assignment when the Master chrome safety pass already
-used it to hide promoted Master shapes from a minority page.
-
-**Hard rule — no visual inference**: Keep every actual title, body, picture,
-chart, table, and page-specific shape on the Slide. Explicit baseline Layouts
-consume authored metadata; unmapped compatibility Layouts do not infer
-placeholders or promote visually similar content.
-
-**Background rule**: Move a Slide `p:bg` to its family Layout only when every
-slide in that family carries exactly the same explicit background. Otherwise,
-keep each background on its Slide. Preserve whether each family shows or hides
-the parent Master shape tree.
-
-**Layout chrome rule**: After family assignment, move only the identical
-leading prefix of explicitly marked chrome (`logo`, `footer`, `header`,
-`watermark`, `chrome`) carried by every family member. Legacy id tokens are
-consulted only when `data-pptx-role` is absent. Generated OOXML and
-image relationships must match exactly, no animation may target the shapes,
-and moving them behind Slide content must preserve z-order. Keep page numbers
-and every non-identical object Slide-local.
+### Structured Layout Routing
+
+Every new SVG project has one deterministic route: `pptx_structure.mode: structured`. `spec_lock.md` contains a complete Master roster and one page-to-Master/Layout row before the first page is drawn. Free design defaults to one Master; templates preserve their restored Master topology.
+
+**Hard rule — no structure inference**: Export does not assign Layout families, promote repeated chrome, cluster pages, infer placeholders, or repair missing metadata. It compiles only the declared root identities, atomic fixed layers, and slot groups. Legacy or unmapped projects must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) first.
+
+**Layout reuse**: Reuse one Layout key only when its ordered fixed Layout atoms and slot ids/types/effective indices/default bounds/binding modes are identical. Different wording, data, imagery, crop, or Slide-local carrier geometry does not create a new Layout. A genuinely different reusable contract gets a new key even when both pages are semantically `content`.
+
+**Zero-slot Layout**: A named Layout may contain no slots and no fixed Layout atoms. This is valid for a cover, poster, full-visual page, or other fixed composition. Do not manufacture an empty `utility` kind or full-page fake `object` slot.
+
+**Adaptive change**: Template `strict` preserves the selected prototype contract. `adaptive` retains the prototype Master and may create a new Layout identity only when fixed Layout atoms or slot topology/bounds change. Update the page mapping immediately while authoring the first such page; never mutate a reused key silently.
### Explicit PPTX Master / Layout / Placeholder Metadata
-**Trigger**: Free-design/brand-only routes use `pptx_structure.mode: baseline`
-without `pptx_layouts` during visual authoring. Explicit post-design
-distillation adds `layout_strategy: distill` plus complete `pptx_layouts`.
-Distillation-capable deck/layout template routes use
-`pptx_structure.mode: template` plus `layout_strategy: distill` and complete
-`page_layouts`, but omit `pptx_layouts` until every page is complete. A
-bounds-missing strict legacy prototype and existing template locks without the
-strategy retain immediate mappings. Preserve keeps its source-package contract.
-Direct diagnostics may pass `--pptx-structure template`. In baseline, explicit
-Layout metadata without a complete lock is an error rather than a dormant hint.
-In deferred template authoring, provisional prototype metadata is allowed while
-the output mapping is wholly absent, but release export remains blocked until
-distillation writes the complete mapping and root kind.
-
-**Project lock**: Legacy immediate-template and existing explicit routes write
-one `pptx_layouts` row per page using
-`P<NN>: <layout_key> | <PowerPoint layout name>`. Post-design distillation uses
-`P<NN>: <layout_key> | <PowerPoint layout name> | <layout_kind>`, where every
-baseline kind is `distilled` or `utility`; every deferred template kind is
-`distilled`. The SVG root values MUST match that row.
-Baseline distillation derives the key/name only from the completed pages that
-the user selected and does not create `page_layouts`. Template `page_layouts`
-is the input-prototype mapping: strict restores its key/name/Master/Layout/
-placeholder structural contract, while adaptive repeats its Master ids/topology/geometry and may create a
-new Layout key/name. Adaptive may retain the prototype key/name only when its
-static Layout, placeholder identities, and default bounds remain unchanged.
-Mirror additionally keeps literal paint, typography, effects, grouping, and
-geometry for every reused Master/Layout identity; only visible text changes.
-Reuse one key only when pages share the same
-placeholder default-frame contract and any static Layout layer; different
-content or local geometry is not a reason to create a new Layout. Every explicit
-route requires numeric `spec_lock.md` typography `title` / `body` rows.
-
-**Master text-style contract**: Structured baseline and template export map the
+**Trigger**: Every newly generated SVG page uses this interface. `spec_lock.md` declares `pptx_structure.mode: structured`, a complete `pptx_masters` roster, and one `pptx_layouts` row per page before authoring begins. Template routes additionally keep `page_layouts` as input-prototype provenance.
+
+**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.
+
+**Template behavior**: Strict preserves the selected prototype's 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 additionally preserves literal paint, typography, effects, atomic geometry, and referenced assets for every reused identity. The source PPTX group hierarchy may still be flattened because Master/Layout groups are outside the current SVG contract.
+
+**Master text-style contract**: Structured export maps 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`.
@@ -1478,8 +1381,7 @@ locked `body` size to every level in both `p:bodyStyle` and `p:otherStyle`.
**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 explicit Layout export. Unmapped baseline,
-`preserve`, and `flat` do not apply this Master text-style update.
+Missing `title` or `body` rows fail 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
@@ -1491,29 +1393,25 @@ prototype size remain unchanged.
| Metadata | Placement | Behavior |
|---|---|---|
+| `data-pptx-master="master-default"` | root `<svg>` | Binds the slide to one generated Slide Master key |
+| `data-pptx-master-name="Default Master"` | root `<svg>` | Sets the Master picker/display name |
| `data-pptx-layout="content"` | root `<svg>` | Binds the slide to one generated reusable layout key |
| `data-pptx-layout-name="Title and Content"` | root `<svg>` | Sets the PowerPoint layout-picker name; defaults from the layout key |
-| `data-pptx-layout-kind="distilled"` | root `<svg>` | Marks a completed baseline selection or deferred template page as `distilled`; baseline-only unselected shells use `utility` |
-| `data-pptx-layer="master"` | direct visual child | Moves one repeated static object/background into the slide master |
-| `data-pptx-layer="layout"` | direct visual child | Moves one repeated static object/background into the selected layout |
+| `data-pptx-layer="master"` | direct atomic visual child | Moves one repeated static object/background into the named Slide Master; `<g>` is forbidden |
+| `data-pptx-layer="layout"` | direct atomic visual child | Moves one repeated static object/background into the selected Layout; `<g>` is forbidden |
| `data-pptx-layer="slide"` | direct full-canvas solid `<rect>` only | Writes a one-page override as Slide `p:bg` |
-| `data-pptx-placeholder="..."` | direct visual child | Supplies a generated Layout placeholder prototype. Legacy immediate/pre-authored template contracts and `distilled` atomic carriers bind the current Slide shape; a final distilled composite object region remains ordinary and uses a hidden binding proxy. |
-| `data-pptx-placeholder-bounds="x y width height"` | placeholder element | Overrides the reusable placeholder frame in SVG user units |
-| `data-pptx-placeholder-idx="1"` | placeholder element | Retains an imported source layout placeholder index; optional for reconstructed layouts |
+| `data-pptx-placeholder="..."` | direct slot `<g id>` | Declares a reusable Layout slot whose visible content remains Slide-local |
+| `data-pptx-placeholder-bounds="x y width height"` | slot `<g>` | Supplies the positive reusable design-zone frame in SVG user units |
+| `data-pptx-placeholder-idx="1"` | slot `<g>` | Retains an imported source Layout placeholder index; optional for reconstructed layouts |
+| `data-pptx-placeholder-carrier="true"` | one compatible direct child of a normal slot | Binds that visible child as the real Slide placeholder carrier |
+| `data-pptx-placeholder-binding="proxy"` | composite `object` slot `<g>` only | Keeps the visible group ordinary and creates one hidden transparent binding proxy |
| `data-pptx-editable="false"` | master/layout element or slide background | Declares intentional editing outside ordinary slide content |
-**Hard rule — explicit only**: Structured baseline and template export never
-promote visually similar content by inference. Every mapped SVG requires root
-`data-pptx-layout` and `data-pptx-layout-name`; a distilled mapping also
-requires `data-pptx-layout-kind`. Every master/layout/placeholder element
-requires a unique `id` and must be a direct child of the root SVG. A baseline
-`utility` page is the narrow exception: it declares the root contract but contains no
-Layout element or placeholder. It may repeat the exact Master contract shared
-by every mapped page.
+**Hard rule — explicit only**: Structured export never promotes visually similar content by inference. Every SVG requires the four root Master/Layout identity attributes. Every Master/Layout atom and slot requires a unique stable `id` and is a direct root child. Layouts with zero slots are valid. `data-pptx-layout-kind`, `distilled`, and `utility` are legacy metadata and fail the current contract.
**Layer order**: Author the SVG in PowerPoint paint order: Master background,
-Layout background, optional Slide background, Master shapes, Layout shapes,
-then slide-local content/placeholders. Backgrounds are a special inheritance
+Layout background, optional Slide background, remaining Master atoms, remaining Layout atoms,
+then slot groups and Slide-local content groups. Backgrounds are a special inheritance
plane beneath every shape; this order keeps standalone SVG preview and
PowerPoint rendering aligned. The exporter rejects interleaved layers.
@@ -1528,16 +1426,16 @@ cover/section/content variants under the same design language. Gradients,
images, textures, transformed rects, and visible-stroke rects are not promoted
by this solid-background rule.
-| Placeholder value | SVG element | PowerPoint placeholder |
+| Placeholder value | Direct carrier inside slot `<g>` | PowerPoint placeholder |
|---|---|---|
-| `title`, `subtitle`, `body` | direct `<text>` | `title`, `subTitle`, `body` |
-| `date`, `footer`, `slide-number` | direct `<text>` | `dt`, `ftr`, `sldNum` |
-| `picture` | direct `<image>` or imported crop `<svg>` | `pic` |
-| `chart`, `table` | direct matching `data-pptx-native` marker group | `chart`, `tbl` |
-| `object` | one direct text, image, or basic SVG shape; final `distilled` output may instead use one direct composite group as a Layout-only region proxy | `obj` |
-| `media` | direct `<image>` or imported crop `<svg>` | `media` |
-
-**Text placeholder carrier**: A multiline text placeholder must remain one
+| `title`, `subtitle`, `body` | one `<text data-pptx-placeholder-carrier="true">` | `title`, `subTitle`, `body` |
+| `date`, `footer`, `slide-number` | one `<text data-pptx-placeholder-carrier="true">` | `dt`, `ftr`, `sldNum` |
+| `picture` | one `<image>` or supported imported crop `<svg>`, marked as carrier | `pic` |
+| `chart`, `table` | one matching `data-pptx-native` marker group, marked as carrier | `chart`, `tbl` |
+| `object` | one text, image, or basic SVG shape marked as carrier; alternatively the slot group declares `binding="proxy"` | `obj` |
+| `media` | one `<image>` or supported imported crop `<svg>`, marked as carrier | `media` |
+
+**Text slot carrier**: A multiline text placeholder must remain one
native text frame. Use the default paragraph merge; `--no-merge` and explicit
`data-pptx-text-mode="lines"` cannot supply several line shapes as one
PowerPoint placeholder prototype/binding. Leave strict-line text Slide-local
@@ -1545,13 +1443,7 @@ when separate frames are the required result.
`title` is normally type-matched without an index in reconstructed layouts; if
an imported source title explicitly has one, preserve that exact index. Every
-indexed placeholder on one layout uses a unique OOXML UInt32 index. Explicit
-legacy immediate-template/pre-authored export writes the semantic type on both the Layout and
-Slide placeholder (except `obj`, whose OOXML default is already `obj`) so
-PowerPoint and `python-pptx` retain the same identity. Distilled export always
-writes that identity on the Layout; atomic Slide carriers retain a matching
-binding, while a composite object region uses an ordinary visible carrier plus
-a hidden transparent proxy.
+indexed placeholder on one layout uses a unique OOXML UInt32 index. Structured export writes the semantic type on both the Layout and Slide carrier (except `obj`, whose OOXML default is already `obj`) so PowerPoint and `python-pptx` retain the same identity. A composite object slot instead keeps its visible group ordinary and uses a hidden transparent proxy.
Date, footer, and slide-number placeholders enable their matching Layout `p:hf`
flags; a date placeholder also gets a `datetimeFigureOut` field in the reusable
Layout definition. The current Slide keeps its authored date content.
@@ -1560,104 +1452,44 @@ 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.
-**Placeholder prototype**: The first slide using a layout key supplies that
-layout's placeholder formatting. `data-pptx-placeholder-bounds` supplies the
-reusable default frame. Legacy immediate-template and pre-existing explicit
-contracts may omit it and fall back to the prototype object's native DrawingML
-bounds. Every newly created template page and every `distilled` Layout provides
-it on every placeholder: derive the bounds from
+**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
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 placeholder ids/types/default bounds on every slide using
-that layout. For `distilled`, the Layout always owns the reusable `p:ph`.
-Atomic text/picture/native-object carriers keep a matching Slide binding so the
-approved rendering stays identical. A direct composite `<g>` is allowed only as
-a final distilled `object` region proxy: its visible Slide group remains
-ordinary, and export adds one hidden transparent matching binding shape to
-suppress empty inherited placeholder paint in PowerPoint-compatible renderers.
-The placeholder bounds define the Layout default only; actual Slide content and
-local geometry may differ.
-
-**Final-package read-back gate**: After writing a temporary structured-baseline
-or template-mode PPTX and before publishing it, export reopens the package and
+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
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,
-placeholder type and effective index, matching `p:hf` flags, prototype-derived
-or explicitly overridden frame, direct prompt size, and level-one default size.
+Master picker identity, placeholder type and effective index, matching `p:hf` flags, explicit design-zone frame, direct prompt size, and level-one default size.
Every owned `p:bg` is checked as an exact zero-or-one payload against the pre-
promotion result; this includes preserving the base Master background when no
authored Master background replaces it. During the same export, every finished
Slide, Layout, and Master must reproduce its exact top-level shape-name roster
-and order after packaging. For `distilled`, the gate additionally verifies that
-each atomic visible carrier owns the expected binding, each composite visible
-carrier remains ordinary, and every composite binding proxy is hidden.
-A `utility` Layout must read back with no background, shape, or
-placeholder. Later slides may keep different slide-local geometry; only the reusable
+and order after packaging. The gate verifies that each carrier-bound slot owns the expected Slide binding, each composite visible carrier remains ordinary, and every composite binding proxy is hidden. A zero-slot Layout must read back with no placeholder. Later slides may keep different Slide-local geometry; only the reusable
Layout frame is checked against the explicit/prototype contract. Any mismatch
fails export without replacing the requested output.
-This gate applies to structured baseline and `template`; unmapped baseline,
-`preserve`, and `flat` retain their existing behavior.
**Static structure consistency**: Repeat the same master element ids on every
slide and the same layout element ids on every slide sharing a layout. Their
generated OOXML must be identical within the affected master/layout group.
-Static structure may carry shapes, text, or images; non-image/external
-relationships are rejected. A full-canvas first rect/group may be marked as a
-master or layout background.
+Static structure may carry shapes, text, or images; non-image/external relationships are rejected. Every static object is atomic; a `<g data-pptx-layer="master|layout">` is forbidden. A full-canvas first rect may be marked as a Master or Layout background.
-**Native object placeholders**: `chart` / `table` placeholders require
+**Native object slot carriers**: `chart` / `table` slots require
`--native-objects`; fallback groups contain several shapes and cannot map to one
PowerPoint placeholder. `object` is the generic PowerPoint content slot and
-must still resolve to one top-level DrawingML object. `media` currently binds
+uses either one carrier object or the explicit composite proxy downgrade. `media` currently binds
an authored image/crop to a native `media` placeholder; it does not synthesize
video or audio media from a decorative SVG group.
-### Legacy Preserved Source Master / Layout Contract
+### Legacy Structure Migration Boundary
-**Trigger**: An existing project already ships `native_structure.json` and `source_template.pptx`, has strict template adherence, and sets `pptx_structure.mode: preserve`. Current `create-template` output does not emit this pair; retain this contract only for backward compatibility.
+Existing 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 no root Master identity must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before generation or export.
-| Artifact | Authority |
-|---|---|
-| `source_template.pptx` | Original master/layout/theme/package parts |
-| `native_structure.json` | Stable layout keys, picker names, parent masters, placeholder types/indices, source SHA-256 |
-| `pptx_layouts` | Per-generated-page source layout selection |
-| SVG metadata | Standalone preview layers and slide-content placeholder binding |
-
-**Hard rule — source package wins**: Mark source master/layout visuals as direct `data-pptx-layer="master|layout"` preview children. Preserve export removes those generated copies and renders the original source parts. Unmarked content stays slide-local.
-
-**Placeholder identity**: Keep actual content on the slide. Copy the source placeholder index into `data-pptx-placeholder-idx` when present; the exporter restores the source placeholder type/idx pair. Imported `subTitle`, `obj`, `media`, and `dt` placeholders retain distinct `subtitle`, `object`, `media`, and `date` semantic roles instead of collapsing into body/other. Multiple placeholders with the same semantic role require explicit indices.
-
-**Multi-master boundary**: Preserve every source master already present in the package. Do not synthesize a new master merely for cover/section differences; rebuilt templates continue to prefer one master plus semantic layouts.
-
-```xml
-<svg xmlns="http://www.w3.org/2000/svg"
- viewBox="0 0 1280 720"
- data-pptx-layout="content"
- data-pptx-layout-name="Title and Content">
- <rect id="master-bg" data-pptx-layer="master"
- data-pptx-editable="false"
- width="1280" height="720" fill="#F8FAFC"/>
- <rect id="content-bg" data-pptx-layer="layout"
- data-pptx-editable="false"
- width="1280" height="720" fill="#FFFFFF"/>
- <g id="content-rule" data-pptx-layer="layout"
- data-pptx-editable="false">
- <line x1="48" y1="96" x2="1232" y2="96"
- stroke="#CBD5E1" stroke-width="2"/>
- </g>
- <text id="page-title" data-pptx-placeholder="title"
- data-pptx-placeholder-bounds="80 112 1120 72"
- x="80" y="158" font-size="40">Actual page title</text>
- <image id="hero-image" data-pptx-placeholder="picture"
- data-pptx-placeholder-bounds="680 210 480 320"
- x="680" y="210" width="480" height="320"
- href="../images/hero.png"/>
-</svg>
-```
+When original PPTX/native facts exist, migration preserves the source Master roster, Layout parent relationships and picker names, placeholder type/index/bounds, and visible supported geometry. Source Master/Layout groups are recursively flattened into atomic SVG elements. 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 a5732e64..4eb7bfdf 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -100,13 +100,13 @@ Write the locked value to `spec_lock.md` `- visual_style:` and the rationale to
> **Template vs preset**: a style mention may sound like a template name ("academic style" vs the `academic_defense/` template directory). Step 3 only triggers on an explicit template directory path supplied by the user — bare names and style words never copy templates; they map to a visual-style preset here. If a template was triggered upstream, its files are already in `<project_path>/templates/` and its fused design_spec governs.
-**Legacy native contract**: When `<project_path>/templates/native_structure.json` exists, treat it as backward-compatible `preserve` input only. Current templates declare their PowerPoint structure directly in the SVG roster.
+**Legacy template boundary**: A template containing `native_structure.json`, `source_template.pptx`, missing root Master identity, direct atomic placeholders, or old `baseline` / `preserve` / distillation metadata must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before Step 3. Do not plan against a legacy compatibility contract.
**Template adherence confirmation**: Surface this closed Stage-1 choice only when Step 3 loaded a `kind: deck` or `kind: layout` template. Omit it for free design and brand-only templates.
| Value | Planning and export behavior |
|---|---|
-| `strict` | Map every page to one template SVG. Keep its explicit Master/Layout/placeholder contract and output layout key unchanged. |
+| `strict` | Map every page to one template SVG. Keep its explicit Master/Layout/slot contract and output Layout key unchanged. |
| `adaptive` | Map every page to the closest template SVG. Keep the template Master contract, but allow a new explicit Layout key when the selected composition must adapt to the content. |
**Default — adaptive (may override when the user requests exact template use)**: Recommend `adaptive` when the user supplied only a template path with no stricter instruction. Preselect `strict` when the user explicitly asks to follow or preserve the template closely; the Stage-1 confirmation still records the final choice. Record the confirmed value in `design_spec.md §I` and as `template_adherence` under `spec_lock.md pptx_structure`.
@@ -845,19 +845,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 distilled, machine-readable short form of the color / typography / icon / image / **page_rhythm** / **page_layouts** / **page_charts** decisions above. Write `pptx_layouts` before generation only for legacy immediate-template or preserve routes; new baseline/template distillation writes it after the complete SVG pages exist. 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_layouts** / **page_charts** / **pptx_masters** / **pptx_layouts** decisions above. Master/Layout structure is part of this planning contract before the first SVG. 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**: Write `mode: baseline` for free design and brand-only routes. Do not add `layout_strategy` during baseline planning; the explicit [`distill-layouts`](../workflows/distill-layouts.md) workflow adds it only after the user selects completed pages. When a deck/layout template is confirmed, write `mode: template` and `template_adherence: strict|adaptive`. Add `layout_strategy: distill` after the template bounds preflight below. Use `mode: preserve` only when reopening a legacy strict project that already carries a validated `native_structure.json` + `source_template.pptx` pair. Do not choose `flat`; it is a CLI-only diagnostic override.
- - **Template bounds preflight**: Inspect every selected `page_layouts` SVG before finalizing the lock. If every placeholder has explicit `data-pptx-placeholder-bounds`, use deferred distillation for either adherence. Adaptive may also use deferred distillation with a legacy bounds-missing prototype because Distiller authors new design-zone bounds. If strict selects any bounds-missing prototype, use legacy immediate-template compatibility: omit `layout_strategy`, write the complete kindless `pptx_layouts` mapping from prototype key/name before generation, and emit one warning naming the legacy template pages. Do not silently convert strict to adaptive or derive strict bounds from sample text.
- - **pptx_layouts (native output Layout contract)**: Omit the whole section during planning for new baseline and distillation-capable template routes. The §IX `Layout` line describes visual composition intent only; it is not a final PowerPoint Layout key. Template `page_layouts` selects the input prototype; [`distill-layouts`](../workflows/distill-layouts.md) writes the output key/name/kind only from the completed SVG. Bounds-missing strict legacy templates, other immediate locks without `layout_strategy`, and preserve locks retain pre-generation mappings.
- - **Post-design reuse boundary**: Do not predict rich reusable Layouts from the outline. After visual construction, only [`distill-layouts`](../workflows/distill-layouts.md) may finalize the output contract. Baseline promotes user-selected pages and maps unselected pages to one utility Layout. Template strict restores the selected prototype's structure/bounds; adaptive retains its Master ids/topology/geometry and may distill an evolved Layout. Non-mirror skin continues to follow `spec_lock`. The exporter never discovers or clusters layouts itself.
- - **page_layouts (deck/layout templates only)**: Add one `P<NN>: <svg_basename>` row for every page. This is the complete input-prototype mapping. Strict later restores that SVG's structural Layout contract; adaptive keeps its Master structure and may evolve the Layout after the page is complete. Omit the whole section for free-design and brand-only routes.
+ - **pptx_structure is mandatory**: Every new project writes `mode: structured`. Free design and brand-only routes default to one Master; add another only when the design genuinely needs it. Deck/layout templates also record `template_adherence: strict|adaptive`. Do not write `baseline`, `template`, `preserve`, `flat`, `layout_strategy`, or Layout-kind rows into a new project.
+ - **Master roster**: Write one `pptx_masters` row per Master as `<master_key>: <picker name>`. For a template, copy the restored prototype roster. For free design, define stable deck-wide background/chrome atoms at planning time; Master visuals are root-level atomic elements and may never be `<g>`.
+ - **pptx_layouts (native 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. A Layout may intentionally have zero slots; never manufacture an empty `utility` kind or full-page fake slot.
+ - **Slot planning**: 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**: 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.
- **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 defers any new output Layout key until post-design distillation; strict mode must select an existing compatible Layout or revise the outline. Never omit `page_layouts` inside a new deck/layout template route.
+ - **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 a989f9d7..cb5445b1 100644
--- a/skills/ppt-master/references/template-designer.md
+++ b/skills/ppt-master/references/template-designer.md
@@ -14,7 +14,7 @@ Generate reusable page templates at the output scope confirmed by `create-templa
- **Output location**: `library` (default) → `skills/ppt-master/templates/<kind_dir>/<template_name>/`; `project` → the confirmed `<target_project>/templates/` root with no nested template-ID directory
- **Input**: finalized template brief (output scope, target project when project-scoped, template ID, display name, kind, applicable scenarios, tone, theme mode, canvas format, optional reference assets, accepted basic template norms)
-**Hard rule — scope is execution metadata**: Use `output_scope` and `target_project` to route files, but do not write either field into portable `design_spec.md` frontmatter. Do not create a new PPTX structure mode; deck/layout output still declares `native_structure_mode: template`.
+**Hard rule — scope is execution metadata**: Use `output_scope` and `target_project` to route files, but do not write either field into portable `design_spec.md` frontmatter. Do not create a new PPTX structure mode; deck/layout output declares `native_structure_mode: structured`.
**Project-scope precondition**: The workflow has already confirmed an initialized target project, an empty `<target_project>/templates/`, and collision-free destination filenames in `images/` and `icons/`. Do not begin final writes before that all-at-once preflight passes.
@@ -49,11 +49,11 @@ Input priority for PPTX-backed template creation:
7. `summary.md` only as a fast scan; never as the canonical fact source
8. screenshots / original PPTX only for style verification
-**Native structure output**: Always set `native_structure_mode: template`. Do not ship `native_structure.json` or `source_template.pptx`. Reconstruct one clean Master plus semantic Layouts through explicit SVG structure metadata. Every page remains a complete standalone SVG preview, and every retained source Layout is represented by at least one complete template page even when no source Slide used it. Mirror is the page-count exception: retain the Layouts referenced by source Slides, report unused source Layouts, and use fidelity when the full picker roster must be materialized.
+**Native structure output**: Always set `native_structure_mode: structured`. Do not ship `native_structure.json` or `source_template.pptx`. Reconstruct the source Master roster and Layout graph through explicit SVG metadata. Recursively flatten source Master/Layout groups into direct atomic elements while pushing supported transforms, styles, opacity, and paint order into each atom. Every page remains a complete standalone SVG preview, and every source Layout is represented by at least one complete template page even when no source Slide used it. Mirror is the page-count exception: report unused source Layouts that cannot be represented and use fidelity when the full picker roster must be materialized.
-**Downstream boundary**: The Strategist confirmation stage selects `strict` or `adaptive` when a project consumes this package. Both export through explicit template mode. Strict keeps the referenced Layout contract; adaptive may create a new Layout while retaining the template Master. Template_Designer does not preselect that project-level choice.
+**Downstream boundary**: The Strategist confirmation stage selects `strict` or `adaptive` when a project consumes this package. Both export through `pptx_structure.mode: structured`. Strict keeps the referenced Layout contract; adaptive may create a new Layout identity while retaining the template Master. Template_Designer does not preselect that project-level choice.
-When the source has a native Layout graph, `design_spec.md §V` must be followed by a `Source Layout Consolidation` table. Record every retained source Layout key/name and its output SVG plus rebuilt Layout key/picker name; if mirror cannot materialize an unused source Layout, record the explicit unused reason. This table is the audit artifact for consolidation and must not be replaced by prose such as “similar layouts merged.”
+When the source has a native Layout graph, `design_spec.md §V` must be followed by a `Source Structure Reconstruction` table. Record every source Master/Layout key/name, parent relationship, output SVG, and rebuilt key/picker name; if mirror cannot materialize an unused source Layout, record the explicit unsupported reason. Never silently merge, drop, or re-parent source structure.
---
@@ -110,7 +110,7 @@ When the brief sets `Replication mode: mirror`, preserve literal page appearance
- Visual source: `<import_workspace>/svg-flat/slide_NN.svg` (the self-contained "what PowerPoint shows" view). Structural source: `svg/master_*.svg`, `svg/layout_*.svg`, and `svg/inheritance.json`.
- Output: `<template_target>/<NNN>_<page_type>.svg`, where `<template_target>` is the library package directory or the project `templates/` root. `<NNN>` is the zero-padded source slide index (3 digits) and `<page_type>` is derived from `manifest.json` `pageTypeCandidates` — `cover` / `toc` / `chapter` / `content` / `ending`. When the page-type heuristic is ambiguous, fall back to `content`. Preserve source slide order via the numeric prefix.
-- Required metadata rewrite: declare the output Layout on the root, mark inherited Master/Layout visuals as direct preview layers, and map source content slots to semantic `data-pptx-placeholder` markers where the imported contract exposes them. Add `data-pptx-role` only to structural page-frame objects whose behavior is not already expressed by those specialized markers.
+- Required metadata rewrite: declare the output Master/Layout key and picker names on the root, mark inherited Master/Layout visuals as direct atomic elements, and map source content slots to top-level semantic slot groups where the imported contract exposes them. Add `data-pptx-role` only to structural page-frame objects whose behavior is not already expressed by specialized markers.
- Other allowed modifications: rewrite `<image href="...">` paths to local assets and rename assets semantically. Keep geometry, decoration, sprite-sheet wrappers, original example text, chart previews, and fonts visually unchanged.
- Forbidden: simplifying decorative complexity, merging similar slides, or dropping inherited preview chrome.
- `design_spec.md` §V Page Roster lists every emitted file with a one-line content-fit description; SVG metadata owns native reconstruction.
@@ -157,7 +157,7 @@ source_canvas_height: 720
source_viewbox: "0 0 1280 720"
replication_mode: standard | fidelity | mirror
# Required for every deck/layout template. Source packages remain analysis-only.
-native_structure_mode: template
+native_structure_mode: structured
# Optional — only when this template overrides canonical placeholder vocabulary.
# Omit only when the page truly exposes no replaceable content slots.
# placeholders:
@@ -188,7 +188,7 @@ native_structure_mode: template
## V. Page Roster
One row per emitted SVG describing what this template's version of cover / chapter / content / ending looks like (background treatment, decorative anchors, layout rhythm, image behavior, content density, intended content slot). Record the rebuilt Layout key and PowerPoint picker name. For `fidelity` mode, note the cluster source and visual differentiator. For `mirror` mode the roster is the load-bearing content-fit index, so each row must distinguish siblings by column count, hero element, density, and suitable content. Roster entries must match the actual SVG files on disk.
-For a source-derived native template, add `### Source Layout Consolidation` immediately after the roster with columns `Source Layout key/name`, `Output SVG`, `Rebuilt key/picker name`, and `Disposition`. Include one row for every retained source Layout, including consolidated and explicitly unused mirror Layouts.
+For a source-derived native template, add `### Source Structure Reconstruction` immediately after the roster with columns `Source Master/Layout key/name`, `Parent Master`, `Output SVG`, `Rebuilt key/picker name`, and `Disposition`. Include one row for every source Master/Layout, including explicitly unsupported mirror Layouts.
## VI. Assets (omit when none)
Logos, cover backgrounds, brand textures bundled with the template package — file name, dimensions, intended usage.
@@ -246,7 +246,7 @@ Do:
- use a background image asset when the original decorative layer is too complex to recreate cleanly
- use cleaned slide SVG references to inspect composition, spacing, text hierarchy, and fixed decorative structure only after factual metadata has been anchored
- read every reference SVG under `svg/` — `master_*.svg`, `layout_*.svg`, and every `slide_*.svg` regardless of slide count. Master / layout files describe the deck's shared visual language (read first); slide files describe per-page content (read after). Partial coverage drops template fidelity.
-- materialize every retained source Layout into at least one complete template page by composing its Master layer, Layout layer, placeholder contract, and an appropriate Slide sample. When several source Layouts consolidate into one semantic output Layout, record that mapping; never silently drop an unused source Layout.
+- materialize every source Layout into at least one complete template page by composing its parent Master atoms, Layout atoms, slot contract, and an appropriate Slide sample; never silently merge, drop, or re-parent source structure.
- rename adopted assets to semantic names (`cover_bg.png`, `brand_emblem.png`) rather than carrying raw `image3.png` into the final template
Do not:
@@ -258,17 +258,17 @@ Do not:
| Rebuilt fact | Template SVG declaration |
|---|---|
-| Output semantic layout | Root `data-pptx-layout` + stable `data-pptx-layout-name` |
-| Rebuilt master/layout visual | Direct preview child with `data-pptx-layer="master|layout"` and `data-pptx-editable="false"` |
-| Semantic content slot | Direct content child with `data-pptx-placeholder` and explicit `data-pptx-placeholder-bounds`; add `data-pptx-placeholder-idx` when same-role slots require stable disambiguation |
+| Output semantic Master/Layout | Root `data-pptx-master` / `data-pptx-master-name` plus `data-pptx-layout` / `data-pptx-layout-name` |
+| Rebuilt Master/Layout visual | Direct atomic child with `data-pptx-layer="master|layout"` and `data-pptx-editable="false"`; `<g>` is forbidden for either layer |
+| Semantic content slot | Direct `<g id>` with `data-pptx-placeholder` and explicit `data-pptx-placeholder-bounds`; exactly one compatible direct child carries `data-pptx-placeholder-carrier="true"` |
| Page-only background | Direct full-canvas solid rect with `data-pptx-layer="slide"` |
| Structural page-frame hint | Optional `data-pptx-role` only when background/decoration/header/footer/logo/watermark/chrome/page-number behavior is not already expressed by layer/placeholder metadata; stable unique `id` required |
Repeat inherited visuals in every standalone SVG so browser preview remains complete. Template export validates their equality, moves one copy into the generated Master/Layout parts, and removes the repeated Slide copies. Do not flatten inherited visuals into unmarked slide content.
-**Forbidden — deck-instance Layout kind**: Do not carry `data-pptx-layout-kind="distilled|utility"` into a reusable template package. The package owns a pre-authored prototype; downstream completed pages receive their final kind during post-design distillation.
+**Forbidden — legacy structure contract**: Do not carry `data-pptx-layout-kind`, `distilled`, `utility`, unmapped `baseline`, `preserve`, or direct atomic placeholders into a reusable template package. Route that source through [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) first.
-**Composite distilled-source boundary**: When Type B input contains a final distilled top-level group marked as an `object` region proxy, do not copy that marker into the reusable package. Preserve the group as the standalone visual sample, remove its placeholder attributes, and add a separate direct atomic `rect` placeholder proxy at the same design-zone bounds with `fill="none" stroke="none"`. Give that proxy a stable semantic id/type/index. Composite group placeholders are final deck-instance metadata; template prototypes remain atomic.
+**Composite slot boundary**: A normal slot group has exactly one compatible direct carrier. Only a genuinely composite region may declare `data-pptx-placeholder="object"` with `data-pptx-placeholder-binding="proxy"`; the visible group stays Slide-local and export creates a hidden transparent binding proxy. Do not use proxy binding as the default template slot form.
Use the imported placeholder types verbatim: `title`, `subtitle`, `body`,
`picture`, `chart`, `table`, `object`, `media`, `date`, `footer`, and
@@ -277,7 +277,7 @@ Use the imported placeholder types verbatim: `title`, `subtitle`, `body`,
title normally has no index. Assign stable indices only when repeated roles need
disambiguation inside the rebuilt Layout.
-**Hard rule — explicit design-zone bounds**: Every placeholder in a newly created template carries `data-pptx-placeholder-bounds="x y width height"`. For imported placeholders, use the source Layout geometry from `manifest.json` / `native_structure.json`. For new or consolidated slots, use the intended safe area, column, panel inset, or media frame. Do not use character count, glyph width, current wrapping, or the tight sample-content box.
+**Hard rule — explicit design-zone bounds**: Every slot in a newly created template carries `data-pptx-placeholder-bounds="x y width height"`. For imported slots, use the source Layout geometry from `manifest.json` / `native_structure.json`. For new slots, use the intended safe area, column, panel inset, or media frame. Do not use character count, glyph width, current wrapping, or the tight sample-content box. A Layout may intentionally have zero slots.
### 3. Placeholder Markers
@@ -286,20 +286,24 @@ disambiguation inside the rebuilt Layout.
Use clear placeholder markers for replaceable content:
```xml
-<!-- Text placeholder -->
-<text id="title-slot" data-pptx-placeholder="title"
- data-pptx-placeholder-bounds="80 280 1120 96"
- x="80" y="320" fill="#FFFFFF" font-size="48" font-weight="bold">
- {{TITLE}}
-</text>
+<!-- Text slot -->
+<g id="title-slot" data-pptx-placeholder="title"
+ data-pptx-placeholder-bounds="80 280 1120 96">
+ <text id="title-carrier" data-pptx-placeholder-carrier="true"
+ x="80" y="320" fill="#FFFFFF" font-size="48" font-weight="bold">
+ {{TITLE}}
+ </text>
+</g>
<!-- Content area placeholder (content page only) -->
<rect x="40" y="90" width="1200" height="550" fill="#FFFFFF" rx="8"/>
-<text id="body-slot" data-pptx-placeholder="body"
- data-pptx-placeholder-bounds="40 90 1200 550"
- x="640" y="365" text-anchor="middle" fill="#CBD5E1" font-size="16">
- {{CONTENT_AREA}}
-</text>
+<g id="body-slot" data-pptx-placeholder="body"
+ data-pptx-placeholder-bounds="40 90 1200 550">
+ <text id="body-carrier" data-pptx-placeholder-carrier="true"
+ x="640" y="365" text-anchor="middle" fill="#CBD5E1" font-size="16">
+ {{CONTENT_AREA}}
+ </text>
+</g>
```
### 4. Placeholder Reference (canonical convention, overridable per template)
@@ -432,7 +436,7 @@ If the template is based on PPTX import output, briefly note:
- which extracted assets were reused directly
- which complex original decorations were intentionally simplified
- whether any page-type mapping required judgment beyond the import heuristic
-- how the source Master/Layout graph was consolidated into the rebuilt Master and semantic Layout roster
+- how the source Master/Layout graph was reconstructed, including group flattening and any explicitly unsupported source structures
---
@@ -475,7 +479,7 @@ templates/
- [x] Naming convention applied (standard / fidelity: letter-suffix variants; mirror: `<NNN>_<page_type>.svg`)
- [x] Templates follow design spec (colors, fonts, layout)
- [x] Placeholder markers are clear and standardized; every slot has explicit design-zone bounds; mirror may keep literal text but still maps imported semantic slots
-- [x] Every SVG is a complete preview with explicit Master/Layout/Slide/placeholder metadata and `native_structure_mode: template`; retained source Layouts are materialized, or mirror reports unused Layouts explicitly
+- [x] Every SVG is a complete preview with explicit root Master/Layout identity, atomic Master/Layout elements, grouped slot/carrier metadata, and `native_structure_mode: structured`; source Layouts are materialized, or mirror reports unsupported Layouts explicitly
- [x] Project scope, when selected: bitmaps routed to `images/`; extracted icons copied to both `templates/icons/` and runtime `icons/`
- [ ] **Next step**: Validate assets; register only library scope, otherwise hand the in-place project bundle to main Step 3
```
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 2cb16f3f..22cd0dd2 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -132,11 +132,13 @@ 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` defaults to `baseline`. Free-design/brand-only projects initially omit `pptx_layouts`, keep all actual content Slide-local, and use the compatibility pass: exact z-order-safe shared background/chrome promotion plus coarse root `data-pptx-page-role` families, with filename/id fallbacks. If the user later selects completed pages for reuse, [`distill-layouts`](../workflows/distill-layouts.md) writes one complete mapping: selected pages use explicit `distilled` Layout contracts and unselected pages share an empty `utility` Layout. The exporter compiles only those declarations, validates the finished package, and performs no visual-similarity inference. Baseline also prunes unused layouts and maps locked typography/colors into the PowerPoint theme. Use `--pptx-structure flat` for slide-local diagnostics.
+Native `svg_to_pptx.py` release export uses the project's `structured` lock. Every project supplies a complete Master roster and page-to-Master/Layout mapping before SVG generation. Every SVG root repeats that identity; fixed Master/Layout visuals are direct atomic children, and 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.
-Post-design distilled baseline and distillation-capable deck/layout template routes use the same explicit Layout compiler. A distillation-capable template project selects complete input prototypes in `page_layouts` and defers `pptx_layouts` until every visible SVG page exists. Deferred strict output must match prototype key/name, Master/Layout structure, and placeholder bounds; adaptive must keep Master ids/topology/geometry and may finalize an evolved Layout or author new design-zone bounds for a legacy prototype. Adaptive can reuse the prototype key/name only when that Layout contract is unchanged; evolution receives a new identity. A bounds-missing strict legacy selection instead keeps the complete kindless immediate-template mapping and skips post-design distillation. Non-mirror skin remains project-controlled, while mirror reuses literal visual styling and permits only visible text replacement under an unchanged identity. Every distilled placeholder supplies explicit design-zone bounds independent of current Slide geometry. Atomic carriers retain matching Slide bindings; a final distilled composite object region stays ordinary and receives a hidden transparent binding proxy. The exporter validates prototype and cross-slide contracts, creates one reusable Layout per key, removes repeated inherited copies, and reads the finished package back to verify static/carrier rosters, backgrounds, placeholder identities, proxies, and default bounds.
+The exporter compiles only this 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. Use `--pptx-structure flat` only for diagnostics.
-Current `create-template` output always rebuilds explicit SVG structure and does not package `native_structure.json` or `source_template.pptx`. `preserve` remains available only for existing projects that already carry the legacy pair.
+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. Current `create-template` reconstructs source Master/Layout topology and flattens source structural groups into atoms; the original PPTX remains analysis input.
+
+Legacy `baseline`, `template`, `preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, and missing root Master identity must run [`restore-pptx-structure`](../workflows/restore-pptx-structure.md) before release export.
`pptx_to_svg.py` annotates verified text-grid tables and conservative chart data with `data-pptx-native` metadata. Table import covers exact physical row/grid topology, canonical rectangular merges, safe solid/no-fill per-side borders, plain multi-paragraph cells, and a closed run-rich paragraph schema. Each rich run requires `text` and may use only `bold`, `italic`, `underline`, `strike`, `color`, `font_size`, one `font_family`, `lang`, and `alt_lang`. A merge must use the exact `rowSpan` / `gridSpan` / `hMerge` / `vMerge` physical topology with empty merge slaves. Presentation-only source run XML normalizes, while relationship-bearing text, extensions, line breaks, fields, tabs, bullets, broken text topology, unsafe border XML, non-solid fills, and other merge encodings remain fallback-only. For table style `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}`, the normalized SVG fallback resolves `wholeTbl`, `firstRow`, horizontal banding, theme colors/fonts, and direct cell/run overrides; other built-in/custom style families are not implied.
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 00fc06a2..afa042e5 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -35,8 +35,7 @@ Convert project SVGs into PPTX.
```bash
python3 scripts/svg_to_pptx.py <project_path>
python3 scripts/svg_to_pptx.py <project_path> --native-objects
-python3 scripts/svg_to_pptx.py <project_path> --pptx-structure template # explicit SVG template metadata
-python3 scripts/svg_to_pptx.py <project_path> --pptx-structure preserve # imported source package contract
+python3 scripts/svg_to_pptx.py <project_path> --pptx-structure structured # current release structure
python3 scripts/svg_to_pptx.py <project_path> --pptx-structure flat # structure diagnostic
# Template-import visual round-trip diagnostic only:
python3 scripts/svg_to_pptx.py <template_import_output> -s svg-flat
@@ -71,12 +70,12 @@ Behavior:
inputs and package-level processing.
- For PPTX template-import workspaces, use `-s svg-flat` when you need a visual round-trip check. The layered `svg/` tree is the machine-readable template source and intentionally does not inline inherited master / layout decoration into each slide.
- Native mode is strict about unsupported visual SVG elements: if a visual element cannot be represented or safely preserved, export fails with the SVG file, element tag, and position instead of silently dropping content.
-- Omitting `--pptx-structure` reads `spec_lock.md` and falls back to `baseline`. Free-design baseline projects initially omit `pptx_layouts` and use the coarse root `data-pptx-page-role` family pass plus conservative background/chrome promotion. After explicit user page selection, `distill-layouts` writes one complete mapping with `distilled` contracts for selected pages and one empty `utility` Layout for unselected pages. Distillation-capable template projects also defer `pptx_layouts`: `page_layouts` selects the complete input SVG prototype, and post-design distillation writes `distilled` rows for every page. Deferred strict compares prototype structure/bounds; adaptive compares Master ids/topology/geometry and may author new design-zone bounds. A strict legacy selection with any bounds-missing prototype instead omits `layout_strategy` and uses a complete kindless immediate mapping. Non-mirror paint and typography follow `spec_lock`. Pending or partial distillation is blocked from export. No route infers visual similarity.
-- Template/preserve placeholder semantics distinguish title, subtitle, body, picture, chart, table, generic object, media, date, footer, and slide number. Reconstructed titles are normally type-matched without an index; explicit imported title indices and all other source indices are retained. Imported `subTitle`, `obj`, `media`, and `dt` identities remain distinct through `manifest.json`, `native_structure.json`, Layout XML, and Slide XML.
-- Baseline/template native export reads `spec_lock.md` typography into the PowerPoint theme: `title_family` becomes the major font and `body_family` / `font_family` becomes the minor font. Matching SVG text emits `+mj-*` / `+mn-*` tokens, while unrelated emphasis/code/brand families stay concrete. Preserve mode keeps the imported source theme; flat mode keeps fixed-font diagnostic output.
-- Structured baseline and template mode require numeric `typography.title` and `typography.body` rows. They write the title size to every Master `p:titleStyle` level and the body size to every `p:bodyStyle` / `p:otherStyle` level. Each generated Layout text placeholder also stores the prototype's first direct run size in `a:lstStyle/a:lvl1pPr/a:defRPr@sz` while retaining its prompt run size. Slide direct-run sizes remain unchanged. Missing title/body rows fail explicit Layout export; legacy baseline, preserve, and flat do not apply these updates.
-- Baseline/template native export also maps canonical `spec_lock.md` color roles into the PowerPoint color scheme and emits context-safe `schemeClr` tokens for exact matches in SVG fills/text/strokes, gradients/patterns/bullets, native tables, and native-chart accent series. Local colors, inverse white/black, and effects stay concrete. Preserve mode keeps the imported source color scheme; flat mode keeps fixed-color diagnostic output.
-- Preserve mode is legacy strict-only compatibility for existing projects that already carry `native_structure.json` + `source_template.pptx`. Current template creation does not emit the pair.
+- Omitting `--pptx-structure` reads `spec_lock.md`; release export requires `mode: structured`. The lock must include a complete `pptx_masters` roster and one `pptx_layouts` row per page. `flat` is diagnostic-only.
+- Every page root repeats Master/Layout keys and picker names. Master/Layout fixed visuals are direct atomic children; layer `<g>` elements are invalid.
+- 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.
+- Structured export maps locked typography/colors into PowerPoint Master/Layout/theme defaults, 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.
+- Template `page_layouts` remains input provenance. Strict preserves the prototype contract; adaptive retains its Master and may use a new Layout identity only when fixed Layout atoms or slot topology/bounds change.
+- Legacy `baseline`, `template`, `preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, and missing Master identity are rejected with a pointer to [`restore-pptx-structure`](../../workflows/restore-pptx-structure.md). Export never migrates or infers them.
- Native output uses content-hash media filenames, so identical images are reused and different images cannot overwrite each other by sharing a basename.
- `[Content_Types].xml` is generated from the actual media extensions written into the PPTX. Unknown media extensions fail unless Python's `mimetypes` can identify them.
- Native export writes to a temporary file first and publishes the requested PPTX only after conversion succeeds. A failed conversion does not replace the main output file.
@@ -95,7 +94,7 @@ Behavior:
- Long-audio import and automatic long-audio splitting are not supported; keep narration assets page-level
- Voice choices can be listed with `python3 scripts/notes_to_audio.py --list-common-voices`, `python3 scripts/notes_to_audio.py --list-voices --locale zh-CN`, or provider-specific `--provider <name> --list-voices`
- Page transitions are controlled by `-t/--transition`; per-element entrance animations are controlled by `-a/--animation`
-- Per-element animation applies to top-level SVG `<g id="...">` groups in z-order; aim for 3–8 content groups per slide. Existing layer/slide-number placeholder semantics are read before minimal structural roles; exact id tokens remain a fallback only when all explicit markers are absent
+- Per-element animation applies to ordinary top-level SVG `<g id="...">` groups in z-order; aim for 3–8 Slide-local content groups per slide. Master/Layout atoms and slot groups are structural and excluded; exact id tokens remain a fallback only when explicit structural roles are absent
- An explicit `animations.json` group entry may override the marker-free legacy chrome-name heuristic. It cannot override `data-pptx-layer` or an explicit static role/placeholder marker
- Start mode is set by `--animation-trigger`, mirroring PowerPoint's Start dropdown: `after-previous` (default, cascade with `--animation-stagger` spacing on slide entry), `on-click` (presenter-paced), `with-previous` (all together on slide entry)
- `on-click` is for live presentations only; recorded narration rejects it because the tool does not generate object-level click timings
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index 1ad9836e..3438a601 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -306,7 +306,7 @@ Catalog read: 76 templates
## IX. Content Outline
-> **Native Layout boundary**: Each `Layout` line below describes visual composition intent, not a final PowerPoint Layout key. Free-design/brand-only pages stay unconstrained during SVG authoring. Template pages select an input prototype through `page_layouts`. Distillation-capable template routes defer the final output mapping, and [`distill-layouts`](../workflows/distill-layouts.md) writes reusable native Layouts only from completed pages. A strict legacy selection whose prototype lacks explicit placeholder bounds instead uses the Strategist's planning-time kindless immediate mapping and does not enter deferred distillation.
+> **Native Layout boundary**: Each `Layout` line below describes visual composition intent and feeds the planning-time structured mapping. Before SVG generation, Strategist writes the Master roster and exactly one `<master_key> | <layout_key> | <PowerPoint layout name>` row per page. Free-design/brand-only pages use that structure from their first draft; template pages also select 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.
### Part 1: [Chapter Name]
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index 9e42c10d..b0bee0b8 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -37,7 +37,7 @@
> Strategist: fill only colors actually used. Add extra rows as needed; delete unused rows rather than leave as `#......`.
>
-> **PowerPoint theme roles.** Native `baseline` / `template` export maps `bg` / `background` / `master_bg` → `lt1`, `secondary_bg` / `bg_secondary` → `lt2`, `text` / `body_text` → `dk1`, `text_secondary` → `dk2`, `primary` → `accent1`, `accent` → `accent2`, `secondary_accent` → `accent3`, and `border` → `accent4`. The first two additional non-black/non-white roles become `accent5` / `accent6`; remaining colors stay fixed. Mapping is usage-aware, so a background HEX is not automatically reused for inverse text. Preserve mode keeps the imported source theme; flat mode keeps concrete colors for diagnostics.
+> **PowerPoint theme roles.** Structured export maps `bg` / `background` / `master_bg` → `lt1`, `secondary_bg` / `bg_secondary` → `lt2`, `text` / `body_text` → `dk1`, `text_secondary` → `dk2`, `primary` → `accent1`, `accent` → `accent2`, `secondary_accent` → `accent3`, and `border` → `accent4`. The first two additional non-black/non-white roles become `accent5` / `accent6`; remaining colors stay fixed. Mapping is usage-aware, so a background HEX is not automatically reused for inverse text.
>
> **`image_rendering` and `image_palette`** — required only when `images` section below contains `ai`-sourced files. Values MUST be valid names from `references/image-renderings/_index.md` and `references/image-palettes/_index.md`, **or** the literal string `custom`. Image_Generator reads these and applies them deck-wide. Omit both rows when the deck has no AI-generated images.
>
@@ -75,9 +75,9 @@
>
> **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.
>
-> **Explicit Layout Master defaults**: `pptx_structure.mode: template` and a structured baseline after Layout distillation both require unitless `title` and `body`. Native export writes `title` into every Master `titleStyle` default and `body` into every `bodyStyle` / `otherStyle` default, changing only `a:defRPr@sz`. Direct page-run sizes and role-specific Layout placeholder prototype sizes remain unchanged. Unmapped baseline, `preserve`, and `flat` do not rewrite Master text-style sizes.
+> **Structured Master defaults**: `pptx_structure.mode: structured` requires unitless `title` and `body`. Native export writes `title` into every Master `titleStyle` default and `body` into every `bodyStyle` / `otherStyle` default, changing only `a:defRPr@sz`. Direct page-run sizes and role-specific Layout placeholder prototype sizes remain unchanged.
>
-> **⚠️ PPT-safe stack discipline (HARD rule).** Native `baseline` / `template` export maps `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. `preserve` keeps the source template theme; `flat` keeps concrete fonts for diagnostics.
+> **⚠️ PPT-safe stack discipline (HARD rule).** Structured export maps `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.
>
> **Stack length discipline.** 3-4 fonts per stack is the sweet spot. Converter only writes the **first** Latin and **first** CJK font into PPTX — everything after is silently dropped. macOS-only families (`Songti SC`, `Menlo`, `Monaco`, `Helvetica`) are auto-mapped to Windows equivalents via `FONT_FALLBACK_WIN` (see `scripts/svg_to_pptx/drawingml/utils.py`); stacking both is redundant. Lead with Windows-preinstalled fonts (`Microsoft YaHei` / `SimSun` / `Arial` / `Georgia` / `Consolas`); keep at most **one** macOS-exclusive family (typically `"PingFang SC"`) as a browser-preview nicety.
@@ -125,70 +125,54 @@
> **Missing or empty section** → Executor falls back to `dense` for every page (legacy pre-rhythm behavior). Remove the section only for legacy decks; new decks MUST fill it.
## pptx_structure
-- mode: baseline
+- mode: structured
-> One deck-wide native PowerPoint structure policy. New projects always include this section.
+> One deck-wide native PowerPoint structure policy. New projects always use `structured`; Master/Layout structure exists before the first SVG is drawn.
>
> When Step 3 loaded a deck/layout template, add exactly one of:
> ```
> - template_adherence: adaptive
> - template_adherence: strict
> ```
-> Omit the row for free design and brand-only templates. Both values require one `page_layouts` row per page in new projects. Add `- layout_strategy: distill` and omit `pptx_layouts` until every complete SVG page exists, except when strict uses a legacy template page whose placeholder bounds are missing. That compatibility case omits the strategy and writes the complete kindless output mapping before generation. Adaptive may still distill new design-zone bounds.
+> Omit the row for free design and brand-only templates. Both values require one `page_layouts` row per page. 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.
>
-> New template example:
+> Template example:
> ```
-> - mode: template
+> - mode: structured
> - template_adherence: adaptive
-> - layout_strategy: distill
-> ```
->
-> - `baseline` — default for free design and brand-only routes. During visual construction, omit `pptx_layouts` and explicit root Layout/layer/placeholder metadata so the page composition remains unconstrained. Baseline compatibility export remains available until the user explicitly runs [`distill-layouts`](../workflows/distill-layouts.md).
-> - `template` — required whenever Step 3 loaded a deck/layout template. Distillation-capable projects pair it with `layout_strategy: distill`, a complete `page_layouts` input mapping, and no planning-time `pptx_layouts`. Bounds-missing strict legacy prototypes and existing locks without a strategy retain immediate/pre-authored mappings.
-> - `preserve` — legacy strict-only compatibility for an existing project that already ships `native_structure.json` + `source_template.pptx`. Do not select it for newly created templates.
-> - `flat` — diagnostic escape hatch. Do not lock this in a normal project; pass it on the CLI when comparing slide-local output.
->
-> **Post-design distillation**: Baseline adds `- layout_strategy: distill` only after the user selects completed pages. A distillation-capable template route locks the strategy during planning but defers the whole `pptx_layouts` section. [`distill-layouts`](../workflows/distill-layouts.md) writes the complete final mapping and matching root kind after visual generation. Export rejects the pending or partial state. Strict legacy immediate compatibility skips this state.
->
-> Preserve example:
-> ```
-> - mode: preserve
-> - template_adherence: strict
-> - source_template: templates/source_template.pptx
-> - native_structure: templates/native_structure.json
> ```
+## pptx_masters
+- master-default: Default Master
+
+> One row per Master: `<master_key>: <PowerPoint picker name>`. Free design defaults to one Master. Add another only when the design genuinely needs it or the source PPTX carries multiple Masters. Keys are deck-unique and stable.
+
## pptx_layouts
+- P01: master-default | cover-visual | Cover Visual
+- P02: master-default | content-two-column | Two Column
-> Distillation-capable template projects and free-design/brand-only baseline projects omit this section during visual generation. [`distill-layouts`](../workflows/distill-layouts.md) writes it only from completed SVG pages. Bounds-missing strict legacy templates, other immediate locks without `layout_strategy`, and preserve locks retain pre-authored rows.
->
-> Legacy template/preserve value format: `<layout_key> | <PowerPoint layout name>`. Post-design distillation adds one final kind segment: `<layout_key> | <PowerPoint layout name> | <layout_kind>`. Baseline accepts `distilled` or `utility`; template distillation requires `distilled` on every page.
+> Include exactly one row per page before SVG generation. Value format: `<master_key> | <layout_key> | <PowerPoint layout name>`.
>
-> Distilled baseline example:
-> ```
-> - P01: freeform-unselected | Freeform | utility
-> - P02: editorial-visual | Editorial Visual | distilled
-> - P03: freeform-unselected | Freeform | utility
-> ```
+> 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.
>
-> **Distilled Layout**: `distilled` means a completed page supplied the final reusable contract. Baseline uses user-selected pages; template routes use every `page_layouts` prototype under strict/adaptive rules. Every placeholder carries explicit `data-pptx-placeholder-bounds` derived from its design zone, never from text length or glyph bounds. The same Layout may serve Slides with different local proportions; bounds define only the reusable default.
+> 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.
>
-> **Utility Layout**: `utility` is the single empty `freeform-unselected` Layout for unselected baseline pages. It is forbidden in template distillation because every template page has an input prototype.
+> 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.
>
-> **All-or-none final state**: Once distillation starts, include exactly one row per generated page and matching `data-pptx-layout` / name / kind on every SVG root. Partial mappings are invalid.
+> 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_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, not the final native Layout mapping. Strict restores its structural contract and bounds after design; adaptive retains its Master ids/topology/geometry and may output a new Layout contract. 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 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.
>
> **No entry for a page** is valid only when the entire route is free design or brand-only. It is an error in template mode.
>
> **Hard rule**: Use both `page_layouts` and `page_charts` only with a compatible shell. Adaptive mode may start from a neutral content template and finalize a new explicit Layout after design; strict mode must choose an existing compatible Layout or revise the outline.
>
-> **Whole section omitted** → free design or brand-only route, except for an already-existing legacy immediate-template project that predates explicit prototype mapping. New template strict/adaptive routes require complete `page_layouts`. On a distillation-capable route, `pptx_layouts` appears only after post-design distillation; a bounds-missing strict legacy selection instead writes the complete kindless mapping during planning.
+> **Whole section omitted** → free design or brand-only route. Template strict/adaptive routes require complete `page_layouts`. A legacy package that cannot satisfy the current structured contract must migrate before use; it never enters a compatibility branch inside normal generation.
>
> **Strategist source**: record each project-page choice in project `design_spec.md §IX Content Outline`, using the copied template package's `templates/design_spec.md §V Page Roster` descriptions as the roster authority. Basenames must match files in `templates/` exactly. A typo is a blocking contract error: stop before drawing and report it; never fall back to free design inside template mode.
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index 45f4bd91..b88f1088 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -70,9 +70,9 @@ Branch by the type of reference source the user supplied. This step produces ana
`fidelity` and `mirror` are not available for type C / D — visual references and verbal-only briefs cannot drive page-by-page replication. Type A is the canonical path: `manifest.json` page-type candidates and the layered `svg/` workspace anchor cluster detection (fidelity) and verbatim copy (mirror) with factual data. Type B is supported with caveats:
- **mirror on type B** — direct 1:1 copy. B's SVGs are already self-contained (one file per page, equivalent to `svg-flat/slide_*.svg`). Page-type for the `<NNN>_<page_type>.svg` filename is read from the source filename when it follows the PPT Master naming convention (`01_cover.svg` → `cover`, `03a_content_two_col.svg` → `content`); fall back to `content` otherwise. Particularly natural when the source is `templates/layouts/<existing>` and the user wants to fork an existing template.
-- **fidelity on type B** — inspect root `data-pptx-layout`, direct Master/Layout/placeholder metadata, and companion `spec_lock.md` first. When a complete explicit contract exists, its keys and `pptx_layouts` families are authoritative; preserve them instead of visual re-clustering. Strip deck-instance `data-pptx-layout-kind` when rebuilding the reusable template prototype, while retaining key/name/layers/placeholders/bounds. If the input is an existing template, use its metadata and variant filenames. Only fully unstructured SVG input falls back to AI visual clustering.
-- **distilled project on type B** — when the source `svg_output/` carries `data-pptx-layout-kind`, ingest only pages explicitly selected by the user or roots marked `distilled`. Skip every `utility` page; it is an empty mapping shell, not a reusable template design. Deduplicate repeated members by explicit Layout key/contract before rebuilding prototypes, then strip the deck-instance kind. A final distilled composite `<g data-pptx-placeholder="object">` is a deck-instance region proxy and cannot survive that stripping: keep the group as the complete visual sample, remove its placeholder attributes, and rebuild its bounds as a separate direct atomic no-fill/no-line object-slot proxy in the reusable template SVG.
-- **selected free-design subset on type B** — if a cross-project request names pages from an undistilled free-design project, return to [`distill-layouts`](./distill-layouts.md) first and distill exactly that source subset. Type B intake then receives only the selected `distilled` files. Do not scan or copy the whole `svg_output/` directory and silently turn unselected pages into template variants.
+- **fidelity on type B** — inspect root Master/Layout identities, direct atomic Master/Layout elements, top-level slot groups, and companion `spec_lock.md` first. When a complete current contract exists, its Master roster and `pptx_layouts` families are authoritative; preserve them instead of visual re-clustering. If the input is an existing template, use its metadata and variant filenames.
+- **legacy or unstructured type B** — old `baseline` / `preserve` / `layout_strategy: distill` / `data-pptx-layout-kind` / direct-atomic-placeholder inputs, and SVGs with no root Master identity, first run [`restore-pptx-structure`](./restore-pptx-structure.md). The restored contract is then the Type B input. Do not keep a second compatibility branch inside template creation.
+- **selected free-design subset on type B** — restore the named source pages into the current structured contract, then ingest only that explicit subset. Do not scan or copy the whole `svg_output/` directory and silently turn unselected pages into template variants.
**Replication mode boundary**: `standard` / `fidelity` / `mirror` are construction choices for this workflow only. They decide how the template package is created from the reference source; they do not create a downstream generation route, and `mirror` must not force future decks to preserve the source page count or page order.
@@ -159,7 +159,7 @@ Before composing Step 2, extract the template's reusable norms from the previous
| Density rhythm | title scale, content block count, whitespace balance, dense vs. breathing pages | Page-type guidance for Strategist / Executor |
| Page roster semantics | cover / TOC / chapter / content / ending variants and their intended content slots | `design_spec.md §V Page Roster` rows |
| Asset policy | source images / icons / textures that are part of the template vs. sample-only content | `design_spec.md §VI Assets` or omit sample-only assets |
-| Native PowerPoint structure | `native_structure.json` source facts, masters/layouts, picker names, placeholder type/index, source slide mapping | Rebuild one clean Master plus semantic Layouts in complete, explicitly annotated SVG pages. |
+| Native PowerPoint structure | `native_structure.json` source facts, masters/layouts, picker names, placeholder type/index, source slide mapping | Reconstruct the source Master roster and Layout graph in complete, explicitly annotated SVG pages; flatten source groups into atomic Master/Layout objects. |
Distinguish observed facts from template rules: "`slide_07` uses a left photo crop" is a fact; "content pages may use a left photo rail for location / product / case-study pages" is the reusable rule.
@@ -230,7 +230,7 @@ Compose a single message that surfaces every Required brief item to the user, **
| Theme mode | Recommended localized mode with English ID, plus available modes such as `light` / `dark` / `mixed` with localized explanations |
| Canvas format | Recommended canvas, plus other supported formats from [`canvas-formats.md`](../references/canvas-formats.md) that fit the source aspect ratio or user intent. Always show the concrete pixel size and `viewBox`; do not treat two same-ratio formats such as `ppt169` (`1280x720`) and `banner` (`1920x1080`) as interchangeable. |
| Replication mode | Recommended localized mode with English ID, plus all modes available for the current input type; list forbidden modes for type C / D as unavailable with localized reasons |
-| Native structure reconstruction | For type A, summarize the source master/layout graph from `native_structure.json`, then state the fixed output policy: rebuild one clean Master plus explicit semantic Layouts (`template`). The source package is analysis input only. |
+| Native structure reconstruction | For type A, summarize the source master/layout graph from `native_structure.json`, then state the fixed output policy: reconstruct every retained source Master/Layout identity through the current structured SVG contract. The source package is analysis input only. |
| Visual fidelity for fixed pages | Recommended localized choice with English ID, plus both `literal` / `adapted` options when applicable |
| Asset bundling | Recommended included assets, plus excluded candidate assets with a one-line reason when reference assets exist |
@@ -262,7 +262,7 @@ For type A, also include in this message:
- the exact cleaned `master_*.svg`, `layout_*.svg`, `slide_*.svg` filenames you read from the layered `svg/` view (proof of the hard read gate)
- a one-line summary of the master / layout structure you extracted
-- the source structure facts, including master/layout counts, multi-master status, and reason codes; state that the final package will rebuild one clean Master plus semantic Layouts
+- the source structure facts, including master/layout counts, multi-master status, and reason codes; state that the final package will reconstruct that topology through atomic Master/Layout objects and grouped slots
The user replies with corrections, additions, or "all good".
@@ -337,9 +337,9 @@ For type D, pass only the finalized brief.
The role uses the analysis bundle to anchor objective facts such as theme colors, fonts, reusable backgrounds, common branding assets, layout grammar, image-placement rules, density rhythm, and page-slot semantics, then rebuilds the final SVG templates in a simplified, maintainable form.
-**Native structure reconstruction**: Do not copy `native_structure.json` or `source_template.pptx` into the final template directory. Use their master/layout/placeholder facts to reconstruct one clean Master plus semantic Layouts through the explicit SVG metadata contract. Materialize at least one complete template page for every retained source Layout, including unused Layouts. Immediately below `design_spec.md §V Page Roster`, write a `Source Layout Consolidation` table with one row per retained source Layout: source key/name, output SVG, rebuilt key/picker name, or an explicit unused reason. Never silently drop or merge a source Layout. Mirror keeps its exact source-slide count, so report any unused source Layout that cannot be materialized and use fidelity instead when the full Layout picker roster is required. Every emitted SVG repeats the identical Master layer, the selected Layout layer, and semantic Slide placeholders so it remains a complete standalone preview.
+**Native structure reconstruction**: Do not copy `native_structure.json` or `source_template.pptx` into the final template directory. Use their Master/Layout/placeholder facts to reconstruct the full source topology through the current SVG contract. Preserve every source Master, every retained Layout and its parent Master, picker name, placeholder type/index/bounds, and unused Layout roster. Same-named Layouts under different Masters receive globally unique keys. Recursively flatten source Master/Layout groups: push supported transforms, styles, opacity, and paint order into direct atomic elements; do not emit a Master/Layout `<g>`. Materialize at least one complete template page for every retained source Layout, including unused Layouts. Immediately below `design_spec.md §V Page Roster`, write a `Source Structure Reconstruction` table with one row per source Master/Layout and its output key/page or explicit unsupported reason. Never silently drop, merge, or re-parent source structure. Mirror keeps its exact source-slide count, so report any unused source Layout that cannot be materialized and use fidelity instead when the full Layout picker roster is required. Every emitted SVG repeats the identical atomic Master contract, selected atomic Layout contract, and top-level semantic slot groups so it remains a complete standalone preview.
-Downstream, both template-adherence choices use `pptx_structure.mode: template` plus `layout_strategy: distill`. `page_layouts` selects one complete input prototype per page; `pptx_layouts` is omitted until the generated SVG pages are complete. Strict restores the prototype contract. Adaptive keeps the prototype Master structure and may distill a new Layout under a new key/name. Neither falls back to baseline inside a template deck. For mirror packages, reused Master/Layout identities retain literal visual styling in addition to structure; only visible text content may change.
+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 prototype contract. Adaptive keeps the prototype Master and may explicitly create a new Layout key/name while authoring the page that needs it. For mirror packages, reused Master/Layout identities retain literal visual styling in addition to structure; only visible text content may change.
**Apply the visual-fidelity decision from Step 3**: pages marked `literal` (typically cover / chapter / ending) must reproduce the reference's geometry, decoration, and sprite-sheet crops as-is — "simplified, maintainable form" applies only to genuinely redundant structure, not to load-bearing layout. Pages marked `adapted` may use the reference for tone and structural rhythm but evolve the design.
@@ -347,7 +347,7 @@ Downstream, both template-adherence choices use `pptx_structure.mode: template`
**Mirror-mode override** (type A or B): when `Replication mode: mirror`, this step is a **verbatim copy** rather than a reconstruction. The Template_Designer role:
-1. **Copies the cleaned source pages** into the template directory with literal visual fidelity — no content rewriting or decorative simplification. Then annotate the complete page with root Layout identity plus direct Master/Layout/placeholder metadata derived from the layered source. Remove any deck-instance `data-pptx-layout-kind`; it is rendering-neutral and does not belong to the reusable prototype. The SVG remains visually identical when opened alone, while export can deterministically reconstruct native structure.
+1. **Copies the cleaned source pages** into the template directory with literal visual fidelity — no content rewriting or decorative simplification. Then annotate the complete page with root Master/Layout identity, direct atomic Master/Layout elements, and top-level slot groups derived from the layered source. Recursively flatten source Master/Layout groups while preserving supported appearance and paint order. The SVG remains visually identical when opened alone, while export can deterministically reconstruct native structure.
- Type A: source is the cleaned flat `<import_workspace>/svg-flat/slide_NN.svg`
- Type B: source is each cleaned `*.svg` in the analysis workspace when extraction ran; otherwise each `*.svg` in the input directory (already self-contained)
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`.
@@ -368,7 +368,7 @@ Mirror mode does not simplify the visual page, but it still reconstructs layer o
1. `design_spec.md` — **personality only**. Required sections: Template Overview, Color Scheme, Signature Design Elements, Page Roster (matching the actual SVG files on disk). Skip Typography / Assets / Placeholder Overrides when they would just restate defaults. Declare 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 `data-pptx-layout` / `data-pptx-layout-name`, direct Master/Layout layers, and direct semantic `data-pptx-placeholder` markers with explicit design-zone bounds. Minimal structural `data-pptx-role` hints are added only when those specialized markers cannot express required behavior. Both strict and adaptive downstream set `mode: template`, require complete `page_layouts`, and defer `pptx_layouts` until post-design distillation.
+ - `{{...}}` 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.
4. Template assets (optional) — library scope bundles Logos / PNG / JPG / reference SVG inside the package; project scope applies the `templates/` / `images/` / dual-icon routing defined above
---
@@ -398,9 +398,9 @@ python3 skills/ppt-master/scripts/svg_quality_checker.py "<template_target>" --t
- skip `spec_lock.md` drift checks (templates do not ship a spec_lock)
- enforce roster ↔ `design_spec.md` consistency as **errors** (orphan files / missing files break the template contract and, in library scope, the target kind's index)
- emit advisory **warnings** when a page lacks a conventional placeholder — these are hints, not failures. Declare a `placeholders:` block in `design_spec.md` frontmatter to silence them when your template intentionally uses a different vocabulary
-- require every SVG root to declare an output Layout and every SVG to contain at least one direct Master/Layout/placeholder declaration
-- emit `placeholder_bounds_missing` for legacy packages; treat that warning as blocking in this creation workflow and add finite positive design-zone bounds to every new placeholder
-- validate cross-page Master equality plus same-key Layout/placeholder equality
+- require every SVG root to declare one output Master and Layout; zero-slot Layouts are valid
+- reject Master/Layout `<g>` elements, nested structure markers, missing slot bounds, and carrier-bound slots without exactly one compatible carrier
+- validate cross-page Master equality plus same-key Layout atom/slot equality
**Checklist**:
@@ -412,10 +412,10 @@ python3 skills/ppt-master/scripts/svg_quality_checker.py "<template_target>" --t
- [ ] SVG `viewBox` matches the declared canvas dimensions, not just the aspect ratio (for `ppt169`: `0 0 1280 720`; for `banner`: `0 0 1920 1080`); `width` / `height`, if written, equal it
- [ ] Placeholder names follow the canonical convention where applicable; templates with intentionally different vocabularies (e.g. `{{KEY_MESSAGE}}` instead of `{{PAGE_TITLE}}`) should declare a `placeholders:` frontmatter block to silence advisory warnings
- [ ] Asset files referenced by SVGs exist at their resolved paths. In project scope, bitmap references resolve through `../images/`; no bitmap remains accidentally stranded in `templates/`
-- [ ] `design_spec.md` frontmatter declares `native_structure_mode: template`; no `native_structure.json` or `source_template.pptx` is packaged
-- [ ] Every SVG root declares `data-pptx-layout` and `data-pptx-layout-name`; direct Master/Layout elements and semantic placeholders obey the explicit paint-order contract. Structural `data-pptx-role` is used only when specialized metadata cannot express required package/page-number/animation behavior
-- [ ] Every placeholder declares explicit design-zone bounds; no bound was derived from sample text length, glyph ink, or current wrapping
-- [ ] Every retained source Layout is represented by a complete template page, or `design_spec.md` records its explicit consolidation target/unused reason in `Source Layout Consolidation`
+- [ ] `design_spec.md` frontmatter declares `native_structure_mode: structured`; no `native_structure.json` or `source_template.pptx` is packaged
+- [ ] Every SVG root declares Master/Layout key and picker names; Master/Layout visuals are direct atoms, never `<g>`, and obey the explicit paint-order contract. Structural `data-pptx-role` is used only when specialized metadata cannot express required package/page-number/animation behavior
+- [ ] Every slot is a direct `<g id>` with explicit design-zone bounds and exactly one compatible direct carrier, or an explicit composite `object` proxy; zero-slot Layouts remain valid
+- [ ] Every source Layout is represented by a complete template page, or `design_spec.md` records an explicit unsupported reason in `Source Structure Reconstruction`; no silent merge, drop, or re-parenting
- [ ] If any SVG references an extracted vector `data-icon`, the corresponding SVG asset exists under the package's `icons/` directory. Project scope also has the identical runtime copy under `<target_project>/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_target>/*_*.svg` matches the cleaned flat `<import_workspace>/svg-flat/slide_*.svg` count; type B: matches the source SVG count); filenames follow the `<NNN>_<page_type>.svg` convention; **no `{{...}}` placeholder strings appear in any copied SVG** (`grep -l "{{" "<template_target>"/*.svg` should return nothing — if the type B source itself contains placeholders, the user should be in `standard` mode, not `mirror`); §V Page Roster in `design_spec.md` lists every emitted file with a one-line description of what the page contains and what content slot it suits
@@ -470,9 +470,9 @@ The index file is a **discovery index** — it lets the AI answer "what template
> source_canvas_width: 1280
> source_canvas_height: 720
> source_viewbox: "0 0 1280 720"
-> # All current deck/layout templates rebuild an explicit SVG structure.
+> # All current deck/layout templates rebuild the current structured SVG contract.
> # Downstream strict/adaptive use is confirmed by Strategist and is not stored here.
-> native_structure_mode: template
+> native_structure_mode: structured
> page_count: 5
> primary_color: "#005587"
> ---
diff --git a/skills/ppt-master/workflows/distill-layouts.md b/skills/ppt-master/workflows/distill-layouts.md
deleted file mode 100644
index 1b11bbc5..00000000
--- a/skills/ppt-master/workflows/distill-layouts.md
+++ /dev/null
@@ -1,220 +0,0 @@
----
-description: Distill completed free-design or template-based SVG pages into reusable PowerPoint Layouts
----
-
-# Distill Layouts Workflow
-
-Finalize reusable Master/Layout structure only after the complete visible SVG pages exist.
-
-**Trigger**: Run on explicit free-design reuse requests, and automatically after template-based visual generation only when `layout_strategy: distill` is locked and `pptx_layouts` is still absent.
-
----
-
-## 1. Scope and State
-
-| Project state | Action |
-|---|---|
-| `mode: baseline` with no `layout_strategy` | Continue only when the user selected finished pages for reuse |
-| `mode: template` + `layout_strategy: distill` + no `pptx_layouts` | Continue; every page already has one input prototype in `page_layouts` |
-| `layout_strategy: distill` + complete `pptx_layouts` | Validate/no-op and continue to export; re-enter only when the user explicitly asks to re-distill after later SVG changes |
-| `mode: template` without `layout_strategy` | Stop; keep the legacy immediate/pre-authored template contract |
-| `mode: preserve` | Stop; preserve owns the imported native package contract |
-| Raw PPTX request | Route to [`create-template`](./create-template.md) |
-| Cross-project package from an already distilled source | Route to [`create-template`](./create-template.md) with only user-selected/`distilled` pages, never `utility` pages |
-| Cross-project package from an undistilled free-design source | First complete this workflow for the explicitly selected source pages, then pass only those `distilled` pages to [`create-template`](./create-template.md) |
-| Missing completed `svg_output/` | Stop; finish Executor visual construction first |
-
-`page_layouts` is the input prototype mapping. `pptx_layouts` is the output native Layout contract. Do not write the latter before the complete SVG design exists on a deferred template route.
-
-🚧 **GATE**: Read `spec_lock.md`, every SVG in `svg_output/`, every template SVG named by `page_layouts`, the complete page roster, and `animations.json` when present. Distillation writes one all-page output contract; a selected-page-only read is insufficient.
-
-**Hard rule**: Keep this work in the main agent. Do not infer, cluster, or match by visual similarity.
-
----
-
-## 2. Resolve Prototypes
-
-### 2.1 Baseline selection
-
-**User selection wins**: Use the requested page numbers or filenames. One selected page creates one Layout unless the user explicitly asks to share a family.
-
-⛔ **BLOCKING**: When a baseline reuse request names no pages, present a short candidate list with page number, composition, and reuse rationale, then wait for the user to choose. Do not promote every page automatically.
-
-**Shared baseline family**: Share one key only when the user explicitly requests it. The named prototype supplies the default bounds; otherwise use the first page in the selection order and state that choice. Every member repeats the same placeholder ids/types/indices/default bounds and static Layout elements. Slide-local geometry may differ.
-
-### 2.2 Template prototypes
-
-**Per-page source**: Resolve each `P<NN>` through `page_layouts` to one complete SVG in `templates/`. The template page is both the visual prototype and the structural authority for its Master/Layout/placeholder metadata.
-
-| Adherence | Final contract |
-|---|---|
-| `strict` | Keep the prototype Layout key/name, Master/Layout ids/topology/geometry, and placeholder id/type/index/default-bounds contract |
-| `adaptive` | Keep the prototype Master ids/topology/geometry; derive a new explicit Layout key/name, static framing, placeholder topology, and design-zone bounds only when the completed page evolved |
-
-**Hard rule — stable provenance**: Match inherited structure by `page_layouts` plus stable direct-child `id`. Do not recover a missing object by geometry, text role, filename, or visual similarity.
-
-**Template skin boundary**: For non-mirror templates, colors, strokes, effects, and font sizes follow the project `spec_lock` re-skin rules. Strict locks reusable structure and bounds, not the template package's sample paint. Mirror remains visually literal.
-
-**Strict legacy boundary**: A strict prototype without explicit bounds on every placeholder cannot enter deferred distillation. Return to the Strategist bounds preflight and use legacy immediate-template compatibility, or upgrade the template package. Do not switch the user's strict choice to adaptive automatically.
-
----
-
-## 3. Build the Final Contract
-
-| Scope | Baseline source | Template source |
-|---|---|---|
-| Master | Preserve an already exact all-page Master; do not invent one | Preserve the selected template Master ids/topology/geometry in both strict and adaptive; apply the locked project skin |
-| Layout | User-selected reusable static framing behind content | Strict copies the prototype; adaptive keeps only stable evolved framing from the completed design |
-| Placeholder | Safe direct atomic carrier, or the final composite-object region exception below | Strict keeps the prototype identity/bounds; adaptive keeps template semantics where applicable and derives evolved design-zone bounds |
-| Slide | Actual text, imagery, data, icons, complex groups, foreground overlays, local geometry | Same |
-
-**Hard rule — complete-SVG authority**: The finished SVG remains the sole visible page authority. Do not add a visible object from the template during distillation. Missing inherited visuals are an Executor error; return to page generation instead of repairing them invisibly at export time.
-
-**Hard rule — no visible redesign**: Do not change text, geometry, paint, image hrefs, or z-order. Structure-only reparenting is allowed only for the safe single-carrier case below.
-
-**Hard rule — safe placeholder carrier**: Prefer one direct atomic object. When the reusable unit is an already completed multi-object region, the final `distilled` SVG may mark exactly one direct top-level `<g>` as `data-pptx-placeholder="object"` with explicit design-zone bounds. This is a Layout-only region proxy: its visible Slide group remains ordinary and export adds a hidden transparent binding proxy. Do not use this exception in reusable template SVGs, pending template pages, utility pages, or legacy immediate contracts. Nested metadata, unsafe text extraction, and non-top-level groups remain forbidden.
-
-**Single-carrier extraction**: Replace a top-level one-carrier wrapper by its child only when the wrapper has no clip, mask, filter, `animations.json` reference, animation target, or multi-object semantics. Materialize inherited presentation attributes and transforms, preserve the effective paint position and stable referenced id, then run the render-equivalence gate in §7. If the gate cannot run, keep the object Slide-local.
-
-**Native chart/table boundary**: Keep chart/table groups Slide-local by default. Mark one as a placeholder only when it already carries a valid matching `data-pptx-native` contract and export will use the same `--native-objects` choice.
-
-**Final kind**: Add `data-pptx-layout-kind="distilled"` to every selected baseline page and every deferred template page. Template distillation has no utility pages because every page owns a `page_layouts` prototype.
-
-**Finished-Slide preservation**: A distilled marker supplies a Layout prototype without moving visible content. Atomic carriers retain matching Slide bindings for render fidelity. Composite object-region carriers remain ordinary and receive hidden transparent binding proxies, preventing empty inherited slots from painting over an approved page.
-
-```xml
-<svg viewBox="0 0 1280 720"
- data-pptx-layout="editorial-visual"
- data-pptx-layout-name="Editorial Visual"
- data-pptx-layout-kind="distilled">
- <g id="visual-frame" data-pptx-layer="layout">...</g>
- <text id="page-title"
- data-pptx-placeholder="title"
- data-pptx-placeholder-bounds="60 36 1160 64">Actual title</text>
- <image id="hero-image"
- data-pptx-placeholder="picture"
- data-pptx-placeholder-idx="1"
- data-pptx-placeholder-bounds="570 120 650 500"
- x="620" y="120" width="600" height="500"
- href="../images/hero.jpg"/>
- ...
-</svg>
-```
-
----
-
-## 4. Derive Default Placeholder Bounds
-
-| Placeholder | Bounds source |
-|---|---|
-| `title` / `subtitle` | Title safe area or header zone |
-| `body` | Column, panel inner box, or intended copy region |
-| `picture` / `media` | Image frame or intended visual region |
-| `chart` / `table` / `object` | Reusable plot, grid, or object zone; chart/table remains conditional under §3 |
-| `footer` / `slide-number` | Stable footer or page-number zone |
-
-**Hard rule**: Every placeholder on a `distilled` Layout carries `data-pptx-placeholder-bounds="x y width height"` with four finite values and positive width/height.
-
-**Forbidden — text-tight bounds**: Do not derive bounds from character count, glyph width, line wrapping, text ink, or `data-pptx-text-bounds`. Use the intended design zone. `data-pptx-text-bounds` continues to own only the current Slide text frame.
-
-**Local geometry remains free**: Placeholder bounds define the Layout default. The current object geometry remains the Slide override and may differ across pages using one key.
-
----
-
-## 5. Complete the All-Page Mapping
-
-### 5.1 Baseline utility mapping
-
-Map every unselected baseline page to one empty utility Layout:
-
-```xml
-<svg ...
- data-pptx-layout="freeform-unselected"
- data-pptx-layout-name="Freeform"
- data-pptx-layout-kind="utility">
- ...all visible objects remain Slide-local...
-</svg>
-```
-
-**Hard rule**: A `utility` Layout has zero Layout elements and zero placeholders. It exists only to keep the baseline mapping complete.
-
-### 5.2 Template mapping
-
-Map every template page to `distilled`. Strict reuses the selected prototype key/name. Adaptive keeps that key/name only when the static Layout, placeholder identities, and default bounds still match; any evolved reusable contract receives both a new key and a new picker name. Pages sharing one key repeat an identical static/placeholder/default-bounds contract.
-
-For a `replication_mode: mirror` package, the Master and every Slide-local non-text element preserve literal paint, fonts, effects, grouping, geometry, and referenced asset identity. A reused Layout/placeholder identity does the same. Only visible text content may change. Adaptive may intentionally evolve a Layout, but it must use the new key/name rule above; the mirror Master and ordinary Slide-local visuals remain literal. Referenced `<defs>` and applicable embedded-style rules are compared by each layer's actual dependency closure, so resources private to a genuinely new adaptive Layout do not masquerade as Slide-local drift.
-
-**Forbidden — template utility**: Do not map any deferred template page to `utility`, omit its prototype, or fall back to free design.
-
----
-
-## 6. Finalize `spec_lock.md`
-
-Write `layout_strategy: distill` and the complete output mapping atomically. Keep `page_layouts` unchanged on template routes.
-
-```markdown
-## pptx_structure
-- mode: template
-- template_adherence: adaptive
-- layout_strategy: distill
-
-## pptx_layouts
-- P01: cover-hero | Cover Hero | distilled
-- P02: editorial-visual | Editorial Visual | distilled
-
-## page_layouts
-- P01: 01_cover
-- P02: 03_content
-```
-
-**Hard rule**: Write one row for every generated page. Do not leave a partial mapping or mix final and pending SVG roots. Remove `data-pptx-page-role` from every mapped root and remove generic `data-pptx-role` from a carrier that now has specialized placeholder metadata.
-
-**Baseline migration**: Do not silently replace an existing kindless structured-baseline mapping. Proceed only when the request explicitly asks to migrate or re-distill it.
-
-**Completed-state re-entry**: A complete distilled mapping is idempotent. If no SVG structure changed, validate it and continue without rewriting. After later edits, re-distill only on an explicit request and replace the complete mapping/root metadata atomically; never expose a partial pending state.
-
----
-
-## 7. Validate and Resume Export
-
-Before any extraction or metadata reparenting, render each affected page with the existing fixed-output renderer, then copy the baseline outside `.preview/` before the next render overwrites it:
-
-```bash
-python3 skills/ppt-master/scripts/visual_review.py "<project_path>" --pages "<page_stem>"
-mkdir -p "<project_path>/analysis/layout_distill_compare"
-cp "<project_path>/.preview/<page_stem>.png" "<project_path>/analysis/layout_distill_compare/<page_stem>.before.png"
-```
-
-After the structure edit, render the same page again and compare the retained baseline with the new `.preview` PNG:
-
-```bash
-python3 skills/ppt-master/scripts/visual_review.py "<project_path>" --pages "<page_stem>"
-python3 -c 'from PIL import Image, ImageChops; import sys; a=Image.open(sys.argv[1]).convert("RGBA"); b=Image.open(sys.argv[2]).convert("RGBA"); raise SystemExit(0 if a.size == b.size and ImageChops.difference(a, b).getbbox() is None else 1)' "<project_path>/analysis/layout_distill_compare/<page_stem>.before.png" "<project_path>/.preview/<page_stem>.png"
-```
-
-Require exit code 0. If a page differs, undo the extraction and keep that object Slide-local. Pure root metadata additions that do not reparent or change any visible child do not need this comparison.
-
-Run the project quality gate:
-
-```bash
-python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path>
-```
-
-The checker validates complete mappings, explicit bounds, utility emptiness, selected template prototypes, strict structural equality, and adaptive Master-structure equality. Fix every error before export.
-
-| Entry point | Next action |
-|---|---|
-| Before the first export | Resume `SKILL.md` Step 7 |
-| After an existing export | Re-run Step 7.2 `finalize_svg.py`, then repeat the exact prior Step 7.3 invocation with the same native-object, animation, narration, notes, and transition flags |
-
-```markdown
-## ✅ Layout Distillation Complete
-
-- [x] Baseline user selections or all template prototypes resolved explicitly
-- [x] Every distilled placeholder has explicit design-zone bounds
-- [x] Template Master structure matches the selected prototypes
-- [x] `spec_lock.md` and every SVG root carry one complete final mapping
-- [x] Structure-only edits are pixel-identical to their pre-edit render
-- [x] Project quality checker reports zero errors
-- [ ] **Next**: Resume or repeat the canonical export steps
-```
diff --git a/skills/ppt-master/workflows/index.md b/skills/ppt-master/workflows/index.md
index 7f870cdc..3989e47c 100644
--- a/skills/ppt-master/workflows/index.md
+++ b/skills/ppt-master/workflows/index.md
@@ -21,13 +21,13 @@ Registry for standalone workflows referenced by `SKILL.md` and [`routing.md`](./
| `create-brand` | [`create-brand.md`](./create-brand.md) | Build/extract a reusable brand identity preset | Logo/site/branded deck/PDF or explicit brand setup request | Not a layout/deck template roster | Workflow Step 1 | Brand directory under `templates/brands/<id>/` | Blocks on brand evidence and validation defined in the workflow |
| `resume-execute` | [`resume-execute.md`](./resume-execute.md) | Continue an existing split-mode project | Planning-session artifacts exist | Do not re-run planning | Execution-session entry | SVG generation, post-processing, export | Stops if `design_spec.md` or `spec_lock.md` is missing |
| `refine-spec` | [`refine-spec.md`](./refine-spec.md) | User explicitly opts into spec refinement before generation | Strategist confirmation stage completed | Do not enter by default | After Step 4, before Step 5/6 | Revised `design_spec.md` and `spec_lock.md` | Blocks for user review/approval before generation |
+| `restore-pptx-structure` | [`restore-pptx-structure.md`](./restore-pptx-structure.md) | Existing project or template uses a legacy/unmapped PowerPoint structure contract | Legacy SVG project/package exists; original PPTX/native facts are preferred when available | Not part of normal new-project generation; exporter never migrates implicitly | Before Step 3 template use, SVG generation, or export | Current structured SVGs plus complete Master/Layout lock mapping | Blocks only when restoration requires an unresolved design decision |
| `verify-charts` | [`verify-charts.md`](./verify-charts.md) | Deck contains data charts that require coordinate calibration | SVG pages exist | Not needed for decks without data charts | Between Step 6 and Step 7 | Verified/fixed chart geometry | Blocks on chart coordinate errors |
| `customize-animations` | [`customize-animations.md`](./customize-animations.md) | User asks for object-level animation order/effect/timing | Target deck/SVG groups exist | Do not add per-element builds by default | Before or during export configuration | `animations.json` or equivalent validated config | Blocks if target objects cannot be identified |
| `native-enhance-pptx` | [`native-enhance-pptx.md`](./native-enhance-pptx.md) | Finished PPTX should keep content/layout stable while adding notes/audio/timing/transitions | Source PPTX exists | No SVG regeneration | Workflow Step 1 | Patched PPTX through OOXML | Blocks on source archive/validation failures |
| `native-narration-pptx` | [`native-narration-pptx.md`](./native-narration-pptx.md) | Compatibility reference for the narration subset of native enhancement | Existing PPTX exists | Prefer `native-enhance-pptx` for new requests | Compatibility entry | Narration-enhanced PPTX | Follow compatibility doc |
| `live-preview` | [`live-preview.md`](./live-preview.md) | User asks for preview, element selection, browser annotations, or re-entry to the editor | Project exists; SVGs required only for annotation apply/export | Do not apply annotations during active generation | Step 6 auto-start or workflow Step 1/2 | Running preview or applied browser edits/annotations | Blocks only when project/SVG target is missing |
| `visual-review` | [`visual-review.md`](./visual-review.md) | User explicitly asks for per-page visual review or visual rubric | Generated SVG pages exist | Never inferred from deck size/model identity | Between Step 6 and Step 7 | Findings and fixed SVGs | Blocks on selected severe findings if the workflow says to fix |
-| `distill-layouts` | [`distill-layouts.md`](./distill-layouts.md) | User asks to promote finished baseline pages, or a template project reaches deferred structure finalization | Completed SVG pages; template route also requires complete `page_layouts` | Not for preserve, legacy immediate-template, or cross-project registration | After Step 6 or as a post-export re-entry | Complete all-page `pptx_layouts` plus SVG structure metadata | Baseline blocks for missing page selection; template blocks for missing/invalid prototypes |
| `generate-audio` | [`generate-audio.md`](./generate-audio.md) | User asks for recorded narration, voiceover, audio, or video-style export | Post-processing/export context exists; notes available | Do not call `notes_to_audio.py` directly | After Step 7 | Audio files and optional narration-embedded PPTX | Single backend/voice/settings confirmation |
---
diff --git a/skills/ppt-master/workflows/refine-spec.md b/skills/ppt-master/workflows/refine-spec.md
index 2d053f95..1791d806 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 template bounds preflight after structural revisions.** If the user changes `template_adherence` or any `page_layouts` choice, repeat the Strategist preflight in [`strategist.md`](../references/strategist.md) §6.2 before approval and hand-back. Inspect every newly selected prototype. A distillation-capable strict route requires explicit `data-pptx-placeholder-bounds` on every prototype placeholder; adaptive may still defer and author new design-zone bounds when a legacy prototype lacks them. If strict selects any bounds-missing prototype, keep the user's strict choice but switch the lock to legacy immediate-template compatibility: omit `layout_strategy`, write the complete kindless `pptx_layouts` mapping before generation, and surface the required warning. Update both artifacts together; never leave the pre-revision deferred state in `spec_lock.md`.
+**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.
---
diff --git a/skills/ppt-master/workflows/restore-pptx-structure.md b/skills/ppt-master/workflows/restore-pptx-structure.md
new file mode 100644
index 00000000..de7fd7fa
--- /dev/null
+++ b/skills/ppt-master/workflows/restore-pptx-structure.md
@@ -0,0 +1,183 @@
+---
+description: Restore legacy SVG projects to the explicit structured Master/Layout contract
+---
+
+# Restore PPTX Structure Workflow
+
+Restore an existing SVG-authored project before quality checking or release export when its Master/Layout contract is absent or legacy.
+
+**Trigger**: Run when `svg_quality_checker.py` or `svg_to_pptx.py` reports a missing or legacy `pptx_structure.mode`, or when the user explicitly asks to migrate an older SVG project.
+
+---
+
+## 1. Route Boundary
+
+| Input state | Action |
+|---|---|
+| Missing `pptx_structure` or legacy `baseline` / `generated` | Restore structure from the complete SVG deck; use source facts when available |
+| Legacy `template`, `layout_strategy: distill`, `data-pptx-layout-kind`, or `utility` | Replace the distillation contract with one explicit structured contract |
+| Legacy `preserve` plus `native_structure.json` / `source_template.pptx` | Use the native facts as restoration evidence; rebuild the SVG contract instead of preserving package parts |
+| Existing `mode: structured` project | Validate and repair only the reported mismatch; do not re-infer the deck |
+| Raw PPTX intended as a reusable template | Run [`create-template`](./create-template.md), not this workflow |
+| Existing PPTX receiving notes/audio/timing/transitions | Keep the direct [`native-enhance-pptx`](./native-enhance-pptx.md) route; do not create SVGs |
+| Raw PPTX template receiving new content | Keep the direct [`template-fill-pptx`](./template-fill-pptx.md) route |
+
+**Hard rule**: Keep restoration in the main agent and inspect the complete page roster. Do not delegate page classification, cluster by visual similarity, or write a batch SVG generator.
+
+🚧 **GATE**: Read `spec_lock.md`, every file in `svg_output/`, every template SVG named by `page_layouts`, and any original PPTX/native structure facts that belong to this project.
+
+---
+
+## 2. Preserve the Pre-Migration State
+
+Before editing, copy the current `svg_output/` and `spec_lock.md` into one new timestamped directory under:
+
+```text
+<project>/backup/<timestamp>/restore-pptx-structure/
+```
+
+Record the source evidence used for restoration in a short `README.md` inside that backup directory: original PPTX/native facts, legacy template SVGs, or completed SVG pages only.
+
+**Hard rule**: Never delete the legacy sources during restoration. If the requested migration would rewrite several existing files and the user has not already authorized that operation, obtain the repository-required bulk-modification confirmation first.
+
+---
+
+## 3. Determine the Structure
+
+Use this evidence priority:
+
+| Priority | Evidence | Contract |
+|---:|---|---|
+| 1 | Original PPTX plus verified native structure facts | Preserve Master/Layout names, ownership, placeholder type/index/bounds, and page assignment |
+| 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 |
+
+Classify each visible object:
+
+| Classification | SVG representation |
+|---|---|
+| Fixed across every Layout under one Master | Root-level atomic element with `data-pptx-layer="master"` |
+| Fixed only for one reusable Layout | Root-level atomic element with `data-pptx-layer="layout"` |
+| Replaceable reusable content region | Root-level placeholder `<g>` with explicit design-zone bounds |
+| Page-specific content or foreground overlay | Ordinary Slide-local SVG content without Master/Layout ownership |
+
+**Hard rule — no Master/Layout groups**: A fixed Master or Layout visual must not be a `<g>`. Recursively expand every legacy/source group into individual root-level atomic elements. Compose and apply group transforms, opacity, inherited paint, clip behavior, and styles to each atom while preserving paint order. The restoration target preserves supported visual output and Master/Layout topology; it does not preserve source grouping as an editing unit.
+
+**Hard rule — no visual redesign**: Do not change wording, geometry, paint, assets, or z-order except for the normalization required to flatten a fixed Master/Layout group. Render before and after any transform-flattening edit and require pixel equivalence.
+
+---
+
+## 4. Write the Structured SVG Contract
+
+Every page root declares its final ownership:
+
+```xml
+<svg viewBox="0 0 1280 720"
+ data-pptx-master="master-default"
+ data-pptx-master-name="Default Master"
+ data-pptx-layout="content-two-column"
+ data-pptx-layout-name="Two Column">
+```
+
+Fixed visuals are direct atomic children:
+
+```xml
+<path id="master-brand-rule" data-pptx-layer="master" .../>
+<rect id="layout-title-rule" data-pptx-layer="layout" .../>
+```
+
+An ordinary placeholder is one root-level group with exactly one compatible direct carrier:
+
+```xml
+<g id="title-slot"
+ data-pptx-placeholder="title"
+ data-pptx-placeholder-bounds="72 48 1136 72">
+ <text id="title"
+ data-pptx-placeholder-carrier="true"
+ x="72" y="100">Actual title</text>
+</g>
+```
+
+| Slot contract | Rule |
+|---|---|
+| `title`, `subtitle`, `body`, `date`, `footer`, `slide-number` | Use exactly one direct text carrier |
+| `picture`, `media` | Use exactly one compatible direct image/media carrier |
+| `chart`, `table` | Use one compatible direct native carrier only when the matching native-object contract is valid |
+| Atomic `object` | Use exactly one compatible direct carrier |
+| Composite `object` | Set `data-pptx-placeholder-binding="proxy"`; keep the visible children Slide-local inside the slot and declare no carrier |
+
+**Hard rule — bounds**: Every slot group declares `data-pptx-placeholder-bounds="x y width height"` with finite values and positive width/height. Bounds describe the reusable design zone, not the current content's tight box.
+
+**Hard rule — wrapper neutrality**: The slot `<g>` is an authoring boundary, not a rendered object. It may carry only `id` and `data-pptx-*` attributes. Move any transform, opacity, fill/stroke, filter, clip/mask, style, or class behavior onto the visible children before marking the group as a slot.
+
+**Hard rule — proxy boundary**: `proxy` is allowed only for a composite `object` slot. Ordinary slots must use the default carrier binding.
+
+**Zero-slot Layouts are valid**: A cover, poster, or purely visual Layout may declare no placeholder group. Do not manufacture a full-page `object` slot or a `utility` Layout.
+
+Remove legacy `data-pptx-layout-kind`, `layout_strategy`, `distilled`, `utility`, and preserve-only ownership metadata from the restored SVG contract.
+
+---
+
+## 5. Replace the Project Lock
+
+After every SVG has its final metadata, replace the legacy structure sections as one complete mapping:
+
+```markdown
+## pptx_structure
+- mode: structured
+
+## pptx_masters
+- master-default: Default Master
+
+## pptx_layouts
+- P01: master-default | cover-visual | Cover Visual
+- P02: master-default | content-two-column | 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.
+
+**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.
+
+**Template adherence**: Keep `template_adherence: strict|adaptive` only when a template route already owns that policy. Strict pages keep the referenced contract. Adaptive pages that changed the contract receive a new Layout key and name.
+
+---
+
+## 6. Validate and Resume
+
+Before flattening each affected page, render and retain its baseline outside `.preview/`:
+
+```bash
+python3 skills/ppt-master/scripts/visual_review.py "<project_path>" --pages "<page_stem>"
+cp "<project_path>/.preview/<page_stem>.png" "<backup_path>/<page_stem>.before.png"
+```
+
+After restoring that page, render again and compare it with the retained baseline:
+
+```bash
+python3 skills/ppt-master/scripts/visual_review.py "<project_path>" --pages "<page_stem>"
+python3 -c 'from PIL import Image, ImageChops; import sys; a=Image.open(sys.argv[1]).convert("RGBA"); b=Image.open(sys.argv[2]).convert("RGBA"); raise SystemExit(0 if a.size == b.size and ImageChops.difference(a, b).getbbox() is None else 1)' "<backup_path>/<page_stem>.before.png" "<project_path>/.preview/<page_stem>.png"
+```
+
+Require exit code 0. If the render differs, repair the transform/style materialization before continuing. Pure metadata edits that do not change or reparent visible children do not require this comparison.
+
+Then run:
+
+```bash
+python3 skills/ppt-master/scripts/svg_quality_checker.py "<project_path>"
+```
+
+Fix every error. The gate must confirm root Master/Layout identity, root-level atomic fixed elements, slot bounds, carrier/proxy rules, complete lock mappings, and same-key contract equality.
+
+After the checker reports zero errors, return to `SKILL.md` Step 7.2 and Step 7.3. Run the commands sequentially with the same native-object, animation, narration, notes, and transition flags previously selected.
+
+```markdown
+## ✅ PPTX Structure Restoration Complete
+
+- [x] Legacy SVG and lock artifacts backed up with source-evidence notes
+- [x] Every page root declares one Master and one Layout
+- [x] Fixed Master/Layout visuals are root-level atomic elements, never groups
+- [x] Every slot has explicit bounds and a valid carrier or proxy contract
+- [x] `spec_lock.md` contains complete `structured` Master and page mappings
+- [x] Group-flattening edits are pixel-equivalent and the quality gate reports zero errors
+- [ ] **Next**: Resume the canonical post-processing and release export steps
+```
diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.md
index dd986eda..8c3aa87f 100644
--- a/skills/ppt-master/workflows/routing.md
+++ b/skills/ppt-master/workflows/routing.md
@@ -42,7 +42,7 @@ Route selection authority for PPT Master. Use this file before entering the main
| Topic only, no source facts | User supplies only a topic name or requirement and no substantive source material | [`topic-research`](./topic-research.md), then main `SKILL.md` pipeline | Direct main pipeline with invented facts | Web/source gathering is allowed or user supplies facts | Research material becomes source input for Step 1 | Stop if facts cannot be gathered and the user supplies no source |
| Source material can be reworked into a new story | PDF/DOCX/URL/Markdown/text/conversation content, or PPTX treated as content | Main `SKILL.md` pipeline | Direct PPTX edit workflows | Source content exists or is available in conversation | `design_spec.md`, `spec_lock.md`, `svg_output/`, exported PPTX | Stop at Step gates when required artifacts are missing |
| PPTX as re-architectable source | User allows page count/order/outline to change, or asks to split/merge/drop/reorder slides | Main `SKILL.md` pipeline with `ppt_to_md.py` plus PPTX intake | [`beautify-pptx`](./beautify-pptx.md) | PPTX source exists | Markdown content plus `analysis/source_profile.json`; Strategist may re-outline | Stop if user requires exact 1:1 page preservation |
-| Explicit template directory path | User provides a directory containing `design_spec.md` with `kind: brand`, `kind: layout`, or `kind: deck` | Main `SKILL.md` Step 3 | Fuzzy template lookup by bare name | Path resolves and frontmatter kind is valid | External assets are copied/fused into `<project>/templates/`; the same project's own `templates/` path is consumed in place | Stop if the path does not exist or lacks valid `design_spec.md` |
+| Explicit template directory path | User provides a directory containing `design_spec.md` with `kind: brand`, `kind: layout`, or `kind: deck` | Main `SKILL.md` Step 3 | Fuzzy template lookup by bare name | Path resolves, frontmatter kind is valid, and every deck/layout SVG satisfies the current structured Master/Layout/slot contract | External assets are copied/fused into `<project>/templates/`; the same project's own `templates/` path is consumed in place | Route a legacy package to [`restore-pptx-structure`](./restore-pptx-structure.md) before Step 3; stop if the path does not exist or lacks valid `design_spec.md` |
---
@@ -68,11 +68,11 @@ 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 | Brand preset 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 project/template SVGs use unmapped `baseline`, `preserve`, `layout_strategy: distill`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, or lack root Master identity | [`restore-pptx-structure`](./restore-pptx-structure.md) before generation/export or before Step 3 template consumption | Legacy SVG project/package exists; original PPTX/native facts are used when available | Current structured SVG contract plus complete `pptx_masters`/`pptx_layouts` mapping | 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 |
| Visual review | User explicitly asks for per-page visual self-check or visual rubric | [`visual-review`](./visual-review.md) between Step 6 and Step 7 | SVG pages exist | Visual review findings and fixes before post-processing | Do not run without explicit user request |
-| Finalize reusable Layouts | User asks to promote completed baseline pages, or a template project has `layout_strategy: distill` with missing `pptx_layouts` after SVG generation | [`distill-layouts`](./distill-layouts.md) after Step 6 or explicit post-export re-entry | Completed SVG pages; template route also has one `page_layouts` prototype per page | Baseline: selected Layouts plus one utility; template: every page distilled against strict/adaptive prototype rules | Complete mappings are validation/no-op unless re-distill is explicit; cross-project `create-template` consumes selected/`distilled` pages and skips `utility` |
| Recorded narration / video export | User asks for narration, voiceover, or video-style export | [`generate-audio`](./generate-audio.md) after post-processing | Notes and exported deck exist | Audio files and optional narration-embedded PPTX | Stop for the workflow's single backend/voice confirmation |
---