| 1 | # Technical Design |
| 2 | |
| 3 | [English](./technical-design.md) | [Chinese](./zh/technical-design.md) |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## Design Philosophy — AI-Directed Workflow, Human-Controlled Draft |
| 8 | |
| 9 | PPT Master produces a **high-quality editable PowerPoint draft**, not a sealed final deck. The workflow reasons about the message, designs the pages, and authors or preserves native PowerPoint objects under an explicit route contract. The user reviews the direction and owns the final-mile judgment in PowerPoint. Remaining work should be refinement of a real deck, not reconstruction from slide images or a thin editable skin. |
| 10 | |
| 11 | The workflow supplies presentation-specific reasoning, state, contracts, and quality gates; deterministic tools handle conversion, validation, packaging, and repeatable file operations. **The selected model still sets the quality ceiling**, while the user's taste and judgment guide review and finishing. |
| 12 | |
| 13 | ### SVG Is a Project-Specific Intermediate Language |
| 14 | |
| 15 | PPT Master does not aim to convert arbitrary SVG into PPTX. `svg_output/` uses a **project-canonical SVG intermediate language**: it borrows SVG's XML syntax and two-dimensional graphics model, while the project contract closes the allowed elements, attributes, units, metadata, structural contracts, and DrawingML mappings. The direction is intentional: **SVG adapts to PPT Master; PPT Master does not expand to follow the entire SVG standard**. |
| 16 | |
| 17 | The intermediate language distinguishes three input states: |
| 18 | |
| 19 | | State | Definition | Handling | |
| 20 | |---|---|---| |
| 21 | | Canonical authoring input | The single recommended expression generated by prompts, templates, and examples | Validate and compile through registered mappings without alias warnings | |
| 22 | | Compatible input | An explicitly documented historical or manual spelling with one safe, deterministic normalization | The checker emits a non-blocking warning; the converter normalizes it without feeding the alias back into prompts | |
| 23 | | Invalid or unsupported input | An expression with no mapping, ambiguous meaning, a broken structural contract, or a risk of invalid DrawingML/PPTX | The checker reports an error and blocks the standard flow; the converter fails when its own preflight or package validation encounters the same invalid condition | |
| 24 | |
| 25 | For example, project typography uses SVG px semantics, with finite unitless values such as `font-size="24"` as the canonical spelling. Another unit remains compatible input only when the converter has a deterministic normalization and the checker accepts it as compatible; it must not become a new generated spelling. Compatible reads are a controlled migration boundary, not permission to widen the authoring language. |
| 26 | |
| 27 | The workflow, authoring guidance, and deterministic tool layers have separate |
| 28 | responsibilities and cannot substitute for one another: |
| 29 | |
| 30 | | Layer | Single responsibility | Explicit non-responsibility | |
| 31 | |---|---|---| |
| 32 | | Generate workflow | Sequence stages, invoke gates, switch roles, and hand artifacts to their declared consumers | It does not absorb Strategist, Executor, checker, or exporter decisions merely because it coordinates them | |
| 33 | | Prompts, templates, and examples | State the project-canonical spelling precisely and reduce drift and warnings at the source | They are not a correctness or safety boundary | |
| 34 | | `svg_quality_checker.py` | Enforce the project contract on authoring state; errors block and non-blocking warnings pass | It does not silently rewrite pages or guess design intent | |
| 35 | | `svg_to_pptx.py` | Defensively validate compiler mappings and the package, normalize supported compatible forms, require a current matching final quality report for formal release, and link it into postflight | It does not rerun the complete `svg_quality_checker.py` or treat file creation as proof that the upstream quality gate passed | |
| 36 | | `workflow_transcript.py` / `workflow_log.py` | Record project-scoped Python command envelopes plus bounded material outcomes, and explicitly append important non-Python audit events | They do not retain the full console stream, infer readiness, rerun another tool, or alter the owning tool's result | |
| 37 | |
| 38 | The automatic recorder resolves the project from `PPT_MASTER_PROJECT_PATH`, a |
| 39 | path-bearing argument, or the current working directory, in that order. The |
| 40 | environment signal is needed only for stdout-oriented helpers with no project |
| 41 | path; it is placed on the same Python command and creates no wrapper process. |
| 42 | |
| 43 | --- |
| 44 | |
| 45 | ## Generate PPTX Architecture |
| 46 | |
| 47 | The diagram below covers the default Generate PPTX lifecycle. The |
| 48 | `beautify-pptx` profile uses that lifecycle unless the same request explicitly |
| 49 | asks for Quick, in which case it uses `quick-generate` while keeping the same |
| 50 | 1:1 source constraints. Quick bypasses separate planning/confirmation, the |
| 51 | first-page gate, and preview finalization; source understanding and resource |
| 52 | preparation still run as needed, and one lockless final quality gate remains. |
| 53 | Exactly one runtime procedure is loaded. |
| 54 | Create Template has its own workspace lifecycle, while Fill Native PPTX and |
| 55 | Enhance Native PPTX operate directly on OOXML; the route table later in this |
| 56 | document covers all four. |
| 57 | |
| 58 | ``` |
| 59 | User Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text) |
| 60 | ↓ |
| 61 | [Source Processing & Factual Sufficiency] → source_to_md.py dispatches by type; topic-only or planning-critical factual gaps enter topic-research |
| 62 | └── Raw or converted content is ready; research writes supplemental Markdown and fact provenance for project import |
| 63 | ↓ |
| 64 | [Create Project] → project_manager.py init <project_name> --format <format> |
| 65 | ↓ |
| 66 | [Archive Sources & Project Analysis (when source files exist; conversation text skips)] → project_manager.py import-sources <project_path> <sources...> |
| 67 | ├── First move/copy supplied files into sources/ under the ownership boundary |
| 68 | ├── Then run intake on each archived PPTX and write analysis/<stem>.identity.json, <stem>.slide_library.json, source_profile.json |
| 69 | ├── If canonical same-stem Markdown is absent, run ppt_to_md.py against that archived PPTX |
| 70 | └── Content-type files in sources/ become the content contract |
| 71 | ↓ |
| 72 | [Template Candidate Preparation (Step 3)] — internal only; no UI, wait, selection, template read, or installation |
| 73 | Prepare indexed Brand/Style/Layout/Deck candidates and supplied exact roots |
| 74 | Stage 1 confirms communication plus free design/template use together; selected workspaces are then validated/fused before Stage 2 |
| 75 | Raw PPTX template requests route to template-fill; reusable SVG templates are created by create-template first |
| 76 | ↓ |
| 77 | [Strategist] - Stage 1 communication confirmation + final Stage 2 solution/production confirmation → design_spec.md + spec_lock.md |
| 78 | ↓ |
| 79 | [Image Acquisition] (when any resource row needs AI generation, web search, or slicing) |
| 80 | ↓ |
| 81 | [Executor] |
| 82 | ├── Live preview starts and stays available during generation |
| 83 | ├── Generate P01 → svg_quality_checker.py --stage first-page --json |
| 84 | ├── Use P01 as a method sample to classify the complete issue set; fix every blocking error and selected advisory warnings |
| 85 | ├── Generate P02 through the final page continuously → svg_output/ (no checker calls in between) |
| 86 | ├── [Quality Check] svg_quality_checker.py --stage final --json (mandatory — 0 errors; warnings are non-blocking) |
| 87 | └── [Speaker notes, conditional] effective Speaker Notes outcome enabled → complete notes/total.md |
| 88 | ↓ |
| 89 | [Chart calibration (conditional)] → verify-charts stage (required for decks containing data charts) |
| 90 | ↓ |
| 91 | [Visual self-check (optional, opt-in)] → visual-review stage (only when the user explicitly requests it) |
| 92 | ↓ |
| 93 | [Post-processing] → [total_md_split.py when notes are enabled] → finalize_svg.py → svg_to_pptx.py (defensive validation, then compilation; --no-notes when disabled) |
| 94 | ↓ |
| 95 | Output: |
| 96 | svg_final/ |
| 97 | └── *.svg ← Mandatory derived visual previews; attempt to inline supported images, with EMF/WMF external-reference exceptions |
| 98 | |
| 99 | exports/ |
| 100 | ├── <project_name>_<timestamp>.pptx ← Default native-shape output (DrawingML) |
| 101 | ├── <project_name>_<timestamp>_native_charts_tables.pptx ← Explicit --native-charts-and-tables variant |
| 102 | └── <project_name>_<timestamp>_narrated.pptx ← --recorded-narration or --narration-audio-dir variant |
| 103 | |
| 104 | validation/ |
| 105 | ├── workflow.log ← Compact Python command/outcome audit + important manual audit events |
| 106 | ├── svg_quality_report.json ← Blocking/introduced/inherited/source-import SVG findings |
| 107 | └── <output_stem>.report.json ← Postflight package/resource audit linked to the final SVG quality report |
| 108 | |
| 109 | # Default-flow mode (no -o) creates the backup directory, then attempts a best-effort source copy |
| 110 | backup/<timestamp>/ |
| 111 | └── svg_output/ ← A successful copy can rebuild the PPTX from frozen authored SVG |
| 112 | ``` |
| 113 | |
| 114 | The explicit shortcut removes the separate planning and confirmation phase, not |
| 115 | the inputs or resources needed to build the deck: |
| 116 | |
| 117 | ```text |
| 118 | Source material or topic |
| 119 | -> convert/read sources and research identified factual gaps as needed |
| 120 | -> resolve mode/style and decide content, page structure, and carriers in active context |
| 121 | -> prepare selected images/icons/formulas and operational manifests |
| 122 | -> hand-author svg_output/ under the shared SVG standards |
| 123 | -> verify data-driven chart coordinates when present |
| 124 | -> svg_quality_checker.py --quick-generate --stage final --json |
| 125 | -> svg_to_pptx.py --quick-generate |
| 126 | -> exports/<name>_<timestamp>.pptx |
| 127 | ``` |
| 128 | |
| 129 | These decisions are made automatically by the current agent without Strategist, |
| 130 | Confirm UI, `design_spec.md`, `spec_lock.md`, or a substitute plan. They cannot |
| 131 | be reconstructed or resumed after the active context is lost. |
| 132 | |
| 133 | In the default flow, without an explicit `-o`, the native-object and narration |
| 134 | flags may combine into |
| 135 | `<project_name>_<timestamp>_native_charts_tables_narrated.pptx`; explicit `-o` |
| 136 | preserves the caller-supplied filename. Quick generation accepts the same |
| 137 | optional native-object and narration flags. |
| 138 | |
| 139 | ### SVG as a Constrained Page-Design Language |
| 140 | |
| 141 | For every workflow that authors or redesigns visual slides through SVG, `svg_output/` is the complete page-design authority, but SVG here means project-canonical SVG accepted by the project contract—not any SVG a browser can render. 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. In the default pipeline, templates, `design_spec.md`, and `spec_lock.md` guide SVG authoring; `quick-generate` instead uses active-context decisions and explicit SVG values. The exporter never uses planning inputs as a second visual layer that fills in missing page content. |
| 142 | |
| 143 | The always-loaded core also owns the fallback visual-quality and numeric leading defaults. Explicit user, template / brand, and locked-style requirements override compatible aesthetic defaults; when those authorities are silent, hierarchy, typography, alignment, negative space, purposeful assets, and the core's density-based leading ranges still apply. Default and Quick Generate always load `svg-effects.md` and run its Visual Job Router before completing a page. None of these aesthetic choices can override a technical Required / Forbidden boundary. |
| 144 | |
| 145 | Minimal semantic markers do not weaken that closure. Free-design, brand-only, `quick-generate`, and `template_reuse_scope: style` pages use flat Slide-local ownership: every represented object stays on the Slide and no Master/Layout identity, layer, or placeholder metadata is authored. Default export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock; lockless `quick-generate` uses converter-default theme scaffolding. Neither promotes Slide content. Only `template_reuse_scope: mirror|layout` uses the structured route, where 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. A semantic-legacy template package is not upgraded in place or accepted as a structured Step 3 input: create a new workspace through `create-template`, using a native PPTX's still-present package facts or an old SVG's visuals only as reference, then author new pages through the AI-derived application route. A flat project is intentionally unmapped, not legacy. Export never infers, repairs, or migrates Master/Layout structure or placeholders. |
| 146 | |
| 147 | | Domain | Authority | |
| 148 | |---|---| |
| 149 | | Visible page content and layout on SVG-authoring routes | Final page SVG in `svg_output/` | |
| 150 | | Project-canonical SVG syntax, compatible forms, and mapping boundary | The split authority set selected through [`references/shared-standards.md`](../skills/ppt-master/references/shared-standards.md) | |
| 151 | | Master/Layout/Slide packaging and native-object mapping | SVG-to-PPTX translation; it may reorganize represented content but does not invent visible content | |
| 152 | | Animations, transitions, speaker notes, and narration | Dedicated sidecars/assets and PPTX package post-processing | |
| 153 | | Direct native-PPTX editing | The selected native workflow's PPTX/OOXML contract | |
| 154 | |
| 155 | This is a page-design closure rule, not a claim that SVG describes the entire PPTX package. Rebuilding the visible slide from its completed SVG is the relevant invariant; reconstructing notes, audio, timing, relationships, or direct native edits from SVG alone is not. |
| 156 | |
| 157 | `svg_final/` does not change that boundary. In the default pipeline, Step 7 derives visual previews from `svg_output/`: supported bitmap/SVG resources are inlined when processing succeeds, while EMF/WMF stay external for native passthrough; unresolved ordinary images retain their original references, and the current finalizer counts those processing errors without failing the whole run. These files support IDE/browser inspection and manual insertion as SVG pictures. They are not a second PPTX export route and carry no PowerPoint Convert-to-Shape compatibility contract. Editable shapes come only from the project converter translating `svg_output/` into native DrawingML PPTX. |
| 158 | |
| 159 | Existing-PPTX requests split by mutation model: the two native workflows bypass SVG, while `beautify-pptx` remains a Generate PPTX profile that regenerates the visible design: |
| 160 | |
| 161 | | Workflow | Input role | Output mechanics | Why it is separate | |
| 162 | |---|---|---|---| |
| 163 | | `template-fill-pptx` | a native PPTX template deck plus new material | clone selected slides and patch text / tables / charts in OOXML | preserves the user's PowerPoint slide shells instead of converting them into SVG | |
| 164 | | `native-enhance-pptx` | a finished PPTX whose layout/content should remain stable | patch notes, narration, timings, and transitions directly in OOXML | appends native enhancements without regenerating design | |
| 165 | | `beautify-pptx` | an existing PPTX whose page count/order/wording must stay 1:1 | extract source facts, regenerate a native deck through the SVG pipeline | changes layout and hierarchy only; it is not direct in-place editing | |
| 166 | |
| 167 | --- |
| 168 | |
| 169 | ## Route Decision Quick Reference |
| 170 | |
| 171 | Executable route selection is authoritative in [`workflows/routing.md`](../skills/ppt-master/workflows/routing.md); this section is a rationale-oriented quick reference, not a second route matrix to maintain. |
| 172 | |
| 173 | Use this table before reasoning about implementation details. Most failed runs start with the wrong route, not the wrong command. |
| 174 | |
| 175 | | Request shape | Route | Boundary | |
| 176 | |---|---|---| |
| 177 | | Topic only, or supplied material lacks facts required by the requested outcome | Generate PPTX + `topic-research` inside Step 1 | topic-only research starts immediately; source-backed research follows conversion/read and fills only identified factual gaps | |
| 178 | | Source files or conversation text, deck structure may be rethought | Generate PPTX | Strategist may split, merge, drop, reorder, and redesign | |
| 179 | | Explicit quick generation | Generate PPTX + `quick-generate` profile | convert/read sources, research factual gaps, and prepare required resources as needed; explicit user requirements are followed and the current agent decides every remaining content, page, visual, and resource question in active context, skips Strategist/confirmation/spec/lock/finalize, hand-authors SVG, passes one lockless final gate, and exports the final PPTX | |
| 180 | | PPTX as source material, user allows a new story/page structure | Generate PPTX via `ppt_to_md` + `pptx_intake` | PPTX identity/geometry are facts and candidates, not replica constraints | |
| 181 | | Raw PPTX template plus new material/topic | Fill Native PPTX (`template-fill-pptx`) | clone/fill native slides; no SVG generation | |
| 182 | | Existing PPTX, preserve page count/order/wording 1:1, improve layout | Generate PPTX + `beautify-pptx` profile | content and pagination stay locked; explicit Quick intent uses Quick, otherwise Default | |
| 183 | | Finished PPTX, keep content/layout stable, add notes/audio/timings/transitions | Enhance Native PPTX (`native-enhance-pptx`) | direct OOXML patch; no design regeneration | |
| 184 | | User wants a reusable template workspace from one or more PPTX/SVG files, images/PDFs, documents/websites, brand assets, direct text, or a mixed reference bundle | Create Template (`create-template`) | the fixed entry reads every applicable evidence channel, dispatches one Create Brand, Create Style, Create Layout, or Create Deck child workflow, then returns a workspace root as a Generate Stage-1 candidate; structured children may export a review PPTX | |
| 185 | | Default Generate reaches planning; an exact current-contract workspace root or current Create Template handoff may already be present | Generate PPTX Stage 1 | Step 3 prepares candidates without interaction; Stage 1 confirms communication plus free design/template use together; ordinary requests default to free design, explicit template intent or any root defaults to template mode, and only one root is preselected; selected workspaces are validated/fused before Stage 2 | |
| 186 | | User asks to tune object-level animation order/effect/timing | Generate PPTX + `customize-animations` stage | optional export policy via `animations.json` | |
| 187 | | User asks to preview, select, annotate, or re-export browser edits | Generate PPTX + `live-preview` stage | annotations apply only at defined handoff points | |
| 188 | |
| 189 | Ambiguous "optimize this PPT" requests reduce to one discriminator: preserve the original page count/order/wording, or treat the deck as source material and rebuild the story. Both use Generate PPTX; preservation selects the `beautify-pptx` profile, while restructuring uses the normal profile. In either case, explicit Quick intent selects Quick; otherwise Default applies. |
| 190 | |
| 191 | --- |
| 192 | |
| 193 | ## Technical Pipeline |
| 194 | |
| 195 | **The pipeline: AI generates SVG → post-processing converts to DrawingML (PPTX).** |
| 196 | |
| 197 | The default full flow breaks into three stages: |
| 198 | |
| 199 | **Stage 1 — Content Understanding & Design Planning** |
| 200 | Source documents (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text) are converted into the content and analysis facts the Strategist needs. The Strategist confirms an open communication contract, derives a complete deck solution from it, resolves production mechanics, and produces the design specification. |
| 201 | |
| 202 | **Stage 2 — AI Visual Generation** |
| 203 | The Executor role generates each slide as an SVG file. The output of this stage is a **design draft**, not a finished product. |
| 204 | |
| 205 | **Stage 3 — Engineering Conversion** |
| 206 | Post-processing scripts convert supported SVG vector elements to DrawingML. Text and vector shapes stay native PowerPoint objects — clickable, editable, and restylable — while raster assets are copied as PPT picture media instead of flattening the slide into one image. |
| 207 | |
| 208 | `quick-generate` retains the source-understanding and resource-preparation work |
| 209 | needed by the deck, but skips the separate Strategist planning/confirmation |
| 210 | phase, first-page gate, and `finalize_svg.py`. The current agent follows every |
| 211 | explicit user requirement and makes the remaining content, page, visual, and |
| 212 | resource decisions automatically in one active context. It resolves a mode and |
| 213 | visual style, considers the complete image/icon/native-shape/chart/table/formula |
| 214 | carrier menu, then authors under the shared SVG standards, runs any selected |
| 215 | capability-specific preparation, passes one lockless final quality gate, and |
| 216 | uses the same DrawingML converter and postflight. It writes no substitute plan |
| 217 | or resumable design history; context loss restarts the Quick run. |
| 218 | |
| 219 | --- |
| 220 | |
| 221 | ## Artifact Flow |
| 222 | |
| 223 | Artifact source/derived ownership is authoritative in [`artifact-ownership.md`](../skills/ppt-master/references/artifact-ownership.md); this section visualizes the same dataflow for architecture rationale. |
| 224 | |
| 225 | The workflow is easier to maintain if the artifacts are read as a dataflow rather than as folders that happen to exist: |
| 226 | |
| 227 | ```text |
| 228 | sources/<content files> ────────┐ |
| 229 | sources/*.facts.json ───────────┤ |
| 230 | analysis/source_profile.json ───┼─> Strategist -> design_spec.md + spec_lock.md |
| 231 | analysis/image_analysis.csv ────┘ |
| 232 | |
| 233 | design_spec.md + spec_lock.md + images/ + icons/ + templates/ |
| 234 | └─> Executor -> svg_output/ |
| 235 | ├─> planning artifacts/references stay in the valid active context |
| 236 | ├─> project_manager.py page-context <project> P<NN> [on demand] |
| 237 | │ └─> --record-usage -> analysis/page-context/P<NN>.usage.json |
| 238 | ├─> svg_quality_checker.py -> validation/svg_quality_report.json |
| 239 | ├─> finalize_svg.py -> svg_final/ |
| 240 | └─> svg_to_pptx.py -> exports/<name>_<ts>.pptx + validation/<output_stem>.report.json |
| 241 | backup/<ts>/svg_output/ [default output path; copy is best-effort after directory creation] |
| 242 | |
| 243 | Quick Generate: |
| 244 | source material or topic |
| 245 | └─> conversion/read + factual-gap research [as needed] |
| 246 | └─> active-context mode/style + content/page/carrier decisions |
| 247 | └─> images/ + icons/ + formula/resource manifests [as needed] |
| 248 | └─> hand-authored svg_output/ |
| 249 | ├─> verify-charts [only for data-driven chart geometry] |
| 250 | └─> svg_quality_checker.py --quick-generate --stage final --json |
| 251 | └─> svg_to_pptx.py --quick-generate -> exports/*.pptx |
| 252 | + validation/<output_stem>.report.json |
| 253 | + backup/<ts>/svg_output/ [default output path] |
| 254 | |
| 255 | Direct OOXML routes: |
| 256 | analysis/<stem>.slide_library.json + source PPTX + fill_plan.json |
| 257 | └─> template_fill_pptx.py -> exports/*.pptx |
| 258 | source PPTX project copy + enhancement plan + notes/audio/timing assets |
| 259 | └─> native_enhance_pptx.py -> exports/*.pptx |
| 260 | ``` |
| 261 | |
| 262 | The critical split is that `svg_output/` is authored state, while `svg_final/`, `exports/`, and `backup/` are derived delivery or archival state. Deleting that distinction makes validation, re-export, and manual repair much harder to reason about. |
| 263 | |
| 264 | --- |
| 265 | |
| 266 | ## Why SVG? |
| 267 | |
| 268 | SVG sits at the center of this pipeline. The choice was made by elimination. |
| 269 | |
| 270 | **Direct DrawingML generation** seems most direct — skip the intermediate format, have AI output PowerPoint's underlying XML. But DrawingML is extremely verbose; a simple rounded rectangle requires dozens of lines of nested XML. AI has far less training data for it than SVG, output is unreliable, and debugging is nearly impossible by eye. |
| 271 | |
| 272 | **HTML/CSS** is one of the formats AI knows best. But HTML and PowerPoint have fundamentally different world views. HTML describes a *document* — headings, paragraphs, lists — where element positions are determined by content flow. PowerPoint describes a *canvas* — every element is an independent, absolutely positioned object with no flow and no context. This isn't just a layout calculation problem; it's a structural mismatch. Even if you solved the browser layout engine problem (what Chromium does in millions of lines of code), an HTML `<table>` still has no natural mapping to a set of independent shapes on a slide. |
| 273 | |
| 274 | **WMF/EMF** (Windows Metafile) is Microsoft's own native vector graphics format and shares direct ancestry with DrawingML — the conversion loss would be minimal. But AI has essentially no training data for it, so this path is dead on arrival. Notably, even Microsoft's own format loses to SVG here. |
| 275 | |
| 276 | **SVG as embedded images** is the simplest path — render each slide as an image and embed it. But this destroys editability entirely: shapes become pixels, text cannot be selected, colors cannot be changed. No different from a screenshot. |
| 277 | |
| 278 | SVG wins because it shares the same world view as DrawingML: both are absolute-coordinate 2D vector graphics formats built around the same concepts: |
| 279 | |
| 280 | | SVG | DrawingML | |
| 281 | |---|---| |
| 282 | | `<path d="...">` | `<a:custGeom>` | |
| 283 | | `<rect rx="...">` | `<a:prstGeom prst="roundRect">` | |
| 284 | | `<circle>` / `<ellipse>` | `<a:prstGeom prst="ellipse">` | |
| 285 | | `transform="translate/scale/rotate"` | `<a:xfrm>` | |
| 286 | | `linearGradient` / `radialGradient` | `<a:gradFill>` | |
| 287 | | `fill-opacity` / `stroke-opacity` | `<a:alpha>` | |
| 288 | |
| 289 | This table shows conceptual counterparts, not a commitment to the entire SVG standard or a promise of lossless semantics. Every supported capability must have an explicit mapping in the applicable module selected by the [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md) router, identifying its project-canonical spelling, accepted compatible inputs, target DrawingML expression, fidelity, and rejection boundary; capabilities that support PPTX import must also identify the source PPTX/OOXML semantics. A mapping may be exact, deterministically normalized, an explicit fallback, a sidecar, or unsupported. Package semantics such as notes, animations, and relationships do not need to be forced into SVG, but their owning route must be explicit. |
| 290 | |
| 291 | For a PowerPoint-first, feature-by-feature view of those relationships, see the [PowerPoint Feature ↔ Project SVG Mapping Guide](./powerpoint-svg-mapping.md). It owns the public capability and PPTX-import recovery map; the authority set routed by `shared-standards.md` owns generated authoring. |
| 292 | |
| 293 | The main generation route uses **canonical narrow writes and controlled compatible reads**. New `svg_output/` and reusable templates use only project-canonical spellings—for example, uppercase opaque `#RRGGBB`, with transparency carried by the matching `fill-opacity`, `stroke-opacity`, `stop-opacity`, `flood-opacity`, or atomic-element `opacity`. Historical or manual input proceeds only when the compatibility contract documents it, the conversion has one meaning, and the output is valid. The checker emits a non-blocking warning for such input, and the converter normalizes it at the compilation boundary. Anything that requires guessing, lacks a mapping, or could produce a damaged PPTX is an error. |
| 294 | |
| 295 | Conversion is therefore not format guessing between arbitrary SVG and DrawingML. It is a registered, fidelity-described, testable compilation from project-canonical SVG to DrawingML. |
| 296 | |
| 297 | SVG is also the only format that simultaneously satisfies every role in the pipeline: **AI can reliably generate it, humans can preview and debug it in any browser, and scripts can translate it under an explicit compatibility contract** — all before a single line of DrawingML is written. |
| 298 | |
| 299 | --- |
| 300 | |
| 301 | ## Source Content Conversion |
| 302 | |
| 303 | Source documents (PDF / DOCX / EPUB / XLSX / PPTX / web pages) are normalized before Strategist work starts, but there is no single "everything becomes Markdown and nothing else matters" channel anymore. The current design has two fact channels with explicit ownership: |
| 304 | |
| 305 | | Channel | Artifact | Owner | Used for | |
| 306 | |---|---|---|---| |
| 307 | | Content contract | `sources/` content-type files (primarily `<stem>.md`) | `source_to_md/*` converters + `import-sources` | text, tables, chart values, SmartArt node wording, citations, and source narrative | |
| 308 | | Structured analysis | `analysis/*.json` / `analysis/*.csv` | intake and analysis tools | PPTX identity, slide geometry, native tables/charts, SmartArt relationships, and measurable image facts such as dimensions, aspect ratio, reference count, media type, and renderability | |
| 309 | |
| 310 | For a PPTX source, `project_manager.py import-sources` first moves or copies the original into the project's `sources/` under the ownership boundary, then runs `pptx_intake.py` against that archived path. Only when no explicit or existing canonical same-stem Markdown is present does it finally invoke `ppt_to_md.py`. A normal first import therefore produces both fact channels, while deduplication may skip redundant Markdown conversion and an intake failure is recorded as an import note rather than fabricated analysis. Markdown remains the main generation pipeline's content source. A successful intake bundle writes `<stem>.identity.json`, `<stem>.slide_library.json`, and merges a compact multi-deck index into `analysis/source_profile.json`. Strategist reads the compact index for source facts and opens raw per-deck artifacts only when a workflow needs them. That distinction matters: the main pipeline may rethink page count and story, while `template-fill` and `beautify` promote parts of the same intake facts into stronger constraints. |
| 311 | |
| 312 | Converter-generated image assets are also normalized. Companion `<stem>_files/` directories are imported into the project `images/` pool, `image_manifest.json` is merged by filename, and Markdown asset references are rewritten when imported names change. Office vector images (`.emf` / `.wmf`) are first-class runtime assets: they are not rasterized during intake, `finalize_svg.py` leaves them external for the native path, and `svg_to_pptx.py` embeds them as Office vector media so CJK fonts and vector detail are not lost. |
| 313 | |
| 314 | Two converter design choices still shape the system: |
| 315 | |
| 316 | **Native-Python first, external binaries as fallback.** Common formats are handled by pure-Python wheels; pandoc is only invoked for the long tail of niche formats. Forcing every user to install system binaries they may not have permission for is a usability tax that does not pay off when most inputs are docx / pdf / html / pptx. |
| 317 | |
| 318 | **TLS fingerprint impersonation for high-security sites.** Web fetching uses the Python `web_to_md.py` path by default and relies on `curl_cffi` when available for Chrome-like TLS impersonation. WeChat Official Accounts and several CDNs block Python's default handshake outright; keeping this in the Python converter path avoids making a Node fetcher the primary architecture. |
| 319 | |
| 320 | --- |
| 321 | |
| 322 | ## Project Structure & Lifecycle |
| 323 | |
| 324 | `project_manager.py init` creates the standard project working directories; |
| 325 | `--quick-generate` creates `svg_output/` plus the cold |
| 326 | `validation/workflow.log` audit log, omits the project README, and leaves |
| 327 | other directories on demand. The explicit |
| 328 | [`quick-generate`](../skills/ppt-master/workflows/profiles/quick-generate.md) |
| 329 | profile omits planning artifacts and `svg_final/`, but its project may still |
| 330 | contain converted sources, analysis, images, icons, rendered formulas, and |
| 331 | required resource manifests. It hand-authors `svg_output/`, writes a lockless |
| 332 | final quality report, and retains the ordinary postflight and default-path |
| 333 | backup around the final PPTX. The audit log and reports preserve tool outcomes, |
| 334 | not the AI's design reasoning or a resumable stage state. The default delivery |
| 335 | lifecycle is: |
| 336 | |
| 337 | | Directory | Role | |
| 338 | |---|---| |
| 339 | | `sources/` | archived originals, normalized Markdown, and converter companion files | |
| 340 | | `analysis/` | machine-extracted facts: PPTX intake bundles and regenerated image analysis | |
| 341 | | `images/` | single runtime image pool for user, extracted, formula, web, AI, sliced, EMF/WMF assets | |
| 342 | | `icons/` | project-local icon set copied by `icon_sync.py`; global library fallback at export exists only for legacy compatibility | |
| 343 | | `templates/` | copied template specs / SVG references / non-image template assets | |
| 344 | | `svg_output/` | the only hand-authored SVG source directory | |
| 345 | | `svg_final/` | mandatory normal-flow derived visual-preview SVGs; supported bitmap/SVG resources are inlined when possible, while EMF/WMF retain an external-reference exception; used for IDE/browser preview or manual insertion as SVG pictures | |
| 346 | | `live_preview/` | preview server state, edit history, and annotation logs | |
| 347 | | `notes/` | `total.md` and split per-slide speaker notes | |
| 348 | | `validation/` | cold workflow audit log, SVG quality reports, and PPTX postflight audit reports | |
| 349 | | `exports/` | timestamped native PPTX deliverables | |
| 350 | | `backup/<timestamp>/` | default export creates the timestamped directory, then attempts a frozen `svg_output/` copy; copy failure does not fail export, but directory-creation failure is not currently downgraded | |
| 351 | |
| 352 | The CLI supports `--move`, `--copy`, and an automatic default, with one fixed ownership boundary: only sources already under the repository's `projects/` tree may move into a target project's `sources/`; every other local path is copied and remains untouched, even when `--move` is supplied. `--copy` preserves a projects-local input. Generate PPTX uses the automatic mode so canonical repository documents and external user files cannot be removed during intake. |
| 353 | |
| 354 | --- |
| 355 | |
| 356 | ## Architecture Invariants |
| 357 | |
| 358 | Executable artifact ownership invariants are authoritative in [`artifact-ownership.md`](../skills/ppt-master/references/artifact-ownership.md); this section explains why those boundaries matter architecturally. |
| 359 | |
| 360 | These invariants are stronger than ordinary implementation preferences. If a change violates one, it is probably changing the architecture rather than refactoring it. |
| 361 | |
| 362 | | Invariant | Practical consequence | |
| 363 | |---|---| |
| 364 | | `sources/` content-type files are the Generate content contract | text, tables, and chart values come from content-type files in `sources/` (Markdown is primary, but `.txt` / `.csv` / `.json` / `.yaml` / … count too); known sidecars (`*.conversion_profile.json`, `*_files/image_manifest.json`) are excluded | |
| 365 | | `analysis/` stores machine facts, not design contracts | `source_profile.json` and intake artifacts inform Strategist in the default pipeline and the current agent in `quick-generate`; they do not lock page count/order except in workflows that say so | |
| 366 | | `design_spec.md` explains the design; `spec_lock.md` executes it in the default pipeline | both remain owning artifacts there; `quick-generate` persists neither or any substitute plan, and the current agent follows explicit user requirements while keeping every remaining content, page, visual, and resource decision only in active context; context loss restarts Quick | |
| 367 | | Planning context is retained until invalidated | continuous execution reuses the complete Design Spec, lock, and triggered references; fresh/resumed/restarted or compacted execution reloads them once | |
| 368 | | `page-context` is on demand | the read-only projector supports diagnostics, deterministic routing checks, and optional usage telemetry; it is not a pre-page gate | |
| 369 | | `svg_output/` is the only hand-authored SVG directory | quality checks, manual edits, re-export, and `update_spec.py` target authored source | |
| 370 | | `svg_final/` is mandatory but derived in default delivery | it is regenerated from `svg_output/` for visual preview or manual insertion as an SVG picture; supported resources are inlined when possible while EMF/WMF retain an external-reference exception, and it never becomes the native export source of truth; quick-generate skips this artifact | |
| 371 | | Native PPTX export reads `svg_output/` by default | converter preserves icons, `preserveAspectRatio`, rounded rects, and native image crop metadata before finalization rewrites them | |
| 372 | | PowerPoint Convert to Shape is outside the compatibility contract | `svg_final/` may be inserted as an SVG picture, but the converted structure and visual result are not guaranteed and do not constrain the supported SVG feature set | |
| 373 | | Direct OOXML routes do not enter the SVG pipeline | preservation workflows patch native PPTX parts directly | |
| 374 | | Image facts come from regenerated metadata | `analysis/image_analysis.csv` is re-derived from the live `images/` folder; in the default pipeline Strategist uses source context first and inspects only a specifically ambiguous asset when semantics or safe placement cannot otherwise be resolved, while in `quick-generate` the current agent applies the same bounded analysis while preparing resources; SVG authoring does not rescan source pixels | |
| 375 | | Raw PPTX templates are not Step 3 candidates | Step 3 accepts only exact reusable-template workspace roots as candidate input | |
| 376 | |
| 377 | --- |
| 378 | |
| 379 | ## Canvas Format System |
| 380 | |
| 381 | PPT Master is not PPT-only — the same SVG → DrawingML pipeline produces square posters, 9:16 stories, A4 prints. Format-specific conventions (ratios, safe zones, brand areas) live in [`references/canvas-formats.md`](../skills/ppt-master/references/canvas-formats.md). |
| 382 | |
| 383 | The architectural choice worth flagging: **viewBox is in pixels, not absolute units.** Pixel space makes layout reasoning unambiguous for the AI Executor (`x="100"` is unambiguously left + 100px) and inspectable in any browser. Conversion to PowerPoint's EMU happens once at export — picking pixels means the rest of the pipeline (Strategist, Executor, quality checker, post-processing) never thinks in EMU, which would be hostile both to AI generation and to human debugging. |
| 384 | |
| 385 | --- |
| 386 | |
| 387 | ## Template System & Selection |
| 388 | |
| 389 | Template use is **opt-in, not inferred**. Default Step 3 only prepares |
| 390 | candidates; it never opens UI or reads template content. Stage 1 displays its |
| 391 | template-independent communication recommendation together with a switchable |
| 392 | free-design/template choice. Ordinary requests default to free design; explicit |
| 393 | template intent or any supplied root defaults to template mode. Exactly one root |
| 394 | may be preselected, while multiple roots remain unselected candidates. The |
| 395 | system never chooses a template from topic similarity. |
| 396 | |
| 397 | **Why free design remains an explicit option.** Templates are floors that easily become ceilings: they lock the deck into the template's visual idioms regardless of how the content actually wants to be presented. Free-design layouts derive structure from the source content rather than imposing it from a fixed grammar, so the visual rhythm tracks the content rather than fighting it. Constrained mode is genuinely better in narrow cases (brand-locked decks, strongly typed scenarios like academic defense or government reports), while the selector keeps the final choice with the user. |
| 398 | |
| 399 | **Exact selection, not semantic matching.** A bare name like |
| 400 | `presentation_core`, a brand mention, or a style phrase such as "McKinsey |
| 401 | style" is never fuzzy-matched to a directory. The default page lists registered |
| 402 | Brand/Style/Layout/Deck entries only from their four `*_index.json` files; |
| 403 | chat discovery reads the same indexes and returns exact roots. Explicit paths |
| 404 | remain valid, and an exact path matching a registered canonical root may be |
| 405 | displayed as `library`; an unregistered root remains `explicit`. Current |
| 406 | workspaces resolve `templates/design_spec.md`; the server parses every explicit |
| 407 | root's real `kind`, while the source label remains provenance only. Compatible flat Brand/Layout/Deck |
| 408 | packages may resolve direct `design_spec.md` only when they satisfy the current |
| 409 | kind contract, including current structured SVGs for Layout/Deck. Style has no |
| 410 | legacy-flat form. A free-form style brief remains ordinary Stage-2 input and |
| 411 | does not activate a Style workspace. Directory shape never authorizes structure |
| 412 | migration. A package with legacy Master/Layout/placeholder semantics must be |
| 413 | replaced by a newly created template workspace before Step 3. |
| 414 | |
| 415 | All current Brand/Style/Layout/Deck packages use one workspace routing contract. Brand and Style workspaces omit the SVG roster; empty optional directories are omitted: |
| 416 | |
| 417 | ```text |
| 418 | <template_workspace>/ |
| 419 | ├── templates/ # design_spec.md; Create Layout / Create Deck also include SVG prototypes |
| 420 | ├── images/ # optional; bitmap assets referenced as ../images/<name> |
| 421 | ├── icons/ |
| 422 | │ └── imported/ # optional; canonical imported vector assets |
| 423 | └── exports/ # optional, on-demand review files; Git-ignored in the library |
| 424 | ``` |
| 425 | |
| 426 | Style narrows this routing shape to `templates/design_spec.md` only; it does |
| 427 | not carry asset or review payloads. Existing project scaffolding is not Style |
| 428 | input. |
| 429 | |
| 430 | `<template_workspace>` is either `skills/ppt-master/templates/<kind>/<id>/` or |
| 431 | another exact workspace root such as `projects/<name>/`. Step 3 records it as |
| 432 | candidate input without reading template content. Once Stage 1 selects it, the |
| 433 | apply stage validates, fuses, and installs it into the current project's |
| 434 | `templates/`, `images/`, and `icons/`; it never copies `exports/`. Strategist |
| 435 | and later roles read only that project-local copy when template-aware planning |
| 436 | begins after Stage 1. The source workspace remains portable between |
| 437 | locations without reshaping; global index registration controls whether it |
| 438 | appears as a library choice. |
| 439 | |
| 440 | For Create Layout / Create Deck, `standard` and `fidelity` write new SVG documents and a new Master/Layout/slot system; source topology is visual evidence only and is neither preserved nor distilled. `mirror` materializes a new workspace from the source page order, Master/Layout identities and parentage, placeholder facts, and supported visuals that are actually present and validated, without semantic synthesis or gap filling. Layout mirror is legal only when that preserved source is already brand-neutral and application-neutral; otherwise author a new Layout or retain the facts as Deck. Because structural layers cannot be `<g>`, fixed-layer source group wrappers are mechanically expanded into direct atoms while preserving ownership, paint order, and appearance. Create Brand analyzes identity fragments only; Create Style extracts portable method/direction only. Neither enters structural replication strategies or produces an SVG roster. |
| 441 | |
| 442 | The four template kinds own different segments of the design contract: |
| 443 | |
| 444 | | Kind | Owns | Typical contents | Effect on Strategist | |
| 445 | |---|---|---|---| |
| 446 | | `brand` | identity | colors, typography, logo, voice, icon style | locks identity; structure remains free | |
| 447 | | `style` | direction / method | communication method, open page roles, evidence/data rules, visual defaults, image/icon direction, advisory review focus | seeds Stage 2; Style-only stays flat, while fusion follows the selected Layout/Deck structure; never becomes identity truth or triggers visual review | |
| 448 | | `layout` | brand-neutral structure | canvas, page structure, semantic text roles/spatial behavior, page types, SVG roster | exposes structure; identity and communication application remain downstream decisions | |
| 449 | | `deck` | application + integrated identity/structure | recurring situations, audiences/outcomes, representative page roles, identity, and actual SVG roster | contributes descriptive context and prototypes that Strategist compares with the independently confirmed Stage-1 contract and current content before deriving the application plan | |
| 450 | |
| 451 | Theme, Slide Master, Slide Layout, and Placeholder are compiled PowerPoint |
| 452 | objects, not additional template kinds. Layout owns topology, placement, |
| 453 | semantic text roles, and spatial behavior; Brand owns identity values and |
| 454 | assets. Under `template_reuse_scope: layout`, export resolves final placeholder |
| 455 | formatting from those rules plus the confirmed reading mode/type scale; |
| 456 | `mirror` preserves literal source formatting and text topology. Export may |
| 457 | place both rule sets into the same native Master/Layout graph. |
| 458 | |
| 459 | When several workspaces are selected, fusion is segment-level, not field-level. Brand owns identity, Style owns direction/method defaults, Layout owns compatible structure, and Deck retains descriptive reusable-application context plus any identity/structure not overridden. Library/explicit provenance never changes that order. The current project's application contract comes only from confirmed Stage 1; Deck context is comparison input for Stage 2, not an override. User confirmation remains highest. Style palette/type defaults never override Brand/Deck identity; its method/composition expectations must be compatible with the selected Deck context and Layout/Deck structure or fusion surfaces a conflict. A project-local Brand + Layout composition gets its application context from Stage 1 and is not automatically promoted into a reusable library Deck. Same-kind conflicts are surfaced rather than resolved by implicit ordering. This keeps template composition debuggable: a fused spec can say exactly which bundle owns each segment. |
| 460 | |
| 461 | **Raw PPTX files cannot be Step 3 workspaces.** Normal Generate may use a PPTX as source material, and `beautify-pptx` may redesign it while preserving page count, order, and per-page wording 1:1; neither treats the source PPTX as a Step 3 template. When a raw PPTX is used as a template or native slide shell and filled with new material, the default route is Fill Native PPTX. If the request permits splitting, merging, dropping, reordering, or narrative restructuring, it remains Generate. Only a request to create a reusable template workspace and reuse that design system in SVG-route Step 3 first runs Create Template and then supplies the generated workspace root. |
| 462 | |
| 463 | **Template contracts are opt-in; charts and icons are not.** The asymmetry is intentional: Layout locks reusable structure, Style locks direction/method defaults, Brand locks identity, and Deck combines a recurring application with identity and structure. Charts and icons are reusable primitives that do not by themselves impose a deck-wide contract. Same `templates/` directory, different ownership. |
| 464 | |
| 465 | --- |
| 466 | |
| 467 | ## Role System: Specialized Modes in a Single Pipeline |
| 468 | |
| 469 | PPT Master keeps deck-state roles—Strategist, Image_Generator, and Executor—inside one main agent rather than distributing them across parallel sub-agents. They are instruction scopes loaded on demand, not independent agents with stale copies of the deck state. A supporting stage may use a bounded sub-agent only when its authority defines a durable artifact hand-off that does not depend on shared deck state. The core choice has three connected reasons: |
| 470 | |
| 471 | **Why one agent, not parallel sub-agents.** Page design depends on the full upstream context — Strategist's color choices, the image resources that actually got acquired (vs failed and substituted), prior pages' visual rhythm. Sub-agents would start with a stale partial snapshot of that context and produce visually drifting decks. The same logic forbids batched page generation (e.g., five pages per turn): batching accelerates context compression and the deck's visual consistency degrades faster than the speed gain is worth. |
| 472 | |
| 473 | **Why role-specialized references, not one mega prompt.** Strategist runs in "negotiate with user" mode (open-ended, conversational, willing to back up); Executor runs in "produce strict XML" mode: it may not reselect upstream decisions or omit required attributes, but it still owns geometry, composition, hierarchy, and visual treatment inside implementation dimensions the Design Spec leaves open. Mixing both into one prompt forces the model to hold incompatible discipline in the same turn — every prompt-engineering pathology of mode-mixing shows up. Splitting into per-role files lets each role load only what it needs and discard the rest. |
| 474 | |
| 475 | **Template choice and communication share Stage 1.** Step 3 prepares candidates |
| 476 | without interaction, while the Stage-1 communication recommendation is authored |
| 477 | without reading those candidates or any template content. The UI confirms that |
| 478 | communication contract and the switchable free-design/template choice together; |
| 479 | only afterward does the agent install/fuse a non-free selection. Strategist uses |
| 480 | one dependency-ordered two-stage gate. Its `delivery_context` recommendation distinguishes presenter-led, reader-led, hybrid, and recorded/self-running use in one prose field, names the primary context, and records any secondary use; hybrid never stands alone without its lead mode. The prose boxes remain editable and none requires a non-empty answer: confirmation persists the current text exactly, and a cleared value stays empty instead of falling back to the recommendation. Final Stage 2 is authored once from that contract and confirms both the complete deck solution and its production mechanics: reading mode, narrative mode, page count, coordinated visual system, image sources, generated-image rendering, conditional AI acquisition, formula policy, generation mode, the Design Spec review toggle, and whether the agent should proactively generate speaker notes, custom animations, or narration audio. Only after Stage 1 is confirmed, when a template is installed, does Strategist read the project-local workspace and current content, derive **how to apply it**, and expose that plan as editable `template_application` prose; Stage 2 never reselects a template, and the internal reuse/adherence modes stay hidden. Reading mode decides how meaning is carried by page, visuals, presenter, and notes; its cards do not present px values. The browser may apply the deterministic `reading mode → body baseline → unpinned role sizes` dependency locally, while manual size edits pin visible values. It never regenerates Stage 2. The three proactive values are fallback policies, not capability bans: the latest explicit user instruction wins, then final Stage 2, then the fixed defaults `true / false / false`. Strategist still records non-binding Motion suggestions when useful; a suggestion alone does not activate custom-animation execution. Generated images inherit the selected deck color anchors directly; there is no independent image-palette choice. Final state has two equivalent carriers: the default UI path reads `confirm_ui/result.json` exactly once after the final wait, while an explicit chat-only or delegated path retains an equivalent final confirmation summary and may produce no `result.json`. Both paths first resolve and persist every effective production outcome into one `design_spec.md` and complete Gate 1 fidelity. With refinement off, lock authoring proceeds immediately. With `refine_spec: true`, the pipeline stops before `spec_lock.md`; the user may revise any part of that same Design Spec through normal chat for any number of rounds, and explicit approval then releases Gate 2 lock authoring. No second Design Spec or parallel lock is maintained. Normal lock authoring and downstream execution do not reread either confirmation channel. Required manual assets may still introduce their own conditional blocking points, so this is not an exclusive claim over every runtime gate. Project validation requires the compact `audience` / `objective` / `core_message` anchor set under `spec_lock.md ## communication` plus an `Audience move` in every §IX Slide block. |
| 481 | |
| 482 | The three proactive values confirmed in final Stage 2 remain independent raw |
| 483 | evidence. In particular, enabling narration may enable the effective Speaker |
| 484 | Notes outcome in the Design Spec, but it never rewrites the raw speaker-notes |
| 485 | choice. |
| 486 | |
| 487 | **Image analysis is metadata-first, with a narrow visual fallback.** When images exist, `analyze_images.py` supplies the regenerated measured facts in `analysis/image_analysis.csv`; the CSV is a view over the live `images/` folder, not a durable cache. In the default pipeline, Strategist first resolves supplied images from source placement and nearby prose, captions / alt text / titles, filenames, user notes, existing resource records, and that metadata. It may inspect one specific image only when a material ambiguity remains about selection, factual identity, page role, crop safety, or focal placement—never as a bulk inventory scan. The answer is written into Design Spec §VIII, after which Executor uses the plan and measured geometry without reopening source pixels for semantic discovery. In `quick-generate`, the current agent applies the same bounded analysis while preparing the selected resources from active-context decisions; no Design Spec projection or general resource roster is written. User images, extracted images, web images, AI outputs, formulas, and sliced elements still converge into the same measured fact table. |
| 488 | |
| 489 | **Retained planning context** carries continuity; the on-demand page projector is only a diagnostic described below. |
| 490 | |
| 491 | --- |
| 492 | |
| 493 | ## Execution Discipline |
| 494 | |
| 495 | Generate routing selects one runtime authority before loading its procedure: [`workflows/generate-pptx.md`](../skills/ppt-master/workflows/generate-pptx.md) owns Default Step 1–7, while [`quick-generate.md`](../skills/ppt-master/workflows/profiles/quick-generate.md) owns the self-contained Quick lifecycle. [`beautify-pptx.md`](../skills/ppt-master/workflows/profiles/beautify-pptx.md) selects between them from explicit Quick intent and keeps its 1:1 constraints in either branch. [`SKILL.md`](../skills/ppt-master/SKILL.md) owns only global execution discipline and the mandatory handoff to `routing.md`. Together, these rules may look bureaucratic but exist because LLMs default to "let me solve the whole problem in this turn", which is exactly the wrong shape for a serial pipeline where each step's output is bounded, checkpointed, and consumed by the next. They close failure modes that surfaced repeatedly in practice: out-of-order execution, AI proxying user design decisions, cross-phase bundling, missing prerequisites, speculative pre-work, sub-agent context loss, page-batching drift, long-deck color/font drift, batch/script-generated SVG drift, and routing ambiguity. |
| 496 | |
| 497 | Global stop/continue policy is authoritative in [`failure-recovery.md`](../skills/ppt-master/workflows/governance/failure-recovery.md); its concrete recovery matrix and resume pointers currently cover Generate PPTX. This section does not duplicate those rules. |
| 498 | |
| 499 | Three boundaries are especially important to the architecture. First, page SVGs must be hand-authored by the current main agent, one page at a time; writing a Python/Node/shell generator to emit pages is prohibited because the resulting deck loses cross-page judgment and visual continuity. Second, default-pipeline cadence is `P01 → first-page gate → uninterrupted remaining pages → final gate`. P01 is a method sample: execution emits a `gate-signal`, then carries resolved method rules into later pages; no checker call or page batch interrupts P02 through the final page. `quick-generate` retains serial hand-authoring and P01 as its visual anchor, skips the first-page gate, and runs one lockless final gate after the complete roster exists. Third, routing is deterministic: raw PPTX template requests, beautify-profile requests, native enhancement, custom-animation stages, live-preview stages, and other registered triggers are not turned into open-ended user route questions when the repository already defines the boundary. |
| 500 | |
| 501 | In the default pipeline, the Role Switching Protocol (mandated read of `references/<role>.md` before mode change) serves two reinforcing purposes: forcing fresh role instructions into context overrides drift from the previous mode, and the visible marker in the conversation transcript creates an audit trail so the user can see when the agent moved between modes — critical when reviewing why a particular decision was made. |
| 502 | |
| 503 | --- |
| 504 | |
| 505 | ## Spec Propagation: spec_lock.md as Contextual Execution Contract |
| 506 | |
| 507 | In the default pipeline, the Strategist phase produces two artifacts that look redundant but serve different masters: |
| 508 | |
| 509 | - `design_spec.md` — human-readable narrative; the "why" of the deck (communication intent, audience outcome, narrative / template / visual rationale, page outline) |
| 510 | - `spec_lock.md` — machine-readable execution contract; the compact `audience` / `objective` / `core_message` communication anchors plus stable identity/reuse roles and routing values (core HEX/font roles, icon library, image resources, and structure mappings) |
| 511 | |
| 512 | Why both? `design_spec.md` preserves the complete confirmed solution and rationale; `spec_lock.md` names the subset that must remain stable or routable across pages. It is authored from that Design Spec plus the page/resource/template context, not copied field by field from raw UI JSON or chat-summary payloads. [Generate PPTX Step 6](../skills/ppt-master/workflows/generate-pptx.md#step-6-executor-phase) retains both artifacts once per valid execution context. Fresh/resumed/restarted execution, compaction, or summary-only recovery reloads both once; an unchanged continuous context does not reread either file. Contextual tints, gradient/effect paints, and sparse non-structural display-font accents remain page decisions; recurrence or a stable semantic role requires an upstream lock role. |
| 513 | |
| 514 | The view omits universal SVG/icon prohibitions already owned by the always-loaded Executor core and retains only project-specific forbidden rows. It selects images from the current page brief, explicit image-resource page assignments, and mirror prototype references. Images assigned elsewhere are excluded; any unresolved legacy image remains in a compatibility subset, and `confirmed-none` appears only when every locked image has a deterministic assignment elsewhere. |
| 515 | |
| 516 | The lock is also the per-page routing table. Beyond global colors and typography, it carries `page_rhythm` (`anchor` / `dense` / `breathing`), `page_charts` (the selected page-local chart-catalog reference, which triggers reading the corresponding SVG and §VII Usage but does not lock the final chart type or geometry), image rows with placement/cropping contracts, and the locked `mode` / `visual_style` values that decide which execution rule files are loaded. A selected custom direction also carries its resolved `mode_behavior` / `visual_style_behavior`. When it actually combines or borrows catalog entries, the lock records their exact ids in optional `mode_references` / `visual_style_references` / `image_rendering_references`, and execution reads every listed file before synthesis; a genuinely novel custom omits the corresponding reference field. `template_reuse_scope: mirror|layout` locks additionally carry `page_layouts` (which input template SVG each page inherits), unique `pptx_masters` / `pptx_layouts` definitions, and `page_pptx_layouts` assignments. `template_reuse_scope: style`, free-design, and brand-only projects use `pptx_structure.mode: flat` and omit those sections entirely rather than writing empty values. Empty entries elsewhere are meaningful signals: no chart or no image is often a design decision rather than missing data. |
| 517 | |
| 518 | `page-context v2` remains an on-demand projector. Each invocation emits a compact global anchor set bound to `lock_source.sha256`, the current §IX/resource/routing delta, and scoped path/SHA fingerprints for large references; the projection is not a color/font allowlist or a replacement authority. It is used only for explicit diagnostics/telemetry or an unresolved page/template/chart path-SHA question. A bounded exact repair in a valid uncompacted context may use targeted fragment readback plus validation; fresh, compacted, external, unknown, structural, or mismatched changes require one complete Design Spec and lock read. Flat pages have no prototype reference; structured pages use the authoritative complete SVG. Manifests and text-slot sidecars remain derived tool diagnostics and are never injected into page authoring. |
| 519 | |
| 520 | `--record-usage` writes a derived, input-hashed compact-output snapshot for an invoked page under `analysis/page-context/`. Token counting lazily uses `o200k_base`; a missing `tiktoken` installation records `tokens: null` without blocking execution. `page-context-report` excludes stale snapshots, reports existing snapshots, and lists unique reference fingerprints; telemetry may be partial. The once-loaded reference payloads and other session context remain intentionally unmeasured. |
| 521 | |
| 522 | `update_spec.py` propagates an intentional deck-wide anchor change in two coordinated steps: plan and literal-replace the value across every `svg_output/*.svg`, then write the authoritative `spec_lock.md` only after those SVG updates succeed. The tool's scope is deliberately narrow — only `colors.*` (HEX values, case-insensitive replacement) and universal `typography.font_family` (attribute-scoped). A universal font replacement also sets every existing `typography.*_family` lock row to the same value in one lock-file write, so title/body/role locks cannot retain values that the command has removed from every SVG. Other fields (font sizes, per-role font changes, icons, images, canvas) are intentionally **not supported** because their replacements would need attribute-scoped or semantic awareness whose risk/benefit doesn't justify bulk propagation. This reverse lock update is also valid when repeated contextual use is deliberately promoted into a named semantic role; it must not be used merely to empty an informational checker comparison. For unsupported fields, edit the owning artifact and re-author the affected pages. |
| 523 | |
| 524 | The tool refuses to back up: it relies on git for revert. Adding a backup mechanism would just duplicate git's job and create stale snapshots. |
| 525 | |
| 526 | --- |
| 527 | |
| 528 | ## Materials → Plan → Realization: the Kitchen Contract |
| 529 | |
| 530 | The cooking analogy is the canonical ownership model for the default Generate |
| 531 | pipeline, not just explanatory prose. `quick-generate` removes the separate |
| 532 | Strategist and confirmation layer; it does not remove preparation. |
| 533 | |
| 534 | | Restaurant | PPT Master | Authority | |
| 535 | |---|---|---| |
| 536 | | Customer and initial ingredients | User confirmation and supplied sources/assets | Defines facts, intent, exclusions, acquisition permissions, and how specific the requested outcome is | |
| 537 | | Service coordinator | Generate workflow | Sequences the declared stages, gates, role switches, and handoffs without taking over any role's decisions or deterministic tool's checks | |
| 538 | | Menu planner and preparation lead | Strategist, `design_spec.md`, `spec_lock.md`, and Strategist-owned acquisition stages | Assesses sufficiency; fills permitted factual gaps; selects the content, resources, page roster, chart-reference/template-layout keys, fonts, palette anchors, icon system and curated pool, and crop boundaries; records optional capability/expression recommendations; readies the complete project-local inventory before execution | |
| 539 | | Cook | Executor | Uses only prepared project-local assets and realizes the plan through geometry, composition, hierarchy, spacing, and treatment without changing the selected “dish” or acquiring/substituting ingredients; chooses suitable prepared icons per page and may adapt fields explicitly labeled as suggestions or References | |
| 540 | | Quality inspector | `svg_quality_checker.py` | Reads authoring state and reports contract findings; it does not edit pages, own the page roster, or package the deck | |
| 541 | | Packager | `svg_to_pptx.py` | After a matching final report passes, compiles the authored SVG, validates the package, and publishes the receipt; it does not repair SVG or rerun the checker | |
| 542 | | Run recorder | `workflow_transcript.py`, `workflow_log.py`, and `validation/workflow.log` | Records Python command envelopes, material tagged outcomes, bounded status samples, and omission counts, then accepts explicitly selected important non-Python events; it does not decide whether the workflow may advance | |
| 543 | |
| 544 | **Quick generation collapses planning into the current agent.** Source conversion, |
| 545 | factual-gap research, and resource preparation still run when needed. The agent |
| 546 | automatically selects the content, page roster, mode, visual style, and resource |
| 547 | needs in active context; scans images, icons, native shapes, charts/tables, |
| 548 | formulas, and simple typography/geometry as available carriers; prepares the |
| 549 | selected supplied/extracted/AI/web/sliced images, icons, and formulas with their |
| 550 | required operational manifests or provenance records; and then hand-authors |
| 551 | SVG. It does not invoke Strategist, Confirm UI, `design_spec.md`, |
| 552 | `spec_lock.md`, or a substitute planning artifact. These decisions are not |
| 553 | recoverable after context loss. |
| 554 | One agent may therefore perform several creative stages in sequence, but their |
| 555 | ownership boundaries do not merge; checker, exporter, and transcript recorder |
| 556 | remain separate deterministic tools. |
| 557 | |
| 558 | **Default preparation has two clocks.** Topic Research supplies facts before final confirmation: it starts immediately for topic-only input, or after supplied material is converted/read when planning-critical factual gaps remain. It supplements only those gaps and acquires no images. When the current AI editor provides an isolated worker with web/fetch access and write access to the declared outputs, the main agent defines the gaps and the worker writes the existing research/provenance artifacts, returning only a receipt; otherwise research runs in the main context. AI / web / slice image acquisition runs only after final confirmation and the completed `design_spec.md §VIII` / `spec_lock.md`, then reaches a terminal status before Executor starts. Strategist also resolves, syncs, and validates a curated project icon pool while authoring the final plan. Image_Generator, Image_Searcher, and icon-sync tooling are preparation mechanisms under Strategist ownership, not independent decision owners. Quick generation uses those preparation mechanisms as needed under the current agent's in-context decisions, without inserting a confirmation gate. |
| 559 | |
| 560 | **Prepared project-local assets are the boundary.** In the default pipeline, images and other declared resources remain available only when Strategist has selected them, recorded them in the planning artifacts, and made their project paths resolvable or explicitly `Needs-Manual`. Icons are prepared when their SVG files exist under `<project>/icons/`; `spec_lock.icons.inventory` indexes the Strategist's curated synced bundled pool but neither assigns page usage nor exhaustively whitelists execution. Executor chooses among prepared icons per page. In quick generation, active-context resource decisions and their project-local files/manifests replace that planning projection; no general roster or page assignment is written. The current agent may acquire and prepare those resources before SVG authoring. Files elsewhere on disk are not authorized. Missing material returns to the owning preparation step; SVG authoring never silently substitutes it. |
| 561 | |
| 562 | **Specificity controls freedom.** “Make Mapo tofu” fixes the result's identity: technique and presentation may vary, but tomato-and-eggs or tofu soup is a substitution. “Make a tofu dish” leaves an in-class choice. In the default pipeline, Strategist may resolve that choice; if the Design Spec deliberately leaves a dimension broad, Executor may realize it within that envelope. Once the Design Spec names a binding choice, execution cannot reopen it. In quick generation, the current agent resolves the equivalent choice in active context and keeps it stable while authoring. Fields explicitly labeled as suggestions or References—including a preferred page-local image pattern—remain expression guidance that may be adapted without changing content, resources, identity, or explicit constraints. |
| 563 | |
| 564 | **Garnish remains local.** Sparse page-local font or color accents may add hierarchy, differentiation, or atmosphere without becoming a second visual system. In the default pipeline, structural/recurring fonts, palette roles, resources, or recurring cross-page identity patterns remain Strategist decisions and require an upstream Design Spec/lock update before reuse; in quick generation, the current agent establishes those anchors in active context and preserves them across pages. A default-pipeline page-local §VIII image pattern remains a preferred composition reference. |
| 565 | |
| 566 | **Prompt-refactor invariant.** In the default pipeline, compression must preserve initial materials, user confirmation, Strategist-owned preparation, planning ownership, and execution freedom as separate layers. Moving acquisition into Executor, turning permission into quota, flexible realization into silent resource/identity reselection, or an exact binding plan into an approximate target is a semantic regression. The explicit quick profile consolidates the first layers under the current agent; it does not erase source, resources, aesthetics, data visualization, or native-shape capability. Default runtime authority lives in [`strategist.md`](../skills/ppt-master/references/strategist.md) and [`executor-base.md`](../skills/ppt-master/references/executor-base.md); Quick runtime authority starts at [`quick-generate.md`](../skills/ppt-master/workflows/profiles/quick-generate.md) and directly loads the applicable shared and conditional execution references without inheriting Default's persisted-plan prerequisites. Prompt-writing governance lives in [`prompt-style.md`](./rules/prompt-style.md). |
| 567 | |
| 568 | --- |
| 569 | |
| 570 | ## Image Acquisition & Embedding |
| 571 | |
| 572 | Several architectural decisions shape this phase: |
| 573 | |
| 574 | **Provider-specific config keys, not a generic `IMAGE_API_KEY`.** Every backend takes its own `OPENAI_API_KEY` / `MINIMAX_API_KEY` / etc. and the active one is selected by an explicit `IMAGE_BACKEND=<name>`. A unified `IMAGE_API_KEY` field looks tidier on first glance but causes silent confusion when a user has multiple providers configured at once and isn't sure which one is active — the kind of fault that surfaces only as "image generation gives weird results" with no clear failure point. Forcing per-provider keys makes "which backend am I using" a config-readable fact, not an inference. |
| 575 | |
| 576 | **Permissive-by-default license filter, with strict mode for credit-incompatible layouts.** Web image search defaults to allowing CC BY / CC BY-SA images with inline attribution — most slides have visual room for a credit element. `--strict-no-attribution` is the escape hatch for full-bleed hero images and tight composition where there's no place to put a credit without breaking the design. Non-commercial (CC BY-NC*) and no-derivatives (CC BY-ND*) licenses are auto-rejected because the typical PPT Master output is shared in commercial or modified contexts; a permissive default with that floor is the failure mode users actually want. |
| 577 | |
| 578 | **Manifest-first acquisition.** In-pipeline AI generation always writes `images/image_prompts.json` and renders the sidecar `image_prompts.md`, even for one image. The positional `image_gen.py "prompt"` form is intentionally limited to one-off debugging because it leaves no manifest/sidecar audit trail. Web acquisition mirrors this with `images/image_queries.json` for multi-row batches and `image_sources.json` for attribution/source tracking. |
| 579 | |
| 580 | **The Design Spec owns the image-execution path.** Final confirmation from either the UI or chat is first persisted as `AI Image Acquisition Path` in `design_spec.md §I`; Image_Generator selects API, host-native, or manual from that value and may not reopen the decision during execution. `image_gen.py --manifest` belongs only to API Path A. The current CLI still contains a defensive guard that reads UI `result.json` and blocks an accidental Path A call when that file explicitly records `host-native` or `manual`. That guard is not an authority source, does not cover chat-only confirmation, and cannot replace Design Spec routing. It is a remaining implementation mismatch in the upstream authority chain, not a normal consumer path. |
| 581 | |
| 582 | **One coherent sheet when related spot illustrations fit it.** Several same-family spots may share one AI illustration sheet plus `slice` rows when their cell shapes, detail, quality, and semantic needs are compatible; otherwise they may be generated independently. When the sheet path is chosen, `slice_images.py` cuts it into named transparent elements, those derived files join `images/`, and `analyze_images.py` is rerun so Executor sees their real dimensions. |
| 583 | |
| 584 | **Terminal status before Executor.** Rows that require acquisition must end in `Generated`, `Sourced`, or `Needs-Manual`; `Pending` and `Failed` are not allowed to leak into Executor. A `Needs-Manual` row can continue through SVG generation only as a known placeholder/dependency, and Step 7 re-checks required files before final export. |
| 585 | |
| 586 | **External refs during development, two divergent embedding strategies for downstream outputs.** While editing in `svg_output/`, images are external file references for fast iteration and single-point replacement. `svg_final/` then Base64-inlines ordinary bitmaps and supported SVG resources, while retaining external EMF/WMF references for native PPTX passthrough; an individual inline failure increments the processing-error count, but it does not rewrite authored source or fail the finalizer as a whole. Native PPTX instead copies bitmaps or Office vectors into the package media folder and uses `<a:srcRect>` for supported bitmap cropping. The split exists because the preview and compiler serve different responsibilities: one is a derived visual reference, while the other produces editable DrawingML through the project converter. `svg_final/` is not an unconditionally portable no-external-dependency interchange format or a compatibility source for PowerPoint Convert to Shape. |
| 587 | |
| 588 | **One rendering lock, inherited deck anchors, and per-image composition.** When a deck includes AI-generated images, Stage 2 confirms the deck-wide `rendering` inside each coordinated design direction. Image colors are not a second user decision: Image_Generator starts from the core HEX roles in `spec_lock.md colors`, then interprets them with the completed Design Spec and each resource's `type` or hero-page composition. Rendering may derive coherent tints, material colors, lighting transitions, and atmospheric hues while preserving the core role meanings; it must not replace the deck identity with an unrelated image-only palette. A repeated derived tone may be promoted into a named lock role. |
| 589 | |
| 590 | --- |
| 591 | |
| 592 | ## Image-Text Composition: P / M / A / C |
| 593 | |
| 594 | Whenever the image/formula branch is active, its compact placement vocabulary in [`references/image-layout-patterns.md`](../skills/ppt-master/references/image-layout-patterns.md) is read alongside the layout math. Its current patterns are organized by composition responsibility: |
| 595 | |
| 596 | - **P · Primary Structures** — single-visual, image-as-canvas, and multi-visual page skeletons. |
| 597 | - **M · Modifier Layers** — crop/reveal, tone/focus, and framing/placement/depth treatments applied to an existing skeleton. |
| 598 | - **A · Asset-Dependent Treatments** — compositions that require a prepared composite or appearance, cutout, or registered derivative. |
| 599 | - **C · Cross-Page Continuity** — persistent-state, camera, and matched-framing relationships across slides. |
| 600 | |
| 601 | **Why the catalog includes a combination playbook.** Capability discovery alone does not teach repeatable composition. The playbook turns a page job into a compact sequence: select the `P` skeleton, name the integration need or stylistic role, add the smallest `M` that serves it, use `A` only when its prepared asset exists, add `C` only for an intentional cross-page relationship, then stop when another layer no longer earns its place. Its high-yield combinations are recall aids, not recipes that every deck must cover. |
| 602 | |
| 603 | **Why always reading the library does not impose a catalog or layer quota.** It expands compositional choice rather than defining legal output. A page may use one or several `P` structures and any useful `M`, prepared `A`, or cross-page `C` patterns, cite no id at all, or use a free-form composition when that better serves the narrative and hierarchy. |
| 604 | |
| 605 | **Why the catalog uses two-level IDs.** Handles such as `#P2-01` and `#M1-01` expose both composition responsibility and the local family, so combinations remain readable. The final number follows current browse order rather than preserving historical numbering. These are prompt vocabulary, not runtime effect codes: the Executor realizes the accompanying composition guidance, and the exporter does not map an ID to fixed DrawingML. |
| 606 | |
| 607 | **Why composition intent flows through Strategist's resource list.** The `Layout pattern` column in `§VIII Image Resource List` carries one non-empty free-form suggestion and may optionally cite hierarchical ids from the library; `Crop Policy` separately records `adaptive` or `no-crop`. This preserves a useful starting point across session re-entry without making any catalog entry or id mandatory. Executor may resize, reflow, reposition, rebalance, replace the suggestion, or use another composition when that communicates better. Resource identity, must-use/content obligations, `no-crop`, and explicit user/template constraints remain binding; only changing those requires an upstream Design Spec update. |
| 608 | |
| 609 | **Why true hard constraints stay upstream.** Cross-cutting SVG authoring and PPTX-compatibility exceptions live in the authority set routed by [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md). The layout patterns file points to that router rather than restating the contract, so each rule still has one owning module and no stale duplicate in the pattern catalog. |
| 610 | |
| 611 | --- |
| 612 | |
| 613 | ## Project-Canonical SVG and the Compatibility Boundary |
| 614 | |
| 615 | SVG and DrawingML are not equivalent expression models, so the main compiler route does not treat “the browser can render it” as “the project can export it.” Input is accepted only when the applicable module selected by [`references/shared-standards.md`](../skills/ppt-master/references/shared-standards.md) registers a project-canonical expression or an explicit compatible form with a deterministic DrawingML mapping. The split authority set owns syntax, structure, units, metadata, compatible aliases, fidelity, and rejection conditions; this architecture document defines the layering principle without duplicating individual rules. |
| 616 | |
| 617 | **Why local reuse is compile-time reuse, not a retained PowerPoint object.** The canonical contract defines accepted authoring forms, and the shared validator enforces them. After validation, the pipeline recursively materializes each referenced subtree and rewrites clone-local IDs before export. PPTX-to-SVG import therefore returns expanded primitives rather than reconstructing the authoring-time reuse graph. |
| 618 | |
| 619 | The architectural reasons worth knowing here: |
| 620 | |
| 621 | - **Why mappings are closed instead of accepting ordinary SVG by default.** Project-canonical SVG is a compiler intermediate language, not a browser compatibility layer. Adding an element, attribute, or value requires corresponding input semantics, output mapping, validation, and regression verification; unregistered capabilities do not enter the main compiler route. |
| 622 | - **Why compatible input is not authoring permission.** A documented historical alias may be normalized deterministically and receive a non-blocking checker warning; prompts, templates, and examples still generate only the project-canonical spelling. Migration and manual-input compatibility must not widen generated syntax. |
| 623 | - **Why warnings may pass.** A warning is limited to a recommended spelling, deterministic normalization, known fidelity reduction, or visual-quality risk when legal output remains guaranteed. It does not change page semantics or require Executor re-authoring; any condition that must be corrected for delivery is an error. |
| 624 | - **Why empirical, not derived from spec.** The compatibility boundary grew from real PPT export failures, not from reading the OOXML specification. Some theoretically representable effects remain unreliable across PowerPoint versions, so the contract reflects the actually shippable subset. |
| 625 | - **XML well-formedness remains a precondition.** Malformed SVG fails before DrawingML compatibility matters. The canonical contract owns the accepted authoring forms so XML guidance cannot drift across architecture and prompt documents. |
| 626 | - **Compatibility validation runs before post-processing.** `svg_quality_checker.py` evaluates `svg_output/`; post-processing rewrites SVG and could mask source-level violations. Blocking errors are re-authored by the Executor, while warnings do not trigger a rewrite. Generate proceeds to export only after the final checker reports zero errors. The converter does not rerun that full checker; it independently validates compiler mappings, ZIP integrity, slide count, and package structure, then records the upstream report stage, blocking count, and SVG-source fingerprint in postflight. |
| 627 | |
| 628 | --- |
| 629 | |
| 630 | ## Quality Gate |
| 631 | |
| 632 | **Why a checker exists at all.** SVG generated by an LLM is not deterministic — compatibility violations creep in over long decks and only surface when `svg_to_pptx` aborts mid-conversion or PowerPoint silently drops elements. The checker turns "PowerPoint export failed at page 14" into "page 14 violates the SVG compatibility contract" — an order-of-magnitude faster diagnosis loop, which is what makes long decks economically feasible to iterate on. |
| 633 | |
| 634 | **Why placed before post-processing, not after.** Post-processing rewrites SVG (icon embedding, image inlining), which would mask source-level violations. Reading `svg_output/` directly catches the Executor's actual output, before any cleanup that might paper over a bug. |
| 635 | |
| 636 | **Why the default pipeline has first-page and final checks.** The P01 gate treats the first page as a method sample: it separates method-level, page-local, and not-yet-exercised capabilities, reviews the complete issue set, then fixes every blocking error and selected advisory warnings in one consolidated loop. After it passes, P02 through the final page are generated continuously without checker calls; only the final gate inspects the complete authored set before release. The first calibrates method, while the second verifies the whole deck, so neither substitutes for the other. |
| 637 | |
| 638 | **Severity model: errors block, warnings do not, and there is intentionally no auto-fix.** Severity is determined by whether the input maps deterministically and legally, not merely by whether it uses the recommended spelling: |
| 639 | |
| 640 | | Severity | Classification | Pipeline behavior | |
| 641 | |---|---|---| |
| 642 | | `error` | A structural contract is broken; the input has no mapping or is ambiguous; required metadata is missing; a value is invalid; conversion may violate DrawingML/PPTX constraints; or PowerPoint may need to repair the file | The Executor must re-author and revalidate; Generate must not enter export while the final report still has blocking errors. Formal release export independently rejects such a report before PPTX creation | |
| 643 | | `warning` | A unique, safe, legal conversion exists, but the input is not project-canonical or carries a documented normalization, fidelity reduction, or visual-quality risk | Record the diagnostic and allow publication; no acknowledgement or mandatory rewrite is required | |
| 644 | |
| 645 | The gate follows the three-layer responsibility defined in the design philosophy. It intentionally has no auto-fix: a mechanical patch can silently overwrite valid design intent and ship a worse page. |
| 646 | |
| 647 | **Current implementation boundary.** Formal default release export and `--quick-generate` each compute the exact SVG-source fingerprint and refuse a missing, unreadable, unsupported, non-final, blocking, stale, or unverifiable final report before PPTX creation. An existing project without `validation/svg_quality_report.json` exits nonzero with the `not-provided` gate status; run the final checker against its current `svg_output/` before release export. A matching report may still contain non-blocking warnings; publication continues and postflight records `passed-with-warnings` when applicable. An explicit non-`output` `--source` remains a diagnostic override and bypasses this release gate, so a diagnostic file's existence alone is not delivery proof; postflight still records any verifiable report linkage. |
| 648 | |
| 649 | If the same warning repeatedly appears in newly generated pages, fix the prompt, template example, or specification so default output returns to the project-canonical spelling. That is a generation-quality issue, not a reason to turn otherwise safe compatible input into an error. Conversely, if practice shows that a warning can produce an invalid file or ambiguous meaning, update the contract and checker together to classify it as an error. |
| 650 | |
| 651 | **Why chart coordinate verification hangs off the same gate.** Chart pages have geometric correctness requirements (bar heights / pie sweep angles / axis tick positions) that aren't structural and aren't caught by SVG validity rules. The natural place to catch them is the same gate where the AI is asked to revisit its output — bundling the cognitive context "look at what you generated and fix it" into one phase, rather than splitting structural and geometric review into separate review rounds. |
| 652 | |
| 653 | --- |
| 654 | |
| 655 | ## Post-Processing Pipeline |
| 656 | |
| 657 | > Why each artifact and module exists in the engineering conversion stage, and which workflows would break if you delete it. Read this before considering any simplification of `svg_final/` / `finalize_svg.py` / `svg_to_pptx.py`. |
| 658 | |
| 659 | ### Post-processing artifacts and workflows |
| 660 | |
| 661 | The post-processing and export stages keep authoring, validation, preview, delivery, and archival artifacts distinct. Each one serves a workflow that nothing else in the pipeline can replace. Every PPTX entry below is a variant of the same `svg_output/` → native DrawingML route, not a parallel image-based converter. |
| 662 | |
| 663 | | Artifact | Workflow it serves | Why nothing else replaces it | |
| 664 | | --- | --- | --- | |
| 665 | | `svg_output/` | source of truth, manual editing, `update_spec.py`, `svg_quality_checker.py` | only directory whose contents are authored, not derived | |
| 666 | | `svg_final/` | IDE/browser inspection and manual insertion as an SVG picture | `.pptx` is not openable in IDEs, while `svg_output/` may render incompletely because icon/image refs are external. Ordinary resources are inlined when possible and EMF/WMF stay external; PowerPoint Convert to Shape is unsupported | |
| 667 | | `exports/<name>_<ts>.pptx` (native) | default primary deliverable — editable in PowerPoint as DrawingML shapes | default DrawingML object model; native Chart/Table and narration variants remain editable but have different object or playback behavior | |
| 668 | | `validation/svg_quality_report.json` | machine-readable final SVG gate | separates blocking failures, introduced advisories, inherited prototype findings, and source-import losses, and fingerprints the checked SVG bytes | |
| 669 | | `validation/<output_stem>.report.json` | published-PPTX postflight and resource audit | records actual ZIP/package part counts; reruns ZIP and Slide-count checks; labels relationship, structured-package, transition, and animation validation as build-time enforcement; accepts quality-report linkage only when its SHA-256 fingerprint matches the export inputs; and surfaces unresolved tokens, external images, and generic-only font stacks | |
| 670 | | `exports/<name>_<ts>_native_charts_tables.pptx` (opt-in via `--native-charts-and-tables`) | when `data-pptx-replace-with` markers should replace SVG-derived, shape-based charts/tables with PowerPoint-native Chart/Table objects | data-backed objects with chart/table-specific controls; the default DrawingML shapes remain independently editable | |
| 671 | | `exports/<name>_<ts>_narrated.pptx` (via `--recorded-narration` or `--narration-audio-dir`) | embeds matched narration audio; complete recorded mode directly supports auto-play and PowerPoint video export | `--recorded-narration` requires matching audio for every slide and writes duration-plus-padding auto-advance; low-level `--narration-audio-dir` permits partial or zero coverage and writes auto-advance only with `--use-narration-timings` | |
| 672 | | `exports/<narrated_stem>.mp4` (optional via `powerpoint_video.py`) | animation-faithful narrated video on Windows PowerPoint 2016+ | delegates to PowerPoint's native encoder and waits for completion; it is a post-PPTX integration, not a second deck renderer | |
| 673 | | `backup/<ts>/svg_output/` (default output path only; copy is best-effort after directory creation) | re-export from frozen SVG sources without rerunning the LLM | after successful conversion the exporter creates the backup directory and attempts the copy; explicit `-o` creates none, copy failure does not block export, prints a warning outside quiet mode, and leaves postflight `backup_path` empty, while directory-creation failure remains fatal | |
| 674 | |
| 675 | Validation JSON files and `validation/workflow.log` are cold audit artifacts, |
| 676 | not routine model inputs. The workflow log is opened only when the user |
| 677 | explicitly requests a run review. It reconstructs observed commands and a |
| 678 | bounded material outcome selection—not the complete console stream—plus |
| 679 | selected non-Python details such as a material stage handoff or rework reason, |
| 680 | user-approved exception, or manual recovery choice. Each command footer reports |
| 681 | how many output lines were retained or omitted. These manual entries are |
| 682 | optional and never duplicate artifacts, routine progress, or private reasoning; |
| 683 | current artifacts still establish the stage and readiness. The |
| 684 | exporter reads the SVG quality report programmatically and, in the default |
| 685 | non-quiet flow, prints a compact `[POSTFLIGHT]` receipt with the status, |
| 686 | quality-gate result, Slide count, warning-category counts, and artifact paths. |
| 687 | Successful agents consume that receipt instead of loading either complete |
| 688 | JSON; only failure investigation or an explicit audit extracts targeted report |
| 689 | fields. |
| 690 | |
| 691 | ### SVG preprocessors have TWO usage forms |
| 692 | |
| 693 | This is easy to miss when reading the code. Shared cleanup modules, the local-reference expander, and the inline-geometry materializer are used both to write `svg_final/` and in memory during native conversion. The checker, editor, and structure parser also share parts of the geometry interpretation, but they are not artifact consumers in this section. |
| 694 | |
| 695 | **Disk consumer** — in the default Generate flow, `finalize_svg.py` writes `svg_output/` → `svg_final/` once per run, expanding both project icon placeholders and qualified local `<use>` references. This mandatory default-flow output feeds IDE/browser preview and may be inserted manually as an SVG picture; it is not converted into a separate PPTX artifact. Quick-generate skips the disk consumer. |
| 696 | |
| 697 | **Memory consumer** — native pptx generation reads `svg_output/` directly (no disk hop). It materializes author SVG inline geometry, expands project icon placeholders, materializes geometry injected by those icons, expands qualified local `<use>` references, and finally processes positional text runs: |
| 698 | |
| 699 | | In-memory call site | Preprocessor | Why native pptx needs it | |
| 700 | | --- | --- | --- | |
| 701 | | `svg_to_pptx/drawingml/converter.py` | `svg_to_pptx.geometry_properties` | inline-style geometry must become XML attributes before translation and must run again after icon expansion | |
| 702 | | `svg_to_pptx/use_expander.py` | `svg_finalize.embed_icons` | DrawingML doesn't recognize `<use data-icon="...">`; without expansion every icon silently drops | |
| 703 | | `svg_to_pptx/use_expander.py` | static local-reference expansion | DrawingML does not preserve SVG `<use>` instance graphs; qualifying subtrees must be materialized with instance-local IDs | |
| 704 | | `svg_to_pptx/tspan_flattener.py` | `svg_finalize.flatten_tspan` | DrawingML text runs cannot reposition mid-paragraph; a dy-stacked block of `<tspan>`s would otherwise collapse onto one baseline, and an x-anchored tspan would render in the wrong column | |
| 705 | |
| 706 | ### Per-module consumer table |
| 707 | |
| 708 | | Module | Disk consumer | Memory consumer | Delete impact | |
| 709 | | --- | --- | --- | --- | |
| 710 | | `geometry_properties.py` | `finalize_svg.py` after copy and again after icon expansion | `drawingml/converter.py`; the checker, editor, and template structure parser share the same interpretation | inline-style geometry no longer maps consistently into XML geometry, so preview, validation, and native conversion may diverge | |
| 711 | | `embed_icons.py` | `finalize_svg` `embed-icons` step (followed by local-use expansion) | `svg_to_pptx/use_expander.py` | native pptx loses all icons, and `svg_final/` loses visual closure for supported icons | |
| 712 | | `svg_to_pptx/use_expander.py` (local references) | `finalize_svg` `embed-icons` step | native converter preflight | finalize/native export can no longer materialize qualified local reuse | |
| 713 | | `flatten_tspan.py` | `finalize_svg` `flatten-text` step | `svg_to_pptx/tspan_flattener.py` | **native pptx multi-line `dy`-stacked text collapses to one line** | |
| 714 | | `align_embed_images.py` | `finalize_svg` `align-images` step | — | `svg_final/` loses ordinary-image embedding, so IDE/browser preview and manually inserted SVG pictures lose those images | |
| 715 | | `crop_images.py` / `embed_images.py` / `fix_image_aspect.py` | imported by `align_embed_images.py` | — | `align_embed_images` `ImportError`, full chain broken | |
| 716 | | `svg_rect_to_path.py` | — (legacy standalone utility; no supported pipeline consumer) | — | no supported preview or native-PPTX artifact depends on it; PowerPoint's manual Convert to Shape command is outside the project contract | |
| 717 | |
| 718 | --- |
| 719 | |
| 720 | ## Direct OOXML Routes |
| 721 | |
| 722 | Not every PPTX-related request should regenerate slides. PPT Master now has direct OOXML routes for cases where the native deck itself is the object being edited. |
| 723 | |
| 724 | `template_fill_pptx.py` is a thin CLI wrapper over `scripts/template_fill_pptx/`. Its analyzer extracts a slide library with text slots, tables, charts, and geometry; the fill plan selects source slides, confirms replacements, then the applier clones slides and patches XML parts directly. This route deliberately avoids SVG: a user who supplies a PowerPoint template usually wants those native slide masters, placeholders, tables, and charts to remain PowerPoint-native. |
| 725 | |
| 726 | `native_enhance_pptx.py` is the stable entry point for finished-deck enhancement. It delegates to `native_enhance_pptx_core.py` and patches the PPTX package from a project copy: notes, global or per-slide page transitions, recorded narration media, slide timings, and related metadata. Intake records a source hash and ordered slide-part roster; validate/apply reject source drift or incomplete requested material. A read-only delivery check inventories package integrity, fonts, media, hidden slides, size, and existing motion at intake/preflight, then audits the candidate before atomic publication. The retired `native_narration_pptx.py` name remains only as a thin CLI compatibility shim. The contract is preservation: existing content, layout, and formatting are not regenerated. |
| 727 | |
| 728 | These direct routes share some analysis primitives with the main pipeline, but at different depths. Template Fill consumes the standard PPTX intake slide library. Native Enhance uses `ppt_to_md.py` for content understanding, generates its own lightweight `slide_index.json` from the archived package, and keeps machine delivery reports under `validation/`. Neither shares the SVG authoring or post-processing stages. That separation is intentional: SVG generation is a design synthesis path; direct OOXML editing is a preservation path. |
| 729 | |
| 730 | --- |
| 731 | |
| 732 | ## Native PPTX Conversion Internals |
| 733 | |
| 734 | `svg_to_pptx.py` implements the final defensive layer defined in the design philosophy; this section explains only the internal structure of that constrained compiler route. |
| 735 | |
| 736 | **Why per-element dispatch, not whole-file translation.** SVG's hierarchical model maps cleanly onto DrawingML's group / shape / picture types — there's no need for a holistic optimizer that re-plans the slide. Each shape kind gets its own narrow translator, which keeps each translator simple enough to debug and unit-test in isolation. The output quality of a slide is the sum of independent local conversions; that property is fragile under whole-file translation but robust under element dispatch. |
| 737 | |
| 738 | **Why imported and authored shape metadata are separate.** A lossless imported SVG may need native-shape metadata, hidden carriers, and preview fingerprints to recover an advanced PowerPoint shape. That representation stays immutable in the temporary analysis workspace as native-payload backing. `svg_authoring_view.py` creates the editable template-creation IR: lightweight SVGs with document-local source refs plus an `authoring_manifest.json` containing paths and initial hashes, not duplicated payload. `standard` / `fidelity` author project-canonical SVG and use the compact authored-preset group only for exact registered preset matches. Mirror materializes validated templates from the IR and rehydrates converter-supported metadata only for unchanged Slide-local/slot refs; fixed structural layers remain direct atoms, unsupported or edited objects keep their current SVG fallback, and IR-only refs do not enter final template SVGs. |
| 739 | |
| 740 | **Why there is only one PPTX compiler route.** Native export reads authored SVGs and translates supported SVG elements into DrawingML shapes. The normal deck path reads `svg_output/`; when requested, create-template invokes the same structured compiler on validated template prototypes to produce `exports/<id>_template_preview.pptx` as review evidence. The project does not package whole-slide SVG media or alternate raster renderings into a second PPTX. `svg_final/` is still generated on every standard deck run, but it is only a derived visual-preview / SVG-picture artifact rather than a PPTX source; PowerPoint's manual Convert to Shape command remains outside the supported contract. |
| 741 | |
| 742 | **Why structure is authored before visual generation on structured reuse routes.** Master and Layout are not post-processing discoveries. With `template_reuse_scope: mirror|layout`, the Strategist writes unique Master/Layout definitions and complete page assignments before SVG generation; the Executor writes those identities, fixed atoms, and slots while composing each page, and export only compiles declared structure. `template_reuse_scope: style`, free-design, and brand-only decks make the opposite trade: they stay on `mode: flat`, keep every object Slide-local, author no structure metadata, and receive only a clean project-owned Master/Blank-Layout shell at export. Legacy inputs may inform a new `create-template` workspace, but they never enter an in-place structure-upgrade route; neither generation mode triggers heuristic Master/Layout promotion or placeholder inference. |
| 743 | |
| 744 | **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. |
| 745 | |
| 746 | **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. |
| 747 | |
| 748 | **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. |
| 749 | |
| 750 | **Why the internal application plan retains two fields.** Strategist derives `template_reuse_scope` to record literal mirror reuse, structural layout reuse, or flat style reference. Structured plans then derive `template_adherence: strict|adaptive`: `page_layouts` records the complete authoring prototype, `pptx_masters` / `pptx_layouts` record unique reusable definitions, and `page_pptx_layouts` records page assignment. Strict preserves the declared prototype contract. Adaptive retains its Master, and Strategist may declare a new Layout only when fixed Layout atoms or slot topology/bounds change. If construction reveals that need, execution returns upstream and resumes only after Strategist updates, reads back, and validates the definition and assignment; the exporter never infers it later. These are exporter values, not user confirmation options. A template-backed definition may remain unused and still register in the final package. Layout skin remains project-controlled, while mirror additionally preserves literal visuals and text-node topology. `style` has no adherence value or structure mappings. |
| 751 | |
| 752 | **Why explicit-Layout text defaults are split between Master and Layout.** Both flat and structured export write the declared title anchor and a deterministic nine-level body hierarchy into Master defaults while preserving indentation and bullet settings. On structured routes, each generated Layout text slot additionally copies its carrier's first run size into the level-one default while retaining the prompt's direct size. This preserves Layout-specific scale when placeholder text is inserted or reset; direct runs on generated Slides remain unchanged. |
| 753 | |
| 754 | **Why structured output is read back before publication.** Metadata preflight cannot prove package serialization preserved every relationship and registration. Export therefore reopens the temporary PPTX and validates published Slides separately from the complete Master/Layout roster, including definitions unused by all Slides. It checks Presentation → Master → Layout → Slide registration, physical part/content-type rosters, picker identities, exact static-object order, placeholder type/effective index/bounds, carrier bindings, hidden proxies, and zero-slot Layouts before publishing the file. |
| 755 | |
| 756 | **Why Create Layout / Create Deck have authored and preservation modes.** `pptx_template_import.py` emits layered Master/Layout/Slide references plus native structure facts. `standard` / `fidelity` use those assets and visuals as references, then author a new topology from the confirmed reusable behavior. Mirror instead materializes a new workspace from the validated source roster and topology one-to-one, allowing only mechanical normalization required by the explicit structured contract and never inventing absent facts. The original PPTX remains immutable analysis evidence, not a packaged export dependency. Create Brand has no structural replication strategy. |
| 757 | |
| 758 | **Why create-template uses one workspace route in both scopes.** `create-template` keeps `library` as its default indexed output and may instead write under an initialized project. Both roots require `templates/`; `images/`, `icons/`, and on-demand `exports/` appear only when they contain real files, and existing SVG asset references follow the same rules. This makes the workspace migratable and reusable without a library-only package branch or a reduced project branch. The sole scope difference is global index registration. Both scopes share one portable workspace contract, but only Layout / Deck own a structured SVG contract; Brand remains identity-only. |
| 759 | |
| 760 | **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. |
| 761 | |
| 762 | **Why PowerPoint-native Chart/Table reconstruction uses explicit replacement markers, not automatic object replacement.** The standalone `pptx_to_svg.py` importer emits a visible SVG fallback plus `data-pptx-replace-with` and `<metadata type="application/json">` only for validated table/chart subsets. Generated decks prepare that pair only when Strategist marks the §IX page block `Native-ready: yes`; §VII remains a positive catalog-reference inventory, and a catalog marker is a capability example rather than an execution decision. The parent marker determines the payload schema; ordinary shapes and connectors never use this contract. 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 without a non-empty `effectLst` / `effectDag` normalizes into that schema; a table-cell run effect instead disables native replacement and adds a blocking effect diagnostic. 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. |
| 763 | |
| 764 | For supported parsed column/bar/line/area, pie/doughnut, scatter, and bubble charts, a missing baked preview is replaced by a deterministic readable SVG fallback marked `data-pptx-fallback-kind="normalized"`. The importer also covers the verified column/line/area combo subset, canonical four-series OHLC stock, area charts with numeric date axes, verified scatter/bubble charts with the closed `axes.x` / `axes.y` contract, radar, safe `of_pie` `serLines`, axis/title/legend normalization, and bounded bar/column gap/overlap cases. `gapWidth` is accepted only as one integer in `0..500`, and `overlap` only as one integer in `-100..100`; these presentation values intentionally normalize in native output, while malformed, duplicate, or out-of-range input fails closed. Combo plots may retain independent primary/secondary category caches and workbook ranges. XY import derives `scatter_style` from uniform effective series line/marker/smooth state. The closed category/value and XY axis contracts retain kind, position, visibility, label position, number format, min/max/major unit, reversal, and major gridlines for native read-back; the normalized XY fallback consumes only the two `major_gridlines` flags. |
| 765 | |
| 766 | ChartEx import is deliberately closed to seven validated data models: `treemap`, `sunburst`, `histogram`, `pareto`, `box_whisker`, `waterfall`, and `funnel`. Their supported hierarchy/category/value/series/subtotal data topology round-trips through native output and reimport. Numeric caches must be non-empty and finite, with canonical non-negative counts/indexes and exact contiguous point topology. Source ChartEx style, axes, labels, and binning may normalize; this is not arbitrary ChartEx import or presentation fidelity. C4/C5 do not expand the normalized renderer, so valid active types outside it still use `data-pptx-fallback-kind="placeholder"` without a source preview. Full `AxisSpec`, arbitrary ChartEx families, arbitrary rich OOXML, rotated/flipped/3D charts, unverified combo/stock/date-axis variants, and other unmodeled semantics remain outside the active import subset. Native replacement may normalize payload-external presentation details and retains the data-model-first warning. Default export keeps fallback children as editable DrawingML shapes; only `--native-charts-and-tables` activates PowerPoint-native Chart/Table objects with a data source and object-specific editing model. Every active imported marker carries `data-pptx-import-source="pptx"` and `data-pptx-fallback-sha256`: stale visible edits, reachable SVG definition/reference changes, or marker transforms make native replacement fail rather than discard the SVG edit, while a hashless legacy imported marker that retains import provenance remains compatible with a warning. Generated authoring omits both importer provenance and a static baseline without warning. This importer/exporter pairing is a reconstruction aid, not a preservation-route substitute for `template-fill-pptx` or `native-enhance-pptx`. |
| 767 | |
| 768 | --- |
| 769 | |
| 770 | ## Animation & Transition Model |
| 771 | |
| 772 | The interesting design choice is the animation **anchor**, not the effect list. |
| 773 | |
| 774 | **Why anchor object animations on top-level `<g>` groups.** PowerPoint's |
| 775 | animation timeline is shape-keyed—each animated object needs a stable shape ID. |
| 776 | Animating individual primitives would produce 30+ separately moving atoms per |
| 777 | slide, while animating only the slide as a whole loses visual storytelling. |
| 778 | Top-level groups are the natural granularity: Executor already uses |
| 779 | `<g id="...">` to mark logical content blocks, so entrance, emphasis, path, |
| 780 | and exit effects share the same semantic units. The group identifies a |
| 781 | PowerPoint shape target rather than one timeline record: the legacy |
| 782 | single-effect object creates one Animation Pane row, while `effects[]` may |
| 783 | create several ordered rows that all target the same shape. |
| 784 | |
| 785 | **Why page structure is auto-skipped.** Any top-level group with `data-pptx-layer` is static structure, and the current scanner also treats every explicit `data-pptx-placeholder` as static page framing; `background` / `header` / `footer` / `decoration` / `watermark` / `page-number` roles cover the remaining chrome. The ID-token fallback is not enabled or disabled per SVG: it applies to each top-level group that lacks layer, role, and placeholder markers, so a mixed new/legacy SVG may still use the legacy ID heuristic on only its unmarked groups. Separately, when an SVG has no top-level groups, no animation target has been found, and only one to eight root primitives qualify, those primitives form a bounded compatibility fallback. This is the scanner's actual scope; the animation reference's whole-page “marker-free legacy SVG” wording still needs separate alignment with the implementation. |
| 786 | |
| 787 | **Why object-level animation uses a sidecar, not SVG attributes.** SVG remains |
| 788 | the static visual source of truth. Custom PPTX animation is export policy, so |
| 789 | per-object overrides live in optional `animations.json` keyed by slide stem and |
| 790 | top-level group id. A populated group uses either the fully compatible legacy |
| 791 | single-effect fields or a non-empty `effects[]` envelope, never both. Each |
| 792 | resolved row owns its effect, sequence order, delay, duration, Start mode, |
| 793 | and optional `trigger_shape`; the slide animation trigger supplies only the |
| 794 | inherited Start mode. The generated scaffold is neutral (`effect: none`) and |
| 795 | leaves groups as `{}` until motion is adopted. This keeps PowerPoint-specific |
| 796 | metadata out of SVG without forcing one semantic object to have only one |
| 797 | motion phase. |
| 798 | |
| 799 | **Why automatic modes remain entrance-only.** `auto`, `mixed`, and `random` |
| 800 | answer one bounded question: how an otherwise generic reveal should enter. |
| 801 | They do not invent emphasis, movement, or exit intent. Those three categories, |
| 802 | and an explicitly selected entrance, use canonical effects in the sidecar so |
| 803 | the authoring decision remains inspectable. |
| 804 | |
| 805 | **Why the target model stops at top-level shape effects.** The generated model |
| 806 | does not infer paragraph/text-range builds, author custom freeform motion |
| 807 | paths, sequence native Chart/SmartArt internals, or emit media playback |
| 808 | commands. Native motion-path presets remain valid object effects; media |
| 809 | playback remains in the audio/video workflows. |
| 810 | |
| 811 | **Why recorded narration drives auto-advance from clip duration.** Recorded-narration mode targets video export, where no presenter clicks through the deck. It probes each clip's real duration and sets slide auto-advance to `audio duration + --narration-padding`; padding defaults to 0.5 seconds so the tail is not cut off. It does not use estimated reading speed or a fixed per-slide duration. |
| 812 | |
| 813 | **Why recorded narration rejects on-click object animation.** PowerPoint can |
| 814 | record click timings during a real rehearsal, but PPT Master does not synthesize |
| 815 | object-level click events. The recorded narration path writes page-level audio |
| 816 | and slide auto-advance timings only, so click-driven object effects would leave |
| 817 | the export dependent on extra manual PowerPoint rehearsal. Decks exported with |
| 818 | `--recorded-narration` must therefore use click-free object animations |
| 819 | (`after-previous` or `with-previous`) on every resolved row; this also excludes |
| 820 | `trigger_shape`. |
| 821 | |
| 822 | **Why native video export is a separate command.** Audio synthesis and PPTX |
| 823 | packaging are cross-platform project operations; PowerPoint video encoding is a |
| 824 | Windows desktop integration. `powerpoint_video.py` therefore accepts the final |
| 825 | narrated PPTX, invokes `CreateVideo`, and polls `CreateVideoStatus` to present a |
| 826 | synchronous CLI result without coupling Office automation to the TTS backends. |
| 827 | |
| 828 | --- |
| 829 | |
| 830 | ## Maintenance Boundaries: What Not To Collapse |
| 831 | |
| 832 | The tempting simplifications below have explicit costs. Treat them as negative contracts unless the surrounding architecture is deliberately redesigned. |
| 833 | |
| 834 | | Do not collapse or add | Why | |
| 835 | |---|---| |
| 836 | | Do not fuzzy-match template names or style phrases to library paths | Template selection must be deterministic; applying the wrong workspace is harder to recover from than free design | |
| 837 | | Do not treat a raw PPTX template as a Step 3 template | when used as a template/page shell, it belongs to native cloning/filling; source use, 1:1 beautify, and restructuring instead follow their Generate boundaries rather than passing a PPTX directly to Step 3 | |
| 838 | | Do not merge `template-fill-pptx`, `beautify-pptx`, and `native-enhance-pptx` into one "PPTX optimization" route | their preservation contracts differ: native fill, 1:1 redesign, and direct enhancement are separate operations | |
| 839 | | Do not script-generate batches of Executor SVG pages | cross-page design judgment depends on sequential main-agent authoring | |
| 840 | | Do not make `image_analysis.csv` a durable cache | `images/` is a live folder; facts must be regenerated on use | |
| 841 | | Do not make `svg_final/` the default native PPTX input | `svg_final/` rewrites resources for visual preview, while native conversion needs high-fidelity `svg_output/` semantics | |
| 842 | | Do not treat `svg_final/` as a shape-recoverable or no-external-dependency interchange format | it serves visual preview and SVG-picture insertion, but EMF/WMF retain external-reference exceptions; PowerPoint Convert to Shape is unsupported | |
| 843 | | Do not auto-enable object-level animations | page transitions are default; object motion is an explicit export policy | |
| 844 | | Do not default visual review, narration, chart verification, or animation customization into every run | these workflows have narrow triggers and extra dependencies | |
| 845 | | Do not replace `finalize_svg.py` with a file copy | finalization embeds icons/images, flattens special text, and prepares preview artifacts | |
| 846 | | Do not use `analysis/<stem>.slide_library.json` as a second source of chart values in the main pipeline | Markdown owns content values; intake chart/table entries are structural digests unless a direct-PPTX workflow owns them | |
| 847 | |
| 848 | --- |
| 849 | |
| 850 | ## Routes and Supporting Runbooks |
| 851 | |
| 852 | [`workflows/index.md`](../skills/ppt-master/workflows/index.md) is a maintainer-only inventory and does not enter the task-loading chain. Runtime route selection is authoritative in [`workflows/routing.md`](../skills/ppt-master/workflows/routing.md). PPT Master has exactly four top-level artifact routes: Generate PPTX, Create Template, Fill Native PPTX, and Enhance Native PPTX. A user request enters one of those routes; no supporting runbook competes with them. |
| 853 | |
| 854 | Supporting files stay separate only to keep route contracts focused and load optional context on demand: |
| 855 | |
| 856 | | Class | Runbooks | Owning route | |
| 857 | |---|---|---| |
| 858 | | Generation profiles | `beautify-pptx`, `quick-generate` | Beautify preserves wording/pages and selects Default unless Quick is explicit; Quick owns the direct SVG-to-PPTX lifecycle | |
| 859 | | Template child workflows | `create-brand`, `create-style`, `create-layout`, `create-deck` | Create Template dispatches exactly one for identity-only, roster-free direction/method, brand-neutral/application-neutral structure, or a recurring application with integrated identity/structure | |
| 860 | | Template-input stage | `apply-template-workspace` | Runs after Default Stage 1 confirms at least one workspace and before Stage 2; free design skips installation, while Quick may provide direct exact-root input | |
| 861 | | Generation stages | `topic-research`, `resume-execute`, `refine-spec`, `verify-charts`, `visual-review`, `live-preview`, `customize-animations` | Generate PPTX at their defined intake, planning, editing, quality, or post-processing points | |
| 862 | | Shared stage | `generate-audio` | Generate PPTX post-processing or Enhance Native PPTX narration integration | |
| 863 | | Governance | `failure-recovery` | Global stop/continue policy for all four routes; concrete recovery matrix and resume pointers for Generate PPTX | |
| 864 | |
| 865 | This classification is a responsibility boundary, not a filename preference. A new top-level route is justified only by a distinct artifact lifecycle and mutation model; kind-specific execution inside Create Template remains a child workflow, optional route behavior remains a profile or stage, and cross-route policy remains governance. |
| 866 |