| 1 | # PPT Master Toolset |
| 2 | |
| 3 | This directory contains user-facing scripts for conversion, project setup, direct PPTX template filling, SVG processing, export, recorded narration, and image generation. |
| 4 | |
| 5 | ## Directory Layout |
| 6 | |
| 7 | - Top-level `scripts/`: runnable entry scripts |
| 8 | - `scripts/project_management/`: internals behind `project_manager.py` |
| 9 | - `scripts/source_to_md.py`: unified source-document → Markdown dispatcher |
| 10 | - `scripts/source_to_md/`: source-document → Markdown routing/batch helpers and backend converters (`_dispatcher.py`, `_batch.py`, `pdf_to_md.py`, `doc_to_md.py`, `excel_to_md.py`, `ppt_to_md.py`, `web_to_md.py`) |
| 11 | - `scripts/image_backends/`: internal provider implementations used by `image_gen.py` |
| 12 | - `scripts/tts_backends/`: internal TTS provider implementations used by `notes_to_audio.py` |
| 13 | - `scripts/template_import/`: internal PPTX reference-preparation helpers used by `pptx_template_import.py` |
| 14 | - `scripts/svg_finalize/`: internal post-processing helpers used by `finalize_svg.py` |
| 15 | - `scripts/docs/`: topic-focused script documentation |
| 16 | - `scripts/prompt_audit.py` + `scripts/prompt_audit_manifest.json`: maintainer-only prompt budget/governance lint (see [`docs/prompt_audit.md`](docs/prompt_audit.md)); the manifest is audit-only and never loaded as prompt context |
| 17 | - `scripts/assets/`: static assets consumed by scripts |
| 18 | |
| 19 | ## Quick Start |
| 20 | |
| 21 | Typical end-to-end workflow: |
| 22 | |
| 23 | ```bash |
| 24 | python3 scripts/source_to_md.py <file-or-url-or-dir> [<file-or-url-or-dir> ...] |
| 25 | # or direct backend calls: |
| 26 | python3 scripts/source_to_md/pdf_to_md.py <file.pdf> |
| 27 | # or |
| 28 | python3 scripts/source_to_md/ppt_to_md.py <deck.pptx> |
| 29 | python3 scripts/source_to_md/excel_to_md.py <workbook.xlsx> |
| 30 | python3 scripts/project_manager.py init <project_name> --format ppt169 |
| 31 | python3 scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...> |
| 32 | python3 scripts/total_md_split.py <project_path> |
| 33 | python3 scripts/finalize_svg.py <project_path> |
| 34 | python3 scripts/animation_config.py scaffold <project_path> # optional object-level animation overrides |
| 35 | python3 scripts/svg_to_pptx.py <project_path> |
| 36 | ``` |
| 37 | |
| 38 | After `init`, project-scoped Python CLIs automatically record their command |
| 39 | envelopes and bounded material outcomes in |
| 40 | `<project_path>/validation/workflow.log`; invoke them directly, without a |
| 41 | logging wrapper. The log does not copy the full console stream. |
| 42 | |
| 43 | Repository update: |
| 44 | |
| 45 | ```bash |
| 46 | python3 scripts/update_repo.py |
| 47 | ``` |
| 48 | |
| 49 | ## Script Index |
| 50 | |
| 51 | | Area | Primary scripts | Documentation | |
| 52 | |------|-----------------|---------------| |
| 53 | | Conversion | `source_to_md.py`, `source_to_md/pdf_to_md.py`, `source_to_md/doc_to_md.py`, `source_to_md/excel_to_md.py`, `source_to_md/ppt_to_md.py`, `source_to_md/web_to_md.py`, `pptx_intake.py`, `pptx_to_svg.py` | [docs/conversion.md](./docs/conversion.md) | |
| 54 | | Project management | `project_manager.py`, `workflow_log.py`, `workflow_transcript.py`, `batch_validate.py`, `generate_examples_index.py`, `error_helper.py`, `pptx_template_import.py`, `template_fill_pptx.py`, `native_enhance_pptx.py`, `pptx_delivery_check.py` | [docs/project.md](./docs/project.md) | |
| 55 | | SVG pipeline | `preset_shape_svg.py`, `shape_boolean_svg.py`, `svg_authoring_view.py`, `compact_svg_coordinates.py`, `mirror_template_materialize.py`, `finalize_svg.py`, `svg_to_pptx.py`, `template_preview_pptx.py`, `total_md_split.py`, `svg_quality_checker.py`, `extract_svg_assets.py`, `extract_svg_pictures.py`, `animation_config.py`, `notes_to_audio.py`, `narration_sync.py` | [docs/svg-pipeline.md](./docs/svg-pipeline.md); [native shape authoring](../references/native-shape-authoring.md) | |
| 56 | | PPTX transitions | `pptx_transitions.py` | [docs/pptx-transitions.md](./docs/pptx-transitions.md) | |
| 57 | | PPTX animations | `pptx_animations.py`, `animation_config.py` | [docs/pptx-animations.md](./docs/pptx-animations.md) | |
| 58 | | Animation resources | `sound_sync.py` | [sound vocabulary and sync](../templates/sounds/README.md); [docs/pptx-animations.md](./docs/pptx-animations.md) | |
| 59 | | Spec maintenance | `update_spec.py`, `visualization_recall.py`; legacy `chart_recall.py` | [docs/update_spec.md](./docs/update_spec.md); [docs/visualization-recall.md](./docs/visualization-recall.md) | |
| 60 | | Image tools | `image_gen.py`, `image_treat.py`, `analyze_images.py`, `gemini_watermark_remover.py` | [docs/image.md](./docs/image.md) | |
| 61 | | Maintenance smokes | Inline temporary-project commands | [advanced image and motion](./docs/advanced-image-motion-smoke.md); [mask and gradient](./docs/mask-gradient-smoke.md); [multilingual text](./docs/multilingual-text-smoke.md) | |
| 62 | | Repo maintenance | `update_repo.py` | README install/update section | |
| 63 | | Troubleshooting | validation, preview, export, dependency issues | [docs/troubleshooting.md](./docs/troubleshooting.md) | |
| 64 | |
| 65 | ## High-Frequency Commands |
| 66 | |
| 67 | Conversion: |
| 68 | |
| 69 | ```bash |
| 70 | python3 scripts/source_to_md.py <file-or-url-or-dir> [<file-or-url-or-dir> ...] |
| 71 | python3 scripts/source_to_md/pdf_to_md.py <file.pdf> |
| 72 | python3 scripts/source_to_md/ppt_to_md.py <deck.pptx> |
| 73 | python3 scripts/source_to_md/doc_to_md.py <file.docx> |
| 74 | python3 scripts/source_to_md/excel_to_md.py <workbook.xlsx> |
| 75 | python3 scripts/source_to_md/web_to_md.py <url> |
| 76 | python3 scripts/pptx_to_svg.py <deck.pptx> -o <output_dir> # reconstruction/reference SVG import |
| 77 | ``` |
| 78 | |
| 79 | Project setup: |
| 80 | |
| 81 | ```bash |
| 82 | python3 scripts/project_manager.py init <project_name> --format ppt169 |
| 83 | python3 scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...> |
| 84 | python3 scripts/project_manager.py scaffold-spec <project_path> # optional manual helper |
| 85 | python3 scripts/project_manager.py scaffold-lock <project_path> # optional manual helper |
| 86 | python3 scripts/project_manager.py validate <project_path> |
| 87 | python3 scripts/project_manager.py page-context <project_path> P07 --record-usage |
| 88 | python3 scripts/project_manager.py page-context-report <project_path> |
| 89 | ``` |
| 90 | |
| 91 | `page-context` is an on-demand read-only current-page projection for diagnostics, |
| 92 | routing checks, or context measurement; normal generation retains the complete |
| 93 | Design Spec and lock once per valid execution context. Each invocation includes |
| 94 | the global lock projection as a continuity anchor set, not a color/font allowlist; large Design Specs, |
| 95 | prototype, and selected family visualization references are emitted only as scoped |
| 96 | path/SHA fingerprints and are read once per execution context. `--bundle` is a |
| 97 | deprecated compatibility no-op. `--record-usage` writes one derived snapshot |
| 98 | under `analysis/page-context/`; exact `o200k_base` token counts are optional and |
| 99 | degrade to `tokens: null` when `tiktoken` is absent. Telemetry may be partial. |
| 100 | |
| 101 | Optional visualization-recall diagnostics and canonical validation: |
| 102 | |
| 103 | ```bash |
| 104 | python3 scripts/visualization_recall.py recall --page P03 --tag "time series" --tag "three metrics" --tag "direction over time" |
| 105 | python3 scripts/visualization_recall.py validate chart/line_chart |
| 106 | ``` |
| 107 | |
| 108 | Template source import: |
| 109 | |
| 110 | ```bash |
| 111 | python3 scripts/pptx_template_import.py <template.pptx> |
| 112 | python3 scripts/pptx_template_import.py <template.pptx> --manifest-only |
| 113 | python3 scripts/pptx_template_import.py <template.pptx> --inheritance-mode both |
| 114 | python3 scripts/svg_authoring_view.py <imported-svg-or-dir> -o <output-dir> --projection-kind layered |
| 115 | python3 scripts/svg_authoring_view.py <authoring-dir> --refresh-summary |
| 116 | python3 scripts/compact_svg_coordinates.py <template_workspace>/templates --inplace --keep-native-frames |
| 117 | python3 scripts/mirror_template_materialize.py <import_workspace> <template_workspace> |
| 118 | python3 scripts/template_preview_pptx.py <template_workspace> |
| 119 | python3 scripts/template_preview_pptx.py <legacy_template_workspace> --visual-only |
| 120 | ``` |
| 121 | |
| 122 | Template import defaults to the canonical layered `svg/` tree. Use |
| 123 | `--inheritance-mode both` only when a separate self-contained `svg-flat/` |
| 124 | verification tree is required. No derived narrative digest is generated |
| 125 | because `manifest.json` already owns those facts. |
| 126 | |
| 127 | `svg_authoring_view.py` creates a lightweight, non-destructive editable IR |
| 128 | bundle from PPTX-imported SVGs. It removes embedded `txbody` payloads, |
| 129 | duplicate hidden geometry carriers, and import-identity attributes from the |
| 130 | copy while retaining visible fallback geometry, text, images, stable element |
| 131 | ids, root Master/Layout markers, selected native-shape intent, and |
| 132 | document-local `data-pptx-source-ref` values. |
| 133 | Relative local image references are rewritten so the projected copy still |
| 134 | renders from its new location. The bundle's `authoring_summary.json` is the |
| 135 | model-readable current-file index; `authoring_manifest.json` records |
| 136 | source/authoring hashes and object paths for tools without duplicating opaque |
| 137 | payload and does not enter model context. Imported model-facing frames and safe |
| 138 | transform page coordinates use at most two decimals; immutable lossless SVGs |
| 139 | retain the original precision. In-place vector/picture extraction |
| 140 | refreshes the summary automatically; use `--refresh-summary` after other direct |
| 141 | IR edits. The full imported SVG remains unchanged as native-payload backing. |
| 142 | Template creation edits the IR and materializes validated `templates/*.svg`; |
| 143 | the IR directory itself is not a final template or direct release export |
| 144 | source. |
| 145 | |
| 146 | `mirror_template_materialize.py` is the deterministic Type A mirror compiler. |
| 147 | It consumes only the layered `authoring-svg/` IR as editable input, loads its |
| 148 | tool-only manifest internally, and validates it against immutable `svg/`, |
| 149 | `native_structure.json`, |
| 150 | `svg/inheritance.json`, `source_template.pptx`, and any extracted-vector |
| 151 | inventory, then publishes a complete structured template roster atomically. |
| 152 | Unchanged supported Slide-local/slot refs may recover native payload; edited |
| 153 | refs keep their current SVG fallback. Fixed Master/Layout wrappers are expanded |
| 154 | mechanically into direct atoms, source visibility flags become canonical root |
| 155 | metadata, and imported vectors are copied once to `icons/imported/`. Large |
| 156 | opaque `txBody`, shape-style, and custom-geometry payloads are deduplicated into |
| 157 | `templates/native_payloads.json.gz`; repeated native restoration attributes |
| 158 | are stored there as short `data-pptx-native-ref` records. Structural metadata |
| 159 | stays inline, while checker, template-structure validation, and export hydrate |
| 160 | both layers in memory. Legacy inline payload and v1 payload-only stores remain |
| 161 | readable. The v1 execution manifest points to per-prototype |
| 162 | `ppt-master.template-text-slots.v2-min` diagnostic sidecars. They are derived |
| 163 | tool metadata and are not injected into model context. Checker and export |
| 164 | validate output attributes, topology, and resource hashes against the complete |
| 165 | prototype internally. Bitmap assets |
| 166 | go to `images/`; other referenced source assets go to `templates/assets/`. |
| 167 | The destination must be empty, and the command does not write |
| 168 | `templates/design_spec.md`; Template_Designer owns that authored brief. |
| 169 | |
| 170 | `template_preview_pptx.py` reads a template workspace, exports every public `templates/*.svg` prototype as one structured review slide, and verifies the resulting Master/Layout package. In a project root containing Layout and Deck specs, it previews the active Layout roster. Canonical definition-only `layout_<layout_key>.svg` prototypes are registered as reusable Layouts through internal carrier slides that are removed before publication; they never increase the review deck's visible slide count. This is an on-demand review action: its default output is `exports/<template_id>_template_preview.pptx`, and that directory need not exist before the command runs. It refuses an existing output unless an intentional re-export passes `--force`. `--visual-only` is an explicit migration aid for legacy SVG rosters: it creates a slide-local visual review deck without validating or claiming a reusable Master/Layout contract. This diagnostic path does not require a project `spec_lock.md`; it may retain generic theme/text defaults inside its clean one-Master/one-Layout shell. New structured templates use the default mode when a review deck is requested. |
| 171 | |
| 172 | Template fill (direct PPTX, no SVG conversion): |
| 173 | |
| 174 | ```bash |
| 175 | python3 scripts/project_manager.py init <project_name> --format ppt169 |
| 176 | python3 scripts/project_manager.py import-sources <project_path> <source.pptx> <material...> |
| 177 | # Manual fallback when import-sources did not produce analysis/<stem>.slide_library.json: |
| 178 | python3 scripts/template_fill_pptx.py analyze <project_path>/sources/<source.pptx> -o <project_path>/analysis/<stem>.slide_library.json |
| 179 | python3 scripts/template_fill_pptx.py scaffold <project_path>/analysis/<stem>.slide_library.json -o <project_path>/analysis/fill_plan.json --slides "1,3,4" |
| 180 | python3 scripts/template_fill_pptx.py check-plan <project_path>/analysis/<stem>.slide_library.json <project_path>/analysis/fill_plan.json -o <project_path>/analysis/check_report.json |
| 181 | python3 scripts/template_fill_pptx.py apply <project_path>/sources/<source.pptx> <project_path>/analysis/fill_plan.json -o <project_path>/exports/filled.pptx |
| 182 | python3 scripts/template_fill_pptx.py validate <project_path> |
| 183 | ``` |
| 184 | |
| 185 | `apply` requires `fill_plan.json` to have top-level `"status": "confirmed"` unless `--force` is passed. It automatically writes `filled_YYYYMMDD_HHMMSS.pptx` unless the output stem already ends with a timestamp. It preserves source page transitions by default; `--transition <effect>` accepts a canonical effect in the shared native gallery registry documented by [`docs/pptx-transitions.md`](docs/pptx-transitions.md), while old names remain accepted only as compatibility inputs, and `--transition-duration <seconds>` changes a replacement effect's duration. `--transition none` removes the visual effect, `--transition keep` states the preservation policy explicitly, and a per-slide `transition` field in the plan overrides whatever the CLI selects. The object form accepts effect-specific native `effect_options`. |
| 186 | |
| 187 | Native existing-PPTX enhancement (direct PPTX, no SVG conversion): |
| 188 | |
| 189 | ```bash |
| 190 | python3 scripts/native_enhance_pptx.py init <source.pptx> --name <project_slug> |
| 191 | python3 scripts/native_enhance_pptx.py plan <project_path> |
| 192 | python3 scripts/native_enhance_pptx.py validate <project_path> |
| 193 | python3 scripts/native_enhance_pptx.py apply <project_path> |
| 194 | python3 scripts/pptx_delivery_check.py <finished.pptx> |
| 195 | ``` |
| 196 | |
| 197 | Native preset shape authoring (one or more registry-backed fragments on stdout): |
| 198 | |
| 199 | ```bash |
| 200 | python3 scripts/preset_shape_svg.py list --search arrow |
| 201 | python3 scripts/preset_shape_svg.py describe rightArrow --compact |
| 202 | python3 scripts/preset_shape_svg.py render rightArrow --id process-arrow --frame 120 180 240 96 --fill '#2563EB' |
| 203 | python3 scripts/preset_shape_svg.py render-batch --input - <<'JSON' |
| 204 | [ |
| 205 | {"preset":"chevron","id":"step-1","frame":[120,180,220,96], |
| 206 | "fill":"#2563EB","stroke":"none","adjustments":{"adj":"val 42000"}}, |
| 207 | {"preset":"leftBrace","id":"group-brace","frame":[380,170,48,240],"fill":"none","stroke":"#111827","stroke_width":3} |
| 208 | ] |
| 209 | JSON |
| 210 | ``` |
| 211 | |
| 212 | Runtime capability discovery reads |
| 213 | [`preset-shape-vocabulary.md`](../references/preset-shape-vocabulary.md), which |
| 214 | lists all 187 exact names by Office category and objective contour family. |
| 215 | `list [--search QUERY]` and `list --grouped [--search QUERY]` remain optional |
| 216 | location views; they do not replace the complete vocabulary. |
| 217 | `describe --compact` returns the selected preset's objective identity, Office |
| 218 | category, family, scope, literal boundary, adjustments, connector/path facts, |
| 219 | connection sites, and text-rectangle availability. Plain `describe` preserves |
| 220 | the full nested semantics payload. A zero-match `list --search` remains |
| 221 | a failed lookup with exit code 1. |
| 222 | |
| 223 | The helper never writes a page or project file. Select one exact semantic |
| 224 | stock-shape match, inspect the emitted fragment, and insert it into the |
| 225 | hand-authored SVG with the normal patch workflow. Semantic discovery does not |
| 226 | force ordinary rectangles, ellipses, or lines through `render`; use the |
| 227 | simplest exact authoring form from the native-shape reference. A rendered |
| 228 | project-owned preset is one compact atomic `<g>` with direct registry-generated |
| 229 | visible paths. When one effect is justified, optional `--filter-id softShadow` |
| 230 | references one existing direct page-level filter under the shared shadow/glow |
| 231 | contract and applies it once to a shape preset. Connector presets do not accept |
| 232 | that option. The helper does not create the filter definition. `render-batch` |
| 233 | accepts a non-empty JSON array using the snake_case forms of the single-render |
| 234 | options; it validates every item and duplicate id before printing, so one |
| 235 | invalid item produces no partial fragment output. The batch remains |
| 236 | fragment-only input for one current construction, not a page generator or |
| 237 | project manifest. `adjustments` is a JSON object keyed by guide name, unlike |
| 238 | the repeatable single-render `--adjust NAME=FORMULA` option. |
| 239 | Quality check and export rerender the registry instead of relying on a hidden |
| 240 | carrier, preview wrapper, or stored preview fingerprint. PPTX import and |
| 241 | round-trip SVGs deliberately keep their expanded carrier/preview evidence and |
| 242 | are not rewritten into this authored form. Keep ordinary rectangles, ellipses, |
| 243 | freeform geometry, charts, icons, and ambiguous silhouettes as regular SVG. |
| 244 | See [`references/shared-standards-core.md`](../references/shared-standards-core.md) §1.5 for |
| 245 | the normative contract and |
| 246 | [`references/native-shape-authoring.md`](../references/native-shape-authoring.md) |
| 247 | for selection and authoring guidance. |
| 248 | |
| 249 | PowerPoint-style Merge Shapes materialization (source read-only; result paths |
| 250 | on stdout): |
| 251 | |
| 252 | ```bash |
| 253 | python3 scripts/shape_boolean_svg.py render slide.svg \ |
| 254 | --operation intersect \ |
| 255 | --source circle \ |
| 256 | --source card \ |
| 257 | --id overlap |
| 258 | ``` |
| 259 | |
| 260 | The first source owns result paint and is the primary geometry for `subtract`. |
| 261 | Local and ancestor transforms are baked into SVG-root coordinates. Replace the |
| 262 | operands with every returned path at the root in the primary operand's z-order; |
| 263 | `fragment` returns multiple stable sibling paths. Operands may be supported |
| 264 | closed geometry or supported horizontal implicit-LTR direct `<text>` whose exact |
| 265 | OpenType weight/style can be resolved; repeat `--font-dir PATH` for additional |
| 266 | font roots. Text is shaped to glyph outlines before the operation, so the |
| 267 | result remains editable freeform geometry but is no longer editable text. See |
| 268 | [`references/native-shape-authoring.md`](../references/native-shape-authoring.md) |
| 269 | §6 for the closed operand and failure contract. |
| 270 | |
| 271 | Create-template/source normalization (optional; never part of automatic export): |
| 272 | |
| 273 | ```bash |
| 274 | python3 scripts/extract_svg_assets.py <layered_svg_dir> --icons-dir <icons_dir> --icon-namespace imported --inplace --id-prefix layered |
| 275 | python3 scripts/extract_svg_assets.py <flat_svg_dir> --icons-dir <icons_dir> --icon-namespace imported --reuse-inventory <layered_inventory.json> --inplace --id-prefix flat |
| 276 | python3 scripts/extract_svg_pictures.py "<svg_file>" --select "<group_id>" --resource-root "<workspace>" --images-dir "<picture_assets_dir>" --inplace # optional create-template normalization: one selected group -> one SVG picture |
| 277 | python3 scripts/compact_svg_coordinates.py <template_workspace>/templates --inplace --keep-native-frames |
| 278 | python3 scripts/mirror_template_materialize.py <import_workspace> <template_workspace> # Type A mirror only; destination owns no roster |
| 279 | ``` |
| 280 | |
| 281 | `extract_svg_assets.py` fingerprints each extracted subtree before generated-ID |
| 282 | namespacing. Process the layered authoring view first, then pass its inventory to |
| 283 | the flat view with `--reuse-inventory`; matching flat subtrees reference the |
| 284 | existing layered asset instead of creating a duplicate file. Only unmatched |
| 285 | flat-only vectors create new assets. Create-template stores these assets once in |
| 286 | `<workspace>/icons/imported/` and writes `data-icon="imported/<name>"` references. |
| 287 | Inventories retain any `data-pptx-source-ref` values carried by the extracted |
| 288 | subtree, so re-inlining preserves authoring-manifest object identity. |
| 289 | Rerunning a namespaced pass against an already rewritten projection inventories |
| 290 | the existing references without progressively wrapping more parent geometry. |
| 291 | |
| 292 | Post-processing and export: |
| 293 | |
| 294 | ```bash |
| 295 | # Run only when the Design Spec's effective Speaker Notes outcome is enabled. |
| 296 | python3 scripts/total_md_split.py <project_path> |
| 297 | python3 scripts/finalize_svg.py <project_path> |
| 298 | python3 scripts/svg_to_pptx.py <project_path> |
| 299 | ``` |
| 300 | |
| 301 | When Speaker Notes is disabled, skip `total_md_split.py` and append |
| 302 | `--no-notes` to `svg_to_pptx.py` so stale files under `notes/` cannot be |
| 303 | embedded. |
| 304 | |
| 305 | `finalize_svg.py` optimizes ordinary raster images by default using `2x` display pixels and max `2560px`; validated nested crop transports retain source pixel dimensions because their inner `1×1` image is source-unit geometry rather than a rendered-pixel budget. Native `svg_to_pptx.py` defaults to `--image-sizing cap`: images that need neither resizing nor EXIF geometry normalization retain their original bytes, while oversized single-frame raster sources are re-encoded after resizing toward `2560px`. Cropped or stretched placements (including imported picture crops) retain enough source pixels to avoid undersupplying the visible frame. Use `svg_to_pptx.py --image-sizing display --image-scale 2 --image-quality 85` for an explicit compact export, or `--no-image-optimize` to force original image bytes. |
| 306 | |
| 307 | `finalize_svg.py` remains mandatory because it creates the self-contained `svg_final/` visual preview. Those SVGs may be opened directly or inserted into PowerPoint as SVG pictures. The only supported generated-PPTX path is `svg_output/` through the project SVG-to-DrawingML converter; `-s final` is diagnostic-only, and PowerPoint's manual Convert-to-Shape operation is unsupported. |
| 308 | |
| 309 | For SVG-authoring routes, `svg_output/` is the complete visible page-design source: every exported text, image, shape, background, and template-derived layout element is present in the page SVG or explicitly referenced by it. Export may translate represented content into Master/Layout/Slide parts or native objects, but it does not retrieve missing visible content from templates or planning files. Speaker notes, animation, narration, transitions, `template-fill-pptx`, and `native-enhance-pptx` remain separately owned capabilities. |
| 310 | |
| 311 | Native `svg_to_pptx.py` release export reads the project's explicit structure mode. Free-design, Brand-only, Style-only, and other `template_reuse_scope: style` projects use `flat`, omit Master/Layout mappings and SVG structure metadata, keep every represented object Slide-local, and materialize one clean project-owned Master plus one Blank Layout from the current color/typography lock. Stock content placeholders and unused built-in Layouts are removed; only the standard date/footer/slide-number capability hooks remain. A Deck/Layout application uses `structured` only when Strategist derives `template_reuse_scope: mirror|layout`: each project supplies unique Master/Layout definitions and one Layout assignment per generated page before SVG generation, and every SVG root repeats its assigned identity. A template-backed definition may remain unused and still register without a published carrier slide. Fixed Master/Layout visuals are direct semantic atoms; ordinary groups are invalid there, while one validated compact authored-preset `<g>` is the sole group exception because it compiles to one native shape. Reusable slots are top-level groups with positive design-zone bounds plus one compatible carrier. Composite `object` regions use explicit proxy binding, and zero-slot Layouts are valid. |
| 312 | |
| 313 | Structured template export compiles only the declared structure, maps locked typography/colors into PowerPoint defaults, creates the named Master/Layout parts, and reads the package back before publication. It never clusters pages, promotes repeated chrome heuristically, or invents placeholders. Flat export is the normal free-design/Brand-only/Style-only/style-scope route: it creates only the clean project-owned shell and performs no promotion or deduplication of Slide content. |
| 314 | |
| 315 | Template `page_layouts` records authoring-input provenance, `pptx_masters` / `pptx_layouts` own unique reusable definitions, and `page_pptx_layouts` owns page assignment. Strict preserves its Master/Layout/slot contract; adaptive retains its Master and may use a new Layout key only when fixed Layout atoms or slot topology/bounds change. `standard` / `fidelity` author new SVGs and a new Master/Layout/slot contract. `mirror` materializes a new workspace from the complete validated source identity graph—including unused Layout definitions—without semantic synthesis or gap filling, while mechanically expanding fixed-layer group wrappers into the direct atoms required by the structured contract. |
| 316 | |
| 317 | Legacy structured/template contracts using `baseline`, `template`, `preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, or incomplete root Master identity must be replaced by a new workspace created through [`create-template`](../workflows/create-template.md). Generate new structured SVG pages from that workspace; do not upgrade the existing PPTX/SVG in place. Explicit flat free-design/Brand-only/Style-only projects intentionally omit root Master identity. |
| 318 | |
| 319 | `pptx_to_svg.py` also writes a canonical `animations.json` whose default |
| 320 | transition is `none`. Page transitions produced by the current native |
| 321 | transition registry are read back with their effective options, exact duration, |
| 322 | automatic advance, and optional embedded WAV sound. Source transition XML |
| 323 | outside that closed writer/read-back contract remains diagnosed rather than |
| 324 | being normalized by guesswork. |
| 325 | Finite object-animation rows from the current writer are also projected when |
| 326 | their registry effect, effective options, pane order, trigger, exact duration, |
| 327 | relative delay, and top-level SVG group target all read back exactly. Advanced |
| 328 | timing, build/media trees, duration-less native rows, and unmapped targets stay |
| 329 | diagnosed/direct-preserve. |
| 330 | |
| 331 | `pptx_to_svg.py` annotates verified text-grid tables and conservative chart data with `data-pptx-replace-with` beside the visible SVG fallback and places the payload in `<metadata type="application/json">`; the parent claim selects the chart or table schema. Imported table/chart groups under this contract carry `data-pptx-import-source="pptx"`, whether active or fallback-only. Table import covers exact physical row/grid topology, canonical rectangular merges, safe solid/no-fill per-side borders, plain multi-paragraph cells, and a closed run-rich paragraph schema. Each rich run requires `text` and may use only `bold`, `italic`, `underline`, `strike`, `color`, `font_size`, one `font_family`, `lang`, and `alt_lang`. A merge must use the exact `rowSpan` / `gridSpan` / `hMerge` / `vMerge` physical topology with empty merge slaves. Presentation-only source run XML without a non-empty `effectLst` / `effectDag` normalizes; a table-cell run effect disables native replacement and adds a blocking effect diagnostic. Relationship-bearing text, extensions, line breaks, fields, tabs, bullets, broken text topology, unsafe border XML, non-solid fills, and other merge encodings remain fallback-only. For table style `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}`, the normalized SVG fallback resolves `wholeTbl`, `firstRow`, horizontal banding, theme colors/fonts, and direct cell/run overrides; other built-in/custom style families are not implied. |
| 332 | |
| 333 | Supported parsed column/bar/line/area, pie/doughnut, scatter, and bubble charts without a baked preview receive a deterministic readable fallback marked `data-pptx-fallback-kind="normalized"`. The importer additionally activates verified column/line/area combo charts, canonical OHLC stock charts, area charts with numeric date axes, verified scatter/bubble charts whose two value axes fit the closed `axes.x` / `axes.y` contract, radar charts, safe `of_pie` `serLines`, axis/title/legend normalization, and validated bar/column gap/overlap cases. Combo plots may retain independent primary/secondary category caches and workbook ranges. Both the category/value and XY contracts retain kind/position/visibility/label position/number format/min/max/major unit/reverse/major gridlines for native read-back. Scatter import derives effective `scatter_style` from uniform per-series line/marker/smooth state. The normalized XY fallback consumes only the two major-gridline flags; the C4/C5 additions do not expand the normalized renderer. `gapWidth` is accepted only as an integer in `0..500` and `overlap` only as an integer in `-100..100`; both normalize in native output, while malformed or out-of-range values fail closed. Safe common series paint forms and theme scheme colors are resolved; unknown series paint/style XML outside the explicit normalization boundaries still fails closed. Safe stock series style may pass the structural gate, but stock series, `hiLowLines`, and up-down bar local styling can still normalize under the data-object-first contract. The PowerPoint-native replacement remains allowed to normalize unmodeled no-fill/alpha/line/marker details and reports the route-level loss risk. Chart title/legend/axis titles and supported data-label flags are retained when the current schema can represent them. Fallback-only objects keep rendered SVG content or a baked chart preview and carry `data-pptx-replacement-status`, which validation and `--native-charts-and-tables` export report as a warning. An active marker without a renderer keeps `data-pptx-fallback-kind="placeholder"`; default export keeps the reconstruction-only placeholder and the native Chart/Table opt-in may still reconstruct it. |
| 334 | |
| 335 | The ChartEx importer accepts exactly the validated treemap, sunburst, histogram, pareto, box-whisker, waterfall, and funnel data models. Supported hierarchy/category/value/series/subtotal data round-trips to native output; source style, axes, labels, and binning may normalize. Numeric caches must be non-empty and finite with exact contiguous point topology. This is not arbitrary ChartEx import or presentation fidelity, and the ChartEx native writer still only promises valid payload palette entries rather than full source styling. |
| 336 | |
| 337 | Active imported table/chart markers carry `data-pptx-fallback-sha256`. Visible fallback edits, reachable SVG fragment-definition changes, marker-local reference-target changes, and marker transforms make the baseline stale: the mandatory quality checker warns, default export remains available, and `--native-charts-and-tables` fails instead of discarding the SVG edit. Generated authoring and reusable templates omit import provenance and a static baseline without warning. Hashless legacy imported markers that still carry PPTX import provenance remain convertible with a checker/replacement-route warning. Legacy `data-pptx-native*`, `data-pptx-visual-status`, and `data-pptx-route-status` spellings and the `--native-objects` option remain read-compatible; generated output and canonical commands use the replacement/fallback names and `--native-charts-and-tables`. |
| 338 | |
| 339 | Exporter-canonical classic charts also recover canonical solid series/slice |
| 340 | colors and exact one- or two-paragraph title styling; two paragraphs retain |
| 341 | their `title` / `subtitle` roles. Slide-number fields resolve to the display |
| 342 | number defined by `firstSlideNum`; standalone master/layout SVGs retain their |
| 343 | literal field fallback because they are shared by multiple slides. |
| 344 | |
| 345 | Image generation: |
| 346 | |
| 347 | ```bash |
| 348 | python3 scripts/image_gen.py "A modern futuristic workspace" |
| 349 | python3 scripts/image_gen.py --list-backends |
| 350 | python3 scripts/analyze_images.py <project_path>/images |
| 351 | ``` |
| 352 | |
| 353 | Generated-deck formulas do not use an image command. Author a native formula |
| 354 | marker in the page SVG; `svg_to_pptx.py` compiles its LaTeX metadata to editable |
| 355 | PowerPoint OMML. Forward compilation covers the explicitly documented Microsoft |
| 356 | 365 LaTeX and mhchem input profiles and fails closed outside them. |
| 357 | `pptx_to_svg.py` also reconstructs PPT Master-owned, validator-clean OMML into |
| 358 | canonical block/inline formula markers with visible linear SVG previews. This |
| 359 | is a closed-vocabulary reverse import, not arbitrary third-party |
| 360 | OMML-to-LaTeX conversion; unknown OMML is reported and kept opaque in tolerant |
| 361 | mode. The retained `latex_render.py` utility is |
| 362 | standalone legacy rasterization only and is not connected to either Generate |
| 363 | profile. |
| 364 | |
| 365 | Repository update: |
| 366 | |
| 367 | ```bash |
| 368 | python3 scripts/update_repo.py |
| 369 | python3 scripts/update_repo.py --skip-pip |
| 370 | ``` |
| 371 | |
| 372 | ## Recommendations |
| 373 | |
| 374 | - Keep one user-facing entry point per workflow at the top level of `scripts/` |
| 375 | - Move provider-specific or helper internals into subdirectories |
| 376 | - Prefer the unified entry points `project_manager.py`, `finalize_svg.py`, and `image_gen.py` |
| 377 | - Use `svg_output/` for the only supported native PPTX export and `svg_final/` for self-contained SVG visual preview / picture insertion |
| 378 | |
| 379 | ## Related Docs |
| 380 | |
| 381 | - [Conversion Tools](./docs/conversion.md) |
| 382 | - [Project Tools](./docs/project.md) |
| 383 | - [SVG Pipeline Tools](./docs/svg-pipeline.md) |
| 384 | - [PPTX Transition Core](./docs/pptx-transitions.md) |
| 385 | - [Image Tools](./docs/image.md) |
| 386 | - [Troubleshooting](./docs/troubleshooting.md) |
| 387 | - [Skill Entry](../SKILL.md) |
| 388 | |
| 389 | _Last updated: 2026-07-11_ |
| 390 |