Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

fix(docs): cover Quick lockless structured authoring in shared contracts

hugohe3cf5237977d5c
diff --git a/skills/ppt-master/references/pptx-structure-interface.md b/skills/ppt-master/references/pptx-structure-interface.md
index e584f1f2..1e26184e 100644
--- a/skills/ppt-master/references/pptx-structure-interface.md
+++ b/skills/ppt-master/references/pptx-structure-interface.md
@@ -2,7 +2,7 @@
# PPTX Structure Interface
-Conditional interface for PowerPoint Master, Layout, fixed-layer, and placeholder authoring. Load only when `spec_lock.md pptx_structure.mode` is `structured`.
+Conditional interface for PowerPoint Master, Layout, fixed-layer, and placeholder authoring. In Generate, load only for Default `spec_lock.md pptx_structure.mode: structured` or Quick structured Slide authoring from an installed Layout/Deck owner.
**Cross-reference map**: unqualified §1.5 and §4.2 references point to [`shared-standards-core.md`](./shared-standards-core.md); this file's own sections are §1–§3.
@@ -10,13 +10,15 @@ Conditional interface for PowerPoint Master, Layout, fixed-layer, and placeholde
Every new SVG project declares one deterministic route. Free-design, brand-only, and `template_reuse_scope: style` projects use `pptx_structure.mode: flat`, omit `pptx_masters` / `pptx_layouts` / `page_pptx_layouts` / `page_layouts`, and author no Master/Layout/layer/placeholder metadata. Export keeps all represented content Slide-local while materializing one clean project-owned Master plus one Blank Layout from the current color/typography lock; stock content placeholders and unused built-in Layouts are removed, while the standard date/footer/slide-number capability hooks remain. Deck/layout template projects whose AI-derived lock records `template_reuse_scope: mirror|layout` use `mode: structured`; `standard` / `fidelity` templates use their authored contract, while mirror templates use the validated source identities and parentage declared by the newly authored compact workspace.
+**Quick exception**: Lock-row/Strategist statements below are Default-only. Quick keeps free/Brand/Style-only flat; an installed Layout/Deck owner is structured unless visual-only, with identities on SVG roots and title/body anchors inferred from slot carriers.
+
**Hard rule — no structure inference**: Flat export performs no promotion or deduplication; every object stays Slide-local. Structured template export compiles only declared root identities, atomic fixed layers, and slot groups—it does not assign Layout families, cluster pages, infer placeholders, repair missing metadata, or migrate legacy contracts. Create a new current workspace through [`create-template`](../workflows/create-template.md) before generating structured pages.
**Layout reuse**: Reuse one Layout key only when its ordered fixed Layout atoms and slot ids/types/effective indices/default bounds/binding modes are identical. Different wording, data, imagery, crop, or Slide-local carrier geometry does not create a new Layout. A genuinely different reusable contract gets a new key even when both pages are semantically `content`.
**Zero-slot Layout**: A named Layout may contain no slots and no fixed Layout atoms. This is valid for a cover, poster, full-visual page, or other fixed composition. Do not manufacture an empty `utility` kind or full-page fake `object` slot.
-**Adaptive change**: Template `strict` preserves the selected prototype contract. `adaptive` retains the prototype Master and may use a current or new Layout identity only when Strategist already declared it in the complete plan and lock. If construction proves that fixed Layout atoms or slot topology/bounds must change, stop and return upstream for Strategist to add or revise the definition and page mapping before authoring resumes; Executor never mutates a reused key or the lock.
+**Adaptive change**: `strict` preserves the prototype. `adaptive` retains its Master and uses only a Layout declared in Default's plan/lock or permitted by Quick's frozen Template Application. Required atom/slot-contract changes return Default for repair/readback/validation; Quick creates a new Layout only under that permission. Never mutate a reused key.
## 2. Explicit PPTX Master / Layout / Placeholder Metadata
@@ -24,7 +26,7 @@ Every new SVG project declares one deterministic route. Free-design, brand-only,
**Project lock**: A Master row is `<master_key>: <PowerPoint picker name>`. A unique Layout row is `<layout_key>: <master_key> | <PowerPoint picker name> | <prototype source>`, where the source is a generated `P<NN>` or installed `template:<basename>`. A page assignment is `P<NN>: <layout_key>` under `page_pptx_layouts`. The SVG root values MUST match the assigned definition. A Layout key belongs to exactly one Master and must be globally unique. Reuse one key only when prototypes share identical ordered Layout atoms and slot ids/types/effective indices/default bounds/binding modes. An unused Layout uses a template SVG source and remains registered without a published carrier slide. Every structured route requires numeric `spec_lock.md` typography `title` / `body` rows.
-**Template behavior**: Strict preserves the selected prototype's declared Master/Layout/slot contract. Adaptive retains its Master and realizes the current or new Layout key/name declared by Strategist. A construction-discovered change to fixed Layout atoms or slot topology/bounds returns upstream for plan/lock repair, readback, and validation before authoring resumes. Mirror-created prototypes preserve validated source identity, parentage, slots, meaning, and similar presentation in compact new SVG; paint/geometry nodes need not be isomorphic. `standard` / `fidelity` never make source topology authoritative; mirror does not synthesize a replacement topology or fill missing facts.
+**Template behavior**: Strict preserves the selected prototype's Master/Layout/slot contract. Adaptive realizes only a Layout allowed by §1 and never mutates a reused key. Mirror-created prototypes preserve validated source identity, parentage, slots, meaning, and similar presentation in compact new SVG; paint/geometry nodes need not be isomorphic. `standard` / `fidelity` never make source topology authoritative; mirror does not synthesize replacement topology or fill missing facts.
Imported inherited-shape visibility remains an immutable analysis fact until a
structured mirror is materialized. The final mirror root carries that fact with
@@ -34,24 +36,27 @@ present. Authored `standard` / `fidelity` templates normally omit both and use
the default `true`. See
[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).
-**Master text-style contract**: Flat and structured export map the declared
-`title` anchor to every `a:defRPr` in Master `p:titleStyle`. Level 1 in both
+**Master text-style contract**: Default reads title/body anchors from its lock;
+structured Quick infers them from semantic slot carriers with deterministic
+fallbacks, while flat Quick retains stock defaults. An effective `title` anchor
+maps to every `a:defRPr` in Master `p:titleStyle`. Level 1 in both
`p:bodyStyle` and `p:otherStyle` uses the declared `body` anchor; levels 2–9
use a deterministic descending hierarchy from `15/16` through `8/16` of that
size, rounded to 0.5 pt and floored at the smaller of 8 pt or the body size.
Existing per-level indentation and bullet properties remain unchanged.
-| Master style | Locked source | XML field changed |
+| Master style | Effective source | XML field changed |
|---|---|---|
-| `p:titleStyle` | `typography.title` | Every `a:defRPr@sz` |
-| `p:bodyStyle` | `typography.body` | Level 1 plus derived level 2–9 `a:defRPr@sz` |
-| `p:otherStyle` | `typography.body` | Level 1 plus derived level 2–9 `a:defRPr@sz` |
+| `p:titleStyle` | title anchor | Every `a:defRPr@sz` |
+| `p:bodyStyle` | body anchor | Level 1 plus derived level 2–9 `a:defRPr@sz` |
+| `p:otherStyle` | body anchor | Level 1 plus derived level 2–9 `a:defRPr@sz` |
**Hard rule — narrow scope**: This Master update changes only Master
`p:txStyles//a:defRPr@sz`; it preserves level indentation, bullet, margin, and
paragraph settings. It does not rewrite direct run sizes on generated slides,
so the initial slide rendering remains controlled by the authored SVG. Missing
-`title` or `body` rows fail flat or structured export.
+Default `title` or `body` rows fail flat or structured export; Quick structured
+uses inferred/fallback anchors.
**Layout level-one text-default contract**: For every text-bearing placeholder
whose first prototype run has a direct `a:rPr@sz`, explicit Layout export copies that
diff --git a/skills/ppt-master/references/semantic-svg.md b/skills/ppt-master/references/semantic-svg.md
index d4230943..4dcedcb9 100644
--- a/skills/ppt-master/references/semantic-svg.md
+++ b/skills/ppt-master/references/semantic-svg.md
@@ -16,7 +16,7 @@ PPT Master uses rendering-neutral compiler hints only where ordinary SVG cannot
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.
-**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.
+**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 Default `template_reuse_scope: mirror|layout` pages or Quick pages authoring an installed Layout/Deck owner's structure 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.
**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`.
diff --git a/skills/ppt-master/references/shared-standards-core.md b/skills/ppt-master/references/shared-standards-core.md
index 87c94e96..d943adbe 100644
--- a/skills/ppt-master/references/shared-standards-core.md
+++ b/skills/ppt-master/references/shared-standards-core.md
@@ -8,7 +8,7 @@ Mandatory reference for every route that authors or regenerates slide visuals th
|---|---|
| Default or Quick Generate; otherwise noncanonical/alpha paint, advanced line or text treatment, gradient/filter/effect, transform, freeform/radial geometry, or constructed style | [`svg-effects.md`](./svg-effects.md) |
| A page will use a preset pattern fill or evaluate native chart/table replacement | [`native-data-interface.md`](./native-data-interface.md) before deciding eligibility or emitting metadata |
-| `pptx_structure.mode: structured` | [`pptx-structure-interface.md`](./pptx-structure-interface.md) |
+| Default structured lock, or Quick installed Layout/Deck structured authoring | [`pptx-structure-interface.md`](./pptx-structure-interface.md) |
**Default — shared aesthetic baseline (may be overridden by explicit user, installed template / brand, or locked / Quick-resolved visual-style requirements)**: Required / Forbidden technical contracts remain absolute. When a higher authority is silent, build clear hierarchy through typography and leading, alignment, negative space, purposeful imagery / icons, and restrained repetition before decoration. Deliberate tightness, imbalance, off-axis placement, or container-heavy structure remains valid when that authority calls for it.
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index 409813be..5afc8be6 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -7,6 +7,6 @@ Compatibility router for the split SVG specifications. Runtime routes load the c
| XML/SVG foundation, shared visual-quality defaults, page closure, grouping | [`shared-standards-core.md`](./shared-standards-core.md) | Always for SVG authoring |
| Advanced effects and geometry | [`svg-effects.md`](./svg-effects.md) | Always for Default / Quick Generate; otherwise when the corresponding effect or geometry is used |
| Preset patterns and native chart/table metadata | [`native-data-interface.md`](./native-data-interface.md) | Corresponding native-data interface is used |
-| Master/Layout/placeholder structure | [`pptx-structure-interface.md`](./pptx-structure-interface.md) | `pptx_structure.mode: structured` |
+| Master/Layout/placeholder structure | [`pptx-structure-interface.md`](./pptx-structure-interface.md) | Default structured lock, or Quick installed Layout/Deck structured authoring |
**Hard rule**: This file is a routing pointer, not a combined runtime authority. Follow the selected route's required modules; do not load every remaining conditional module by default.
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 6d680b27..3164a910 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -759,7 +759,7 @@ Behavior:
inputs and package-level processing.
- For PPTX template-import workspaces, use `-s svg-flat` when you need a visual round-trip check. The layered `svg/` tree is the machine-readable template source and intentionally does not inline inherited master / layout decoration into each slide.
- Native mode is strict about unsupported visual SVG elements: if a visual element cannot be represented or safely preserved, export fails with the SVG file, element tag, and position instead of silently dropping content. Dangerous compatibility export first applies the registry in `svg_compatibility.py`; it currently lowers a filter on an otherwise attribute-free one-child group whose child is a supported native filter target. The complete strict preflight then runs normally; every remaining contract, resource, conversion, relationship, or package error still blocks export.
-- Omitting `--pptx-structure` reads `spec_lock.md`. Free-design, brand-only, and `template_reuse_scope: style` releases declare `mode: flat`, omit Master/Layout mappings and SVG structure metadata, and materialize one clean project-owned Master plus one Blank Layout from the current lock. Deck/layout templates use `mode: structured` only for `template_reuse_scope: mirror|layout`, with complete unique `pptx_masters` / `pptx_layouts` rosters and one `page_pptx_layouts` assignment per page. A template-backed Layout definition may remain unused by pages and still register in the final package.
+- Default export omitting `--pptx-structure` reads `spec_lock.md`. Free-design, brand-only, and `template_reuse_scope: style` releases declare `mode: flat`, omit Master/Layout mappings and SVG structure metadata, and materialize one clean project-owned Master plus one Blank Layout from the current lock. Deck/layout templates use `mode: structured` only for `template_reuse_scope: mirror|layout`, with complete unique `pptx_masters` / `pptx_layouts` rosters and one `page_pptx_layouts` assignment per page. A template-backed Layout definition may remain unused by pages and still register in the final package.
- On structured template routes, every page root repeats Master/Layout keys and picker names. Master/Layout fixed visuals are direct semantic atoms. Ordinary layer `<g>` elements are invalid; one validated compact authored-preset `<g>` emitted by `preset_shape_svg.py` is the sole group exception because it compiles to one native shape.
- Every visible direct root `<g>` except a compact helper-authored preset atom requires root-coordinate `data-pptx-bounds`; nested bounds are ignored. The text-free preset atom remains top-level when standalone, uses `data-pptx-frame`, and never carries bounds. Frame/native metadata never replaces bounds on any other group; placeholder bounds also define the slot frame. Checker compares root bounds with `viewBox`, descendant text with its module using DrawingML wrapping headroom, and every estimable visible text carrier directly with the root `viewBox` before that headroom. Images, shapes, paths, `<use>`, effects, and object frames are excluded from module containment. Per side, ≤`1px` is ignored; module overflow ≤`5%` warns and >`5%` fails, while larger page text overflow always fails. Bounds never clip/reflow; unestimable visible text warns. A wholly off-canvas direct-root Morph endpoint may opt out of page containment with `data-pptx-morph-staging="true"`; it still needs valid module bounds, retained Morph uses an explicit pair, and partial overflow remains blocking.
- Missing required root bounds fails on final pages/templates and under `--template-mode`; references warn until adapted.
diff --git a/skills/ppt-master/templates/decks/README.md b/skills/ppt-master/templates/decks/README.md
index bd96498f..44069bf3 100644
--- a/skills/ppt-master/templates/decks/README.md
+++ b/skills/ppt-master/templates/decks/README.md
@@ -43,9 +43,9 @@ exact roots are `library`; other exact roots remain
stage, which owns path normalization, compatibility checks, installation, and
installation after Stage 1 and before Stage 2. Template-aware reading begins in final Stage 2 from the
installed project-local copy.
-Quick applies a supplied exact Deck root directly and otherwise uses free
-design. It uses installed prototypes as flat authoring inputs; reusable
-native Master/Layout compilation remains a default lock-backed capability.
+Quick applies a supplied exact Deck root directly and otherwise uses flat free
+design. It authors the installed Master/Layout/slot contract as lockless
+structured Slides unless the user explicitly requests visual-only flat use.
This file owns the Deck schema and application-context boundary. Chat discovery
reads the same index and returns exact roots; a bare ID never resolves
implicitly.
diff --git a/skills/ppt-master/templates/layouts/README.md b/skills/ppt-master/templates/layouts/README.md
index 4bb5ec7d..b6fb85b7 100644
--- a/skills/ppt-master/templates/layouts/README.md
+++ b/skills/ppt-master/templates/layouts/README.md
@@ -58,9 +58,9 @@ Choosing and confirming an entry runs the conditional
stage, which owns path normalization, compatibility checks, installation, and
installation after Stage 1 and before Stage 2. Template-aware reading begins in final Stage 2 from the
installed project-local copy.
-Quick applies a supplied exact Layout root directly and otherwise uses free
-design. It uses installed prototypes as flat authoring inputs; reusable
-native Master/Layout compilation remains a default lock-backed capability.
+Quick applies a supplied exact Layout root directly and otherwise uses flat free
+design. It authors the installed Master/Layout/slot contract as lockless
+structured Slides unless the user explicitly requests visual-only flat use.
This file owns the Layout schema and its identity/application boundary. Chat
discovery reads the same index and returns exact roots; a bare ID never resolves
implicitly.
diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.md
index 57b58e48..1901f378 100644
--- a/skills/ppt-master/workflows/profiles/quick-generate.md
+++ b/skills/ppt-master/workflows/profiles/quick-generate.md
@@ -682,8 +682,8 @@ Layout under the selected Master when the frozen application paragraph calls
for adaptation; it never infers ownership from repeated Slide-local geometry.
The lockless final checker and exporter derive `structured` solely from that
complete SVG roster. Include all visible content and resource references in each
-SVG, and set one root `data-pptx-page-role` from `cover`, `toc`, `section`,
-`content`, or `ending` independently of the native structure metadata.
+SVG. Flat pages set one root `data-pptx-page-role` from `cover`, `toc`,
+`section`, `content`, or `ending`; structured pages omit it.
**Typography**: name a concrete target-installed/approved PowerPoint family
under [`shared-standards-core.md`](../../references/shared-standards-core.md)