| 1 | # Minimal Semantic SVG Markers |
| 2 | |
| 3 | PPT Master uses rendering-neutral compiler hints only where ordinary SVG cannot express PowerPoint Master, Layout, placeholder, native-object, or package behavior. |
| 4 | |
| 5 | ## 1. Boundary |
| 6 | |
| 7 | | Marker | Placement | Purpose | |
| 8 | |---|---|---| |
| 9 | | `data-pptx-page-role` | Root `<svg>` on flat pages only | Classify a free-design/brand-only page as `cover`, `toc`, `section`, `content`, or `ending`. | |
| 10 | | `data-pptx-master` / `data-pptx-master-name` | Root `<svg>` | Bind the page to one named PowerPoint Slide Master. | |
| 11 | | `data-pptx-layout` / `data-pptx-layout-name` | Root `<svg>` | Bind the page to one named Layout under that Master. | |
| 12 | | `data-pptx-layer="master"` | Direct atomic child of root | Promote one fixed visual object to the named Master. | |
| 13 | | `data-pptx-layer="layout"` | Direct atomic child of root | Promote one fixed visual object to the named Layout. | |
| 14 | | `data-pptx-placeholder` | Direct child `<g id>` of root | Declare one reusable Layout slot whose visible content remains Slide-local. | |
| 15 | | `data-pptx-role` | Structural page-frame element | Supply package, page-number, or animation behavior not already expressed by specialized metadata. | |
| 16 | |
| 17 | The completed SVG remains the full visible page. Removing the metadata must not change browser rendering. Do not copy visible text, geometry, style, or asset values into metadata. |
| 18 | |
| 19 | **Hard rule — route boundary**: Free-design, brand-only, and `template_reuse_scope: style` pages use `pptx_structure.mode: flat`, declare one canonical root `data-pptx-page-role`, and omit every Master/Layout/layer/placeholder marker in this document. Only deck/layout template pages whose AI-derived lock records `template_reuse_scope: mirror|layout` declare their final Master and Layout before drawing begins and omit `data-pptx-page-role`; the structured exporter compiles that contract and never selects, clusters, distills, or visually infers it. |
| 20 | |
| 21 | **Hard rule — specialized metadata wins**: Use Master/Layout/placeholder metadata for native structure, `data-pptx-replace-with` for optional PowerPoint-native Chart/Table replacement, and the imported/authored shape metadata defined in [`shared-standards-core.md`](./shared-standards-core.md) §§1.4–1.5. Do not duplicate those facts with `data-pptx-role`. |
| 22 | |
| 23 | --- |
| 24 | |
| 25 | ## 2. Master and Layout Atoms |
| 26 | |
| 27 | On structured `template_reuse_scope: mirror|layout` routes, Master and fixed Layout visuals are atomic root children: |
| 28 | |
| 29 | ```xml |
| 30 | <svg xmlns="http://www.w3.org/2000/svg" |
| 31 | viewBox="0 0 1280 720" |
| 32 | data-pptx-master="master-default" |
| 33 | data-pptx-master-name="Default Master" |
| 34 | data-pptx-layout="content-two-column" |
| 35 | data-pptx-layout-name="Two Column"> |
| 36 | <rect id="master-bg" data-pptx-layer="master" |
| 37 | x="0" y="0" width="1280" height="720" fill="#F8FAFC"/> |
| 38 | <path id="layout-rule" data-pptx-layer="layout" |
| 39 | d="M72 132H1208" stroke="#CBD5E1"/> |
| 40 | </svg> |
| 41 | ``` |
| 42 | |
| 43 | | Requirement | Rule | |
| 44 | |---|---| |
| 45 | | Placement | Every Master/Layout atom is a direct child of the root SVG and has a stable unique `id`. | |
| 46 | | Grouping | A `<g>` may not carry `data-pptx-layer="master|layout"`. Imported PowerPoint groups are recursively flattened and their transform/style/opacity/z-order semantics are pushed into atomic children. | |
| 47 | | Atomicity | One marked child must compile to one DrawingML object. A nested crop `<svg>` is allowed only when it is the supported single-picture carrier, not an arbitrary container. | |
| 48 | | Consistency | Pages sharing one Master key repeat the identical ordered Master atom contract. Pages sharing one `(master, layout)` pair repeat the identical ordered Layout atom contract. | |
| 49 | | Ownership | Concrete titles, body text, metrics, charts, tables, images, and page-specific decoration stay Slide-local or inside a declared slot. | |
| 50 | |
| 51 | > Note: Flattening a source PPTX group preserves supported appearance and native-layer ownership, but intentionally does not preserve the source group-editing hierarchy. |
| 52 | |
| 53 | --- |
| 54 | |
| 55 | ## 3. Layout Slots |
| 56 | |
| 57 | ### 3.1 Carrier-bound slot |
| 58 | |
| 59 | Use one direct root group as the authoring boundary and one compatible direct child as the visible PowerPoint placeholder carrier: |
| 60 | |
| 61 | ```xml |
| 62 | <g id="title-slot" |
| 63 | data-pptx-placeholder="title" |
| 64 | data-pptx-bounds="72 48 1136 72"> |
| 65 | <text id="title-carrier" |
| 66 | data-pptx-carrier="true" |
| 67 | x="72" y="100">Actual title</text> |
| 68 | </g> |
| 69 | ``` |
| 70 | |
| 71 | | Requirement | Rule | |
| 72 | |---|---| |
| 73 | | Placement | The slot `<g id>` is a direct root child. Structural metadata may not be nested below it. | |
| 74 | | Bounds | `data-pptx-bounds="x y width height"` is mandatory, finite, and positive. It describes the reusable design zone, not the current glyph/content tight bounds. | |
| 75 | | Carrier | The group contains exactly one compatible direct drawable child marked `data-pptx-carrier="true"`. Export unwraps that child into the real Slide placeholder binding. | |
| 76 | | Identity | `data-pptx-idx` is optional; effective indices must be unique within one Layout. Preserve a source index when reconstructing an existing PPTX. | |
| 77 | | Fixed decoration | Reusable decoration does not belong in the slot. Author it as a root Layout atom. Page-specific labels/captions use another slot or remain Slide-local. | |
| 78 | |
| 79 | Canonical placeholder values are `title`, `subtitle`, `body`, `picture`, `chart`, `table`, `object`, `media`, `date`, `footer`, and `slide-number`. Carrier compatibility is defined in [`pptx-structure-interface.md`](./pptx-structure-interface.md) §2. |
| 80 | |
| 81 | ### 3.2 Explicit composite proxy |
| 82 | |
| 83 | When one reusable region is a composite object that cannot bind to one real PowerPoint placeholder, declare the downgrade explicitly: |
| 84 | |
| 85 | ```xml |
| 86 | <g id="hero-composite-slot" |
| 87 | data-pptx-placeholder="object" |
| 88 | data-pptx-binding="proxy" |
| 89 | data-pptx-bounds="544 160 664 472"> |
| 90 | <rect x="544" y="160" width="664" height="472" fill="#E2E8F0"/> |
| 91 | <text x="576" y="214">Visible composite content</text> |
| 92 | </g> |
| 93 | ``` |
| 94 | |
| 95 | The visible group stays Slide-local. Export creates one hidden transparent matching placeholder proxy. Proxy binding is valid only for `object`; it is an explicit fallback, not the default slot form. |
| 96 | |
| 97 | ### 3.3 Zero-slot Layout |
| 98 | |
| 99 | A Layout may contain no slot groups. Cover, poster, full-visual, or other fixed-composition pages still declare their Master/Layout root identity and any fixed atoms; do not manufacture a full-page `object` placeholder merely to make the Layout non-empty. |
| 100 | |
| 101 | --- |
| 102 | |
| 103 | ## 4. Minimal Structural Roles |
| 104 | |
| 105 | Use `data-pptx-role` only when no specialized marker owns the behavior: |
| 106 | |
| 107 | | Value | Compiler behavior | |
| 108 | |---|---| |
| 109 | | `background` | Treat an otherwise unmarked background as static page framing for animation. | |
| 110 | | `decoration` | Exclude decorative framing from automatic entrance animation. | |
| 111 | | `header`, `footer`, `logo`, `watermark`, `chrome` | Identify Slide-local static framing without claiming Master/Layout ownership. | |
| 112 | | `page-number` | Identify a Slide-local number when no `slide-number` placeholder exists. | |
| 113 | |
| 114 | On flat pages, a direct root background image or full-canvas scrim/decoration |
| 115 | rectangle may carry the matching role and remain a primitive. Give the marked |
| 116 | element a stable unique `id`; do not add a `<g>` solely to avoid an |
| 117 | ungrouped-element advisory. |
| 118 | |
| 119 | Do not add structural roles to ordinary titles, body copy, cards, KPIs, diagrams, charts, icons, or images. |
| 120 | |
| 121 | --- |
| 122 | |
| 123 | ## 5. Validation and Migration |
| 124 | |
| 125 | For structured `template_reuse_scope: mirror|layout` projects, validation rejects: |
| 126 | |
| 127 | - a missing root Master/Layout identity or a page-to-lock mismatch; |
| 128 | - a Master/Layout `<g>`, nested structure marker, missing/stale id, or inconsistent shared atom contract; |
| 129 | - a slot without positive bounds, a carrier-bound slot without exactly one compatible carrier, or a proxy binding on a non-`object` slot; |
| 130 | - incomplete page mappings, cross-Master Layout-key reuse, or conflicting same-key Layout contracts. |
| 131 | |
| 132 | Legacy structured/template SVGs using unmapped `baseline`, `preserve`, `layout_strategy: distill`, `data-pptx-layout-kind`, `distilled`, `utility`, direct atomic placeholders, or an incomplete Master identity are not a second supported structured contract. Create a new workspace through [`create-template`](../workflows/create-template.md) before generation or export. An explicit `mode: flat` free-design/brand-only project is current and intentionally has no Master identity. Original PPTX Type A may preserve native identities that still exist in the package; legacy SVG-only Type B may guide `standard` / `fidelity` visually but does not authorize topology recovery. Export never derives, repairs, or migrates structure. |
| 133 |