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
refactor(prompts): split role and SVG authorities by trigger
hugohe385d3489a70a6
diff --git a/AGENTS.md b/AGENTS.mdindex 4ac81b2f..b9eadc03 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -20,7 +20,7 @@ PPT Master is an AI-driven presentation generation system. Multi-role collaborat## Execution Requirements- For any `brand`, `layout`, or `deck` workspace creation from PPTX/SVG, images/PDFs, documents/websites, brand assets, direct text, or mixed references, enter [`skills/ppt-master/workflows/create-template.md`](skills/ppt-master/workflows/create-template.md); it keeps the fixed Create Template name and dispatches exactly one of [`create-brand`](skills/ppt-master/workflows/create-template/create-brand.md), [`create-layout`](skills/ppt-master/workflows/create-template/create-layout.md), or [`create-deck`](skills/ppt-master/workflows/create-template/create-deck.md).-- Technical SVG/PPT constraints live in [`skills/ppt-master/references/shared-standards.md`](skills/ppt-master/references/shared-standards.md).+- Always-on SVG constraints live in [`skills/ppt-master/references/shared-standards-core.md`](skills/ppt-master/references/shared-standards-core.md). Load [`svg-effects.md`](skills/ppt-master/references/svg-effects.md), [`native-data-interface.md`](skills/ppt-master/references/native-data-interface.md), and [`pptx-structure-interface.md`](skills/ppt-master/references/pptx-structure-interface.md) only when their documented execution triggers apply.- Canvas choices live in [`skills/ppt-master/references/canvas-formats.md`](skills/ppt-master/references/canvas-formats.md).- Icon library details live in [`skills/ppt-master/templates/icons/README.md`](skills/ppt-master/templates/icons/README.md).@@ -46,6 +46,8 @@ python3 skills/ppt-master/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or# Project managementpython3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_dirs_or_URLs...> --move+python3 skills/ppt-master/scripts/project_manager.py scaffold-spec <project_path>+python3 skills/ppt-master/scripts/project_manager.py scaffold-lock <project_path>python3 skills/ppt-master/scripts/project_manager.py validate <project_path># Icon selection — copy chosen library icons into <project>/icons/ (missing names reported + non-zero = re-pick)@@ -92,7 +94,7 @@ For serial post-processing and export, follow [`generate-pptx.md`](skills/ppt-ma- `skills/ppt-master/SKILL.md` — global discipline and route-entry authority.- `skills/ppt-master/workflows/generate-pptx.md` — Generate PPTX Step 1–7 authority.-- `skills/ppt-master/references/` — role definitions and technical specifications.+- `skills/ppt-master/references/` — role cores plus conditionally loaded role and technical modules.- `skills/ppt-master/scripts/` — runnable tool scripts.- `skills/ppt-master/scripts/docs/` — topic-focused script docs.- `skills/ppt-master/templates/` — layout templates, chart templates, icon library, brand presets.diff --git a/docs/powerpoint-svg-mapping.md b/docs/powerpoint-svg-mapping.mdindex 1cbf8dee..109407fd 100644--- a/docs/powerpoint-svg-mapping.md+++ b/docs/powerpoint-svg-mapping.md@@ -8,7 +8,7 @@This guide answers one question from the PowerPoint user's point of view: **for a PowerPoint feature, what project representation owns it, and what survives export or import?** PowerPoint semantics are therefore the primary index. SVG elements appear only as the implementation of a specific PowerPoint capability.-This is a public capability and import-behavior map, not a second generated-SVG syntax specification and not a promise to convert arbitrary SVG or arbitrary OOXML. The canonical generated-authoring contract remains [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md); when generated syntax differs, that contract wins. PPTX import recovery modes and user-visible degradation belong to §11 here and to the [conversion command reference](../skills/ppt-master/scripts/docs/conversion.md), while the parser implementation remains the exact source of truth. A feature not listed here is not implicitly supported.+This is a public capability and import-behavior map, not a second generated-SVG syntax specification and not a promise to convert arbitrary SVG or arbitrary OOXML. The canonical generated-authoring contract is the authority set selected through [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md); when generated syntax differs, the applicable module wins. PPTX import recovery modes and user-visible degradation belong to §11 here and to the [conversion command reference](../skills/ppt-master/scripts/docs/conversion.md), while the parser implementation remains the exact source of truth. A feature not listed here is not implicitly supported.The main route compiles **project-canonical SVG**, not general browser SVG:@@ -48,7 +48,7 @@ Each row owns one PowerPoint capability. The mapping cardinality is not always o| Theme colors and fonts | Roles locked in `spec_lock.md`; canonical SVG uses the resolved values | Theme-aware tokens where an exact locked role can be retained; otherwise direct DrawingML values | `Native-stable` for registered roles | New pages must not invent unlocked colors, fonts, or text sizes || PowerPoint-only package identity | `spec_lock.md` structure declarations and the package builder | Presentation, Master, Layout, relationship, and content-type registrations | Read back from package structure, not inferred from page appearance | Final-package read-back must match the declared roster |-See [`canvas-formats.md`](../skills/ppt-master/references/canvas-formats.md) for supported canvases and [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md) §4.1 for the normative root-`viewBox` contract.+See [`canvas-formats.md`](../skills/ppt-master/references/canvas-formats.md) for supported canvases and [`shared-standards-core.md` §4.1](../skills/ppt-master/references/shared-standards-core.md#41-semantic-svg-marker-contract) for the normative root-`viewBox` contract.## 2. Master, Layout, background, and placeholder features@@ -80,9 +80,9 @@ See [`canvas-formats.md`](../skills/ppt-master/references/canvas-formats.md) for| Page role such as cover/content/ending | Flat-route root `data-pptx-page-role` compiler hint | Routing/validation hint; not a native PowerPoint page type | No independent OOXML object | Structured pages use explicit Master/Layout identity instead || Slide sections and custom shows | No SVG mapping | Not authored by the main generation route | `Direct preservation` where a source-preserving workflow owns them | Do not encode them as visual metadata |-The exact structured metadata and slot grammar live in the [PPTX structure section of the normative standards](../skills/ppt-master/references/shared-standards.md#pptx-structure-routing).+The exact structured metadata and slot grammar live in the [PPTX Structure Interface](../skills/ppt-master/references/pptx-structure-interface.md#1-pptx-structure-routing).-Internal identifiers and PowerPoint display names are separate concerns: Master and Layout keys use the restricted project ASCII identifier grammar, while picker names may contain spaces. Every Layout definition also names its parent Master and one explicit prototype source. The normative standards own the exact row syntax.+Internal identifiers and PowerPoint display names are separate concerns: Master and Layout keys use the restricted project ASCII identifier grammar, while picker names may contain spaces. Every Layout definition also names its parent Master and one explicit prototype source. The PPTX Structure Interface owns the exact row syntax.## 3. PowerPoint shapes and drawing objects@@ -108,7 +108,7 @@ Internal identifiers and PowerPoint display names are separate concerns: MasterProject-authored presets deliberately use a compact representation, while PPTXimport keeps the expanded evidence needed for lossless round-trip decisions.The exact machine contract remains in-[`shared-standards.md`](../skills/ppt-master/references/shared-standards.md), and+[`shared-standards-core.md`](../skills/ppt-master/references/shared-standards-core.md), andpreset selection and authoring behavior are documented in[`native-shape-authoring.md`](../skills/ppt-master/references/native-shape-authoring.md).@@ -122,13 +122,13 @@ preset selection and authoring behavior are documented in| Significant text whitespace | Exact `xml:space="default"` or `xml:space="preserve"` on `<text>`/`<tspan>` | Normalized or preserved U+0020 text in editable DrawingML runs | `Native-normalized`; inline run ownership is retained | Uses the project Chromium/SVG2 contract: LF/TAB become spaces, `default` collapses across runs, `preserve` retains them, and Unicode spacing characters remain literal; CSS `white-space` and legacy SVG 1.1 newline deletion are outside the mapping || Font family | Canonical `font-family` resolved against the project lock | Direct typeface or registered theme font | `Native-stable` within installed/font-substitution limits | Unlocked or unavailable fonts are reported by validation || Font size | Finite unitless SVG pixels, for example `font-size="24"` | DrawingML hundredths of a point; `1 px = 0.75 pt` | `Native-stable` after unit conversion | Generated authoring uses only unitless px; registered legacy units are compatible input and warn, while unknown units error; DrawingML minimum is 1 pt |-| Font weight | Registered `font-weight` on `<text>`/`<tspan>` | DrawingML regular/bold run switch | `Native-normalized`; numeric weights collapse to the DrawingML boolean boundary | The exact value grammar and aliases belong to [`shared-standards.md` §6.7](../skills/ppt-master/references/shared-standards.md#67-advanced-text-treatments) |-| Italic, underline, and strike | Registered `font-style` / `text-decoration` on `<text>`/`<tspan>` | DrawingML italic, underline, and strike run properties | `Native-stable` for registered tokens | Unknown tokens are rejected; the exact grammar belongs to [`shared-standards.md` §6.7](../skills/ppt-master/references/shared-standards.md#67-advanced-text-treatments) |+| Font weight | Registered `font-weight` on `<text>`/`<tspan>` | DrawingML regular/bold run switch | `Native-normalized`; numeric weights collapse to the DrawingML boolean boundary | The exact value grammar and aliases belong to [`svg-effects.md` §6.7](../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) |+| Italic, underline, and strike | Registered `font-style` / `text-decoration` on `<text>`/`<tspan>` | DrawingML italic, underline, and strike run properties | `Native-stable` for registered tokens | Unknown tokens are rejected; the exact grammar belongs to [`svg-effects.md` §6.7](../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || Text fill and transparency | Canonical fill plus run alpha | DrawingML run fill and alpha | `Native-normalized` | Use the semantic alpha channel, not an unregistered CSS effect || Text outline | Registered stroke on text | DrawingML run outline | `Native-normalized` | Review when outline carries fine visual meaning |-| Text alignment | Registered `text-anchor` and paragraph semantics | Paragraph alignment plus normalized text-frame position | `Native-normalized` | Run-level anchoring and browser baseline heuristics are unsupported; exact placement belongs to [`shared-standards.md` §6.7](../skills/ppt-master/references/shared-standards.md#67-advanced-text-treatments) |+| Text alignment | Registered `text-anchor` and paragraph semantics | Paragraph alignment plus normalized text-frame position | `Native-normalized` | Run-level anchoring and browser baseline heuristics are unsupported; exact placement belongs to [`svg-effects.md` §6.7](../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || Vertical text-frame alignment | No canonical generated-SVG control; generated text boxes use top anchoring | Top-anchored DrawingML text body | Imported vertical text may be normalized, but the main route does not expose a general authoring control | Do not infer vertical alignment from SVG baseline or browser layout behavior |-| Character spacing | Registered `letter-spacing` | DrawingML character spacing | `Native-normalized` | Unsupported CSS typography, out-of-range DrawingML spacing, and negative tracking that collapses a generated run advance or text-frame extent to a non-positive value are rejected under [`shared-standards.md` §6.7](../skills/ppt-master/references/shared-standards.md#67-advanced-text-treatments) |+| Character spacing | Registered `letter-spacing` | DrawingML character spacing | `Native-normalized` | Unsupported CSS typography, out-of-range DrawingML spacing, and negative tracking that collapses a generated run advance or text-frame extent to a non-positive value are rejected under [`svg-effects.md` §6.7](../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || Bulleted paragraph | Recognized leading bullet form | Native DrawingML bullet | `Native-normalized` | Only the registered bullet grammar is promoted || Rotated text | Supported transform on the text object | Rotated text shape | `Native-normalized` | Skewed text and browser-only transforms are unsupported || Text shadow or glow | Supported filter/effect contract | One native outer shadow or glow | `Approximate` | One supported effect graph only; review material effects |@@ -195,12 +195,12 @@ Imported chart groups classify their visible fallback with `data-pptx-fallback-k| Visually drawn chart | Ordinary SVG geometry and text | Independent editable PowerPoint shapes | Fidelity follows each component row | It has no “Edit Data” workbook || PowerPoint-native classic chart | One `<g data-pptx-replace-with="chart">` with registered JSON data in `<metadata type="application/json">` and a visible fallback | `p:graphicFrame`, classic chart part, and embedded workbook | Supported imports reconstruct a fallback plus replacement metadata | Chart type and data must match the closed schema; requires `--native-charts-and-tables` || Native ChartEx chart | Same marker interface with a supported ChartEx family | `cx:chart` part and embedded workbook | Supported families can reconstruct semantically | Only the registered family/field combinations are accepted |-| Chart title, legend, axes, labels, and series formatting | Registered native-chart metadata | Native chart properties | `Native-normalized` | Exact fields and supported families remain normative in `shared-standards.md` |+| Chart title, legend, axes, labels, and series formatting | Registered native-chart metadata | Native chart properties | `Native-normalized` | Exact fields and supported families remain normative in `native-data-interface.md` || Chart caption, source, or footnote | Ordinary companion SVG text outside the replacement marker | Editable slide text boxes beside the chart | `Native-stable` as text | Do not hide slide prose inside chart JSON || Edited SVG fallback with stale replacement metadata | Updated visible SVG plus stale hash | Default export keeps the visible SVG; native replacement fails | Explicit safety behavior | The compiler never discards a newer visual edit silently || Unsupported 3D or deferred chart family | SVG-drawn chart, baked asset, or direct source preservation | No guessed native chart | Fallback / `Direct preservation` | Unsupported aliases must fail native validation |-The exhaustive chart/table schemas and supported family list intentionally remain in the [normative replacement contract](../skills/ppt-master/references/shared-standards.md#powerpoint-native-chart--table-replacement-markers-opt-in).+The exhaustive chart/table schemas and supported family list intentionally remain in the [Native Data Interface replacement contract](../skills/ppt-master/references/native-data-interface.md#2-powerpoint-native-chart--table-replacement-markers-opt-in).## 9. PowerPoint playback and package features@@ -281,7 +281,7 @@ A generated-SVG warning is not permission to guess. It is reserved for a determiTreat a mapping change as a compiler change, not as a permissive SVG parser tweak:1. Name the PowerPoint capability and its intended editable DrawingML result.-2. Define one canonical project-SVG or sidecar representation in [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md).+2. Define one canonical project-SVG or sidecar representation in the applicable authority module selected by [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md).3. State accepted compatible input separately from generated authoring.4. Implement export, and implement import only when semantic reconstruction is supported.5. Add checker classification: error for invalid/ambiguous input, warning only for deterministic compatible or approximate input.@@ -293,4 +293,4 @@ Implementation entry points:- Export: [`svg_to_pptx.py`](../skills/ppt-master/scripts/svg_to_pptx.py) and `scripts/svg_to_pptx/`- Import: [`pptx_to_svg.py`](../skills/ppt-master/scripts/pptx_to_svg.py) and `scripts/pptx_to_svg/`- Validation: [`svg_quality_checker.py`](../skills/ppt-master/scripts/svg_quality_checker.py)-- Canonical contract: [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md)+- Authority router: [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md)diff --git a/docs/roadmap.md b/docs/roadmap.mdindex 6483f926..2c310992 100644--- a/docs/roadmap.md+++ b/docs/roadmap.md@@ -31,16 +31,16 @@ Structural capability growth since March 2026. Single flags and incremental poli- **Live Preview enters the main pipeline** ([`workflows/stages/live-preview.md`](../skills/ppt-master/workflows/stages/live-preview.md)) — browser preview, click elements to write annotations, say "apply my annotations" and the AI rewrites that region (built on [@WodenJay](https://github.com/WodenJay)'s [PR #85](https://github.com/hugohe3/ppt-master/pull/85))- **Create a reusable template workspace from a PPTX** ([`workflows/create-template.md`](../skills/ppt-master/workflows/create-template.md)) — read the supported theme / Master / Layout / asset facts that still exist in the package, then author or materialize a new validated Brand / Layout / Deck workspace without modifying the source PPTX-- **AI image three-dimension system** rendering × palette × type + Strategist h.5 lock, downstream consumes a fixed contract+- **AI image three-dimension system** rendering × palette × type + [`strategist-image.md`](../skills/ppt-master/references/strategist-image.md) §2 lock, downstream consumes a fixed contract- **AI image `hero_page` dual-track** — local insert + full-canvas hero image coexist- **Brand identity preset subsystem** ([`workflows/create-template/create-brand.md`](../skills/ppt-master/workflows/create-template/create-brand.md)) — the Create Brand child workflow extracts and reuses brand palette / typography / logo / voice under the fixed Create Template entry- **Visual self-review stage** ([`workflows/stages/visual-review.md`](../skills/ppt-master/workflows/stages/visual-review.md)) — rubric-based per-page check of AI-generated SVGs- **AI image: Type concept boundary clarification** — Type is now narrowed to "the internal geometric skeleton of a local infographic block" (11 real skeletons); the four pseudo-types (hero / background / portrait / typography) fold back into `page_role: hero_page` plus four composition primitives (single-subject / portrait / typographic / atmospheric); hero_page text layering rule (visual keywords embedded, editable text via SVG overlay)- **Brutalist AI newspaper example deck shipped** ([`examples/ppt169_brutalist_ai_newspaper_2026/`](../examples/ppt169_brutalist_ai_newspaper_2026/)) — first of the three P0 capability-backing demos: wall-to-wall small type + irregular columns + halftone monochrome + single-spot red + real native shapes; 10-page editorial annual report stressing text-position precision and cross-page consistency- **Kubernetes Blueprint example deck shipped** ([`examples/ppt169_kubernetes_blueprint_2026/`](../examples/ppt169_kubernetes_blueprint_2026/)) — second of the three P0 capability-backing demos: isometric technical-drawing aesthetic + blueprint cyan/amber palette + hand-authored SVG geometry (no raster images) + custom drawing-in animation; 10-page Kubernetes architecture walkthrough stressing geometric shape generalization and chart-structure extensibility-- **AI image `custom` escape hatch** — `rendering` / `palette` / hero composition each accept `custom` + a one-paragraph `*_behavior` prose, replacing the false "default to vector-illustration / cool-corporate" fallback; end-to-end contract spans [`image-renderings/_index.md`](../skills/ppt-master/references/image-renderings/_index.md) §1.5, [`image-palettes/_index.md`](../skills/ppt-master/references/image-palettes/_index.md) §2, Strategist h.5 hard-rule (≤1 custom per dimension; one candidate may carry both), spec_lock fields, and Image_Generator Step 2 consumption branch+- **AI image `custom` escape hatch** — `rendering` / `palette` / hero composition each accept `custom` + a one-paragraph `*_behavior` prose, replacing the false "default to vector-illustration / cool-corporate" fallback; end-to-end contract spans [`image-renderings/_index.md`](../skills/ppt-master/references/image-renderings/_index.md) §1.5, [`image-palettes/_index.md`](../skills/ppt-master/references/image-palettes/_index.md) §2, [`strategist-image.md`](../skills/ppt-master/references/strategist-image.md) §2 hard-rule (≤1 custom per dimension; one candidate may carry both), spec_lock fields, and Image_Generator Step 2 consumption branch- **Template architecture: three-kind consolidation** ([`docs/templates-architecture.md`](./templates-architecture.md)) — brand / layout / deck split into three independent dirs with per-kind schemas + segment-level fusion + git-style conflict resolution; [Generate PPTX Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option) dispatches per `kind`, trigger rule remains "explicit path only"-- **Pattern fill PPTX safety net** — `svg_quality_checker.py` warns when a referenced `<pattern>` lacks `data-pptx-pattern` and the converter will use its compatible `ltUpDiag` fallback; it still rejects `patternTransform` and values outside OOXML `ST_PresetPatternVal`. `shared-standards.md §7` documents the closed preset enum and color resolution from importer metadata or child paint+- **Pattern fill PPTX safety net** — `svg_quality_checker.py` warns when a referenced `<pattern>` lacks `data-pptx-pattern` and the converter will use its compatible `ltUpDiag` fallback; it still rejects `patternTransform` and values outside OOXML `ST_PresetPatternVal`. [`native-data-interface.md` §1](../skills/ppt-master/references/native-data-interface.md#1-pattern-fill--pattern-with-pptx-preset-annotation) documents the closed preset enum and color resolution from importer metadata or child paint- **LaTeX math formula rendering shipped** ([`scripts/latex_render.py`](../skills/ppt-master/scripts/latex_render.py)) — Strategist locks one of three policies (`mixed` / `render-all` / `text-only`) inside the Typography confirmation and writes an explicit `images/formula_manifest.json`; the renderer walks a codecogs → quicklatex → mathpad → wikimedia fallback chain and emits transparent PNGs that land in §VIII as `Acquire Via: formula` / `Status: Rendered` rows; formula-heavy decks (academic / engineering / educational) finally have a native rendering route. Formula selection is a Strategist decision — the renderer never scans source files for `$...$` markers- **Live preview direct editing — L1 / L2 / L3** ([`workflows/stages/live-preview.md`](../skills/ppt-master/workflows/stages/live-preview.md)) — the browser editor gains deterministic in-place edits with no AI round-trip: text content (L1), presentation attributes like fill / stroke / font-size (L2), and on-canvas geometry (L3) — drag a selected element to move it, arrow-key nudge (`Shift` = 10px), multi-select, plus a right-click overlap picker for stacked shapes. Edits stage with `Ctrl+Z` undo + coalescing and write to `svg_output/` on **Apply changes**; moves persist through finalize / export (moved text frames, promoted multi-line tspans, repositioned icons all reproduce in the PPTX). Re-export stays chat-driven; on-canvas resize handles are not yet implemented (resize via the geometry inputs)@@ -51,7 +51,7 @@ Structural capability growth since March 2026. Single flags and incremental poli- **Prompt constraint-strength decoupling** ([`docs/rules/prompt-style.md`](rules/prompt-style.md) §4) — three explicit strength tiers — rule (`Hard rule` / `Forbidden`) / default (`Default — … may override`) / reference (`Reference — not a constraint`) — plus an "objective failure vs taste" test and a checker boundary, so the model can tell "must keep vs may deviate" at a glance; the visual-style catalog is Reference-strength throughout- **visual-style catalog grows to 18, aligned with image-renderings + examples reclaimed** — first four distilled from the [examples library](../examples/) (`brutalist` / `blueprint` / `memphis` / `zine`), then six filling in the hand-drawn / textured renderings that have a layout twin (`sketch-notes` / `ink-notes` / `chalkboard` / `paper-cut` / `vintage-poster` / `pixel-art`), then four more reclaimed from still-uncovered example aesthetics: `ink-wash` (rice-paper whitespace, from Cangzhuo / Li Ziqi) · `glassmorphism` (dark frosted-glass + gradient light, from glassmorphism_demo, split out of soft-rounded) · `photo-editorial` (full-bleed photography dominates, text captions, from Pritzker / fashion_weekly) · `data-journalism` (Bloomberg/Economist multi-column micro-charts + sidebars, from global_ai_capital). The catalog is regrouped into five families (corporate-product / editorial-publication / expressive-print / hand-drawn-brush / specialty). **The test**: a rendering earns a visual-style twin only when it defines a whole-page layout language, not merely how an inserted image looks — so photo-*led composition* gets `photo-editorial` (paired with corporate-photo), while purely atmospheric renderings (nature / warm-scene / fantasy-animation) stay imagery-only and just pair with a layout style. Zero HEX, Reference strength throughout- **mode catalog grows to 5: add `briefing`** — fills the "neutral information delivery" cell: no thesis, no story, no teaching, no spectacle — topic titles, even weight, complete and scannable, for status updates / reference decks / catalogs / meeting packs / FAQs that inform without arguing. The five now partition presentation *intent* more nearly MECE: persuade (pyramid) · tell a story (narrative) · teach (instructional) · impress (showcase) · simply inform (briefing). `_index` gains a `briefing` vs `pyramid` tie-breaker ("if you'd have to invent a thesis to fit pyramid, it's briefing"). Five presets plus a `custom` escape hatch for a bespoke direction none of them captures (a special cadence, a multi-mode fusion, a particular posture) — either user-requested or Strategist-recommended, confirmed like every lock; a deck always locks one value, and a fusion is one `custom` describing the acts. The only thing to avoid is defaulting to `custom` when a preset genuinely fits. Mirrors the truth-precedence rule that a user-authored outline or direction overrides the mode-- **mode / visual-style system validated on real decks + four calibration tightenings landed** — the 5 modes + 18 visual-styles + the `custom` escape hatch were exercised on five covering decks (briefing×data-journalism / narrative×photo-editorial / instructional×chalkboard / showcase×glassmorphism / custom×zine, with the narrative deck going through the AI-image branch): **zero selection misses** (all four Close-calls tie-breakers fired and held against the real grey-zone pulls), **discipline fully honored** (zero HEX / Reference strength / whole-page layout language), **the `custom` mechanism works** (a `mode_behavior` prose paragraph carried a 10-page generation and reads as plain language at confirmation, not a bare token), **mode ⟂ visual_style holds** (any combination without bleed, including a positive check of the "keynote/launch = mode not style" route), export 5/5 decks × every page with 0 failures. Tightened four spots from the real signal: `strategist §e` now locks the full neutral tier set the visual_style implies up front (killing the mid-deck color top-ups seen in three consecutive decks), `executor-base §1` re-skins chart/layout template gradients-shadows-fills to the deck's visual_style (templates supply structure, not skin; mirror templates retain their declared prototype paint per §1.1), `briefing §1` makes `core_message` state coverage rather than a claim (briefing-only; global §IX assertion semantics stay for narrative/instructional/pyramid), and `svg_quality_checker` fixes font-family drift false positives (delimiter-matched capture + stack normalization) and drops the font-size ceiling for showcase mode and poster visual-styles+- **mode / visual-style system validated on real decks + four calibration tightenings landed** — the 5 modes + 18 visual-styles + the `custom` escape hatch were exercised on five covering decks (briefing×data-journalism / narrative×photo-editorial / instructional×chalkboard / showcase×glassmorphism / custom×zine, with the narrative deck going through the AI-image branch): **zero selection misses** (all four Close-calls tie-breakers fired and held against the real grey-zone pulls), **discipline fully honored** (zero HEX / Reference strength / whole-page layout language), **the `custom` mechanism works** (a `mode_behavior` prose paragraph carried a 10-page generation and reads as plain language at confirmation, not a bare token), **mode ⟂ visual_style holds** (any combination without bleed, including a positive check of the "keynote/launch = mode not style" route), export 5/5 decks × every page with 0 failures. Tightened four spots from the real signal: `strategist §e` now locks the full neutral tier set the visual_style implies up front (killing the mid-deck color top-ups seen in three consecutive decks), [`executor-structured.md`](../skills/ppt-master/references/executor-structured.md) §1 re-skins chart/layout template gradients-shadows-fills to the deck's visual_style (templates supply structure, not skin; mirror templates retain their declared prototype paint per §1.1), `briefing §1` makes `core_message` state coverage rather than a claim (briefing-only; global §IX assertion semantics stay for narrative/instructional/pyramid), and `svg_quality_checker` fixes font-family drift false positives (delimiter-matched capture + stack normalization) and drops the font-size ceiling for showcase mode and poster visual-styles- **Optional spec-review checkpoint shipped** ([`workflows/stages/refine-spec.md`](../skills/ppt-master/workflows/stages/refine-spec.md)) — an opt-in pause after the Strategist confirmation stage: when the user explicitly asks (default OFF), the Strategist produces the full `design_spec.md` + `spec_lock.md`, then stops so the user can revise any part of the spec (outline / color / typography / layout / image strategy / page rhythm) before generation, keeping both files in sync. Same shape as the split-mode note — it never fires on its own, the default pipeline is unchanged, and it surfaces as one opt-in line inside the Strategist confirmation stage. Review lenses (logical clarity / information density / focus / register / emotional resonance / chapter balance + the design dimensions) give a direction only, never a numeric threshold (`Reference` strength). Prompted by [@cuberoocp](https://github.com/cuberoocp) in [issue #173](https://github.com/hugohe3/ppt-master/issues/173)- **Interactive visual Strategist confirmation stage page (Step 4)** ([`scripts/confirm_ui/server.py`](../skills/ppt-master/scripts/confirm_ui/server.py), field schema [`scripts/docs/confirm_ui.md`](../skills/ppt-master/scripts/docs/confirm_ui.md)) — the Strategist confirmation stage moves from chat-only to a browser page that auto-launches by default at Step 4. Template adherence appears only for deck/layout templates and defaults to `adaptive`: every page still maps to the template architecture, while unmatched compositions may create a new explicit Layout under the same Master. `strict` keeps the selected Layout contracts unchanged. The page shares port `5050` with Live Preview and writes authoritative choices to `result.json`.- **A batch of source-conversion fidelity gains** — less information dropped as source material enters the pipeline: `doc_to_md` converts Word OMML / Office Math equations to inline LaTeX, `pdf_to_md` recognizes `Figure N |` pipe-delimited captions, and `ppt_to_md` preserves hyperlinks already in the source deck (run-level external `[text](url)` / slide-internal jumps `[text](#slide-N)` / shape-level clicks, with dangerous-scheme filtering and anchor-text Markdown escaping) and transcribes native chart data into Markdown tables (values survive the conversion instead of collapsing to a single picture). Caption recognition is based on [@suay1113](https://github.com/suay1113)'s [PR #191](https://github.com/hugohe3/ppt-master/pull/191); hyperlink preservation is distilled from [@ZhaoZuohong](https://github.com/ZhaoZuohong)'s [PR #155](https://github.com/hugohe3/ppt-master/pull/155)diff --git a/docs/rules/prompt-style.md b/docs/rules/prompt-style.mdindex 9518dec3..5cd18887 100644--- a/docs/rules/prompt-style.md+++ b/docs/rules/prompt-style.md@@ -202,6 +202,6 @@ The canonical exemplars to model new files after:| If you're writing... | Model after ||---|---|| A role reference (Image_X / Strategist-style) | [`image-searcher.md`](../../skills/ppt-master/references/image-searcher.md), [`strategist.md`](../../skills/ppt-master/references/strategist.md) |-| A shared spec across roles | [`image-base.md`](../../skills/ppt-master/references/image-base.md), [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) |+| A shared spec across roles | [`image-base.md`](../../skills/ppt-master/references/image-base.md), [`shared-standards-core.md`](../../skills/ppt-master/references/shared-standards-core.md) || A technical / format spec | [`canvas-formats.md`](../../skills/ppt-master/references/canvas-formats.md), [`svg-image-embedding.md`](../../skills/ppt-master/references/svg-image-embedding.md), [`image-layout-spec.md`](../../skills/ppt-master/references/image-layout-spec.md) || Stage runbook | [`workflows/stages/verify-charts.md`](../../skills/ppt-master/workflows/stages/verify-charts.md) |diff --git a/docs/technical-design.md b/docs/technical-design.mdindex 89b23be9..dc71d644 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -93,7 +93,7 @@ Minimal semantic markers do not weaken that closure. Free-design, brand-only, an| Domain | Authority ||---|---|| Visible page content and layout on SVG-authoring routes | Final page SVG in `svg_output/` |-| Project-canonical SVG syntax, compatible forms, and mapping boundary | [`references/shared-standards.md`](../skills/ppt-master/references/shared-standards.md) |+| 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) || Master/Layout/Slide packaging and native-object mapping | SVG-to-PPTX translation; it may reorganize represented content but does not invent visible content || Animations, transitions, speaker notes, and narration | Dedicated sidecars/assets and PPTX package post-processing || Direct native-PPTX editing | The selected native workflow's PPTX/OOXML contract |@@ -205,9 +205,9 @@ SVG wins because it shares the same world view as DrawingML: both are absolute-c| `linearGradient` / `radialGradient` | `<a:gradFill>` || `fill-opacity` / `stroke-opacity` | `<a:alpha>` |-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 [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md) that identifies 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.+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.-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; `shared-standards.md` remains the generated-authoring contract.+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.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.@@ -414,13 +414,13 @@ The catalog of *how an image is placed on a slide* (full vocabulary in [`referen**Why composition flows through Strategist's resource list, not just Executor's improvisation.** The `Layout pattern` column in `§VIII Image Resource List` accepts a `#<id> + #<id> ...` expression — Primary id plus optional Modifier ids — so the composition is declared *before* SVG generation, audited by `svg_quality_checker`, and survives session re-entry. Pushing composition onto Executor alone would lose it on context compression in long decks; encoding it in the spec_lock-adjacent resource list makes it a piece of the design contract.-**Why true hard constraints stay upstream.** Cross-cutting SVG authoring and PPTX-compatibility exceptions live exclusively in [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md). The layout patterns file points there rather than restating the contract — so when a constraint changes, only one file changes, and a stale duplicate in patterns cannot silently keep enforcing the old rule.+**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.---## Project-Canonical SVG and the Compatibility Boundary-PowerPoint's DrawingML is a strict subset of what SVG can express, so the main compiler route does not treat “the browser can render it” as “the project can export it.” Input is accepted only when [`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. That file is the sole authority for syntax, structure, units, metadata, compatible aliases, fidelity, and rejection conditions; this architecture document defines the layering principle without duplicating individual rules.+PowerPoint's DrawingML is a strict subset of what SVG can express, 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.**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.diff --git a/docs/templates-architecture.md b/docs/templates-architecture.mdindex 3d32d1b0..5b7f629d 100644--- a/docs/templates-architecture.md+++ b/docs/templates-architecture.md@@ -400,7 +400,7 @@ Bitmaps share the workspace `images/` pool and template SVGs reference them thro### Strategist confirmation stage behavior per kind-Installing a template does not narrow away the communication question. Stage 1 always confirms the same open communication contract independently of the template. Brand supplies identity constraints while structure stays free; Layout exposes structural capability; Deck also contributes an application contract. Stage 2 derivation compares that stored application with the confirmed current contract rather than silently treating it as truth, then decides whether a compatible Deck/Layout should be consumed as `mirror`, `layout`, or `style` where legal. A mirror-authored workspace therefore enables literal reuse but never selects it automatically. Stage 3 realizes the confirmed direction with the identity, structure, and application rules actually retained by that scope. The detailed rules live in `references/strategist.md` and `spec_lock_reference.md`.+Installing a template does not narrow away the communication question. Stage 1 always confirms the same open communication contract independently of the template. Brand supplies identity constraints while structure stays free; Layout exposes structural capability; Deck also contributes an application contract. Stage 2 derivation compares that stored application with the confirmed current contract rather than silently treating it as truth, then decides whether a compatible Deck/Layout should be consumed as `mirror`, `layout`, or `style` where legal. A mirror-authored workspace therefore enables literal reuse but never selects it automatically. Stage 3 realizes the confirmed direction with the identity, structure, and application rules actually retained by that scope. Planning semantics live in `references/strategist.md` and `references/strategist-template.md`; `templates/schemas/spec_lock.schema.json` owns the machine structure.---diff --git a/docs/zh/powerpoint-svg-mapping.md b/docs/zh/powerpoint-svg-mapping.mdindex e216da64..fb2e1f2d 100644--- a/docs/zh/powerpoint-svg-mapping.md+++ b/docs/zh/powerpoint-svg-mapping.md@@ -8,7 +8,7 @@本指南从 PowerPoint 使用者的视角回答一个问题:**对于某项 PowerPoint 功能,项目中由什么表达承载,导出或回导时能保留什么?** 因此,PowerPoint 语义是唯一主索引,SVG 元素只作为某项 PowerPoint 能力的具体实现出现。-这是一份公开的能力与导入行为映射表,不是第二份生成 SVG 语法规范,也不承诺转换任意 SVG 或任意 OOXML。规范生成合同仍属于 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md);生成语法出现差异时,以该合同为准。PPTX 导入的容错模式与用户可见降级由本文 §11 和[转换命令文档](../../skills/ppt-master/scripts/docs/conversion.md)负责,精确 parser 行为仍以实现代码为真值。本指南未列出的功能不会因此被默认为受支持。+这是一份公开的能力与导入行为映射表,不是第二份生成 SVG 语法规范,也不承诺转换任意 SVG 或任意 OOXML。规范生成合同由 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 路由到拆分权威集;生成语法出现差异时,以适用模块为准。PPTX 导入的容错模式与用户可见降级由本文 §11 和[转换命令文档](../../skills/ppt-master/scripts/docs/conversion.md)负责,精确 parser 行为仍以实现代码为真值。本指南未列出的功能不会因此被默认为受支持。主路线编译的是**项目规范化 SVG**,而不是通用浏览器 SVG:@@ -48,7 +48,7 @@ PowerPoint 意图| 主题颜色与字体 | `spec_lock.md` 锁定的角色;规范 SVG 使用解析后的值 | 当精确匹配锁定角色时保留 theme token,否则写直接 DrawingML 值 | 已登记角色为 `Native-stable` | 新页面不得自行发明未锁定颜色、字体或字号 || PowerPoint 包身份 | `spec_lock.md` 结构声明与打包器 | Presentation、Master、Layout、relationship 与 content type 注册 | 从包结构读回,不从页面外观推断 | 最终包读回必须与声明的 roster 一致 |-受支持的画布见 [`canvas-formats.md`](../../skills/ppt-master/references/canvas-formats.md),根 `viewBox` 的规范合同见 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) §4.1。+受支持的画布见 [`canvas-formats.md`](../../skills/ppt-master/references/canvas-formats.md),根 `viewBox` 的规范合同见 [`shared-standards-core.md` §4.1](../../skills/ppt-master/references/shared-standards-core.md#41-semantic-svg-marker-contract)。## 2. Master、Layout、背景与占位符功能@@ -80,9 +80,9 @@ PowerPoint 意图| cover/content/ending 等页面角色 | flat 路线根 `data-pptx-page-role` 编译提示 | 路由/校验提示;不是 PowerPoint 原生页面类型 | 没有独立 OOXML 对象 | structured 页面改用显式 Master/Layout 身份 || 幻灯片节与自定义放映 | 无 SVG 映射 | 主生成路线不编写 | 当源保留工作流拥有该语义时为 `Direct preservation` | 不得编码为可见 metadata |-精确的结构 metadata 与 slot 语法见规范中的 [PPTX 结构章节](../../skills/ppt-master/references/shared-standards.md#pptx-structure-routing)。+精确的结构 metadata 与 slot 语法见 [PPTX 结构接口](../../skills/ppt-master/references/pptx-structure-interface.md#1-pptx-structure-routing)。-内部标识符与 PowerPoint 显示名称是两件事:Master 和 Layout key 使用项目受限 ASCII 标识符语法,picker 名称可以含空格。每个 Layout 定义还必须指定父 Master 与一个显式原型来源。精确行语法由规范文档拥有。+内部标识符与 PowerPoint 显示名称是两件事:Master 和 Layout key 使用项目受限 ASCII 标识符语法,picker 名称可以含空格。每个 Layout 定义还必须指定父 Master 与一个显式原型来源。精确行语法由 PPTX 结构接口拥有。## 3. PowerPoint 形状与绘图对象@@ -105,7 +105,7 @@ PowerPoint 意图| 图标 / 导入向量 | 由项目图标管线解析的 `<use data-icon="library/name">`;create-template 导入统一使用 `imported/<name>` | 展开后的可编辑矢量原语/组 | 重建几何,不恢复原图标库引用 | 标识区分大小写;导入素材仅在工作区根目录 `icons/imported/<name>.svg` 保留一份 || SmartArt / DiagramML | 无主 SVG 对象映射 | 主重设计路线可以用普通 shape 重建语义 | 原生/模板路线中为 `Direct preservation`,否则为 preview 或显式 fallback | 不得将装饰性组标记为原生 SmartArt |-项目创作 preset 有意采用 compact 表达,而 PPTX 导入继续保留无损往返裁决所需的 expanded 证据。精确机器合同仍属于 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md),preset 选择与创作行为见 [`native-shape-authoring.md`](../../skills/ppt-master/references/native-shape-authoring.md)。+项目创作 preset 有意采用 compact 表达,而 PPTX 导入继续保留无损往返裁决所需的 expanded 证据。精确机器合同仍属于 [`shared-standards-core.md`](../../skills/ppt-master/references/shared-standards-core.md),preset 选择与创作行为见 [`native-shape-authoring.md`](../../skills/ppt-master/references/native-shape-authoring.md)。## 4. PowerPoint 文本功能@@ -117,13 +117,13 @@ PowerPoint 意图| 有意义的文本空白 | `<text>`/`<tspan>` 上精确的 `xml:space="default"` 或 `xml:space="preserve"` | 可编辑 DrawingML run 中归一化或保留的 U+0020 文本 | `Native-normalized`;保留行内 run 所有权 | 使用项目 Chromium/SVG2 合同:LF/TAB 转为空格,`default` 跨 run 折叠,`preserve` 全部保留,Unicode 间隔字符保持字面值;CSS `white-space` 与 SVG 1.1 遗留换行删除不在映射内 || 字体 | 根据项目 lock 解析的规范 `font-family` | 直接 typeface 或已登记 theme font | 在安装字体/替换边界内为 `Native-stable` | 校验会报告未锁定或不可用字体 || 字号 | 有限、无单位的 SVG px,例如 `font-size="24"` | DrawingML 百分之一磅;`1 px = 0.75 pt` | 单位转换后为 `Native-stable` | 生成创作只使用无单位 px;已登记历史单位是会产生 warning 的兼容输入,未知单位为 error;DrawingML 下限为 1 pt |-| 字重 | `<text>`/`<tspan>` 上已登记的 `font-weight` | DrawingML 常规/粗体 run 开关 | `Native-normalized`;数值字重会折叠到 DrawingML 布尔边界 | 精确取值语法与别名属于 [`shared-standards.md` §6.7](../../skills/ppt-master/references/shared-standards.md#67-advanced-text-treatments) |-| 斜体、下划线与删除线 | `<text>`/`<tspan>` 上已登记的 `font-style` / `text-decoration` | DrawingML 斜体、下划线与删除线 run 属性 | 已登记 token 为 `Native-stable` | 拒绝未知 token;精确语法属于 [`shared-standards.md` §6.7](../../skills/ppt-master/references/shared-standards.md#67-advanced-text-treatments) |+| 字重 | `<text>`/`<tspan>` 上已登记的 `font-weight` | DrawingML 常规/粗体 run 开关 | `Native-normalized`;数值字重会折叠到 DrawingML 布尔边界 | 精确取值语法与别名属于 [`svg-effects.md` §6.7](../../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) |+| 斜体、下划线与删除线 | `<text>`/`<tspan>` 上已登记的 `font-style` / `text-decoration` | DrawingML 斜体、下划线与删除线 run 属性 | 已登记 token 为 `Native-stable` | 拒绝未知 token;精确语法属于 [`svg-effects.md` §6.7](../../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || 文本填充与透明度 | 规范 fill 加 run alpha | DrawingML run fill 与 alpha | `Native-normalized` | 使用语义 alpha 通道,不使用未登记 CSS 效果 || 文本轮廓 | 文本上已登记 stroke | DrawingML run outline | `Native-normalized` | 轮廓承载精细视觉意义时需复核 |-| 文本对齐 | 已登记的 `text-anchor` 与段落语义 | 段落对齐加归一化文本框位置 | `Native-normalized` | 不支持 run 级锚定与浏览器 baseline 启发式;精确放置属于 [`shared-standards.md` §6.7](../../skills/ppt-master/references/shared-standards.md#67-advanced-text-treatments) |+| 文本对齐 | 已登记的 `text-anchor` 与段落语义 | 段落对齐加归一化文本框位置 | `Native-normalized` | 不支持 run 级锚定与浏览器 baseline 启发式;精确放置属于 [`svg-effects.md` §6.7](../../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || 文本框垂直对齐 | 无规范生成 SVG 控制;生成文本框使用顶部对齐 | 顶部对齐的 DrawingML text body | 导入的垂直文本可能被归一化,但主路线不公开通用创作控制 | 不得从 SVG baseline 或浏览器排版行为推断垂直对齐 |-| 字符间距 | 已登记 `letter-spacing` | DrawingML 字符间距 | `Native-normalized` | 按 [`shared-standards.md` §6.7](../../skills/ppt-master/references/shared-standards.md#67-advanced-text-treatments) 拒绝不受支持的 CSS 排版、超出 DrawingML 范围的间距,以及导致生成 run advance 或文本框 extent 非正的负字距 |+| 字符间距 | 已登记 `letter-spacing` | DrawingML 字符间距 | `Native-normalized` | 按 [`svg-effects.md` §6.7](../../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) 拒绝不受支持的 CSS 排版、超出 DrawingML 范围的间距,以及导致生成 run advance 或文本框 extent 非正的负字距 || 项目符号段落 | 已识别的前导项目符号形式 | 原生 DrawingML bullet | `Native-normalized` | 仅提升已登记 bullet 语法 || 旋转文本 | 文本对象上受支持的 transform | 旋转文本 shape | `Native-normalized` | 倾斜文本与浏览器专属 transform 不受支持 || 文本阴影或发光 | 受支持 filter/effect 合同 | 一个原生外阴影或发光 | `Approximate` | 仅支持一个已登记效果图;实质效果需复核 |@@ -190,12 +190,12 @@ PowerPoint 原生 Chart/Table 对象是可选功能。默认导出保留 SVG fal| 视觉绘制图表 | 普通 SVG 几何与文本 | 相互独立的可编辑 PowerPoint shape | 保真度遵循各组件对应行 | 没有“编辑数据”工作簿 || PowerPoint 原生经典图表 | 一个带 `<metadata type="application/json">` 已登记 JSON 数据和可见 fallback 的 `<g data-pptx-replace-with="chart">` | `p:graphicFrame`、经典 chart part 与嵌入工作簿 | 受支持的导入重建 fallback 加替换 metadata | chart type 与数据必须匹配封闭 schema;需要 `--native-charts-and-tables` || 原生 ChartEx 图表 | 具有受支持 ChartEx family 的相同 marker 接口 | `cx:chart` part 与嵌入工作簿 | 受支持 family 可按语义重建 | 仅接受已登记 family/field 组合 |-| 图表标题、图例、坐标轴、标签与系列格式 | 已登记原生图表 metadata | 原生 chart 属性 | `Native-normalized` | 精确字段与受支持 family 仍以 `shared-standards.md` 为规范 |+| 图表标题、图例、坐标轴、标签与系列格式 | 已登记原生图表 metadata | 原生 chart 属性 | `Native-normalized` | 精确字段与受支持 family 仍以 `native-data-interface.md` 为规范 || 图表说明、来源或脚注 | replacement marker 之外的普通伴随 SVG text | 图表旁边可编辑的 Slide 文本框 | 作为文本时为 `Native-stable` | 不得把 Slide 文案隐藏在 chart JSON 里 || 已编辑 SVG fallback 与过期替换 metadata | 更新后的可见 SVG 加过期 hash | 默认导出保留可见 SVG;原生替换失败 | 显式安全行为 | 编译器绝不默默丢弃更新的视觉编辑 || 不支持的 3D 或延后图表 family | SVG 绘制图表、烘焙资产或直接源保留 | 不猜测原生图表 | fallback / `Direct preservation` | 不支持的 alias 必须使原生校验失败 |-完整图表/表格 schema 和受支持 family 列表有意仅保留在[规范化替换合同](../../skills/ppt-master/references/shared-standards.md#powerpoint-native-chart--table-replacement-markers-opt-in)中。+完整图表/表格 schema 和受支持 family 列表有意仅保留在[原生数据接口替换合同](../../skills/ppt-master/references/native-data-interface.md#2-powerpoint-native-chart--table-replacement-markers-opt-in)中。## 9. PowerPoint 播放与打包功能@@ -276,7 +276,7 @@ sidecar 工作流见[转场与动画](./animations.md)(技术规范源为 [`re应将映射变更视为编译器变更,而不是宽松 SVG parser 调整:1. 命名 PowerPoint 能力与预期的可编辑 DrawingML 结果。-2. 在 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 中定义一种规范项目 SVG 或 sidecar 表达。+2. 在 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 路由到的适用权威模块中定义一种规范项目 SVG 或 sidecar 表达。3. 将可接受兼容输入与生成创作分开声明。4. 实现导出;仅当支持语义重建时实现导入。5. 增加 Checker 分类:非法/歧义输入为 error,只有结果确定的兼容或近似输入可为 warning。@@ -288,4 +288,4 @@ sidecar 工作流见[转场与动画](./animations.md)(技术规范源为 [`re- 导出:[`svg_to_pptx.py`](../../skills/ppt-master/scripts/svg_to_pptx.py) 与 `scripts/svg_to_pptx/`- 导入:[`pptx_to_svg.py`](../../skills/ppt-master/scripts/pptx_to_svg.py) 与 `scripts/pptx_to_svg/`- 校验:[`svg_quality_checker.py`](../../skills/ppt-master/scripts/svg_quality_checker.py)-- 规范合同:[`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md)+- 权威路由:[`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md)diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.mdindex 55fc2086..e5823f4e 100644--- a/docs/zh/roadmap.md+++ b/docs/zh/roadmap.md@@ -31,16 +31,16 @@- **Live Preview 进入主流程**([`workflows/stages/live-preview.md`](../../skills/ppt-master/workflows/stages/live-preview.md)) — 浏览器实时预览 + 点选元素写要求 + 「apply my annotations」让 AI 重做该区域(基于 [@WodenJay](https://github.com/WodenJay) [PR #85](https://github.com/hugohe3/ppt-master/pull/85))- **从原生 PPTX 创建新模板工作区**([`workflows/create-template.md`](../../skills/ppt-master/workflows/create-template.md)) — 读取 OOXML 中实际存在且受支持的主题 / 母版 / 版式 / 资源事实,物化为新的模板合同;不修改来源 PPTX-- **AI 图三维系统** rendering × palette × type + Strategist h.5 锁定,下游消费固定契约+- **AI 图三维系统** rendering × palette × type + [`strategist-image.md`](../../skills/ppt-master/references/strategist-image.md) §2 锁定,下游消费固定契约- **AI 图 `hero_page` 双档** — 局部插图 + 整页主角图共存- **品牌身份预设子系统**([`workflows/create-template/create-brand.md`](../../skills/ppt-master/workflows/create-template/create-brand.md)) — 固定 Create Template 入口下的 Create Brand 子工作流,提取并复用品牌色板 / 字体 / Logo / 语调- **视觉自检阶段**([`workflows/stages/visual-review.md`](../../skills/ppt-master/workflows/stages/visual-review.md)) — 按 rubric 逐页自查 AI 生成的 SVG- **AI 图 Type 概念边界澄清** — Type 收窄回「local 信息图的内部几何骨架」(11 个真骨架);原 4 个伪 type (hero/background/portrait/typography) 折回 `page_role: hero_page` + 4 条构图通则(single-subject / portrait / typographic / atmospheric);hero_page 文字分层规则(关键视觉词 embedded、可改文字走 SVG)- **Brutalist AI 报章示例 deck 交付**([`examples/ppt169_brutalist_ai_newspaper_2026/`](../../examples/ppt169_brutalist_ai_newspaper_2026/)) — P0 三档第一档落地:满版小字 + 不规则栏宽 + halftone 黑白图 + 单点红 + 真原生 shape,10 页编辑部年报实压「文字位置精度 + 跨页一致性」- **Kubernetes Blueprint 示例 deck 交付**([`examples/ppt169_kubernetes_blueprint_2026/`](../../examples/ppt169_kubernetes_blueprint_2026/)) — P0 三档第二档落地:等距工程图美学 + 蓝图青/琥珀色板 + 全手写 SVG 几何(无 raster 图)+ 自定义"逐笔绘制"动画,10 页 Kubernetes 架构走读实压「几何形状泛化 + chart 结构扩展性」-- **AI 图 `custom` 兜底出口** — `rendering` / `palette` / hero 构图三处允许声明 `custom` + 一段 `*_behavior` prose,替换原"找不到匹配就硬塞 vector-illustration / cool-corporate"的假兜底;端到端契约:[`image-renderings/_index.md`](../../skills/ppt-master/references/image-renderings/_index.md) §1.5 + [`image-palettes/_index.md`](../../skills/ppt-master/references/image-palettes/_index.md) §2 + Strategist h.5 hard-rule(每维 ≤1 custom,单候选可双 custom)+ spec_lock 字段 + Image_Generator Step 2 消费分支+- **AI 图 `custom` 兜底出口** — `rendering` / `palette` / hero 构图三处允许声明 `custom` + 一段 `*_behavior` prose,替换原"找不到匹配就硬塞 vector-illustration / cool-corporate"的假兜底;端到端契约:[`image-renderings/_index.md`](../../skills/ppt-master/references/image-renderings/_index.md) §1.5 + [`image-palettes/_index.md`](../../skills/ppt-master/references/image-palettes/_index.md) §2 + [`strategist-image.md`](../../skills/ppt-master/references/strategist-image.md) §2 hard-rule(每维 ≤1 custom,单候选可双 custom)+ spec_lock 字段 + Image_Generator Step 2 消费分支- **Template 架构三分类收口**([`docs/zh/templates-architecture.md`](./templates-architecture.md)) — brand / layout / deck 三独立目录 + 每类独立 schema + 段级合成 + git-style 冲突解决;[Generate PPTX Step 3](../../skills/ppt-master/workflows/generate-pptx.md#step-3-template-option) 按 kind 分支处理,触发规则仍是「显式路径才触发」-- **Pattern 填充 PPTX 安全网** — 被引用的 `<pattern>` 缺少 `data-pptx-pattern` 时,`svg_quality_checker.py` 现在给出 warning,转换器继续使用兼容的 `ltUpDiag` 回退;`patternTransform` 或超出 OOXML `ST_PresetPatternVal` 枚举的值仍然报错。`shared-standards.md §7` 落地了完整 preset 清单,以及从导入元数据或子元素 paint 解析颜色的合同+- **Pattern 填充 PPTX 安全网** — 被引用的 `<pattern>` 缺少 `data-pptx-pattern` 时,`svg_quality_checker.py` 现在给出 warning,转换器继续使用兼容的 `ltUpDiag` 回退;`patternTransform` 或超出 OOXML `ST_PresetPatternVal` 枚举的值仍然报错。[`native-data-interface.md` §1](../../skills/ppt-master/references/native-data-interface.md#1-pattern-fill--pattern-with-pptx-preset-annotation) 落地了完整 preset 清单,以及从导入元数据或子元素 paint 解析颜色的合同- **LaTeX 数学公式渲染上线**([`scripts/latex_render.py`](../../skills/ppt-master/scripts/latex_render.py)) — Strategist 在 Typography 确认中锁定 `mixed` / `render-all` / `text-only` 三档策略,显式写 `images/formula_manifest.json`;脚本走 codecogs → quicklatex → mathpad → wikimedia 四源 fallback chain,输出透明 PNG 进 §VIII 表的 `Acquire Via: formula` / `Status: Rendered` 行;公式密集型 deck(学术 / 工程 / 教学)首次拥有原生渲染路径,规则面禁止扫源文件 `$...$` 自动渲染(公式选取是 Strategist 决策)- **实时预览直接编辑 — L1 / L2 / L3**([`workflows/stages/live-preview.md`](../../skills/ppt-master/workflows/stages/live-preview.md)) — 浏览器编辑器新增无需 AI 往返的确定性就地编辑:文字内容(L1)、fill / stroke / font-size 等样式属性(L2)、以及画布上的几何操作(L3)——在选中元素上拖拽即移动、方向键微调(`Shift` = 10px)、多选、加右键重叠选择器选取堆叠元素。编辑支持 `Ctrl+Z` 撤销 + 合并,点 **Apply changes** 写回 `svg_output/`;移动经 finalize / 导出保位(移动的 text、提升的多行 tspan、重定位的 icon 都在 PPTX 中如实再现)。重新导出仍由对话触发;画布上的缩放手柄尚未实现(缩放走几何输入框)@@ -51,7 +51,7 @@- **提示词约束强度三档解耦**([`docs/rules/prompt-style.md`](../rules/prompt-style.md) §4) — 规则(`Hard rule` / `Forbidden`)/ 默认(`Default — … may override`)/ 参考(`Reference — not a constraint`)三档显式化 + 「客观失败 vs 品味」判据 + checker 边界,让模型对「该守 vs 可破」一目了然;visual-style catalog 全程用 Reference 强度- **visual-style catalog 扩充至 18 个,与 image-renderings 对齐 + 示例库回收** — 先从[示例库](../../examples/)提炼 4 个(`brutalist` / `blueprint` / `memphis` / `zine`),再补齐 [`image-renderings`](../../skills/ppt-master/references/image-renderings/) 里有排版对应物的手绘 / 纹理风格 6 个(`sketch-notes` / `ink-notes` / `chalkboard` / `paper-cut` / `vintage-poster` / `pixel-art`),再回收示例库里仍未覆盖的独立气质:`ink-wash`(新中式水墨留白,源 藏拙 / 李子柒)· `glassmorphism`(深底磨砂玻璃 + 流光,源 glassmorphism_demo,从 soft-rounded 独立)· `photo-editorial`(满版摄影主导、文字点题,源 Pritzker / fashion_weekly)· `data-journalism`(Bloomberg/Economist 新闻信息图,多栏微图表 + 数据侧栏,源 global_ai_capital)。catalog 重组为 5 组(企业产品 / 编辑出版 / 表现印刷 / 手绘笔触 / 特殊)。**关键判据**:一个 rendering 升 visual-style 的前提是它定义「整页版面语言」而非「插入图的样子」——故 corporate-photo「摄影主导版面」该建(photo-editorial),而 nature / warm-scene / fantasy-animation 等纯氛围 rendering 仍只配对、不单建。全程零 HEX、Reference 强度- **mode catalog 扩档至 5 个:加 `briefing`** — 补上「中性信息平铺」这一格:无论点 / 无故事 / 不教学 / 不冲击,topic 标题、等权铺事实、完整可扫读,服务周报 / 参考册 / 目录 / 会议材料 / FAQ 这类「只告知不论证」的 deck。五个 mode 自此更接近 MECE 地切分**表达意图**:说服(pyramid)· 讲故事(narrative)· 教会(instructional)· 震住(showcase)· 只告知(briefing)。`_index` 加了 `briefing` vs `pyramid` 的灰区判据(「要不要造个 thesis 才塞得进 pyramid → 那就是 briefing」)。五个预设之外加一个 `custom` 兜底,承接预设盖不住的 bespoke 方向(特殊节奏 / 多 mode 融合 / 特定姿态)——用户点名**或策略师推荐**皆可,与所有锁一样由用户确认;一份 deck 永远只锁一个值,融合=一个 custom 描述多幕。唯一要避免的是「预设明明贴合却图省事甩 custom」。这与「用户自带大纲 / 方向覆盖 mode」是同一条真值优先原则-- **mode / visual-style 体系真实 deck 验证完成 + 四项校准收紧落地** — 5 mode + 18 visual-style + `custom` 逃生舱在 5 份覆盖性 deck 上跑过验证(briefing×data-journalism / narrative×photo-editorial / instructional×chalkboard / showcase×glassmorphism / custom×zine,其中 narrative 一份走 AI 图生成分支):**选型零误判**(四对 Close-calls 灰区引力全被触发且全抗住)、**纪律全落实**(零 HEX / Reference 强度 / 整页版面语言)、**custom 机制可用**(`mode_behavior` 散文段落撑过 10 页生成、能讲成大白话让用户确认)、**mode ⟂ visual_style 正交成立**(任意组合无串味,含「keynote/发布会=mode 不是 style」路由正面验证)、导出 5/5 deck × 全页 0 失败。据真实信号收紧四处:`strategist §e` 按 visual_style 预判中性档位一次锁全(消除连续三份的 Executor 中途补色)、`executor-base §1` 套模板页重皮到当前 visual_style(模板供结构不供皮,mirror 模板保持已声明的视觉身份)、`briefing §1` 的 `core_message` = 本页覆盖什么而非证明什么(briefing 专属例外,全局 §IX 论断语义保留给 narrative/instructional/pyramid)、`svg_quality_checker` 修字体 drift 误报(按定界符匹配 + font-stack 归一化)+ 放宽 showcase mode 与 poster 类 visual-style 的字号上限+- **mode / visual-style 体系真实 deck 验证完成 + 四项校准收紧落地** — 5 mode + 18 visual-style + `custom` 逃生舱在 5 份覆盖性 deck 上跑过验证(briefing×data-journalism / narrative×photo-editorial / instructional×chalkboard / showcase×glassmorphism / custom×zine,其中 narrative 一份走 AI 图生成分支):**选型零误判**(四对 Close-calls 灰区引力全被触发且全抗住)、**纪律全落实**(零 HEX / Reference 强度 / 整页版面语言)、**custom 机制可用**(`mode_behavior` 散文段落撑过 10 页生成、能讲成大白话让用户确认)、**mode ⟂ visual_style 正交成立**(任意组合无串味,含「keynote/发布会=mode 不是 style」路由正面验证)、导出 5/5 deck × 全页 0 失败。据真实信号收紧四处:`strategist §e` 按 visual_style 预判中性档位一次锁全(消除连续三份的 Executor 中途补色)、[`executor-structured.md`](../../skills/ppt-master/references/executor-structured.md) §1 套模板页重皮到当前 visual_style(模板供结构不供皮,mirror 模板保持已声明的视觉身份)、`briefing §1` 的 `core_message` = 本页覆盖什么而非证明什么(briefing 专属例外,全局 §IX 论断语义保留给 narrative/instructional/pyramid)、`svg_quality_checker` 修字体 drift 误报(按定界符匹配 + font-stack 归一化)+ 放宽 showcase mode 与 poster 类 visual-style 的字号上限- **可选 spec 复核环节上线**([`workflows/stages/refine-spec.md`](../../skills/ppt-master/workflows/stages/refine-spec.md)) — 策略师确认阶段后新增一个 opt-in 停顿点:用户明确要求时(默认 OFF),Strategist 先产出完整 `design_spec.md` + `spec_lock.md`,停下来让用户对 spec 任意部分(大纲 / 配色 / 排版 / 版式 / 图片策略 / page rhythm)深入讨论修改,改完同步两个文件再进生成。与 split-mode 同构——不主动触发、默认管线零变化,仅在策略师确认阶段里多一行 opt-in 提示。复核视角(逻辑清晰度 / 信息密度 / 焦点 / 口语化 / 感染力 / 章节配比 + 各设计维度)只给方向、不落任何数字阈值(`Reference` 强度)。启发自 [@cuberoocp](https://github.com/cuberoocp) [issue #173](https://github.com/hugohe3/ppt-master/issues/173)- **交互式可视化策略师确认页(Step 4)**([`scripts/confirm_ui/server.py`](../../skills/ppt-master/scripts/confirm_ui/server.py),字段 schema [`scripts/docs/confirm_ui.md`](../../skills/ppt-master/scripts/docs/confirm_ui.md)) — 模板遵循方式只在加载 Deck/Layout 模板时显示,默认推荐 `adaptive`:每页仍映射模板架构,无匹配构图时可在同一 Master 下创建新 Layout;`strict` 保持所选 Layout 契约不变。确认页与 Live Preview 共用端口,最终 `result.json` 对下游权威。- **源文档转换保真度提升一批** — 源材料进管线时更少丢信息:`doc_to_md` 把 Word 里的 OMML / Office Math 公式转成内联 LaTeX、`pdf_to_md` 识别 `Figure N |` 竖线分隔的图注、`ppt_to_md` 保留源 deck 已有的超链接(run 级外链 `[text](url)` / slide 内部跳转 `[text](#slide-N)` / shape 级点击,含危险 scheme 过滤与锚文本 Markdown 转义)并把原生图表数据转写成 Markdown 表格(数值随转换存活,不再只剩一张图)。图注识别基于 [@suay1113](https://github.com/suay1113) [PR #191](https://github.com/hugohe3/ppt-master/pull/191),超链接保留提炼自 [@ZhaoZuohong](https://github.com/ZhaoZuohong) [PR #155](https://github.com/hugohe3/ppt-master/pull/155)diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex 2c065883..db5d0e14 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -92,7 +92,7 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使| 领域 | 权威来源 ||---|---|| SVG 创作路线中的可见页面内容与布局 | `svg_output/` 中的最终页面 SVG |-| 项目规范化 SVG 的语法、兼容形式与映射边界 | [`references/shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) |+| 项目规范化 SVG 的语法、兼容形式与映射边界 | 由 [`references/shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 选择的拆分权威集 || Master/Layout/Slide 打包与原生对象映射 | SVG 到 PPTX 的翻译;可以重组 SVG 已表达的内容,但不能创造新的可见内容 || 动画、转场、讲稿和旁白 | 各自的 sidecar / 资源与 PPTX package 后处理 || 直接原生 PPTX 编辑 | 所选原生工作流自己的 PPTX / OOXML 契约 |@@ -206,9 +206,9 @@ SVG 胜出,因为它与 DrawingML 拥有相同的世界观:两者都是绝| `linearGradient` / `radialGradient` | `<a:gradFill>` || `fill-opacity` / `stroke-opacity` | `<a:alpha>` |-这张表只展示概念对应关系,不是对整个 SVG 标准的承诺,也不承诺所有映射语义无损。每项受支持能力都必须在 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 中拥有明确的映射记录,说明项目规范写法、允许的兼容输入、目标 DrawingML 表达、保真度和拒绝条件;涉及 PPTX 回导的能力还要说明来源 PPTX / OOXML 语义。映射状态可以是精确、确定性归一化、显式 fallback、sidecar 或 unsupported;讲稿、动画、relationships 等 package 语义不必强行塞进 SVG,但必须明确由哪条路线承载。+这张表只展示概念对应关系,不是对整个 SVG 标准的承诺,也不承诺所有映射语义无损。每项受支持能力都必须在 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 路由到的适用模块中拥有明确映射,说明项目规范写法、允许的兼容输入、目标 DrawingML 表达、保真度和拒绝条件;涉及 PPTX 回导的能力还要说明来源 PPTX / OOXML 语义。映射状态可以是精确、确定性归一化、显式 fallback、sidecar 或 unsupported;讲稿、动画、relationships 等 package 语义不必强行塞进 SVG,但必须明确由哪条路线承载。-如需从 PowerPoint 功能出发逐项查看这些关系,请参阅 [PowerPoint 功能 ↔ 项目 SVG 映射指南](./powerpoint-svg-mapping.md)。该文档负责公开能力与 PPTX 导入语义映射;`shared-standards.md` 继续负责生成 SVG 创作合同。+如需从 PowerPoint 功能出发逐项查看这些关系,请参阅 [PowerPoint 功能 ↔ 项目 SVG 映射指南](./powerpoint-svg-mapping.md)。该文档负责公开能力与 PPTX 导入语义映射;由 `shared-standards.md` 路由的权威集负责生成 SVG 创作。主生成路线采用**规范窄写入、受控兼容读取**。新生成的 `svg_output/` 与可复用模板只使用项目规范写法,例如不透明的六位大写 `#RRGGBB`,透明度放在对应的 `fill-opacity`、`stroke-opacity`、`stop-opacity`、`flood-opacity` 或原子元素 `opacity` 中。历史或人工输入只有在兼容合同明确登记、转换结果唯一且输出合法时才可继续导出;Checker 对这类写法给出非阻塞 warning,转换器在编译边界统一归一化。任何需要猜测、没有映射或可能产生损坏 PPTX 的表达都必须报 error。@@ -410,13 +410,13 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:**为什么组合走 Strategist 资源列表,不只交给 Executor 临场发挥。** `§VIII 图片资源列表` 的 `Layout pattern` 列接受 `#<id> + #<id> ...` 表达式——Primary id 加可选 Modifier id——所以组合在 SVG 生成**之前**就被声明、被 `svg_quality_checker` 审计、并能在 session 重入后存活。把组合责任只压在 Executor 身上,长 deck 上下文压缩时就会丢;把它编码进 spec_lock 旁的资源列表,组合就成为设计契约的一部分。-**为什么真正的硬约束留在上游。** 跨切的 SVG 创作与 PPTX 兼容性例外独家住在 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md)。版式词表只指向这份合同,不再复述——这样规则变化时只有一个文件要改,词表里也不会留下一份过期副本继续暗中强制旧规则。+**为什么真正的硬约束留在上游。** 跨切的 SVG 创作与 PPTX 兼容性例外属于 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 路由的权威集。版式词表只指向该路由,不再复述合同;每条规则仍只有一个所属模块,词表里也不会留下过期副本。---## 项目规范化 SVG 与兼容性边界-PowerPoint 的 DrawingML 是 SVG 表达力的严格子集,因此主编译路径不把“浏览器可以渲染”视为“项目可以导出”。只有在 [`references/shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 中登记了项目规范表达或显式兼容形式,并且拥有确定 DrawingML 映射的词汇,才属于可接受输入。该文件是语法、结构、单位、metadata、兼容别名、保真度和拒绝条件的唯一权威;本架构文档只定义分层原则,不复制具体规则。+PowerPoint 的 DrawingML 是 SVG 表达力的严格子集,因此主编译路径不把“浏览器可以渲染”视为“项目可以导出”。只有在 [`references/shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 路由到的适用模块中登记了项目规范表达或显式兼容形式,并且拥有确定 DrawingML 映射的词汇,才属于可接受输入。该拆分权威集负责语法、结构、单位、metadata、兼容别名、保真度和拒绝条件;本架构文档只定义分层原则,不复制具体规则。**为什么本地复用是编译期复用,不是 PowerPoint 保留对象。** 接受的创作形式由权威合同定义、共享校验器执行。校验通过后,流水线会递归实体化引用子树并重写克隆局部 ID 后再导出;PPTX 回导因此只返回展开后的原语,不重建创作期复用图。diff --git a/docs/zh/templates-architecture.md b/docs/zh/templates-architecture.mdindex 2717d39b..01b2ca62 100644--- a/docs/zh/templates-architecture.md+++ b/docs/zh/templates-architecture.md@@ -355,7 +355,7 @@ AI: 你给了两个 brand,检测到段级冲突:### 策略师确认阶段在不同 kind 下的行为-安装模板不会让沟通问题消失。Stage 1 始终独立确认同一份开放式沟通契约。Brand 提供身份约束、结构仍然自由;Layout 提供结构能力;Deck 还提供应用契约。Stage 2 推导时才把已保存的应用契约与当前确认结果对照,不能静默当成真值,再根据场景在合法范围内选择 `mirror`、`layout` 或 `style`。因此,按 mirror 创建的工作区只是允许原样复用,不会自动选中原样复用。Stage 3 再用该消费范围实际保留的身份、结构与应用规则实现已确认方向。具体规则落在 `references/strategist.md` 与 `spec_lock_reference.md`。+安装模板不会让沟通问题消失。Stage 1 始终独立确认同一份开放式沟通契约。Brand 提供身份约束、结构仍然自由;Layout 提供结构能力;Deck 还提供应用契约。Stage 2 推导时才把已保存的应用契约与当前确认结果对照,不能静默当成真值,再根据场景在合法范围内选择 `mirror`、`layout` 或 `style`。因此,按 mirror 创建的工作区只是允许原样复用,不会自动选中原样复用。Stage 3 再用该消费范围实际保留的身份、结构与应用规则实现已确认方向。规划语义由 `references/strategist.md` 与 `references/strategist-template.md` 负责,机器结构由 `templates/schemas/spec_lock.schema.json` 负责。---diff --git a/skills/ppt-master/references/ai-image-comparison/README.md b/skills/ppt-master/references/ai-image-comparison/README.mdindex 7243f9b1..0acb32f2 100644--- a/skills/ppt-master/references/ai-image-comparison/README.md+++ b/skills/ppt-master/references/ai-image-comparison/README.md@@ -58,7 +58,7 @@ Generated images land in the corresponding subdirectory. Each item's `status` in| If you are deciding... | Look at ||---|---|-| Which rendering to lock in Strategist h.5 | `rendering/` — scan all 20 side by side; pick the visual temperament that matches the deck |+| Which rendering to lock in [`strategist-image.md`](../strategist-image.md) §2 | `rendering/` — scan all 20 side by side; pick the visual temperament that matches the deck || Diagnosing a legacy palette lock or comparison asset | `palette/` — see how historical color behaviors shift the same subject; do not expose it as a new-flow choice || Which type fits a specific image's purpose | `type/` — match the internal composition to the page's content shape |diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.mdindex e00f75fc..854205df 100644--- a/skills/ppt-master/references/animations.md+++ b/skills/ppt-master/references/animations.md@@ -167,7 +167,7 @@ Aim for **3–8 content groups per slide**. This is also the granularity PowerPo- ≤ 8 visible top-level primitives → each becomes one anchor (capped to avoid 70+ atom cascades on dense pages).- > 8 → animation is skipped on that slide. The slide still renders, just without entrance animation.-Executors should wrap logical sections in `<g id>` regardless of whether you plan to animate. The Executor reference (`skills/ppt-master/references/shared-standards.md`) requires it.+Executors should wrap logical sections in `<g id>` regardless of whether you plan to animate. [`shared-standards-core.md`](./shared-standards-core.md) requires it.---diff --git a/skills/ppt-master/references/canvas-formats.md b/skills/ppt-master/references/canvas-formats.mdindex fa6b8d61..d801b1b7 100644--- a/skills/ppt-master/references/canvas-formats.md+++ b/skills/ppt-master/references/canvas-formats.md@@ -1,6 +1,6 @@# Canvas Format Specification-> See [`shared-standards.md`](shared-standards.md) §4.1 for the normative root+> See [`shared-standards-core.md`](./shared-standards-core.md) §4.1 for the normative root> `viewBox` grammar, compatibility spellings, and fail-closed validation rules.## Format Quick Reference@@ -71,7 +71,7 @@ Content purpose?| Story | — | Middle 1500px | Top safe zone 120px, bottom 180px || WeChat Article Header | Center/left-aligned 48-72px | — | Image on right or as background |-> **Body font baseline scales with canvas and reading mode** — a PPT 16:9 baseline confirmed for read-close / business / projection cannot be carried onto tall canvases (Xiaohongshu / Story / A4). Pick the baseline from the confirmed canvas, not the recommended one; see the per-canvas px anchors in [`strategist.md`](strategist.md) §g "Font Size Ramp" (the system is px-only — all sizes are unitless px on every canvas).+> **Body font baseline scales with canvas and reading mode** — a PPT 16:9 baseline confirmed for read-close / business / projection cannot be carried onto tall canvases (Xiaohongshu / Story / A4). Pick the baseline from the confirmed canvas, not the recommended one; see the per-canvas px anchors in [`strategist.md`](strategist.md) §g "Typography Plan Confirmation" (the system is px-only — all sizes are unitless px on every canvas).## ViewBox Examplesdiff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.mdindex 327a5724..4ba9ba21 100644--- a/skills/ppt-master/references/executor-base.md+++ b/skills/ppt-master/references/executor-base.md@@ -1,137 +1,27 @@-# Executor Common Guidelines+# Executor Flat and Shared Core-> Narrative skeleton and visual aesthetic come from this deck's locked files under [`modes/`](./modes/_index.md) and [`visual-styles/`](./visual-styles/_index.md). Technical constraints are in shared-standards.md.+Always-loaded Executor authority for flat SVG page authoring and behavior shared by every Generate route. Load conditional branches only when their trigger is present.-**Hard rule — complete page SVG**: Every visible object intended for the exported slide MUST exist in the final page SVG or be explicitly referenced by it. Templates and `spec_lock.md` guide construction; they are not export-time overlays for missing visible content.--**Hard rule — route-specific PowerPoint structure**: Free-design, brand-only, and `template_reuse_scope: style` projects use `pptx_structure.mode: flat`: write no root Master/Layout identity, `data-pptx-layer`, or `data-pptx-placeholder`; every visible object remains Slide-local, and the root declares exactly one canonical `data-pptx-page-role` (`cover` / `toc` / `section` / `content` / `ending`). Export materializes one clean project-owned Master plus one Blank Layout from the current lock. `template_reuse_scope: mirror|layout` projects use `mode: structured`: every page reads its locked Master/Layout row and declares the four root identity attributes from the first draft. Do not add `data-pptx-layout-kind` or duplicate identity with `data-pptx-page-role`. Add `data-pptx-role` only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by specialized metadata; the marked element uses a stable unique `id`. See [`semantic-svg.md`](./semantic-svg.md).--**Hard rule — supported PPTX route**: The only supported generated-PPTX path is `svg_output/` through the project SVG-to-DrawingML converter. Step 7.2 still generates `svg_final/` as a mandatory self-contained visual preview that may be inserted as an SVG picture. Do not treat PowerPoint's manual Convert-to-Shape operation as an authoring target or compatibility requirement.--> Note: this rule covers page design only. Speaker notes, animations, transitions, narration, and direct native-PPTX workflows retain their separate artifacts and package-level processing.-------## 1. Template Reuse Rules+**Conditional branch routing**:-### 1.0 Pre-generation Template Read--**Hard rule**: Read the compact template roster once, but never treat a summary as the full page prototype.--| Source list | Read path |+| Trigger | Load ||---|---|-| Chosen template's `design_spec.md` (template capabilities) | `templates/design_spec.md` |-| Model-readable execution roster, when present | `templates/template_execution_manifest.json` |-| Selected mirror prototype's text-slot sidecar | The roster entry's `text_slots_path` under `templates/` |-| Every distinct chart name in `spec_lock.md page_charts` | `templates/charts/<chart_name>.svg` |-| Chart types in `design_spec.md §VII` not covered above | `templates/charts/<chart_name>.svg` |--When `template_execution_manifest.json` and the selected entry's `text_slots_path` exist, read the compact roster once for selection/orientation and the sidecar before authoring each mirror page; then read the selected complete `templates/<basename>.svg`, which remains the visual/structural authority. Layout reuse reads the selected complete SVG but does not need the mirror-only sidecar. When the manifest, selected entry, or sidecar is unavailable, batch-read every distinct `<basename>` in `spec_lock.md page_layouts` before page 1. On mirror, preserve text topology directly from the complete SVG under §1.1; missing derived metadata alone does not invalidate the workspace. Chart SVGs remain one-time batch reads.--`spec_lock.md` is the only file re-read per page (§2.1).--**Exception**: user mid-deck adds pages or swaps templates introducing a basename/chart absent from the original roster/batch → read the new file once, continue.--> The execution manifest reduces roster/context load; it never authorizes writing from selectors alone. The selected full SVG must be open before editing that page.--Resolve the per-page template SVG via `spec_lock.md page_layouts` (authoritative). There is no filename/page-type fallback.--**Resolution order (per page):**--1. `template_reuse_scope: mirror` → see §1.1. The installed workspace must support `replication_mode: mirror`.-2. `template_reuse_scope: layout` → resolve `P<NN>: <basename>` from `page_layouts`, retain the structure system, and apply the non-mirror skin/reflow rules below.-3. `template_reuse_scope: style` or no deck/layout template → flat free design: use template colors/typography/decoration/rhythm as style input, but write no native Master/Layout mapping or SVG structure metadata.-4. `mirror` / `layout` with no current-page `page_layouts` row → stop; adaptive mode still requires one selected input prototype.--> Note: `page_layouts` disambiguates the multiple content variants a template may ship; missing mappings are contract errors.--**Templates supply structure, not skin (`layout` scope)**: a chart or layout template's gradients, drop-shadows, palette, **and font sizes** are placeholder. Inherit its geometry, label / legend placement, and series-encoding logic; re-skin every fill / stroke to the deck's `visual_style` + `spec_lock.colors` — flat styles strip the gradients and shadows, gradient / glass styles repaint their own. Forbidden — shipping a template's default `<linearGradient>` / `cardShadow` / Tailwind fills unchanged. `mirror` scope is the exception: §1.1 preserves visuals verbatim.--**Font size is skin, not geometry (non-mirror).** A chart / layout template's hardcoded `font-size` values (often 11–16px, sized for the template's own dense placeholder text) are NOT inherited — classify each text into its `spec_lock.md` role and use that role's locked size, exactly as you re-skin color. **Structural roles (page title / body / subtitle / annotation / footnote) hold their one deck-wide size on every page** — the template's placeholder px never overrides it; same-role text drifting page to page is what makes a deck look unprofessional.--**Typography execution order (mandatory):**--1. Build a per-page text inventory from `design_spec.md §IX` + the current `notes/<NN>_*.md`.-2. Classify each text item before drawing. **Structural roles** (`title`, `subtitle` / `lead`, `body`, `annotation`, `footnote` / `page_number`) must map to their declared `spec_lock.typography` slot. A **one-off feature element** (a single hero number, an isolated emphasis label) may take an in-ramp intermediate value — the ramp is anchored on `body`, not a closed menu — but a feature size that **recurs** must be promoted to a declared slot. The failure mode this guards against is structural text silently inheriting the template's compact px, not legitimate feature sizing.-3. Copy the role's locked px value into `font-size` verbatim. Do this before placing the text; never start from a template `font-size` and then "adjust".-4. Layout from those locked sizes: compute line-height, wrapped line count, child `y` / `dy`, card padding, card height, column gaps, and available image/chart area from the chosen px values.-5. Only after this reflow may you inspect fit. If fit fails, move / resize containers or simplify local geometry first; do not reduce the role size merely because the inherited template slot was smaller.--**Geometry adapts to the type, never the reverse**: when the locked size is larger than the template's placeholder text, widen / heighten the card, open spacing, and recompute child `y` / `dy` to make room — do not shrink the font to fit the inherited container. A `font-size` change is a layout change: revise line-height and every downstream vertical coordinate that depends on it. For wrapped text, allocate at least the wrapped line count × line-height plus top / bottom padding; fixed `y` stacks copied from a smaller template are invalid once the locked role size is applied. The Executor renders the page it was given; page count and per-page density are the Strategist's call, fixed at confirmation — do **not** re-paginate, split the page, or drop authored content to cope with size here. Only when a single block still cannot fit after the geometry is fully reflowed may you shrink **that block** as a bounded last resort — and **only body text** is ever shrunk this way. Title, subtitle, annotation / caption, footnote and page number are **locked once set and never adjusted to fit** — their values hold across the whole deck. Step the overflowing body block's `font-size` down by `2`px at a time, and only if it still overflows step it down again, up to a cumulative floor of **`4`px below the locked body size** (e.g. `24` → no smaller than `20`). This is a **local, single-block** reduction — the deck-wide locked body size is unchanged on every other block and page. (The Executor works in **unitless px** throughout — spec_lock and SVG carry no `pt`.) If the block still overflows at the floor, surface a `warning:` rather than silently restructure the page. (Mirror templates are the exception: §1.1 preserves their sizes verbatim — there the source deck's typography *is* the spec.)--### 1.1 Mirror reuse — literal page replacement--When `spec_lock.md` confirms `template_reuse_scope: mirror`, Executor switches to a literal replacement path. The workspace capability `replication_mode: mirror` is a prerequisite, not the trigger by itself:--1. **Per-page reference selection** — Strategist selects one mirror page per project page via `spec_lock.md page_layouts` (e.g., `P04: 015_content`). The basename is the mirror filename without extension; Strategist made this choice by reading `design_spec.md §V Page Roster` descriptions, not by guessing.-2. **Copy, don't fill** — open the referenced full mirror SVG immediately before authoring the page. Copy it as the starting point, then edit slide-specific text in place. Preserve every non-text element and every `data-pptx-*` structure attribute verbatim.-3. **What you may edit** — only the visible string values already carried by `<text>` and `<tspan>` nodes that express slide-specific content (title, body, captions, KPI labels, dates, page numbers). Keep the number, order, nesting relationship, and **all attributes** of every `<text>` / `<tspan>` node unchanged. Never merge or split nodes, move a string between nodes, add a new tspan, or delete an empty carrier. The selected `text_slots_path` sidecar exposes the expected selectors/counts/hashes, but the complete SVG remains authoritative.-4. **What you must not touch** — element positions, sizes, fonts, colors, fills, strokes, gradients, **which image each `<image>` points at**, `<g>` grouping, sprite-sheet `<svg viewBox>` wrappers, decorative `<rect>` / `<path>` / `<circle>` / `<polygon>` shapes, `<use data-icon="...">` markers, embedded chart data structures. Mirror's value is preserving the source deck's visual identity — any geometric / decorative drift defeats the purpose. **The `href` path is not the image**: normalizing a bare `href="cover_bg.png"` to `href="../images/<name>"` (when Step 3 relocated the asset to `images/`) points at the *same* image and changes nothing visual — that is an allowed path fix, not a fidelity edit. Leaving the bare href as-is is also fine; the exporter and live preview resolve bare hrefs against `images/` either way.-5. **Content fit** — if the replacement needs a different number of text segments/items, do not merge/split nodes, drop sourced content, or restructure the grid. Select a better mirror prototype and update the planning mappings, or report `warning: P<NN> content does not fit mirror reference <basename>; choose another prototype or change template_reuse_scope to layout/style`.-6. **Visible text editing** — mirror SVGs may keep literal source text rather than `{{...}}` authoring markers. Edit values in place while retaining imported semantic `data-pptx-placeholder` identity and exact text topology.-7. **Output filename** — follow the standard project SVG naming convention (`<NN>_<page_name>.svg` where `<NN>` matches the project page index, not the mirror source index). The mirror filename is the *reference*, not the *output*.--**Detecting mirror mode**: read `template_reuse_scope` from `spec_lock.md` before every page. `replication_mode: mirror` in the installed template only determines whether that confirmed scope is legal; it must never force mirror behavior when the confirmed scope is `layout` or `style`.--**Mirror + chart pages**: chart structures inside a mirror SVG are already drawn (axis, series, labels). Treat them as visual references — replace the data labels and series text content to match the project's chart spec, but do not redraw the chart from a `templates/charts/<name>.svg` baseline. A mirror template's `page_charts` entries are normally absent for this reason.--**Legacy template boundary**: A template with missing root Master identity, direct atomic placeholders, `data-pptx-layout-kind`, unmapped `baseline`, `preserve`, or `layout_strategy: distill` is not a fallback input. Stop and create a new current workspace through [`create-template`](../workflows/create-template.md) before generation.--### Page-Template Mapping Declaration (Required Output)--Before generating each page, output which template is used:--```-📝 **Template mapping**: `templates/03a_content_image_text.svg` (free-design routes may use "None")-🎯 **Adherence rules / layout strategy**: [specific description]-```--- **Content pages**: template defines only header/footer; content area is free-- **No template**: allowed only on free-design or brand-only routes+| `pptx_structure.mode: structured` | [`executor-structured.md`](./executor-structured.md) |+| Any data chart, chart catalog selection, or text-grid table | [`executor-chart.md`](./executor-chart.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 |+| Any image or formula resource, including template-bundled images | [`executor-image.md`](./executor-image.md) |+| Any `Status: Sourced` web image | [`executor-web-image.md`](./executor-web-image.md), after `executor-image.md` |+| Speaker notes generation after all SVG pages pass | [`executor-notes.md`](./executor-notes.md) |-### 1.2 PowerPoint Master / Layout Mapping+> Narrative skeleton and visual aesthetic come from this deck's locked files under [`modes/`](./modes/_index.md) and [`visual-styles/`](./visual-styles/_index.md). Technical constraints are in [`shared-standards-core.md`](./shared-standards-core.md).-This section applies only when a deck/layout template is confirmed with `template_reuse_scope: mirror|layout`. `page_layouts` selects the input SVG prototype, `pptx_masters` / `pptx_layouts` declare unique reusable output definitions, and `page_pptx_layouts` assigns every generated page before the first page is drawn. `template_reuse_scope: style`, free-design, and brand-only routes use `pptx_structure.mode: flat`, omit all four sections, skip the rest of §1.2, and keep every SVG object Slide-local.--**Hard rule — reuse-scope route**: `template_reuse_scope: mirror|layout` requires `pptx_structure.mode: structured`. `template_reuse_scope: style` requires `mode: flat` even though a template supplied its visual vocabulary. Missing mode or legacy values (`baseline`, `template`, `preserve`), `layout_strategy`, Layout-kind fields, partial mappings, and old direct placeholders stop generation. Create a new template workspace through [`create-template`](../workflows/create-template.md); do not upgrade the active SVG project in place.--**Hard rule — root identity**: A `page_pptx_layouts` row binds the page to one key in `pptx_layouts`; that unique definition supplies its Master key, Layout picker name, and prototype source. Put the declared Master key/name and Layout key/name on the root SVG. A Layout key belongs to exactly one Master and remains globally unique.--**Hard rule — atomic fixed layers**: Every `data-pptx-layer="master|layout"` visual is one direct root semantic atom that compiles to one DrawingML object. An ordinary marked `<g>` is forbidden; one validated compact authored-preset `<g>` emitted by `preset_shape_svg.py` is the sole group exception because it compiles to one native shape. When reconstructing source PPTX groups, recursively push supported transforms, paint, opacity, and z-order into atomic children. Repeat the identical ordered Master atom contract on every page using that Master and the identical ordered Layout atom contract on every page sharing that `(master, layout)` pair.--**Hard rule — PowerPoint paint order**: Direct children appear in this order: Master background atoms, Layout background atoms, optional Slide background, remaining Master atoms, remaining Layout atoms, then slot groups and Slide-local content groups. Backgrounds are the inheritance plane beneath all shapes.--**Mandatory — slot authoring**: A reusable content slot is one direct root `<g id>` carrying `data-pptx-placeholder` and positive `data-pptx-placeholder-bounds`. A normal slot contains exactly one compatible direct drawable child marked `data-pptx-placeholder-carrier="true"`. Export unwraps that child into the real Slide placeholder binding. Decorations do not belong in the slot; move reusable decoration to a root Layout atom and keep page-specific labels/captions in another slot or Slide-local group.--**Mandatory — slot identity**: Preserve imported `data-pptx-placeholder-idx` values where available; otherwise omit the title index and assign unique indices only where repeated roles need disambiguation. Pages sharing one Layout key repeat the same slot ids/types/effective indices/default bounds/binding modes. Current text, crop, and Slide-local carrier geometry may differ.--**Composite proxy fallback**: A genuinely composite region may use a direct `<g data-pptx-placeholder="object" data-pptx-placeholder-binding="proxy">` with positive bounds. Its visible group remains Slide-local and export creates one hidden transparent matching placeholder proxy. This downgrade is valid only for `object`; do not use it for an ordinary title, body, picture, chart, table, or media slot.--**Forbidden — dummy carriers**: Never satisfy a carrier slot with tiny text, near-transparent glyphs, background-colored punctuation, or other fake content. Leave an intentionally blank text carrier empty/whitespace-only—the exporter emits a legal invisible U+200B run—or use the composite `object` proxy contract. If `strict` prototype binding cannot represent the completed composition, surface the mismatch; select a compatible prototype or create an explicit adaptive Layout instead of hiding the conflict.--**Zero-slot Layout**: A Layout may have no slot groups. Covers, posters, and fixed visual pages still declare their named Master/Layout and fixed atoms. Do not manufacture a full-page `object` slot or empty `utility` identity.--**Mandatory — per-page slot coverage**: On every mapped page, declare a slot for each standard role the page actually has: the page heading as `title`, a cover tagline as `subtitle`, the page number as `slide-number`, running footer text as `footer`, a hero / content image as `picture`, and a body block already authored as one merged text frame as `body`. A page shipping zero slots exports a Layout with no insertable placeholders — valid only for a genuinely fixed composition (see Zero-slot Layout above), never as the deck-wide default. Pages sharing one layout key ship the same slot set.--**Hard rule — variable slot content**: “Per-page headings never stay Slide-local by default” means authoring them as `title` / `subtitle` slots; it never permits page-varying text or images to become fixed Layout atoms. Any such value that varies across pages sharing one Layout key MUST be carried by a slot or remain Slide-local.--**Mandatory — master/layout layer coverage**: On every mapped page, mark the deck-wide background and every-page chrome (footer bar, running logo) `data-pptx-layer="master"`, and mark the static framing that defines this layout key's composition (header rule, divider band, zone panels — including chrome repeated on every content page but absent from the cover) `data-pptx-layer="layout"`. A mapped page with zero `data-pptx-layer` marks exports a bare Master and an empty Layout — the layer marks, not the slide content, give each Layout its visible design.--**Layout identity**: Different keys differ in fixed Layout atoms or slot topology/default bounds/binding modes. Identical contracts should share one key. Current wording, imagery, crop, and Slide-local geometry never define identity.--**Template adherence**: Strict copies the prototype Master/Layout/slot contract exactly. Adaptive keeps the prototype Master and may change reusable Layout atoms or slots only under a new explicit Layout key/name. When the completed composition genuinely needs that change, update `spec_lock.md pptx_layouts` immediately while authoring the first affected page; later pages may reuse the new key only by repeating its exact contract. Changing only a label is not a new Layout.--**Layout-content boundary**: Mark only genuinely reusable fixed framing as a Master/Layout atom. Concrete titles, body copy, metrics, chart marks, images, and page-specific groups remain inside slot groups or ordinary Slide-local content groups. The exporter never infers or clusters structure.+**Hard rule — complete page SVG**: Every visible object intended for the exported slide MUST exist in the final page SVG or be explicitly referenced by it. Templates and `spec_lock.md` guide construction; they are not export-time overlays for missing visible content.-**Background ownership**:+**Hard rule — flat PowerPoint structure**: Free-design, brand-only, and `template_reuse_scope: style` projects use `pptx_structure.mode: flat`: write no root Master/Layout identity, `data-pptx-layer`, or `data-pptx-placeholder`; every visible object remains Slide-local, and the root declares exactly one canonical `data-pptx-page-role` (`cover` / `toc` / `section` / `content` / `ending`). A `style` template supplies colors, typography, decoration, and rhythm as style input without creating per-page prototype mappings. Export materializes one clean project-owned Master plus one Blank Layout from the current lock. Add `data-pptx-role` only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by specialized metadata; the marked element uses a stable unique `id`. See [`semantic-svg.md`](./semantic-svg.md).-| Scope | SVG authoring |-|---|---|-| Deck-wide default | Direct full-canvas solid `<rect data-pptx-layer="master">` repeated identically on every page |-| Page-type default | Direct full-canvas solid `<rect data-pptx-layer="layout">` repeated on every page sharing that layout key |-| One-page exception | Direct full-canvas solid `<rect data-pptx-layer="slide">` |+**Hard rule — supported PPTX route**: The only supported generated-PPTX path is `svg_output/` through the project SVG-to-DrawingML converter. Step 7.2 still generates `svg_final/` as a mandatory self-contained visual preview that may be inserted as an SVG picture. Do not treat PowerPoint's manual Convert-to-Shape operation as an authoring target or compatibility requirement.-The exporter writes these solid fills as real Master/Layout/Slide `p:bg`, not selectable full-canvas shapes. In structured mode, gradients, preset patterns, images, textures, and overlay panels remain explicit shapes or pictures; the generic background-promotion rule outside structured mode does not expand this ownership contract.+> Note: this rule covers page design only. Speaker notes, animations, transitions, narration, and direct native-PPTX workflows retain their separate artifacts and package-level processing.---@@ -159,7 +49,7 @@ The §IX wording and sourced facts remain authoritative. Do not rewrite, drop, o**Per-block expression**: render each `design_spec.md §IX Content` block in its written texture — a full-sentence block as wrapped prose, a fragment/label block as bullets/keywords. **Never split a full-sentence block into a bullet list** — splitting loses the information that the block was continuous reasoning, not a set of parallel points; not because a bullet lays out easier, and not because an inherited template slot is shaped as a list. If a block carries no clear texture, infer the mode from its wording and the page layout.-- **Prose render recipe**: one `<text>` per paragraph; wrap lines with sibling `<tspan>` where the first line uses `dy="0"` and every subsequent line repeats the parent `<text>`'s **exact `x`** and the **same positive relative `dy`** (the line-height). Equal relative `dy` + matching `x` + the same effective `font-size` lets lines flow inside one PowerPoint paragraph; a font-size change preserves a new paragraph inside the same text frame, while a growing/cumulative `dy`, an irregular gap, or a mismatched `x` (e.g. `x="0"` under `<text x="60">`) may split them into separate single-line boxes. Set the line-height `dy` from the font size × a line-height factor. **Default — line-height by density (may override per content fit)**: ~1.4–1.5× for dense / small-body blocks (CLReq comfortable minimum), 1.6–2.0× for large-type, sparse, or `breathing` blocks. Fit about width ÷ font-size CJK glyphs per line (Latin fits roughly twice that); the last line runs short. Use the body ramp size, not a new one.+- **Prose render recipe**: use one `<text>` per paragraph. For wrapped lines, follow [`shared-standards-core.md`](./shared-standards-core.md) §4.2: sibling positioned `<tspan>` lines repeat the parent's exact `x`, effective font size, and one positive relative `dy`. Use roughly 1.4–1.5× line height for dense/small body and 1.6–2.0× for large or breathing text; keep the locked body size.- **Template precedence**: when an inherited template slot is a bullet list but the §IX block is prose, the prose wins — widen or reflow the container to hold the paragraph, or drop that card; do not pour the sentence back into the list slot.- **Mode precedence**: the locked mode shapes voice / register, not §IX's authored titles or page order. When a `§IX` title is a user-authored topic label, keep it — do not upgrade it to an assertion just because the mode (e.g. `pyramid`) favors them; mode title-tendencies apply only to AI-drafted titles.@@ -174,9 +64,10 @@ The §IX wording and sourced facts remain authoritative. Do not rewrite, drop, o- Colors (fill / stroke / stop-color) MUST come from `colors`- Icons MUST come from `icons.inventory`; library MUST equal `icons.library`- Font family from `typography`: use role override (`title_family` / `body_family` / `emphasis_family` / `code_family`) if declared, else fall back to `font_family`-- Font sizes follow a **ramp anchored on `typography.body`**, not a closed menu. **Structural roles — page title, body, subtitle, annotation / caption, footnote / page number — render at one consistent size deck-wide, taken from their `spec_lock` slot; never re-pick a structural role's size page by page or carry a template's placeholder px.** This locks the **role**, not every glyph: a page may still carry deliberate typographic hierarchy — a lead-in sentence, an inline emphasis figure, a pull-quote, a kicker, a hero number — but each of those is its **own role / feature element** with its own size, **applied consistently deck-wide** (declare a recurring one as its own `spec_lock` slot). In-band intermediate sizes are for exactly these feature elements. What is banned is the *same* role drifting size to fit a container or by page whim — that scatter is what reads as unprofessional. Sizes outside every band require extending the lock first.-- **The page's core message is primary — render it ≥ `body`.** The one-idea / key-claim / key-takeaway line a page is built around is its most important text; map it to the locked `lead` or `subtitle` slot (≥ `body`), never to a sub-`body` size. Demoting it below body while data callouts or labels sit larger inverts the hierarchy — the failure this prevents. If no `lead` / `subtitle` slot is locked for a recurring core-message line, surface it (per below) instead of improvising a smaller one. A footnote / page number / source credit uses the locked `footnote` (or `annotation`) slot — never an invented sub-`annotation` size; and the body-shrink last resort (§1.0) bottoms out at `body − 4`px, a hard floor never crossed.-- **Write the locked px verbatim; at most 2 decimals.** `font-size` MUST be the exact px from `spec_lock.typography` — if `body` is `24`, write `24`; never substitute a "rounder" or PowerPoint-familiar number (`20` / `18` / `36`). The system is px-only — there is no pt to convert, and a remembered pt-style value written as px renders the whole deck the wrong size. Prefer whole numbers (sizes are clean even px); keep a decimal only for a slot that genuinely carries one in `spec_lock`. Never emit long tails like `20.8026`: the exporter rounds the final size to 1 decimal pt, so extra px precision is wasted noise.+- Font sizes follow a ramp anchored on `typography.body`. Structural roles use their locked size deck-wide; recurring feature roles such as lead, pull quote, or hero number need their own lock slot. Never resize one role page by page or inherit a template placeholder size.+- **Core message ≥ `body`**: map the page's primary claim to locked `lead` / `subtitle`, never below body. Footnotes, page numbers, and credits use locked `footnote` / `annotation`; do not invent smaller sizes.+- **Write locked px verbatim, with at most two decimals.** Do not substitute familiar pt-style numbers or emit long precision tails.+- **Bounded body-fit last resort**: reflow geometry first; only an overflowing body block may step down by `2`px, never below `body − 4`px. Other roles never shrink. At the floor, warn instead of dropping content or repaginating. Mirror pages preserve source typography.- Images MUST reference files listed under `images`; no invented filenames- Formula PNGs are images with `Acquire Via: formula`; place a `Rendered` file only from its listed path, use the normal placeholder for `Needs-Manual`, and never recreate the formula as text.@@ -198,64 +89,6 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`**Tag not found for current page — fixed compatibility default** → emit `warning: spec_lock.md page_rhythm tag not found for P<NN> — falling back to dense` once per deck (aggregate; do not repeat per page), fall back to `dense`. Do not invent a tag.-**Per-page template lookup — `page_layouts` section (`mirror` / `layout` only)**:--Before drawing each page, look up its entry in `page_layouts` to decide which basename to inherit (the SVG itself was loaded in §1.0):--- Entry present (e.g., `P04: 03a_content_image_text`) → inherit the corresponding full SVG. The basename **must match** an actual file in the chosen template directory. If it does not, stop before drawing and report the invalid mapping; neither `strict` nor `adaptive` may fall back to free design inside a structured template deck.-- No entry for this page with `template_reuse_scope: mirror|layout` → stop before drawing and report the missing Strategist mapping. Adaptive mode still requires one selected complete template SVG; flexibility applies to the post-design output Layout, not to whether an input prototype exists.-- Whole section absent while `template_reuse_scope: mirror|layout` is present → stop before drawing; the current template contract is incomplete.-- `template_reuse_scope: style` → the whole section must be absent; do not perform per-page prototype lookup.--Do **not** invent a prototype entry, and do **not** assume a structured template just because `templates/` exists. For `mirror` / `layout`, a missing or invalid `page_layouts` row is an upstream contract error. `style` is a separate flat deck route, never a per-page fallback.--**Per-page PowerPoint layout lookup — `template_reuse_scope: mirror|layout` only**:--- When `pptx_structure.mode` is `flat` (including `template_reuse_scope: style`), skip this lookup and the structured scaffold below. `pptx_masters`, `pptx_layouts`, `page_layouts`, and the corresponding SVG metadata must all be absent; each root still declares its canonical `data-pptx-page-role`.-- With `template_reuse_scope: mirror|layout`, `pptx_structure.mode` must equal `structured`; any other or missing value is rejected. Do not migrate an invalid structured contract in place: create a new current-contract workspace through Create Template before generation resumes.-- Read the current page assignment as `P<NN>: <layout_key>`. Resolve the assigned Layout key in `pptx_layouts`, then resolve its Master key in `pptx_masters`. Missing, malformed, or partial mappings stop before drawing.-- Write matching root Master/Layout key and picker names. Do not write `data-pptx-layout-kind` or `data-pptx-page-role`.-- On strict template use, the row and SVG contract match the selected prototype exactly.-- On adaptive template use, retain the prototype Master. If the final composition changes fixed Layout atoms or slot topology/bounds, allocate a new key/name and update this row before completing the page.-- A Layout key may repeat across non-adjacent pages only when its fixed atoms and slot contracts are identical.--**Structured template-page scaffold**:--```xml-<svg viewBox="…"- data-pptx-master="<master-key>" data-pptx-master-name="<master-name>"- data-pptx-layout="<layout-key>" data-pptx-layout-name="<layout-name>">- <rect id="master-bg" data-pptx-layer="master" …/> <!-- one atomic Master object -->- <text id="master-footer" data-pptx-layer="master" …>…</text> <!-- no Master/Layout g -->- <path id="layout-rule" data-pptx-layer="layout" …/> <!-- one atomic Layout object -->- <g id="title-slot" data-pptx-placeholder="title"- data-pptx-placeholder-bounds="60 36 1160 64">- <text id="title-carrier" data-pptx-placeholder-carrier="true" …>…</text>- </g>- <g id="body-slot" data-pptx-placeholder="body"- data-pptx-placeholder-idx="1"- data-pptx-placeholder-bounds="60 120 470 500">- <text id="body-carrier" data-pptx-placeholder-carrier="true" …>…</text>- </g>- <g id="picture-slot" data-pptx-placeholder="picture"- data-pptx-placeholder-idx="2"- data-pptx-placeholder-bounds="570 120 650 500">- <image id="picture-carrier" data-pptx-placeholder-carrier="true" …/>- </g>- <g id="content-block-1">…</g> <!-- 3–8 content groups -->- <g id="content-block-2">…</g>-</svg>-```--On structured template pages, Master/Layout atoms and slot groups are direct root children and precede ordinary content groups. Structural metadata nested inside an ordinary content group fails export. Flat pages use ordinary top-level semantic groups only.--**Per-page chart reference — `page_charts` section**:--Before drawing each page, look up its entry in `page_charts` to decide which chart structure applies (the SVG itself was loaded in §1.0):--- Entry present (e.g., `P09: timeline_horizontal`) → adapt the corresponding chart SVG already in context. Apply project colors/typography/density; do not copy verbatim. Cross-reference `templates/charts/charts_index.json` for the chart's purpose summary if needed.-- No entry for this page → either no chart on this page, or a chart that didn't match any catalog template (Strategist's `no-template-match` fallback). Design the visualization from scratch using `design_spec.md §VII` for guidance.-- Whole section absent → no chart pages in this deck.---@@ -269,9 +102,11 @@ Before drawing each page, look up its entry in `page_charts` to decide which cha- **Generation rhythm**: lock global design context first, then generate pages sequentially in one continuous context. No batched groups (e.g., 5 at a time).- **Fact provenance**: when a §IX page lists `Fact IDs`, resolve each ID from `sources/*.facts.json` and keep the claim/value unchanged. Render a compact source footnote using the source name and a short URL/domain when space permits; state the attribution naturally in speaker notes. When §IX says `Data class: scenario`, place a visible localized `Scenario data` / `情景数据` label adjacent to the affected KPI/chart and state naturally in notes that the number is illustrative. Never attach an external fact ID to scenario data or let an unlabeled invented KPI look factual.- **Default — stage each page with the style's composition geometry (may override when the content genuinely calls for a plain grid)**: an SVG page is a canvas, not a DOM. Before defaulting to stacked rounded-rect cards or uniform equal columns, pick one page-scale move from the locked visual style's §1 `Composition geometry` (a bleed shape, diagonal split, oversized numeral, orbit rings, …) to stage the page's primary zone. Card grids are one option among many, not the house layout.-- **Reference — image-led promotional pages (not a constraint)**: for travel, venue, product-introduction, hospitality, event, real-estate, and brochure-style decks, let images define the page skeleton before placing text. Consult [`image-layout-patterns.md`](image-layout-patterns.md) §Imported Deck Patterns and prefer patterns such as `#74` TOC image-navigation cards, `#75` asymmetric chapter banners, `#77` photo mosaic with a text cell, `#78` ambient banner + evidence photo + text panel, `#79` ribbon-header image cards, and `#80` side hero image + staggered evidence cards before falling back to plain left/right image-text splits.+- **Card containers — use the documented patterns**: when a content page needs section cards, use [`CHART_STYLE_GUIDE.md`](../templates/charts/CHART_STYLE_GUIDE.md) §11 patterns such as half-rounded tabs, nested borders, card-grid skeletons, relationship arrows, and ground anchors. Do not rebuild the legacy tinted rounded-rect plus cover-rect hack; it breaks SVG-to-PPTX color editing.+- **Reference — prefer semantic geometry over preset stacks**: for relationships such as ascending, converging, breaking through, or stacking, consider one page-specific polygon/path that expresses the relationship before stacking generic arrows. This does not override §3.0 when one literal stock shape is the semantic object.+- **Reference — create depth with restraint**: use rhythm, spacing, typography, accent bars, and subtle tints before shadows. Reserve lift for a few genuinely floating elements; keep peer grids, dividers, and body containers flat.- **Phased batch generation** (recommended):- 1. **Visual Construction Phase**: generate all SVG pages sequentially for visual consistency. Use layout judgment for chart marks during the draft. **MUST embed plot-area markers** per §3.1 below on every chart page — coordinate calibration is a post-generation step (see [`verify-charts`](../workflows/stages/verify-charts.md)) that depends on these markers — and **native object metadata** per §3.2 on every eligible data-chart page. **Reach for native presets** per §3.0 as you draw each page: a block arrow, chevron, banner/ribbon, callout, standard flowchart node, or star is authored through `preset_shape_svg.py` at draw time — decided by the object's intent as you create it, never by scanning finished paths, and never committed to a bare `<path>`/`<polygon>` when a preset expresses it (a gradient fill/stroke or a pattern fill is the one paint exception — keep those ordinary SVG). **First-page gate (Mandatory)**: after completing the first page, run `python3 scripts/svg_quality_checker.py <project_path> --stage first-page` and fix every error before drawing page 2. This stage validates only the first authored page with a partial structure roster; future declared pages are not reported missing.+ 1. **Visual Construction Phase**: generate all SVG pages sequentially for visual consistency. Use layout judgment for chart marks during the draft. **MUST embed plot-area markers** per [`executor-chart.md`](./executor-chart.md) §2.1 on every chart page — coordinate calibration is a post-generation step (see [`verify-charts`](../workflows/stages/verify-charts.md)) that depends on these markers — and **native object metadata** per [`executor-chart.md`](./executor-chart.md) §2.2 on every eligible data-chart page. **Reach for native presets** per §3.0 as you draw each page: a block arrow, chevron, banner/ribbon, callout, standard flowchart node, or star is authored through `preset_shape_svg.py` at draw time — decided by the object's intent as you create it, never by scanning finished paths, and never committed to a bare `<path>`/`<polygon>` when a preset expresses it (a gradient fill/stroke or a pattern fill is the one paint exception — keep those ordinary SVG). **First-page gate (Mandatory)**: after completing the first page, run `python3 scripts/svg_quality_checker.py <project_path> --stage first-page` and fix every error before drawing page 2. This stage validates only the first authored page with a partial structure roster; future declared pages are not reported missing.2. **Quality Check Gate**: run `python3 scripts/svg_quality_checker.py <project_path> --stage final --json` on `svg_output/`. Any `error` (banned/unsupported features, invalid values, unresolved references, viewBox mismatch, etc.) MUST be fixed on the offending page before proceeding — regenerate and re-check. Every `warning` is advisory: it never sends the page back for required modification, never authorizes automatic rewriting of compatible user syntax, and needs no acknowledgement/disposition line. Recommendation warnings describe the generated-SVG default; fidelity/quality warnings may be surfaced when material, while the existing input remains releasable. Prototype-identical diagnostics are recorded as `inherited`, source conversion losses as `source-import`, changed/new advisories as `introduced`, and release failures as `blocking` in `exports/svg_quality_report.json`. If release truly depends on a condition, it belongs in `errors`. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.3. **Logic Construction Phase**: after SVGs pass the quality check, batch-generate speaker notes for narrative continuity.@@ -318,85 +153,6 @@ stdout. It does not write a page or choose layout. Read the fragment and insertit through the normal `apply_patch` page edit; never redirect, loop, or batch itinto `svg_output/`.-### 3.1 Chart Plot-Area Marker (MANDATORY on every chart page)--> The [`verify-charts`](../workflows/stages/verify-charts.md) stage enumerates chart pages from `design_spec.md §VII`, then reads each page's plot-area marker to feed `svg_position_calculator.py`. A missing marker invokes that stage's declared fallback and adds avoidable derivation work.--**Hard rule**: every SVG page that contains a data visualization chart includes a plot-area marker inside `<g id="chartArea">`, placed **after axis lines** and **before the first data element** (bar, line, area, point).--**Rectangular plot area** (bar / horizontal_bar / grouped_bar / stacked_bar / line / area / stacked_area / scatter / waterfall / pareto / butterfly):--```xml-<!-- chart-plot-area: x_min,y_min,x_max,y_max -->-```--**Radial charts** (pie / donut / radar):--```xml-<!-- chart-plot-area: pie | center: cx,cy | radius: r -->-<!-- chart-plot-area: donut | center: cx,cy | outer-radius: r1 | inner-radius: r2 -->-<!-- chart-plot-area: radar | center: cx,cy | radius: r -->-```--**How to determine coordinate values**:--| Value | Derivation |-|-------|------------|-| `x_min` | X coordinate of the Y-axis line (leftmost data boundary) |-| `y_min` | Y coordinate of the topmost grid line (highest data boundary) |-| `x_max` | X coordinate of the rightmost axis endpoint or grid line |-| `y_max` | Y coordinate of the X-axis baseline |-| `cx, cy` | Center point of pie/donut/radar (accounting for `transform="translate()"`) |-| `r` | Outer radius of the chart |--**Per-page verification** — after writing each chart SVG, confirm the marker exists:--```bash-grep "chart-plot-area" <project_path>/svg_output/<current_page>.svg-```--> Calculator-supported data-chart templates in `templates/charts/` include this-> marker as a reference. If a data chart covered by §3.1 lacks it, that is a-> bug. Conceptual diagrams, frameworks, and other non-data visualizations in-> the same library do not use a plot-area marker.-- **Technical specs**: see [shared-standards.md](shared-standards.md) for SVG/PPT constraints-- **Card containers — use the documented patterns**: when a content page needs section cards (4 quadrants, parallel aspects, capability blocks, info cards), use the patterns codified in [`templates/charts/CHART_STYLE_GUIDE.md`](../templates/charts/CHART_STYLE_GUIDE.md) §11 — half-rounded section tab (§11.1), nested card border without stroke (§11.2), card-grid skeletons (§11.3), diagonal dashed relationship arrow for cross-quadrant relationships (§11.5), ground-anchor ellipse as a non-filter depth marker (§11.6), bidirectional interaction arrows for paired protocols (§11.7). Do not reinvent the "tinted full-rounded rect + white cover-rect to hide the bottom corners" hack; it survives in older templates but breaks SVG→PPTX color editing. Reference templates: [`labeled_card.svg`](../templates/charts/labeled_card.svg), [`quadrant_text_bullets.svg`](../templates/charts/quadrant_text_bullets.svg), [`kpi_cards.svg`](../templates/charts/kpi_cards.svg), [`matrix_2x2.svg`](../templates/charts/matrix_2x2.svg), [`team_roster.svg`](../templates/charts/team_roster.svg), [`client_server_flow.svg`](../templates/charts/client_server_flow.svg).-- **Reference — prefer semantic shapes over preset stacks (not a constraint)**: when a slide needs to express "ascending / converging / breaking through / stacking" — i.e., a relationship that goes beyond a generic arrow — prefer a single custom `<polygon>` or `<path>` that encodes the semantics geometrically, rather than stacking multiple preset arrows. A converging-tip path or a podium polygon reads faster than three arrows pointing at a label. Do not codify these as templates — they are page-specific; the rule is just "consider polygon before stacking presets."-- **Reference — visual depth through restraint (not a constraint)**: layered depth comes from rhythm (flat vs lifted, dense vs spacious), not from shadows everywhere. Shadow typically suits 2-3 genuinely floating elements per page (cards on photos, primary CTA, overlays); keep peer-grid cards, dividers, body containers flat. Reach for typography weight, spacing, accent bars, subtle tints **before** shadow.--### 3.2 PowerPoint-Native Chart/Table Replacement Marker (MANDATORY on eligible data-chart and text-grid table pages)--> `svg_to_pptx.py --native-charts-and-tables` replaces marked groups with PowerPoint-native Chart/Table objects (charts get an embedded Excel workbook). Markers stay dormant in the default export, whose SVG children become independently editable DrawingML shapes, but a deck without markers can never form data-backed native Chart/Table objects. Write the marker at draw time: the data is already in hand, and recovering it later costs a full re-read pass.--**Hard rule**: every data chart whose type appears in the **Supported chart types** list of [shared-standards.md](shared-standards.md) "PowerPoint-Native Chart / Table Replacement Markers" (the single authority for the eligible set, marker contract, and JSON schemas) gets `data-pptx-replace-with="chart"` plus one `<metadata type="application/json">` JSON child on its top-level `<g>`, transcribing the same data just plotted. Every pure text-grid data table gets `data-pptx-replace-with="table"` the same way, transcribing all visible cell text into `columns` / `rows`. The parent marker determines the JSON schema; do not duplicate a chart/table kind on the metadata child.--Generated authoring MUST omit `data-pptx-import-source` and-`data-pptx-fallback-sha256`: those attributes record imported-PPTX provenance-and its sealed fallback baseline. Never copy a static baseline from a chart-catalog or reusable template; normal content edits would make it stale.--`data-pptx-replace-with` is a **data-backed replacement claim**, not a generic label for a group that contains numbers and not a marker for ordinary PowerPoint shapes or connectors. Add it only when the matching JSON payload can be written in the same edit; if the object is meant to remain SVG geometry, do not add the marker.--- Chart types absent from that list and conceptual/diagrammatic graphics (process flows, cycles, quadrant cards, timelines, KPI cards) get **no marker** — `svg_quality_checker.py` rejects unsupported marker types.-- Canonical rectangular merged text cells may carry a table marker by putting anchor-only `row_span` / `col_span` in metadata and leaving covered cells blank. Nonrectangular/overlapping merges, nonblank covered cells, and graphical cells (icons, harvey balls, rating dots) get **no table marker** and stay on the SVG fallback route.-- Transcribe, don't restyle: `categories` / `series[].values` are the numbers just plotted; `style.colors` carries the series HEX values already used on the page (from `spec_lock.colors`).-- Data-point color: when a single column/bar series uses data-point colors in the fallback, copy those fills into `series[].point_colors` in category order.-- Data labels: when visible point values are part of the fallback chart, write `data_labels` instead of companion text; use `data_labels.points` for selected labels, and use `number_format`, `font_size`, `font_family`, and per-point `colors` / `color` when the fallback labels carry suffixes or color-coded text.-- Line markers: when the fallback line chart draws visible point nodes, set `line_style: "lineMarker"`; leave the default `line` only for line charts without nodes.-- Area-under-line: when a combo plot is drawn as a filled area under a line, keep `type: "line"`, add `area_fill: true`, and copy the area transparency into `series[].fill_opacity`; copy visible line `stroke-width` into `series[].line_width` for line/area series.-- Native chrome: write `title`, `subtitle`, axis titles, or `show_legend: true` only when the fallback visibly renders the same chrome inside the native chart's replacement scope. `title` is the PowerPoint chart title, not an object name; use `name` for page-semantic object naming (e.g. `p03-revenue-chart`). Write explicit `x`/`y`/`width`/`height` read from the drawn plot area; omission is the fallback — the exporter then infers the frame from the drawn fallback geometry.-- Value-axis labels: when the fallback keeps category labels but intentionally omits numeric value-axis tick labels, set `show_value_axis_labels: false`.-- Freeform chart text: transcribe center labels, source notes, and other in-chart annotations as companion `caption` / `note` / `notes` entries with explicit slide-coordinate bounds; do not rely on fallback `<text>` children to survive native export.-- Native chart typography mirrors the SVG fallback. Copy the fallback's shared chart font into `style.font_family` and visible chart text sizes into the matching metadata fields (`title_font_size`, `subtitle_font_size`, `axis_font_size`, `note_font_size`, etc.) only when role sizes differ; otherwise let the exporter infer them from visible fallback text. When a visible chart title, subtitle, or axis title needs its own size/color/font, write that field as an object with `text`, `font_size`, `font_family`, and `color`. Use `axis_title_font_size`, `legend_font_size`, or companion per-entry `font_size` only when the fallback visibly uses a separate size.-- Native table typography mirrors the SVG fallback. Write `style.font_family` and `style.font_size` from the visible table text; use `header_font_size` or per-cell `font_size` only when the fallback visibly does so. If the fallback has no explicit table font, fall back to the deck body family and locked body size from `spec_lock.md typography`.-- The marker group's transform stays translate/scale only (no rotate / matrix / skew).-- Visual parity is not a goal: the SVG drawing remains the designed visual and exports as editable DrawingML shapes; the native object is the data-backed counterpart with PowerPoint's chart/table-specific model. Never simplify the SVG design to match what a native object could show.--**Per-page verification** — after writing each eligible data-chart or text-grid table page, confirm the marker exists:--```bash-grep "data-pptx-replace-with" <project_path>/svg_output/<current_page>.svg-```### SVG File Naming Convention@@ -485,137 +241,21 @@ ls skills/ppt-master/templates/icons/simple-icons/ | grep github----## 5. Visualization Reference--Chart SVGs referenced in **VII. Visualization Reference List** are loaded once via the §1.0 batch read. This section governs adaptation only.--**Hard rule**: adapt the loaded chart SVG; do not improvise from memory and do not replicate verbatim. Apply project colors, typography, content; preserve visualization type.--**Adaptation rules**:-- **Preserve**: visualization type (bar/line/pie/timeline/process/framework…) as specified-- **Adapt**: data, labels, colors (project scheme), dimensions-- **Freely adjust**: composition, axis ranges, grid, legend, spacing, decoration — as long as the chart stays accurate and readable-- **Forbidden**: changing visualization type without spec justification; omitting data points or structural elements from the outline--> Templates: `templates/charts/` (76 types). Index: `templates/charts/charts_index.json`--### 5.1 Chart Coordinate Calibration--Coordinate calibration runs as a **conditional post-generation stage**, not inside the Executor authoring loop. After SVG generation completes, if the deck contains data charts, run [`verify-charts`](../workflows/stages/verify-charts.md) before post-processing.--The executor's only obligation here is upstream: embed the `<!-- chart-plot-area ... -->` marker on every chart page during initial draft (§3.1). Verify-charts enumerates chart pages from `design_spec.md §VII` (authoritative deck plan) and uses the marker to feed `svg_position_calculator.py`.--> Do NOT run `svg_position_calculator.py` during the initial draft. The calculator calibrates already-generated SVGs against their declared plot areas; running it before the SVG exists has nothing to compare against.-------## 6. Image Handling--Handle images by their status in the Design Spec's Image Resource List. Status enum and lifecycle: [`svg-image-embedding.md`](svg-image-embedding.md).--| Status | Source | Handling |-|--------|--------|----------|-| **Existing** | User-provided | Reference images directly from `../images/` directory |-| **Generated** | Generated by Image_Generator | Reference images directly from `../images/` directory |-| **Sourced** | Web-acquired by Image_Searcher | Reference from `../images/`. **Read [`image_sources.json`](image-searcher.md) to decide attribution** — see §6.1 below. |-| **Rendered** | Deterministic formula PNG | Reference from `../images/`; use `preserveAspectRatio="xMidYMid meet"` |-| **Needs-Manual** | Acquisition failed and file is absent | Use dashed border placeholder unless the expected file exists; the Step 7 readiness gate swaps placeholders for real files before export |-| **Placeholder** | Not yet prepared | Use dashed border placeholder |--**Reference syntax**: see [`svg-image-embedding.md`](svg-image-embedding.md).--**Template-bundled images**: when a template (deck / layout / brand) is applied, its bitmaps are copied into the project's `images/` alongside every other runtime image ([`apply-template-workspace.md`](../workflows/stages/apply-template-workspace.md)). Reference them the same way — `../images/<name>` — and do **not** reproduce a template SVG's bare sibling href (e.g. `href="cover_bg.png"`): the template SVG is reference material, the rendered page lives in `svg_output/` and must point at `../images/`. `template_reuse_scope: mirror` (§1.1) is the one exception — it copies hrefs verbatim, and the exporter resolves those bare hrefs against `images/`.--**Placeholder**: Dashed border `<rect stroke-dasharray="8,4" .../>` + description text--**`no-crop` images**: when a `spec_lock.md images` entry ends with ` | no-crop`, size the container to the image's native ratio (from `analyze_images.py` or file dims) and use `preserveAspectRatio="xMidYMid meet"`. Untagged entries are croppable — default to `slice`.--**Formula images — declared-inference fallback for a missing `no-crop` flag**: rows with `Acquire Via: formula` or `Type: Latex Formula` MUST be treated as no-crop. For a rendered file, use dimensions in this order: current `analysis/image_analysis.csv`, `design_spec.md §VIII`, then `images/formula_manifest.json`. For a `Needs-Manual` row, size the dashed placeholder from the planned dimensions in §VIII, then the manifest; the Step 7 readiness gate re-analyzes the supplied file and reconciles the container before export. Do not normalize all formulas to one height unless the spec explicitly states that layout choice.--### 6.1 Inline Attribution for Sourced Images (web path)--Whenever the slide uses an image with `Status: Sourced`, look up the corresponding entry in `project/images/image_sources.json` and act on `license_tier`:--| `license_tier` | Action on this slide |-|---|---|-| `no-attribution` | Embed the `<image>` element only. **No credit element needed.** |-| `attribution-required` | Embed the `<image>` element **plus** a small inline `<text>` credit element per the visual spec in [image-searcher.md §7](./image-searcher.md). |-| `manual` | Embed the `<image>` element only. **No credit element** — a user-supplied `--from-url` replacement; verifying usage rights / any required credit is the user's responsibility. |--The credit text is **not** rendered by post-processing or export — it must be present in the SVG you produce. The shape of the credit element (size, position, color, multi-image source line, hero gradient overlay) is specified in [image-searcher.md §7](./image-searcher.md). Do not invent a different style.--Use `attribution_text` from the manifest entry as the **starting point**, then compress for the small-text constraint (drop URL, drop filename, keep "via Provider / License"). For CC0/PD images that landed in the `attribution-required` tier only because of upstream metadata quirks (rare), credits are still safe to render.--`svg_quality_checker.py` treats missing CC BY / CC BY-SA inline attribution as an **error**. Fix the offending SVG before post-processing.--**The manifest is the single source of truth for credits.** Do not duplicate license info into speaker notes or any other artifact.-------## 7. Font Usage+## 5. Font UsageSource of truth: `spec_lock.md typography`. Use `font_family` as default; override per role with `title_family` / `body_family` / `emphasis_family` / `code_family` if declared. LaTeX formulas that Strategist rendered are PNG images, not a `code_family` text role.-**Missing required field — `typography.font_family`** → stop and return to [`strategist.md`](strategist.md) §6 step 4 to repair `spec_lock.md`; do not infer a stack from `design_spec.md`.+**Missing required field — `typography.font_family`** → stop and return to Generate Step 4 / [`strategist.md`](strategist.md) §6.2 to repair `spec_lock.md`; do not infer a stack from `design_spec.md`.**Hard rule**: every SVG `font-family` stack MUST resolve to pre-installed exported Latin / EA typefaces (Microsoft YaHei / SimHei / SimSun / Arial / Calibri / Segoe UI / Times New Roman / Georgia / Consolas / Courier New / Impact / Arial Black). PPTX has no runtime fallback — missing fonts degrade to Calibri.----## 8. Speaker Notes Generation Framework--### Task 1. Generate Complete Speaker Notes Document--After all SVG pages are finalized, enter Logic Construction Phase and write the full notes to `notes/total.md`. Batch-writing (not per-page) lets transitions plan coherently.--**Pure spoken narration**: notes are read aloud verbatim by `notes_to_audio.py` (TTS). Write only what should be spoken. No visible markers, no labeled meta-lines, no enumerated key-point lists, no duration annotations — anything you write outside the heading will be vocalized.--**Per-page structure**: `# <number>_<page_title>` heading (the `#` heading line is the only thing stripped before TTS), pages separated by `---`. Body is 2–5 natural sentences carrying the page's core message. Page-to-page transitions live inside the opening sentence as natural prose ("接下来……" / "Having framed X, let's turn to Y") — no bracketed `[过渡]` / `[Transition]` tags.--**Reading-mode note burden**:--| `consumption_mode` | Notes emphasis |-|---|---|-| `text` | Add interpretation or transition without reading the already self-contained page aloud. |-| `balanced` | Connect the visible claim and evidence, explain the trade-off, and bridge to the next page. |-| `presentation` | Carry the reasoning, context, and supporting detail intentionally omitted from the sparse projected surface. |--**Concrete examples** — same shape applies to any language; just write naturally in that language.+## 6. Completion Routing-中文 deck:--```-# 02_市场格局--在明确了行业背景之后,我们来看具体的市场格局。当前线上零售集中度持续上升,前三大平台合计份额已经达到百分之六十八,腰部玩家正在被快速挤压,留给新进入者的窗口期不超过十八个月。这意味着我们的策略必须聚焦,而不是铺开。-```--英文 deck:--```-# 02_market_landscape--Having framed the industry backdrop, let's look at the actual market landscape. Online retail concentration keeps rising — the top three platforms now hold sixty-eight percent of combined share, mid-tier players are being squeezed fast, and the window for new entrants is under eighteen months. This means our strategy has to focus, not spread.-```--> 日本語 / 한국어 / 其他语言:照搬同样的结构,用对应语言自然书写即可。--**Number readability**: TTS reads digits and symbols literally. Prefer fully-spelled forms in the language being spoken when literal pronunciation would be awkward (e.g. Chinese "百分之六十八" reads better than "68%"; "1-2分钟" reads as "一减二分钟"). Plain integers and percentages in English are fine as-is.--**Common mistakes to avoid**:-- Leaving any bracketed stage marker (`[过渡]` / `[Transition]` / `[Pause]` / `[Data]` / `[Scan Room]` / `[Interactive]` / `[Benchmark]` etc.) in the text — they will be read aloud literally.-- Adding `要点:① …` / `Key points: (1) …` / `时长:2分钟` / `Duration: 2 minutes` / `Flex: …` lines — TTS will speak "要点 一 …".-- Mixing languages within one deck's notes.--### Task 2. Split Into Per-Page Note Files--Auto-split `notes/total.md` into per-page files in `notes/`.--**Naming**: match SVG names (`01_cover.svg` → `notes/01_cover.md`); `slide01.md` also supported (legacy).-----+After every SVG page passes the final quality check, load [`executor-notes.md`](./executor-notes.md) and complete its notes contract before entering the route's Step 7.-## 9. Next Steps After Completion+## 7. Next Steps After Completion> **Auto-continuation**: After Visual Construction Phase (all SVG pages) and Logic Construction Phase (all notes) are complete, the Executor proceeds directly to the post-processing pipeline.diff --git a/skills/ppt-master/references/executor-chart.md b/skills/ppt-master/references/executor-chart.mdnew file mode 100644index 00000000..2cf5385a--- /dev/null+++ b/skills/ppt-master/references/executor-chart.md@@ -0,0 +1,125 @@+> See [`executor-base.md`](./executor-base.md) for the always-loaded Executor core and [`native-data-interface.md`](./native-data-interface.md) for native chart/table metadata schemas.++# Executor Chart and Table Branch++Conditional Executor authority for data charts, chart-catalog adaptations, chart verification markers, and eligible native chart/table replacement metadata.++**Trigger**: load when `design_spec.md §VII` contains a chart/table visualization, `spec_lock.md page_charts` contains any row, or the page carries an eligible data chart or text-grid table.++## 1. Reference Loading and Per-page Selection++Read each selected chart SVG once before its first use. If a later page introduces a chart absent from the initial selection, read that file once and continue.++**Per-page chart reference — `page_charts` section**:++Before drawing each page, look up its entry in `page_charts` to decide which chart structure applies (the SVG itself was loaded in §1):++- Entry present (e.g., `P09: timeline_horizontal`) → adapt the corresponding chart SVG already in context. Apply project colors/typography/density; do not copy verbatim. Use the selected §VII row and SVG; do not load the full chart catalog during execution.+- No entry for this page → either no chart on this page, or a chart that didn't match any catalog template (Strategist's `no-template-match` fallback). Design the visualization from scratch using `design_spec.md §VII` for guidance.+- Whole section absent → no chart pages in this deck.++---++## 2. Chart and Native-data Authoring++### 2.1 Chart Plot-Area Marker (MANDATORY on every chart page)++> The [`verify-charts`](../workflows/stages/verify-charts.md) stage enumerates chart pages from `design_spec.md §VII`, then reads each page's plot-area marker to feed `svg_position_calculator.py`. A missing marker invokes that stage's declared fallback and adds avoidable derivation work.++**Hard rule**: every SVG page that contains a data visualization chart includes a plot-area marker inside `<g id="chartArea">`, placed **after axis lines** and **before the first data element** (bar, line, area, point).++**Rectangular plot area** (bar / horizontal_bar / grouped_bar / stacked_bar / line / area / stacked_area / scatter / waterfall / pareto / butterfly):++```xml+<!-- chart-plot-area: x_min,y_min,x_max,y_max -->+```++**Radial charts** (pie / donut / radar):++```xml+<!-- chart-plot-area: pie | center: cx,cy | radius: r -->+<!-- chart-plot-area: donut | center: cx,cy | outer-radius: r1 | inner-radius: r2 -->+<!-- chart-plot-area: radar | center: cx,cy | radius: r -->+```++**How to determine coordinate values**:++| Value | Derivation |+|-------|------------|+| `x_min` | X coordinate of the Y-axis line (leftmost data boundary) |+| `y_min` | Y coordinate of the topmost grid line (highest data boundary) |+| `x_max` | X coordinate of the rightmost axis endpoint or grid line |+| `y_max` | Y coordinate of the X-axis baseline |+| `cx, cy` | Center point of pie/donut/radar (accounting for `transform="translate()"`) |+| `r` | Outer radius of the chart |++**Per-page verification** — after writing each chart SVG, confirm the marker exists:++```bash+grep "chart-plot-area" <project_path>/svg_output/<current_page>.svg+```++> Calculator-supported data-chart templates in `templates/charts/` include this+> marker as a reference. If a data chart covered by §2.1 lacks it, that is a+> bug. Conceptual diagrams, frameworks, and other non-data visualizations in+> the same library do not use a plot-area marker.+Technical SVG/PPT constraints remain in [`shared-standards-core.md`](./shared-standards-core.md).++### 2.2 PowerPoint-Native Chart/Table Replacement Marker (MANDATORY on eligible data-chart and text-grid table pages)++> `svg_to_pptx.py --native-charts-and-tables` replaces marked groups with PowerPoint-native Chart/Table objects (charts get an embedded Excel workbook). Markers stay dormant in the default export, whose SVG children become independently editable DrawingML shapes, but a deck without markers can never form data-backed native Chart/Table objects. Write the marker at draw time: the data is already in hand, and recovering it later costs a full re-read pass.++**Hard rule**: before deciding whether a chart or table is eligible for native replacement, load [`native-data-interface.md`](./native-data-interface.md). Every data chart whose type appears in that authority's **Supported chart types** list gets `data-pptx-replace-with="chart"` plus one `<metadata type="application/json">` JSON child on its top-level `<g>`, transcribing the same data just plotted. Every pure text-grid data table gets `data-pptx-replace-with="table"` the same way, transcribing all visible cell text into `columns` / `rows`. The parent marker determines the JSON schema; do not duplicate a chart/table kind on the metadata child.++Generated authoring MUST omit `data-pptx-import-source` and+`data-pptx-fallback-sha256`: those attributes record imported-PPTX provenance+and its sealed fallback baseline. Never copy a static baseline from a chart+catalog or reusable template; normal content edits would make it stale.++`data-pptx-replace-with` is a **data-backed replacement claim**, not a generic label for a group that contains numbers and not a marker for ordinary PowerPoint shapes or connectors. Add it only when the matching JSON payload can be written in the same edit; if the object is meant to remain SVG geometry, do not add the marker.++- Chart types absent from that list and conceptual/diagrammatic graphics (process flows, cycles, quadrant cards, timelines, KPI cards) get **no marker** — `svg_quality_checker.py` rejects unsupported marker types.+- Canonical rectangular merged text cells may carry a table marker by putting anchor-only `row_span` / `col_span` in metadata and leaving covered cells blank. Nonrectangular/overlapping merges, nonblank covered cells, and graphical cells (icons, harvey balls, rating dots) get **no table marker** and stay on the SVG fallback route.+- Transcribe, don't restyle: `categories` / `series[].values` are the numbers just plotted; `style.colors` carries the series HEX values already used on the page (from `spec_lock.colors`).+- Data-point color: when a single column/bar series uses data-point colors in the fallback, copy those fills into `series[].point_colors` in category order.+- Data labels: when visible point values are part of the fallback chart, write `data_labels` instead of companion text; use `data_labels.points` for selected labels, and use `number_format`, `font_size`, `font_family`, and per-point `colors` / `color` when the fallback labels carry suffixes or color-coded text.+- Line markers: when the fallback line chart draws visible point nodes, set `line_style: "lineMarker"`; leave the default `line` only for line charts without nodes.+- Area-under-line: when a combo plot is drawn as a filled area under a line, keep `type: "line"`, add `area_fill: true`, and copy the area transparency into `series[].fill_opacity`; copy visible line `stroke-width` into `series[].line_width` for line/area series.+- Native chrome: write `title`, `subtitle`, axis titles, or `show_legend: true` only when the fallback visibly renders the same chrome inside the native chart's replacement scope. `title` is the PowerPoint chart title, not an object name; use `name` for page-semantic object naming (e.g. `p03-revenue-chart`). Write explicit `x`/`y`/`width`/`height` read from the drawn plot area; omission is the fallback — the exporter then infers the frame from the drawn fallback geometry.+- Value-axis labels: when the fallback keeps category labels but intentionally omits numeric value-axis tick labels, set `show_value_axis_labels: false`.+- Freeform chart text: transcribe center labels, source notes, and other in-chart annotations as companion `caption` / `note` / `notes` entries with explicit slide-coordinate bounds; do not rely on fallback `<text>` children to survive native export.+- Native chart typography mirrors the SVG fallback. Copy the fallback's shared chart font into `style.font_family` and visible chart text sizes into the matching metadata fields (`title_font_size`, `subtitle_font_size`, `axis_font_size`, `note_font_size`, etc.) only when role sizes differ; otherwise let the exporter infer them from visible fallback text. When a visible chart title, subtitle, or axis title needs its own size/color/font, write that field as an object with `text`, `font_size`, `font_family`, and `color`. Use `axis_title_font_size`, `legend_font_size`, or companion per-entry `font_size` only when the fallback visibly uses a separate size.+- Native table typography mirrors the SVG fallback. Write `style.font_family` and `style.font_size` from the visible table text; use `header_font_size` or per-cell `font_size` only when the fallback visibly does so. If the fallback has no explicit table font, fall back to the deck body family and locked body size from `spec_lock.md typography`.+- The marker group's transform stays translate/scale only (no rotate / matrix / skew).+- Visual parity is not a goal: the SVG drawing remains the designed visual and exports as editable DrawingML shapes; the native object is the data-backed counterpart with PowerPoint's chart/table-specific model. Never simplify the SVG design to match what a native object could show.++**Per-page verification** — after writing each eligible data-chart or text-grid table page, confirm the marker exists:++```bash+grep "data-pptx-replace-with" <project_path>/svg_output/<current_page>.svg+```+++---++## 3. Visualization Reference++Chart SVGs referenced in **VII. Visualization Reference List** are loaded once through §1. This section governs adaptation only.++**Hard rule**: adapt the loaded chart SVG; do not improvise from memory and do not replicate verbatim. Apply project colors, typography, content; preserve visualization type.++**Adaptation rules**:+- **Preserve**: visualization type (bar/line/pie/timeline/process/framework…) as specified+- **Adapt**: data, labels, colors (project scheme), dimensions+- **Freely adjust**: composition, axis ranges, grid, legend, spacing, decoration — as long as the chart stays accurate and readable+- **Forbidden**: changing visualization type without spec justification; omitting data points or structural elements from the outline++> Templates: `templates/charts/`. The Strategist's selected key is already locked in `page_charts`; execution opens only that key's SVG.++### 3.1 Chart Coordinate Calibration++Coordinate calibration runs as a **conditional post-generation stage**, not inside the Executor authoring loop. After SVG generation completes, if the deck contains data charts, run [`verify-charts`](../workflows/stages/verify-charts.md) before post-processing.++The executor's only obligation here is upstream: embed the `<!-- chart-plot-area ... -->` marker on every chart page during initial draft (§2.1). Verify-charts enumerates chart pages from `design_spec.md §VII` (authoritative deck plan) and uses the marker to feed `svg_position_calculator.py`.++> Do NOT run `svg_position_calculator.py` during the initial draft. The calculator calibrates already-generated SVGs against their declared plot areas; running it before the SVG exists has nothing to compare against.diff --git a/skills/ppt-master/references/executor-image.md b/skills/ppt-master/references/executor-image.mdnew file mode 100644index 00000000..a2b78278--- /dev/null+++ b/skills/ppt-master/references/executor-image.md@@ -0,0 +1,32 @@+> See [`executor-base.md`](./executor-base.md) for the always-loaded Executor core.++# Executor Image Branch++Conditional Executor authority for image status handling, placement, crop behavior, formula images, and template-bundled images.++**Trigger**: load when `design_spec.md §VIII` or `spec_lock.md images` contains any image/formula row, or when a selected template carries bitmap assets.++## 1. Image Handling++Handle images by their status in the Design Spec's Image Resource List. Status enum and lifecycle: [`svg-image-embedding.md`](svg-image-embedding.md).++| Status | Source | Handling |+|--------|--------|----------|+| **Existing** | User-provided | Reference images directly from `../images/` directory |+| **Generated** | Generated by Image_Generator | Reference images directly from `../images/` directory |+| **Sourced** | Web-acquired by Image_Searcher | Reference from `../images/`. **Read [`image_sources.json`](image-searcher.md) to decide attribution** — load [`executor-web-image.md`](./executor-web-image.md). |+| **Rendered** | Deterministic formula PNG | Reference from `../images/`; use `preserveAspectRatio="xMidYMid meet"` |+| **Needs-Manual** | Acquisition failed and file is absent | Use dashed border placeholder unless the expected file exists; the Step 7 readiness gate swaps placeholders for real files before export |+| **Placeholder** | Not yet prepared | Use dashed border placeholder |++**Reference syntax**: see [`svg-image-embedding.md`](svg-image-embedding.md).++**Template-bundled images**: when a template (deck / layout / brand) is applied, its bitmaps are copied into the project's `images/` alongside every other runtime image ([`apply-template-workspace.md`](../workflows/stages/apply-template-workspace.md)). Reference them the same way — `../images/<name>` — and do **not** reproduce a template SVG's bare sibling href (e.g. `href="cover_bg.png"`): the template SVG is reference material, the rendered page lives in `svg_output/` and must point at `../images/`. `template_reuse_scope: mirror` ([`executor-structured.md`](./executor-structured.md) §1.1) is the one exception — it copies hrefs verbatim, and the exporter resolves those bare hrefs against `images/`.++Use each resource row's locked layout pattern; do not collapse image-led pages into a generic left/right split.++**Placeholder**: Dashed border `<rect stroke-dasharray="8,4" .../>` + description text++**`no-crop` images**: when a `spec_lock.md images` entry ends with ` | no-crop`, size the container to the image's native ratio (from `analyze_images.py` or file dims) and use `preserveAspectRatio="xMidYMid meet"`. Untagged entries are croppable — default to `slice`.++**Formula images — declared-inference fallback for a missing `no-crop` flag**: rows with `Acquire Via: formula` or `Type: Latex Formula` MUST be treated as no-crop. For a rendered file, use dimensions in this order: current `analysis/image_analysis.csv`, `design_spec.md §VIII`, then `images/formula_manifest.json`. For a `Needs-Manual` row, size the dashed placeholder from the planned dimensions in §VIII, then the manifest; the Step 7 readiness gate re-analyzes the supplied file and reconciles the container before export. Do not normalize all formulas to one height unless the spec explicitly states that layout choice.diff --git a/skills/ppt-master/references/executor-notes.md b/skills/ppt-master/references/executor-notes.mdnew file mode 100644index 00000000..ff252678--- /dev/null+++ b/skills/ppt-master/references/executor-notes.md@@ -0,0 +1,54 @@+> See [`executor-base.md`](./executor-base.md) for the always-loaded Executor core.++# Executor Speaker-notes Branch++Conditional late-stage authority for generating the complete speaker-notes document.++**Trigger**: load only after all SVG pages pass the final quality check.++## 1. Speaker Notes Generation Framework++### 1.1 Generate Complete Speaker Notes Document++After all SVG pages are finalized, enter Logic Construction Phase and write the full notes to `notes/total.md`. Batch-writing (not per-page) lets transitions plan coherently.++**Pure spoken narration**: notes are read aloud verbatim by `notes_to_audio.py` (TTS). Write only what should be spoken. No visible markers, no labeled meta-lines, no enumerated key-point lists, no duration annotations — anything you write outside the heading will be vocalized.++**Per-page structure**: `# <number>_<page_title>` heading (the `#` heading line is the only thing stripped before TTS), pages separated by `---`. Body is 2–5 natural sentences carrying the page's core message. Page-to-page transitions live inside the opening sentence as natural prose ("接下来……" / "Having framed X, let's turn to Y") — no bracketed `[过渡]` / `[Transition]` tags.++**Reading-mode note burden**:++| `consumption_mode` | Notes emphasis |+|---|---|+| `text` | Add interpretation or transition without reading the already self-contained page aloud. |+| `balanced` | Connect the visible claim and evidence, explain the trade-off, and bridge to the next page. |+| `presentation` | Carry the reasoning, context, and supporting detail intentionally omitted from the sparse projected surface. |++**Concrete examples** — same shape applies to any language; just write naturally in that language.++中文 deck:++```+# 02_市场格局++在明确了行业背景之后,我们来看具体的市场格局。当前线上零售集中度持续上升,前三大平台合计份额已经达到百分之六十八,腰部玩家正在被快速挤压,留给新进入者的窗口期不超过十八个月。这意味着我们的策略必须聚焦,而不是铺开。+```++英文 deck:++```+# 02_market_landscape++Having framed the industry backdrop, let's look at the actual market landscape. Online retail concentration keeps rising — the top three platforms now hold sixty-eight percent of combined share, mid-tier players are being squeezed fast, and the window for new entrants is under eighteen months. This means our strategy has to focus, not spread.+```++> 日本語 / 한국어 / 其他语言:照搬同样的结构,用对应语言自然书写即可。++**Number readability**: TTS reads digits and symbols literally. Prefer fully-spelled forms in the language being spoken when literal pronunciation would be awkward (e.g. Chinese "百分之六十八" reads better than "68%"; "1-2分钟" reads as "一减二分钟"). Plain integers and percentages in English are fine as-is.++**Common mistakes to avoid**:+- Leaving any bracketed stage marker (`[过渡]` / `[Transition]` / `[Pause]` / `[Data]` / `[Scan Room]` / `[Interactive]` / `[Benchmark]` etc.) in the text — they will be read aloud literally.+- Adding `要点:① …` / `Key points: (1) …` / `时长:2分钟` / `Duration: 2 minutes` / `Flex: …` lines — TTS will speak "要点 一 …".+- Mixing languages within one deck's notes.++After `notes/total.md` is complete, return to Generate Step 7.1. The route authority owns the serial split command and its success criterion.diff --git a/skills/ppt-master/references/executor-structured.md b/skills/ppt-master/references/executor-structured.mdnew file mode 100644index 00000000..996df8fc--- /dev/null+++ b/skills/ppt-master/references/executor-structured.md@@ -0,0 +1,180 @@+> See [`executor-base.md`](./executor-base.md) for the always-loaded Executor core and [`pptx-structure-interface.md`](./pptx-structure-interface.md) for the SVG metadata contract.++# Executor Structured Template Branch++Conditional Executor authority for `template_reuse_scope: mirror|layout` with `pptx_structure.mode: structured`.++**Trigger**: load only when the lock selects structured template reuse.++## 1. Template Reuse Rules++### 1.0 Pre-generation Template Read++**Hard rule**: Read the compact template roster once, but never treat a summary as the full page prototype.++| Source list | Read path |+|---|---|+| Chosen template's `design_spec.md` (template capabilities) | `templates/design_spec.md` |+| Model-readable execution roster, when present | `templates/template_execution_manifest.json` |+| Selected mirror prototype's text-slot sidecar | The roster entry's `text_slots_path` under `templates/` |++When `template_execution_manifest.json` and the selected entry's `text_slots_path` exist, read the compact roster once for selection/orientation and the sidecar before authoring each mirror page; then read the selected complete `templates/<basename>.svg`, which remains the visual/structural authority. Layout reuse reads the selected complete SVG but does not need the mirror-only sidecar. When the manifest, selected entry, or sidecar is unavailable, batch-read every distinct `<basename>` in `spec_lock.md page_layouts` before page 1. On mirror, preserve text topology directly from the complete SVG under §1.1; missing derived metadata alone does not invalidate the workspace.++`spec_lock.md` is the only route-wide artifact that must be re-read for every page. Keep the current `design_spec.md §IX` page brief in immediate context, re-reading that brief after context compaction as required by [`executor-base.md`](./executor-base.md) §2.1.++**Exception**: user mid-deck adds pages or swaps templates introducing a basename absent from the original roster/batch → read the new file once, continue.++> The execution manifest reduces roster/context load; it never authorizes writing from selectors alone. The selected full SVG must be open before editing that page.++Resolve the per-page template SVG via `spec_lock.md page_layouts` (authoritative). There is no filename/page-type fallback.++**Resolution order (per page):**++1. `template_reuse_scope: mirror` → see §1.1. The installed workspace must support `replication_mode: mirror`.+2. `template_reuse_scope: layout` → resolve `P<NN>: <basename>` from `page_layouts`, retain the structure system, and apply the non-mirror skin/reflow rules below.+3. `mirror` / `layout` with no current-page `page_layouts` row → stop; adaptive mode still requires one selected input prototype.++> Note: `page_layouts` disambiguates the multiple content variants a template may ship; missing mappings are contract errors.++**Templates supply structure, not skin (`layout` scope)**: a chart or layout template's gradients, drop-shadows, palette, **and font sizes** are placeholder. Inherit its geometry, label / legend placement, and series-encoding logic; re-skin every fill / stroke to the deck's `visual_style` + `spec_lock.colors` — flat styles strip the gradients and shadows, gradient / glass styles repaint their own. Forbidden — shipping a template's default `<linearGradient>` / `cardShadow` / Tailwind fills unchanged. `mirror` scope is the exception: §1.1 preserves visuals verbatim.++**Font size is skin, not geometry (non-mirror).** A chart / layout template's hardcoded `font-size` values (often 11–16px, sized for the template's own dense placeholder text) are NOT inherited — classify each text into its `spec_lock.md` role and use that role's locked size, exactly as you re-skin color. **Structural roles (page title / body / subtitle / annotation / footnote) hold their one deck-wide size on every page** — the template's placeholder px never overrides it; same-role text drifting page to page is what makes a deck look unprofessional.++**Typography execution order (mandatory):**++1. Build a per-page text inventory from `design_spec.md §IX` + the current `notes/<NN>_*.md`.+2. Classify each text item before drawing. **Structural roles** (`title`, `subtitle` / `lead`, `body`, `annotation`, `footnote` / `page_number`) must map to their declared `spec_lock.typography` slot. A **one-off feature element** (a single hero number, an isolated emphasis label) may take an in-ramp intermediate value — the ramp is anchored on `body`, not a closed menu — but a feature size that **recurs** must be promoted to a declared slot. The failure mode this guards against is structural text silently inheriting the template's compact px, not legitimate feature sizing.+3. Copy the role's locked px value into `font-size` verbatim. Do this before placing the text; never start from a template `font-size` and then "adjust".+4. Layout from those locked sizes: compute line-height, wrapped line count, child `y` / `dy`, card padding, card height, column gaps, and available image/chart area from the chosen px values.+5. Only after this reflow may you inspect fit. If fit fails, move / resize containers or simplify local geometry first; do not reduce the role size merely because the inherited template slot was smaller.++**Geometry adapts to the type, never the reverse**: when the locked size is larger than the template's placeholder text, widen or heighten the card, open spacing, and recompute child `y` / `dy`; do not shrink text to inherit a smaller container. Recompute line-height and downstream coordinates, and allocate wrapped-line height plus padding. Page count and density remain the confirmed Strategist decision: do not repaginate, split, or drop content. If a fully reflowed block still fails, apply the single bounded body-fit exception in [`executor-base.md`](./executor-base.md) §2.1. Mirror instead preserves source typography under §1.1.++### 1.1 Mirror reuse — literal page replacement++When `spec_lock.md` confirms `template_reuse_scope: mirror`, Executor switches to a literal replacement path. The workspace capability `replication_mode: mirror` is a prerequisite, not the trigger by itself:++1. **Per-page reference selection** — Strategist selects one mirror page per project page via `spec_lock.md page_layouts` (e.g., `P04: 015_content`). The basename is the mirror filename without extension; Strategist made this choice by reading `design_spec.md §V Page Roster` descriptions, not by guessing.+2. **Copy, don't fill** — open the referenced full mirror SVG immediately before authoring the page. Copy it as the starting point, then edit slide-specific text in place. Preserve every non-text element and every `data-pptx-*` structure attribute verbatim.+3. **What you may edit** — only the visible string values already carried by `<text>` and `<tspan>` nodes that express slide-specific content (title, body, captions, KPI labels, dates, page numbers). Keep the number, order, nesting relationship, and **all attributes** of every `<text>` / `<tspan>` node unchanged. Never merge or split nodes, move a string between nodes, add a new tspan, or delete an empty carrier. The selected `text_slots_path` sidecar exposes the expected selectors/counts/hashes, but the complete SVG remains authoritative.+4. **What you must not touch** — element positions, sizes, fonts, colors, fills, strokes, gradients, **which image each `<image>` points at**, `<g>` grouping, sprite-sheet `<svg viewBox>` wrappers, decorative `<rect>` / `<path>` / `<circle>` / `<polygon>` shapes, `<use data-icon="...">` markers, embedded chart data structures. Mirror's value is preserving the source deck's visual identity — any geometric / decorative drift defeats the purpose. **The `href` path is not the image**: normalizing a bare `href="cover_bg.png"` to `href="../images/<name>"` (when Step 3 relocated the asset to `images/`) points at the *same* image and changes nothing visual — that is an allowed path fix, not a fidelity edit. Leaving the bare href as-is is also fine; the exporter and live preview resolve bare hrefs against `images/` either way.+5. **Content fit** — if the replacement needs a different number of text segments/items, do not merge/split nodes, drop sourced content, or restructure the grid. Select a better mirror prototype and update the planning mappings, or report `warning: P<NN> content does not fit mirror reference <basename>; choose another prototype or change template_reuse_scope to layout/style`.+6. **Visible text editing** — mirror SVGs may keep literal source text rather than `{{...}}` authoring markers. Edit values in place while retaining imported semantic `data-pptx-placeholder` identity and exact text topology.+7. **Output filename** — follow the standard project SVG naming convention (`<NN>_<page_name>.svg` where `<NN>` matches the project page index, not the mirror source index). The mirror filename is the *reference*, not the *output*.++**Detecting mirror mode**: read `template_reuse_scope` from `spec_lock.md` before every page. `replication_mode: mirror` in the installed template only determines whether that confirmed scope is legal; it must never force mirror behavior when the confirmed scope is `layout` or `style`.++**Mirror + chart pages**: chart structures inside a mirror SVG are already drawn (axis, series, labels). Treat them as visual references — replace the data labels and series text content to match the project's chart spec, but do not redraw the chart from a `templates/charts/<name>.svg` baseline. A mirror template's `page_charts` entries are normally absent for this reason.++**Legacy template boundary**: A template with missing root Master identity, direct atomic placeholders, `data-pptx-layout-kind`, unmapped `baseline`, `preserve`, or `layout_strategy: distill` is not a fallback input. Stop and create a new current workspace through [`create-template`](../workflows/create-template.md) before generation.++### Page-Template Mapping Declaration (Required Output)++Before generating each page, output which template is used:++```+📝 **Template mapping**: `templates/03a_content_image_text.svg` (free-design routes may use "None")+🎯 **Adherence rules / layout strategy**: [specific description]+```++- **Content pages**: template defines only header/footer; content area is free+- **No template**: allowed only on free-design or brand-only routes++### 1.2 PowerPoint Master / Layout Mapping++This section applies only when a deck/layout template is confirmed with `template_reuse_scope: mirror|layout`. `page_layouts` selects the input SVG prototype, `pptx_masters` / `pptx_layouts` declare unique reusable output definitions, and `page_pptx_layouts` assigns every generated page before the first page is drawn. `template_reuse_scope: style`, free-design, and brand-only routes use `pptx_structure.mode: flat`, omit all four sections, skip the rest of §1.2, and keep every SVG object Slide-local.++**Hard rule — reuse-scope route**: `template_reuse_scope: mirror|layout` requires `pptx_structure.mode: structured`. `template_reuse_scope: style` requires `mode: flat` even though a template supplied its visual vocabulary. Missing mode or legacy values (`baseline`, `template`, `preserve`), `layout_strategy`, Layout-kind fields, partial mappings, and old direct placeholders stop generation. Create a new template workspace through [`create-template`](../workflows/create-template.md); do not upgrade the active SVG project in place.++**Hard rule — root identity**: A `page_pptx_layouts` row binds the page to one key in `pptx_layouts`; that unique definition supplies its Master key, Layout picker name, and prototype source. Put the declared Master key/name and Layout key/name on the root SVG. A Layout key belongs to exactly one Master and remains globally unique.++**Hard rule — atomic fixed layers**: Every `data-pptx-layer="master|layout"` visual is one direct root semantic atom that compiles to one DrawingML object. An ordinary marked `<g>` is forbidden; one validated compact authored-preset `<g>` emitted by `preset_shape_svg.py` is the sole group exception because it compiles to one native shape. When reconstructing source PPTX groups, recursively push supported transforms, paint, opacity, and z-order into atomic children. Repeat the identical ordered Master atom contract on every page using that Master and the identical ordered Layout atom contract on every page sharing that `(master, layout)` pair.++**Hard rule — PowerPoint paint order**: Direct children appear in this order: Master background atoms, Layout background atoms, optional Slide background, remaining Master atoms, remaining Layout atoms, then slot groups and Slide-local content groups. Backgrounds are the inheritance plane beneath all shapes.++**Mandatory — slot authoring**: A reusable content slot is one direct root `<g id>` carrying `data-pptx-placeholder` and positive `data-pptx-placeholder-bounds`. A normal slot contains exactly one compatible direct drawable child marked `data-pptx-placeholder-carrier="true"`. Export unwraps that child into the real Slide placeholder binding. Decorations do not belong in the slot; move reusable decoration to a root Layout atom and keep page-specific labels/captions in another slot or Slide-local group.++**Mandatory — slot identity**: Preserve imported `data-pptx-placeholder-idx` values where available; otherwise omit the title index and assign unique indices only where repeated roles need disambiguation. Pages sharing one Layout key repeat the same slot ids/types/effective indices/default bounds/binding modes. Current text, crop, and Slide-local carrier geometry may differ.++**Composite proxy fallback**: A genuinely composite region may use a direct `<g data-pptx-placeholder="object" data-pptx-placeholder-binding="proxy">` with positive bounds. Its visible group remains Slide-local and export creates one hidden transparent matching placeholder proxy. This downgrade is valid only for `object`; do not use it for an ordinary title, body, picture, chart, table, or media slot.++**Forbidden — dummy carriers**: Never satisfy a carrier slot with tiny text, near-transparent glyphs, background-colored punctuation, or other fake content. Leave an intentionally blank text carrier empty/whitespace-only—the exporter emits a legal invisible U+200B run—or use the composite `object` proxy contract. If `strict` prototype binding cannot represent the completed composition, surface the mismatch; select a compatible prototype or create an explicit adaptive Layout instead of hiding the conflict.++**Zero-slot Layout**: A Layout may have no slot groups. Covers, posters, and fixed visual pages still declare their named Master/Layout and fixed atoms. Do not manufacture a full-page `object` slot or empty `utility` identity.++**Mandatory — per-page slot coverage**: On every mapped page, declare a slot for each standard role the page actually has: the page heading as `title`, a cover tagline as `subtitle`, the page number as `slide-number`, running footer text as `footer`, a hero / content image as `picture`, and a body block already authored as one merged text frame as `body`. A page shipping zero slots exports a Layout with no insertable placeholders — valid only for a genuinely fixed composition (see Zero-slot Layout above), never as the deck-wide default. Pages sharing one layout key ship the same slot set.++**Hard rule — variable slot content**: “Per-page headings never stay Slide-local by default” means authoring them as `title` / `subtitle` slots; it never permits page-varying text or images to become fixed Layout atoms. Any such value that varies across pages sharing one Layout key MUST be carried by a slot or remain Slide-local.++**Mandatory — master/layout layer coverage**: On every mapped page, mark the deck-wide background and every-page chrome (footer bar, running logo) `data-pptx-layer="master"`, and mark the static framing that defines this layout key's composition (header rule, divider band, zone panels — including chrome repeated on every content page but absent from the cover) `data-pptx-layer="layout"`. A mapped page with zero `data-pptx-layer` marks exports a bare Master and an empty Layout — the layer marks, not the slide content, give each Layout its visible design.++**Layout identity**: Different keys differ in fixed Layout atoms or slot topology/default bounds/binding modes. Identical contracts should share one key. Current wording, imagery, crop, and Slide-local geometry never define identity.++**Template adherence**: Strict copies the prototype Master/Layout/slot contract exactly. Adaptive keeps the prototype Master and may change reusable Layout atoms or slots only under a new explicit Layout key/name. When the completed composition genuinely needs that change, update `spec_lock.md pptx_layouts` immediately while authoring the first affected page; later pages may reuse the new key only by repeating its exact contract. Changing only a label is not a new Layout.++**Layout-content boundary**: Mark only genuinely reusable fixed framing as a Master/Layout atom. Concrete titles, body copy, metrics, chart marks, images, and page-specific groups remain inside slot groups or ordinary Slide-local content groups. The exporter never infers or clusters structure.++**Background ownership**:++| Scope | SVG authoring |+|---|---|+| Deck-wide default | Direct full-canvas solid `<rect data-pptx-layer="master">` repeated identically on every page |+| Page-type default | Direct full-canvas solid `<rect data-pptx-layer="layout">` repeated on every page sharing that layout key |+| One-page exception | Direct full-canvas solid `<rect data-pptx-layer="slide">` |++The exporter writes these solid fills as real Master/Layout/Slide `p:bg`, not selectable full-canvas shapes. In structured mode, gradients, preset patterns, images, textures, and overlay panels remain explicit shapes or pictures; the generic background-promotion rule outside structured mode does not expand this ownership contract.++---++## 2. Per-page Structured Lookup++**Per-page template lookup — `page_layouts` section (`mirror` / `layout` only)**:++Before drawing each page, look up its entry in `page_layouts` to decide which basename to inherit (the full prototype was loaded in §1.0):++- Entry present (e.g., `P04: 03a_content_image_text`) → inherit the corresponding full SVG. The basename **must match** an actual file in the chosen template directory. If it does not, stop before drawing and report the invalid mapping; neither `strict` nor `adaptive` may fall back to free design inside a structured template deck.+- No entry for this page with `template_reuse_scope: mirror|layout` → stop before drawing and report the missing Strategist mapping. Adaptive mode still requires one selected complete template SVG; flexibility applies to the post-design output Layout, not to whether an input prototype exists.+- Whole section absent while `template_reuse_scope: mirror|layout` is present → stop before drawing; the current template contract is incomplete.+- `template_reuse_scope: style` → the whole section must be absent; do not perform per-page prototype lookup.++Do **not** invent a prototype entry, and do **not** assume a structured template just because `templates/` exists. For `mirror` / `layout`, a missing or invalid `page_layouts` row is an upstream contract error. `style` is a separate flat deck route, never a per-page fallback.++**Per-page PowerPoint layout lookup — `template_reuse_scope: mirror|layout` only**:++- When `pptx_structure.mode` is `flat` (including `template_reuse_scope: style`), skip this lookup and the structured scaffold below. `pptx_masters`, `pptx_layouts`, `page_layouts`, and the corresponding SVG metadata must all be absent; each root still declares its canonical `data-pptx-page-role`.+- With `template_reuse_scope: mirror|layout`, `pptx_structure.mode` must equal `structured`; any other or missing value is rejected. Do not migrate an invalid structured contract in place: create a new current-contract workspace through Create Template before generation resumes.+- Read the current page assignment as `P<NN>: <layout_key>`. Resolve the assigned Layout key in `pptx_layouts`, then resolve its Master key in `pptx_masters`. Missing, malformed, or partial mappings stop before drawing.+- Write matching root Master/Layout key and picker names. Do not write `data-pptx-layout-kind` or `data-pptx-page-role`.+- On strict template use, the row and SVG contract match the selected prototype exactly.+- On adaptive template use, retain the prototype Master. If the final composition changes fixed Layout atoms or slot topology/bounds, allocate a new key/name and update this row before completing the page.+- A Layout key may repeat across non-adjacent pages only when its fixed atoms and slot contracts are identical.++**Structured template-page scaffold**:++```xml+<svg viewBox="…"+ data-pptx-master="<master-key>" data-pptx-master-name="<master-name>"+ data-pptx-layout="<layout-key>" data-pptx-layout-name="<layout-name>">+ <rect id="master-bg" data-pptx-layer="master" …/> <!-- one atomic Master object -->+ <text id="master-footer" data-pptx-layer="master" …>…</text> <!-- no Master/Layout g -->+ <path id="layout-rule" data-pptx-layer="layout" …/> <!-- one atomic Layout object -->+ <g id="title-slot" data-pptx-placeholder="title"+ data-pptx-placeholder-bounds="60 36 1160 64">+ <text id="title-carrier" data-pptx-placeholder-carrier="true" …>…</text>+ </g>+ <g id="body-slot" data-pptx-placeholder="body"+ data-pptx-placeholder-idx="1"+ data-pptx-placeholder-bounds="60 120 470 500">+ <text id="body-carrier" data-pptx-placeholder-carrier="true" …>…</text>+ </g>+ <g id="picture-slot" data-pptx-placeholder="picture"+ data-pptx-placeholder-idx="2"+ data-pptx-placeholder-bounds="570 120 650 500">+ <image id="picture-carrier" data-pptx-placeholder-carrier="true" …/>+ </g>+ <g id="content-block-1">…</g> <!-- 3–8 content groups -->+ <g id="content-block-2">…</g>+</svg>+```++On structured template pages, Master/Layout atoms and slot groups are direct root children and precede ordinary content groups. Structural metadata nested inside an ordinary content group fails export. Flat pages use ordinary top-level semantic groups only.diff --git a/skills/ppt-master/references/executor-web-image.md b/skills/ppt-master/references/executor-web-image.mdnew file mode 100644index 00000000..e9f580e8--- /dev/null+++ b/skills/ppt-master/references/executor-web-image.md@@ -0,0 +1,25 @@+> Load after [`executor-image.md`](./executor-image.md).++# Executor Web-image Attribution Branch++Conditional Executor authority for inline attribution on web-sourced images.++**Trigger**: load when at least one placed image has `Status: Sourced`.++## 1. Inline Attribution for Sourced Images++Whenever the slide uses an image with `Status: Sourced`, look up the corresponding entry in `project/images/image_sources.json` and act on `license_tier`:++| `license_tier` | Action on this slide |+|---|---|+| `no-attribution` | Embed the `<image>` element only. **No credit element needed.** |+| `attribution-required` | Embed the `<image>` element **plus** a small inline `<text>` credit element per the visual spec in [image-searcher.md §7](./image-searcher.md). |+| `manual` | Embed the `<image>` element only. **No credit element** — a user-supplied `--from-url` replacement; verifying usage rights / any required credit is the user's responsibility. |++The credit text is **not** rendered by post-processing or export — it must be present in the SVG you produce. The shape of the credit element (size, position, color, multi-image source line, hero gradient overlay) is specified in [image-searcher.md §7](./image-searcher.md). Do not invent a different style.++Use `attribution_text` from the manifest entry as the **starting point**, then compress for the small-text constraint (drop URL, drop filename, keep "via Provider / License"). For CC0/PD images that landed in the `attribution-required` tier only because of upstream metadata quirks (rare), credits are still safe to render.++`svg_quality_checker.py` treats missing CC BY / CC BY-SA inline attribution as an **error**. Fix the offending SVG before post-processing.++**The manifest is the single source of truth for credits.** Do not duplicate license info into speaker notes or any other artifact.diff --git a/skills/ppt-master/references/image-base.md b/skills/ppt-master/references/image-base.mdindex dd9656f6..24f355cd 100644--- a/skills/ppt-master/references/image-base.md+++ b/skills/ppt-master/references/image-base.md@@ -99,7 +99,7 @@ License / attribution data lives **only** in `project/images/image_sources.json`- SVG `<title>` / `<desc>` (stripped by `svg_to_pptx.py`)- A separate "Image Credits" appendix slide (lost on single-page sharing)-Executor reads the manifest per slide and renders inline credits when needed — see [`executor-base.md`](./executor-base.md) §6.1 and [`image-searcher.md`](./image-searcher.md) §7.+Executor reads the manifest per slide and renders inline credits when needed — see [`executor-web-image.md`](./executor-web-image.md) §1 and [`image-searcher.md`](./image-searcher.md) §7.---diff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.mdindex c32b9004..692f96a3 100644--- a/skills/ppt-master/references/image-generator.md+++ b/skills/ppt-master/references/image-generator.md@@ -276,7 +276,7 @@ Use that deliberately. On a wide sheet (`16:9`, `21:9`, `4:1`, `8:1`), `1xN` makIf one deck needs mixed shapes, create separate sheets per shape family unless one carefully designed grid gives every element enough room. Keep the visual family consistent through the same `deck_rendering` and `color_scheme`, not by forcing all cells into one square sheet.-**Resource contract — the sheet and its elements are different row kinds.** A sliced element can only be placed if it exists as a resource the Executor is allowed to reference (`spec_lock.md images`). So §VIII carries two row kinds (full rules: [`design_spec_reference.md`](../templates/design_spec_reference.md) §VIII):+**Resource contract — the sheet and its elements are different row kinds.** A sliced element can only be placed if it exists as a resource the Executor is allowed to reference (`spec_lock.md images`). So §VIII carries two row kinds (planning authority: [`strategist-image.md`](./strategist-image.md)):- **Sheet row** — `Acquire Via: ai`, `Type: Illustration Sheet`, the intent prompt, named as the slice source with its intended cell shape and placement purpose (`Reference: landscape footer-vignette spot set`). It is generated in Step 5 but **never placed on a slide** — keep it **out of** `spec_lock.md images`. Image_Generator resolves the exact `aspect_ratio`, grid, and slice command from this intent.- **Element rows** — one per used element, `Acquire Via: slice`, filename matching a `--names` output, `Reference` naming the parent sheet + cell/element. These **are** placed — list every one in `spec_lock.md images`, usually with ` | no-crop` (a tight-trimmed transparent spot should be fit, not cover-cropped). Their dimensions are filled in after slicing (Step 5 re-runs `analyze_images.py`). **Set each element row's Layout pattern from the decorative-cutout family, never a boxed container** — see Placement below.@@ -296,7 +296,7 @@ python3 scripts/slice_images.py <project>/images/illus_sheet.png --grid 2x3 \2. **Clean grid, or it cuts ugly.** The model will not place every element perfectly; force a clear grid with gutters, and generate **a few sheets** (re-roll the same prompt) to pick the cleanest-laid-out one before slicing. State the exact row/column structure and cell shape so the model does not invent a square matrix. `--trim` absorbs the rest.3. **Generate only as large as needed.** Each cell is a fraction of the sheet. Pick the smallest sheet size that keeps each sliced cell at least **1.5-2x** the intended display size. `1K` is usually enough for small 80-160px decorative spots; use `2K` for medium 180-320px placements; reserve `4K` for large, cropped, or potentially enlarged elements.-**Placement — these are decorative accessories, not boxed pictures.** A transparent spot wasted in a centered rectangle looks cheaper than no spot at all. Each element row's Layout pattern comes from the decorative-cutout family in [`image-layout-patterns.md`](./image-layout-patterns.md): `#63` sticker/cutout, `#4` bleed off the canvas edge, `#58` corner fragment, `#66` fade into the background, `#69` slight editorial rotation, `#49` asymmetric cluster. Push spots to the margins, let them run off-edge or sit behind/beside text, vary size and angle across pages, and overlap the content rather than reserving a tidy tile for them. Anchor most pages on one primary element and let the rest stay small ([primary-per-page](./strategist.md) §h) — scattered same-weight tiles are exactly the generic look to avoid.+**Placement — these are decorative accessories, not boxed pictures.** A transparent spot wasted in a centered rectangle looks cheaper than no spot at all. Each element row's Layout pattern comes from the decorative-cutout family in [`image-layout-patterns.md`](./image-layout-patterns.md): `#63` sticker/cutout, `#4` bleed off the canvas edge, `#58` corner fragment, `#66` fade into the background, `#69` slight editorial rotation, `#49` asymmetric cluster. Push spots to the margins, let them run off-edge or sit behind/beside text, vary size and angle across pages, and overlap the content rather than reserving a tidy tile for them. Anchor most pages on one primary element and let the rest stay small ([primary-per-page](./strategist-image.md)) — scattered same-weight tiles are exactly the generic look to avoid.**Through-line — one family, many roles.** A spot sheet pays off more when the same motif family also drives the cover and section dividers. A large cover / divider anchor is not a giant sheet cell—generate it as its own `hero_page` image sharing the sheet's `deck_rendering`, `color_scheme`, and subject world. Plan this only when the deck leans into illustration, never as a quota.diff --git a/skills/ppt-master/references/image-layout-patterns.md b/skills/ppt-master/references/image-layout-patterns.mdindex 021cf2ac..b3c94de0 100644--- a/skills/ppt-master/references/image-layout-patterns.md+++ b/skills/ppt-master/references/image-layout-patterns.md@@ -148,7 +148,7 @@ Stack any of these freely on top of a Primary structure. Multiple Modifiers per24. **Custom path crop (blob, arrow, leaf, silhouette)** — `<clipPath><path d="…"/></clipPath>`; allows any curved or organic shape. PowerPoint export translates this to `custGeom` and survives roundtrip.-25. **Layered paper-cut stack** — clip each image layer under the image-only contract in [`shared-standards.md`](shared-standards.md) §1.2; draw vector layers directly in their final geometry. A small conditional shadow on each layer can create physical separation.+25. **Layered paper-cut stack** — clip each image layer under the image-only contract in [`shared-standards-core.md`](./shared-standards-core.md) §1.2; draw vector layers directly in their final geometry. A small conditional shadow on each layer can create physical separation.26. **Triptych baked into a single wide image** — one wide `<image width=1160 height=334>` whose internal composition already contains 2–3 scenes. Generate the triptych as one image (not three separate calls) when scene-to-scene consistency matters — the model preserves character identity, lighting continuity, and color grading far more reliably when panels are produced together.@@ -204,7 +204,7 @@ Stack any of these freely on top of a Primary structure. Multiple Modifiers per67. **Image with knock-out / cut-out shape** — overlay a shape filled with the background color or another image, creating the impression of a hole punched through the underlying image.-68. **Text-as-mask over image** — letterforms revealing image through them. Under the canonical SVG compatibility boundary in [`shared-standards.md`](shared-standards.md), realize this pattern as a pre-rendered image rather than a runtime effect. Prompt for "large lettering revealing the underlying scene through letterforms" and treat the result as a fixed artistic choice.+68. **Text-as-mask over image** — letterforms revealing image through them. Under the canonical SVG compatibility boundary in [`shared-standards-core.md`](./shared-standards-core.md), realize this pattern as a pre-rendered image rather than a runtime effect. Prompt for "large lettering revealing the underlying scene through letterforms" and treat the result as a fixed artistic choice.69. **Image rotated at a slight angle for editorial feel** — `transform="rotate(angle cx cy)"` on the `<image>` or its container `<g>`; 2–6 degrees typical. Adds dynamism without breaking layout.@@ -252,8 +252,8 @@ Combine freely. The "AI-default" failure mode is the opposite: defaulting to bar## Hard Constraints- Long body copy, data points, numeric labels, and Chinese text always go in the SVG layer — never baked into the image.-- All project-wide SVG compatibility exceptions and conditional mappings are- owned by [`shared-standards.md`](shared-standards.md). This catalog neither+- Project-wide SVG compatibility rules start at [`shared-standards-core.md`](./shared-standards-core.md),+ whose routing table names each conditional owner. This catalog neitherrestates nor relaxes that contract; each pattern records only itsscenario-specific rendering choice.diff --git a/skills/ppt-master/references/image-layout-spec.md b/skills/ppt-master/references/image-layout-spec.mdindex 723135b0..a72d49bc 100644--- a/skills/ppt-master/references/image-layout-spec.md+++ b/skills/ppt-master/references/image-layout-spec.md@@ -1,4 +1,4 @@-> See shared-standards.md for common technical constraints.+> See [`shared-standards-core.md`](./shared-standards-core.md) for common technical constraints.# Image Layout Specification@@ -6,14 +6,14 @@ Layout rules for pages where the image is placed **side-by-side with body text****Core principle (side-by-side)**: compute container layout from the image's original aspect ratio so the image displays completely — no excess whitespace, no cropping.-> **Scope**: this spec applies to *side-by-side* intent only. Other intents (hero / full-bleed, atmosphere / background, accent / inline) use full-bleed placement where ratio alignment is not a constraint and cropping is expected — the ratio→split table below does NOT apply. See `references/strategist.md` §h for intent selection.+> **Scope**: this spec applies to *side-by-side* intent only. Other intents (hero / full-bleed, atmosphere / background, accent / inline) use full-bleed placement where ratio alignment is not a constraint and cropping is expected — the ratio→split table below does NOT apply. See `references/strategist-image.md` for intent selection.---## Layout Decision Flow```-1. Decide narrative intent (hero / atmosphere / side-by-side / accent) — see strategist.md §h+1. Decide narrative intent (hero / atmosphere / side-by-side / accent) — see strategist-image.md2. If intent = side-by-side: continue below. Otherwise: compose per narrative; this spec does not apply.3. Get image original dimensions → Calculate ratio (width/height)4. Select layout type based on ratiodiff --git a/skills/ppt-master/references/image-renderings/_index.md b/skills/ppt-master/references/image-renderings/_index.mdindex e08ac87c..7906c91b 100644--- a/skills/ppt-master/references/image-renderings/_index.md+++ b/skills/ppt-master/references/image-renderings/_index.md@@ -77,7 +77,7 @@ When no preset carries the deck's temperament, set `image_rendering: custom` and- image_rendering_behavior: "Hand-screened poster aesthetic — slightly misregistered halftone overlays, 3 flat ink colors with visible dot pattern at 12% opacity, no gradients, no anti-aliased edges; reads as silkscreen print."```-**Hard rule**: `custom` is a tail-case, not a default. See [`strategist.md`](../strategist.md) h.5 for the one-`custom`-per-dimension limit.+**Hard rule**: `custom` is a tail-case, not a default. See [`strategist-image.md`](../strategist-image.md) for the one-`custom`-per-dimension limit.---diff --git a/skills/ppt-master/references/image-searcher.md b/skills/ppt-master/references/image-searcher.mdindex 5de01a4a..55fcc9ba 100644--- a/skills/ppt-master/references/image-searcher.md+++ b/skills/ppt-master/references/image-searcher.md@@ -1,4 +1,4 @@-> See [`image-base.md`](./image-base.md) for the common framework. Technical SVG/PPT constraints are in [`shared-standards.md`](./shared-standards.md).+> See [`image-base.md`](./image-base.md) for the common framework. Technical SVG/PPT constraints are in [`shared-standards-core.md`](./shared-standards-core.md).# Image_Searcher Reference Manual@@ -196,7 +196,7 @@ Never treat a generic `required_terms` pass as acceptance. For example, matching```bashpython3 scripts/image_search.py --from-url <image-url> --filename <name>.jpg -o <project_path>/images```- Recorded with `license_tier: manual` — verifying usage rights is the user's call. Human replacement is a legitimate outcome, not a failure. It updates the image and `image_sources.json` but does **not** rewrite `image_queries.json`, so a row fixed this way may still read `Needs-Manual` in the batch manifest — harmless: the file is present, so export proceeds (executor-base §6.1);+ Recorded with `license_tier: manual` — verifying usage rights is the user's call. Human replacement is a legitimate outcome, not a failure. It updates the image and `image_sources.json` but does **not** rewrite `image_queries.json`, so a row fixed this way may still read `Needs-Manual` in the batch manifest — harmless: the file is present, so export proceeds ([`executor-web-image.md`](./executor-web-image.md) §1);3. (opt-in) `--save-candidates` to pull auto-alternatives with their own `source_page_url`s, then `--promote` the best (below);4. if nothing fits, mark the row `Needs-Manual`.diff --git a/skills/ppt-master/references/modes/briefing.md b/skills/ppt-master/references/modes/briefing.mdindex bb46a813..04c2252c 100644--- a/skills/ppt-master/references/modes/briefing.md+++ b/skills/ppt-master/references/modes/briefing.md@@ -30,7 +30,7 @@ Neutral information delivery. Lay the facts out plainly and completely, organize## 3. Speaker-notes register-Even, factual, plain. State what the page shows without building tension or pressing a "so what". No rhetorical questions, no suspense — a clear read-out the listener can follow or skim. Numbers stated plainly. (Common framework: [`executor-base.md §8`](../executor-base.md).)+Even, factual, plain. State what the page shows without building tension or pressing a "so what". No rhetorical questions, no suspense — a clear read-out the listener can follow or skim. Numbers stated plainly. (Common framework: [`executor-notes.md`](../executor-notes.md) §1.)## 4. Page skeleton examplediff --git a/skills/ppt-master/references/modes/instructional.md b/skills/ppt-master/references/modes/instructional.mdindex b0181a73..d0feaefe 100644--- a/skills/ppt-master/references/modes/instructional.md+++ b/skills/ppt-master/references/modes/instructional.md@@ -32,7 +32,7 @@ Titles state what the page teaches ("How attention weights are computed") — cl## 3. Speaker-notes register-Patient, explanatory. Define before using; analogy then principle. Anticipate the learner's question and answer it. Steady pace; signpost transitions ("now that we have X, we can ask Y"). Conversational data. (Common framework: [`executor-base.md §8`](../executor-base.md).)+Patient, explanatory. Define before using; analogy then principle. Anticipate the learner's question and answer it. Steady pace; signpost transitions ("now that we have X, we can ask Y"). Conversational data. (Common framework: [`executor-notes.md`](../executor-notes.md) §1.)---diff --git a/skills/ppt-master/references/modes/narrative.md b/skills/ppt-master/references/modes/narrative.mdindex 44224531..a8276e82 100644--- a/skills/ppt-master/references/modes/narrative.md+++ b/skills/ppt-master/references/modes/narrative.md@@ -30,7 +30,7 @@ Titles read as beats that advance the arc ("Then the numbers stopped adding up")## 3. Speaker-notes register-Conversational narration — like talking with the audience, not reading a report. Scenario-conflict-resolution per page. Metaphors make the abstract tangible ("like adding a turbocharger"). Plain rhetorical questions create suspense; bridge each page from the prior one. Conversational data ("nearly a third", "more than doubled"). (Common framework: [`executor-base.md §8`](../executor-base.md).)+Conversational narration — like talking with the audience, not reading a report. Scenario-conflict-resolution per page. Metaphors make the abstract tangible ("like adding a turbocharger"). Plain rhetorical questions create suspense; bridge each page from the prior one. Conversational data ("nearly a third", "more than doubled"). (Common framework: [`executor-notes.md`](../executor-notes.md) §1.)---diff --git a/skills/ppt-master/references/modes/pyramid.md b/skills/ppt-master/references/modes/pyramid.mdindex 2f3ca71c..5dc50cee 100644--- a/skills/ppt-master/references/modes/pyramid.md+++ b/skills/ppt-master/references/modes/pyramid.md@@ -44,7 +44,7 @@ SCQA opening, pyramid body:## 3. Speaker-notes register-Conclusion-driven: the first sentence of each page's notes is the takeaway, then 2-3 supporting facts in flowing prose. Composed, authoritative. Every number paired with its comparison in the same sentence ("23% — nearly double the industry's 12%"). Spell percentages as words where the spoken form reads more naturally. (Common framework: [`executor-base.md §8`](../executor-base.md).)+Conclusion-driven: the first sentence of each page's notes is the takeaway, then 2-3 supporting facts in flowing prose. Composed, authoritative. Every number paired with its comparison in the same sentence ("23% — nearly double the industry's 12%"). Spell percentages as words where the spoken form reads more naturally. (Common framework: [`executor-notes.md`](../executor-notes.md) §1.)---diff --git a/skills/ppt-master/references/modes/showcase.md b/skills/ppt-master/references/modes/showcase.mdindex 31c00b69..301330b7 100644--- a/skills/ppt-master/references/modes/showcase.md+++ b/skills/ppt-master/references/modes/showcase.md@@ -30,7 +30,7 @@ Titles are short and evocative — a phrase, not a sentence.## 3. Speaker-notes register-Energetic, evocative — sets mood and builds anticipation. Short, punchy sentences. Lets the visual do the work and narrates the feeling around it. (Common framework: [`executor-base.md §8`](../executor-base.md).)+Energetic, evocative — sets mood and builds anticipation. Short, punchy sentences. Lets the visual do the work and narrates the feeling around it. (Common framework: [`executor-notes.md`](../executor-notes.md) §1.)---diff --git a/skills/ppt-master/references/native-data-interface.md b/skills/ppt-master/references/native-data-interface.mdnew file mode 100644index 00000000..022604bf--- /dev/null+++ b/skills/ppt-master/references/native-data-interface.md@@ -0,0 +1,368 @@+> See [`shared-standards-core.md`](./shared-standards-core.md) for the mandatory SVG foundation.++# Native Data Interface++Conditional interface for preset pattern fills and PowerPoint-native chart/table replacement metadata. Load when either feature appears in the authored SVG.++## 1. Pattern Fill — `<pattern>` with PPTX preset annotation++`<pattern>` requests one fixed DrawingML preset; the converter does not render+the tile's arbitrary geometry. Use this interface only when that preset mapping+is intended.++`data-pptx-pattern="<preset>"` is the generated default for selecting the+intended preset from the enum below. The converter retains an `ltUpDiag`+fallback when the annotation is absent; the checker reports that fallback as a+non-blocking fidelity warning. Invalid explicit preset names remain errors+because they violate the closed OOXML enum.++Pattern colors may come from importer metadata (`data-pptx-fg` /+`data-pptx-bg`) or from the pattern's child paint. Without metadata, the first+child `<rect>` fill becomes the background and the first stroke (or other fill)+becomes the foreground. A missing background defaults to white; a missing+foreground means no native pattern fill can be emitted. The child geometry+itself is never used as a repeatable tile.++**Valid `data-pptx-pattern` values** (OOXML `ST_PresetPatternVal` — closed enum, anything outside makes PowerPoint open with "needs to be repaired"):++| Category | Values |+|---|---|+| Grids | `smGrid` · `lgGrid` · `dotGrid` *(no `ltGrid` — common typo)* |+| Diagonal lines | `ltUpDiag` · `ltDnDiag` · `dkUpDiag` · `dkDnDiag` · `wdUpDiag` · `wdDnDiag` · `dashUpDiag` · `dashDnDiag` · `diagCross` |+| Horizontal / vertical lines | `horz` · `vert` · `ltHorz` · `ltVert` · `dkHorz` · `dkVert` · `narHorz` · `narVert` · `dashHorz` · `dashVert` · `cross` |+| Percent fills | `pct5` · `pct10` · `pct20` · `pct25` · `pct30` · `pct40` · `pct50` · `pct60` · `pct70` · `pct75` · `pct80` · `pct90` |+| Checks & confetti | `smCheck` · `lgCheck` · `smConfetti` · `lgConfetti` |+| Decorative | `horzBrick` · `diagBrick` · `weave` · `plaid` · `trellis` · `zigZag` · `wave` · `sphere` · `divot` · `shingle` · `solidDmnd` · `openDmnd` · `dotDmnd` |++`svg_quality_checker.py` warns when a referenced pattern lacks the annotation;+it errors when the pattern uses `patternTransform` or names a preset outside+this enum.++## 2. PowerPoint-Native Chart / Table Replacement Markers (Opt-in)++Native PowerPoint tables and Excel-backed charts activate at export time only. The default chart/table route remains hand-authored SVG geometry so the deck stays pixel-stable across PowerPoint / Keynote / LibreOffice / WPS.++**Authoring — markers are standard on supported data charts and text-grid tables**: Executor writes the marker at draw time on every data chart whose type falls in the supported set and on every pure text-grid data table ([`executor-chart.md`](./executor-chart.md) §2.2), so any deck can later form native objects without regeneration. Canonical rectangular merged text cells may use the narrow `row_span` / `col_span` contract below; graphical cells stay unmarked on the SVG fallback route. The marker group supplies both: visible SVG fallback children for browser/live-preview rendering, and JSON metadata for `svg_to_pptx` native export.++**Hard rule — activation is the opt-in, dormant unless exported with `--native-charts-and-tables`**: A marker only declares that a group is eligible for PowerPoint-native Chart/Table replacement. Normal `svg_to_pptx.py` runs keep the fallback SVG children and convert them into independently editable DrawingML shapes. Pass `--native-charts-and-tables` only when the data source and chart/table-specific object model matter more than cross-renderer layout fidelity: it emits the PowerPoint Chart/Table object and skips the fallback children to avoid duplicates. Native styling preserves the core palette, text, axis, grid, and background colors where possible, but it is still a PowerPoint Chart/Table object rather than a pixel-identical SVG drawing.++The native route is deliberately data-object-first and may be lossy: marker-local labels, callouts, KPIs, guide lines, custom split/bin semantics, or styling that is absent from the payload may disappear or normalize. Export warns about this route-level risk and any narrower issue it can detect. Loss of visual parity is not grounds to remove an active marker that the emitter can otherwise convert; use the default SVG-fallback export when exact authored artwork matters more than a native data source and object-specific controls.++| Replacement marker | Native output | Required metadata |+|---|---|---|+| `<g data-pptx-replace-with="table">` | `<p:graphicFrame>` with `<a:tbl>` | bounds + `columns` or `rows` |+| `<g data-pptx-replace-with="chart">` | `<p:graphicFrame>` with `c:chart` / `cx:chart` + chart part + embedded workbook | bounds + `type`, plus chart data |++**Metadata placement**: Put JSON in one child+`<metadata type="application/json">`. The parent group's+`data-pptx-replace-with` value selects the table or chart schema, so the+metadata child does not repeat an object-kind attribute. Attribute JSON+(`data-pptx-json="..."`) remains read-compatible but is harder to XML-escape+correctly and is not canonical authoring.++**Bounds**: Provide `x`, `y`, `width`, and `height` in metadata, or as+`data-pptx-x` / `data-pptx-y` / `data-pptx-width` / `data-pptx-height` on the+marker group. If any bound is omitted, the exporter infers the object frame+from the visible fallback geometry; this keeps SVG fallback and native object+placement aligned. Complete explicit bounds are absolute slide coordinates;+marker/ancestor `translate` and `scale` transforms apply only when at least one+bound is inferred. `x`, `y`, `width`, and `height` must be finite and resolve+inside PowerPoint's 32-bit DrawingML coordinate range; `width` and `height`+must resolve to at least one EMU. Native table frames must additionally resolve+to at least one EMU per resolved row and column.++**Validation**: `svg_quality_checker.py` validates replacement marker kind, JSON+metadata, bounds/fallback availability, table rows/columns, supported chart+type, chart data shape, and any imported fallback baseline before export.++Imported marker freshness, fallback classification, provenance, and legacy+read compatibility are operational import concerns. Keep generated authoring+free of those attributes; use the exact behavior and field index in+[`conversion.md`](../scripts/docs/conversion.md#native-table-and-chart-import-claims).++```xml+<g id="p03-revenue-chart" data-pptx-replace-with="chart">+ <metadata type="application/json">+ {+ "x": 120, "y": 150, "width": 520, "height": 320,+ "type": "column",+ "title": "Revenue by Segment",+ "categories": ["Q1", "Q2", "Q3"],+ "series": [+ {"name": "Cloud", "values": [12, 15, 19]},+ {"name": "Services", "values": [8, 9, 11]}+ ]+ }+ </metadata>+ <!-- Visible SVG fallback for live preview / non-native export goes here. -->+</g>+```++**Table schema**: Native tables are rectangular DrawingML grids. Use `columns`+for the optional header row and `rows` for body rows; shorter rows are padded+with blank cells unless `strict_grid: true` is set. Tables may contain at most+1000 resolved rows and 1000 resolved columns. Use `column_widths` and+`row_heights` as relative weights. Weight lists must match the resolved grid,+contain finite non-negative numbers, and include at least one positive value.+If present, `header_rows` must be an integer from `0` through the resolved row+count. Write `strict_grid`, `style.band_row`, and cell `bold` as JSON booleans.+Cell objects accept `text`, `fill`, `color`,+`align`, `valign`, `bold`, `font_size`, `padding`, `border_color`, and+`border_width`, plus optional `lang`; the same `padding`, `border_color`,+`border_width`, and `lang` keys may also live under `style` as table defaults.+For multi-paragraph text, replace cell `text` with a non-empty `paragraphs`+list. Each entry is either a string or an object containing optional+`align: "l|ctr|r"` and exactly one of `text` or non-empty `runs`; empty+paragraph strings are preserved, and cell `text` / `paragraphs` are mutually+exclusive. Each run is an object with required string `text` and optional JSON+boolean `bold`, `italic`, `underline`, and `strike`, plus optional `color`,+`font_size`, one-typeface `font_family`, `lang`, and `alt_lang`. Unknown fields,+wrong types, empty run lists, multi-typeface `font_family`, and unsupported+colors fail fast. PPTX import requires exact physical row/grid topology and+normalizes source presentation-only run XML outside this closed schema only+when it contains no non-empty `rPr` / `defRPr` / `endParaRPr` `effectLst` or+`effectDag`. A table-cell run effect follows the blocking effect contract above+instead of entering either the native payload or an effect-free fallback.+Relationship-bearing text, extensions, structural line breaks, fields, tabs,+bullets, malformed run topology, and unsupported text-body structure remain+fallback-only.+Per-side cell borders use `borders.left|right|top|bottom`, where each value is+either `{ "style": "none" }` or+`{ "style": "solid", "color": "#RRGGBB", "width": <positive-px> }`.+Per-side borders are cell-only; legacy uniform `border_color` / `border_width`+remain supported as defaults that an individual side may override.+When `lang` is absent, export derives `zh-CN` for CJK text and `en-US`+otherwise. `style.band_row: false` disables both `<a:tblPr bandRow>` and+materialized alternating row fills. Native table typography mirrors the+visible SVG fallback: put `style.font_family` and `style.font_size` on the+marker from the table text already drawn, then use `style.header_font_size` or+per-cell `font_size` only when the fallback visibly differs. If the fallback+has no explicit table font, use the deck body family and locked body size from+`spec_lock.md`.++**Hard rule — table metadata is the native source of truth**: Every row,+summary line, value, and cell-level style that must survive+`--native-charts-and-tables` must be present in `columns` / `rows`. SVG fallback text is+discarded during native export. `svg_quality_checker.py` warns when visible+fallback `<text>` inside a native table marker does not appear in metadata.+For numeric or currency columns, use cell objects with `align: "r"`; SVG+`text-anchor="end"` does not carry into the native table.++**Merged table cells — canonical rectangular contract only**: Put positive JSON+integer `row_span` / `col_span` values on the merge anchor and keep every+covered grid cell blank. Spans must stay within the resolved rectangular grid+and may not overlap. The exporter emits the canonical DrawingML topology+(`rowSpan` on the top edge, `gridSpan` on the left edge, `hMerge` / `vMerge` on+covered cells). CamelCase aliases, raw OOXML merge fields, top-level merge lists,+nonblank covered cells, invalid spans, and overlaps fail fast. The PPTX importer+activates native reconstruction only for that same explicit rectangular topology+with empty merge-slave text bodies; other merge encodings remain fallback-only+with `unsupported-merge-topology`.++**Category chart schema**: `column`, `bar`, `line`, `area`, `pie`,+`doughnut`, `pieOfPie`, `barOfPie`, and `radar` use `categories` plus+`series[].values`. Pie-family charts (`pie`, `doughnut`, `pieOfPie`, and+`barOfPie`) must have exactly one series; the exporter assigns per-category+slice colors so single-series charts do not collapse into one solid color.+Column and bar charts may set per-point colors with `series[].point_colors`+or `series[].pointColors`; the list must match `series[].values` length.+Classic category charts may set native PowerPoint data labels with+`data_labels`. Use `data_labels: true` for default value labels, or an object+with `show_value`, `position`, `number_format`, `font_size`, `font_family`,+`bold`, `color`, and optional per-point `colors`. Supported label positions+depend on chart type: clustered column/bar labels may use `outside_end`,+`inside_end`, `inside_base`, or `center`; stacked / percent-stacked column/bar+labels may use `inside_end`, `inside_base`, or `center`; line labels may use+`above`, `center`, or `best_fit`; area labels do not emit a native label+position. To label only selected data points, use `data_labels.points` with+zero-based `idx` plus optional per-point `position`, `number_format`,+`font_size`, `font_family`, `bold`, and `color`.++**Combo chart schema**: `combo` uses shared `categories` plus either `plots[]`+or typed `series[]`. Each plot supports `type: "column" | "line" | "area"`,+its own `series`, and optional `axis: "secondary"` for a right-side value axis.+When primary and secondary plots genuinely use different category caches,+`plots[]` may also carry its own `categories` and `category_numeric`; the+workbook writer allocates independent category/value ranges. Typed `series[]`+continues to require the shared top-level categories.+Imported `plots[]` may carry `series_indices` so the verified source identity+where each `c:idx` equals its `c:order` survives when physical plot order differs+from legend order. If one plot supplies it, every plot must supply a same-length+list of unique non-negative JSON integers, and the combined values must form one+contiguous `0..N-1` range. Sources whose `idx` and `order` differ stay+fallback-only; typed `series[]` does not accept this plot-scoped field.+Typed `series[]` accepts the same `type` and `axis` fields per series, and+adjacent compatible series are grouped into the same PowerPoint plot. Area+series may set `fill_opacity` / `fillOpacity` as a `0..1` SVG opacity value+when the SVG fallback uses a transparent area fill under an opaque line. A line plot with `area_fill: true`+is exported as a PowerPoint area chart under the hood; `fill_opacity` only sets+the fill style and does not trigger conversion by itself. Combo export layers+area plots below columns and lines while preserving the original series indices.+Line and area series may set `line_width` / `lineWidth` in SVG px units to+match fallback `stroke-width`.++**Narrow classic-axis schema**: `axes` is a closed object with the roles+`category`, `value`, `secondary_category`, and `secondary_value`. Each role may+set only `kind` (`text`, `date`, or `value`, as appropriate), `position`,+`visible`, `label_position` (`next_to`, `none`, `low`, or `high`),+`number_format`, `minimum`, `maximum`, `major_unit`, `reverse`, and+`major_gridlines`. `major_unit` applies to value axes only. PPTX date-axis+**import** is deliberately narrow: numeric Excel date serials are accepted for+area charts and OHLC stock charts; arbitrary date-axis source families are not.+This contract is not a full `AxisSpec`: logarithmic scales, minor units/gridlines,+crossing values, display units, tick skipping, and other unlisted OOXML semantics+remain unsupported and fail closed on import.++**Narrow XY-axis schema**: `scatter` and `bubble` may use a closed `axes` object+with only `x` and `y` roles. Both roles have `kind: "value"`; `x.position`+is `bottom` or `top`, while `y.position` is `left` or `right`. Each accepts the+same closed fields above, and `major_unit` is valid on both value axes. PPTX+import requires the plot to reference exactly two mutually cross-linked+`c:valAx` nodes and separately enforces the closed field/topology gates. The+native writer emits and the importer reads back every field in this closed+contract. Scatter import derives the effective `scatter_style` from a uniform+per-series line/marker/smooth state; unsupported or nonuniform states remain+fallback-only. The normalized SVG fallback newly consumes only+`axes.x.major_gridlines` and `axes.y.major_gridlines`; the other fields do not+imply full visual-axis parity.++**XY chart schema**: `scatter` and `bubble` use `series[].x` + `series[].y`;+`bubble` also requires one `series[].size` / `series[].sizes` value per point.+`series[].points` is also accepted as `[x, y]` / `[x, y, size]` tuples or+`{x, y, size}` objects.++**Chart typography**: Metadata sizes use the same px-style unit as SVG text+(`1px = 0.75pt`). `style.font_family` and the role-specific+`title_font_size`, `subtitle_font_size`, `axis_font_size`,+`axis_title_font_size`, `legend_font_size`, and `note_font_size` fields are+required only when the native object must preserve typography that cannot be+inferred unambiguously from the visible fallback.++**Chart chrome metadata**: Text that is visually part of the chart must be in+metadata, not only in SVG fallback children; metadata MUST still match visible+fallback chrome. `title` becomes the native chart title on classic charts; it+is not an object name, so use `name` for semantic object naming. `subtitle`+becomes the second rich-text line of that classic chart title. `title`,+`subtitle`, and axis-title values may be strings or objects with `text`,+`font_size`, `font_family`, and `color` when the fallback uses local role+typography. `svg_quality_checker.py` rejects `title`, `subtitle`, or axis-title+metadata whose text is not visible inside the replacement marker's fallback. Direct+`--native-charts-and-tables` export keeps the chart native but omits that inconsistent+chrome with a warning. chartEx keeps PowerPoint's empty `<cx:title>` and emits+the title / subtitle as companion editable text boxes until chartEx rich titles+are validated. Axis+titles are optional and explicit: use `axis_titles` with+`category`, `value`, `x`, `y`, or `secondary_value` keys, or the root aliases+`category_axis_title`, `value_axis_title`, `x_axis_title`, `y_axis_title`, and+`secondary_value_axis_title`; do not add semantic axis titles that are not+visible in the fallback. Set `show_value_axis_labels: false` when the fallback+keeps category labels but omits numeric value-axis tick labels, such as a radar+chart without radial coordinates. Native legends are metadata-controlled: use+`show_legend: true` and `legend_position` only when the fallback's legend is+meant to be replaced by PowerPoint's native legend.+Companion text such as `caption`, `source`, `note`, `notes`, `footnote`, and+`footnotes` is exported as editable PPT text boxes next to the native chart. A+companion entry may be a string or an object with `text`, `x`, `y`, `width`,+`height`, `font_size`, `color`, `align`, and `bold`; explicit bounds are+recommended so the native export matches the SVG fallback placement. Explicit+companion bounds are slide coordinates, not local coordinates inside a+transformed marker group. Use companion text for chart captions, source notes,+center labels, and freeform annotations; use `data_labels` for values that+belong to chart points.++**Chart color styling**: For classic native charts, `style.colors` sets series+colors. The exporter also writes explicit chart-area fill, plot-area fill,+axis line, gridline, and label text colors so PowerPoint does not substitute a+white/default-theme chart. If omitted, the exporter infers these colors from+the visible SVG fallback: the largest panel-like `<rect>` becomes the chart+background, fallback text supplies label color, and fallback strokes supply+axis/grid colors. Override any of them explicitly under `style` with+`chart_area_fill`, `plot_area_fill`, `text_color`, `axis_color`, and+`grid_color`; use `"none"` for transparent chart or plot area fill. Generated+payloads default to uppercase `#RRGGBB`. The exporter retains compatibility for+`#RGB`, `rgb(...)` / `rgba(...)`, and common CSS names, normalizing them to+6-digit OOXML RGB. Bar and column series also disable PowerPoint's negative-value+inversion so negative bars keep the same series fill instead of turning into+white/theme fill.++For ChartEx native charts, valid payload `style.colors` (or root `colors`)+populate the ChartEx color-style part instead of being replaced by a fixed+accent1–accent6 list. Other ChartEx style semantics remain normalized.++**PowerPoint chartEx schema**: `treemap`, `sunburst`, `histogram`, `pareto`,+`boxWhisker`, `waterfall`, and `funnel` use Office 2016+ chartEx parts. Use+these input shapes:++| Type | Required data |+|---|---|+| `treemap`, `sunburst` | `values` plus either `levels` (`levels[level][point]`) or path-style `categories` (`[["Region", "Group", "Leaf"], ...]`) |+| `treemap` display note | Top-level group labels default to `overlapping`; override with `parent_label_layout: "banner" \| "overlapping" \| "none"`. PowerPoint labels only the top level and leaves — intermediate levels group tiles spatially without labels (sunburst shows every ring). |+| `histogram` | `values` |+| `pareto`, `waterfall`, `funnel` | `categories` + `values`; `waterfall` also accepts `subtotals` / `subtotal_indices` point indexes |+| `boxWhisker` | `series[].values`; optional `series[].categories` per value |++> Note: chartEx files are valid PPTX and editable in PowerPoint; non-Microsoft+> renderers can display a limited subset.++**Stock chart schema**: `stock` uses numeric Excel date serials in+`categories` or `dates`, plus exactly four series in open / high / low / close+order. Use either `series` with four entries, or top-level `open`, `high`,+`low`, and `close` arrays. PPTX import currently recognizes only canonical OHLC+stock charts with shared numeric date caches, `hiLowLines`, and `upDownBars`.+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. HLC, volume, noncanonical structure, and style XML+outside the safe parsing boundary stay fallback-only.++**PPTX chart-import boundary**: The importer recognizes conservative classic+single-plot charts plus the verified scatter/bubble XY-axis, column/line/area+combo, area date-axis, canonical OHLC stock, radar, safe `of_pie` `serLines`,+axis/title/legend normalization, and bar/column gap/overlap subsets. Imported+`gapWidth` must be one canonical integer in `0..500`; imported `overlap` must be+one canonical integer in `-100..100`. Both values intentionally normalize to+the native writer contract rather than claiming exact source-style retention.+Malformed, duplicate, or out-of-range values fail closed.++ChartEx import is closed to seven validated data models: `treemap`, `sunburst`,+`histogram`, `pareto`, `box_whisker`, `waterfall`, and `funnel`. The importer+retains their supported hierarchy/category/value/series/subtotal topology for+native read-back. Numeric cache values must be non-empty and finite, and cache+counts/indexes must be canonical non-negative decimal integers with exact,+contiguous topology; malformed, non-numeric, `NaN`, infinite, sparse, duplicate,+or mismatched caches fail closed. ChartEx style, axis, label, and binning details+outside the payload normalize. Full `AxisSpec`, arbitrary ChartEx families or+presentation fidelity, arbitrary stock variants, and axis/combo/date-axis+semantics outside the closed fields above remain fallback-only. The C4/C5+import work does not expand the normalized SVG renderer and does not reduce+existing SVG-marker-to-native writer support.++**Deferred chart types**: Exploded pie / doughnut variants, `map`, `heatmap`,+`bullet`, and `gantt` are intentionally outside the current native-object+support boundary. The exporter fails fast for these types until each mapping is+implemented and validated one by one.++**Supported chart types**:++- `column`, `bar`: `clustered`, `stacked`, or `percentStacked` (`grouping`)+- `line`: `standard`, `stacked`, or `percentStacked` (`grouping`); `line` or `lineMarker` (`line_style`, default `line` / no markers)+- `area`: `standard`, `stacked`, or `percentStacked` (`grouping`)+- `pie`: exactly one series, per-slice colors+- `doughnut`: exactly one series, per-slice colors+- `pieOfPie`, `barOfPie`: exactly one series, per-slice colors+- `radar`, `radarMarkers`, `radarFilled`+- `scatter`: `marker` (default), `lineMarker`, `line`, `smoothMarker`, or `smooth` (`scatter_style`)+- `bubble`: x/y/size series+- `combo`: `column`, `line`, and `area` plots, optional secondary value axis+- `treemap`, `sunburst`: hierarchical chartEx charts+- `histogram`, `pareto`+- `boxWhisker`+- `waterfall`, `funnel`+- `stock`: open / high / low / close series++3D chart aliases (`3DColumn`, `3DBar`, `3DLine`, `3DArea`, `3DPie`, cone,+cylinder, pyramid variants, and `surface`) are unsupported.++Native legends are opt-in through `show_legend: true`; `legend_position`+defaults to `bottom` and accepts `top`, `left`, or `right`.++**Forbidden — replacement marker transforms**: Do not rotate, skew, or matrix-transform table/chart replacement groups. Translate / scale is accepted; complex transforms fail export because PowerPoint-native table/chart frames do not preserve arbitrary SVG transforms.diff --git a/skills/ppt-master/references/native-shape-authoring.md b/skills/ppt-master/references/native-shape-authoring.mdindex c0f6fcbf..ed56b464 100644--- a/skills/ppt-master/references/native-shape-authoring.md+++ b/skills/ppt-master/references/native-shape-authoring.md@@ -1,4 +1,4 @@-> See [`shared-standards.md`](./shared-standards.md) §§1.4–1.5 for the native-shape metadata and validation contracts.+> See [`shared-standards-core.md`](./shared-standards-core.md) §§1.4–1.5 for the native-shape metadata and validation contracts.# Native Preset Shape Authoring Referencediff --git a/skills/ppt-master/references/pptx-structure-interface.md b/skills/ppt-master/references/pptx-structure-interface.mdnew file mode 100644index 00000000..6bc44dd5--- /dev/null+++ b/skills/ppt-master/references/pptx-structure-interface.md@@ -0,0 +1,195 @@+> See [`shared-standards-core.md`](./shared-standards-core.md) for the mandatory SVG foundation.++# 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`.++**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.++## 1. PPTX Structure Routing++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 confirmed with `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 materialized workspace.++**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 create a new Layout identity only when fixed Layout atoms or slot topology/bounds change. Update the page mapping immediately while authoring the first such page; never mutate a reused key silently.++## 2. Explicit PPTX Master / Layout / Placeholder Metadata++**Trigger**: This explicit metadata interface applies only to new pages generated from a current deck/layout template workspace with `template_reuse_scope: mirror|layout`. `spec_lock.md` declares `pptx_structure.mode: structured`, complete unique `pptx_masters` / `pptx_layouts` rosters, one `page_pptx_layouts` assignment per generated page, and `page_layouts` as authoring-prototype provenance. `template_reuse_scope: style`, free-design, and brand-only SVGs use `mode: flat` and none of these metadata fields.++**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 may allocate a new Layout key/name only when fixed Layout atoms or slot topology/bounds change; update the lock during authoring. Mirror-created prototypes preserve validated source identity, literal paint, typography, effects, atomic geometry, and referenced assets in a new workspace. `standard` / `fidelity` never make source topology authoritative; mirror does not synthesize a 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+the two optional canonical booleans below so export can write the preserved source+package fields without inferring visibility from which shapes happen to be+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+locked `title` size to every `a:defRPr` in Master `p:titleStyle`. Level 1 in+both `p:bodyStyle` and `p:otherStyle` uses the locked `body` size; 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 |+|---|---|---|+| `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` |++**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.++**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+size to the generated Layout prompt run and+`p:txBody/a:lstStyle/a:lvl1pPr/a:defRPr@sz`. It does not rewrite Slide direct+runs or Layout levels 2–9. This preserves the layout-specific size when+level-one placeholder text is inserted or reset; placeholders without a direct+prototype size remain unchanged.++| Metadata | Placement | Behavior |+|---|---|---|+| `data-pptx-master="master-default"` | root `<svg>` | Binds the slide to one generated Slide Master key |+| `data-pptx-master-name="Default Master"` | root `<svg>` | Sets the Master picker/display name |+| `data-pptx-layout="content"` | root `<svg>` | Binds the slide to one generated reusable layout key |+| `data-pptx-layout-name="Title and Content"` | root `<svg>` | Sets the PowerPoint layout-picker name; defaults from the layout key |+| `data-pptx-show-master-shapes="false"` | root `<svg>` | Accepts exact lowercase `true` or `false` and writes the assigned Layout's `p:sldLayout@showMasterSp`; every SVG using the same Layout key must repeat the same value; omission means `true` |+| `data-pptx-show-inherited-shapes="false"` | root `<svg>` | Accepts exact lowercase `true` or `false` and writes this Slide's `p:sld@showMasterSp`; `false` hides inherited Layout and Master shapes without removing backgrounds, placeholders, parts, or parent relationships; omission means `true` |+| `data-pptx-layer="master"` | direct semantic atom | Moves one repeated static object/background into the named Slide Master; ordinary `<g>` is forbidden, while one validated compact authored-preset `<g>` (§1.5) is an atomic exception |+| `data-pptx-layer="layout"` | direct semantic atom | Moves one repeated static object/background into the selected Layout; ordinary `<g>` is forbidden, while one validated compact authored-preset `<g>` (§1.5) is an atomic exception |+| `data-pptx-layer="slide"` | direct full-canvas solid `<rect>` only | Writes a one-page override as Slide `p:bg` |+| `data-pptx-placeholder="..."` | direct slot `<g id>` | Declares a reusable Layout slot whose visible content remains Slide-local |+| `data-pptx-placeholder-bounds="x y width height"` | slot `<g>` | Supplies the positive reusable design-zone frame in SVG user units with at most two decimals per value |+| `data-pptx-placeholder-idx="1"` | slot `<g>` | Retains an imported source Layout placeholder index; optional for reconstructed layouts |+| `data-pptx-placeholder-carrier="true"` | one compatible direct child of a normal slot | Binds that visible child as the real Slide placeholder carrier |+| `data-pptx-placeholder-binding="proxy"` | composite `object` slot `<g>` only | Keeps the visible group ordinary and creates one hidden transparent binding proxy |+| `data-pptx-editable="false"` | master/layout element or slide background | Declares intentional editing outside ordinary slide content |++**Hard rule — explicit only**: On a structured `template_reuse_scope: mirror|layout` route, every SVG requires the four root Master/Layout identity attributes. Optional inherited-shape visibility uses only exact lowercase `true` / `false`; other spellings fail, and omission means `true`. Every Master/Layout atom and slot requires a unique stable `id` and is a direct root child. Layouts with zero slots are valid. `data-pptx-layout-kind`, `distilled`, and `utility` are legacy metadata and fail the structured contract. Flat `template_reuse_scope: style`, free-design, and brand-only pages omit the entire interface, including the visibility attributes.++**Layer order**: Author the SVG in PowerPoint paint order: Master background,+Layout background, optional Slide background, remaining Master atoms, remaining Layout atoms,+then slot groups and Slide-local content groups. Backgrounds are a special inheritance+plane beneath every shape; this order keeps standalone SVG preview and+PowerPoint rendering aligned. The exporter rejects interleaved layers.++**Solid background ownership**: Structured export deliberately narrows scoped+background ownership to a direct full-canvas solid `<rect>` and disables the+generic conversion-level promotion described in §4.2. Mark the solid rect+`data-pptx-layer="master"` for the deck-wide default,+`data-pptx-layer="layout"` for a page-type override, or+`data-pptx-layer="slide"` for a one-slide override. An unmarked direct+full-canvas solid rect in the background plane is also treated as Slide scope.+A Layout background overrides the Master background; a Slide background+overrides both. Use the Master for a globally stable color and the Layout for+cover/section/content variants under the same design language. Gradient and+preset-pattern rects remain ordinary shapes on declared Master/Layout layers+or as Slide-local content; images remain pictures. Textures, transformed rects,+and visible-stroke rects also remain ordinary objects.++| Placeholder value | Direct carrier inside slot `<g>` | PowerPoint placeholder |+|---|---|---|+| `title`, `subtitle`, `body` | one `<text data-pptx-placeholder-carrier="true">` | `title`, `subTitle`, `body` |+| `date`, `footer`, `slide-number` | one `<text data-pptx-placeholder-carrier="true">` | `dt`, `ftr`, `sldNum` |+| `picture` | one `<image>` or supported imported crop `<svg>`, marked as carrier | `pic` |+| `chart`, `table` | one matching `data-pptx-replace-with` marker group, marked as carrier | `chart`, `tbl` |+| `object` | one text, image, basic SVG shape, or validated compact authored-preset `<g>` marked as carrier; alternatively the slot group declares `binding="proxy"` | `obj` |+| `media` | one `<image>` or supported imported crop `<svg>`, marked as carrier | `media` |++**Text slot carrier**: A multiline text placeholder must remain one+native text frame. Use the default paragraph merge; `--no-merge` cannot supply+several line shapes as one+PowerPoint placeholder prototype/binding. Leave strict-line text Slide-local+when separate frames are the required result.++For a materialized mirror, an imported text carrier may additionally keep the+source shape's positive `data-pptx-frame="x y width height"`. That frame owns+the Slide carrier `a:xfrm`; the converter reconstructs text-body insets from the+visible SVG anchor/baseline instead of shrinking the shape to glyph bounds.+`data-pptx-placeholder-bounds` remains the reusable Layout default and may+legitimately differ. Do not add `data-pptx-frame` to an authored+`standard` / `fidelity` carrier merely to duplicate its Layout bounds.++**Blank text carrier**: Leave a marked text carrier empty or whitespace-only+when the placeholder must remain visually blank. Export materializes one+invisible U+200B run so the carrier still becomes a native PowerPoint text+shape. Do not insert a dummy dash, shrink text below the DrawingML 1pt minimum,+or hide a visible glyph with opacity/background paint; those workarounds either+leak content or produce a PPTX that PowerPoint repairs.++`title` is normally type-matched without an index in reconstructed layouts; if+an imported source title explicitly has one, preserve that exact index. Every+indexed placeholder on one layout uses a unique OOXML UInt32 index. Structured export writes the semantic type on both the Layout and Slide carrier (except `obj`, whose OOXML default is already `obj`) so PowerPoint and `python-pptx` retain the same identity. A composite object slot instead keeps its visible group ordinary and uses a hidden transparent proxy.+Date, footer, and slide-number placeholders enable their matching Layout `p:hf`+flags; a date placeholder also gets a `datetimeFigureOut` field in the reusable+Layout definition. The current Slide keeps its authored date content.++Because an omitted `p:ph@idx` has the effective value `0`, an omitted-index+title reserves `0`; no other placeholder on that Layout may use the same+effective index.++**Slot prototype**: The prototype source declared by the unique Layout definition supplies that Layout's placeholder formatting. `data-pptx-placeholder-bounds` supplies the reusable default frame and is mandatory on every slot. Derive it from+the intended design zone, column, panel inset, safe area, or picture frame —+never from text length, glyph width, line count, or a tight content bounding+box. Repeat the same slot ids/types/effective indices/default bounds/binding modes on every slide using that Layout. The Layout owns the reusable `p:ph`; normal visible carriers keep a matching Slide binding so approved rendering stays identical. A composite `object` proxy adds one hidden transparent binding shape to suppress empty inherited placeholder paint. Bounds define the Layout default only; actual Slide content and local carrier geometry may differ.++**Final-package read-back gate**: After writing a temporary structured PPTX and before publishing it, export reopens the package and+verifies that each published Slide targets exactly one Layout, one Layout key always resolves to the+same part, different keys do not collapse onto one part, and every declared Layout—including one unused by all published Slides—is+registered through its Master and the Presentation. Physical Slide/Layout/+Master part rosters, their content-type overrides, and their Presentation/+Master registrations must be exact. It also verifies the Layout picker name,+Master picker identity, placeholder type and effective index, matching `p:hf` flags, explicit design-zone frame, direct prompt size, and level-one default size.+Every owned `p:bg` is checked as an exact zero-or-one payload against the pre-+promotion result; this includes preserving the base Master background when no+authored Master background replaces it. During the same export, every finished+Slide, Layout, and Master must reproduce its exact top-level shape-name roster+and order after packaging. The gate verifies that each carrier-bound slot owns the expected Slide binding, each composite visible carrier remains ordinary, and every composite binding proxy is hidden. A zero-slot Layout must read back with no placeholder. Later slides may keep different Slide-local geometry; only the reusable+Layout frame is checked against the explicit/prototype contract. Any mismatch+fails export without replacing the requested output.++**Static structure consistency**: Repeat the same master element ids on every+slide and the same layout element ids on every slide sharing a layout. Their+generated OOXML must be identical within the affected master/layout group.+Static structure may carry shapes, text, or images; non-image/external+relationships are rejected. Every static object is atomic. An ordinary+`<g data-pptx-layer="master|layout">` is forbidden; the validated compact+authored-preset group from §1.5 is the sole group exception because it compiles+to one native object. A full-canvas first rect may be marked as a Master or+Layout background.++**Native object slot carriers**: `chart` / `table` slots require+`--native-charts-and-tables`; fallback groups contain several shapes and cannot map to one+PowerPoint placeholder. `object` is the generic PowerPoint content slot and+uses either one carrier object—including one validated compact authored-preset+group—or the explicit composite proxy downgrade. `media` currently binds+an authored image/crop to a native `media` placeholder; it does not synthesize+video or audio media from a decorative SVG group.++## 3. Legacy Template Input Boundary++Existing structured/template projects or packages that carry `native_structure.json` / `source_template.pptx`, `pptx_structure.mode: baseline|template|preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled` / `utility`, direct atomic placeholders, or an incomplete root Master identity are not generation/export inputs and are never upgraded in place. Create a separate current workspace through [`create-template`](../workflows/create-template.md). A project explicitly declaring `pptx_structure.mode: flat` is the current free-design/brand-only route and needs no conversion merely because it has no Master/Layout metadata.++| Available source | Allowed create-template behavior |+|---|---|+| Original PPTX Type A | `standard` / `fidelity` author new topology; `mirror` preserves supported Master/Layout/placeholder facts that still exist in the package |+| Legacy or unstructured SVG Type B | `standard` / `fidelity` use pages as visual/contextual reference and author a complete new contract; old metadata is not output topology |+| Complete current SVG Type B | `mirror` may preserve the explicit current contract in a new workspace; authored modes may replace it |++Without an original PPTX or complete current Type B contract, do not claim mirror or source-topology recovery. After template creation, Generate PPTX Step 3 authors new structured `svg_output/` pages; the exporter only compiles those declarations and never derives, repairs, or migrates structure.++---diff --git a/skills/ppt-master/references/semantic-svg.md b/skills/ppt-master/references/semantic-svg.mdindex 4f15cead..28b01d8f 100644--- a/skills/ppt-master/references/semantic-svg.md+++ b/skills/ppt-master/references/semantic-svg.md@@ -18,7 +18,7 @@ The completed SVG remains the full visible page. Removing the metadata must not**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 confirmed with `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 — 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.md`](./shared-standards.md) §§1.4–1.5. Do not duplicate those facts with `data-pptx-role`.+**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`.---@@ -76,7 +76,7 @@ Use one direct root group as the authoring boundary and one compatible direct ch| Identity | `data-pptx-placeholder-idx` is optional; effective indices must be unique within one Layout. Preserve a source index when reconstructing an existing PPTX. || Fixed decoration | Reusable decoration does not belong in the slot. Author it as a root Layout atom. Page-specific labels/captions use another slot or remain Slide-local. |-Canonical placeholder values are `title`, `subtitle`, `body`, `picture`, `chart`, `table`, `object`, `media`, `date`, `footer`, and `slide-number`. Carrier compatibility is defined in [`shared-standards.md`](./shared-standards.md) §7.+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.### 3.2 Explicit composite proxydiff --git a/skills/ppt-master/references/shared-standards-core.md b/skills/ppt-master/references/shared-standards-core.mdnew file mode 100644index 00000000..4f4aa86e--- /dev/null+++ b/skills/ppt-master/references/shared-standards-core.md@@ -0,0 +1,642 @@+# Shared SVG Core Standards++Mandatory reference for every route that authors or regenerates slide visuals through SVG. It owns XML validity, the closed generated-authoring surface, basic converter compatibility, page closure, semantic grouping, and shared fidelity vocabulary.++**Conditional module routing**:++| Trigger | Load |+|---|---|+| 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) |++**Fidelity labels**:++| Label | Meaning |+|---|---|+| `Native-stable` | Generated PPTX uses the corresponding native DrawingML property or object and retains the documented semantics within the technique-specific limits. |+| `Native-normalized` | Export targets an editable DrawingML equivalent, but normalizes the SVG into another structure such as a freeform, run property, or simplified paint/effect. |+| `Approximate` | DrawingML has no exact SVG equivalent; export targets the intended effect through a documented approximation, and material differences require output review. |+| `Bake-required` | The runtime effect is outside the native contract; pre-render it into an image or rebuild it with explicit supported geometry. |++**Reading rules**:++- **Required** / **Forbidden** statements are non-negotiable technical boundaries.+- **Conditional** contracts apply only when the corresponding feature is used.+- **Reference — not a constraint** passages expose capabilities and recipes; they do not require every page or visual style to use them.+- The locked `visual_style` controls whether and how strongly a compatible effect is used. It never expands the technical boundary.++**Hard rule — generated authoring is fail-closed**: `svg_output/` and reusable+template SVGs may use only properties and conditional interfaces explicitly+listed in this file or a triggered module in the routing table above. `svg_quality_checker.py` rejects unknown inline visual+properties and conditional contracts that have no reliable compatibility+mapping; documented fallback forms remain valid and receive warnings.++**Default — recommended authoring and supported input stay separate (may+preserve supported input)**: generated SVG uses one predictable default+spelling, while converter-supported equivalent spellings remain valid input.+The checker may recommend normalization, but such warnings do not require+modification or block export. Only invalid, unsafe, or unreliably convertible+input is an error; do not remove converter support to enforce a narrower+generation preference.++**Hard rule — one-way fidelity vocabulary**: the labels above describe the+`svg_output/` → generated PPTX path. They do not promise reconstruction of the+original SVG syntax, `<defs>` graph, `<use>` structure, path commands, or+`<tspan>` layout after PPTX-to-SVG import, nor pixel identity across PowerPoint,+LibreOffice, Keynote, and WPS.++**Hard rule — capability boundary**: a recipe never expands converter support.+Use only the target elements and syntax documented by each conditional+contract. Unsupported element tags fail preflight; browser-rendered attributes+outside these contracts must not be assumed to have a DrawingML mapping.++---+++## 1. Required Foundation, Forbidden Features, and Conditional Interfaces++### 1.0 Text characters: must be well-formed XML++SVG is strict XML. Two rules for all text and attribute values:++| Character category | Required form | Forbidden form |+|---|---|---|+| Typography & symbols (em dash, en dash, ©, ®, →, ·, NBSP, full-width punctuation, emoji…) | **Raw Unicode characters** — write `—` `–` `©` `®` `→` directly | HTML named entities — `—` `–` `©` `®` `→` `·` ` ` `…` `•` etc. |+| XML reserved characters (`&`, `<`, `>`, `"`, `'`) | **XML entities only** — `&` `<` `>` `"` `'` (e.g. `R&D`, `error < 5%`) | Bare `&` `<` `>` (e.g. `R&D`, `error < 5%`) |++One offending character invalidates the file and aborts export.++**Structural blacklist** (in addition to the character rules above):++| Banned Feature | Description |+|----------------|-------------|+| `mask` | Masks |+| `<style>` | Embedded stylesheets |+| `class` | CSS selector attributes |+| External CSS | External stylesheet links |+| `<foreignObject>` | Embedded external content |+| `textPath` | Text along a path |+| `@font-face` | Custom font declarations |+| `<animate*>` / `<set>` | SVG animations |+| `<script>` / event attributes | Scripts and interactivity |+| `<iframe>` | Embedded frames |++The blacklist above is exhaustive for globally forbidden structural syntax.+It is not a positive allowlist for every browser-rendered property. Features+that require a restricted form are valid only under the conditional contracts+below; unlisted visual properties are unsupported.++**Hard rule — inline visual-property allowlist**:++| Property family | Allowed inline `style` properties |+|---|---|+| Paint and line | `fill`, `stroke`, `stroke-width`, `stroke-dasharray`, `stroke-linecap`, `stroke-linejoin`, `fill-opacity`, `stroke-opacity`, `vector-effect` |+| Text | `font-family`, `font-size`, `font-weight`, `font-style`, `text-anchor`, `letter-spacing`, `text-decoration` |+| Alpha and definition paint | `opacity`, `stop-color`, `stop-opacity`, `flood-color`, `flood-opacity` |+| Literal geometry | The element-specific properties in §2.1 |+| Preview-only | `shape-rendering`; it does not change native geometry |++**Default — ordinary generated paint**: the table allows inline placement of+those property names. New solid paint uses uppercase six-digit `#RRGGBB`;+`fill` / `stroke` may instead use lowercase `none` or an exact local+`url(#id)`. Load [`svg-effects.md`](./svg-effects.md) before authoring any+alternative compatible color spelling, alpha/opacity channel, dash/cap/join,+gradient, filter, or constructed paint/effect. Existing compatible alternatives+remain valid input and receive recommendation warnings rather than errors.++Conditional properties with a required XML form stay out of inline style:+write `filter="url(#id)"`, `clip-path="url(#id)"`, and+`marker-start` / `marker-end` as direct attributes. `!important`, unknown CSS+properties, blend modes, isolation, and backdrop filters fail quality check.++The table registers property names, not arbitrary CSS values. Ordinary generated+text uses a non-empty `font-family`, a finite positive unitless-px `font-size`,+`font-weight` of `normal` / `bold` / an integer hundred from `100` through+`900`, `font-style` of `normal` / `italic`, and `text-anchor` of `start` /+`middle` / `end`. Inheritable text declarations belong only on `<svg>`, `<g>`,+`<text>`, or `<tspan>`; `text-anchor` is invalid on `<tspan>`. Load+[`svg-effects.md`](./svg-effects.md) §6.7 before authoring tracking,+underline/strike, text outline/alpha, gradient text, or text filter effects.+Unknown or unmapped declarations fail Checker preflight and native export.++> **`marker-start` / `marker-end` is conditional** — see §1.1.+>+> **`clipPath` on `<image>` is conditional** — see §1.2.+>+> **Static same-document `<use>` is conditional** — see §1.3.+>+> **Imported native-shape metadata is conditional** — see §1.4.+>+> **Authored native preset fragments are conditional** — see §1.5.+>+> **Inline CSS geometry, simple gradients, filters, and approximate group+> opacity are conditional** — see §2 and [`svg-effects.md`](./svg-effects.md).+>+> **PPT preset patterns and native chart/table/template metadata are+> conditional** — see [`native-data-interface.md`](./native-data-interface.md) and [`pptx-structure-interface.md`](./pptx-structure-interface.md).++DrawingML has no arbitrary per-pixel alpha-compositing path. Effects that rely+on one, including text-knockout image fills and arbitrary alpha composites,+must be baked into a raster asset before SVG export.++---++### 1.1 Line-end Markers (Conditional Contract)++`marker-start` and `marker-end` are supported on `<line>` and `<path>` only+when the referenced marker fits this native-arrow contract:++| Concern | Required form |+|---|---|+| Reference | Exact local `url(#id)` to a `<marker>` in `<defs>` |+| Orientation | `orient="auto"` or `orient="auto-start-reverse"`; the latter reverses `marker-start` while behaving like `auto` at `marker-end` |+| Shape | One direct shape representing a DrawingML `triangle`, `stealth`, `arrow`, `diamond`, or `oval` line end: a 3-vertex `<polygon>` / closed path (triangle), a simple concave 4-vertex `<polygon>` / closed path (stealth), an open 3-vertex path (arrow), a simple convex 4-vertex `<polygon>` / closed path (diamond), or one `<circle>` / `<ellipse>` (oval) |+| Path grammar | Use one explicit `M`/`L` command per vertex. Triangle, stealth, and diamond paths end in `Z`; arrow paths remain open after the third vertex. Do not use `H`, `V`, curves, or an implicit multi-point `L` command inside a marker path |+| Color parity | Triangle, stealth, diamond, and oval use a fill matching the parent line stroke. The open arrow uses `fill="none"` and a stroke matching the parent line stroke. DrawingML line ends inherit the line color |++The converter maps these five shapes to their corresponding DrawingML line-end+types. Prefer `<polygon>` for the closed triangle, stealth, and diamond forms;+the open arrow form requires `<path>`. Four-vertex shapes must be simple and+non-degenerate: convex geometry maps to diamond and concave geometry maps to+stealth. Checker and exporter preflight consume this same contract; other+marker shapes have no native mapping and block export instead of being silently+dropped.++PPTX import compatibility, tolerant recovery, strict-mode rejection, and+diagnostic behavior are indexed in+[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).++---++### 1.2 Image Clipping (Conditional Contract)++`clip-path` has a native picture-geometry mapping only on SVG-namespace+`<image>` elements (plus the exact imported crop wrapper defined under Images)+and only under this contract:++| Concern | Required form |+|---|---|+| SVG-namespace `<clipPath>` defined inside `<defs>` | Converter looks up one exact local id; missing, duplicate, foreign-namespace, or malformed references fail |+| Contains exactly one direct SVG-namespace supported shape child | Multiple shapes are not composited |+| Shape is one of: `<circle>`, `<ellipse>`, `<rect>` (optional rx/ry), `<path>`, `<polygon>` | These map to DrawingML geometry (preset or custom) |+| No `clip-rule` or `fill-rule`, whether direct or in inline `style` | DrawingML picture geometry has no equivalent winding-rule control |+| Used only on `<image>` or an exact imported crop wrapper | Shapes, groups, text, and generalized nested SVG targets are **forbidden** |++| SVG clip shape | DrawingML output |+|---|---|+| `<circle>` / `<ellipse>` | Full-frame `<a:prstGeom prst="ellipse"/>`; the child must exactly cover the image frame. A `userSpaceOnUse` circle requires a square physical frame; a normalized `objectBoundingBox` circle may fill any frame |+| `<rect>` / `<rect rx="..."/>` | A plain full-frame rect is a compatible no-op; rounded form maps to full-frame `<a:prstGeom prst="roundRect"/>` with one physical radius adjustment. The rect must exactly cover the image frame and cannot express non-uniform physical corner radii |+| `<path>` / `<polygon>` | `<a:custGeom>` with coordinates mapped into the image frame |++`clip-path` on shapes, groups, or text is forbidden; author the target geometry+directly instead. Use a path/polygon clip when the intended contour does not+cover the full picture frame. A contour that depends on even-odd or another+explicit winding rule is outside this mapping and must be rebuilt as one+unambiguous visible contour or pre-rendered.++---++### 1.3 Static Same-Document `<use>` (Conditional Contract)++**Expansion contract**: Static local reuse is compile-time authoring shorthand. `finalize_svg.py` and+native export replace each qualifying instance with cloned primitive content;+PPTX-to-SVG import emits the resulting primitives and does **not** reconstruct+the original `<use>` / `<symbol>` structure.++| Concern | Required form |+|---|---|+| Reference syntax | Author new SVG with the SVG 2 form `href="#id"`. Legacy `xlink:href="#id"` remains read-compatible and Live Preview normalizes it to `href`; if both attributes exist, their values MUST match. |+| Referenced target | One of `<symbol>`, `<g>`, `<use>`, `<rect>`, `<circle>`, `<ellipse>`, `<line>`, `<path>`, `<polygon>`, `<polyline>`, `<text>`, or `<image>`. Nested local `<use>` is recursively expanded. |+| Instance position | Generated `<use x>` / `<use y>` use finite unitless values; an explicit `px` suffix is read-compatible. Omitted values default to `0`. |+| Symbol viewport | A referenced `<symbol>` MUST have a finite four-number `viewBox` with positive width/height. Its `<use>` MUST have positive finite unitless `width` and `height`; an explicit `px` suffix is read-compatible. |+| Aspect ratio | Default/aligned `meet` values and plain `preserveAspectRatio="none"` are supported. `slice`, `refX`, and `refY` are forbidden. |+| Viewport boundary | Symbol artwork MUST stay inside its `viewBox`; expansion does not reproduce symbol overflow clipping. |+| Internal references | Author exact `href="#id"` and `url(#id)` fragments. The expander also reads legacy `xlink:href="#id"` and rewrites all instance-local cloned IDs. |+| Structural metadata | Neither the `<use>` instance nor its referenced subtree may carry `data-pptx-layer*`, chart/table replacement metadata (`data-pptx-replace-with`, `data-pptx-replacement-*`, `data-pptx-import-source`, or `data-pptx-fallback-*`), or `data-pptx-placeholder*`. Author those objects directly instead of reusing them. |+| Safety limits | A reachable reference chain may contain at most 64 instances, and one SVG may expand at most 10,000 local `<use>` instances. |++**Forbidden — unsafe local references**:++- External/file/data URLs, missing targets, conflicting `href` / `xlink:href`,+ unsupported target elements, and circular reference chains+- Duplicate IDs on the referenced target, the `<use>` instance, or anywhere in+ the reused subtree+- Quoted/whitespace CSS fragment variants such as `url('#id')`; use exact+ `url(#id)` when an internal paint/filter/clip reference must be rewritten++**Contract example**:++```xml+<svg xmlns="http://www.w3.org/2000/svg">+ <defs>+ <symbol id="statusDot" viewBox="0 0 20 20" preserveAspectRatio="xMidYMid meet">+ <circle cx="10" cy="10" r="8" fill="#16A34A"/>+ </symbol>+ <g id="legendRow">+ <rect width="120" height="32" rx="8" fill="#F1F5F9"/>+ <text x="42" y="22" font-size="16" fill="#0F172A">Ready</text>+ </g>+ </defs>+ <use href="#statusDot" x="80" y="120" width="32" height="32"/>+ <use href="#legendRow" x="120" y="120"/>+</svg>+```++---++### 1.4 Imported Native PowerPoint Shapes (Conditional Contract)++`pptx_to_svg.py` emits rendering-neutral metadata when a visible SVG object+originates from `p:sp`, `p:cxnSp`, or `p:grpSp`. This contract is for lossless+import SVGs and unchanged imported objects that remain Slide-local or inside a+slot during mirror materialization. Ordinary authored SVG does not need these+attributes, and no separate source-payload opt-in marker exists.++| Metadata | Placement | Required behavior |+|---|---|---|+| `data-pptx-object` | Logical `<g>` and native carrier | `shape`, `connector`, `group`, or `picture`; never infer the object kind from path appearance. |+| `data-pptx-shape-id` + `data-pptx-shape-scope` | Logical `<g>` and carrier | Preserve the source part-scoped identity. Export remaps duplicate Master/Layout/Slide ids into page-unique ids before rebinding connector references. |+| `data-pptx-frame="x y width height"` | Logical `<g>` and carrier | Own native `a:xfrm` position and size. Lossless import SVGs and tool-side native records use sufficient precision for exact EMU recovery; the model-facing authoring IR may use the compact page-coordinate spelling defined below. Path bounds, stroke, markers, shadows, and text glyph bounds never replace this frame. |+| `data-pptx-prst` | Preset carrier and logical `<g>` | One of the locked 187 DrawingML `ST_ShapeType` values. |+| `data-pptx-av-*` | Preset carrier and logical `<g>` | Preserve the complete validated DrawingML adjustment formula, including non-`val` formulas. |+| `data-pptx-part="geometry"` | One hidden carrier path | The single native export authority for frame, base fill/line/effect, preset/custom geometry, and object identity. |+| `data-pptx-part="geometry-preview"` / `geometry-detail` | Visible preview group/paths | Render the preset's independent path fill/stroke layers. A hash-locked preview group may mirror the carrier's one filter so a multi-path preset renders one aggregate imported effect; these elements are never emitted as duplicate PowerPoint shapes. |+| `data-pptx-preview-sha256` | Logical preset `<g>` and carrier | Detect edits to visible preset paths or paint. A stale preview fails quality check/export instead of silently reusing old native metadata. |+| `data-pptx-geometry-kind="custom"` + `data-pptx-custgeom` or `data-pptx-custgeom-ref` | Custom-geometry carrier | Preserve the validated original `a:custGeom` subtree. If the visible path hash is unchanged, export writes formulas, handles, connection sites, text rectangle, and path list exactly; edited paths compile from current SVG geometry. |+| `data-pptx-start/end-shape-id/site` | Connector logical `<g>` and carrier | Restore `a:stCxn` / `a:endCxn` after scoped shape-id allocation. A connector may retain one zero frame axis; it must not be expanded from visible stroke or marker bounds. |+| `data-pptx-shape-style` or `data-pptx-shape-style-ref` | Native carrier | Preserve a relationship-free `p:style` independently of text, including shapes with no visible text. |+| `data-pptx-effect-status="unsupported"` + `data-pptx-effect-reason` | Imported `p:sp` / `p:cxnSp` logical object and native carrier; imported `p:pic` carrier and logical object; imported `p:grpSp` logical group; imported table `p:graphicFrame` logical group | Record why an encountered source object or text-run `effectLst` / `effectDag` cannot enter the registered target-specific effect mapping without changing semantics. Checker and export stop with the recorded reason; these attributes are diagnostics, not a preserved effect payload or authoring syntax. |+| `metadata[data-pptx-part="txbody"]` with inline Base64 or `data-pptx-ref` | Logical shape `<g>` | Preserve unchanged `p:txBody`, including an empty text body. Content, whitespace, positioning, visible typography, or incompatible child-topology edits invalidate the payload. A source payload with run-level effects then blocks checker/export instead of losing those effects; an effect-free payload uses the normal SVG text fallback. |++**Hard rule — compact native metadata transport**: Type A mirror+materialization moves `p:txBody`, relationship-free `p:style`, and+`a:custGeom` payloads into the content-addressed+`templates/native_payloads.json.gz` store. It also deduplicates repeated native+restoration fields—object identity, frame, preset/custom-geometry guards,+preview/text hashes, connector endpoints, payload references, and adjustment+formulas—into short `data-pptx-native-ref` records in the same store. Checker,+template-structure validation, and export validate and hydrate both layers in+memory. Keep Master/Layout, placeholder, layer, editable-object, diagnostic,+and editable chart/table metadata inline. Legacy inline Base64 and v1+payload-only stores remain readable.++One effect reason remains its existing plain token. If one imported object has+multiple independent unsupported reasons, both marker copies store the same+deduplicated, lexicographically sorted compact JSON string array in+`data-pptx-effect-reason`; adding a later reason must not overwrite an earlier+one. This array is still diagnostic metadata, not an authoring surface.++**Import/authoring representation split**:++| Representation | Contract |+|---|---|+| Lossless import SVG | Keep complete native payload, hidden carriers, and preview evidence in the temporary analysis workspace. It is immutable native-payload backing, not the editable template source. |+| Authoring IR bundle | Keep editable SVGs plus model-readable `authoring_summary.json` and tool-only `authoring_manifest.json`. Exclude opaque payload and duplicate hidden carriers from model context while retaining visible shape intent and a stable document-local `data-pptx-source-ref` on each imported logical object. Compact model-facing imported frames and safe transform page coordinates to at most two decimals before hashing the IR. The summary owns the compact current-file index; the manifest owns source paths and initial hashes and never enters model context. |+| `standard` / `fidelity` output | Use the compact authored-preset contract (§1.5) for newly authored stock shapes; do not transplant opaque import payload or source topology. |+| `mirror` output | Materialize from the edited authoring IR. Rehydrate supported imported metadata only when a Slide-local/slot object's source ref and initial authoring hash still match; otherwise keep the current SVG fallback. Expand fixed Master/Layout group wrappers into direct semantic atoms while preserving source ownership, paint order, and visible appearance. |++**Hard rule — model-facing page-coordinate precision**:++| Surface | Precision contract |+|---|---|+| Imported `data-pptx-frame` in authoring IR | At most two decimals. An unchanged mirror source ref recovers the exact lossless frame before tool-side native-record externalization. |+| `data-pptx-placeholder-bounds` in final template SVG | At most two decimals. |+| `translate(...)`, `rotate(... cx cy)`, and `matrix(... e f)` | Translation values and rotation centers use at most two decimals. Keep the rotation angle and matrix `a b c d` coefficients unchanged. |+| Protected values | Do not apply this compaction to path/points geometry, normalized crop or nested `viewBox` ratios, gradient offsets, opacity, scale arguments, canonical authored-preset frames, or lossless/tool-side native frames. |++**Hard rule — authoring source refs**: `data-pptx-source-ref` is reserved for+the create-template authoring IR. Its value is unique within one authoring SVG,+not across the workspace, and must be resolved through that document's+`authoring_manifest.json` record by the owning tool. Models MUST NOT read that+machine manifest. Moving a referenced subtree into+`icons/imported/` for readability must preserve the attribute and record it in+the vector inventory; re-inlining re-establishes the same mapping. Final materialized+template SVGs and normal project `svg_output/` must not contain this attribute.++**Hard rule — structural-layer boundary**: An unchanged imported logical object+may keep currently supported metadata while it remains Slide-local or inside a+slot. An imported logical `<g>` cannot be assigned to Master/Layout because+those layers require direct semantic atoms. Mechanically expand a fixed-layer+source group into direct atoms, rebuilding a preset when supported and+otherwise retaining the visible SVG fallback. A newly authored compact preset+`<g>` from §1.5 is the sole group exception: validation proves that it compiles+to exactly one native shape/connector. Do not use this normalization to change+ownership or appearance.++**Hard rule — selective payload**: Do not copy every imported metadata block into+an authored template. Keep the full lossless import SVG separately as immutable+audit/fallback backing. Mirror may reuse only metadata already supported by the+converter on source-ref/hash-matching Slide-local/slot objects; unsupported or+edited objects use the current SVG fallback. `data-pptx-replace-with` remains reserved for the+optional PowerPoint-native Chart/Table replacement contract.++**Registry and rendering rules**:++- The hash-locked shared registry must equal the independent 187-value shape+ catalog. Missing, duplicate, unknown, or corrupt definitions fail closed.+- Preset preview paths come from the shared DrawingML formula evaluator; do not+ add per-shape Python geometry handlers.+- Preset size is controlled only by `data-pptx-frame` / `a:xfrm`. Adjustment+ formulas control the contour inside that frame and are not rescaled when the+ frame changes.+- A group transform may move, scale, rotate, or flip the complete logical+ shape without invalidating its preview fingerprint. Editing a generated+ `geometry-detail` path directly is unsupported unless the carrier metadata+ and preview fingerprint are regenerated together.+- Unknown or malformed SVG transform operations fail closed. DrawingML cannot+ represent arbitrary shear, so a non-orthogonal transform must stop native+ export instead of being silently approximated as rotation and scale.+- Opaque XML payloads containing any `r:*` relationship attribute are never+ copied into a new slide part. Relationship-bearing text content and+ shape-level `a:blipFill` use the existing rebuilt visual fallback and are+ not covered by atomic `p:sp + p:txBody` rehydration.+- Unknown future presets and explicit `unsupported` geometry status never+ downgrade silently to `rect`; native export stops with the recorded reason.++**Fidelity boundary**: native preset/custom geometry, logical frame, scoped+identity, connector topology, and relationship-free unchanged horizontal+text-body semantics on ordinary shape fills are `Native-stable`. The SVG+preview paint for gradient/pattern+`darken`/`lighten` layers is `Native-normalized`; original group child+coordinates, shape-level image-fill reconstruction, and vertical-text+reconstruction are also normalized rather than byte-identical OOXML.++---++### 1.5 Authored Native PowerPoint Presets (Conditional Contract)++New SVG pages and project-owned canonical reusable templates may opt one+complete geometric object into a native DrawingML preset through the+deterministic fragment helper. Selection behavior lives in+[`native-shape-authoring.md`](./native-shape-authoring.md); this section owns+the machine contract. This compact canonical form describes the intended+preset, frame, adjustments, and paint once, keeps only registry-generated+visible SVG paths, and embeds no source OOXML or serialized preview fingerprint.++| Metadata / structure | Required behavior |+|---|---|+| `data-pptx-authoring="preset"` | Appears once on the logical `<g>`; distinguishes strict project authoring from legacy/imported metadata. |+| `data-pptx-object` | `shape` or `connector`; connector-family presets must use `connector`, and `connector` must use a connector-family preset. Authored connectors require `fill="none"` plus a visible stroke and export as unconnected `p:cxnSp`. |+| `data-pptx-prst`, `data-pptx-frame`, `data-pptx-av-*` | Generated together from the locked registry and written once on the logical group. The frame is the helper's exact four-part, space-separated ordinary-decimal spelling and remains authoritative even when visible path bounds differ; commas, scientific notation, leading `+`, and redundant decimal spellings are rejected. |+| Local `fill` / `stroke` plus supported paint attributes | Base paint is written once on the group; a visible stroke also carries an explicit width. Canonical page/template authoring keeps channel paint local. Compatible ancestor paint/opacity may compose under the general SVG rules and receives a recommendation warning. |+| Ordered direct `<path>` children | Browser-visible registry layers only. Each child writes just its required path-level fill/stroke override; labels and decorations stay outside the atomic group. |+| No carrier / wrapper / fingerprint | `data-pptx-part`, hidden geometry carriers, preview wrappers, and `data-pptx-preview-sha256` belong to expanded import/compatibility transport, not canonical project authoring. |++Generate one fragment at a time:++```bash+python3 ${SKILL_DIR}/scripts/preset_shape_svg.py render rightArrow \+ --id p03-growth-arrow \+ --frame 160 210 320 112 \+ --fill "#2563EB" \+ --stroke none \+ --adjust "adj1=val 50000"+```++**Hard rule — helper-only metadata**: never add or edit authored preset+metadata or registry paths by hand. The compact helper output is atomic.+Regenerate it when preset, frame, adjustment, fill, stroke, or stroke width+changes. Replace the whole fragment with ordinary SVG when free contour editing+is required.++Template ownership metadata is orthogonal to preset geometry. After inserting+the complete helper output, `create-template` may add only the registered+`data-pptx-layer`, `data-pptx-editable`, `data-pptx-placeholder-carrier`, or+`data-pptx-role` attribute needed by the surrounding structured contract. It+must not change preset/frame/adjustment/paint metadata or any direct path.++**Reusable-template boundary**: a project-owned canonical template may retain+one complete helper-generated atomic fragment when the stock preset is an exact+semantic match and its paint stays inside the authoring boundary below. The+fragment is an executable exemplar and one semantic atom, not a freely editable+template primitive. It may be Slide-local, the one carrier of an `object` slot,+or a direct Master/Layout fixed atom. An adaptation may reuse it unchanged only+when preset, frame, adjustments, and paint are unchanged; otherwise regenerate+the whole fragment with the helper.+Imported, mirror, and third-party templates are never upgraded by contour+inference.++**Hard rule — visible page closure**: the helper prints a complete visible+fragment to stdout; export never invents its preview. The main Agent inserts+that output into the hand-authored page or canonical reusable template. The+helper cannot write a project, select layout, or generate a page.++**Authoring paint boundary**: v1 accepts `none` or six-digit solid HEX fill and+stroke, optional fill/stroke opacity, stroke width, line cap, and line join.+Generated pages take colors from `spec_lock.md`; `create-template` authored+templates take them from the confirmed brief and template `design_spec.md`.+Use ordinary SVG for gradients, patterns, filters, or other treatments outside+this narrow contract. Registry-derived multi-path darken/lighten colors are+authorized derivatives of the locked base paint and do not count as color+drift. Mirror preserves source paint under §1.4 instead.++**Validation**: quality check and export both rerender authored fragments from+`preset + frame + adjustments + group paint` and compare every visible path and+path-level paint override directly. Registry-path edits, geometry metadata that+leaves those paths stale, unknown adjustments, out-of-range frames/transforms,+zero-scale transforms, and shear/skew fail closed. Export expands the validated+compact group only in memory and reuses the lossless native-shape conversion+path. Older authored carrier/preview fragments remain compatible as ordinary+Slide-local input and+receive a non-blocking migration warning; they do not gain the new compact+group's structured-atom exception. `pptx_to_svg` expanded output remains the+lossless round-trip form and is not warned as authored input.++**Fidelity boundary**: an unchanged authored fragment is `Native-stable` as+one `p:sp` or `p:cxnSp`. Text remains outside the atomic fragment and may export+as a grouped editable text box. Authoring v1 creates only unconnected+`p:cxnSp`; it does not accept hand-written endpoint/site metadata. An+`actionButton*` preset maps visual geometry only. Preset appearance never+invents connector attachment, action behavior, navigation targets, or+hyperlinks.++---++## 2. Conditional Compatibility Mappings++### 2.1 Literal Geometry Lengths and Inline Geometry++**Hard rule — direct geometry length grammar**: New generated SVG writes the+following XML geometry values and `stroke-width` as finite unitless ordinary+decimals in the page `viewBox` coordinate space, for example `x="120"` and+`stroke-width="2"`. The explicit `px` suffix is read-compatible and receives a+recommendation warning. No other unit is registered for this surface.++| Element / surface | Direct length attributes |+|---|---|+| `<svg>`, `<rect>`, `<image>`, `<use>` | `x`, `y`, `width`, `height`; `<rect>` also `rx`, `ry` |+| `<circle>` | `cx`, `cy`, `r` |+| `<ellipse>` | `cx`, `cy`, `rx`, `ry` |+| `<line>` | `x1`, `y1`, `x2`, `y2` |+| `<text>` / positional `<tspan>` | `x`, `y`; `<tspan>` also `dx`, `dy` |+| Any supported painted element | `stroke-width` |++`width`, `height`, `r`, `rx`, `ry`, and `stroke-width` must be non-negative;+the stricter positive `<use>` symbol-viewport rule remains in §1.3. `pt`,+`pc` / `pica`, `in`, `cm`, `mm`, `q`, `em`, `rem`, percentages, unknown units,+non-finite values, expressions, scientific notation, leading plus signs, and+trailing decimal points are invalid here even when generic SVG/CSS defines+them. A missing attribute may use its documented SVG/project default; an+explicitly supplied invalid value never falls back to that default.++The following geometry properties may appear in the same element's+`style="..."`. The pipeline materializes them as+XML geometry attributes before SVG post-processing and native PPTX conversion.+An inline geometry declaration overrides an existing same-name XML attribute.++| Element | Recognized properties |+|---|---|+| `<rect>` | `x`, `y`, `width`, `height`, `rx`, `ry` |+| `<circle>` | `cx`, `cy`, `r` |+| `<ellipse>` | `cx`, `cy`, `rx`, `ry` |+| `<image>` | `x`, `y`, `width`, `height` |+| `<svg>` | `x`, `y`, `width`, `height` |+| `<use>` | `x`, `y`, `width`, `height` |++**Hard rule — inline geometry grammar**: every non-zero value is one finite+`px` literal, such as `120px` or `-8.5px`; exact zero may be unitless. `width`,+`height`, `rx`, `ry`, and `r` must be non-negative. Percentages, `auto`,+`calc()`, `var()`, `!important`, `inherit`, and every other unit are forbidden.+Do not put geometry on an unsupported element: line endpoints, text positions,+path data, and polygon/polyline points remain XML attributes.++**Forbidden — CSS geometry cascade**: `<style>`, `class`, selector rules,+external stylesheets, and imported styles remain forbidden. This contract is+only for literal declarations in an element's own `style` attribute; PPT Master+does not compute CSS cascade or custom properties. Root canvas authority remains+the `viewBox`, regardless of root `<svg>` compatibility width/height values.++### 2.2 Group Opacity Compatibility++**Default — descendant alpha (may preserve compatible group opacity)**: New+`svg_output/` and reusable templates put alpha on the affected descendant+paint, text run, picture, or supported effect. DrawingML has no isolated+group-alpha model, so overlapping descendants can look different when one+group value is distributed across them.++The converter nevertheless accepts `<g opacity="...">` and inline group+`opacity` by multiplying group alpha into descendants. That path is+`Approximate`; nested group/child alpha multiplies, and `--native-charts-and-tables`+rejects transparent native table/chart markers. The quality checker reports a+non-blocking fidelity warning so existing or intentionally authored input can+continue without modification.++---++## 3. Canvas Format Quick Reference++Use the already locked canvas id and exact viewBox. [`canvas-formats.md`](canvas-formats.md) owns format selection; this core owns only SVG conformance on that canvas.++---++## 4. Required Page Contract and Conditional Packaging++### 4.0 Complete Page-Design Contract++| Concern | Requirement |+|---|---|+| Visible slide result | The completed `svg_output/<slide>.svg` MUST contain every visible text, image, shape, diagram, chart/table fallback, background, and template-derived layout element intended for that slide. External visual assets are valid when the SVG references them explicitly. |+| Template/control inputs | Templates, `design_spec.md`, and `spec_lock.md` guide authoring. Do not depend on them to add visible elements after the page SVG is complete. |+| PPTX translation | The exporter may map represented SVG content to DrawingML/native objects and deduplicate represented elements into Master/Layout/Slide parts. It MUST NOT invent visible slide content absent from the SVG. |+| Excluded package behavior | Speaker notes, animations, transitions, narration audio, PPTX relationships, and direct native-PPTX workflows remain separately owned. They are not part of the SVG page-design contract. |++**Hard rule — page-design closure**: A final page SVG is the sole visual/design authority for that page on every SVG-authoring route. SVG is not the authority for the entire PPTX package.++### 4.1 Semantic SVG Marker Contract++Semantic markers are minimal compiler hints. Flat pages declare one root `data-pptx-page-role` and omit Master/Layout/layer/placeholder markers. Structured pages carry their final root identity, layer atoms, slots, and native-object metadata from authoring start and omit `data-pptx-page-role`. Use `data-pptx-role` with a stable `id` only when no specialized marker expresses page-frame behavior. Keep ordinary visible content in SVG attributes/text; [`semantic-svg.md`](semantic-svg.md) owns the vocabulary.++- **Canvas authority**: New authoring writes `viewBox="0 0 W H"` with positive+ integer pixels from the lock. Numerically equivalent spellings and positive+ fractional imported dimensions remain compatible; export quantizes once at+ `1 SVG px = 9,525 EMU`. Invalid/non-finite values, non-zero origin,+ non-positive size, or unsupported PowerPoint dimensions are errors. All pages+ and Layout prototypes in one build share the numeric canvas and match+ `spec_lock.md canvas.viewBox`; standalone templates match `design_spec.md+ canvas_viewbox`. Optional root `width`/`height` do not override `viewBox`.+ Root `<svg>` transform is forbidden; nested crop and `<symbol viewBox>` keep+ their own contracts.+- **Font portability**: font families used by the deck must resolve to installed+ export faces. `@font-face` remains forbidden; the typography contract lives in+ [`strategist.md §g`](strategist.md).+- **Icon placeholders**: `<use data-icon="library/name">` is a pipeline-specific+ form, distinct from local SVG reuse. Follow the contract in+ [`../templates/icons/README.md`](../templates/icons/README.md).+- **Local reuse**: ordinary same-document `<use>` follows §1.3.++### 4.2 Conditional Editability and Package Promotion++These forms are needed only when the stated PPT behavior matters:++| Desired behavior | Required form |+|---|---|+| One editable PPT text frame with mixed inline formatting | Put the logical line in one `<text>` with non-positional `<tspan>` children. A `<tspan>` with `x`/`y`/`dy` starts a new positioned line. Evenly `dy`-stacked lines that repeat the parent `<text>`'s `x` stay in one frame: equal effective `font-size` may flow in the current paragraph, while a font-size change, list marker, or accepted larger gap starts a new paragraph. An unmergeable gap or mismatched `x` flattens to separate frames. Separate `<text>` elements stay valid when separate frames are intended. |+| Stable object grouping or object-level animation anchor | Wrap the intended object in `<g id="...">`. Content grouping is **mandatory** per §4.3 — a top-level `<g id>` is also the animation anchor; it is not an optional convenience. |+| Native PowerPoint background promotion | Outside structured mode, the first eligible visual layer may be a direct full-canvas `<rect>` or one inside a simple single-child group. Its fill must have a registered native mapping (solid, linear/radial gradient, or preset pattern), and it must have no transform, filter, clip, rounding, or visible stroke. Export writes the fill as Slide `p:bg`; image elements remain pictures. Structured routes use the narrower explicit solid-background ownership contract in [`pptx-structure-interface.md`](./pptx-structure-interface.md). |+| Free-design / brand-only PowerPoint structure | Use `pptx_structure.mode: flat`. Keep every represented object Slide-local; export materializes one clean project-owned Master plus one Blank Layout from the current lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. Do not author Master/Layout identities, layers, or placeholder slots. |+| Reusable template-based PowerPoint Layout | Select one complete authoring SVG per page in `page_layouts`, declare each unique Master/Layout definition once, and assign pages through `page_pptx_layouts`. Strict preserves the prototype contract; adaptive retains its Master and may define and assign a new explicit Layout key during page authoring. Non-mirror skin follows `spec_lock`. |++**Hard rule — supported shape conversion**: Every PPT editability claim in this specification refers to the project converter reading `svg_output/` and emitting native DrawingML. `svg_final/` is a self-contained visual preview that may be inserted into PowerPoint as an SVG picture. PowerPoint's manual Convert-to-Shape operation is unsupported; do not narrow the authoring contract to its undocumented SVG subset.++### 4.3 Element Grouping (Mandatory)++Wrap logically related Slide-local elements in top-level `<g id="...">` groups. This is **required on every generated page**, not an optional convenience: it produces real PowerPoint groups in the exported PPTX and gives each content unit a stable animation anchor. Plain `<g>` is the grouping primitive; keep alpha on individual descendants per §2.2. Flat free-design/brand-only pages use only ordinary semantic groups. On structured template pages, direct atomic Master/Layout elements are the required exception and a top-level slot `<g>` is already a semantic group. Nested implementation groups inside one named content unit may remain anonymous unless another specialized contract requires an id; they are not independent animation targets.++**Semantic-group rule**: direct Slide content uses semantic groups. Aim for **3–8 ordinary top-level content `<g id>` groups per slide**; on structured template pages, slot groups and atomic Master/Layout objects are excluded. Each ordinary group becomes one entrance step under the chosen animation trigger. Leaving Slide-local titles, body lines, list items, cards, or decorative clusters as ungrouped top-level atoms is an authoring-contract violation reported as an aggregate Checker warning.++**Structural atoms and slots are excluded automatically.** `data-pptx-layer` and `data-pptx-placeholder` semantics are read first; otherwise explicit `data-pptx-role` values (`background`, `decoration`, `header`, `footer`, `chrome`, `watermark`, `page-number`, `logo`) mark Slide-local static framing (§4.1, [`semantic-svg.md`](semantic-svg.md)). A normal slot group has exactly one direct compatible carrier; several drawing atoms require the explicit composite `object` proxy fallback. Native chart/table carrier groups retain their specialized [`native-data-interface.md`](./native-data-interface.md) contract.++**What to group** (one `<g id>` per unit):++| Grouping unit | Contains |+|---|---|+| Card / panel | Background rect + optional shadow (only if it floats over a photo/colored panel, [`svg-effects.md`](./svg-effects.md) §6.4) + icon + title + body text |+| Process step | Number/marker + icon + label + description |+| List item | Bullet / number + icon + title + description |+| Icon-text combo | Icon element + adjacent label |+| Page header | Title + subtitle + accent decoration |+| Page footer | Page number + branding |+| Decorative cluster | Related decorative shapes (rings, dots, orbs) |++An authored native preset fragment (§1.5) is already an atomic `<g id>` and+counts as one content group. Keep it top-level when it stands alone. When it+needs a label or decoration, place the preset and those siblings inside a+separate parent content group; never put them inside the preset group itself.++**Forbidden**:++- One giant `<g>` around the whole slide (collapses to a single animation step).+- Many ungrouped Slide-local `<rect>` / `<text>` / `<path>` atoms — they have no stable sidecar target and selection/editing degrades. Primitive fallback applies only when the root contains no top-level `<g>` at all; it is capped at 8 visible primitives.+- One group per icon / text line / mark (too many steps).+- Anonymous top-level groups — every top-level semantic group needs a descriptive `id`.++**Naming — required.** A descriptive, page-unique `id` on every top-level content `<g>` (`card-1`, `step-discover`, `header`, `footer`) is mandatory; it is the stable SVG-side animation and trace anchor. An anonymous top-level group still converts, but `animations.json` cannot reference it; an anonymous one-child implementation wrapper may also flatten. Primitive fallback is unrelated and applies only to roots with no top-level groups.++```xml+<g id="card-benefits-1">+ <!-- Shadow only if the card floats over a colored panel; on flat white, omit it. -->+ <rect x="60" y="115" width="565" height="260" rx="20" fill="#FFFFFF" filter="url(#shadow)"/>+ <use data-icon="chunk-filled/bolt" x="108" y="163" width="44" height="44" fill="#0071E3"/>+ <text x="105" y="270" font-size="56" font-weight="bold" fill="#0071E3">10×</text>+ <text x="250" y="270" font-size="30" font-weight="bold" fill="#1D1D1F">Faster</text>+ <text x="105" y="310" font-size="18" fill="#6E6E73">Reduce production time from days to hours.</text>+</g>+```++---++## 5. Workflow Authority++The serial post-processing and export workflow belongs to+[`generate-pptx.md`](../workflows/generate-pptx.md) Step 7. This file defines SVG authoring boundaries+and intentionally does not mirror commands, flags, or output behavior.++---+++## 8. Scope Boundary++Generate project structure, commands, quality-gate order, and export products+are owned by [`generate-pptx.md`](../workflows/generate-pptx.md). They are+intentionally outside this SVG authoring policy.diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.mdindex 51b76dc9..b93747eb 100644--- a/skills/ppt-master/references/shared-standards.md+++ b/skills/ppt-master/references/shared-standards.md@@ -1,1959 +1,12 @@# Shared Technical Standards-Mandatory reference for every PPT Master route that authors or regenerates slide visuals through SVG: owns shared XML/SVG constraints, editable PPTX mappings, advanced effects, geometry recipes, and PPT-specific interfaces.-Other files link here instead of restating its contracts.+Compatibility router for the split SVG technical specifications. Runtime routes load the core plus only the modules triggered by the current lock and page features.-**Document map**:--| Section | Owns | Strength |-|---|---|---|-| §1 Required Foundation, Forbidden Features, and Conditional Interfaces | XML validity, the closed generated-authoring surface, structural blacklist, native line ends, image clipping, static local reuse, and imported/authored native-shape semantics | Required / Forbidden / Conditional |-| §2 Conditional Compatibility Mappings | Direct geometry-length grammar, literal inline geometry, and the approximate group-opacity compatibility boundary | Required / Conditional / Default |-| §3 Canvas Format Quick Reference | Pointer to the complete canvas catalog | Reference |-| §4 Required Page Contract and Conditional Packaging | Complete-page authority, semantic markers, editable text/grouping, and package promotion | Required / Conditional |-| §5 Workflow Authority | Pointer to the serial post-processing/export procedure | Workflow pointer |-| §6 Advanced SVG Effects and Authoring Techniques | Color/alpha, gradients, shadows, glow, overlays, lines, text treatments, transforms, freeform geometry, chart geometry, and constructed visual styles | Contract + optional recipes |-| §7 Conditional PPT Interfaces | Pattern fills, native tables/charts, Master text styles, and Master/Layout/placeholder metadata | Conditional |-| §8 Scope Boundary | Concerns intentionally owned by another reference or workflow | Boundary |--**Advanced capability index**:--| Capability family | Available authoring vocabulary | Detail |+| Scope | Authority | Trigger ||---|---|---|-| Color and transparency | Default opaque `#RRGGBB` paint plus channel-specific alpha; compatible CSS-color spellings, picture/atomic-element opacity, and approximate group opacity | §2.2, §6.2 |-| Gradients and paint | Linear/radial fills, transparent stops, gradient text, gradient strokes, and preset patterns | §6.3, §7 |-| Depth and light | Soft/colored/directional shadow, glow, layered-geometry fallback, and paper-layer elevation | §6.4 |-| Image treatment | Directional scrim, bottom fade, vignette, spotlight, brand wash, picture fading, and glass-like surfaces | §1.2, §6.5 |-| Lines and connectors | Preset/custom dash, cap/join, gradient flow strokes, markers, and explicit-grid paths | §1.1, §6.6 |-| Text treatments | Mixed runs, tracking, underline, strikethrough, gradient fill, outline, transparency, watermark text, and text glow | §4.2, §6.7 |-| Transforms and composition | Translate, scale, rotate, mirror, supported matrix composition, layering, and static local reuse | §1.3, §6.8 |-| Freeform geometry | Full SVG path vocabulary, curves, organic containers, multi-subpaths, and asymmetric rounded rectangles | §6.9 |-| Imported PowerPoint shapes | Immutable lossless payload backing, editable authoring IR, and selective rehydration of preset/custom geometry, connectors, and unchanged native text bodies | §1.4 |-| Authored PowerPoint preset shapes | Registry-generated visible fragments that export as one native preset shape or connector | §1.5; [`native-shape-authoring.md`](./native-shape-authoring.md) |-| Radial/chart geometry | Pie/donut arcs, dashed-circle ring segments, gauges, progress rings, sunbursts, and diagonal polygon arrowheads | §6.10 |-| Constructed visual styles | Faux glass, hand-drawn marks, ink wash, Riso offset, pixel grid, halftone, isometric facets, paper cut, and line-plus-area data treatment | §6.11 |-| Unsupported-effect fallbacks | Raster baking or explicit-geometry alternatives for blur, inner shadow, soft edge, reflection, turbulence, blend modes, and arbitrary masks | §6.12 |-| Selection quick reference | Grouped scenario routing; fidelity remains in owning subsections | §6.13 |--**Fidelity labels**:--| Label | Meaning |-|---|---|-| `Native-stable` | Generated PPTX uses the corresponding native DrawingML property or object and retains the documented semantics within the technique-specific limits. |-| `Native-normalized` | Export targets an editable DrawingML equivalent, but normalizes the SVG into another structure such as a freeform, run property, or simplified paint/effect. |-| `Approximate` | DrawingML has no exact SVG equivalent; export targets the intended effect through a documented approximation, and material differences require output review. |-| `Bake-required` | The runtime effect is outside the native contract; pre-render it into an image or rebuild it with explicit supported geometry. |--**Reading rules**:--- **Required** / **Forbidden** statements are non-negotiable technical boundaries.-- **Conditional** contracts apply only when the corresponding feature is used.-- **Reference — not a constraint** passages expose capabilities and recipes; they do not require every page or visual style to use them.-- The locked `visual_style` controls whether and how strongly a compatible effect is used. It never expands the technical boundary.--**Hard rule — generated authoring is fail-closed**: `svg_output/` and reusable-template SVGs may use only properties and conditional interfaces explicitly-listed in this file. `svg_quality_checker.py` rejects unknown inline visual-properties and conditional contracts that have no reliable compatibility-mapping; documented fallback forms remain valid and receive warnings.--**Default — recommended authoring and supported input stay separate (may-preserve supported input)**: generated SVG uses one predictable default-spelling, while converter-supported equivalent spellings remain valid input.-The checker may recommend normalization, but such warnings do not require-modification or block export. Only invalid, unsafe, or unreliably convertible-input is an error; do not remove converter support to enforce a narrower-generation preference.--**Hard rule — one-way fidelity vocabulary**: the labels above describe the-`svg_output/` → generated PPTX path. They do not promise reconstruction of the-original SVG syntax, `<defs>` graph, `<use>` structure, path commands, or-`<tspan>` layout after PPTX-to-SVG import, nor pixel identity across PowerPoint,-LibreOffice, Keynote, and WPS.--**Hard rule — capability boundary**: a recipe never expands converter support.-Use only the target elements and syntax documented by each conditional-contract. Unsupported element tags fail preflight; browser-rendered attributes-outside these contracts must not be assumed to have a DrawingML mapping.-------## 1. Required Foundation, Forbidden Features, and Conditional Interfaces--### 1.0 Text characters: must be well-formed XML--SVG is strict XML. Two rules for all text and attribute values:--| Character category | Required form | Forbidden form |-|---|---|---|-| Typography & symbols (em dash, en dash, ©, ®, →, ·, NBSP, full-width punctuation, emoji…) | **Raw Unicode characters** — write `—` `–` `©` `®` `→` directly | HTML named entities — `—` `–` `©` `®` `→` `·` ` ` `…` `•` etc. |-| XML reserved characters (`&`, `<`, `>`, `"`, `'`) | **XML entities only** — `&` `<` `>` `"` `'` (e.g. `R&D`, `error < 5%`) | Bare `&` `<` `>` (e.g. `R&D`, `error < 5%`) |--One offending character invalidates the file and aborts export.--**Structural blacklist** (in addition to the character rules above):--| Banned Feature | Description |-|----------------|-------------|-| `mask` | Masks |-| `<style>` | Embedded stylesheets |-| `class` | CSS selector attributes |-| External CSS | External stylesheet links |-| `<foreignObject>` | Embedded external content |-| `textPath` | Text along a path |-| `@font-face` | Custom font declarations |-| `<animate*>` / `<set>` | SVG animations |-| `<script>` / event attributes | Scripts and interactivity |-| `<iframe>` | Embedded frames |--The blacklist above is exhaustive for globally forbidden structural syntax.-It is not a positive allowlist for every browser-rendered property. Features-that require a restricted form are valid only under the conditional contracts-below; unlisted visual properties are unsupported.--**Hard rule — inline visual-property allowlist**:--| Property family | Allowed inline `style` properties |-|---|---|-| Paint and line | `fill`, `stroke`, `stroke-width`, `stroke-dasharray`, `stroke-linecap`, `stroke-linejoin`, `fill-opacity`, `stroke-opacity`, `vector-effect` |-| Text | `font-family`, `font-size`, `font-weight`, `font-style`, `text-anchor`, `letter-spacing`, `text-decoration` |-| Alpha and definition paint | `opacity`, `stop-color`, `stop-opacity`, `flood-color`, `flood-opacity` |-| Literal geometry | The element-specific properties in §2.1 |-| Preview-only | `shape-rendering`; it does not change native geometry |--**Default — one generated value spelling (may preserve supported input)**: the-table allows inline placement of those property names. New generated paint-prefers the spelling in §6.2 whether it appears as an attribute or inside-`style`. Converter-compatible aliases remain valid input in both locations and-produce recommendation warnings rather than errors.--Conditional properties with a required XML form stay out of inline style:-write `filter="url(#id)"`, `clip-path="url(#id)"`, and-`marker-start` / `marker-end` as direct attributes. `!important`, unknown CSS-properties, blend modes, isolation, and backdrop filters fail quality check.--The table registers property names, not arbitrary CSS values. Text property-values and their element-specific placement are a closed grammar owned by-§6.7; unknown or unmapped declarations on `<text>` / `<tspan>`, and unsupported-inherited text properties, fail both Checker preflight and native export.--> **`marker-start` / `marker-end` is conditional** — see §1.1.->-> **`clipPath` on `<image>` is conditional** — see §1.2.->-> **Static same-document `<use>` is conditional** — see §1.3.->-> **Imported native-shape metadata is conditional** — see §1.4.->-> **Authored native preset fragments are conditional** — see §1.5.->-> **Inline CSS geometry, simple gradients, filters, and approximate group-> opacity are conditional** — see §2 and §6.->-> **PPT preset patterns and native chart/table/template metadata are-> conditional** — see §7.--DrawingML has no arbitrary per-pixel alpha-compositing path. Effects that rely-on one, including text-knockout image fills and arbitrary alpha composites,-must be baked into a raster asset before SVG export.-------### 1.1 Line-end Markers (Conditional Contract)--`marker-start` and `marker-end` are supported on `<line>` and `<path>` only-when the referenced marker fits this native-arrow contract:--| Concern | Required form |-|---|---|-| Reference | Exact local `url(#id)` to a `<marker>` in `<defs>` |-| Orientation | `orient="auto"` or `orient="auto-start-reverse"`; the latter reverses `marker-start` while behaving like `auto` at `marker-end` |-| Shape | One direct shape representing a DrawingML `triangle`, `stealth`, `arrow`, `diamond`, or `oval` line end: a 3-vertex `<polygon>` / closed path (triangle), a simple concave 4-vertex `<polygon>` / closed path (stealth), an open 3-vertex path (arrow), a simple convex 4-vertex `<polygon>` / closed path (diamond), or one `<circle>` / `<ellipse>` (oval) |-| Path grammar | Use one explicit `M`/`L` command per vertex. Triangle, stealth, and diamond paths end in `Z`; arrow paths remain open after the third vertex. Do not use `H`, `V`, curves, or an implicit multi-point `L` command inside a marker path |-| Color parity | Triangle, stealth, diamond, and oval use a fill matching the parent line stroke. The open arrow uses `fill="none"` and a stroke matching the parent line stroke. DrawingML line ends inherit the line color |--The converter maps these five shapes to their corresponding DrawingML line-end-types. Prefer `<polygon>` for the closed triangle, stealth, and diamond forms;-the open arrow form requires `<path>`. Four-vertex shapes must be simple and-non-degenerate: convex geometry maps to diamond and concave geometry maps to-stealth. Checker and exporter preflight consume this same contract; other-marker shapes have no native mapping and block export instead of being silently-dropped.--PPTX import compatibility, tolerant recovery, strict-mode rejection, and-diagnostic behavior are indexed in-[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).-------### 1.2 Image Clipping (Conditional Contract)--`clip-path` has a native picture-geometry mapping only on SVG-namespace-`<image>` elements (plus the exact imported crop wrapper defined under Images)-and only under this contract:--| Concern | Required form |-|---|---|-| SVG-namespace `<clipPath>` defined inside `<defs>` | Converter looks up one exact local id; missing, duplicate, foreign-namespace, or malformed references fail |-| Contains exactly one direct SVG-namespace supported shape child | Multiple shapes are not composited |-| Shape is one of: `<circle>`, `<ellipse>`, `<rect>` (optional rx/ry), `<path>`, `<polygon>` | These map to DrawingML geometry (preset or custom) |-| No `clip-rule` or `fill-rule`, whether direct or in inline `style` | DrawingML picture geometry has no equivalent winding-rule control |-| Used only on `<image>` or an exact imported crop wrapper | Shapes, groups, text, and generalized nested SVG targets are **forbidden** |--| SVG clip shape | DrawingML output |-|---|---|-| `<circle>` / `<ellipse>` | Full-frame `<a:prstGeom prst="ellipse"/>`; the child must exactly cover the image frame. A `userSpaceOnUse` circle requires a square physical frame; a normalized `objectBoundingBox` circle may fill any frame |-| `<rect>` / `<rect rx="..."/>` | A plain full-frame rect is a compatible no-op; rounded form maps to full-frame `<a:prstGeom prst="roundRect"/>` with one physical radius adjustment. The rect must exactly cover the image frame and cannot express non-uniform physical corner radii |-| `<path>` / `<polygon>` | `<a:custGeom>` with coordinates mapped into the image frame |--`clip-path` on shapes, groups, or text is forbidden; author the target geometry-directly instead. Use a path/polygon clip when the intended contour does not-cover the full picture frame. A contour that depends on even-odd or another-explicit winding rule is outside this mapping and must be rebuilt as one-unambiguous visible contour or pre-rendered.-------### 1.3 Static Same-Document `<use>` (Conditional Contract)--**Expansion contract**: Static local reuse is compile-time authoring shorthand. `finalize_svg.py` and-native export replace each qualifying instance with cloned primitive content;-PPTX-to-SVG import emits the resulting primitives and does **not** reconstruct-the original `<use>` / `<symbol>` structure.--| Concern | Required form |-|---|---|-| Reference syntax | Author new SVG with the SVG 2 form `href="#id"`. Legacy `xlink:href="#id"` remains read-compatible and Live Preview normalizes it to `href`; if both attributes exist, their values MUST match. |-| Referenced target | One of `<symbol>`, `<g>`, `<use>`, `<rect>`, `<circle>`, `<ellipse>`, `<line>`, `<path>`, `<polygon>`, `<polyline>`, `<text>`, or `<image>`. Nested local `<use>` is recursively expanded. |-| Instance position | Generated `<use x>` / `<use y>` use finite unitless values; an explicit `px` suffix is read-compatible. Omitted values default to `0`. |-| Symbol viewport | A referenced `<symbol>` MUST have a finite four-number `viewBox` with positive width/height. Its `<use>` MUST have positive finite unitless `width` and `height`; an explicit `px` suffix is read-compatible. |-| Aspect ratio | Default/aligned `meet` values and plain `preserveAspectRatio="none"` are supported. `slice`, `refX`, and `refY` are forbidden. |-| Viewport boundary | Symbol artwork MUST stay inside its `viewBox`; expansion does not reproduce symbol overflow clipping. |-| Internal references | Author exact `href="#id"` and `url(#id)` fragments. The expander also reads legacy `xlink:href="#id"` and rewrites all instance-local cloned IDs. |-| Structural metadata | Neither the `<use>` instance nor its referenced subtree may carry `data-pptx-layer*`, chart/table replacement metadata (`data-pptx-replace-with`, `data-pptx-replacement-*`, `data-pptx-import-source`, or `data-pptx-fallback-*`), or `data-pptx-placeholder*`. Author those objects directly instead of reusing them. |-| Safety limits | A reachable reference chain may contain at most 64 instances, and one SVG may expand at most 10,000 local `<use>` instances. |--**Forbidden — unsafe local references**:--- External/file/data URLs, missing targets, conflicting `href` / `xlink:href`,- unsupported target elements, and circular reference chains-- Duplicate IDs on the referenced target, the `<use>` instance, or anywhere in- the reused subtree-- Quoted/whitespace CSS fragment variants such as `url('#id')`; use exact- `url(#id)` when an internal paint/filter/clip reference must be rewritten--**Contract example**:--```xml-<svg xmlns="http://www.w3.org/2000/svg">- <defs>- <symbol id="statusDot" viewBox="0 0 20 20" preserveAspectRatio="xMidYMid meet">- <circle cx="10" cy="10" r="8" fill="#16A34A"/>- </symbol>- <g id="legendRow">- <rect width="120" height="32" rx="8" fill="#F1F5F9"/>- <text x="42" y="22" font-size="16" fill="#0F172A">Ready</text>- </g>- </defs>- <use href="#statusDot" x="80" y="120" width="32" height="32"/>- <use href="#legendRow" x="120" y="120"/>-</svg>-```-------### 1.4 Imported Native PowerPoint Shapes (Conditional Contract)--`pptx_to_svg.py` emits rendering-neutral metadata when a visible SVG object-originates from `p:sp`, `p:cxnSp`, or `p:grpSp`. This contract is for lossless-import SVGs and unchanged imported objects that remain Slide-local or inside a-slot during mirror materialization. Ordinary authored SVG does not need these-attributes, and no separate source-payload opt-in marker exists.--| Metadata | Placement | Required behavior |-|---|---|---|-| `data-pptx-object` | Logical `<g>` and native carrier | `shape`, `connector`, `group`, or `picture`; never infer the object kind from path appearance. |-| `data-pptx-shape-id` + `data-pptx-shape-scope` | Logical `<g>` and carrier | Preserve the source part-scoped identity. Export remaps duplicate Master/Layout/Slide ids into page-unique ids before rebinding connector references. |-| `data-pptx-frame="x y width height"` | Logical `<g>` and carrier | Own native `a:xfrm` position and size. Lossless import SVGs and tool-side native records use sufficient precision for exact EMU recovery; the model-facing authoring IR may use the compact page-coordinate spelling defined below. Path bounds, stroke, markers, shadows, and text glyph bounds never replace this frame. |-| `data-pptx-prst` | Preset carrier and logical `<g>` | One of the locked 187 DrawingML `ST_ShapeType` values. |-| `data-pptx-av-*` | Preset carrier and logical `<g>` | Preserve the complete validated DrawingML adjustment formula, including non-`val` formulas. |-| `data-pptx-part="geometry"` | One hidden carrier path | The single native export authority for frame, base fill/line/effect, preset/custom geometry, and object identity. |-| `data-pptx-part="geometry-preview"` / `geometry-detail` | Visible preview group/paths | Render the preset's independent path fill/stroke layers. A hash-locked preview group may mirror the carrier's one filter so a multi-path preset renders one aggregate imported effect; these elements are never emitted as duplicate PowerPoint shapes. |-| `data-pptx-preview-sha256` | Logical preset `<g>` and carrier | Detect edits to visible preset paths or paint. A stale preview fails quality check/export instead of silently reusing old native metadata. |-| `data-pptx-geometry-kind="custom"` + `data-pptx-custgeom` or `data-pptx-custgeom-ref` | Custom-geometry carrier | Preserve the validated original `a:custGeom` subtree. If the visible path hash is unchanged, export writes formulas, handles, connection sites, text rectangle, and path list exactly; edited paths compile from current SVG geometry. |-| `data-pptx-start/end-shape-id/site` | Connector logical `<g>` and carrier | Restore `a:stCxn` / `a:endCxn` after scoped shape-id allocation. A connector may retain one zero frame axis; it must not be expanded from visible stroke or marker bounds. |-| `data-pptx-shape-style` or `data-pptx-shape-style-ref` | Native carrier | Preserve a relationship-free `p:style` independently of text, including shapes with no visible text. |-| `data-pptx-effect-status="unsupported"` + `data-pptx-effect-reason` | Imported `p:sp` / `p:cxnSp` logical object and native carrier; imported `p:pic` carrier and logical object; imported `p:grpSp` logical group; imported table `p:graphicFrame` logical group | Record why an encountered source object or text-run `effectLst` / `effectDag` cannot enter the registered target-specific effect mapping without changing semantics. Checker and export stop with the recorded reason; these attributes are diagnostics, not a preserved effect payload or authoring syntax. |-| `metadata[data-pptx-part="txbody"]` with inline Base64 or `data-pptx-ref` | Logical shape `<g>` | Preserve unchanged `p:txBody`, including an empty text body. Content, whitespace, positioning, visible typography, or incompatible child-topology edits invalidate the payload. A source payload with run-level effects then blocks checker/export instead of losing those effects; an effect-free payload uses the normal SVG text fallback. |--**Hard rule — compact native metadata transport**: Type A mirror-materialization moves `p:txBody`, relationship-free `p:style`, and-`a:custGeom` payloads into the content-addressed-`templates/native_payloads.json.gz` store. It also deduplicates repeated native-restoration fields—object identity, frame, preset/custom-geometry guards,-preview/text hashes, connector endpoints, payload references, and adjustment-formulas—into short `data-pptx-native-ref` records in the same store. Checker,-template-structure validation, and export validate and hydrate both layers in-memory. Keep Master/Layout, placeholder, layer, editable-object, diagnostic,-and editable chart/table metadata inline. Legacy inline Base64 and v1-payload-only stores remain readable.--One effect reason remains its existing plain token. If one imported object has-multiple independent unsupported reasons, both marker copies store the same-deduplicated, lexicographically sorted compact JSON string array in-`data-pptx-effect-reason`; adding a later reason must not overwrite an earlier-one. This array is still diagnostic metadata, not an authoring surface.--**Import/authoring representation split**:--| Representation | Contract |-|---|---|-| Lossless import SVG | Keep complete native payload, hidden carriers, and preview evidence in the temporary analysis workspace. It is immutable native-payload backing, not the editable template source. |-| Authoring IR bundle | Keep editable SVGs plus model-readable `authoring_summary.json` and tool-only `authoring_manifest.json`. Exclude opaque payload and duplicate hidden carriers from model context while retaining visible shape intent and a stable document-local `data-pptx-source-ref` on each imported logical object. Compact model-facing imported frames and safe transform page coordinates to at most two decimals before hashing the IR. The summary owns the compact current-file index; the manifest owns source paths and initial hashes and never enters model context. |-| `standard` / `fidelity` output | Use the compact authored-preset contract (§1.5) for newly authored stock shapes; do not transplant opaque import payload or source topology. |-| `mirror` output | Materialize from the edited authoring IR. Rehydrate supported imported metadata only when a Slide-local/slot object's source ref and initial authoring hash still match; otherwise keep the current SVG fallback. Expand fixed Master/Layout group wrappers into direct semantic atoms while preserving source ownership, paint order, and visible appearance. |--**Hard rule — model-facing page-coordinate precision**:--| Surface | Precision contract |-|---|---|-| Imported `data-pptx-frame` in authoring IR | At most two decimals. An unchanged mirror source ref recovers the exact lossless frame before tool-side native-record externalization. |-| `data-pptx-placeholder-bounds` in final template SVG | At most two decimals. |-| `translate(...)`, `rotate(... cx cy)`, and `matrix(... e f)` | Translation values and rotation centers use at most two decimals. Keep the rotation angle and matrix `a b c d` coefficients unchanged. |-| Protected values | Do not apply this compaction to path/points geometry, normalized crop or nested `viewBox` ratios, gradient offsets, opacity, scale arguments, canonical authored-preset frames, or lossless/tool-side native frames. |--**Hard rule — authoring source refs**: `data-pptx-source-ref` is reserved for-the create-template authoring IR. Its value is unique within one authoring SVG,-not across the workspace, and must be resolved through that document's-`authoring_manifest.json` record by the owning tool. Models MUST NOT read that-machine manifest. Moving a referenced subtree into-`icons/imported/` for readability must preserve the attribute and record it in-the vector inventory; re-inlining re-establishes the same mapping. Final materialized-template SVGs and normal project `svg_output/` must not contain this attribute.--**Hard rule — structural-layer boundary**: An unchanged imported logical object-may keep currently supported metadata while it remains Slide-local or inside a-slot. An imported logical `<g>` cannot be assigned to Master/Layout because-those layers require direct semantic atoms. Mechanically expand a fixed-layer-source group into direct atoms, rebuilding a preset when supported and-otherwise retaining the visible SVG fallback. A newly authored compact preset-`<g>` from §1.5 is the sole group exception: validation proves that it compiles-to exactly one native shape/connector. Do not use this normalization to change-ownership or appearance.--**Hard rule — selective payload**: Do not copy every imported metadata block into-an authored template. Keep the full lossless import SVG separately as immutable-audit/fallback backing. Mirror may reuse only metadata already supported by the-converter on source-ref/hash-matching Slide-local/slot objects; unsupported or-edited objects use the current SVG fallback. `data-pptx-replace-with` remains reserved for the-optional PowerPoint-native Chart/Table replacement contract.--**Registry and rendering rules**:--- The hash-locked shared registry must equal the independent 187-value shape- catalog. Missing, duplicate, unknown, or corrupt definitions fail closed.-- Preset preview paths come from the shared DrawingML formula evaluator; do not- add per-shape Python geometry handlers.-- Preset size is controlled only by `data-pptx-frame` / `a:xfrm`. Adjustment- formulas control the contour inside that frame and are not rescaled when the- frame changes.-- A group transform may move, scale, rotate, or flip the complete logical- shape without invalidating its preview fingerprint. Editing a generated- `geometry-detail` path directly is unsupported unless the carrier metadata- and preview fingerprint are regenerated together.-- Unknown or malformed SVG transform operations fail closed. DrawingML cannot- represent arbitrary shear, so a non-orthogonal transform must stop native- export instead of being silently approximated as rotation and scale.-- Opaque XML payloads containing any `r:*` relationship attribute are never- copied into a new slide part. Relationship-bearing text content and- shape-level `a:blipFill` use the existing rebuilt visual fallback and are- not covered by atomic `p:sp + p:txBody` rehydration.-- Unknown future presets and explicit `unsupported` geometry status never- downgrade silently to `rect`; native export stops with the recorded reason.--**Fidelity boundary**: native preset/custom geometry, logical frame, scoped-identity, connector topology, and relationship-free unchanged horizontal-text-body semantics on ordinary shape fills are `Native-stable`. The SVG-preview paint for gradient/pattern-`darken`/`lighten` layers is `Native-normalized`; original group child-coordinates, shape-level image-fill reconstruction, and vertical-text-reconstruction are also normalized rather than byte-identical OOXML.-------### 1.5 Authored Native PowerPoint Presets (Conditional Contract)--New SVG pages and project-owned canonical reusable templates may opt one-complete geometric object into a native DrawingML preset through the-deterministic fragment helper. Selection behavior lives in-[`native-shape-authoring.md`](./native-shape-authoring.md); this section owns-the machine contract. This compact canonical form describes the intended-preset, frame, adjustments, and paint once, keeps only registry-generated-visible SVG paths, and embeds no source OOXML or serialized preview fingerprint.--| Metadata / structure | Required behavior |-|---|---|-| `data-pptx-authoring="preset"` | Appears once on the logical `<g>`; distinguishes strict project authoring from legacy/imported metadata. |-| `data-pptx-object` | `shape` or `connector`; connector-family presets must use `connector`, and `connector` must use a connector-family preset. Authored connectors require `fill="none"` plus a visible stroke and export as unconnected `p:cxnSp`. |-| `data-pptx-prst`, `data-pptx-frame`, `data-pptx-av-*` | Generated together from the locked registry and written once on the logical group. The frame is the helper's exact four-part, space-separated ordinary-decimal spelling and remains authoritative even when visible path bounds differ; commas, scientific notation, leading `+`, and redundant decimal spellings are rejected. |-| Local `fill` / `stroke` plus supported paint attributes | Base paint is written once on the group; a visible stroke also carries an explicit width. Canonical page/template authoring keeps channel paint local. Compatible ancestor paint/opacity may compose under the general SVG rules and receives a recommendation warning. |-| Ordered direct `<path>` children | Browser-visible registry layers only. Each child writes just its required path-level fill/stroke override; labels and decorations stay outside the atomic group. |-| No carrier / wrapper / fingerprint | `data-pptx-part`, hidden geometry carriers, preview wrappers, and `data-pptx-preview-sha256` belong to expanded import/compatibility transport, not canonical project authoring. |--Generate one fragment at a time:--```bash-python3 ${SKILL_DIR}/scripts/preset_shape_svg.py render rightArrow \- --id p03-growth-arrow \- --frame 160 210 320 112 \- --fill "#2563EB" \- --stroke none \- --adjust "adj1=val 50000"-```--**Hard rule — helper-only metadata**: never add or edit authored preset-metadata or registry paths by hand. The compact helper output is atomic.-Regenerate it when preset, frame, adjustment, fill, stroke, or stroke width-changes. Replace the whole fragment with ordinary SVG when free contour editing-is required.--Template ownership metadata is orthogonal to preset geometry. After inserting-the complete helper output, `create-template` may add only the registered-`data-pptx-layer`, `data-pptx-editable`, `data-pptx-placeholder-carrier`, or-`data-pptx-role` attribute needed by the surrounding structured contract. It-must not change preset/frame/adjustment/paint metadata or any direct path.--**Reusable-template boundary**: a project-owned canonical template may retain-one complete helper-generated atomic fragment when the stock preset is an exact-semantic match and its paint stays inside the authoring boundary below. The-fragment is an executable exemplar and one semantic atom, not a freely editable-template primitive. It may be Slide-local, the one carrier of an `object` slot,-or a direct Master/Layout fixed atom. An adaptation may reuse it unchanged only-when preset, frame, adjustments, and paint are unchanged; otherwise regenerate-the whole fragment with the helper.-Imported, mirror, and third-party templates are never upgraded by contour-inference.--**Hard rule — visible page closure**: the helper prints a complete visible-fragment to stdout; export never invents its preview. The main Agent inserts-that output into the hand-authored page or canonical reusable template. The-helper cannot write a project, select layout, or generate a page.--**Authoring paint boundary**: v1 accepts `none` or six-digit solid HEX fill and-stroke, optional fill/stroke opacity, stroke width, line cap, and line join.-Generated pages take colors from `spec_lock.md`; `create-template` authored-templates take them from the confirmed brief and template `design_spec.md`.-Use ordinary SVG for gradients, patterns, filters, or other treatments outside-this narrow contract. Registry-derived multi-path darken/lighten colors are-authorized derivatives of the locked base paint and do not count as color-drift. Mirror preserves source paint under §1.4 instead.--**Validation**: quality check and export both rerender authored fragments from-`preset + frame + adjustments + group paint` and compare every visible path and-path-level paint override directly. Registry-path edits, geometry metadata that-leaves those paths stale, unknown adjustments, out-of-range frames/transforms,-zero-scale transforms, and shear/skew fail closed. Export expands the validated-compact group only in memory and reuses the lossless native-shape conversion-path. Older authored carrier/preview fragments remain compatible as ordinary-Slide-local input and-receive a non-blocking migration warning; they do not gain the new compact-group's structured-atom exception. `pptx_to_svg` expanded output remains the-lossless round-trip form and is not warned as authored input.--**Fidelity boundary**: an unchanged authored fragment is `Native-stable` as-one `p:sp` or `p:cxnSp`. Text remains outside the atomic fragment and may export-as a grouped editable text box. Authoring v1 creates only unconnected-`p:cxnSp`; it does not accept hand-written endpoint/site metadata. An-`actionButton*` preset maps visual geometry only. Preset appearance never-invents connector attachment, action behavior, navigation targets, or-hyperlinks.-------## 2. Conditional Compatibility Mappings--### 2.1 Literal Geometry Lengths and Inline Geometry--**Hard rule — direct geometry length grammar**: New generated SVG writes the-following XML geometry values and `stroke-width` as finite unitless ordinary-decimals in the page `viewBox` coordinate space, for example `x="120"` and-`stroke-width="2"`. The explicit `px` suffix is read-compatible and receives a-recommendation warning. No other unit is registered for this surface.--| Element / surface | Direct length attributes |-|---|---|-| `<svg>`, `<rect>`, `<image>`, `<use>` | `x`, `y`, `width`, `height`; `<rect>` also `rx`, `ry` |-| `<circle>` | `cx`, `cy`, `r` |-| `<ellipse>` | `cx`, `cy`, `rx`, `ry` |-| `<line>` | `x1`, `y1`, `x2`, `y2` |-| `<text>` / positional `<tspan>` | `x`, `y`; `<tspan>` also `dx`, `dy` |-| Any supported painted element | `stroke-width` |--`width`, `height`, `r`, `rx`, `ry`, and `stroke-width` must be non-negative;-the stricter positive `<use>` symbol-viewport rule remains in §1.3. `pt`,-`pc` / `pica`, `in`, `cm`, `mm`, `q`, `em`, `rem`, percentages, unknown units,-non-finite values, expressions, scientific notation, leading plus signs, and-trailing decimal points are invalid here even when generic SVG/CSS defines-them. A missing attribute may use its documented SVG/project default; an-explicitly supplied invalid value never falls back to that default.--The following geometry properties may appear in the same element's-`style="..."`. The pipeline materializes them as-XML geometry attributes before SVG post-processing and native PPTX conversion.-An inline geometry declaration overrides an existing same-name XML attribute.--| Element | Recognized properties |-|---|---|-| `<rect>` | `x`, `y`, `width`, `height`, `rx`, `ry` |-| `<circle>` | `cx`, `cy`, `r` |-| `<ellipse>` | `cx`, `cy`, `rx`, `ry` |-| `<image>` | `x`, `y`, `width`, `height` |-| `<svg>` | `x`, `y`, `width`, `height` |-| `<use>` | `x`, `y`, `width`, `height` |--**Hard rule — inline geometry grammar**: every non-zero value is one finite-`px` literal, such as `120px` or `-8.5px`; exact zero may be unitless. `width`,-`height`, `rx`, `ry`, and `r` must be non-negative. Percentages, `auto`,-`calc()`, `var()`, `!important`, `inherit`, and every other unit are forbidden.-Do not put geometry on an unsupported element: line endpoints, text positions,-path data, and polygon/polyline points remain XML attributes.--**Forbidden — CSS geometry cascade**: `<style>`, `class`, selector rules,-external stylesheets, and imported styles remain forbidden. This contract is-only for literal declarations in an element's own `style` attribute; PPT Master-does not compute CSS cascade or custom properties. Root canvas authority remains-the `viewBox`, regardless of root `<svg>` compatibility width/height values.--### 2.2 Group Opacity Compatibility--**Default — descendant alpha (may preserve compatible group opacity)**: New-`svg_output/` and reusable templates put alpha on the affected descendant-paint, text run, picture, or supported effect. DrawingML has no isolated-group-alpha model, so overlapping descendants can look different when one-group value is distributed across them.--The converter nevertheless accepts `<g opacity="...">` and inline group-`opacity` by multiplying group alpha into descendants. That path is-`Approximate`; nested group/child alpha multiplies, and `--native-charts-and-tables`-rejects transparent native table/chart markers. The quality checker reports a-non-blocking fidelity warning so existing or intentionally authored input can-continue without modification.-------## 3. Canvas Format Quick Reference--> See [`canvas-formats.md`](canvas-formats.md) for the full format table (presentations / social / marketing) and the format-selection decision tree.-------## 4. Required Page Contract and Conditional Packaging--### 4.0 Complete Page-Design Contract--| Concern | Requirement |-|---|---|-| Visible slide result | The completed `svg_output/<slide>.svg` MUST contain every visible text, image, shape, diagram, chart/table fallback, background, and template-derived layout element intended for that slide. External visual assets are valid when the SVG references them explicitly. |-| Template/control inputs | Templates, `design_spec.md`, and `spec_lock.md` guide authoring. Do not depend on them to add visible elements after the page SVG is complete. |-| PPTX translation | The exporter may map represented SVG content to DrawingML/native objects and deduplicate represented elements into Master/Layout/Slide parts. It MUST NOT invent visible slide content absent from the SVG. |-| Excluded package behavior | Speaker notes, animations, transitions, narration audio, PPTX relationships, and direct native-PPTX workflows remain separately owned. They are not part of the SVG page-design contract. |--**Hard rule — page-design closure**: A final page SVG is the sole visual/design authority for that page on every SVG-authoring route. SVG is not the authority for the entire PPTX package.--### 4.1 Semantic SVG Marker Contract--Semantic markers are minimal compiler hints orthogonal to native SVG semantics. Free-design, brand-only, and `template_reuse_scope: style` pages use flat export, declare one canonical root `data-pptx-page-role` (`cover` / `toc` / `section` / `content` / `ending`), and omit Master/Layout/layer/placeholder markers. On `template_reuse_scope: mirror|layout` routes, root Master/Layout identity, atomic layer elements, grouped slots, and native-object metadata are authoritative and read first; each page carries its final structured contract from the start of SVG authoring and omits `data-pptx-page-role`. Add `data-pptx-role` only when no specialized marker expresses the required page-frame behavior; the element also uses a stable unique `id`. Do not classify ordinary page content or move visible facts out of SVG attributes/text into metadata. See [`semantic-svg.md`](semantic-svg.md) for the canonical vocabulary and examples.--- **Canvas authority**: New authoring writes the root canvas exactly as- `viewBox="0 0 W H"`, using single spaces and positive ordinary-decimal integer- pixels from the selected project/template lock. Numerically identical SVG- spellings (integral decimals, exponent or leading-plus notation, and comma- separators) are compatible input and receive a normalization warning.- Positive fractional dimensions are also read-compatible for custom slide- sizes reconstructed from PPTX; export quantizes them once at- `1 SVG px = 9,525 EMU`. Missing/malformed/non-finite values, a non-zero- origin, non-positive dimensions, or dimensions outside PowerPoint's supported- slide-size range are errors. Every public page and internal Layout prototype- in one build MUST use the same numeric canvas and match `spec_lock.md`- `canvas.viewBox`; standalone templates match `design_spec.md`- `canvas_viewbox`. Root `width` and `height` are optional and do not override- the `viewBox`. Root `<svg>` `transform` is forbidden; apply transforms to- child elements or groups. This root-page rule does not replace the separate- nested-crop and `<symbol viewBox>` contracts.-- **Font portability**: font families used by the deck must resolve to installed- export faces. `@font-face` remains forbidden; the typography contract lives in- [`strategist.md §g`](strategist.md).-- **Icon placeholders**: `<use data-icon="library/name">` is a pipeline-specific- form, distinct from local SVG reuse. Follow the contract in- [`../templates/icons/README.md`](../templates/icons/README.md).-- **Local reuse**: ordinary same-document `<use>` follows §1.3.--### 4.2 Conditional Editability and Package Promotion--These forms are needed only when the stated PPT behavior matters:--| Desired behavior | Required form |-|---|---|-| One editable PPT text frame with mixed inline formatting | Put the logical line in one `<text>` with non-positional `<tspan>` children. A `<tspan>` with `x`/`y`/`dy` starts a new positioned line. Evenly `dy`-stacked lines that repeat the parent `<text>`'s `x` stay in one frame: equal effective `font-size` may flow in the current paragraph, while a font-size change, list marker, or accepted larger gap starts a new paragraph. An unmergeable gap or mismatched `x` flattens to separate frames. Separate `<text>` elements stay valid when separate frames are intended. |-| Stable object grouping or object-level animation anchor | Wrap the intended object in `<g id="...">`. Content grouping is **mandatory** per §4.3 — a top-level `<g id>` is also the animation anchor; it is not an optional convenience. |-| Native PowerPoint background promotion | Outside structured mode, the first eligible visual layer may be a direct full-canvas `<rect>` or one inside a simple single-child group. Its fill must have a registered native mapping (solid, linear/radial gradient, or preset pattern), and it must have no transform, filter, clip, rounding, or visible stroke. Export writes the fill as Slide `p:bg`; image elements remain pictures. Structured routes use the narrower explicit solid-background ownership contract in §7. |-| Free-design / brand-only PowerPoint structure | Use `pptx_structure.mode: flat`. Keep every represented object Slide-local; export materializes one clean project-owned Master plus one Blank Layout from the current lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. Do not author Master/Layout identities, layers, or placeholder slots. |-| Reusable template-based PowerPoint Layout | Select one complete authoring SVG per page in `page_layouts`, declare each unique Master/Layout definition once, and assign pages through `page_pptx_layouts`. Strict preserves the prototype contract; adaptive retains its Master and may define and assign a new explicit Layout key during page authoring. Non-mirror skin follows `spec_lock`. |--**Hard rule — supported shape conversion**: Every PPT editability claim in this specification refers to the project converter reading `svg_output/` and emitting native DrawingML. `svg_final/` is a self-contained visual preview that may be inserted into PowerPoint as an SVG picture. PowerPoint's manual Convert-to-Shape operation is unsupported; do not narrow the authoring contract to its undocumented SVG subset.--### 4.3 Element Grouping (Mandatory)--Wrap logically related Slide-local elements in top-level `<g id="...">` groups. This is **required on every generated page**, not an optional convenience: it produces real PowerPoint groups in the exported PPTX and gives each content unit a stable animation anchor. Plain `<g>` is the grouping primitive; keep alpha on individual descendants per §2.2. Flat free-design/brand-only pages use only ordinary semantic groups. On structured template pages, direct atomic Master/Layout elements are the required exception and a top-level slot `<g>` is already a semantic group. Nested implementation groups inside one named content unit may remain anonymous unless another specialized contract requires an id; they are not independent animation targets.--**Semantic-group rule**: direct Slide content uses semantic groups. Aim for **3–8 ordinary top-level content `<g id>` groups per slide**; on structured template pages, slot groups and atomic Master/Layout objects are excluded. Each ordinary group becomes one entrance step under the chosen animation trigger. Leaving Slide-local titles, body lines, list items, cards, or decorative clusters as ungrouped top-level atoms is an authoring-contract violation reported as an aggregate Checker warning.--**Structural atoms and slots are excluded automatically.** `data-pptx-layer` and `data-pptx-placeholder` semantics are read first; otherwise explicit `data-pptx-role` values (`background`, `decoration`, `header`, `footer`, `chrome`, `watermark`, `page-number`, `logo`) mark Slide-local static framing (§4.1, [`semantic-svg.md`](semantic-svg.md)). A normal slot group has exactly one direct compatible carrier; several drawing atoms require the explicit composite `object` proxy fallback. Native chart/table carrier groups retain their specialized §7 contract.--**What to group** (one `<g id>` per unit):--| Grouping unit | Contains |-|---|---|-| Card / panel | Background rect + optional shadow (only if it floats over a photo/colored panel, §6.4) + icon + title + body text |-| Process step | Number/marker + icon + label + description |-| List item | Bullet / number + icon + title + description |-| Icon-text combo | Icon element + adjacent label |-| Page header | Title + subtitle + accent decoration |-| Page footer | Page number + branding |-| Decorative cluster | Related decorative shapes (rings, dots, orbs) |--An authored native preset fragment (§1.5) is already an atomic `<g id>` and-counts as one content group. Keep it top-level when it stands alone. When it-needs a label or decoration, place the preset and those siblings inside a-separate parent content group; never put them inside the preset group itself.--**Forbidden**:--- One giant `<g>` around the whole slide (collapses to a single animation step).-- Many ungrouped Slide-local `<rect>` / `<text>` / `<path>` atoms — they have no stable sidecar target and selection/editing degrades. Primitive fallback applies only when the root contains no top-level `<g>` at all; it is capped at 8 visible primitives.-- One group per icon / text line / mark (too many steps).-- Anonymous top-level groups — every top-level semantic group needs a descriptive `id`.--**Naming — required.** A descriptive, page-unique `id` on every top-level content `<g>` (`card-1`, `step-discover`, `header`, `footer`) is mandatory; it is the stable SVG-side animation and trace anchor. An anonymous top-level group still converts, but `animations.json` cannot reference it; an anonymous one-child implementation wrapper may also flatten. Primitive fallback is unrelated and applies only to roots with no top-level groups.--```xml-<g id="card-benefits-1">- <!-- Shadow only if the card floats over a colored panel; on flat white, omit it. -->- <rect x="60" y="115" width="565" height="260" rx="20" fill="#FFFFFF" filter="url(#shadow)"/>- <use data-icon="chunk-filled/bolt" x="108" y="163" width="44" height="44" fill="#0071E3"/>- <text x="105" y="270" font-size="56" font-weight="bold" fill="#0071E3">10×</text>- <text x="250" y="270" font-size="30" font-weight="bold" fill="#1D1D1F">Faster</text>- <text x="105" y="310" font-size="18" fill="#6E6E73">Reduce production time from days to hours.</text>-</g>-```-------## 5. Workflow Authority--The serial post-processing and export workflow belongs to-[`generate-pptx.md`](../workflows/generate-pptx.md) Step 7. This file defines SVG authoring boundaries-and intentionally does not mirror commands, flags, or output behavior.-------## 6. Advanced SVG Effects and Authoring Techniques--**Reference — not a constraint**: “Advanced” means capability depth, not rarity.-Use any compatible technique when it serves the locked visual style and content.--### 6.1 Availability, Precedence, and Fidelity--| Decision layer | Authority |-|---|---|-| Technical validity | Required / Forbidden / Conditional contracts in this file |-| Project values | `<project_path>/spec_lock.md` colors, fonts, icons, and images |-| Aesthetic fit | Locked `visual_style` / `visual_style_behavior` |-| Per-page choice | Content purpose, hierarchy, legibility, semantics, and rhythm |--**Hard rule — illustrative colors**: colors below demonstrate syntax only;-generated pages use matching `spec_lock.md` roles. Fidelity labels are defined-at the front of this document. Review an `Approximate` result in native PPTX-when the effect carries material meaning.-------### 6.2 Color, Alpha, and Opacity--Compatible paint grammar includes recognized named colors, `rgb()` / `rgba()`,-`hsl()` / `hsla()`, and `#RGB` / `#RGBA` / `#RRGGBB` / `#RRGGBBAA`. The-converter also tolerates legacy bare 3/4/6/8-digit hexadecimal tokens.--**Default — canonical generated paint tokens (may preserve compatible-alternatives)**: New `svg_output/` and reusable template SVGs write solid paint-as uppercase six-digit `#RRGGBB`. `fill` / `stroke` may instead use lowercase-`none` or the exact local reference form `url(#id)`. Named colors, lowercase or-short/alpha HEX, functional colors, and bare legacy HEX remain supported input.-The quality checker prints an optional canonical rewrite as a recommendation-warning; it does not require modification or block export.-Explicit empty, malformed, or unrecognized paint values are errors in both-Checker and exporter preflight; neither converts unknown intent into-`noFill` or default black. Omitted properties still follow their own element-contract, such as SVG's default fill or §6.3's required gradient-stop color.--| Intent | Canonical authoring | Native result / fidelity |-|---|---|---|-| Solid fill or text paint | `fill="#RRGGBB"` | Solid DrawingML paint; `Native-stable` |-| Fill/text alpha | Opaque `fill` + `fill-opacity="0..1"` | Fill/run alpha; `Native-stable` |-| Stroke alpha | Opaque `stroke` + `stroke-opacity="0..1"` | Line/outline alpha; `Native-stable` |-| Gradient-stop alpha | Opaque `stop-color` + `stop-opacity="0..1"` | Per-stop alpha; `Native-stable` |-| Shadow/glow alpha | Opaque `flood-color` + `flood-opacity="0..1"` | Effect alpha; `Native-stable` within §6.4 |-| Picture fade | `<image opacity="0..1">` | Picture `<a:alphaModFix>`; `Native-stable` |-| One atomic whole-object fade | Non-group element `opacity="0..1"` | Alpha compiled into its supported paint/effect channels; `Native-normalized` |-| Pattern alpha | Opaque pattern child paint + child fill/stroke opacity | Conditional; §7 |-| CSS color alpha | Alpha-bearing named/functional/HEX paint | `Native-normalized`; recommendation warning only |-| Group fade | `<g opacity>` compatibility | `Approximate`; fidelity warning; §2.2 |--```text-effective fill alpha-= color alpha × ancestor group opacity × element opacity × fill-opacity-```--**Default — opaque color authority (may preserve compatible alpha colors)**:-New generated SVG puts alpha on the semantic channel that owns it. Existing or-intentional alpha-bearing color tokens remain convertible; they normalize into-the matching DrawingML color/alpha channels.--**Default — channel-specific alpha (may override for one atomic whole-object-fade)**: use `fill-opacity`, `stroke-opacity`, `stop-opacity`, or-`flood-opacity` when only that channel fades. Use element `opacity` only when-an image or one non-group atomic object intentionally fades all of its-supported paint/effect channels together. Do not use element `opacity` as an-alias for `rgba()` on a fill-only object.--**Default — alpha grammar (may preserve compatible alternatives)**: write-`opacity`, `fill-opacity`, `stroke-opacity`, `stop-opacity`, and-`flood-opacity` as finite unitless numbers from `0` to `1`. The converter also-accepts finite numeric values that SVG/CSS clamps into that interval;-`stop-opacity` and `flood-opacity` additionally accept finite percentages. The-checker reports those supported non-default spellings as recommendation warnings.-Malformed or non-finite values are errors in both Checker and exporter-preflight; neither substitutes an opaque default for unknown intent.-`fill="transparent"` / `stroke="transparent"` become no fill/line; use a color-plus alpha when a painted transparent layer must remain represented. Prefer-descendant alpha over group opacity when isolated compositing matters (§2.2).--PPTX import is a user-input boundary, not generated authoring. Tolerant mode-retains recognized color semantics, omits only unsupported paint properties,-and records the decision in `conversion-report.json`; `--strict` keeps the-closed parser checks. See-[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).------### 6.3 Gradients and Paint Effects--| Concern | Contract |-|---|---|-| Definition | Direct `<linearGradient>` / `<radialGradient>` child of `<defs>` with unique `id` |-| Reference | Exact local `url(#id)` |-| Stops | Direct `<stop>` children; explicit color; finite offset `0..1` or `0%..100%`; optional stop alpha |-| Coordinates | Normalized values / percentages; do not depend on `gradientUnits` user-space geometry |-| Forbidden | External/quoted refs, `href` inheritance, `gradientTransform`, `spreadMethod`, CSS gradients |--| Target | Contract and fidelity |-|---|---|-| `<rect>`, `<circle>`, `<ellipse>`, `<path>`, `<polygon>` fill/stroke | Linear `Native-normalized`; radial `Approximate` |-| `<line>` / `<polyline>` | Gradient stroke only; linear `Native-normalized`, radial `Approximate` |-| `<text>` / non-positional `<tspan>` | Gradient fill only; no gradient text outline |-| `<image>` | No gradient paint; use §6.5 overlays |--Linear export preserves stops/alpha/direction but reduces coordinates to an-angle. Radial export becomes a centered circular gradient and does not preserve-`cx/cy/r/fx/fy`. Gradient strokes remain editable, but PPTX-to-SVG re-import may-retain only the first stop. Stop alpha and element opacity multiply.-PPTX import normalizes compatible gradients and records any property-level-degradation without aborting the deck; `--strict` keeps the closed parser-contract. See-[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).-The quality checker and exporter preflight both validate definition location,-references, gradient structure, and paint context from the same closed contract.--**Hard rule — non-degenerate gradient geometry**: an `objectBoundingBox`-gradient stroke requires non-zero intrinsic width and height. SVG stroke width-does not expand that object bounding box, so a perfectly horizontal or vertical-gradient ribbon disappears even when its stroke is thick. Author such a ribbon-as a closed shape with gradient `fill`, or use a path whose intrinsic geometry-has both dimensions. Checker and exporter reject the degenerate stroke form.--```xml-<defs>- <linearGradient id="flow" x1="0" y1="0" x2="1" y2="0">- <stop offset="0%" stop-color="#2563EB"/>- <stop offset="100%" stop-color="#10B981" stop-opacity="0.7"/>- </linearGradient>-</defs>-<path d="M100 200 C260 80 420 320 620 180" fill="none"- stroke="url(#flow)" stroke-width="12"/>-```--Preset patterns are a separate PPT interface in §7.-------### 6.4 Shadows, Glow, and Elevation--Filters are native-effect metadata, not a general pixel-filter surface.--| Concern | Contract |-|---|---|-| Definition/reference | Direct `<defs><filter id="...">` child with unique id; direct `filter="url(#id)"` attribute, never inline style |-| Public targets | `<rect>`, `<circle>`, `<path>`, `<text>` |-| Required primitive | `feDropShadow` or `feGaussianBlur` |-| Required parameters | Explicit `stdDeviation` on either effect primitive; explicit `dx`, `dy`, and `flood-opacity` on `feDropShadow`; explicit `flood-opacity` on `feFlood`; explicit `slope` on linear `feFuncA` |-| Accepted helpers | `feOffset`, `feFlood`, `feComposite`, `feMerge`, `feMergeNode`, `feComponentTransfer`, linear `feFuncA` |-| Alpha transfer | Linear `feFuncA` maps multiplicative `slope` only; `intercept` is unsupported |-| Blur sampling | `feGaussianBlur edgeMode` is unsupported; native effects do not expose the SVG edge-sampling modes |-| Primitive coordinates | Omit `primitiveUnits` or use `userSpaceOnUse`; `objectBoundingBox` coordinates are unsupported |-| Numeric values | Finite unitless values; non-negative `stdDeviation`; finite `dx` / `dy`; `feFuncA slope` within `0..1`; mapped glow `rad = stdDeviation × 9525`, shadow `blurRad = stdDeviation × 2 × 9525`, and shadow `dist = hypot(dx,dy) × 9525` must round into DrawingML `0..27273042316900` |-| Classification | Meaningful non-zero offset → one outer shadow; zero/no offset → one glow |-| Fidelity | `Approximate`; one filter becomes one DrawingML effect |--Flood opacity, linear `feFuncA slope`, and element opacity multiply. The-converter-only historical path may also multiply flood-color alpha and-ancestor group opacity.-Native export does not preserve filter-region, `in/in2/result`, merge order, or-composite topology. Other primitives, multiple independent effects, filters on-`<image>` / `<tspan>` / `<g>` / unsupported targets are forbidden; apply the-effect to supported objects or use explicit layers.-The sole `<g filter>` exception is the hash-locked-`data-pptx-part="geometry-preview"` transport in §1.4: it must be a direct child-of an imported preset object and reference the same filter as that object's one-hidden geometry carrier. The preview is render-only and never becomes a second-PowerPoint object; this exception does not authorize filters on ordinary groups.-PPTX import preserves one registered shape/connector shadow or glow and records-unsupported object/run effects as import diagnostics instead of exposing a new-authoring surface. See-[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary)-for tolerant, strict, and release-handling behavior.-The quality checker and exporter preflight enforce the same definition,-reference, primitive, target, and numeric-value contract. Missing required-geometry and malformed values are never replaced by effect defaults during-native export.--```xml-<defs>- <filter id="softShadow" x="-15%" y="-20%" width="130%" height="150%">- <feDropShadow dx="0" dy="6" stdDeviation="8"- flood-color="#000000" flood-opacity="0.10"/>- </filter>- <filter id="expandedShadow" x="-15%" y="-20%" width="130%" height="150%">- <feGaussianBlur in="SourceAlpha" stdDeviation="8" result="b"/>- <feOffset in="b" dx="0" dy="6" result="o"/>- <feFlood flood-color="#000000" flood-opacity="0.10" result="c"/>- <feComposite in="c" in2="o" operator="in" result="s"/>- <feMerge><feMergeNode in="s"/><feMergeNode in="SourceGraphic"/></feMerge>- </filter>- <filter id="titleGlow" x="-30%" y="-30%" width="160%" height="160%">- <feGaussianBlur in="SourceAlpha" stdDeviation="6" result="b"/>- <feFlood flood-color="#38BDF8" flood-opacity="0.45" result="c"/>- <feComposite in="c" in2="b" operator="in" result="g"/>- <feMerge><feMergeNode in="g"/><feMergeNode in="SourceGraphic"/></feMerge>- </filter>-</defs>-```--Even `feDropShadow` with `dx="0" dy="0"` becomes glow. Use an existing accent-color for glow; black reads as diffuse shadow.--| Elevation | Use | `dy` | `stdDeviation` | Alpha |-|---|---|---:|---:|---:|-| Floor | Backgrounds, dividers, equal peers, body containers, decorative lines/icons, single-layer pages | — | — | — |-| Resting | Card over photo/panel, secondary callout | 2–4 | 4–8 | 0.06–0.10 |-| Raised | Primary CTA, focused card, overlay | 6–10 | 10–16 | 0.12–0.20 |-| Glow | Short display text, metric, focus accent | 0 offset | 4–8 | 0.35–0.55 |--**Strong default — single light source per page**: every `feOffset` shadow on-one slide shares the same `dx`/`dy` direction (default `dx="0"`, `dy="4"`–`dy="8"`,-light from upper front). Contradictory shadow directions read as multiple light-sources — a clear low-quality tell. The one sanctioned exception is a deliberate-upward paper-layer light, where every affected layer flips direction together;-never mix directions on the same plane. This is a strong default, not a-checker-enforced hard rule.--**Reference — not a constraint**: keep at most two-non-floor tiers; two or three shadowed objects usually suffice. Do not lift-every peer card or stack strong shadow, border, gradient, and tint on one-container. Same-family colored shadow is reserved for a focal accent. On dark-backgrounds, prefer a light hairline or restrained glow; never glow body copy.-Negative `dy` is valid for an intentional upward paper-layer light source when-every affected layer uses the same direction. For older/strict renderers,-replace a filter with two or three offset translucent shapes behind the object:-alpha `0.03–0.05`, increasing offset/radius, and optional same-family tint near-`0.04` (`Native-stable`).-------### 6.5 Image Treatments, Overlays, and Glass-like Surfaces--| Need | Authoring contract | Fidelity |-|---|---|---|-| Cover/crop | Readable raster dimensions + aligned `slice` | Native `srcRect`; `Native-stable`; otherwise native crop cannot be guaranteed |-| Contain/fit | Aligned `meet` | Fitted picture frame; `Native-normalized` |-| Stretch | `preserveAspectRatio="none"` | Native stretched frame |-| Uniform fade | `<image opacity="...">` | Native picture alpha |-| Shaped picture | §1.2 image-only `clip-path` | Preset/custom picture geometry |--**Hard rule — closed image aspect-ratio grammar**: on `<image>`, omit-`preserveAspectRatio` for the default `xMidYMid meet`, use `none` alone for-stretch, or use one of the nine case-sensitive alignments (`xMinYMin`,-`xMidYMin`, `xMaxYMin`, `xMinYMid`, `xMidYMid`, `xMaxYMid`, `xMinYMax`,-`xMidYMax`, `xMaxYMax`) followed by explicit `meet` or `slice`. Generated SVG-always includes the mode on an aligned value. An alignment without a mode and-values needing whitespace normalization are compatible input and receive a-Checker recommendation. Empty values, `defer`, unknown/wrong-case alignments or-modes, `none` with a mode, and extra tokens are errors; the converter never-guesses a fallback.--**Hard rule — fit/clip interaction**: a non-trivial clip disables `meet`-frame-fit. Match the image box to the source ratio or use `slice`. Do not apply-filters directly to `<image>`.--**Hard rule — picture frames and sources are explicit and decodable**: every-SVG `<image>` has explicit positive `width`/`height` and exactly one non-empty-`href` or compatible `xlink:href`. A data URI must use a supported `image/*`-MIME type, valid strict base64 when marked-`base64`, a non-empty payload, and bytes that decode as the declared format.-An external asset must resolve, use a supported extension, be non-empty, and-decode as that extension. The registered formats are PNG, JPEG, GIF, WebP,-BMP, TIFF, SVG, EMF, and WMF. Explicit template substitution tokens may remain-unresolved only during template checking; export requires the resolved image.-Missing, ambiguous, corrupt, mislabeled, or unsupported sources are errors and-must never be dropped or packaged as invalid zero-byte media.--**Hard rule — nested SVG is an imported crop transport, not a general-viewport**: every non-root `<svg>` must be the exact picture-crop wrapper emitted-by `pptx_to_svg`. The outer element has explicit registered project-geometry-`x`, `y`, positive `width`/`height`, a unit-coordinate `viewBox` made of four-ordinary decimal values, and-`preserveAspectRatio="none"`; it contains exactly one direct, empty `<image>`-with exactly one non-empty `href` or `xlink:href`, `x="0"`, `y="0"`, `width="1"`,-`height="1"`, and `preserveAspectRatio="none"`. Its ancestor chain contains-only the root SVG and ordinary visual `<g>` wrappers; definitions, text,-render-only geometry details, and other non-visual containers cannot own this-transport. The outer wrapper may additionally carry `id`, a supported-`transform`, registered structure metadata (`data-pptx-layer` or-`data-pptx-placeholder-carrier`), and the importer metadata-`data-pptx-frame`, `data-pptx-object`, `data-pptx-shape-id`,-`data-pptx-shape-name`, and `data-pptx-shape-scope`. A shape clip is present-only when exact `data-pptx-crop="1"` and a registered image-only `clip-path`-occur together and the local clip definition resolves. The inner image may-add only registered `opacity`. The `viewBox` must quantize without clamping to-a DrawingML `srcRect` with a positive visible region: each signed crop value-must fit the OOXML percentage integer range `-2147483648..2147483647`, while-`l + r < 100000` and-`t + b < 100000` preserve a positive visible region. Negative crop values and-crop windows extending outside the source unit rectangle are retained exactly,-not clamped. `0 0 1 1` is redundant and must be written as a plain `<image>`.-Extra visual children, indirect images, character data, unknown attributes,-malformed or unrepresentable crop coordinates, and generalized nested-viewports are errors. Checker and the converter share this parser so a nested-subtree cannot pass validation and then silently disappear during export.--| Overlay | Construction | Typical stops / alpha |-|---|---|---|-| Directional scrim | Linear rect, darkest beside text | `0%: 0.88; 55%: 0.30; 100%: 0` |-| Bottom title fade | Vertical rect over lower image | black `0 → 0.72` |-| Vignette/spotlight | Centered radial rect (`cx=50%`, `cy=50%`, `r=70%`); native center only | black `0 → 0.58` |-| Brand wash | Directional existing brand-color gradient | `0.80 → 0.10` |-| Faux glass | Visible fields + diagonal linear panel (`0,0 → 1,1`) + highlight stroke; optional §6.4 elevation | white `0.38 → 0.12`; stroke about `0.55` |--Layer in document order: image → scrim/wash → text. True source/backdrop blur is-`Bake-required`; faux glass is explicit layering, not blur. Validate contrast-against the actual image. All overlay gradients follow §6.3 linear/radial-fidelity.-------### 6.6 Lines, Connectors, Borders, and Markers--| Surface | Contract / native result |-|---|---|-| Solid stroke/width/alpha | `Native-stable` editable line |-| `4,4`; `6,3`; `2,2`; `8,4`; `8,4,2,4` (comma or space separators) | `dash`; `dash`; `sysDot`; `lgDash`; `lgDashDot` (`Native-normalized`) |-| Canonical custom dash | Exactly two positive finite unitless ordinary decimals (`dash gap`); export scales/quantizes against stroke width; `Native-normalized` |-| Compatible custom dash | Three or more positive finite unitless values are accepted but reduce to the first pair with a Checker recommendation; compatible numeric spellings also warn |-| `stroke-linecap` | `butt`, `round`, `square`; `Native-stable` |-| `stroke-linejoin` | `miter`, `round`, `bevel`; `Native-stable` |-| `vector-effect` | Exactly `none` or `non-scaling-stroke`; export resolves the choice into native line width (`Native-normalized`) |-| `stroke-dashoffset` | No general line mapping; allowed only as a direct finite unitless ordinary-decimal attribute on a §6.10 thick-circle shorthand (`px` suffix is compatible input and warns) |-| Gradient stroke | §6.3; re-import may flatten to first stop |-| `marker-start` / `marker-end` | §1.1 native line end; type `Native-normalized`, size `Approximate` (`sm/med/lg`) |--PPTX import treats unsupported line properties as source diagnostics: tolerant-mode retains the object and omits only the unsupported outline; `--strict`-retains the closed rejection behavior. See-[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).--The dash grammar is closed: exact lowercase `none`, or at least two finite-unitless numbers separated by whitespace or one comma. Generated SVG uses-ordinary decimal spellings. A leading plus sign, exponent, trailing decimal-point, surrounding whitespace, or longer custom list is compatible input and-produces a non-blocking normalization recommendation. Unknown units, one-value-arrays, empty or repeated comma fields, non-finite values, and negative or zero-entries are errors. The only zero exception is a gap declared directly on the-§6.10 thick-circle element.--Generated cap, join, and `vector-effect` values use the exact lowercase tokens-in the table. Surrounding whitespace is compatible input and produces a-recommendation; every other token is an error.--Match marker paint to the parent stroke using the shape-specific channel from-§1.1: fill for closed/oval line ends and stroke for the open arrow. Use markers-for connectors and §6.10 calculated geometry for a manual diagonal arrowhead.-When exact grid spacing matters, use one multi-subpath path rather than a-fixed-density preset pattern:--```xml-<path d="M40 0V120 M80 0V120 M0 40H120 M0 80H120"- fill="none" stroke="#2E6EA8" stroke-width="0.8"/>-```-------### 6.7 Advanced Text Treatments--**Hard rule — closed text property grammar**: generated text uses only the-values in the `Canonical authoring` column. Registered compatible input remains-convertible and receives a non-blocking normalization recommendation. Every-other value is invalid; the converter must not replace it with a default.--| Property | Canonical authoring | Compatible input | DrawingML mapping / rejection boundary |-|---|---|---|---|-| `font-weight` | `normal`, `bold`, or an exact integer hundred from `100` through `900` | `medium` → `500`; `semibold` → `600` | `normal` and `100..500` map to regular; `bold` and `600..900` map to `b="1"`; therefore numeric weights are `Native-normalized` |-| `font-style` | `normal` or `italic` | None | `italic` maps to `i="1"`; oblique, angle, relative, and CSS-wide values are invalid |-| `text-anchor` | `start`, `middle`, or `end` on `<svg>`, `<g>`, or `<text>` | None | Maps to left/center/right paragraph alignment plus normalized frame position; it is invalid on `<tspan>` because run-level anchoring has no mapping |-| `text-decoration` | `none`, `underline`, `line-through`, or `underline line-through` | `line-through underline` → canonical order | Maps to the single underline and strike run properties; unknown, repeated, or substring-like tokens are invalid |-| `letter-spacing` | Finite unitless ordinary decimal SVG px | The same ordinary decimal with `px`, `pt`, or `em`; normalize to unitless px | Maps to `a:rPr@spc`; the final value must fit DrawingML `-400000..400000`, and negative tracking must leave every generated DrawingML run with a positive estimated advance and its text frame with a positive extent; keywords, percentages, exponents, leading plus signs, trailing decimal points, non-finite values, and other units are invalid |--The registered text properties follow SVG inheritance, including declarations-on the root `<svg>`: inline `style` overrides the same element's direct-attribute, which overrides its ancestor. Relative font sizes and `em` tracking-resolve against the same effective inherited size in Checker and converter.-Every declaration is validated even when a later declaration overrides it, so-hidden garbage cannot bypass preflight.--The DrawingML character-spacing range is necessary but not sufficient for-negative tracking. After run assembly, each output run must retain a positive-estimated advance using the quantized `sz` and `spc` values that will actually-be written; a wider sibling run or paragraph line cannot hide a run whose-aggregate advance would reverse or collapse, which can reorder or drop-characters across PowerPoint-compatible renderers. The generated text frame-must also retain a positive horizontal and vertical extent. Checker rejects-directly measurable single-line violations, and the converter revalidates-every generated run and text frame before writing OOXML. It must not clamp,-take the absolute value of, or otherwise hide a non-positive advance or extent.-Adjacent authored runs with identical final DrawingML run properties form one-output run before sizing and validation; splitting text across equivalent-`<tspan>` nodes is not a tracking escape hatch. Tracking and width estimates-count the registered project text clusters rather than raw Unicode code points:-combining marks, variation selectors, emoji modifiers and ZWJ sequences,-paired regional indicators, and same-script virama conjuncts do not receive-internal spacing.-An unchanged imported native text body reuses the geometry carrier's positive-shape frame and attaches the preserved `txBody` payload instead of regenerating-runs or a text frame from the SVG estimate.--**Hard rule — element-specific text surface**:--- Inheritable text declarations belong only on `<svg>`, `<g>`, `<text>`, or- `<tspan>`; placing them on geometry, image, definition, or reuse elements is- an error rather than ignored decoration.-- `<text>` accepts `x`, `y`, registered paint/alpha/run properties, the text- properties above, `font-family`, `font-size`, direct `filter`, direct- `transform`, `xml:space`, `id`, and project `data-*` metadata.-- `<tspan>` accepts `x`, `y`, `dx`, `dy`, registered paint/alpha/run- properties, `font-family`, `font-size`, `font-weight`, `font-style`,- `letter-spacing`, `text-decoration`, `xml:space`, `id`, and project `data-*`- metadata. It does not accept `text-anchor`, `filter`, or `transform`.-- `word-spacing`, `dominant-baseline`, `alignment-baseline`, `baseline-shift`,- font shorthand/variant/stretch/feature/variation/synthesis controls,- `font-kerning`/`kerning`, `font-size-adjust`, `line-height`, text alignment,- indent/shadow/rendering controls, white-space/word-break/hyphenation- controls, `writing-mode`, `vertical-align`, `direction`, `unicode-bidi`, and- `text-transform` have no registered native mapping and are errors as direct- attributes or inline style.-- Any other unregistered `font-*` or `text-*` property is also an error; the- closed grammar must not grow through an ignored CSS spelling.--**Hard rule — project text whitespace**:--- `xml:space` is the project's closed authoring control for significant text- whitespace. It is valid only as an exact direct attribute on `<text>` or- `<tspan>`, accepts only the case-sensitive values `default` and `preserve`,- inherits through the text tree, and may be reset on a child `<tspan>`.-- The project maps this control to the visible Chromium/SVG2 behavior used by- Live Preview; it does not claim the legacy SVG 1.1 newline-deletion model.- XML line endings and tabs become U+0020 SPACE. In `default` mode, contiguous- U+0020 characters collapse across inline run boundaries and leading or- trailing default-mode spaces in the resulting text chunk are removed. In- `preserve` mode, every resulting U+0020 character remains significant.-- Only XML whitespace is normalized. NBSP, ideographic space, and other- Unicode spacing characters remain literal text and must not be rewritten by- a generic Unicode-whitespace regular expression.-- Source line breaks do not create PowerPoint paragraphs. Use the registered- positioned-`tspan`/paragraph structure for visual lines, and preserve DOM- text/tail order plus original style inheritance when normalizing that- structure.--These allowlists are additive to the global structural blacklist and the-paint, font-size, opacity, filter, and transform value contracts owned by their-respective sections; they do not weaken those contracts.--| Treatment | SVG surface | Result / boundary |-|---|---|---|-| Underline / strike / both | `text-decoration="underline"`, `line-through`, or both | `Native-stable`; both emits both run properties |-| Mixed runs | Non-positional `<tspan>` | One `Native-normalized` editable frame; §4.2 |-| Font size | Generated default is a finite unitless SVG px value; compatible `px`, `pt`, `pc`/`pica`, `in`, `cm`, `mm`, `q`, `em`, and `rem` values receive a recommendation warning only | Converted to SVG px, then editable DrawingML point size; unsupported units/percentages error |-| Tracking | §6.7 closed `letter-spacing` grammar | `Native-normalized`; compatible units normalize to SVG px before DrawingML conversion |-| Transparency | `opacity` / `fill-opacity` on text/run | `Native-normalized` run alpha, not isolated compositing |-| Gradient fill | §6.3 gradient on text/run | Editable fill; geometry normalizes |-| Outline | Solid `stroke`, `stroke-width`, `stroke-opacity` | `Native-normalized` editable run outline; re-import does not reconstruct it |-| Shadow/glow | §6.4 filter on `<text>` only | Shape shadow / run glow; `Approximate` |-| Native bullet | Leading `· • ● ▪ ■ ◆ ◇ ◦ ‣` + non-empty content | `·`/`•` → `•`; others unchanged; color/alpha from marker run; font/size follow text |--```xml-<text x="100" y="200" font-size="20" xml:space="preserve">Current <tspan- fill="#999999" text-decoration="line-through">old</tspan> value</text>-```--Use strikethrough for removed/former values; it is ordinary notation, not a-style-exclusive effect. Imported double underline/strike normalizes to single.-Bullet detection allows optional leading whitespace, requires non-empty content,-and leaves non-leading decorative glyphs as ordinary text.-Keep body tracking normal; CJK tracking defaults near/below 2% of font size and-above 5% triggers review. Text outline is solid only. `textPath`, masks, blend-modes, generated effects, and text-image knockouts are outside editable text.-------### 6.8 Transforms, Layering, and Static Reuse--| Surface | Contract / fidelity |-|---|---|-| `rotate(angle[, cx, cy])` | Geometry/image/text/ordinary group; `Native-normalized` |-| `translate(x y)` | Geometry/image/group; pure translation also safe on text; `Native-normalized` |-| Positive scale / negative mirror | Geometry/image or a group/use whose expanded visual subtree is geometry/image only; explicit pivot; `Native-normalized` |-| `matrix(a b c d e f)` | Geometry/image or the same geometry/image-only group/use; transformed axes finite, non-zero, orthogonal; excludes rounded rectangles and subtrees containing them; `Native-normalized` |-| Source order | Back-to-front PPT z-order; `Native-stable` |-| `<g opacity>` | Compatible approximate mapping; generated SVG prefers descendant alpha, §2.2 |-| Local `<use>` | §1.3 compile-time reuse; `Native-normalized` |--**Hard rule — closed transform grammar**: Use only lowercase `translate`,-`scale`, `rotate`, and `matrix` with exact finite unitless argument counts:-`translate` 1/2, `scale` 1/2, `rotate` 1/3, and `matrix` 6. Separate arguments-and operations with whitespace or one comma. Leading/trailing/repeated commas,-adjacent operations without a separator, units, unknown functions, and-incomplete input fail quality check and export. Generated numeric tokens use-ordinary decimals; a supported leading `+`, exponent, or trailing decimal point-remains compatible input and receives a non-blocking normalization warning.-Model-facing translation values, rotation centers, and matrix `e/f` use at-most two decimals under §1.4; angles, scale arguments, and matrix `a/b/c/d`-retain the precision required by the transform.--Set text size/position directly. A text transform is either a translate-only-list or one rotate operation; do not scale, matrix-transform, or mix operations-on text. A group containing text follows the same translate-only/single-rotate-limit. `skewX`, `skewY`, zero/non-orthogonal axes, and shear matrices are-forbidden. Native chart/table markers allow translate/scale only. The §6.10-thick-circle shortcut does not inherit general transform support. Positive-rotation is clockwise and pivoted rotation normalizes the native frame. Every-cumulative matrix, including transforms split across ancestors, must remain-finite, non-zero, and orthogonal; importer/live-editor matrices do not expand-the hand-authored contract.-Mirror around vertical pivot `cx` with-`translate(cx 0) scale(-1 1) translate(-cx 0)`; use the analogous Y sequence-for a horizontal pivot. During mirror materialization, imported PowerPoint-groups with an axis flip keep their geometry reflection, while each descendant-SVG text node receives the matching counter-reflection so browser previews keep-glyphs upright. The tool-side native record retains the source group flip.--Layer back-to-front: background/image → scrim/shadow → main geometry → labels /-icons → top annotation. Finalization and native export independently expand-`<use>` into cloned editable primitives; PowerPoint does not retain a symbol /-instance graph.-------### 6.9 Freeform Shapes and Curves--| Input | Native normalization | Fidelity |-|---|---|---|-| `M/L/H/V`, absolute or relative | Absolute `M/L` | `Native-normalized` |-| `C` | Cubic Bézier | `Native-normalized` |-| `S/Q/T` | Explicit cubic controls | `Native-normalized` |-| `A` | Cubic segments of at most 90° | `Approximate` |-| `Z`; polygon/polyline | Closed/open freeform | `Native-normalized` |--**Hard rule — complete freeform grammar**: Generated `path@d` and-`polygon` / `polyline@points` use finite unitless ordinary decimals and only-the commands registered above. Native export consumes the complete attribute;-it never extracts recognizable fragments while ignoring other characters.-Finite scientific notation, a leading plus sign, and a trailing decimal point-remain read-compatible and receive recommendation warnings; generated SVG does-not write them. Unknown commands or characters, misplaced/repeated commas,-non-finite numbers, missing attributes, incomplete command groups, and odd-point counts are invalid. A path starts with `M` / `m`; `A` radii are-non-negative and both arc flags are exactly `0` or `1`. Each registered path-command accepts its uppercase absolute and lowercase relative form. Legal-separator-free arc flag sequences remain valid and are parsed as individual-flag tokens. A polygon has at least three coordinate pairs and a polyline at-least two.--**Validation**: Checker and native export consume the same parser in-[`paths.py`](../scripts/svg_to_pptx/drawingml/paths.py); native-object fallback-bounds reuse its normalized commands rather than a second path grammar.--Command identity, relative coordinates, shorthand, arc parameters, and original-handles are not retained. Geometry needs non-zero bounds. Use a closed cubic-path for organic silhouettes, polygon/closed path for ribbons/facets, open path-for curved connectors, multi-`M` path for exact linework, and a §1.2 path clip-for organic pictures. Filled silhouettes end with `Z`; open paths use-`fill="none"`. Do not depend on `fill-rule="evenodd"`; build explicit visible-geometry or bake an essential knockout.-For a fixed background, a background-colored overlay is also valid.--| Rounded rect input | Result |-|---|---|-| One positive radius, or `0 < rx == ry <= min(width,height)/2` | `Native-stable` adjustable `roundRect` without distorting transforms; the same short-side limit applies to one-radius input |-| `0 < abs(rx-ry) < 0.5px` after scaling | One normalized native radius; `Approximate` |-| `abs(rx-ry) >= 0.5px`, either positive | Cubic custom geometry; no radius handle; `Approximate` |-| Equal radius above half the short side | Native short-side clamp may differ from SVG; `Approximate` |-------### 6.10 Radial Geometry, Donuts, Gauges, Sunbursts, and Diagonal Arrowheads--For center `(cx,cy)`, radius `r`, and degrees `θ`:--```text-x = cx + r × cos(θ × π / 180)-y = cy + r × sin(θ × π / 180)-```--For clockwise pie/donut sectors, default to `-90°` only when the chart starts at-12 o'clock. A full-circle percentage sector spans `percentage × 360°`;-large-arc is `1` above `180°`; outer sweep is `1`, inner return is `0`. Split-both outer and inner boundaries of a full ring into at least two arcs each.-Calculated endpoints survive subject to EMU rounding; `A` curves remain cubic-approximations. Verify all spans plus gaps against the planned sweep.-Explicit arc sectors are editable `Approximate` freeforms. Thin circles using a-§6.6 preset/two-number dash stay `Native-normalized` ellipse lines.--```xml-<!-- 75% donut: center 400,400; outer 180; inner 100; -90° → 180°. -->-<path d="M400 220 A180 180 0 1 1 220 400- L300 400 A100 100 0 1 0 400 300 Z" fill="#2563EB"/>-```--**Gauge**: require `max > min`, `p = clamp((value-min)/(max-min),0,1)`, and-`0 < planned clockwise sweep <= 360°`; value sweep is `p × planned sweep`.-`valueEndAngle = startAngle + valueSweep`; large-arc is `1` iff-`abs(valueSweep) > 180°`.-Omit the value sector at `p=0`. At `p=1` with `360°`, split both boundaries into-at least two arcs. Track/value share center, radii, start, and sweep flags.--**Sunburst — `Approximate`**: one explicit annular sector per node; each depth owns one radius-band and child angular intervals partition the parent. Do not use one `evenodd`-compound ring.--**Thick-circle shorthand — `Approximate`, non-position-sensitive only**:--- One circle per segment; `fill="none"`; the circle may use one `rotate` for its- start angle, and ancestor transforms must be translate-only.-- Exactly two non-preset finite unitless ordinary-decimal values (`dash gap`);- `stroke-dashoffset` is a direct finite unitless ordinary-decimal attribute.-- `0 < stroke-width < 2r`, `stroke-width/r >= 0.15`,- `0 < dash < 2πr`, `gap >= 0`, and `dash + gap >= 2πr - 1` SVG unit. The- one-unit tolerance exists only for integer-rounded circumference values.-- Native construction uses only the first dash and re-imports as a freeform.- Its native start is 90° counterclockwise from the SVG preview; use explicit- arcs whenever start angle, cap, or radial precision matters.--```xml-<circle cx="400" cy="400" r="140" fill="none" stroke="#2563EB"- stroke-width="48" stroke-dasharray="615.75 263.90" stroke-dashoffset="0"/>-```--**Diagonal polygon arrowhead**: for a non-zero line, calculate rather than use a-fixed triangle:--```text-dx=x2-x1; dy=y2-y1; len=√(dx²+dy²); ux=dx/len; uy=dy/len-px=-uy; py=ux-tip=(x2,y2)-back1=(x2-ux×12+px×5, y2-uy×12+py×5)-back2=(x2-ux×12-px×5, y2-uy×12-py×5)-```--Use §1.1 markers for ordinary connectors; the polygon is for a manually drawn-filled `Native-normalized` arrowhead. Example:-`<polygon points="370,430 365.6,417.8 358.2,424.6"/>`.-------### 6.11 Constructed Visual Styles--**Hard rule — explicit construction**: these are supported-layer recipes, not-browser-filter permissions.--**Reference — not a constraint**: use them only when they match the locked style.--| Intent | Construction | Boundary / fidelity |-|---|---|---|-| Faux glass | §6.5 translucent panel + highlight stroke + visible fields | No backdrop blur; `Native-normalized` |-| Hand-drawn mark | Rotated translucent bar + irregular `Q/C` paths + round caps | No roughness filter; `Native-normalized` |-| Ink wash | Few same-family translucent closed curves/strokes | No feather/wet edge; `Native-normalized` |-| Riso offset | Duplicate text/shape with small offset, second ink, lower alpha | No blend mode; `Native-normalized` |-| Pixel grid | Integer-aligned rects on one cell grid | `shape-rendering` preview-only; `Native-stable` |-| Halftone | Sparse calculated circles | `Native-stable`; bake dense screens / use suitable §7 preset |-| Isometric facets | Shared-vertex top/front/side polygons, one light direction | 2D only; `Native-normalized` |-| Paper cut | Ordered organic paths + consistent §6.4 shadow per layer | Filter each layer, not group; `Approximate` |-| Gradient ribbon | Non-degenerate cubic path + §6.3 gradient stroke; closed gradient-filled shape for horizontal/vertical ribbons | `Native-normalized`; no mesh gradient; re-import may flatten color |-| Line-plus-area data | Low-alpha closed area first, crisp line above | Keep area subordinate; `Native-normalized` |--**Minimal construction anchors**:--```xml-<!-- Hand-drawn + ink. -->-<rect x="80" y="80" width="240" height="28" fill="#FDE68A"- opacity="0.72" transform="rotate(-1,200,94)"/>-<path d="M90 150 Q210 142 330 151" fill="none" stroke="#1F2937"- stroke-width="3" stroke-linecap="round"/>-<path d="M80 220 C160 160 250 180 330 230 Z" fill="#1F2937" opacity="0.16"/>-<path d="M90 240 C180 210 250 260 340 220" fill="none" stroke="#1F2937"- stroke-width="10" stroke-linecap="round" opacity="0.70"/>--<!-- Riso, pixel cells, sparse dots. -->-<text x="86" y="320" font-family="Arial, sans-serif" font-size="64"- fill="#EC4899" opacity="0.85">PRINT</text>-<text x="92" y="326" font-family="Arial, sans-serif" font-size="64"- fill="#2563EB">PRINT</text>-<g id="pixel-cells" shape-rendering="crispEdges" fill="#2563EB">- <rect x="400" y="80" width="16" height="16"/><rect x="416" y="80" width="16" height="16"/>-</g>-<g id="sparse-dots" fill="#EC4899"><circle cx="410" cy="140" r="3"/><circle cx="426" cy="140" r="6"/></g>--<!-- Isometric facets + line-over-area. -->-<g id="isometric-facets" transform="translate(520 160)">- <polygon points="0,0 80,-24 160,0 80,24" fill="#60A5FA"/>- <polygon points="0,0 0,48 80,72 80,24" fill="#3B82F6"/>- <polygon points="80,24 80,72 160,48 160,0" fill="#2563EB"/>-</g>-<path d="M760 260 L860 220 L960 250 L960 340 L760 340 Z" fill="#2563EB" opacity="0.10"/>-<path d="M760 260 L860 220 L960 250" fill="none" stroke="#2563EB" stroke-width="4"/>-```--**Default — integer pixel grid (may override for deliberate irregular-treatment)**: avoid soft scaling; use explicit dots only for sparse editable-halftone and route dense full-slide texture to §6.12.-------### 6.12 Unsupported Effects and Native-Safe Alternatives--| Unsupported intent | Do not author | Fidelity | Alternative |-|---|---|---|---|-| Source/backdrop blur; procedural texture | Plain blur, `feTurbulence`, `feDisplacementMap`, `feColorMatrix`, arbitrary filter graph | `Bake-required` | §6.4 effect, explicit geometry, translucent layers, or baked texture |-| Inner shadow, soft edge, reflection | Non-outer-shadow/glow graph | `Bake-required` | Explicit inset/highlight/shadow layers or image |-| Per-pixel compositing | Mask, blend mode, knockout, arbitrary alpha composite | `Bake-required` | Direct geometry; §1.2 image clip; otherwise bake |-| Exact custom tile | Unannotated `<pattern>` / `patternTransform` | `Bake-required` | Multi-subpath geometry, suitable §7 preset, or bake |-| Sheared object | Skew/shear matrix | `Bake-required` | Pre-transform geometry path; bake text/image |--**Hard rule — blur semantics**: within §6.4, zero-offset `feGaussianBlur` means-glow; it does not blur the object or backdrop. Use a low-alpha raster for dense-grain and explicit circles/paths only for sparse editable marks.--Unsupported source effects remain visible where possible and retain their-import diagnostics. Resolve those diagnostics before release export; see-[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).-------### 6.13 Scenario Quick Reference--**Reference — not a constraint**: fidelity remains authoritative in the owning-subsection; this table only routes scenarios.--| Decision family | Scenario routing | Authority / boundary |-|---|---|---|-| Elevation | Floating card → resting shadow; one CTA → colored shadow; equal peers/background → flat; maximum predictability → layered shapes; title/metric → glow | §6.4; never body-copy glow |-| Image/material | Text over image → directional scrim; bottom title → bottom fade; centered hero → vignette; brand wash → brand overlay; glass card → faux glass | §6.5; no backdrop blur |-| Lines | Draft/optional → dash; process direction → marker; flow/series → gradient stroke; exact grid → multi-subpath path | §6.6 / §6.3 |-| Text | Removed/former value → line-through; eyebrow → tracking; watermark/outline heading → text outline; list → native bullet | §6.7 |-| Composition | Move/rotate/mirror → §6.8 transform; repeated static mark → local `<use>` | §6.8; preserve z-order |-| Hand/print | Annotation → highlighter/curve; ink wash → layered alpha paths; Riso → offset duplicate | §6.11; no turbulence, true bleed, or blend mode |-| Pixel/halftone | Pixel accent → integer rect grid; sparse screen → circles | §6.11; dense screen → §6.12 |-| Faceted/layered | Pseudo-3D → 2D facets; paper cut → direct shadow per layer | §6.11; no 3D transform/group composite shadow |-| Data/freeform | Series depth → area first + line above; organic card → closed cubic; shaped image → §1.2 path clip | §6.11 / §6.9 |-| Radial | Donut/gauge → explicit arcs; sunburst → sector per node; position-insensitive ring → shorthand | §6.10; shorthand has 90° preview/native offset |-| Arrow | Manual diagonal arrowhead → calculated triangle; ordinary connector → marker | §6.10 / §1.1 |-| Unsupported | Dense grain, complex composite, or skew → explicit alternative or baked asset | §6.12; foreground text/data stay editable SVG |------## 7. Conditional PPT Interfaces--The interfaces below exist only for PPT behavior that ordinary SVG semantics-cannot express. Use them only when the corresponding native capability is-required.--### Pattern Fill — `<pattern>` with PPTX preset annotation--`<pattern>` requests one fixed DrawingML preset; the converter does not render-the tile's arbitrary geometry. Use this interface only when that preset mapping-is intended.--`data-pptx-pattern="<preset>"` is the generated default for selecting the-intended preset from the enum below. The converter retains an `ltUpDiag`-fallback when the annotation is absent; the checker reports that fallback as a-non-blocking fidelity warning. Invalid explicit preset names remain errors-because they violate the closed OOXML enum.--Pattern colors may come from importer metadata (`data-pptx-fg` /-`data-pptx-bg`) or from the pattern's child paint. Without metadata, the first-child `<rect>` fill becomes the background and the first stroke (or other fill)-becomes the foreground. A missing background defaults to white; a missing-foreground means no native pattern fill can be emitted. The child geometry-itself is never used as a repeatable tile.--**Valid `data-pptx-pattern` values** (OOXML `ST_PresetPatternVal` — closed enum, anything outside makes PowerPoint open with "needs to be repaired"):--| Category | Values |-|---|---|-| Grids | `smGrid` · `lgGrid` · `dotGrid` *(no `ltGrid` — common typo)* |-| Diagonal lines | `ltUpDiag` · `ltDnDiag` · `dkUpDiag` · `dkDnDiag` · `wdUpDiag` · `wdDnDiag` · `dashUpDiag` · `dashDnDiag` · `diagCross` |-| Horizontal / vertical lines | `horz` · `vert` · `ltHorz` · `ltVert` · `dkHorz` · `dkVert` · `narHorz` · `narVert` · `dashHorz` · `dashVert` · `cross` |-| Percent fills | `pct5` · `pct10` · `pct20` · `pct25` · `pct30` · `pct40` · `pct50` · `pct60` · `pct70` · `pct75` · `pct80` · `pct90` |-| Checks & confetti | `smCheck` · `lgCheck` · `smConfetti` · `lgConfetti` |-| Decorative | `horzBrick` · `diagBrick` · `weave` · `plaid` · `trellis` · `zigZag` · `wave` · `sphere` · `divot` · `shingle` · `solidDmnd` · `openDmnd` · `dotDmnd` |--`svg_quality_checker.py` warns when a referenced pattern lacks the annotation;-it errors when the pattern uses `patternTransform` or names a preset outside-this enum.--### PowerPoint-Native Chart / Table Replacement Markers (Opt-in)--Native PowerPoint tables and Excel-backed charts activate at export time only. The default chart/table route remains hand-authored SVG geometry so the deck stays pixel-stable across PowerPoint / Keynote / LibreOffice / WPS.--**Authoring — markers are standard on supported data charts and text-grid tables**: Executor writes the marker at draw time on every data chart whose type falls in the supported set and on every pure text-grid data table ([executor-base.md §3.2](executor-base.md)), so any deck can later form native objects without regeneration. Canonical rectangular merged text cells may use the narrow `row_span` / `col_span` contract below; graphical cells stay unmarked on the SVG fallback route. The marker group supplies both: visible SVG fallback children for browser/live-preview rendering, and JSON metadata for `svg_to_pptx` native export.--**Hard rule — activation is the opt-in, dormant unless exported with `--native-charts-and-tables`**: A marker only declares that a group is eligible for PowerPoint-native Chart/Table replacement. Normal `svg_to_pptx.py` runs keep the fallback SVG children and convert them into independently editable DrawingML shapes. Pass `--native-charts-and-tables` only when the data source and chart/table-specific object model matter more than cross-renderer layout fidelity: it emits the PowerPoint Chart/Table object and skips the fallback children to avoid duplicates. Native styling preserves the core palette, text, axis, grid, and background colors where possible, but it is still a PowerPoint Chart/Table object rather than a pixel-identical SVG drawing.--The native route is deliberately data-object-first and may be lossy: marker-local labels, callouts, KPIs, guide lines, custom split/bin semantics, or styling that is absent from the payload may disappear or normalize. Export warns about this route-level risk and any narrower issue it can detect. Loss of visual parity is not grounds to remove an active marker that the emitter can otherwise convert; use the default SVG-fallback export when exact authored artwork matters more than a native data source and object-specific controls.--| Replacement marker | Native output | Required metadata |-|---|---|---|-| `<g data-pptx-replace-with="table">` | `<p:graphicFrame>` with `<a:tbl>` | bounds + `columns` or `rows` |-| `<g data-pptx-replace-with="chart">` | `<p:graphicFrame>` with `c:chart` / `cx:chart` + chart part + embedded workbook | bounds + `type`, plus chart data |--**Metadata placement**: Put JSON in one child-`<metadata type="application/json">`. The parent group's-`data-pptx-replace-with` value selects the table or chart schema, so the-metadata child does not repeat an object-kind attribute. Attribute JSON-(`data-pptx-json="..."`) remains read-compatible but is harder to XML-escape-correctly and is not canonical authoring.--**Bounds**: Provide `x`, `y`, `width`, and `height` in metadata, or as-`data-pptx-x` / `data-pptx-y` / `data-pptx-width` / `data-pptx-height` on the-marker group. If any bound is omitted, the exporter infers the object frame-from the visible fallback geometry; this keeps SVG fallback and native object-placement aligned. Complete explicit bounds are absolute slide coordinates;-marker/ancestor `translate` and `scale` transforms apply only when at least one-bound is inferred. `x`, `y`, `width`, and `height` must be finite and resolve-inside PowerPoint's 32-bit DrawingML coordinate range; `width` and `height`-must resolve to at least one EMU. Native table frames must additionally resolve-to at least one EMU per resolved row and column.--**Validation**: `svg_quality_checker.py` validates replacement marker kind, JSON-metadata, bounds/fallback availability, table rows/columns, supported chart-type, chart data shape, and any imported fallback baseline before export.--Imported marker freshness, fallback classification, provenance, and legacy-read compatibility are operational import concerns. Keep generated authoring-free of those attributes; use the exact behavior and field index in-[`conversion.md`](../scripts/docs/conversion.md#native-table-and-chart-import-claims).--```xml-<g id="p03-revenue-chart" data-pptx-replace-with="chart">- <metadata type="application/json">- {- "x": 120, "y": 150, "width": 520, "height": 320,- "type": "column",- "title": "Revenue by Segment",- "categories": ["Q1", "Q2", "Q3"],- "series": [- {"name": "Cloud", "values": [12, 15, 19]},- {"name": "Services", "values": [8, 9, 11]}- ]- }- </metadata>- <!-- Visible SVG fallback for live preview / non-native export goes here. -->-</g>-```--**Table schema**: Native tables are rectangular DrawingML grids. Use `columns`-for the optional header row and `rows` for body rows; shorter rows are padded-with blank cells unless `strict_grid: true` is set. Tables may contain at most-1000 resolved rows and 1000 resolved columns. Use `column_widths` and-`row_heights` as relative weights. Weight lists must match the resolved grid,-contain finite non-negative numbers, and include at least one positive value.-If present, `header_rows` must be an integer from `0` through the resolved row-count. Write `strict_grid`, `style.band_row`, and cell `bold` as JSON booleans.-Cell objects accept `text`, `fill`, `color`,-`align`, `valign`, `bold`, `font_size`, `padding`, `border_color`, and-`border_width`, plus optional `lang`; the same `padding`, `border_color`,-`border_width`, and `lang` keys may also live under `style` as table defaults.-For multi-paragraph text, replace cell `text` with a non-empty `paragraphs`-list. Each entry is either a string or an object containing optional-`align: "l|ctr|r"` and exactly one of `text` or non-empty `runs`; empty-paragraph strings are preserved, and cell `text` / `paragraphs` are mutually-exclusive. Each run is an object with required string `text` and optional JSON-boolean `bold`, `italic`, `underline`, and `strike`, plus optional `color`,-`font_size`, one-typeface `font_family`, `lang`, and `alt_lang`. Unknown fields,-wrong types, empty run lists, multi-typeface `font_family`, and unsupported-colors fail fast. PPTX import requires exact physical row/grid topology and-normalizes source presentation-only run XML outside this closed schema only-when it contains no non-empty `rPr` / `defRPr` / `endParaRPr` `effectLst` or-`effectDag`. A table-cell run effect follows the blocking effect contract above-instead of entering either the native payload or an effect-free fallback.-Relationship-bearing text, extensions, structural line breaks, fields, tabs,-bullets, malformed run topology, and unsupported text-body structure remain-fallback-only.-Per-side cell borders use `borders.left|right|top|bottom`, where each value is-either `{ "style": "none" }` or-`{ "style": "solid", "color": "#RRGGBB", "width": <positive-px> }`.-Per-side borders are cell-only; legacy uniform `border_color` / `border_width`-remain supported as defaults that an individual side may override.-When `lang` is absent, export derives `zh-CN` for CJK text and `en-US`-otherwise. `style.band_row: false` disables both `<a:tblPr bandRow>` and-materialized alternating row fills. Native table typography mirrors the-visible SVG fallback: put `style.font_family` and `style.font_size` on the-marker from the table text already drawn, then use `style.header_font_size` or-per-cell `font_size` only when the fallback visibly differs. If the fallback-has no explicit table font, use the deck body family and locked body size from-`spec_lock.md`.--**Hard rule — table metadata is the native source of truth**: Every row,-summary line, value, and cell-level style that must survive-`--native-charts-and-tables` must be present in `columns` / `rows`. SVG fallback text is-discarded during native export. `svg_quality_checker.py` warns when visible-fallback `<text>` inside a native table marker does not appear in metadata.-For numeric or currency columns, use cell objects with `align: "r"`; SVG-`text-anchor="end"` does not carry into the native table.--**Merged table cells — canonical rectangular contract only**: Put positive JSON-integer `row_span` / `col_span` values on the merge anchor and keep every-covered grid cell blank. Spans must stay within the resolved rectangular grid-and may not overlap. The exporter emits the canonical DrawingML topology-(`rowSpan` on the top edge, `gridSpan` on the left edge, `hMerge` / `vMerge` on-covered cells). CamelCase aliases, raw OOXML merge fields, top-level merge lists,-nonblank covered cells, invalid spans, and overlaps fail fast. The PPTX importer-activates native reconstruction only for that same explicit rectangular topology-with empty merge-slave text bodies; other merge encodings remain fallback-only-with `unsupported-merge-topology`.--**Category chart schema**: `column`, `bar`, `line`, `area`, `pie`,-`doughnut`, `pieOfPie`, `barOfPie`, and `radar` use `categories` plus-`series[].values`. Pie-family charts (`pie`, `doughnut`, `pieOfPie`, and-`barOfPie`) must have exactly one series; the exporter assigns per-category-slice colors so single-series charts do not collapse into one solid color.-Column and bar charts may set per-point colors with `series[].point_colors`-or `series[].pointColors`; the list must match `series[].values` length.-Classic category charts may set native PowerPoint data labels with-`data_labels`. Use `data_labels: true` for default value labels, or an object-with `show_value`, `position`, `number_format`, `font_size`, `font_family`,-`bold`, `color`, and optional per-point `colors`. Supported label positions-depend on chart type: clustered column/bar labels may use `outside_end`,-`inside_end`, `inside_base`, or `center`; stacked / percent-stacked column/bar-labels may use `inside_end`, `inside_base`, or `center`; line labels may use-`above`, `center`, or `best_fit`; area labels do not emit a native label-position. To label only selected data points, use `data_labels.points` with-zero-based `idx` plus optional per-point `position`, `number_format`,-`font_size`, `font_family`, `bold`, and `color`.--**Combo chart schema**: `combo` uses shared `categories` plus either `plots[]`-or typed `series[]`. Each plot supports `type: "column" | "line" | "area"`,-its own `series`, and optional `axis: "secondary"` for a right-side value axis.-When primary and secondary plots genuinely use different category caches,-`plots[]` may also carry its own `categories` and `category_numeric`; the-workbook writer allocates independent category/value ranges. Typed `series[]`-continues to require the shared top-level categories.-Imported `plots[]` may carry `series_indices` so the verified source identity-where each `c:idx` equals its `c:order` survives when physical plot order differs-from legend order. If one plot supplies it, every plot must supply a same-length-list of unique non-negative JSON integers, and the combined values must form one-contiguous `0..N-1` range. Sources whose `idx` and `order` differ stay-fallback-only; typed `series[]` does not accept this plot-scoped field.-Typed `series[]` accepts the same `type` and `axis` fields per series, and-adjacent compatible series are grouped into the same PowerPoint plot. Area-series may set `fill_opacity` / `fillOpacity` as a `0..1` SVG opacity value-when the SVG fallback uses a transparent area fill under an opaque line. A line plot with `area_fill: true`-is exported as a PowerPoint area chart under the hood; `fill_opacity` only sets-the fill style and does not trigger conversion by itself. Combo export layers-area plots below columns and lines while preserving the original series indices.-Line and area series may set `line_width` / `lineWidth` in SVG px units to-match fallback `stroke-width`.--**Narrow classic-axis schema**: `axes` is a closed object with the roles-`category`, `value`, `secondary_category`, and `secondary_value`. Each role may-set only `kind` (`text`, `date`, or `value`, as appropriate), `position`,-`visible`, `label_position` (`next_to`, `none`, `low`, or `high`),-`number_format`, `minimum`, `maximum`, `major_unit`, `reverse`, and-`major_gridlines`. `major_unit` applies to value axes only. PPTX date-axis-**import** is deliberately narrow: numeric Excel date serials are accepted for-area charts and OHLC stock charts; arbitrary date-axis source families are not.-This contract is not a full `AxisSpec`: logarithmic scales, minor units/gridlines,-crossing values, display units, tick skipping, and other unlisted OOXML semantics-remain unsupported and fail closed on import.--**Narrow XY-axis schema**: `scatter` and `bubble` may use a closed `axes` object-with only `x` and `y` roles. Both roles have `kind: "value"`; `x.position`-is `bottom` or `top`, while `y.position` is `left` or `right`. Each accepts the-same closed fields above, and `major_unit` is valid on both value axes. PPTX-import requires the plot to reference exactly two mutually cross-linked-`c:valAx` nodes and separately enforces the closed field/topology gates. The-native writer emits and the importer reads back every field in this closed-contract. Scatter import derives the effective `scatter_style` from a uniform-per-series line/marker/smooth state; unsupported or nonuniform states remain-fallback-only. The normalized SVG fallback newly consumes only-`axes.x.major_gridlines` and `axes.y.major_gridlines`; the other fields do not-imply full visual-axis parity.--**XY chart schema**: `scatter` and `bubble` use `series[].x` + `series[].y`;-`bubble` also requires one `series[].size` / `series[].sizes` value per point.-`series[].points` is also accepted as `[x, y]` / `[x, y, size]` tuples or-`{x, y, size}` objects.--**Chart typography**: Metadata sizes use the same px-style unit as SVG text-(`1px = 0.75pt`). `style.font_family` and the role-specific-`title_font_size`, `subtitle_font_size`, `axis_font_size`,-`axis_title_font_size`, `legend_font_size`, and `note_font_size` fields are-required only when the native object must preserve typography that cannot be-inferred unambiguously from the visible fallback.--**Chart chrome metadata**: Text that is visually part of the chart must be in-metadata, not only in SVG fallback children; metadata MUST still match visible-fallback chrome. `title` becomes the native chart title on classic charts; it-is not an object name, so use `name` for semantic object naming. `subtitle`-becomes the second rich-text line of that classic chart title. `title`,-`subtitle`, and axis-title values may be strings or objects with `text`,-`font_size`, `font_family`, and `color` when the fallback uses local role-typography. `svg_quality_checker.py` rejects `title`, `subtitle`, or axis-title-metadata whose text is not visible inside the replacement marker's fallback. Direct-`--native-charts-and-tables` export keeps the chart native but omits that inconsistent-chrome with a warning. chartEx keeps PowerPoint's empty `<cx:title>` and emits-the title / subtitle as companion editable text boxes until chartEx rich titles-are validated. Axis-titles are optional and explicit: use `axis_titles` with-`category`, `value`, `x`, `y`, or `secondary_value` keys, or the root aliases-`category_axis_title`, `value_axis_title`, `x_axis_title`, `y_axis_title`, and-`secondary_value_axis_title`; do not add semantic axis titles that are not-visible in the fallback. Set `show_value_axis_labels: false` when the fallback-keeps category labels but omits numeric value-axis tick labels, such as a radar-chart without radial coordinates. Native legends are metadata-controlled: use-`show_legend: true` and `legend_position` only when the fallback's legend is-meant to be replaced by PowerPoint's native legend.-Companion text such as `caption`, `source`, `note`, `notes`, `footnote`, and-`footnotes` is exported as editable PPT text boxes next to the native chart. A-companion entry may be a string or an object with `text`, `x`, `y`, `width`,-`height`, `font_size`, `color`, `align`, and `bold`; explicit bounds are-recommended so the native export matches the SVG fallback placement. Explicit-companion bounds are slide coordinates, not local coordinates inside a-transformed marker group. Use companion text for chart captions, source notes,-center labels, and freeform annotations; use `data_labels` for values that-belong to chart points.--**Chart color styling**: For classic native charts, `style.colors` sets series-colors. The exporter also writes explicit chart-area fill, plot-area fill,-axis line, gridline, and label text colors so PowerPoint does not substitute a-white/default-theme chart. If omitted, the exporter infers these colors from-the visible SVG fallback: the largest panel-like `<rect>` becomes the chart-background, fallback text supplies label color, and fallback strokes supply-axis/grid colors. Override any of them explicitly under `style` with-`chart_area_fill`, `plot_area_fill`, `text_color`, `axis_color`, and-`grid_color`; use `"none"` for transparent chart or plot area fill. Generated-payloads default to uppercase `#RRGGBB`. The exporter retains compatibility for-`#RGB`, `rgb(...)` / `rgba(...)`, and common CSS names, normalizing them to-6-digit OOXML RGB. Bar and column series also disable PowerPoint's negative-value-inversion so negative bars keep the same series fill instead of turning into-white/theme fill.--For ChartEx native charts, valid payload `style.colors` (or root `colors`)-populate the ChartEx color-style part instead of being replaced by a fixed-accent1–accent6 list. Other ChartEx style semantics remain normalized.--**PowerPoint chartEx schema**: `treemap`, `sunburst`, `histogram`, `pareto`,-`boxWhisker`, `waterfall`, and `funnel` use Office 2016+ chartEx parts. Use-these input shapes:--| Type | Required data |-|---|---|-| `treemap`, `sunburst` | `values` plus either `levels` (`levels[level][point]`) or path-style `categories` (`[["Region", "Group", "Leaf"], ...]`) |-| `treemap` display note | Top-level group labels default to `overlapping`; override with `parent_label_layout: "banner" \| "overlapping" \| "none"`. PowerPoint labels only the top level and leaves — intermediate levels group tiles spatially without labels (sunburst shows every ring). |-| `histogram` | `values` |-| `pareto`, `waterfall`, `funnel` | `categories` + `values`; `waterfall` also accepts `subtotals` / `subtotal_indices` point indexes |-| `boxWhisker` | `series[].values`; optional `series[].categories` per value |--> Note: chartEx files are valid PPTX and editable in PowerPoint; non-Microsoft-> renderers can display a limited subset.--**Stock chart schema**: `stock` uses numeric Excel date serials in-`categories` or `dates`, plus exactly four series in open / high / low / close-order. Use either `series` with four entries, or top-level `open`, `high`,-`low`, and `close` arrays. PPTX import currently recognizes only canonical OHLC-stock charts with shared numeric date caches, `hiLowLines`, and `upDownBars`.-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. HLC, volume, noncanonical structure, and style XML-outside the safe parsing boundary stay fallback-only.--**PPTX chart-import boundary**: The importer recognizes conservative classic-single-plot charts plus the verified scatter/bubble XY-axis, column/line/area-combo, area date-axis, canonical OHLC stock, radar, safe `of_pie` `serLines`,-axis/title/legend normalization, and bar/column gap/overlap subsets. Imported-`gapWidth` must be one canonical integer in `0..500`; imported `overlap` must be-one canonical integer in `-100..100`. Both values intentionally normalize to-the native writer contract rather than claiming exact source-style retention.-Malformed, duplicate, or out-of-range values fail closed.--ChartEx import is closed to seven validated data models: `treemap`, `sunburst`,-`histogram`, `pareto`, `box_whisker`, `waterfall`, and `funnel`. The importer-retains their supported hierarchy/category/value/series/subtotal topology for-native read-back. Numeric cache values must be non-empty and finite, and cache-counts/indexes must be canonical non-negative decimal integers with exact,-contiguous topology; malformed, non-numeric, `NaN`, infinite, sparse, duplicate,-or mismatched caches fail closed. ChartEx style, axis, label, and binning details-outside the payload normalize. Full `AxisSpec`, arbitrary ChartEx families or-presentation fidelity, arbitrary stock variants, and axis/combo/date-axis-semantics outside the closed fields above remain fallback-only. The C4/C5-import work does not expand the normalized SVG renderer and does not reduce-existing SVG-marker-to-native writer support.--**Deferred chart types**: Exploded pie / doughnut variants, `map`, `heatmap`,-`bullet`, and `gantt` are intentionally outside the current native-object-support boundary. The exporter fails fast for these types until each mapping is-implemented and validated one by one.--**Supported chart types**:--- `column`, `bar`: `clustered`, `stacked`, or `percentStacked` (`grouping`)-- `line`: `standard`, `stacked`, or `percentStacked` (`grouping`); `line` or `lineMarker` (`line_style`, default `line` / no markers)-- `area`: `standard`, `stacked`, or `percentStacked` (`grouping`)-- `pie`: exactly one series, per-slice colors-- `doughnut`: exactly one series, per-slice colors-- `pieOfPie`, `barOfPie`: exactly one series, per-slice colors-- `radar`, `radarMarkers`, `radarFilled`-- `scatter`: `marker` (default), `lineMarker`, `line`, `smoothMarker`, or `smooth` (`scatter_style`)-- `bubble`: x/y/size series-- `combo`: `column`, `line`, and `area` plots, optional secondary value axis-- `treemap`, `sunburst`: hierarchical chartEx charts-- `histogram`, `pareto`-- `boxWhisker`-- `waterfall`, `funnel`-- `stock`: open / high / low / close series--3D chart aliases (`3DColumn`, `3DBar`, `3DLine`, `3DArea`, `3DPie`, cone,-cylinder, pyramid variants, and `surface`) are unsupported.--Native legends are opt-in through `show_legend: true`; `legend_position`-defaults to `bottom` and accepts `top`, `left`, or `right`.--**Forbidden — replacement marker transforms**: Do not rotate, skew, or matrix-transform table/chart replacement groups. Translate / scale is accepted; complex transforms fail export because PowerPoint-native table/chart frames do not preserve arbitrary SVG transforms.--### PPTX Structure Routing--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 confirmed with `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 materialized workspace.--**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 create a new Layout identity only when fixed Layout atoms or slot topology/bounds change. Update the page mapping immediately while authoring the first such page; never mutate a reused key silently.--### Explicit PPTX Master / Layout / Placeholder Metadata--**Trigger**: This explicit metadata interface applies only to new pages generated from a current deck/layout template workspace with `template_reuse_scope: mirror|layout`. `spec_lock.md` declares `pptx_structure.mode: structured`, complete unique `pptx_masters` / `pptx_layouts` rosters, one `page_pptx_layouts` assignment per generated page, and `page_layouts` as authoring-prototype provenance. `template_reuse_scope: style`, free-design, and brand-only SVGs use `mode: flat` and none of these metadata fields.--**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 may allocate a new Layout key/name only when fixed Layout atoms or slot topology/bounds change; update the lock during authoring. Mirror-created prototypes preserve validated source identity, literal paint, typography, effects, atomic geometry, and referenced assets in a new workspace. `standard` / `fidelity` never make source topology authoritative; mirror does not synthesize a 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-the two optional canonical booleans below so export can write the preserved source-package fields without inferring visibility from which shapes happen to be-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-locked `title` size to every `a:defRPr` in Master `p:titleStyle`. Level 1 in-both `p:bodyStyle` and `p:otherStyle` uses the locked `body` size; 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 |-|---|---|---|-| `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` |--**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.--**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-size to the generated Layout prompt run and-`p:txBody/a:lstStyle/a:lvl1pPr/a:defRPr@sz`. It does not rewrite Slide direct-runs or Layout levels 2–9. This preserves the layout-specific size when-level-one placeholder text is inserted or reset; placeholders without a direct-prototype size remain unchanged.--| Metadata | Placement | Behavior |-|---|---|---|-| `data-pptx-master="master-default"` | root `<svg>` | Binds the slide to one generated Slide Master key |-| `data-pptx-master-name="Default Master"` | root `<svg>` | Sets the Master picker/display name |-| `data-pptx-layout="content"` | root `<svg>` | Binds the slide to one generated reusable layout key |-| `data-pptx-layout-name="Title and Content"` | root `<svg>` | Sets the PowerPoint layout-picker name; defaults from the layout key |-| `data-pptx-show-master-shapes="false"` | root `<svg>` | Accepts exact lowercase `true` or `false` and writes the assigned Layout's `p:sldLayout@showMasterSp`; every SVG using the same Layout key must repeat the same value; omission means `true` |-| `data-pptx-show-inherited-shapes="false"` | root `<svg>` | Accepts exact lowercase `true` or `false` and writes this Slide's `p:sld@showMasterSp`; `false` hides inherited Layout and Master shapes without removing backgrounds, placeholders, parts, or parent relationships; omission means `true` |-| `data-pptx-layer="master"` | direct semantic atom | Moves one repeated static object/background into the named Slide Master; ordinary `<g>` is forbidden, while one validated compact authored-preset `<g>` (§1.5) is an atomic exception |-| `data-pptx-layer="layout"` | direct semantic atom | Moves one repeated static object/background into the selected Layout; ordinary `<g>` is forbidden, while one validated compact authored-preset `<g>` (§1.5) is an atomic exception |-| `data-pptx-layer="slide"` | direct full-canvas solid `<rect>` only | Writes a one-page override as Slide `p:bg` |-| `data-pptx-placeholder="..."` | direct slot `<g id>` | Declares a reusable Layout slot whose visible content remains Slide-local |-| `data-pptx-placeholder-bounds="x y width height"` | slot `<g>` | Supplies the positive reusable design-zone frame in SVG user units with at most two decimals per value |-| `data-pptx-placeholder-idx="1"` | slot `<g>` | Retains an imported source Layout placeholder index; optional for reconstructed layouts |-| `data-pptx-placeholder-carrier="true"` | one compatible direct child of a normal slot | Binds that visible child as the real Slide placeholder carrier |-| `data-pptx-placeholder-binding="proxy"` | composite `object` slot `<g>` only | Keeps the visible group ordinary and creates one hidden transparent binding proxy |-| `data-pptx-editable="false"` | master/layout element or slide background | Declares intentional editing outside ordinary slide content |--**Hard rule — explicit only**: On a structured `template_reuse_scope: mirror|layout` route, every SVG requires the four root Master/Layout identity attributes. Optional inherited-shape visibility uses only exact lowercase `true` / `false`; other spellings fail, and omission means `true`. Every Master/Layout atom and slot requires a unique stable `id` and is a direct root child. Layouts with zero slots are valid. `data-pptx-layout-kind`, `distilled`, and `utility` are legacy metadata and fail the structured contract. Flat `template_reuse_scope: style`, free-design, and brand-only pages omit the entire interface, including the visibility attributes.--**Layer order**: Author the SVG in PowerPoint paint order: Master background,-Layout background, optional Slide background, remaining Master atoms, remaining Layout atoms,-then slot groups and Slide-local content groups. Backgrounds are a special inheritance-plane beneath every shape; this order keeps standalone SVG preview and-PowerPoint rendering aligned. The exporter rejects interleaved layers.--**Solid background ownership**: Structured export deliberately narrows scoped-background ownership to a direct full-canvas solid `<rect>` and disables the-generic conversion-level promotion described in §4.2. Mark the solid rect-`data-pptx-layer="master"` for the deck-wide default,-`data-pptx-layer="layout"` for a page-type override, or-`data-pptx-layer="slide"` for a one-slide override. An unmarked direct-full-canvas solid rect in the background plane is also treated as Slide scope.-A Layout background overrides the Master background; a Slide background-overrides both. Use the Master for a globally stable color and the Layout for-cover/section/content variants under the same design language. Gradient and-preset-pattern rects remain ordinary shapes on declared Master/Layout layers-or as Slide-local content; images remain pictures. Textures, transformed rects,-and visible-stroke rects also remain ordinary objects.--| Placeholder value | Direct carrier inside slot `<g>` | PowerPoint placeholder |-|---|---|---|-| `title`, `subtitle`, `body` | one `<text data-pptx-placeholder-carrier="true">` | `title`, `subTitle`, `body` |-| `date`, `footer`, `slide-number` | one `<text data-pptx-placeholder-carrier="true">` | `dt`, `ftr`, `sldNum` |-| `picture` | one `<image>` or supported imported crop `<svg>`, marked as carrier | `pic` |-| `chart`, `table` | one matching `data-pptx-replace-with` marker group, marked as carrier | `chart`, `tbl` |-| `object` | one text, image, basic SVG shape, or validated compact authored-preset `<g>` marked as carrier; alternatively the slot group declares `binding="proxy"` | `obj` |-| `media` | one `<image>` or supported imported crop `<svg>`, marked as carrier | `media` |--**Text slot carrier**: A multiline text placeholder must remain one-native text frame. Use the default paragraph merge; `--no-merge` cannot supply-several line shapes as one-PowerPoint placeholder prototype/binding. Leave strict-line text Slide-local-when separate frames are the required result.--For a materialized mirror, an imported text carrier may additionally keep the-source shape's positive `data-pptx-frame="x y width height"`. That frame owns-the Slide carrier `a:xfrm`; the converter reconstructs text-body insets from the-visible SVG anchor/baseline instead of shrinking the shape to glyph bounds.-`data-pptx-placeholder-bounds` remains the reusable Layout default and may-legitimately differ. Do not add `data-pptx-frame` to an authored-`standard` / `fidelity` carrier merely to duplicate its Layout bounds.--**Blank text carrier**: Leave a marked text carrier empty or whitespace-only-when the placeholder must remain visually blank. Export materializes one-invisible U+200B run so the carrier still becomes a native PowerPoint text-shape. Do not insert a dummy dash, shrink text below the DrawingML 1pt minimum,-or hide a visible glyph with opacity/background paint; those workarounds either-leak content or produce a PPTX that PowerPoint repairs.--`title` is normally type-matched without an index in reconstructed layouts; if-an imported source title explicitly has one, preserve that exact index. Every-indexed placeholder on one layout uses a unique OOXML UInt32 index. Structured export writes the semantic type on both the Layout and Slide carrier (except `obj`, whose OOXML default is already `obj`) so PowerPoint and `python-pptx` retain the same identity. A composite object slot instead keeps its visible group ordinary and uses a hidden transparent proxy.-Date, footer, and slide-number placeholders enable their matching Layout `p:hf`-flags; a date placeholder also gets a `datetimeFigureOut` field in the reusable-Layout definition. The current Slide keeps its authored date content.--Because an omitted `p:ph@idx` has the effective value `0`, an omitted-index-title reserves `0`; no other placeholder on that Layout may use the same-effective index.--**Slot prototype**: The prototype source declared by the unique Layout definition supplies that Layout's placeholder formatting. `data-pptx-placeholder-bounds` supplies the reusable default frame and is mandatory on every slot. Derive it from-the intended design zone, column, panel inset, safe area, or picture frame —-never from text length, glyph width, line count, or a tight content bounding-box. Repeat the same slot ids/types/effective indices/default bounds/binding modes on every slide using that Layout. The Layout owns the reusable `p:ph`; normal visible carriers keep a matching Slide binding so approved rendering stays identical. A composite `object` proxy adds one hidden transparent binding shape to suppress empty inherited placeholder paint. Bounds define the Layout default only; actual Slide content and local carrier geometry may differ.--**Final-package read-back gate**: After writing a temporary structured PPTX and before publishing it, export reopens the package and-verifies that each published Slide targets exactly one Layout, one Layout key always resolves to the-same part, different keys do not collapse onto one part, and every declared Layout—including one unused by all published Slides—is-registered through its Master and the Presentation. Physical Slide/Layout/-Master part rosters, their content-type overrides, and their Presentation/-Master registrations must be exact. It also verifies the Layout picker name,-Master picker identity, placeholder type and effective index, matching `p:hf` flags, explicit design-zone frame, direct prompt size, and level-one default size.-Every owned `p:bg` is checked as an exact zero-or-one payload against the pre--promotion result; this includes preserving the base Master background when no-authored Master background replaces it. During the same export, every finished-Slide, Layout, and Master must reproduce its exact top-level shape-name roster-and order after packaging. The gate verifies that each carrier-bound slot owns the expected Slide binding, each composite visible carrier remains ordinary, and every composite binding proxy is hidden. A zero-slot Layout must read back with no placeholder. Later slides may keep different Slide-local geometry; only the reusable-Layout frame is checked against the explicit/prototype contract. Any mismatch-fails export without replacing the requested output.--**Static structure consistency**: Repeat the same master element ids on every-slide and the same layout element ids on every slide sharing a layout. Their-generated OOXML must be identical within the affected master/layout group.-Static structure may carry shapes, text, or images; non-image/external-relationships are rejected. Every static object is atomic. An ordinary-`<g data-pptx-layer="master|layout">` is forbidden; the validated compact-authored-preset group from §1.5 is the sole group exception because it compiles-to one native object. A full-canvas first rect may be marked as a Master or-Layout background.--**Native object slot carriers**: `chart` / `table` slots require-`--native-charts-and-tables`; fallback groups contain several shapes and cannot map to one-PowerPoint placeholder. `object` is the generic PowerPoint content slot and-uses either one carrier object—including one validated compact authored-preset-group—or the explicit composite proxy downgrade. `media` currently binds-an authored image/crop to a native `media` placeholder; it does not synthesize-video or audio media from a decorative SVG group.--### Legacy Template Input Boundary--Existing structured/template projects or packages that carry `native_structure.json` / `source_template.pptx`, `pptx_structure.mode: baseline|template|preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled` / `utility`, direct atomic placeholders, or an incomplete root Master identity are not generation/export inputs and are never upgraded in place. Create a separate current workspace through [`create-template`](../workflows/create-template.md). A project explicitly declaring `pptx_structure.mode: flat` is the current free-design/brand-only route and needs no conversion merely because it has no Master/Layout metadata.--| Available source | Allowed create-template behavior |-|---|---|-| Original PPTX Type A | `standard` / `fidelity` author new topology; `mirror` preserves supported Master/Layout/placeholder facts that still exist in the package |-| Legacy or unstructured SVG Type B | `standard` / `fidelity` use pages as visual/contextual reference and author a complete new contract; old metadata is not output topology |-| Complete current SVG Type B | `mirror` may preserve the explicit current contract in a new workspace; authored modes may replace it |--Without an original PPTX or complete current Type B contract, do not claim mirror or source-topology recovery. After template creation, Generate PPTX Step 3 authors new structured `svg_output/` pages; the exporter only compiles those declarations and never derives, repairs, or migrates structure.-------## 8. Scope Boundary+| XML/SVG foundation, compatibility, 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) | 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` |-Generate project structure, commands, quality-gate order, and export products-are owned by [`generate-pptx.md`](../workflows/generate-pptx.md). They are-intentionally outside this SVG authoring policy.+**Hard rule**: This file is a routing pointer, not a combined runtime authority. Do not load every conditional module by default.diff --git a/skills/ppt-master/references/strategist-image.md b/skills/ppt-master/references/strategist-image.mdnew file mode 100644index 00000000..93a18332--- /dev/null+++ b/skills/ppt-master/references/strategist-image.md@@ -0,0 +1,56 @@+> See [`strategist.md`](./strategist.md) for the core role and load trigger.++# Strategist Image Planning++Conditional extension for formula assets, proposed / confirmed image elaboration, AI rendering selection, and `design_spec.md §VIII` resource planning.++**Trigger**: Core first derives proposed `recommend.image_usage`. Load this module before Stage-2 direction construction when that proposal contains any non-`none` source, when the user supplied an explicit non-`none` image constraint, or when formula handling is triggered. After confirmation, the confirmed sources bound production: confirmed `none` with no formula trigger stops before resource authoring. On a formula-only path, read §3 and the formula-row rules in §4; skip non-formula planning. [`strategist.md`](./strategist.md) owns source recommendation; this module owns image-dependent candidates, production detail, and §VIII rows.++---++## 1. Proposed and Confirmed Image Plan++Before Stage 2, use proposed sources only for candidate construction. After confirmation, discard candidate-only sources, map the confirmed set through [`strategist.md`](./strategist.md) §h, and honor `image_notes`; this module never adds a source.++For illustration, apply this precedence: confirmed `none` → explicit user intent → the locked visual style's `Illus.` propensity (`core` / `supportive` / `sparse`) → none. Propensity controls the lean, not the source or a page quota. When illustration is active, prefer one coherent motif family across hero/section anchors and local spots, but only when the confirmed assets can form that family.++For ≥3 AI-generated same-family spots, plan one unplaced `ai` Illustration Sheet row plus one placed `slice` row per used element; only slice rows enter `spec_lock.md images`. State the intended placement shape family in the sheet reference and use separate sheets for incompatible shapes. [`image-generator.md`](./image-generator.md) §4.3 owns grid, ratio, slicing, and execution details. Stage 3 chooses the AI execution path under `image-generator.md` §7; do not pre-empt or re-pick it here.++## 2. AI Image Strategy — propose before Stage 2; lock only for confirmed `ai`++When proposed sources include `ai`, read every entry in [`image-renderings/_index.md`](./image-renderings/_index.md) before constructing Stage 2. Unless the user or active template already names a rendering, place at least three credible, distinct renderings across the coordinated safe/shifted/bold directions; a genuine compatibility shortfall may return fewer with a reason. Each `image_strategy` carries localized `rendering`, `visual`, and `mood` only. Mood includes a recognizable real-world analogy. Image colors always inherit that direction's deck HEX roles; never add an image palette or alter deck colors to rescue a rendering.++`custom` is a tail case: at most one candidate uses it, and its visual prose must satisfy the catalog's custom grammar. A confirmed choice locks one deck-wide `image_rendering` in `design_spec.md §III` and `spec_lock.md colors`; confirmed custom prose also becomes `image_rendering_behavior` and is carried into every AI brief. A confirmed non-custom id needs no behavior row. Ignore legacy `image_palette` rows.++For specialized or regulated paper-figure subjects, preserve the prompt depth required by [`image-generator.md`](./image-generator.md) §4.2 rather than shortening to a generic brief. Scan the outline for genuine image-led pages, list the proposed hero pages in Stage-2 `image_notes` so the user can retain, edit, or remove them in the same confirmation, then mark only the confirmed pages' AI rows `page_role: hero_page`; local is the default. `text_policy: embedded` is reserved for lettering that must be fused into the artwork; ordinary titles, data, labels, and prose remain editable SVG. Analyze confirmed provided assets before writing §VIII.++## 3. Formula Asset Policy++Formula rendering is a conditional choice surfaced in Stage 3 production confirmation. Recommend one policy and let the user confirm or override it:++| Policy | Behavior | Use |+|---|---|---|+| `mixed` (default) | Render complex expressions to PNG; keep simple inline math as editable text / Unicode | Most academic, engineering, educational, and technical decks |+| `render-all` | Render every formula-worthy expression to PNG | Formula-heavy teaching / research decks where consistency matters more than editability |+| `text-only` | Keep expressions as editable text / Unicode | Business decks, light technical briefs, or an explicit editability preference |++`$...$` / `$$...$$` in source material are input signals only. Never scan output files for dollar-delimited formulas. Fractions, radicals, integrals, sums, limits, matrices, multiline derivations, and complex super/subscripts are formula-worthy; short variables, simple assignments, percentages, and expressions such as `O(n log n)` normally remain text. Never invent an equation for decoration.++For `mixed` or `render-all`, write selected source expressions to `<project_path>/images/formula_manifest.json` before writing the final spec, then run:++```bash+python3 skills/ppt-master/scripts/latex_render.py <project_path>+python3 skills/ppt-master/scripts/analyze_images.py <project_path>/images+```++Follow `latex_render.py --help` for the manifest fields. The renderer writes dimensions, ratio, file, provider, and status back into it. Formula PNGs default to transparent; use an opaque final background only when the asset requires it.++## 4. Image Resource List++Add §VIII for every confirmed non-`none` source and selected formula; a formula-only plan contains only formula rows. Fill the scaffold's filename, dimensions/ratio, layout suggestion/pattern, purpose/type, acquisition, status, reference, and conditional AI fields. `Acquire Via` is `ai`, `web`, `user`, `formula`, `placeholder`, or `slice`; status follows [`svg-image-embedding.md`](./svg-image-embedding.md). References describe visual intent: AI uses subject + intent + composition without repeating rendering or HEX; web uses a concrete subject plus a few positive quality descriptors; formula preserves the source LaTeX and placement intent.++🚧 **GATE — non-formula rows**: read every entry in [`image-layout-patterns.md`](./image-layout-patterns.md). Copy one primary `#<id> <name>` plus any modifier names verbatim into each row; no empty, paraphrased, or invented ids. For decks with at least four image-bearing pages, use an Image-as-Canvas + Native Overlay pattern at least once unless every image is purely a cover, divider, or atmospheric backdrop; record the legitimate exception below the table. Reconsider a plan that collapses every row to the same left/right or top/bottom split.++Choose narrative intent before dimensions: hero/full-bleed, atmosphere/background, side-by-side, or accent/inline. Only side-by-side containers follow native ratio; portrait and multi-image calculations belong to [`image-layout-spec.md`](./image-layout-spec.md). Most assets are croppable. Add `no-crop` in `spec_lock.md images` only for screenshots, charts, certificates/contracts, dense diagrams, and every formula; formula rows use `Type: Latex Formula`, `Acquire Via: formula`, and `Rendered` or `Needs-Manual`.++Judge `text_policy` per AI row using [`image-generator.md`](./image-generator.md) §5.3; paper figures, academic schematics, panel comparisons, and data-axis graphics are positive triggers for reconsidering an all-`none` plan. Step 5 dispatches pending `ai` / `slice` rows to Image_Generator and pending `web` rows to Image_Searcher; formula rows bypass both.diff --git a/skills/ppt-master/references/strategist-template.md b/skills/ppt-master/references/strategist-template.mdnew file mode 100644index 00000000..f6c773c3--- /dev/null+++ b/skills/ppt-master/references/strategist-template.md@@ -0,0 +1,67 @@+> See [`strategist.md`](./strategist.md) for the core role and load trigger.++# Strategist Template Planning++Conditional extension for applying an installed Brand/Layout/Deck workspace to Stage 2 recommendations and the execution lock.++**Trigger**: Load only when Generate Step 3 copied an explicit workspace path into `<project_path>/templates/`. Bare template names, style words, and free-design projects do not trigger this module.++---++## 1. Reuse Scope and Adherence++**Template vs preset**: A style mention and a template directory are different inputs. Bare names and style words map to a visual-style preset; only the installed workspace activates the rules below. Its fused `<project_path>/templates/design_spec.md` is the template-design source.++**Legacy template boundary**: A template containing `native_structure.json`, `source_template.pptx`, missing root Master identity, direct atomic placeholders, or old `baseline` / `preserve` / distillation metadata is not a Generate Step 3 input. Create a current workspace through [`create-template`](../workflows/create-template.md), preferably from the original PPTX when native topology matters. Do not mutate the input in place.++**Template reuse confirmation**: Surface `template_reuse_scope` only for an installed `kind: deck` or `kind: layout` workspace. Omit it for brand-only workspaces.++| Reuse scope | Planning and export behavior |+|---|---|+| `mirror` | Mirror workspaces only. Start from the full selected page, preserve literal visuals and text-node topology, and replace only allowed visible text values. |+| `layout` | Reuse the template Master/Layout system and input prototypes, but allow project-controlled reflow/re-skinning and explicit adaptive Layouts. |+| `style` | Reuse only color, typography, decoration language, and rhythm. Plan `pptx_structure.mode: flat` with no template structure mappings. |++**Deterministic language mapping**: “不要严格复用”, “只参考风格”, “参考这个风格”, and “不必照搬版式” recommend `style` unless the user explicitly asks to retain the layout system, in which case recommend `layout`. “原样复刻”, “替换内容”, and “保持模板页面外观” recommend `mirror` only when `replication_mode: mirror` is available. A bare workspace path with no stronger language defaults to `layout`.++For `mirror` / `layout`, surface `template_adherence`. Hide it for `style`.++| Value | Planning and export behavior |+|---|---|+| `strict` | Map every page to one template SVG. Keep its explicit Master/Layout/slot contract and output Layout key unchanged. |+| `adaptive` | Map every page to the closest template SVG. Keep the template Master contract, but allow a new explicit Layout key when content requires a structural adaptation. |++**Default — layout + adaptive**: For a workspace path without stronger language, recommend `layout` and `adaptive`. Preselect `strict` only when the user explicitly asks to keep the selected Layout contract unchanged. Record the confirmed scope in `design_spec.md §I` and `spec_lock.md pptx_structure`; record adherence only for `mirror` / `layout`.++---++## 2. Scenario Fit and Inherited Design++**Mandatory — consume the stored contract at the decision point**: Immediately before recommending reuse for an installed `kind: deck`, re-read `<project_path>/templates/design_spec.md`. Compare its five `## I. Template Overview` application-contract rows with the confirmed audience, intent, outcome, delivery context, artifact afterlife, and source obligations. Compare every `## V. Page Roster` content-policy value with the required narrative/page roles, including required / optional / repeatable status and fixed / replaceable / example-only content. Treat the contract as applicability evidence, never as the current project's truth; do not copy it into blank Stage-1 fields or infer fields it does not declare. For `kind: layout`, no application contract exists: compare only the roster's structural roles, slots, and capacity.++| Scope | Appropriate when |+|---|---|+| `mirror` | The artifact repeats a known form; literal appearance and text topology are requirements; new content fits existing roles and slots. |+| `layout` | The structural system and brand continue, but the communication outcome requires reflow, new emphasis, or an adaptive Layout. |+| `style` | Only visual identity is reusable, or the outcome requires a different sequence, density, or composition system. |++When the communication contract conflicts with the workspace, surface the mismatch. Template capability constrains what is legal; scenario fit decides what is useful.++> Note: `content_divergence` controls source reorganization; `template_reuse_scope` controls the reused layer; `template_adherence` controls strictness inside `mirror` / `layout`.++**Template design precedence**: User overrides win. Otherwise lock declared colors and title/body font stacks from the fused template `design_spec.md` directly; skip generic color/font candidates and do not adjust template values to fit an industry default. Keep the workspace's declared icon and image constraints when producing those conditional plans.++---++## 3. Structured Lock Planning++For `mirror` / `layout`, write `pptx_structure.mode: structured` plus `template_adherence: strict|adaptive`. Do not write legacy `baseline`, `template`, `preserve`, `layout_strategy`, or Layout-kind rows.++- **Master roster**: Write one `pptx_masters` row per Master as `<master_key>: <picker name>` and copy the workspace's prototype roster. Keys use 1–64 ASCII letters, digits, dots, underscores, or hyphens, start with a letter/digit, and contain no spaces; human-readable spaces belong only in the picker name. Master visuals are root-level atomic elements and may never be `<g>`.+- **Reusable Layout roster**: Write every unique Layout once as `<layout_key>: <master_key> | <PowerPoint layout name> | <prototype source>`. Copy installed `template:<basename>` sources, including currently unused Layouts. A new adaptive Layout uses its first generated `P<NN>` as source. Reuse a key only when fixed atoms and slot ids/types/indices/bounds/binding modes are identical. Name authored keys after composition, never page topic. A Layout may intentionally have zero slots; do not manufacture an empty `utility` kind or full-page fake slot.+- **Page assignment**: Write exactly one `page_pptx_layouts` row per page. Each key must exist in `pptx_layouts`. Check that distinct compositions do not collapse into role-only keys and that one skeleton does not split into topic-specific keys.+- **Slot planning**: Each reusable slot is a direct root `<g id>` with `data-pptx-placeholder`, positive design-zone bounds, and exactly one compatible direct carrier. Bounds come from the intended safe area, column, panel inset, or media frame—not sample text ink. A genuinely composite region may use only the explicit `object` + `proxy` downgrade.+- **Adaptive refinement**: Initial definitions are complete. If construction changes reusable framing or slot topology/bounds, Executor creates one new definition sourced from that page and updates its assignment; it never mutates a reused contract silently. Export only compiles declared structure and never discovers or clusters Layouts.+- **Input prototypes**: Add one `page_layouts` row per page. Strict preserves that SVG's contract; adaptive keeps its Master and may declare a new output Layout; mirror also preserves literal visuals and text-node topology.++**Chart compatibility**: Use `page_layouts` together with `page_charts` only when the selected prototype shell is compatible. For a chart page without an exact roster match, adaptive mode starts from the closest neutral prototype and declares an output Layout; strict mode selects an existing compatible Layout or revises the outline. Never omit `page_layouts` on a structured route.diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex c34d57b2..3f3322ac 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -20,7 +20,7 @@ As a top-tier AI presentation strategist, receive source documents, perform cont## 1. Strategist Confirmation Stage-🚧 **GATE — Mandatory read first**: `read_file templates/design_spec_reference.md` before any analysis or writing. The design_spec.md output MUST follow that template's 10-section structure exactly. After writing, self-check each section is present: I Project Info → II Canvas → III Visual Theme → IV Typography → V Layout → VI Icon → VII Visualization → VIII Image → IX Outline → X Speaker Notes.+🚧 **GATE — artifact structure**: Generate Step 4 creates both versioned scaffolds before authoring. Fill those files in place and run `project_manager.py validate`; the machine schemas, not remembered headings, own their grammar.⛔ **BLOCKING**: After the read, present professional recommendations for the confirmation fields below and wait for explicit user confirmation.@@ -38,7 +38,7 @@ Do not force communication intent into one catalog label. A deck may report prog>> **One opt-in exception**: present the spec-refinement line alongside the split-mode note ([`generate-pptx.md`](../workflows/generate-pptx.md) Step 4). It is OFF by default — the above discipline holds unchanged. Only when the user *explicitly* asks to refine the spec do you hand off to the [refine-spec](../workflows/stages/refine-spec.md) stage, which produces the full spec first and stops for user review/revision of any part before generation. Never enter it unprompted.-> **Default presentation surface — Confirm UI.** Deliver the package through the interactive page: write recommendations to `<project>/confirm_ui/recommendations.json`, then launch per [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4. Stage 2 `design_directions` carries **≥3 coordinated candidates** (safe / shifted / bold); each bundles visual style, color, CJK + Latin typography, icons, and conditional generated-image rendering. This is one set of real alternatives, not independent candidate grids that happen to share a screen. Honest-shortfall exception: if the constraints genuinely cannot yield 3 non-conflicting directions, present the smaller set and say why—never pad with duplicates or conflicts. **Always also print the recommendations + URL in chat** as the fallback. On confirm, read `<project>/confirm_ui/result.json` (`generation_mode: "split"` / `refine_spec: true` are explicit user choices). Skip the page if the user wants chat-only. Full schema and lifecycle live in [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4 + [`scripts/docs/confirm_ui.md`](../scripts/docs/confirm_ui.md).+> **Default presentation surface — Confirm UI.** Deliver the package through the interactive page: write recommendations to `<project>/confirm_ui/recommendations.json`, then launch per [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4. Stage 2 `design_directions` carries **≥3 coordinated candidates** (safe / shifted / bold); each bundles visual style, color, CJK + Latin typography, icons, and conditional generated-image rendering. This is one set of real alternatives, not independent candidate grids that happen to share a screen. Honest-shortfall exception: if the constraints genuinely cannot yield 3 non-conflicting directions, present the smaller set and say why—never pad with duplicates or conflicts. **Always also print the recommendations + URL in chat** as the fallback. On confirm, read `<project>/confirm_ui/result.json` (`generation_mode: "split"` / `refine_spec: true` are explicit user choices). Skip the page if the user wants chat-only. Generate Step 4 owns when to write, wait, and block; [`confirm_ui.md`](../scripts/docs/confirm_ui.md) owns the schema, lifecycle, and fallback contract.### a. Canvas Format Confirmation@@ -123,7 +123,7 @@ The deck's **visual aesthetic** — shape language, decoration density, whitespa**Source**:- User named a style (chat / template / beautify) → it is truth: map to the closest preset (or `custom` with a `visual_style_behavior` paragraph) and lock directly. **Skip the spectrum below** — do not re-offer choice they already made.-- No user description → **present a personality spectrum, not one safe pick** (this is the lever against "every deck looks the same" — the visual style is what most determines a deck's character, so it gets real choice, same hard rule and thinking as h.5). Author **≥3 distinct styles** from the index's auto-selection table spanning *safe* (the industry-norm recommendation) → *shifted* (an alternate one tick more expressive) → *bold* (a characterful style that challenges the default — `brutalist` / `zine` / `memphis` / `ink-wash` / `vintage-poster` etc., whenever the content can carry it). Give each a one-line **temperament tag + real-world analogy** (like h.5's "like an Economist feature"). Write the three to `recommendations.json` `visual_style_spectrum` (each `{id, tag_zh/en/ja, note_zh/en/ja}` — include the `_ja` variants whenever the page `lang` is `ja`) **and present the same three in chat** as the always-valid fallback; set `recommend.visual_style` to the *safe* pick as the pre-selected default. The user may pick any of the three, a style outside them, or Custom. Honest-shortfall exception (mirrors h.5): if the content genuinely supports fewer than 3 non-gimmicky directions, present the smaller set and say why — never pad with a style that fights the content.+- No user description → **present a personality spectrum, not one safe pick** (this is the lever against "every deck looks the same" — the visual style is what most determines a deck's character, so it gets real choice, like the alternative-set rule used for image rendering). Author **≥3 distinct styles** from the index's auto-selection table spanning *safe* (the industry-norm recommendation) → *shifted* (an alternate one tick more expressive) → *bold* (a characterful style that challenges the default — `brutalist` / `zine` / `memphis` / `ink-wash` / `vintage-poster` etc., whenever the content can carry it). Give each a one-line **temperament tag + real-world analogy** (for example, "like an Economist feature"). Write the three to `recommendations.json` `visual_style_spectrum` (each `{id, tag_zh/en/ja, note_zh/en/ja}` — include the `_ja` variants whenever the page `lang` is `ja`) **and present the same three in chat** as the always-valid fallback; set `recommend.visual_style` to the *safe* pick as the pre-selected default. The user may pick any of the three, a style outside them, or Custom. Honest-shortfall exception: if the content genuinely supports fewer than 3 non-gimmicky directions, present the smaller set and say why — never pad with a style that fights the content.**Forbidden — a non-catalog name as `visual_style`**: the value MUST be an `id` from the visual-styles catalog (or genuine `custom` prose). A name that is **not** in that catalog is not a visual style — most often it is an image-rendering name from the `_index` "Paired rendering" column (`flat`, `vector-illustration`, `digital-dashboard`, `3d-isometric`, `corporate-photo`, …), which names the §h *illustration* family, not the deck's layout aesthetic. Do not borrow it. (Names that are intentionally **both** a style and its paired rendering — `glassmorphism`, `blueprint`, `editorial`, `dark-tech` — are valid styles because they *are* in the catalog.) Generic baseline words — `flat` / flat-design / 扁平 / modern / clean / simple / minimal — are **not** custom-worthy either: the whole system is flat by default (shadows discouraged), so map them to the closest preset (flat + grid → `swiss-minimal`; flat + rounded → `soft-rounded`; flat + dense → `brutalist`). Reserve `custom` for an aesthetic no preset covers.@@ -131,50 +131,13 @@ The deck's **visual aesthetic** — shape language, decoration density, whitespaWrite the locked value to `spec_lock.md` `- visual_style:` and the rationale to `design_spec.md`. Executor loads only that one visual-style file.-> **Template vs preset**: a style mention and a template name remain different inputs ("minimalist" vs the `presentation_core/` template directory). Step 3 only triggers on an explicit template directory path supplied by the user — bare names and style words never copy templates; they map to a visual-style preset here. If a template was triggered upstream, its files are already in `<project_path>/templates/` and its fused design_spec governs.--**Legacy template boundary**: A template containing `native_structure.json`, `source_template.pptx`, missing root Master identity, direct atomic placeholders, or old `baseline` / `preserve` / distillation metadata is not a Step 3 input. Create a new current workspace through [`create-template`](../workflows/create-template.md), preferably from the original PPTX when existing native topology matters. Do not plan against a legacy compatibility contract or mutate the input in place.--**Template reuse confirmation**: Surface `template_reuse_scope` only when Step 3 loaded a `kind: deck` or `kind: layout` template. Omit it for free design and brand-only templates.--| Reuse scope | Planning and export behavior |-|---|---|-| `mirror` | Mirror workspaces only. Start from the full selected page, preserve literal visuals and text-node topology, and replace only allowed visible text values. |-| `layout` | Reuse the template Master/Layout system and input prototypes, but allow project-controlled reflow/re-skinning and explicit adaptive Layouts. |-| `style` | Reuse only color, typography, decoration language, and rhythm. Plan a free-design `pptx_structure.mode: flat` deck with no template structure mappings. |--**Deterministic language mapping**: “不要严格复用”, “只参考风格”, “参考这个风格”, and “不必照搬版式” recommend `style` unless the user explicitly asks to retain the layout system, in which case recommend `layout`. “原样复刻”, “替换内容”, and “保持模板页面外观” recommend `mirror` only when `replication_mode: mirror` is available. A bare template path with no stronger language defaults to `layout`, not `mirror`.--For `mirror` / `layout`, surface the second closed Stage-2 choice, `template_adherence`. Hide it for `style`.--| Value | Planning and export behavior |-|---|---|-| `strict` | Map every page to one template SVG. Keep its explicit Master/Layout/slot contract and output Layout key unchanged. |-| `adaptive` | Map every page to the closest template SVG. Keep the template Master contract, but allow a new explicit Layout key when the selected composition must adapt to the content. |--**Default — layout + adaptive**: When the user supplied only a template path, recommend `layout` and `adaptive`. Preselect `strict` only when the user explicitly asks to keep the selected Layout contract unchanged. Record the confirmed scope in `design_spec.md §I` and as `template_reuse_scope` under `spec_lock.md pptx_structure`; record adherence only for `mirror` / `layout`.--**Mandatory — consume the stored contract at the decision point**: Immediately before authoring the Stage-2 reuse recommendation for an installed `kind: deck`, re-read `<project_path>/templates/design_spec.md`. Compare the five application-contract rows in `## I. Template Overview` with the confirmed Stage-1 audience, intent, outcome, delivery context, artifact afterlife, and source obligations. Then compare every `## V. Page Roster` content-policy value with the narrative/page roles the current artifact needs, including required / optional / repeatable status and fixed / replaceable / example-only content. Treat the stored contract as applicability evidence, never as the current project's truth; do not copy it into blank Stage-1 fields or infer fields it does not declare. For `kind: layout`, no application contract exists: compare the current contract only with the roster's structural roles, slots, and capacity.--**Scenario fit comes before template capability.** A workspace advertising `mirror` does not mean the project should consume it in mirror mode. Recommend from the confirmed communication contract:--| Scope | Appropriate when |-|---|---|-| `mirror` | The artifact is a repeat of a known recurring form; literal appearance and text topology are requirements; the new content fits the prototype's existing page roles / slots without changing the argument structure. |-| `layout` | The same structural system and brand should continue, but the new communication outcome requires reflow, new page-level emphasis, or an explicit adaptive Layout. |-| `style` | Only visual identity is reusable, or the audience outcome / narrative needs a different sequence, density, or composition system. |--When the contract conflicts with the template, surface the mismatch in the recommendation instead of forcing content into the available shapes. Template capability constrains what is legal; scenario fit decides what is useful.--> Note: `content_divergence` controls how source material is reorganized; `template_reuse_scope` controls which template layer is reused; `template_adherence` controls structural strictness inside `mirror` / `layout`. Never collapse these axes.+**Conditional template workspace**: When Generate Step 3 installed an explicit workspace path into `<project_path>/templates/`, read [`strategist-template.md`](./strategist-template.md) before completing Stage 2. It owns reuse/adherence, inherited design precedence, and structured-lock planning. Bare names, style words, and free-design projects do not trigger it.**Downstream effect**: e / f / g / h realize the locked mode + visual style. Example: `showcase` + `dark-tech` → e applies one luminous accent on a dark field; g pairs a clean sans with mono; f minimal glow icons; h the `digital-dashboard` rendering.### e. Color Scheme Recommendation-**Hard rule**: User / template colors are truth. If the user has specified colors (HEX, brand colors, or natural-language directives like "use blue as primary"), or a template was loaded at Step 3 via an explicit path (`<project_path>/templates/design_spec.md`), lock those directly and skip the recommendation table. Do not adjust them to fit any palette or industry default. Only when no color signal exists from user or template do you proactively propose a scheme below.--> Step 3 already collapses brand and layout inputs into one fused `design_spec.md`; this layer reads from that single source and does not need to re-resolve brand vs layout precedence.+**Hard rule**: User-specified colors are truth. Lock supplied HEX, brand colors, or natural-language color directives directly and skip the recommendation table. When [`strategist-template.md`](./strategist-template.md) is active, apply its inherited-design precedence. Only when neither source exists do you propose a scheme below.Proactively provide a color scheme (HEX values) based on content characteristics and industry.@@ -237,515 +200,112 @@ See [`../templates/icons/README.md`](../templates/icons/README.md) for the curre### g. Typography Plan Confirmation (Font + Size)-🚧 **GATE — read the locked style's type character first**: `read_file` the visual-style file locked at §d Layer 2 (`visual-styles/<visual_style>.md`) and pull its **§2 Typography character** (you only read the catalog index there; the per-style character lives in the file). Both combinations below MUST realize it, and the **title carries the personality** — the CJK body may stay a neutral pre-installed sans, but the title leads with the character the style asks for (e.g. `ink-wash` → calligraphic `KaiTi` / `FangSong`; `brutalist` / `memphis` / `vintage-poster` / `zine` → display `SimHei` / `Impact`; `editorial` / `data-journalism` / `photo-editorial` → serif `Georgia` / `Cambria` / `SimSun`; `dark-tech` / `blueprint` → clean sans + `Consolas` mono; `swiss-minimal` / `soft-rounded` → grotesque / friendly sans). For `visual_style: custom`, realize its `visual_style_behavior` character instead. Letting the title default to a neutral sans when the style asks for character is the failure mode to avoid.--#### Font Combinations--> Same-deck fonts must form **contrast** (different family, weight, or proportion) or **concord** (one family throughout). "Similar but not identical" pairings *across roles* are forbidden — see blacklist below. *Within one stack*, pairing a Windows font with a macOS counterpart (e.g. `Microsoft YaHei` + `PingFang SC`) is a browser-preview nicety; converter writes resolved Latin / EA typefaces into PPTX, not the CSS fallback tail.+🚧 **GATE**: Read the locked visual-style file's §2 Typography character before recommending type. For a custom style, use its `visual_style_behavior`. The title carries the character; the body may remain neutral.-> **⚠️ PPT-safe font discipline (HARD rule).** PPTX has no runtime fallback — missing fonts substitute to Calibri. Each stack's exported Latin / EA typefaces MUST resolve to pre-installed fonts:-> - CJK → `"Microsoft YaHei"` / `SimHei` / `SimSun` / `FangSong` / `KaiTi`-> - Latin sans → `Arial` / `Calibri` / `Segoe UI` / `Verdana` / `Trebuchet MS`-> - Latin serif → `"Times New Roman"` / `Georgia` / `Cambria` / `Palatino` / `Garamond`-> - Mono → `Consolas` / `"Courier New"`-> - Display → `Impact` / `"Arial Black"`->-> Stacks that export non-pre-installed typefaces (Inter / HarmonyOS Sans / Source Han / brand typefaces like McKinsey Bower) are only acceptable when the Design Spec notes "requires install or PPTX embed".--**Forbidden — similar-but-not-identical pairings across roles** (do not split title vs body across these; within one stack as cross-platform fallback they remain encouraged):--- `Microsoft YaHei` ↔ `PingFang SC` ↔ `Heiti SC`-- `SimSun` ↔ `Songti SC` ↔ `STSong`-- `Arial` ↔ `Helvetica Neue` ↔ `Segoe UI`-- `"Times New Roman"` ↔ `Times`-- `Georgia` ↔ `Cambria`--**Mandatory**: propose **two** combinations to the user — one concord (safe), one contrast (with tension). Do not default to "title = body, same font" without explicit user request. Pick each family by subject fit and the locked `visual_style`'s **§2 character** (read at the GATE above) — there is **no default family**; type should follow the deck's content and aesthetic, not fall back to one safe face.--> **Template precedence**: when a template was loaded at Step 3 via an explicit path and declares `title` / `body` font stacks in `<project_path>/templates/design_spec.md §III Typography` / §IV (or whichever heading the fused spec uses), lock those directly and skip the two-combination presentation. Same precedence as e. — user override > template values.--**Cross-platform pre-installed reference**:--| Category | Safe families |-|----------|--------------|-| CJK sans | Microsoft YaHei, SimHei, PingFang SC, Heiti SC |-| CJK serif | SimSun, FangSong, KaiTi, Songti SC |-| Latin sans | Arial, Calibri, Segoe UI, Verdana, Trebuchet MS, Helvetica Neue |-| Latin serif | Times New Roman, Georgia, Cambria, Palatino, Garamond, Book Antiqua |-| Mono | Consolas, Courier New |-| Display | Impact, Arial Black |--**Seed combinations** (all PPT-safe; first column is the contrast axis, not a scenario) — starting points, not the allowed set. Any client-preinstalled family is fair game; non-pre-installed expressive faces go title-only (see note below). Let the locked style's §2 character pick the axis and the title lead; the `Microsoft YaHei` body cells are the **neutral default, not a requirement** — a styled deck still varies the title even when the CJK body stays a neutral sans.--| Contrast axis | Title stack | Body stack | Code stack |-|---|---|---|---|-| Serif × sans | `Georgia, KaiTi, serif` | `"Microsoft YaHei", "PingFang SC", sans-serif` | — |-| Kai × hei | `KaiTi, Georgia, serif` | `"Microsoft YaHei", "PingFang SC", sans-serif` | — |-| Fangsong × hei | `FangSong, "Times New Roman", serif` | `SimHei, "Microsoft YaHei", sans-serif` | — |-| Double serif | `Palatino, FangSong, serif` | `Cambria, SimSun, serif` | — |-| Same family, weight contrast (900 / 300) | `"Microsoft YaHei", "PingFang SC", sans-serif` | same | — |-| Display × neutral | `Impact, "Arial Black", SimHei, sans-serif` | `Arial, "Microsoft YaHei", sans-serif` | — |-| Cool serif (academic) | `Cambria, SimSun, serif` | `"Times New Roman", SimSun, serif` | — |-| Hei × song (政务) | `SimHei, "Microsoft YaHei", sans-serif` | `SimSun, serif` | — |-| Tech / developer | `Arial, "Microsoft YaHei", sans-serif` | same | `Consolas, "Courier New", monospace` |-| Concord (single family — pick the family by subject + `visual_style`) | `<family by subject>, …, sans-serif / serif` | same | — |--> **Stack length discipline (soft rule).** ≤4 fonts per stack. The exported CJK / Latin typefaces MUST be pre-installed after converter resolution ([`drawingml/utils.py parse_font_family`](../scripts/svg_to_pptx/drawingml/utils.py)). Choose those exported faces from the safe set **by the locked style's character**: `Microsoft YaHei` / `Arial` are the *neutral* members — perfect as the tail fallback and as the lead only when the style is plain-sans, but **not the automatic lead for every deck**. For a styled title, lead with `SimHei` / `KaiTi` / `FangSong` / `SimSun` / `Georgia` / `Cambria` / `Impact` / `Consolas` as the character asks. Keep at most **one** macOS-exclusive family (typically `"PingFang SC"`); macOS→Windows fallback is auto-mapped via `FONT_FALLBACK_WIN`.--> **Non-pre-installed directions** (require install or PPTX embed; note the constraint in Design Spec):-> - **Retro / pixel** — Press Start 2P / VT323 / Silkscreen-> - **Rounded friendly** — Nunito / Quicksand / M PLUS Rounded / OPPO Sans (closest safe substitute: `Trebuchet MS` / `Verdana`)-> - **Modern web sans** — Inter / HarmonyOS Sans / Source Han Sans / Noto Sans-> - **Calligraphic display** — 隶书 LiSu / 华文行楷 STXingkai / 华文新魏 STXinwei (closest safe substitute: `KaiTi` / `FangSong`); cover / section / hero titles only, never body-> - **Brand-specific** — McKinsey Bower, corporate VI typefaces--#### Font Size Ramp (px throughout)--> **Ramp, not a fixed menu.** All sizes derive from the `body` baseline as a ratio. `spec_lock.md typography` declares `body` plus the slots this deck uses (`title` / `subtitle` / `annotation` by default; add `cover_title` / `hero_number` / `subheading` / `lead` / `footnote` / `chart_annotation` as the outline demands).->-> **Mandatory — scan `§IX` before locking and declare a slot for every role that recurs across pages.** Do not ship only the four defaults when the outline plainly carries more. A report / `text`-mode deck almost always recurs a per-page **core-message / lead line** (the one-sentence key-claim / takeaway under the title) and recurring **page numbers / source credits / footnotes** — declare `lead` (in the 1.1–1.4× lead band, and **always ≥ `body`** — the core message is a primary line, never smaller than body) and `footnote` (keep it readable — **~16px for a standard body, not shrunk smaller**) for them. Leaving these undeclared forces the Executor to improvise an unlocked size, and a core line improvised *below* `body` (with data callouts sitting larger) is exactly the hierarchy inversion this prevents. Recurring chart / figure labels get `chart_annotation` likewise.->-> **Structural roles (page title / body / subtitle / annotation / footnote) resolve to one size each and hold it deck-wide** — that consistency is what reads as professional. Picking an intermediate in-band size is for special / feature elements (hero number, display title, one-off emphasis); a recurring one is declared as its own slot so it stays consistent too.+**Family selection**:-> **Unit boundary (HARD rule).** The system is **px-only**. `recommendations.json`, the Confirm UI, `result.json`, `design_spec.md`, `spec_lock.md`, and SVG **all carry unitless px** — there is no pt layer anywhere, and no pt→px conversion step. pt exists only as the size PowerPoint happens to show *after export* (`px × 0.75`, rounded to 1 decimal); it is never an input, a confirmation value, or a provenance field (no `body_size_pt` / `sizes_pt`). Never write `pt` / `px` / `em` units; every layer carries bare px numbers. Geometry — margins, gaps, card sizes — is px too. (The beautify profile reads a source deck's pt at intake but converts to px **before** any recommendation — see [`beautify-pptx.md`](../workflows/profiles/beautify-pptx.md); pt never re-enters the contract.)+- User or active template typography is authoritative. Otherwise present two coherent choices: one concord (safe) and one contrast (more tension). Do not pair title/body families that are merely near-duplicates.+- Exported faces must resolve to fonts available in PowerPoint. Safe anchors are CJK `Microsoft YaHei` / `SimHei` / `SimSun` / `FangSong` / `KaiTi`; Latin sans `Arial` / `Calibri` / `Segoe UI`; Latin serif `Times New Roman` / `Georgia` / `Cambria`; mono `Consolas`; display `Impact` / `Arial Black`.+- Keep each stack to four families or fewer. A non-installed brand or web face is legal only when the Design Spec explicitly records the install / embed requirement and a safe substitute.+- Avoid splitting roles across near-equivalents such as YaHei↔PingFang, SimSun↔Songti, Arial↔Helvetica↔Segoe UI, or Times New Roman↔Times. A cross-platform counterpart may remain inside one fallback stack.+- Choose by the locked style: serif for editorial / data-journalism, display weight for brutalist / poster directions, KaiTi or FangSong for ink character, mono accents for dark-tech / blueprint, and restrained sans for swiss-minimal / soft-rounded.-**Baseline — one fixed initial value per reading mode, not a range.** Reading mode is confirmed in Stage 2 (compatibility key `delivery_purpose`). Its user-facing definition is information carriage (§6.1), not font size. Once selected, the browser uses it as the initial body-size driver because the same canvas reads differently when read close vs. projected. This deterministic local dependency does not regenerate Stage 2. Here it seeds one baseline:+**Size lock — px only**: Every authoring layer carries bare px numbers. PowerPoint's displayed pt is an export result (`px × 0.75`), never an input or confirmation value.-| Reading mode (PPT 16:9) | Body (px) | Reads as |+| Reading mode on PPT | Initial body | Information posture ||---|---:|---|-| `text` · read-close (report, data-dense brief, leave-behind file) | 20px | screen / handout reading at arm's length |-| `balanced` · business (presented **and** read; roadshow, review) — **default** | 24px | mixed projection + reading |-| `presentation` (projected, sparse; keynote, launch, classroom) | 32px | room projection, glance from the back |+| `text` | 20 | read-close / dense |+| `balanced` | 24 | mixed reading + presentation |+| `presentation` | 32 | projected / sparse |-Absent a user override, the initial body baseline is **purely a function of reading mode**—density and visual style do **not** nudge it within a range. Body size is the reading-distance proxy; density is orthogonal and shows in **how much text per page, page count, and `page_rhythm`** (§6.1), the *other* roles, and decoration—never in growing or shrinking the body baseline. One mode → one default body size. The browser derives unpinned role sizes from it locally; editing body or a role pins that visible value, and later reading-mode changes preserve the pin.+Other canvases use the body baseline in [`canvas-formats.md`](canvas-formats.md). The confirmed visible values always win: take Confirm UI `body_size` / `sizes` verbatim; a manually edited role remains pinned, and changing canvas does not secretly rescale it.-| Canvas | Height | Body baseline | Unit |-|---|---|---|---|-| PPT 16:9 / 4:3 | 720 / 768 | 20 / 24 / 32 (by reading mode) | **px** |-| Xiaohongshu | 1242×1660 | 40–55 | px |-| WeChat / IG 1:1 | 1080×1080 | 27–36 | px |-| Story / Portrait | 1080×1920 | 48–64 | px |-| A4 | 1240×1754 | 44–58 | px |+| Recurring role | Ratio to body |+|---|---:|+| Cover title / single-focus hero | 2.5–5× |+| Chapter title | 2–2.5× |+| Page title / KPI hero | 1.5–2× |+| Subtitle | 1.2–1.5× |+| Lead / subheading | 1.1–1.4× |+| Body | 1× |+| Annotation | 0.7–0.85× |+| Footnote / page number | 0.5–0.65× |-> **Every canvas authors px directly.** PPT and social / print alike—the body baseline is a px number (PPT by reading mode above; social / print by the per-canvas value). No pt confirmation, no conversion step on any canvas.+Scan §IX before locking. Declare every recurring role, including `lead`, `footnote`, and chart annotations when used; a lead is always at least body size. One role has one deck-wide size. Snap derived values to clean even px (for body 24, a sound set is title 42, subtitle 32, lead 30, annotation 18, footnote 16). Feature elements may exceed the normal bands only through an explicit named slot.+#### Formula Planning Trigger-> **Confirmed values win — never recompute over them.** The user's confirmed sizes are authoritative. **Confirm UI path**: take `result.json` `typography.body_size` / `sizes` (already px) **verbatim**. Inside Stage 2, changing reading mode updates the body and unpinned roles locally; manually edited sizes stay pinned. Changing canvas deliberately does not rescale sizes. The visible state is therefore the final state—never perform a hidden post-confirm repair. **Chat-fallback path** (no `result.json`): take the px body baseline for the confirmed canvas + reading mode directly from the table above (no conversion).+Formula policy and formula-asset planning are conditional. If the source contains formula-worthy expressions, or the user explicitly requests formula handling, read [`strategist-image.md`](./strategist-image.md) §3 before confirming the production policy or writing formula rows. Load it even when `image_usage` is `none`; otherwise omit formula planning from the core path.-| Level | Ratio to body | 32px baseline (`presentation`) | 24px baseline (`balanced`) |-|-------|---------------|---------------|---------------|-| Cover title (hero headline) | 2.5-5x | 80-160px | 60-120px |-| Chapter / section opener | 2-2.5x | 64-80px | 48-60px |-| Page title | 1.5-2x | 48-64px | 36-48px |-| Hero number (consulting KPIs) | 1.5-2x | 48-64px | 36-48px |-| Subtitle | 1.2-1.5x | 38-48px | 29-36px |-| Lead-in / intro | 1.1-1.4x | 35-45px | 26-34px |-| Subheading | 1.1-1.3x | 35-42px | 26-31px |-| **Body** | **1x** | **32px** | **24px** |-| Annotation / caption | 0.7-0.85x | 22-27px | 17-20px |-| Page number / footnote | 0.5-0.65x | 16-21px | 12-16px |+### h. Image Source Recommendation-> Two baseline columns are illustrative only — for any other `body` px value (20 / 24 / 32 / ...), multiply the row's ratio. Structural roles (page title / body / subtitle / annotation / footnote) take their locked slot value and stay there on every page — not a per-page pick. In-band freedom without pre-declaring is for special / feature elements (hero number, display title, one-off emphasis); a recurring special size should be declared as its own slot. The subtitle / lead / subheading bands overlap on purpose — pick by role, not size, then hold each at one size deck-wide. Values outside **every** band require lock extension first.+| Source id | Approach | Use when |+|---|---|---|+| `none` | No images | Data reports or process documentation whose visual burden is fully served by charts / native SVG |+| `provided` | User-provided assets | Existing images carry factual, brand, product, or narrative authority |+| `ai` | AI-generated | Custom illustrations, backgrounds, metaphors, or a coherent spot family are needed |+| `web` | Web-sourced | Real-world editorial or stock-style reference imagery is needed |+| `placeholder` | Deferred | The image is required but will be supplied later |-> **Round recommended sizes to clean even px — don't ship ratio leftovers.** The ratios are a guide; lock each role at a **clean even px**, not the raw product. For `body` 24px that means **title 42 · subtitle 32 · lead 30 · annotation 18 · footnote 16** — never `32.4` / `18.7` / odd tails, which read as unprofessional. Snap the ratio output to the nearest even px (…14, 16, 18, 20, 24, 28, 32, 36, 42, 48…), then lock that. (The Confirm UI already snaps its per-role suggestions this way; match it on the chat-fallback path.)+**Current inventory**: If `images/` is non-empty, run `python3 scripts/analyze_images.py <project_path>/images` and read `analysis/image_analysis.csv` before recommending a source. Re-run after that folder changes.-> **px is literal — write the locked number verbatim (Mandatory).** `result.json` / `design_spec.md` / `spec_lock.md` / SVG all carry px as-is; there is no conversion anywhere. The size you confirm is the size you write. The Executor's `font-size` MUST be the **exact px from `spec_lock.typography`** — if `body` is `24`, write `24`; never a "rounder" or PowerPoint-familiar number (`20` / `18` / `36`). Writing a remembered pt-style value as px is the silent drift that renders a whole deck the wrong size (e.g. a `24`px body emitted as `20` ships ~17% small); the checker's spec-lock drift guard backstops it, but author it right. Per role: honor any size the user pinned as that slot's locked value; derive the rest from the ramp and snap to clean even px. (At export the px is turned back into pt by `× 0.75`, rounded to 1 decimal — that is the only place pt ever appears, and it is automatic.)+**Recommendation output**: Write `recommend.image_usage` as one source id or an array for mixed sources. Put page roles, authoritative assets, preferred/avoided imagery, and placeholder tolerance in `image_notes.value`. `none` is exclusive. Human-scale topics such as family life, education, wellness, or children lean `ai` when no supplied asset carries the story; regulated investor decks, B2B finance reports, and data-only dashboards remain eligible for `none` by judgment.-> **Hero in single-focus / breathing pages**: when one element *is* the entire page — a large number, a headline, a key phrase — it is the visual subject, not body content. Such heroes may borrow the cover-title band (2.5–5×); for greater emphasis, declare a hero slot in `spec_lock.md` (e.g., `hero_number` / `hero_headline`) — checker exempts declared slots with no fixed upper limit. The row above "Hero number (consulting KPIs) 1.5–2×" applies only to numeric KPIs in dashboard/data layouts, not to full-page focal elements.+**Confirmed value wins**: Accept the confirmed legacy string or multi-select array. Map `ai→ai`, `web→web`, `provided→user`, and `placeholder→placeholder` into §VIII `Acquire Via`. Until confirmation, a coordinated direction that proposes AI may use the visual style's paired rendering; generated images inherit the deck colors and never introduce a second image-palette choice.-#### Formula Rendering Policy+**Conditional module — two-stage trigger**:-Formula rendering is part of Typography confirmation. Recommend one policy and let the user confirm or override it inside item g.+1. First derive the proposed `recommend.image_usage` in core. If it contains any non-`none` source—especially `ai`—read [`strategist-image.md`](./strategist-image.md) **before authoring the Stage-2 design directions** so rendering and other image-dependent candidate details are real, not backfilled after confirmation. An explicit non-`none` image constraint or the formula trigger from §g activates the module at the same point.+2. After confirmation, the confirmed value is the production boundary. A confirmed non-`none` set continues into resource planning; confirmed `none` with no formula trigger skips all downstream image rows even if the proposed recommendation had loaded the module.-| Policy | Behavior | Use |-|---|---|---|-| `mixed` (default) | Render complex formula-worthy expressions to PNG; keep simple inline math as editable text / Unicode | Most academic, engineering, educational, and technical decks |-| `render-all` | Render every formula-worthy expression to PNG | Formula-heavy teaching / research decks where visual consistency matters more than editability |-| `text-only` | Do not render formulas; keep expressions as editable text / Unicode | Business decks, light technical briefs, or user preference for editability |+The module owns formula policy, AI rendering alternatives, acquisition paths, resource rows, prompt depth, page roles, and placement intent.-**Hard rule**: `$...$` / `$$...$$` in source material are input signals only. Do not scan output files for dollar-delimited formulas. After confirmation, Strategist decides which source expressions become formula assets and writes them explicitly to `images/formula_manifest.json`.+### Visualization Candidate Recall (Non-blocking — Strategist recommends, no user confirmation needed)-**Formula-worthy expressions**:+Review planned pages through two lenses:-| Render as PNG | Keep as text |+| Lens | Content shapes ||---|---|-| Fractions, radicals, integrals, sums, limits, matrices, multiline derivations, complex super/subscripts | `O(n log n)`, `x = 3`, single Greek letters, short inline variables, simple percentages / KPIs |+| Numeric / data | comparisons, trends, proportions, KPIs, financials, rankings, distributions, funnels |+| Structural information | rosters, agendas, principles, phases, journeys, capability maps, OKR cascades, roadmaps, strategic frameworks |-**Forbidden — invented math**: formula assets must faithfully structure source content. Do not create a new equation just to make a slide look more academic.--**Manifest step**: After the Strategist confirmation stage and before writing `design_spec.md`, if policy is `mixed` or `render-all` and formulas are selected:+**Per-page recall**: For every page whose information structure may benefit from a visualization, restate the content shape as 3–8 concise English semantic tags. Translate source-language and industry terms into structure before recall. Run:```bash-mkdir -p <project_path>/images-python3 skills/ppt-master/scripts/latex_render.py <project_path>-```--Write the manifest first at `<project_path>/images/formula_manifest.json`. Use this shape:--```json-{- "providers": ["codecogs", "quicklatex", "mathpad", "wikimedia"],- "items": [- {- "id": "formula_001",- "latex": "E = mc^2",- "display": "block",- "color": "#1D1D1F",- "background": "#FFFFFF",- "transparent": true,- "dpi": 400,- "filename": "formula_001.png"- }- ]-}-```--The script renders PNGs into `images/`, trying `codecogs`, `quicklatex`, `mathpad`, then `wikimedia` unless the manifest overrides `providers`. `codecogs`, `quicklatex`, and `mathpad` preserve requested formula color; `wikimedia` is an availability fallback and may require visual checking on dark themes. Formula PNGs are transparent by default: use `background` as the temporary render matte and local background-removal reference. Set `transparent: false` only when the final formula must keep an opaque background. It writes `pixel_width`, `pixel_height`, `ratio`, `file`, `provider`, and `status` back into the manifest. Run `analyze_images.py <project_path>/images` after formula rendering so the formula PNGs are included in the same inventory pass as user images.--### h. Image Usage Confirmation--| Option | Approach | Suitable Scenarios |-|--------|----------|-------------------|-| **A** | No images | Data reports, process documentation |-| **B** | User-provided | Has existing image assets |-| **C** | AI-generated | Custom illustrations, backgrounds needed |-| **D** | Web-sourced | Real-world reference imagery, editorial support, stock-style needs (no API key required for default providers) |-| **E** | Placeholders | Images to be added later |--> 🚧 **GATE — know your resources before recommending.** `images/` is a live working folder (source-extracted pictures, user drops, later replacements), so its facts are **re-derived on use, never trusted from a stale store**. Before recommending image usage, if `images/` is non-empty, regenerate the inventory from whatever is currently in it, then read it back:->-> ```bash-> python3 scripts/analyze_images.py <project_path>/images-> ```->-> Read `<project_path>/analysis/image_analysis.csv` (size / ratio / category of every in-hand picture). The A–E choice is still your judgment, but it MUST be made with the current inventory in full view — never in ignorance of what is already on hand. `image_analysis.csv` is a regenerated view of the live folder, not a durable fact: re-run this whenever `images/` changes.--> **Recommendation shape.** In `recommendations.json`, write `recommend.image_usage` as source ids, not prose. Use a single id for a single source (`"ai"`) and an array for mixed sources (`["ai", "provided"]`, `["web", "placeholder"]`). Put the strategy explanation in top-level `image_notes.value`: page roles, which supplied assets are authoritative, where AI may fill gaps, what kind of imagery to prefer/avoid, and whether placeholders are acceptable. `none` is exclusive and must not be combined with other ids.--> **Default — human-scale topics lean illustrated (may override when factual assets dominate)**: When the source is about personal finance, family life, daily routines, education, wellness, healing, or children, and there are no supplied assets that already carry the story, recommend `image_usage: "ai"` instead of `none`. Use `image_notes.value` to name a warm illustration motif (for example a home ledger, school-day routine, care scene, or life-planning metaphor). Do not apply this default to regulated investor decks, B2B finance reports, or data-only dashboards; those stay eligible for `none` / `web` / `provided` by judgment.--> **Confirmed value wins.** The `image_usage` in `result.json` (or the chat reply) **overrides the recommendation here**. It may be a legacy single string or a Confirm UI multi-select array. Map every selected value to §VIII `Acquire Via` (`ai`→`ai`, `web`→`web`, `provided`→**`user`**, `placeholder`→`placeholder`, `none`→option A, no image rows). When it does not include `ai` (and no legacy prose plan includes AI), skip h.5 entirely and write no `ai` rows. If `image_notes` is present, honor it as the user's image intent while assigning per-page rows. See [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4 for the full mapping.--> **Illustration roles at a glance (Reference).** Within the `image_usage` source boundary, illustrations can play several roles — pick by what the page needs; the **deck illustration motif** rule below threads them into one system. Mechanics live in the linked files.->-> | Role | When | Mechanism | Source |-> |---|---|---|---|-> | Body spot | scattered decorative accent (the icon-counterpart) | `page_role: local`, sheet→slice `#63` ([image-generator §4.3](./image-generator.md)) | `slice` (from an `ai` sheet) / `provided` / `web` |-> | Hero anchor | cover or a single big statement | `page_role: hero_page` + §4.1 Primitive A or D | per `image_usage` |-> | Section divider | chapter identity, often recurring | `page_role: hero_page` + `#75` divider layout | same motif family |-> | Atmospheric background | mood wash behind editable SVG text | `page_role: hero_page` + §4.1 Primitive D | per `image_usage` |-> | Motif through-line | one family across the roles above, deck-wide (a designed system) | combination of the above | `ai`: generate one family; `provided` / `web`: only if the assets already form one family |--> **Spot illustrations follow the locked `visual_style`'s propensity — a default lean, not a confirmation field.** The user confirms image *source* via `image_usage`; illustrations are not a separate confirmation control, page-role map, or user-facing picker. Within that boundary, whether the deck leans into decorative spot illustrations is anchored by the locked `visual_style`'s **illustration propensity** (`core` / `supportive` / `sparse` — see that style's §6 and the [`visual-styles/_index.md`](./visual-styles/_index.md) `Illus.` column):->-> - **`core`** (e.g. sketch-notes, memphis, paper-cut) — illustration is intrinsic; default to planning a coherent spot family.-> - **`supportive`** — use where it genuinely lifts rhythm or section identity, kept restrained.-> - **`sparse`** (e.g. swiss-minimal, photo-editorial, data-journalism) — the style's lead visual competes; default to none.->-> **Precedence (high → low): `image_usage: none` → explicit user intent → visual_style propensity → none.** `image_usage: none` always wins and produces no illustration rows. Otherwise an **explicit user request** to use or skip illustrations (stated in chat — the canonical channel) overrides the propensity default *in either direction*: use them even on a `sparse` style, skip them even on a `core` style. Propensity is only the default when the user gives no steer. Record the decision and its reason in `image_notes` / `design_spec`.->-> **Propensity sets *whether* and the lean — never the *source* or the *how*.** Source still comes from `image_usage`: a `core` style does **not** silently generate AI spots when the user did not select AI — with no AI source it draws only on a confirmed source (`provided` / `web`) or goes without. How heavily and where stays Strategist judgment, and the locked style still governs deployment (a `sparse` style used on explicit request stays very few, very light). Do not force a quota, and do not phrase it as "few pages." Suitable means the spot improves rhythm, warmth, continuity, or section identity without carrying facts or competing with charts, photos, tables, screenshots, or key text.--> **Deck illustration motif — deploy one family as a through-line, not isolated spots.** When the deck leans into illustration (a `core` propensity, or an explicit user request for a designed, illustrated feel), the strongest use is **one coherent motif family**—one subject world sharing the deck-wide rendering and locked deck colors—deployed across scales: a cover anchor (`page_role: hero_page`), recurring section dividers for chapter identity ([image-layout-patterns](./image-layout-patterns.md) `#75`), and small body spots (`local` sheet→slice, `#63`). **Source still bounds it**: the AI motif is planned only when confirmed `image_usage` includes `ai`; `provided` / `web` can carry a through-line only when those assets already form one family. Use it when it serves the deck, never as a quota. Cover / divider anchors are separate `hero_page` generations sharing the spot sheet's rendering, deck colors, and subject world—not oversized cells in the sheet.--**AI generation path — one sheet, then slice.** When spot illustrations are AI-generated and the deck needs ≥3 same-family elements, write one `ai` Illustration Sheet row plus one `slice` row per used element. Step 5 generates the sheet, then slices transparent PNG elements for placement. This is just AI-generated imagery batched for consistency and efficiency; do not generate one image per spot.--**Plan illustration shape from placement, not from a square default.** Before writing the sheet row, group the planned spot illustrations by intended placement shape: compact object, tall side accent, wide banner/vignette, or another explicit shape family. Do not ask for generic "small illustrations" with no shape intent. If one deck needs incompatible shapes, write separate sheet intents instead of forcing every element into one implied square set; Image_Generator owns the exact sheet ratio and grid.--**When recommending C** — surface its three implementation modes so the user knows "no API key" is a supported state:--| Mode | Trigger | Mechanism |-|---|---|---|-| **Path A** | `IMAGE_BACKEND` configured (default) | `image_gen.py` runs in Step 5 |-| **Path B** | `IMAGE_BACKEND` not configured AND host has a native image tool (Codex / Antigravity / Claude Code / similar) — auto-selected, no user prompting needed | Host-native generation |-| **Offline Manual** | `IMAGE_BACKEND` not configured AND host has no native image tool | Prompts written to `images/image_prompts.json`; user generates externally and places files in `project/images/` |--Selection is automatic in Step 5 (A → B → Manual). Detailed contract: [`image-generator.md`](./image-generator.md) §7 Path Selection (Deterministic).--Selections may be mixed at the row level — e.g. a deck can use C for hero illustrations while sourcing D for supporting team photos.--> **Spot illustrations → one sheet, not N rows.** When the deck wants ≥3 small same-family spot illustrations as decorative accessories across pages (the illustration counterpart to icons), do not write one `ai` row per element. Write **one `ai` sheet row** (the sheet prompt intent — generated but never placed, kept out of `spec_lock.md images`) **plus one `slice` element row per used element** (each placed, each listed in `spec_lock.md images` so the Executor may reference it). The sheet row's `Reference` must name the intended cell shape family and placement purpose, such as "portrait side-accent spot set" or "landscape footer-vignette spot set"; the slice rows reference the parent sheet + cell. Step 5 / Image_Generator chooses the exact sheet ratio, grid, and slice command. Plan these sparingly, only where decoration genuinely lifts the page. Full resource contract + slice command: [`image-generator.md`](./image-generator.md) §4.3.--#### h.5 AI Image Strategy — lock rendering; inherit deck colors (only when C is selected)--When the deck includes any `ai` rows, Strategist locks one **deck-wide rendering** here. Every AI image shares it. Color is not a second image-specific decision: the Image_Generator reads the already-confirmed `spec_lock.md colors` roles directly and derives prompt proportions from them.--🚧 **GATE — before recommending values**: `read_file references/image-renderings/_index.md`. It contains the rendering catalog and auto-selection table.--#### Three-candidate presentation (default path)--**Hard rule**: Unless the user has already named a specific rendering (chat or template), include **≥3 distinct renderings** across the Stage-2 coordinated design directions. Never auto-lock one silently.--**Per-candidate image fragment** (inside a complete Stage-2 direction):--```-[Plan A] <temperament label> — <rendering>- Visual: <shape / line / material / light, 1-2 phrases>- Mood: <2-3 traits>; like <real-world analogy: company / publication / event>+python3 skills/ppt-master/scripts/chart_recall.py recall \+ --page P03 \+ --tag "time series" \+ --tag "three metrics" \+ --tag "direction over time" \+ --limit 6```-After the candidates, append one line:+The command reads the live `charts_index.json` and returns positive-scoring candidates up to the requested 3–8 limit, plus an explicit `no-template-match` option. It never pads the shortlist with zero-score keys; zero positive matches means use the fallback. Do not load the full catalog into the prompt.-```-> Rendering references: see references/ai-image-comparison/rendering/ for matching PNGs by name. Image colors inherit this direction's deck color scheme.-```--**Confirm UI packaging**: put one `image_strategy` object inside each Stage-2 `design_directions` candidate when AI is selected. It carries `rendering`, localized `visual`, and localized `mood`; it carries no `palette` or `color`. The page derives the three rendering cards from those directions and appends one built-in Custom card.--**Confirmed Custom card prose**: when `result.json.image_strategy.custom` is non-empty, treat it as a confirmed deck-wide image-direction constraint. Write it into `design_spec.md §III` image direction notes and carry it into every `Acquire Via: ai` prompt brief. It augments the locked rendering id with subject, composition, texture, avoidance, or other prompt-specific constraints.--**Hard rules for candidate construction**:+**Selection**:-| Rule | Behavior |-|---|---|-| Fit the confirmed deck colors | Reject a rendering whose natural color tendency would fight the direction's locked HEX roles. Never modify the deck HEX to rescue a rendering. |-| Span a personality spectrum | Typically: one conservative-default (industry norm), one shifted-tone (same fit, 1-2 ticks different), one bold-contrast (more expressive, may challenge default). No near-duplicates. |-| `Mood` line MUST include a real-world analogy | Company / publication / event the user can picture. Adjective stacks alone are forbidden. |-| Adapt labels to chat language | Schema is English by default. Chinese chat → render as 「方案 A / 视觉 / 色彩 / 情绪」. Structure stays the same; only the labels translate. |-| Skip presentation when user has specified | A user-named rendering (chat / brand / template), or a Confirm UI pick in `result.json.image_strategy`, wins directly; do not re-pick. |-| `custom` is a tail-case, not a default | When no preset fits, at most one candidate may set `rendering: custom`; its `Visual` prose follows [`image-renderings/_index.md`](./image-renderings/_index.md) §1.5. Never use `custom` as a slot filler. |--**Forbidden — padding with conflicts**: if the locked visual / color constraints cannot support three credible renderings, present the smaller set and state why. Never fill remaining slots with known-conflicting options.--**Worked example** (deck colors are already part of each complete design direction):+1. Inspect every returned `Pick for` / `Skip if` summary against the page; prefer the most specific valid structure.+2. Keep one primary visualization per page. Adapt its composition, density, colors, and decoration to the page; do not mimic blindly.+3. If every candidate conflicts, choose `no-template-match`: data-driven content falls back to a table, conceptual/illustrative content to an AI image when the confirmed image source permits it, and structural content to a custom layout.+4. Validate all selected keys before writing the lock:+```bash+python3 skills/ppt-master/scripts/chart_recall.py validate <key> [<key> ...]```-[Plan A] Restrained Professional — vector-illustration- Visual: flat vector, solid color blocks, no gradients or shadows- Mood: steady, trustworthy, restrained gravitas; like a McKinsey consulting report--[Plan B] Editorial Depth — editorial- Visual: magazine layout, 8% paper texture, column-based partitioning- Mood: refined, considered, paced; like an Economist feature spread-[Plan C] Future Energy — 3d-isometric- Visual: isometric 3D, soft shading, 8% glow halos around bright elements- Mood: forward, energetic, futuristic; like an Apple or Stripe product keynote+A failed validation must be corrected with a recalled key. `no-template-match` is not a key and never appears in `page_charts`.-> Every option uses the deck color roles locked in its parent design direction.-```--**Worked example — `custom` rendering** (tail-case):+**Section VII audit**: Use one combined table. Copy the selected candidate's returned `summary` verbatim into `Summary-quote`; record its returned path and page-specific usage. List real returned runners-up with page-specific rejection reasons. If no candidate fits, record `no-template-match`, the fallback, and why.```-[Plan A] 文人雅致 — custom- Visual: dry-brush burnt-ink, five tonal gradations, 宣纸 paper-grain, deliberate negative space; 朱泥 seal as single red mark- Mood: literati restraint; like 苏州博物馆 pacing-```--The `Visual` line feeds `spec_lock.md image_rendering_behavior` when rendering is `custom`; color roles remain ordinary deck-color rows.--After the user picks a candidate (or supplies a custom variant), proceed to "Recording the lock" below.--#### Prompt depth for §VIII rows--**Hard rule**: When §VIII contains paper-figure or subject-domain rows (scientific subjects, specialized fields, regulated content), each row's `generation description` follows [`image-generator.md`](./image-generator.md) §4.2 Prompt depth — expand to the depth the subject demands; 500-1000+ words is normal.--**Forbidden — generic shortening**: never drop a paper-figure row's prompt to a 50-word generic illustration brief.-------#### Catalog reference (for candidate construction)--The tables below are source data Strategist reads when constructing the three candidates above. They are no longer the final output by themselves.--**Rendering recommendation** (soft — user may override with any other rendering from the catalog):--| `d. Style` signal | Recommended rendering | Alternates |-|---|---|---|-| Strategic / MBB / board | `editorial` or `vector-illustration` | `blueprint`, `minimalist-swiss` |-| Corporate report / analysis / 学术答辩 | `vector-illustration` | `flat`, `editorial` |-| High-end consulting / luxury / 高端 / design-firm | `minimalist-swiss` | `editorial`, `vector-illustration` |-| Tech / SaaS / AI / 架构 | `3d-isometric`, `blueprint`, `digital-dashboard` | `flat` |-| Modern SaaS / fintech / health-tech / premium app | `glassmorphism` | `digital-dashboard`, `flat` |-| Product launch / brand / marketing | `flat`, `3d-isometric`, `corporate-photo` | `vector-illustration` |-| Education / training / 教学 / 培训 | `sketch-notes` | `vector-illustration`, `paper-cut` |-| Children / storybook / 儿童 / 治愈 | `fantasy-animation` | `paper-cut`, `watercolor`, `sketch-notes` |-| Cultural / folk / festival / 文化 / 节日 | `paper-cut` | `vintage-poster`, `screen-print` |-| Methodology / Before-After / 方法论 / manifesto | `ink-notes` | `editorial` |-| Government / formal / 政务 | `editorial` or `corporate-photo` | `vector-illustration` |-| Finance / journalism / 财经 | `editorial`, `digital-dashboard` | `vector-illustration` |-| Personal story / 个人成长 / lifestyle | `watercolor`, `warm-scene` | `corporate-photo`, `paper-cut` |-| Cultural / media / opinion / cinematic | `screen-print`, `vintage-poster` | `editorial`, `warm-scene` |-| Brand heritage / hospitality / 老字号 / 周年 | `vintage-poster` | `screen-print`, `editorial` |-| Gaming / retro / 复古 / 像素 | `pixel-art` | `vintage-poster` |-| Environment / wellness / 环保 | `nature` | `watercolor`, `paper-cut` |-| Classroom / blackboard / 课堂 | `chalkboard` | `sketch-notes` |-| Team / company / product photo | `corporate-photo` | — |--**d-e-f-g linkage sanity check** (do this after picking rendering):--| Linkage | What to verify |-|---|---|-| **d. Style ↔ rendering** | Rendering family should match the Style descriptor's temperament (corporate ≠ sketch-notes; tech ≠ watercolor). Already enforced by the recommendation table above. |-| **e. Color HEX ↔ rendering** | Deck HEX is truth. If a rendering's natural color tendency fights those roles, change the rendering—not the deck colors. Image_Generator derives proportions from the locked deck roles. |-| **f. Icon library ↔ rendering** | `tabler-outline` pairs well with all renderings (most versatile). `chunk-filled` / `tabler-filled` pair better with `vector-illustration` / `flat` / `editorial`. `phosphor-duotone` pairs with `flat` / `digital-dashboard`. Mismatch is not fatal but worth flagging. |-| **g. Typography ↔ rendering** | Serif title → pairs well with `editorial`, `corporate-photo`, `screen-print`. Hand-lettered direction → already implied by `sketch-notes` / `ink-notes` (the rendering carries the lettering, no separate font requirement). Display font → `vivid-launch` / `screen-print`. Mismatch is rarely fatal; note in conversation if it feels off. |--**Recording the lock** — after picking, write to:--- `design_spec.md §III Visual Theme` — add lines under the color table:- ```- - **Image Rendering**: vector-illustration- ```-- `spec_lock.md colors` section — add rows at the bottom:- ```- - image_rendering: vector-illustration- ```--**Hard rule — `custom` recording**: when the picked candidate has `rendering: custom`, also write `image_rendering_behavior`. Expand the candidate's `Visual` line to cover [`image-renderings/_index.md`](./image-renderings/_index.md) §1.5. Both `design_spec.md` and `spec_lock.md` carry the behavior line:+| Page | Template | Path | Summary-quote (verbatim) | Usage |+|---|---|---|---|---|+| P03 | line_chart | templates/charts/line_chart.svg | "<returned summary>" | <intent> |+Runners-up considered:+- <returned_key> | rejected for P03: <page-specific reason>```-- image_rendering: custom-- image_rendering_behavior: "Dry-brush burnt-ink with five tonal gradations, 宣纸 paper-grain at 12% opacity, deliberate negative space; 朱泥 seal as a single red mark; no Western outlines, no gradients."-```--Image_Generator reads this rendering lock deck-wide and reads the ordinary color-role rows from the same `spec_lock.md colors` section. A legacy `image_palette` row may still exist in an old lock, but the current flow ignores it; it never overrides the deck HEX roles and is never authored by the new flow.--#### hero_page suggestion (same confirmation turn)--After the user picks a candidate, scan the outline and surface any pages where the image makes more sense as the page's main voice than as a local block. Present them as a short list and let the user confirm, edit, or skip. Result is recorded as `page_role: hero_page` on the matching `ai` rows. Density is judgment-based — no fixed quota.--**Per hero_page title**: lock where it lives — `embedded` (fused into the image: neon, carved, smoke, 3D-lit lettering) or `none` (editable SVG title over an atmospheric backdrop, Primitive D). Default `none`; flip to `embedded` only when the words must be *part of the visual*, not merely a display font. Per page — may bake only the keyword while subtitle / date / chrome stay SVG. Surface it with the hero_page list for the same confirm / edit / skip.--**When selection includes B**, you must run `python3 scripts/analyze_images.py <project_path>/images` before outputting the spec, and integrate scan results into the image resource list.--**When B / C / D / E is selected**, add an image resource list to the spec:--| Column | Description |-|--------|-------------|-| Filename | e.g., `cover_bg.png` |-| Dimensions | e.g., `1280x720` |-| Ratio | e.g., `1.78` |-| Layout suggestion | e.g., `Wide landscape (suitable for full-screen/illustration)` |-| **Layout pattern** | **MANDATORY** — one or more `#<id> <name>` joined by ` + ` from `image-layout-patterns.md`. Combine a Primary id with optional Modifier ids when the page needs it (e.g. `#48 side-by-side comparison + #21 rounded rectangle crop + #29 two-stop scrim`). A single Primary is fine when the page calls for it. See the GATE earlier in this section. Empty cells or invented ids are invalid. |-| Purpose | e.g., `Cover background` |-| Type | Free-form category tag — `Background`, `Photography`, `Illustration`, `Diagram`, `Portrait`, `Latex Formula`, etc. Required for formula rows (`Latex Formula`). |-| **Acquire Via** | `ai` / `web` / `user` / `formula` / `placeholder` / `slice` — only `ai` and `web` drive Step 5 dispatch; `slice` is derived after its `ai` sheet generates (§4.3) |-| Status | Initial status must be `Pending`, `Existing`, `Rendered`, `Needs-Manual`, or `Placeholder`; `Needs-Manual` applies only after an attempted acquisition/render fallback; see [`svg-image-embedding.md`](svg-image-embedding.md) for the full status enum |-| **Reference** | Free-form **intent description** (NOT a search query); feeds Image_Generator (ai) or Image_Searcher (web) |-| `text_policy` (optional, `ai` rows only) | `none` (no text in image) or `embedded` (text is part of the artwork). Leave blank when Image_Generator should decide per row. Long body / data / lists stay in SVG. |-| `page_role` (optional, `ai` rows only) | `local` (image is a region block on an SVG page) or `hero_page` (image is the page's main voice). Leave blank for the `local` default; write `hero_page` explicitly. |--**No-crop flag (exception only)**: most images are croppable — Executor defaults to `preserveAspectRatio="xMidYMid slice"`. When an image must NOT lose pixels (data screenshots, charts, certificates, contracts, dense diagrams), append `no-crop` to its `spec_lock.md images` entry. Executor will then size the container to the native ratio and use `meet`. Don't tag the rest.--**Formula rows**: LaTeX PNGs are image rows with `Acquire Via: formula`, `Type: Latex Formula`, and `Status: Rendered` when the file exists or `Needs-Manual` after provider exhaustion. Always append `no-crop` in `spec_lock.md images`. They are not AI images and never go through Step 5; unresolved files are collected by the Step 7 image-readiness gate.--**Reference field**: Write visual intent, not provider mechanics.--| ✅ Intent description | ❌ Avoid |-|---|---|-| "Diverse engineering team collaborating around a laptop, modern office, natural light" | "team laptop office" |-| "Abstract atmospheric backdrop for academic-defense cover, calm center for text overlay, hint of campus skyline" | "use openverse, search 'office'" |-| "Sunlit forest path in autumn" | "team photo" |--**Per-row Reference grammar**:--| Acquire Via | Reference pattern |-|---|---|-| `ai` | **Subject + intent + composition** only. Do NOT repeat style words or HEX values—rendering is locked by h.5 and deck color roles by `design_spec §III` / `spec_lock.md colors`. Image_Generator injects them automatically. |-| `web` | Concrete subject/place/object first, then 1-3 quality descriptors |-| `formula` | Original LaTeX plus short placement intent, e.g. `formula_001: block energy-mass equation for P03` |--**Allowed web quality descriptors**:--| Descriptor | Use |-|---|---|-| `professional editorial photography` | Stock-style photography |-| `clean composition` | Covers, section dividers, image-text layouts |-| `natural light` | People, workplace, travel, lifestyle scenes |-| `high-resolution` | Large visual areas |--**Forbidden — web negative prompts**: `not tourist snapshot`, `no phone photo`, `avoid amateur style`.--| Mode | Good Reference |-|---|---|-| `web` | "Diverse team collaborating at a modern office desk, professional editorial photography, natural light, laptop visible" |-| `ai` | "Atmospheric backdrop suggesting digital innovation; calm central area reserved for slide title overlay; light geometric anchor at one edge" |-| `ai` | "Four-stage value chain from raw input to R&D output; icons should suggest tax-form → cost-reduction → equipment-upgrade → innovation; no text labels (SVG overlays them)" |--🚧 **GATE — before writing §VIII Image Resource List**: when image approach is B/C/D/E (anything other than A "no images"), this is a three-layer hard requirement, not a suggestion:--1. **Read** — `read_file references/image-layout-patterns.md` and read every catalog entry. The four `Image narrative intent` values below cover only broad categories.-2. **Produce** — every non-formula row in §VIII Image Resource List MUST fill the `Layout pattern` column with one or more `#<id> <name>` joined by ` + ` drawn verbatim from this file (Primary + optional Modifiers). Rows with empty cells, paraphrased names, or invented ids are invalid. Formula rows are the only exception; use `formula-inline` or `formula-block`.-3. **Image-as-canvas coverage** — for any deck with ≥4 image-bearing pages, at least one page MUST use a pattern from the catalog's **Image-as-Canvas + Native Overlay** family unless every image is a pure cover / chapter divider / atmosphere backdrop. This family is the most-skipped one and is usually the right answer for content-rich pages with photographs. If the deck legitimately has no opportunity for it, state the reason in §VIII directly under the table.--**Skip-detection signal for self-audit**: if you notice that every page's `Layout pattern` column resolves to #2/#3 (left-third or right-third), #5/#6 (top-bottom band), or generic side-by-side, you have not actually consulted the file — re-read and reconsider. The default left/right and top/bottom split bias is the failure mode this gate exists to break.--**Skip-detection signal — `text_policy` column**: if every `ai` row resolves to `none` and the deck contains any paper-figure / academic schematic / panel-comparison / data-axis page, you defaulted instead of judging per row. Consult [`image-generator.md`](image-generator.md) §5.3 positive-trigger table and re-decide each row. `none` for every row is correct only when no row matches a trigger; otherwise this is the same class of failure as the layout-pattern signal above.--**Image narrative intent** (decide *before* the ratio table — determines whether the image lives in a container at all):--| Intent | Form | When to use |-|--------|------|-------------|-| **Hero / full-bleed** | Image fills canvas/dominant zone; title floats over with gradient or opacity overlay | Covers, chapter dividers, `breathing` pages — image *is* the message |-| **Atmosphere / background** | Image as low-contrast backdrop (reduced opacity or dark overlay); text reads on top | Section backgrounds, mood-setting — image sets tone, text carries info |-| **Side-by-side** | Image and text as adjacent coequal blocks — ratio table below governs container sizing | Most content pages — image and text read together |-| **Accent / inline** | Small image beside related text, not a container; no ratio matching | Supporting visuals, spot illustrations |--> Intent follows narrative purpose, not image ratio. Don't default every image page to side-by-side.--**Side-by-side ratio alignment** (consult only when the chosen intent is *side-by-side*; detailed calculation rules in `references/image-layout-spec.md`):-| Image Ratio | Recommended Container Layout |-|-------------|-----------------------------|-| > 2.0 (ultra-wide) | Top-bottom split, top full-width |-| 1.5-2.0 (wide) | Top-bottom split |-| 1.2-1.5 (standard landscape) | Left-right split |-| 0.8-1.2 (square) | Left-right split |-| < 0.8 (portrait) | Left-right split, image on left |--Side-by-side only: container ratio must match image ratio. Hero / atmosphere / accent intents ignore ratio alignment.--> **Portrait canvases** (Xiaohongshu, Story): Layout rules differ — top-bottom is preferred for most ratios since left-right columns become too narrow. See "Portrait Canvas Override" in `references/image-layout-spec.md`.--> **Multi-image slides**: When multiple images appear on one page, use the grid formulas in the "Multi-Image Layout" section of `references/image-layout-spec.md`.--> **Pipeline handoff**: When C) AI generation is selected, Image_Generator consumes `Pending` rows and updates them to `Generated` or `Needs-Manual` before Executor proceeds. Status names are defined in [`svg-image-embedding.md`](svg-image-embedding.md).--### Template Match — Visualization + Structural Patterns (Non-blocking — Strategist recommends, no user confirmation needed)--The catalog covers **both data charts and structural information designs**. A "match" is not limited to numeric pages — any page whose content shape matches a `Pick for ...` clause is a candidate:--- **Data-type pages**: comparisons, trends, proportions, KPIs, financials, rankings, distributions, conversion funnels-- **Structural-type pages**: team rosters, agendas, principles & values, methodology phases, customer journey, capability maps, OKR cascades, roadmaps, strategic frameworks (SWOT / BCG / PEST / Porter's Five Forces / Value Chain — matched via `quadrant_text_bullets`, `quadrant_bubble_scatter`, `vertical_pillars`, `hub_inward_arrows`, `chevron_chain_with_tail` respectively)--The most common Strategist failure mode is missing the structural half — treating "chart" as "numeric chart only" and leaving team / agenda / principles / journey pages as text-only when a template would fit. Read the catalog with both lenses.--**Flag native-preset candidates on §VII pages.** For any page row already listed in §VII (including `no-template-match` rows), when its content also calls for a literal stock PowerPoint shape — a chevron, block arrow, standard flowchart node, callout, banner, or star (judged from the page plan, not from a template's name or drawing) — append a candidate note to that page's `Usage`, e.g. `…existing usage…; native-preset candidate: chevron; Executor applies executor-base §3.0`. This primes the Executor at plan-read time without deciding for it: the Executor still selects the exact preset, frame, and paint at draw time via [`executor-base.md`](./executor-base.md) §3.0, or keeps ordinary SVG when that section's exceptions apply. Pages with no §VII row rely on the Executor's §3.0 judgment at draw time.--> **Reading is mandatory; the catalog is a starting point, not a copy target.**-> - Fully read `templates/charts/charts_index.json` **before drafting the Strategist confirmation stage** — the read happens up front, not when you sit down to write Section VII. The file contains `meta` + `charts.<key>.summary` only; each `summary` is a selection rule (`"Pick for … Skip if …"`), not a description. There is **no category, quickLookup, or keyword index** — selection is done by semantically matching each page's content shape against all 76 summaries in one pass.-> - Not every page needs a chart. When a page's information structure matches a catalog entry, **use that template as a structural starting point** — keep the visualization type and core layout logic, then adapt composition, density, color, decoration, and accompanying elements to fit this deck's content and visual tone. Free adjustment is encouraged; what is forbidden is (a) generating without reading the catalog, and (b) blind verbatim mimicry that ignores the page's actual content weight.->-> **Workflow**:-> 1. Read all 76 summaries; for each page, identify the Pick clause that matches the page's content shape AND does not match any Skip clause.-> 2. Prefer specificity (`vertical_list` over generic `numbered_steps`).-> 3. One primary visualization per page; a supporting layout may accompany it.-> 4. List selections in Design Spec section VII; section IX only notes the visualization type name per page.->-> **Source vocabulary mismatch** — the catalog is in English. When source content uses Chinese / industry jargon ("中台", "架构图", "述职", "管道", "前后端"), translate the intent first, then match against summaries. The catalog deliberately keeps no keyword index — full-read forces semantic matching rather than lexical grep.->-> **Read-audit (mandatory, section VII format)** — single combined table; `summary-quote` column is the anti-fabrication audit, `path` + `usage` serve Executor lookup. Format defined in [`templates/design_spec_reference.md`](../templates/design_spec_reference.md) §VII:-> ```-> Catalog read: 76 templates->-> | Page | Template | Path | Summary-quote (verbatim) | Usage |-> | ---- | ------------- | --------------------------------- | ------------------------ | ----- |-> | P03 | column_chart | templates/charts/column_chart.svg | "<verbatim first sentence>" | <intent> |-> | P07 | line_chart | templates/charts/line_chart.svg | "<verbatim first sentence>" | <intent> |-> | P11 | pie_chart | templates/charts/pie_chart.svg | "<verbatim first sentence>" | <intent> |->-> Runners-up considered (3 entries minimum, drawn from real second-best matches):-> - <key_A> | rejected for P03: <reason citing this deck's specifics>-> - <key_B> | rejected for P07: <reason>-> - <key_C> | rejected for P11: <reason>-> ```-> The `summary-quote` must be copy-pasted from `charts_index.json` — paraphrasing or summarizing breaks the audit. Every template name listed (selected or rejected) must `grep` cleanly inside `charts_index.json` (so misspelled or invented keys fail). If fewer than 3 visualization pages exist, list what exists and note "fewer than 3 viz pages"; runners-up still required for each page that does exist.->-> **Fallback when no template fits**:-> 1. Re-read the full summary list with the page's intent re-stated in plain language — "non-obvious" matches often surface on the second pass (e.g. "causal chain" → `process_flow` or `sankey_chart`).-> 2. If still no fit: data-driven content → table layout; conceptual/illustrative → "AI-generated image" (Image_Generator handles); structural → "custom layout".-> 3. Mark the page `no-template-match` in section VII with the fallback chosen and why. Do NOT silently substitute a close-but-wrong chart.+**Flag native-preset candidates**: For any §VII row, including `no-template-match`, append a `Usage` note when the content calls for a literal stock PowerPoint chevron, block arrow, standard flowchart node, callout, banner, or star. Executor still decides the exact preset under its native-shape branch.### Speaker Notes Requirements (Default — no discussion needed)@@ -766,69 +326,34 @@ Read the relevant `_index.md` at confirmation `d` (Layer 1 / Layer 2) for its ca----## 3. Color Knowledge Base--### Consulting Brand Colors--| Brand | HEX |-|-------|-----|-| Deloitte Blue | `#0076A8` |-| McKinsey Blue | `#005587` |-| BCG Dark Blue | `#003F6C` |-| PwC Orange | `#D04A02` |-| EY Yellow | `#FFE600` |--### Versatile / General Colors--| Style | HEX |-|-------|-----|-| Tech Blue | `#2196F3` |-| Vibrant Orange | `#FF9800` |-| Growth Green | `#4CAF50` |-| Professional Purple | `#9C27B0` |-| Alert Red | `#F44336` |+## 3. Color Selection Reference-### Data Visualization Colors+Do not start from a universal palette. Precedence is user / brand values → active template inheritance → the industry anchors in `scripts/config.py` → a project-specific proposal that realizes the locked visual style. Keep body-text contrast at least 4.5:1 and normally use no more than four chromatic colors on one page.-- Positive trend (green): `#2E7D32` → `#4CAF50` → `#81C784`-- Warning trend (yellow): `#F57C00` → `#FFA726` → `#FFD54F`-- Negative trend (red): `#C62828` → `#EF5350` → `#E57373`+Lock the complete role set the style needs, including neutrals such as `surface`, `grid`, `scrim`, `overlay`, or `block-shade`; Executor must not invent a missing tone. For data semantics, use coherent positive / warning / negative ramps rather than unrelated accents.---## 4. Layout Pattern Library-> **Principle — proportion follows information weight, not preset ratios.** Combine patterns, break the grid for `breathing` pages, or propose new patterns. Defaulting every page to symmetric grid produces the "AI-generated" look.+**Proportion follows information weight, not preset ratios.** Choose or combine the smallest structure that expresses the relationship; break the grid for a genuine `breathing` page. Repeating symmetric card grids is a failure mode.-| Pattern | Suitable Scenarios | PPT 16:9 Reference Dimensions |-|--------|-------------------|-------------------------------|-| Single column centered | Covers, conclusions, key points | Content width 800-1000px, horizontally centered |-| Symmetric split (5:5) | Comparisons where two sides carry equal weight | Column ratio 1:1, gap 40-60px |-| Asymmetric split (3:7 / 2:8) | One side dominates — chart vs. takeaway, image vs. caption | Heavier side 840-1024px, lighter side 256-440px |-| Three-column | Parallel points, process steps | Column ratio 1:1:1, gap 30-40px |-| Four-quadrant / matrix | Two-axis classification, strategic quadrants | Quadrant 560x250px, gap 20-30px |-| Top-bottom split | Ultra-wide images + text, processes, timelines | Image full-width, text area >= 150px height |-| Z-pattern / waterfall | Storytelling, case studies — blocks alternate left/right | Guide eye in Z; 3-5 alternating blocks |-| Center-radiating | Core concept + surrounding nodes | Center element 200-300px, 4-6 satellite nodes |-| Full-bleed + floating text | `breathing` / feature pages | Image fills 1280x720, text floats over opacity overlay |-| Figure-text overlap | Hero moments — headline over/against image edge | Text partially overlaps image, not beside it |-| Negative-space-driven | Single element in 40-60% whitespace | One idea, weight through emptiness |+| Content relationship | Useful starting structure |+|---|---|+| One focal claim | centered single column, negative space, or full-bleed + floating text |+| Equal comparison | symmetric split or a true matrix |+| Dominant evidence + takeaway | asymmetric split, typically 3:7 or 2:8 |+| Parallel sequence | three-column, process line, or Z-pattern |+| Core + surrounding forces | center-radiating or hub-spoke |+| Wide visual + explanation | top-bottom split |-**PPT 16:9 (1280x720) key dimensions**: Safe area 1200x640 (40px margins); Title area 1200x100; Content area 1200x500; Footer area 1200x40.+On PPT 16:9, start from a 1200×640 safe area with 40px outer margins, then adapt to content. Template workspaces may supply different geometry; when active, [`strategist-template.md`](./strategist-template.md) owns precedence.---## 5. Template Flexibility Principle-Templates are starting points. The Strategist may adjust based on content and audience:--1. Font size ratios — reference values, adjustable-2. Color schemes — customize per brand/content-3. Layout patterns — combine, nest, or break (§4 lists 11 patterns as reference, not exhaustive)-4. 12-chapter framework — expand or reduce-5. Spacing / border radius — Executor adjusts per content density and `page_rhythm`-----+Free-design patterns are starting points, not quotas. Adjust composition, spacing, and role sizes to the confirmed reading mode, page rhythm, and content. When a template workspace is active, do not reinterpret its reuse contract here; load [`strategist-template.md`](./strategist-template.md).## 6. Workflow & Deliverables@@ -852,28 +377,16 @@ This is what makes the axis meaningful: a `presentation` deck and a `text` deck> Note: §IX is the only content copy the Executor re-reads after context compression — what you write there is what survives.-### 6.2 Outline Output Specification (Must include 10 sections)--| Chapter | Content Requirements |-|---------|---------------------|-| I. Project Information | Project name, canvas, page count, audience, communication intent, audience outcome, core message / ask, delivery context, artifact afterlife, reading mode, content strategy, style / template direction, date |-| II. Canvas Specification | Format, dimensions, viewBox, margins, content area |-| III. Visual Theme | Style description, light/dark theme, tone, color scheme (with HEX table), gradient scheme |-| IV. Typography System | Font plan (per-role families — title / body / emphasis / code), font size hierarchy |-| V. Layout Principles | Page structure (header/content/footer zones), layout pattern library (combine/break as content demands), spacing spec |-| VI. Icon Usage Spec | Source description, placeholder syntax, recommended icon list |-| VII. Visualization Reference List | Visualization type, reference template path, used-in pages, purpose |-| VIII. Image Resource List | Filename, dimensions, ratio, purpose, status, generation description |-| IX. Content Outline | Grouped by chapter; each page includes layout, title, core message (the page's one idea), **audience move** (how the page advances the global outcome), content blocks (in the selected phrasing mode), visualization type (if applicable), plus `Fact IDs` for sourced claims and `Data class: scenario` for invented demonstration data |-| X. Speaker Notes Requirements | File naming rules, content structure description |--**Generation steps**:-1. Read reference template: `templates/design_spec_reference.md`-2. Generate complete spec from scratch based on analysis-3. Save to: `projects/<project_name>.../design_spec.md`-4. **Generate execution lock**: read `templates/spec_lock_reference.md` and produce `projects/<project_name>.../spec_lock.md` — a compact, machine-readable form of the global **communication contract**, color / typography / icon / image / **page_rhythm** / **page_charts**, and route-specific PowerPoint structure decisions above. Do not copy `content_divergence` into the lock; its effect is already authored into §IX. Within the PowerPoint structure portion, free-design, brand-only, and `template_reuse_scope: style` routes write `pptx_structure.mode: flat` and omit all template mappings; only `template_reuse_scope: mirror|layout` routes additionally write `page_layouts`, `page_pptx_layouts`, `pptx_masters`, and `pptx_layouts`. This file is what the Executor re-reads before every page (see [executor-base.md](executor-base.md) §2.1). The values in `spec_lock.md` MUST exactly match the decisions recorded in `design_spec.md`; if they ever diverge, `spec_lock.md` wins and `design_spec.md` should be treated as historical narrative.+### 6.2 Planning Artifact Content++Generate Step 4 creates `design_spec.md` and `spec_lock.md` from their versioned scaffolds. The machine schemas own section names, order, grammar, enums, and conditional structure; do not restate or improvise that grammar here. The Strategist owns what the confirmed values mean and what content fills those structures.++Fill the scaffolded artifacts from the confirmed state and analysis. In §IX, each page carries layout, title, one core message, an **Audience move**, final content wording, applicable visualization/image references, `Fact IDs` for sourced claims, and `Data class: scenario` for invented demonstration data. Run `project_manager.py validate` after both artifacts are filled.++**Execution lock content**: `spec_lock.md` is the compact communication and execution contract for colors, typography, icons, images, page rhythm, chart choices, and route-specific PowerPoint structure. Do not copy `content_divergence` into the lock; its effect is already authored into §IX. Free-design, brand-only, and `template_reuse_scope: style` routes write `pptx_structure.mode: flat`; the conditional template module owns every structured mapping. Executor re-reads the lock before every page (see [executor-base.md](executor-base.md) §2.1). Values must match `design_spec.md`; on divergence, `spec_lock.md` wins and the design spec is historical narrative.+- **Communication trace is mandatory**: Copy `audience`, `communication_intent`, `audience_outcome`, `core_message`, `delivery_context`, `artifact_afterlife`, and canonical `consumption_mode` into `spec_lock.md communication`. Before finalizing §IX, check that every named purpose has at least one outline obligation and **every Slide block**, including cover / divider / closing pages, has an `Audience move` that advances the global outcome. A page that advances no purpose or outcome should be merged, rewritten, or cut. `project_manager.py validate` and `svg_quality_checker.py` enforce the section / field presence, not the subjective quality of the move.- - **page_rhythm is mandatory**: Based on the page list in §IX Content Outline, assign each page one of `anchor` / `dense` / `breathing` (see `spec_lock_reference.md` for the full vocabulary). This is what breaks the uniform "every page is a card grid" feel. New locks may not omit the section; consumer omission behavior is owned by [`executor-base.md`](executor-base.md) §2.1.+ - **page_rhythm is mandatory**: Based on the page list in §IX Content Outline, assign each page one of `anchor` / `dense` / `breathing`. This is what breaks the uniform "every page is a card grid" feel. New locks may not omit the section; consumer omission behavior is owned by [`executor-base.md`](executor-base.md) §2.1.- **Fact IDs and scenario labels are mandatory when applicable**: Read any `sources/*.facts.json`. For each §IX page, list the stable IDs actually used; never cite an ID whose claim is absent from the page. Mark invented KPIs/targets/internal ratios as `Data class: scenario` and state which values are scenario data. Executor carries external sources into notes/footnotes and renders a visible scenario label for scenario figures.- **Rhythm follows narrative, not quota**: `breathing` pages mark natural pauses — chapter transitions, standalone emphasis (hero quote / big number), SCQA bridges. Dense decks may legitimately be all `dense`. **Do NOT invent filler pages** ("Thank you", empty dividers) to pad rhythm — every `breathing` page must say something independent. Consumption mode biases the overall lean (`presentation` toward more `anchor` / `breathing`, `text` toward `dense`; see §6.1) — a bias, never a quota.- **Cover impact is mandatory**: Page `P01` is the deck's first visual contract, not a generic title slide. In `design_spec.md §IX`, add a `Cover impact` line for `P01` that names one concrete hook and one concrete composition strategy. Use the source's strongest available signal: a provocative core claim, object / scene metaphor, hero number, founder / product / audience moment, or a distilled conflict. Pair it with one concrete composition strategy — such as `full-bleed image + floating title`, `typographic poster`, `hero object`, `data hook`, `editorial scene`, `high-contrast abstract geometry`, or a fresh composition the deck's subject suggests (these are starting points, not the allowed set). If no external or AI image is available, still specify a native-SVG visual hook; do not fall back to "title + subtitle + decorative background". (Beautify / template-fill keep the source cover verbatim — this rule does not apply on those preservation paths.)@@ -881,47 +394,17 @@ This is what makes the axis meaningful: a `presentation` deck and a `text` deck- **Closing impact (only when the deck closes)**: the deck's last page is its final visual contract — the strongest impression after the cover. When the deck genuinely lands on a conclusion / call-to-action / final-takeaway page, give it a `Closing impact` line in §IX: name the one thing the audience should leave with (a distilled takeaway, a forward call, a memorable restatement of the core claim) + one composition that delivers it — never a generic "Thank you" / contact-only slide or a centered-title reprise of the cover. **Do NOT invent a closing page to satisfy this** — the filler-page ban above still holds; apply it only to the page where the deck actually resolves. Same exemptions as the cover: skip on template / beautify / template-fill preservation paths.- **pptx_structure is mandatory**: Free-design, brand-only, and `template_reuse_scope: style` routes write `mode: flat`; a style-reference route may also record `template_reuse_scope: style` but omits every structure mapping and `template_adherence`. `template_reuse_scope: mirror|layout` writes `mode: structured` plus `template_adherence: strict|adaptive`. Do not write legacy `baseline`, `template`, `preserve`, `layout_strategy`, or Layout-kind rows into a new project.- **Flat-route boundary**: With `mode: flat`, omit `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`. Do not plan native Master/Layout families or reusable placeholder slots. Every generated SVG object remains Slide-local: omit root Master/Layout identity, `data-pptx-layer`, and `data-pptx-placeholder*` metadata. Export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks.- - **Master roster (`mirror` / `layout` only)**: Write one `pptx_masters` row per Master as `<master_key>: <picker name>` and copy the template workspace's declared prototype roster. Keys use 1–64 ASCII letters, digits, dots, underscores, or hyphens, start with a letter/digit, and contain no spaces; human-readable spaces belong only in `<picker name>`. Master visuals are root-level atomic elements and may never be `<g>`.- - **pptx_layouts (`mirror` / `layout` reusable roster)**: Write every unique reusable Layout once as `<layout_key>: <master_key> | <PowerPoint layout name> | <prototype source>`. Copy the installed template roster with `template:<basename>` sources, including Layouts no generated page currently uses. A genuinely new adaptive Layout uses its first generated `P<NN>` as the source. Reuse a key only when fixed Layout atoms plus slot ids/types/indices/bounds/binding modes are identical. Name authored keys after composition (`timeline-spine`, `kpi-band-trio`, `content-image-right`), never after page topic. A Layout may intentionally have zero slots; never manufacture an empty `utility` kind or full-page fake slot.- - **page_pptx_layouts (`mirror` / `layout` page assignment)**: Write exactly one `P<NN>: <layout_key>` row per generated page. The key must exist in `pptx_layouts`; Master and picker name are inherited from that unique definition. **Self-check before writing the section**: compare distinct assigned keys against distinct compositions in §IX. Distinct compositions collapsing into a handful of role-only keys means pages were clustered by topic label; one shared skeleton splitting into topic-specific keys means pages were split by content wording. Both misstate the roster.- - **Slot planning (`mirror` / `layout` only)**: Each reusable slot is a direct root `<g id>` with `data-pptx-placeholder`, positive design-zone bounds, and exactly one compatible direct carrier. Bounds come from the intended safe area, column, panel inset, or media frame—not sample text ink. A genuinely composite region may use only the explicit `object` + `proxy` downgrade.- - **Adaptive refinement boundary (`mirror` / `layout` only)**: The initial definitions and assignments are complete, not provisional. If actual adaptive construction genuinely changes reusable framing or slot topology/bounds, Executor creates one new `pptx_layouts` definition sourced from that page and updates its `page_pptx_layouts` assignment while authoring the first page. It never mutates a reused contract silently. Export only compiles declared structure and never discovers or clusters Layouts.- - **page_layouts (`mirror` / `layout` only)**: Add one `P<NN>: <svg_basename>` row for every page. This is the complete authoring-input prototype mapping. Strict preserves that SVG's structural contract; adaptive keeps its Master and may explicitly define and assign a new output Layout identity during page authoring. Mirror additionally preserves literal visuals and text-node topology. Omit the whole section for free-design, brand-only, and `style` routes.+ - **Structured template route**: When [`strategist-template.md`](./strategist-template.md) is active and reuse is `mirror|layout`, follow its complete Master/Layout/slot/prototype mapping rules.- **page_charts (write only for chart pages that match a catalog template)**: For each page in `design_spec.md §VII` whose `reference template path` points to `templates/charts/<name>.svg`, add `P<NN>: <chart_name>`. Pages with `no-template-match` in §VII MUST NOT appear here (Executor would look for a non-existent reference). If the deck has no data-visualization pages, omit the section.- - **Hard rule**: On `template_reuse_scope: mirror|layout`, use `page_layouts` together with any `page_charts` entries only when the selected prototype shell is compatible. For a chart page without an exact roster match, adaptive mode selects the closest neutral input prototype and assigns an explicit output Layout key in the planning map; strict mode must select an existing compatible Layout or revise the outline. Never omit `page_layouts` on a structured mirror/layout route. A `style` route may still use chart templates through `page_charts`, but it has no page prototype mapping.----## 7. Project Folder--Project folder must exist before Strategist runs. If not, execute:--```bash-python3 scripts/project_manager.py init <project_name> --format <canvas_format>-```+## 7. Project Boundary-Save outputs to `projects/<project_name>_<format>_<YYYYMMDD>/design_spec.md`.+The Generate route owns project initialization and supplies `<project_path>`. Strategist writes only the two scaffolded planning artifacts at that root plus the explicitly triggered resource manifests; it does not choose or create another project path.----## 8. Complete Design Spec and Prompt Next Steps--After writing `design_spec.md` and `spec_lock.md`, output the next-step prompt below. This is a handoff instruction, not part of `design_spec.md`. Pick the variant by whether Step 3 copied a template into `<project_path>/templates/`.--### Template mode (template applied in Step 3)--```-✅ Design spec complete. Template ready.-Next step:-- Images include AI generation → Invoke Image_Generator-- Otherwise → Invoke Executor-```--### Free design (default, no template)+## 8. Handoff-```-✅ Design spec complete.-Next step:-- Images include AI generation → Invoke Image_Generator-- Otherwise → Invoke Executor (free design for every page)-```+After validation, return to the Generate Step 4 checkpoint. The route—not this role—owns whether Step 5 runs and how execution resumes or auto-proceeds.diff --git a/skills/ppt-master/references/svg-effects.md b/skills/ppt-master/references/svg-effects.mdnew file mode 100644index 00000000..441c91af--- /dev/null+++ b/skills/ppt-master/references/svg-effects.md@@ -0,0 +1,746 @@+> See [`shared-standards-core.md`](./shared-standards-core.md) for the mandatory SVG foundation.++# SVG Effects and Geometry Specification++Conditional reference for advanced paint, effects, transforms, freeform/radial geometry, and constructed visual styles. Load only when the page uses one of these capabilities.++**Cross-reference map**: unqualified §1, §2, and §4 references point to [`shared-standards-core.md`](./shared-standards-core.md); §6 references are local to this file.++## 6. Advanced SVG Effects and Authoring Techniques++**Reference — not a constraint**: “Advanced” means capability depth, not rarity.+Use any compatible technique when it serves the locked visual style and content.++### 6.1 Availability, Precedence, and Fidelity++| Decision layer | Authority |+|---|---|+| Technical validity | Required / Forbidden / Conditional contracts in this file |+| Project values | `<project_path>/spec_lock.md` colors, fonts, icons, and images |+| Aesthetic fit | Locked `visual_style` / `visual_style_behavior` |+| Per-page choice | Content purpose, hierarchy, legibility, semantics, and rhythm |++**Hard rule — illustrative colors**: colors below demonstrate syntax only;+generated pages use matching `spec_lock.md` roles. Fidelity labels are defined+in [`shared-standards-core.md`](./shared-standards-core.md). Review an `Approximate` result in native PPTX+when the effect carries material meaning.++---++### 6.2 Color, Alpha, and Opacity++Compatible paint grammar includes recognized named colors, `rgb()` / `rgba()`,+`hsl()` / `hsla()`, and `#RGB` / `#RGBA` / `#RRGGBB` / `#RRGGBBAA`. The+converter also tolerates legacy bare 3/4/6/8-digit hexadecimal tokens.++**Default — canonical generated paint tokens (may preserve compatible+alternatives)**: New `svg_output/` and reusable template SVGs write solid paint+as uppercase six-digit `#RRGGBB`. `fill` / `stroke` may instead use lowercase+`none` or the exact local reference form `url(#id)`. Named colors, lowercase or+short/alpha HEX, functional colors, and bare legacy HEX remain supported input.+The quality checker prints an optional canonical rewrite as a recommendation+warning; it does not require modification or block export.+Explicit empty, malformed, or unrecognized paint values are errors in both+Checker and exporter preflight; neither converts unknown intent into+`noFill` or default black. Omitted properties still follow their own element+contract, such as SVG's default fill or §6.3's required gradient-stop color.++| Intent | Canonical authoring | Native result / fidelity |+|---|---|---|+| Solid fill or text paint | `fill="#RRGGBB"` | Solid DrawingML paint; `Native-stable` |+| Fill/text alpha | Opaque `fill` + `fill-opacity="0..1"` | Fill/run alpha; `Native-stable` |+| Stroke alpha | Opaque `stroke` + `stroke-opacity="0..1"` | Line/outline alpha; `Native-stable` |+| Gradient-stop alpha | Opaque `stop-color` + `stop-opacity="0..1"` | Per-stop alpha; `Native-stable` |+| Shadow/glow alpha | Opaque `flood-color` + `flood-opacity="0..1"` | Effect alpha; `Native-stable` within §6.4 |+| Picture fade | `<image opacity="0..1">` | Picture `<a:alphaModFix>`; `Native-stable` |+| One atomic whole-object fade | Non-group element `opacity="0..1"` | Alpha compiled into its supported paint/effect channels; `Native-normalized` |+| Pattern alpha | Opaque pattern child paint + child fill/stroke opacity | Conditional; [`native-data-interface.md`](./native-data-interface.md) |+| CSS color alpha | Alpha-bearing named/functional/HEX paint | `Native-normalized`; recommendation warning only |+| Group fade | `<g opacity>` compatibility | `Approximate`; fidelity warning; §2.2 |++```text+effective fill alpha+= color alpha × ancestor group opacity × element opacity × fill-opacity+```++**Default — opaque color authority (may preserve compatible alpha colors)**:+New generated SVG puts alpha on the semantic channel that owns it. Existing or+intentional alpha-bearing color tokens remain convertible; they normalize into+the matching DrawingML color/alpha channels.++**Default — channel-specific alpha (may override for one atomic whole-object+fade)**: use `fill-opacity`, `stroke-opacity`, `stop-opacity`, or+`flood-opacity` when only that channel fades. Use element `opacity` only when+an image or one non-group atomic object intentionally fades all of its+supported paint/effect channels together. Do not use element `opacity` as an+alias for `rgba()` on a fill-only object.++**Default — alpha grammar (may preserve compatible alternatives)**: write+`opacity`, `fill-opacity`, `stroke-opacity`, `stop-opacity`, and+`flood-opacity` as finite unitless numbers from `0` to `1`. The converter also+accepts finite numeric values that SVG/CSS clamps into that interval;+`stop-opacity` and `flood-opacity` additionally accept finite percentages. The+checker reports those supported non-default spellings as recommendation warnings.+Malformed or non-finite values are errors in both Checker and exporter+preflight; neither substitutes an opaque default for unknown intent.+`fill="transparent"` / `stroke="transparent"` become no fill/line; use a color+plus alpha when a painted transparent layer must remain represented. Prefer+descendant alpha over group opacity when isolated compositing matters (§2.2).++PPTX import is a user-input boundary, not generated authoring. Tolerant mode+retains recognized color semantics, omits only unsupported paint properties,+and records the decision in `conversion-report.json`; `--strict` keeps the+closed parser checks. See+[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).+---++### 6.3 Gradients and Paint Effects++| Concern | Contract |+|---|---|+| Definition | Direct `<linearGradient>` / `<radialGradient>` child of `<defs>` with unique `id` |+| Reference | Exact local `url(#id)` |+| Stops | Direct `<stop>` children; explicit color; finite offset `0..1` or `0%..100%`; optional stop alpha |+| Coordinates | Normalized values / percentages; do not depend on `gradientUnits` user-space geometry |+| Forbidden | External/quoted refs, `href` inheritance, `gradientTransform`, `spreadMethod`, CSS gradients |++| Target | Contract and fidelity |+|---|---|+| `<rect>`, `<circle>`, `<ellipse>`, `<path>`, `<polygon>` fill/stroke | Linear `Native-normalized`; radial `Approximate` |+| `<line>` / `<polyline>` | Gradient stroke only; linear `Native-normalized`, radial `Approximate` |+| `<text>` / non-positional `<tspan>` | Gradient fill only; no gradient text outline |+| `<image>` | No gradient paint; use §6.5 overlays |++Linear export preserves stops/alpha/direction but reduces coordinates to an+angle. Radial export becomes a centered circular gradient and does not preserve+`cx/cy/r/fx/fy`. Gradient strokes remain editable, but PPTX-to-SVG re-import may+retain only the first stop. Stop alpha and element opacity multiply.+PPTX import normalizes compatible gradients and records any property-level+degradation without aborting the deck; `--strict` keeps the closed parser+contract. See+[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).+The quality checker and exporter preflight both validate definition location,+references, gradient structure, and paint context from the same closed contract.++**Hard rule — non-degenerate gradient geometry**: an `objectBoundingBox`+gradient stroke requires non-zero intrinsic width and height. SVG stroke width+does not expand that object bounding box, so a perfectly horizontal or vertical+gradient ribbon disappears even when its stroke is thick. Author such a ribbon+as a closed shape with gradient `fill`, or use a path whose intrinsic geometry+has both dimensions. Checker and exporter reject the degenerate stroke form.++```xml+<defs>+ <linearGradient id="flow" x1="0" y1="0" x2="1" y2="0">+ <stop offset="0%" stop-color="#2563EB"/>+ <stop offset="100%" stop-color="#10B981" stop-opacity="0.7"/>+ </linearGradient>+</defs>+<path d="M100 200 C260 80 420 320 620 180" fill="none"+ stroke="url(#flow)" stroke-width="12"/>+```++Preset patterns are a separate PPT interface in [`native-data-interface.md`](./native-data-interface.md).++---++### 6.4 Shadows, Glow, and Elevation++Filters are native-effect metadata, not a general pixel-filter surface.++| Concern | Contract |+|---|---|+| Definition/reference | Direct `<defs><filter id="...">` child with unique id; direct `filter="url(#id)"` attribute, never inline style |+| Public targets | `<rect>`, `<circle>`, `<path>`, `<text>` |+| Required primitive | `feDropShadow` or `feGaussianBlur` |+| Required parameters | Explicit `stdDeviation` on either effect primitive; explicit `dx`, `dy`, and `flood-opacity` on `feDropShadow`; explicit `flood-opacity` on `feFlood`; explicit `slope` on linear `feFuncA` |+| Accepted helpers | `feOffset`, `feFlood`, `feComposite`, `feMerge`, `feMergeNode`, `feComponentTransfer`, linear `feFuncA` |+| Alpha transfer | Linear `feFuncA` maps multiplicative `slope` only; `intercept` is unsupported |+| Blur sampling | `feGaussianBlur edgeMode` is unsupported; native effects do not expose the SVG edge-sampling modes |+| Primitive coordinates | Omit `primitiveUnits` or use `userSpaceOnUse`; `objectBoundingBox` coordinates are unsupported |+| Numeric values | Finite unitless values; non-negative `stdDeviation`; finite `dx` / `dy`; `feFuncA slope` within `0..1`; mapped glow `rad = stdDeviation × 9525`, shadow `blurRad = stdDeviation × 2 × 9525`, and shadow `dist = hypot(dx,dy) × 9525` must round into DrawingML `0..27273042316900` |+| Classification | Meaningful non-zero offset → one outer shadow; zero/no offset → one glow |+| Fidelity | `Approximate`; one filter becomes one DrawingML effect |++Flood opacity, linear `feFuncA slope`, and element opacity multiply. The+converter-only historical path may also multiply flood-color alpha and+ancestor group opacity.+Native export does not preserve filter-region, `in/in2/result`, merge order, or+composite topology. Other primitives, multiple independent effects, filters on+`<image>` / `<tspan>` / `<g>` / unsupported targets are forbidden; apply the+effect to supported objects or use explicit layers.+The sole `<g filter>` exception is the hash-locked+`data-pptx-part="geometry-preview"` transport in §1.4: it must be a direct child+of an imported preset object and reference the same filter as that object's one+hidden geometry carrier. The preview is render-only and never becomes a second+PowerPoint object; this exception does not authorize filters on ordinary groups.+PPTX import preserves one registered shape/connector shadow or glow and records+unsupported object/run effects as import diagnostics instead of exposing a new+authoring surface. See+[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary)+for tolerant, strict, and release-handling behavior.+The quality checker and exporter preflight enforce the same definition,+reference, primitive, target, and numeric-value contract. Missing required+geometry and malformed values are never replaced by effect defaults during+native export.++```xml+<defs>+ <filter id="softShadow" x="-15%" y="-20%" width="130%" height="150%">+ <feDropShadow dx="0" dy="6" stdDeviation="8"+ flood-color="#000000" flood-opacity="0.10"/>+ </filter>+ <filter id="expandedShadow" x="-15%" y="-20%" width="130%" height="150%">+ <feGaussianBlur in="SourceAlpha" stdDeviation="8" result="b"/>+ <feOffset in="b" dx="0" dy="6" result="o"/>+ <feFlood flood-color="#000000" flood-opacity="0.10" result="c"/>+ <feComposite in="c" in2="o" operator="in" result="s"/>+ <feMerge><feMergeNode in="s"/><feMergeNode in="SourceGraphic"/></feMerge>+ </filter>+ <filter id="titleGlow" x="-30%" y="-30%" width="160%" height="160%">+ <feGaussianBlur in="SourceAlpha" stdDeviation="6" result="b"/>+ <feFlood flood-color="#38BDF8" flood-opacity="0.45" result="c"/>+ <feComposite in="c" in2="b" operator="in" result="g"/>+ <feMerge><feMergeNode in="g"/><feMergeNode in="SourceGraphic"/></feMerge>+ </filter>+</defs>+```++Even `feDropShadow` with `dx="0" dy="0"` becomes glow. Use an existing accent+color for glow; black reads as diffuse shadow.++| Elevation | Use | `dy` | `stdDeviation` | Alpha |+|---|---|---:|---:|---:|+| Floor | Backgrounds, dividers, equal peers, body containers, decorative lines/icons, single-layer pages | — | — | — |+| Resting | Card over photo/panel, secondary callout | 2–4 | 4–8 | 0.06–0.10 |+| Raised | Primary CTA, focused card, overlay | 6–10 | 10–16 | 0.12–0.20 |+| Glow | Short display text, metric, focus accent | 0 offset | 4–8 | 0.35–0.55 |++**Strong default — single light source per page**: every `feOffset` shadow on+one slide shares the same `dx`/`dy` direction (default `dx="0"`, `dy="4"`–`dy="8"`,+light from upper front). Contradictory shadow directions read as multiple light+sources — a clear low-quality tell. The one sanctioned exception is a deliberate+upward paper-layer light, where every affected layer flips direction together;+never mix directions on the same plane. This is a strong default, not a+checker-enforced hard rule.++**Reference — not a constraint**: keep at most two+non-floor tiers; two or three shadowed objects usually suffice. Do not lift+every peer card or stack strong shadow, border, gradient, and tint on one+container. Same-family colored shadow is reserved for a focal accent. On dark+backgrounds, prefer a light hairline or restrained glow; never glow body copy.+Negative `dy` is valid for an intentional upward paper-layer light source when+every affected layer uses the same direction. For older/strict renderers,+replace a filter with two or three offset translucent shapes behind the object:+alpha `0.03–0.05`, increasing offset/radius, and optional same-family tint near+`0.04` (`Native-stable`).++---++### 6.5 Image Treatments, Overlays, and Glass-like Surfaces++| Need | Authoring contract | Fidelity |+|---|---|---|+| Cover/crop | Readable raster dimensions + aligned `slice` | Native `srcRect`; `Native-stable`; otherwise native crop cannot be guaranteed |+| Contain/fit | Aligned `meet` | Fitted picture frame; `Native-normalized` |+| Stretch | `preserveAspectRatio="none"` | Native stretched frame |+| Uniform fade | `<image opacity="...">` | Native picture alpha |+| Shaped picture | §1.2 image-only `clip-path` | Preset/custom picture geometry |++**Hard rule — closed image aspect-ratio grammar**: on `<image>`, omit+`preserveAspectRatio` for the default `xMidYMid meet`, use `none` alone for+stretch, or use one of the nine case-sensitive alignments (`xMinYMin`,+`xMidYMin`, `xMaxYMin`, `xMinYMid`, `xMidYMid`, `xMaxYMid`, `xMinYMax`,+`xMidYMax`, `xMaxYMax`) followed by explicit `meet` or `slice`. Generated SVG+always includes the mode on an aligned value. An alignment without a mode and+values needing whitespace normalization are compatible input and receive a+Checker recommendation. Empty values, `defer`, unknown/wrong-case alignments or+modes, `none` with a mode, and extra tokens are errors; the converter never+guesses a fallback.++**Hard rule — fit/clip interaction**: a non-trivial clip disables `meet`+frame-fit. Match the image box to the source ratio or use `slice`. Do not apply+filters directly to `<image>`.++**Hard rule — picture frames and sources are explicit and decodable**: every+SVG `<image>` has explicit positive `width`/`height` and exactly one non-empty+`href` or compatible `xlink:href`. A data URI must use a supported `image/*`+MIME type, valid strict base64 when marked+`base64`, a non-empty payload, and bytes that decode as the declared format.+An external asset must resolve, use a supported extension, be non-empty, and+decode as that extension. The registered formats are PNG, JPEG, GIF, WebP,+BMP, TIFF, SVG, EMF, and WMF. Explicit template substitution tokens may remain+unresolved only during template checking; export requires the resolved image.+Missing, ambiguous, corrupt, mislabeled, or unsupported sources are errors and+must never be dropped or packaged as invalid zero-byte media.++**Hard rule — nested SVG is an imported crop transport, not a general+viewport**: every non-root `<svg>` must be the exact picture-crop wrapper emitted+by `pptx_to_svg`. The outer element has explicit registered project-geometry+`x`, `y`, positive `width`/`height`, a unit-coordinate `viewBox` made of four+ordinary decimal values, and+`preserveAspectRatio="none"`; it contains exactly one direct, empty `<image>`+with exactly one non-empty `href` or `xlink:href`, `x="0"`, `y="0"`, `width="1"`,+`height="1"`, and `preserveAspectRatio="none"`. Its ancestor chain contains+only the root SVG and ordinary visual `<g>` wrappers; definitions, text,+render-only geometry details, and other non-visual containers cannot own this+transport. The outer wrapper may additionally carry `id`, a supported+`transform`, registered structure metadata (`data-pptx-layer` or+`data-pptx-placeholder-carrier`), and the importer metadata+`data-pptx-frame`, `data-pptx-object`, `data-pptx-shape-id`,+`data-pptx-shape-name`, and `data-pptx-shape-scope`. A shape clip is present+only when exact `data-pptx-crop="1"` and a registered image-only `clip-path`+occur together and the local clip definition resolves. The inner image may+add only registered `opacity`. The `viewBox` must quantize without clamping to+a DrawingML `srcRect` with a positive visible region: each signed crop value+must fit the OOXML percentage integer range `-2147483648..2147483647`, while+`l + r < 100000` and+`t + b < 100000` preserve a positive visible region. Negative crop values and+crop windows extending outside the source unit rectangle are retained exactly,+not clamped. `0 0 1 1` is redundant and must be written as a plain `<image>`.+Extra visual children, indirect images, character data, unknown attributes,+malformed or unrepresentable crop coordinates, and generalized nested+viewports are errors. Checker and the converter share this parser so a nested+subtree cannot pass validation and then silently disappear during export.++| Overlay | Construction | Typical stops / alpha |+|---|---|---|+| Directional scrim | Linear rect, darkest beside text | `0%: 0.88; 55%: 0.30; 100%: 0` |+| Bottom title fade | Vertical rect over lower image | black `0 → 0.72` |+| Vignette/spotlight | Centered radial rect (`cx=50%`, `cy=50%`, `r=70%`); native center only | black `0 → 0.58` |+| Brand wash | Directional existing brand-color gradient | `0.80 → 0.10` |+| Faux glass | Visible fields + diagonal linear panel (`0,0 → 1,1`) + highlight stroke; optional §6.4 elevation | white `0.38 → 0.12`; stroke about `0.55` |++Layer in document order: image → scrim/wash → text. True source/backdrop blur is+`Bake-required`; faux glass is explicit layering, not blur. Validate contrast+against the actual image. All overlay gradients follow §6.3 linear/radial+fidelity.++---++### 6.6 Lines, Connectors, Borders, and Markers++| Surface | Contract / native result |+|---|---|+| Solid stroke/width/alpha | `Native-stable` editable line |+| `4,4`; `6,3`; `2,2`; `8,4`; `8,4,2,4` (comma or space separators) | `dash`; `dash`; `sysDot`; `lgDash`; `lgDashDot` (`Native-normalized`) |+| Canonical custom dash | Exactly two positive finite unitless ordinary decimals (`dash gap`); export scales/quantizes against stroke width; `Native-normalized` |+| Compatible custom dash | Three or more positive finite unitless values are accepted but reduce to the first pair with a Checker recommendation; compatible numeric spellings also warn |+| `stroke-linecap` | `butt`, `round`, `square`; `Native-stable` |+| `stroke-linejoin` | `miter`, `round`, `bevel`; `Native-stable` |+| `vector-effect` | Exactly `none` or `non-scaling-stroke`; export resolves the choice into native line width (`Native-normalized`) |+| `stroke-dashoffset` | No general line mapping; allowed only as a direct finite unitless ordinary-decimal attribute on a §6.10 thick-circle shorthand (`px` suffix is compatible input and warns) |+| Gradient stroke | §6.3; re-import may flatten to first stop |+| `marker-start` / `marker-end` | §1.1 native line end; type `Native-normalized`, size `Approximate` (`sm/med/lg`) |++PPTX import treats unsupported line properties as source diagnostics: tolerant+mode retains the object and omits only the unsupported outline; `--strict`+retains the closed rejection behavior. See+[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).++The dash grammar is closed: exact lowercase `none`, or at least two finite+unitless numbers separated by whitespace or one comma. Generated SVG uses+ordinary decimal spellings. A leading plus sign, exponent, trailing decimal+point, surrounding whitespace, or longer custom list is compatible input and+produces a non-blocking normalization recommendation. Unknown units, one-value+arrays, empty or repeated comma fields, non-finite values, and negative or zero+entries are errors. The only zero exception is a gap declared directly on the+§6.10 thick-circle element.++Generated cap, join, and `vector-effect` values use the exact lowercase tokens+in the table. Surrounding whitespace is compatible input and produces a+recommendation; every other token is an error.++Match marker paint to the parent stroke using the shape-specific channel from+§1.1: fill for closed/oval line ends and stroke for the open arrow. Use markers+for connectors and §6.10 calculated geometry for a manual diagonal arrowhead.+When exact grid spacing matters, use one multi-subpath path rather than a+fixed-density preset pattern:++```xml+<path d="M40 0V120 M80 0V120 M0 40H120 M0 80H120"+ fill="none" stroke="#2E6EA8" stroke-width="0.8"/>+```++---++### 6.7 Advanced Text Treatments++**Hard rule — closed text property grammar**: generated text uses only the+values in the `Canonical authoring` column. Registered compatible input remains+convertible and receives a non-blocking normalization recommendation. Every+other value is invalid; the converter must not replace it with a default.++| Property | Canonical authoring | Compatible input | DrawingML mapping / rejection boundary |+|---|---|---|---|+| `font-weight` | `normal`, `bold`, or an exact integer hundred from `100` through `900` | `medium` → `500`; `semibold` → `600` | `normal` and `100..500` map to regular; `bold` and `600..900` map to `b="1"`; therefore numeric weights are `Native-normalized` |+| `font-style` | `normal` or `italic` | None | `italic` maps to `i="1"`; oblique, angle, relative, and CSS-wide values are invalid |+| `text-anchor` | `start`, `middle`, or `end` on `<svg>`, `<g>`, or `<text>` | None | Maps to left/center/right paragraph alignment plus normalized frame position; it is invalid on `<tspan>` because run-level anchoring has no mapping |+| `text-decoration` | `none`, `underline`, `line-through`, or `underline line-through` | `line-through underline` → canonical order | Maps to the single underline and strike run properties; unknown, repeated, or substring-like tokens are invalid |+| `letter-spacing` | Finite unitless ordinary decimal SVG px | The same ordinary decimal with `px`, `pt`, or `em`; normalize to unitless px | Maps to `a:rPr@spc`; the final value must fit DrawingML `-400000..400000`, and negative tracking must leave every generated DrawingML run with a positive estimated advance and its text frame with a positive extent; keywords, percentages, exponents, leading plus signs, trailing decimal points, non-finite values, and other units are invalid |++The registered text properties follow SVG inheritance, including declarations+on the root `<svg>`: inline `style` overrides the same element's direct+attribute, which overrides its ancestor. Relative font sizes and `em` tracking+resolve against the same effective inherited size in Checker and converter.+Every declaration is validated even when a later declaration overrides it, so+hidden garbage cannot bypass preflight.++The DrawingML character-spacing range is necessary but not sufficient for+negative tracking. After run assembly, each output run must retain a positive+estimated advance using the quantized `sz` and `spc` values that will actually+be written; a wider sibling run or paragraph line cannot hide a run whose+aggregate advance would reverse or collapse, which can reorder or drop+characters across PowerPoint-compatible renderers. The generated text frame+must also retain a positive horizontal and vertical extent. Checker rejects+directly measurable single-line violations, and the converter revalidates+every generated run and text frame before writing OOXML. It must not clamp,+take the absolute value of, or otherwise hide a non-positive advance or extent.+Adjacent authored runs with identical final DrawingML run properties form one+output run before sizing and validation; splitting text across equivalent+`<tspan>` nodes is not a tracking escape hatch. Tracking and width estimates+count the registered project text clusters rather than raw Unicode code points:+combining marks, variation selectors, emoji modifiers and ZWJ sequences,+paired regional indicators, and same-script virama conjuncts do not receive+internal spacing.+An unchanged imported native text body reuses the geometry carrier's positive+shape frame and attaches the preserved `txBody` payload instead of regenerating+runs or a text frame from the SVG estimate.++**Hard rule — element-specific text surface**:++- Inheritable text declarations belong only on `<svg>`, `<g>`, `<text>`, or+ `<tspan>`; placing them on geometry, image, definition, or reuse elements is+ an error rather than ignored decoration.+- `<text>` accepts `x`, `y`, registered paint/alpha/run properties, the text+ properties above, `font-family`, `font-size`, direct `filter`, direct+ `transform`, `xml:space`, `id`, and project `data-*` metadata.+- `<tspan>` accepts `x`, `y`, `dx`, `dy`, registered paint/alpha/run+ properties, `font-family`, `font-size`, `font-weight`, `font-style`,+ `letter-spacing`, `text-decoration`, `xml:space`, `id`, and project `data-*`+ metadata. It does not accept `text-anchor`, `filter`, or `transform`.+- `word-spacing`, `dominant-baseline`, `alignment-baseline`, `baseline-shift`,+ font shorthand/variant/stretch/feature/variation/synthesis controls,+ `font-kerning`/`kerning`, `font-size-adjust`, `line-height`, text alignment,+ indent/shadow/rendering controls, white-space/word-break/hyphenation+ controls, `writing-mode`, `vertical-align`, `direction`, `unicode-bidi`, and+ `text-transform` have no registered native mapping and are errors as direct+ attributes or inline style.+- Any other unregistered `font-*` or `text-*` property is also an error; the+ closed grammar must not grow through an ignored CSS spelling.++**Hard rule — project text whitespace**:++- `xml:space` is the project's closed authoring control for significant text+ whitespace. It is valid only as an exact direct attribute on `<text>` or+ `<tspan>`, accepts only the case-sensitive values `default` and `preserve`,+ inherits through the text tree, and may be reset on a child `<tspan>`.+- The project maps this control to the visible Chromium/SVG2 behavior used by+ Live Preview; it does not claim the legacy SVG 1.1 newline-deletion model.+ XML line endings and tabs become U+0020 SPACE. In `default` mode, contiguous+ U+0020 characters collapse across inline run boundaries and leading or+ trailing default-mode spaces in the resulting text chunk are removed. In+ `preserve` mode, every resulting U+0020 character remains significant.+- Only XML whitespace is normalized. NBSP, ideographic space, and other+ Unicode spacing characters remain literal text and must not be rewritten by+ a generic Unicode-whitespace regular expression.+- Source line breaks do not create PowerPoint paragraphs. Use the registered+ positioned-`tspan`/paragraph structure for visual lines, and preserve DOM+ text/tail order plus original style inheritance when normalizing that+ structure.++These allowlists are additive to the global structural blacklist and the+paint, font-size, opacity, filter, and transform value contracts owned by their+respective sections; they do not weaken those contracts.++| Treatment | SVG surface | Result / boundary |+|---|---|---|+| Underline / strike / both | `text-decoration="underline"`, `line-through`, or both | `Native-stable`; both emits both run properties |+| Mixed runs | Non-positional `<tspan>` | One `Native-normalized` editable frame; §4.2 |+| Font size | Generated default is a finite unitless SVG px value; compatible `px`, `pt`, `pc`/`pica`, `in`, `cm`, `mm`, `q`, `em`, and `rem` values receive a recommendation warning only | Converted to SVG px, then editable DrawingML point size; unsupported units/percentages error |+| Tracking | §6.7 closed `letter-spacing` grammar | `Native-normalized`; compatible units normalize to SVG px before DrawingML conversion |+| Transparency | `opacity` / `fill-opacity` on text/run | `Native-normalized` run alpha, not isolated compositing |+| Gradient fill | §6.3 gradient on text/run | Editable fill; geometry normalizes |+| Outline | Solid `stroke`, `stroke-width`, `stroke-opacity` | `Native-normalized` editable run outline; re-import does not reconstruct it |+| Shadow/glow | §6.4 filter on `<text>` only | Shape shadow / run glow; `Approximate` |+| Native bullet | Leading `· • ● ▪ ■ ◆ ◇ ◦ ‣` + non-empty content | `·`/`•` → `•`; others unchanged; color/alpha from marker run; font/size follow text |++```xml+<text x="100" y="200" font-size="20" xml:space="preserve">Current <tspan+ fill="#999999" text-decoration="line-through">old</tspan> value</text>+```++Use strikethrough for removed/former values; it is ordinary notation, not a+style-exclusive effect. Imported double underline/strike normalizes to single.+Bullet detection allows optional leading whitespace, requires non-empty content,+and leaves non-leading decorative glyphs as ordinary text.+Keep body tracking normal; CJK tracking defaults near/below 2% of font size and+above 5% triggers review. Text outline is solid only. `textPath`, masks, blend+modes, generated effects, and text-image knockouts are outside editable text.++---++### 6.8 Transforms, Layering, and Static Reuse++| Surface | Contract / fidelity |+|---|---|+| `rotate(angle[, cx, cy])` | Geometry/image/text/ordinary group; `Native-normalized` |+| `translate(x y)` | Geometry/image/group; pure translation also safe on text; `Native-normalized` |+| Positive scale / negative mirror | Geometry/image or a group/use whose expanded visual subtree is geometry/image only; explicit pivot; `Native-normalized` |+| `matrix(a b c d e f)` | Geometry/image or the same geometry/image-only group/use; transformed axes finite, non-zero, orthogonal; excludes rounded rectangles and subtrees containing them; `Native-normalized` |+| Source order | Back-to-front PPT z-order; `Native-stable` |+| `<g opacity>` | Compatible approximate mapping; generated SVG prefers descendant alpha, §2.2 |+| Local `<use>` | §1.3 compile-time reuse; `Native-normalized` |++**Hard rule — closed transform grammar**: Use only lowercase `translate`,+`scale`, `rotate`, and `matrix` with exact finite unitless argument counts:+`translate` 1/2, `scale` 1/2, `rotate` 1/3, and `matrix` 6. Separate arguments+and operations with whitespace or one comma. Leading/trailing/repeated commas,+adjacent operations without a separator, units, unknown functions, and+incomplete input fail quality check and export. Generated numeric tokens use+ordinary decimals; a supported leading `+`, exponent, or trailing decimal point+remains compatible input and receives a non-blocking normalization warning.+Model-facing translation values, rotation centers, and matrix `e/f` use at+most two decimals under §1.4; angles, scale arguments, and matrix `a/b/c/d`+retain the precision required by the transform.++Set text size/position directly. A text transform is either a translate-only+list or one rotate operation; do not scale, matrix-transform, or mix operations+on text. A group containing text follows the same translate-only/single-rotate+limit. `skewX`, `skewY`, zero/non-orthogonal axes, and shear matrices are+forbidden. Native chart/table markers allow translate/scale only. The §6.10+thick-circle shortcut does not inherit general transform support. Positive+rotation is clockwise and pivoted rotation normalizes the native frame. Every+cumulative matrix, including transforms split across ancestors, must remain+finite, non-zero, and orthogonal; importer/live-editor matrices do not expand+the hand-authored contract.+Mirror around vertical pivot `cx` with+`translate(cx 0) scale(-1 1) translate(-cx 0)`; use the analogous Y sequence+for a horizontal pivot. During mirror materialization, imported PowerPoint+groups with an axis flip keep their geometry reflection, while each descendant+SVG text node receives the matching counter-reflection so browser previews keep+glyphs upright. The tool-side native record retains the source group flip.++Layer back-to-front: background/image → scrim/shadow → main geometry → labels /+icons → top annotation. Finalization and native export independently expand+`<use>` into cloned editable primitives; PowerPoint does not retain a symbol /+instance graph.++---++### 6.9 Freeform Shapes and Curves++| Input | Native normalization | Fidelity |+|---|---|---|+| `M/L/H/V`, absolute or relative | Absolute `M/L` | `Native-normalized` |+| `C` | Cubic Bézier | `Native-normalized` |+| `S/Q/T` | Explicit cubic controls | `Native-normalized` |+| `A` | Cubic segments of at most 90° | `Approximate` |+| `Z`; polygon/polyline | Closed/open freeform | `Native-normalized` |++**Hard rule — complete freeform grammar**: Generated `path@d` and+`polygon` / `polyline@points` use finite unitless ordinary decimals and only+the commands registered above. Native export consumes the complete attribute;+it never extracts recognizable fragments while ignoring other characters.+Finite scientific notation, a leading plus sign, and a trailing decimal point+remain read-compatible and receive recommendation warnings; generated SVG does+not write them. Unknown commands or characters, misplaced/repeated commas,+non-finite numbers, missing attributes, incomplete command groups, and odd+point counts are invalid. A path starts with `M` / `m`; `A` radii are+non-negative and both arc flags are exactly `0` or `1`. Each registered path+command accepts its uppercase absolute and lowercase relative form. Legal+separator-free arc flag sequences remain valid and are parsed as individual+flag tokens. A polygon has at least three coordinate pairs and a polyline at+least two.++**Validation**: Checker and native export consume the same parser in+[`paths.py`](../scripts/svg_to_pptx/drawingml/paths.py); native-object fallback+bounds reuse its normalized commands rather than a second path grammar.++Command identity, relative coordinates, shorthand, arc parameters, and original+handles are not retained. Geometry needs non-zero bounds. Use a closed cubic+path for organic silhouettes, polygon/closed path for ribbons/facets, open path+for curved connectors, multi-`M` path for exact linework, and a [`shared-standards-core.md`](./shared-standards-core.md) §1.2 path clip+for organic pictures. Filled silhouettes end with `Z`; open paths use+`fill="none"`. Do not depend on `fill-rule="evenodd"`; build explicit visible+geometry or bake an essential knockout.+For a fixed background, a background-colored overlay is also valid.++| Rounded rect input | Result |+|---|---|+| One positive radius, or `0 < rx == ry <= min(width,height)/2` | `Native-stable` adjustable `roundRect` without distorting transforms; the same short-side limit applies to one-radius input |+| `0 < abs(rx-ry) < 0.5px` after scaling | One normalized native radius; `Approximate` |+| `abs(rx-ry) >= 0.5px`, either positive | Cubic custom geometry; no radius handle; `Approximate` |+| Equal radius above half the short side | Native short-side clamp may differ from SVG; `Approximate` |++---++### 6.10 Radial Geometry, Donuts, Gauges, Sunbursts, and Diagonal Arrowheads++For center `(cx,cy)`, radius `r`, and degrees `θ`:++```text+x = cx + r × cos(θ × π / 180)+y = cy + r × sin(θ × π / 180)+```++For clockwise pie/donut sectors, default to `-90°` only when the chart starts at+12 o'clock. A full-circle percentage sector spans `percentage × 360°`;+large-arc is `1` above `180°`; outer sweep is `1`, inner return is `0`. Split+both outer and inner boundaries of a full ring into at least two arcs each.+Calculated endpoints survive subject to EMU rounding; `A` curves remain cubic+approximations. Verify all spans plus gaps against the planned sweep.+Explicit arc sectors are editable `Approximate` freeforms. Thin circles using a+§6.6 preset/two-number dash stay `Native-normalized` ellipse lines.++```xml+<!-- 75% donut: center 400,400; outer 180; inner 100; -90° → 180°. -->+<path d="M400 220 A180 180 0 1 1 220 400+ L300 400 A100 100 0 1 0 400 300 Z" fill="#2563EB"/>+```++**Gauge**: require `max > min`, `p = clamp((value-min)/(max-min),0,1)`, and+`0 < planned clockwise sweep <= 360°`; value sweep is `p × planned sweep`.+`valueEndAngle = startAngle + valueSweep`; large-arc is `1` iff+`abs(valueSweep) > 180°`.+Omit the value sector at `p=0`. At `p=1` with `360°`, split both boundaries into+at least two arcs. Track/value share center, radii, start, and sweep flags.++**Sunburst — `Approximate`**: one explicit annular sector per node; each depth owns one radius+band and child angular intervals partition the parent. Do not use one `evenodd`+compound ring.++**Thick-circle shorthand — `Approximate`, non-position-sensitive only**:++- One circle per segment; `fill="none"`; the circle may use one `rotate` for its+ start angle, and ancestor transforms must be translate-only.+- Exactly two non-preset finite unitless ordinary-decimal values (`dash gap`);+ `stroke-dashoffset` is a direct finite unitless ordinary-decimal attribute.+- `0 < stroke-width < 2r`, `stroke-width/r >= 0.15`,+ `0 < dash < 2πr`, `gap >= 0`, and `dash + gap >= 2πr - 1` SVG unit. The+ one-unit tolerance exists only for integer-rounded circumference values.+- Native construction uses only the first dash and re-imports as a freeform.+ Its native start is 90° counterclockwise from the SVG preview; use explicit+ arcs whenever start angle, cap, or radial precision matters.++```xml+<circle cx="400" cy="400" r="140" fill="none" stroke="#2563EB"+ stroke-width="48" stroke-dasharray="615.75 263.90" stroke-dashoffset="0"/>+```++**Diagonal polygon arrowhead**: for a non-zero line, calculate rather than use a+fixed triangle:++```text+dx=x2-x1; dy=y2-y1; len=√(dx²+dy²); ux=dx/len; uy=dy/len+px=-uy; py=ux+tip=(x2,y2)+back1=(x2-ux×12+px×5, y2-uy×12+py×5)+back2=(x2-ux×12-px×5, y2-uy×12-py×5)+```++Use §1.1 markers for ordinary connectors; the polygon is for a manually drawn+filled `Native-normalized` arrowhead. Example:+`<polygon points="370,430 365.6,417.8 358.2,424.6"/>`.++---++### 6.11 Constructed Visual Styles++**Hard rule — explicit construction**: these are supported-layer recipes, not+browser-filter permissions.++**Reference — not a constraint**: use them only when they match the locked style.++| Intent | Construction | Boundary / fidelity |+|---|---|---|+| Faux glass | §6.5 translucent panel + highlight stroke + visible fields | No backdrop blur; `Native-normalized` |+| Hand-drawn mark | Rotated translucent bar + irregular `Q/C` paths + round caps | No roughness filter; `Native-normalized` |+| Ink wash | Few same-family translucent closed curves/strokes | No feather/wet edge; `Native-normalized` |+| Riso offset | Duplicate text/shape with small offset, second ink, lower alpha | No blend mode; `Native-normalized` |+| Pixel grid | Integer-aligned rects on one cell grid | `shape-rendering` preview-only; `Native-stable` |+| Halftone | Sparse calculated circles | `Native-stable`; bake dense screens / use suitable [`native-data-interface.md`](./native-data-interface.md) preset |+| Isometric facets | Shared-vertex top/front/side polygons, one light direction | 2D only; `Native-normalized` |+| Paper cut | Ordered organic paths + consistent §6.4 shadow per layer | Filter each layer, not group; `Approximate` |+| Gradient ribbon | Non-degenerate cubic path + §6.3 gradient stroke; closed gradient-filled shape for horizontal/vertical ribbons | `Native-normalized`; no mesh gradient; re-import may flatten color |+| Line-plus-area data | Low-alpha closed area first, crisp line above | Keep area subordinate; `Native-normalized` |++**Minimal construction anchors**:++```xml+<!-- Hand-drawn + ink. -->+<rect x="80" y="80" width="240" height="28" fill="#FDE68A"+ opacity="0.72" transform="rotate(-1,200,94)"/>+<path d="M90 150 Q210 142 330 151" fill="none" stroke="#1F2937"+ stroke-width="3" stroke-linecap="round"/>+<path d="M80 220 C160 160 250 180 330 230 Z" fill="#1F2937" opacity="0.16"/>+<path d="M90 240 C180 210 250 260 340 220" fill="none" stroke="#1F2937"+ stroke-width="10" stroke-linecap="round" opacity="0.70"/>++<!-- Riso, pixel cells, sparse dots. -->+<text x="86" y="320" font-family="Arial, sans-serif" font-size="64"+ fill="#EC4899" opacity="0.85">PRINT</text>+<text x="92" y="326" font-family="Arial, sans-serif" font-size="64"+ fill="#2563EB">PRINT</text>+<g id="pixel-cells" shape-rendering="crispEdges" fill="#2563EB">+ <rect x="400" y="80" width="16" height="16"/><rect x="416" y="80" width="16" height="16"/>+</g>+<g id="sparse-dots" fill="#EC4899"><circle cx="410" cy="140" r="3"/><circle cx="426" cy="140" r="6"/></g>++<!-- Isometric facets + line-over-area. -->+<g id="isometric-facets" transform="translate(520 160)">+ <polygon points="0,0 80,-24 160,0 80,24" fill="#60A5FA"/>+ <polygon points="0,0 0,48 80,72 80,24" fill="#3B82F6"/>+ <polygon points="80,24 80,72 160,48 160,0" fill="#2563EB"/>+</g>+<path d="M760 260 L860 220 L960 250 L960 340 L760 340 Z" fill="#2563EB" opacity="0.10"/>+<path d="M760 260 L860 220 L960 250" fill="none" stroke="#2563EB" stroke-width="4"/>+```++**Default — integer pixel grid (may override for deliberate irregular+treatment)**: avoid soft scaling; use explicit dots only for sparse editable+halftone and route dense full-slide texture to §6.12.++---++### 6.12 Unsupported Effects and Native-Safe Alternatives++| Unsupported intent | Do not author | Fidelity | Alternative |+|---|---|---|---|+| Source/backdrop blur; procedural texture | Plain blur, `feTurbulence`, `feDisplacementMap`, `feColorMatrix`, arbitrary filter graph | `Bake-required` | §6.4 effect, explicit geometry, translucent layers, or baked texture |+| Inner shadow, soft edge, reflection | Non-outer-shadow/glow graph | `Bake-required` | Explicit inset/highlight/shadow layers or image |+| Per-pixel compositing | Mask, blend mode, knockout, arbitrary alpha composite | `Bake-required` | Direct geometry; §1.2 image clip; otherwise bake |+| Exact custom tile | Unannotated `<pattern>` / `patternTransform` | `Bake-required` | Multi-subpath geometry, suitable [`native-data-interface.md`](./native-data-interface.md) preset, or bake |+| Sheared object | Skew/shear matrix | `Bake-required` | Pre-transform geometry path; bake text/image |++**Hard rule — blur semantics**: within §6.4, zero-offset `feGaussianBlur` means+glow; it does not blur the object or backdrop. Use a low-alpha raster for dense+grain and explicit circles/paths only for sparse editable marks.++Unsupported source effects remain visible where possible and retain their+import diagnostics. Resolve those diagnostics before release export; see+[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).++---++### 6.13 Scenario Quick Reference++**Reference — not a constraint**: fidelity remains authoritative in the owning+subsection; this table only routes scenarios.++| Decision family | Scenario routing | Authority / boundary |+|---|---|---|+| Elevation | Floating card → resting shadow; one CTA → colored shadow; equal peers/background → flat; maximum predictability → layered shapes; title/metric → glow | §6.4; never body-copy glow |+| Image/material | Text over image → directional scrim; bottom title → bottom fade; centered hero → vignette; brand wash → brand overlay; glass card → faux glass | §6.5; no backdrop blur |+| Lines | Draft/optional → dash; process direction → marker; flow/series → gradient stroke; exact grid → multi-subpath path | §6.6 / §6.3 |+| Text | Removed/former value → line-through; eyebrow → tracking; watermark/outline heading → text outline; list → native bullet | §6.7 |+| Composition | Move/rotate/mirror → §6.8 transform; repeated static mark → local `<use>` | §6.8; preserve z-order |+| Hand/print | Annotation → highlighter/curve; ink wash → layered alpha paths; Riso → offset duplicate | §6.11; no turbulence, true bleed, or blend mode |+| Pixel/halftone | Pixel accent → integer rect grid; sparse screen → circles | §6.11; dense screen → §6.12 |+| Faceted/layered | Pseudo-3D → 2D facets; paper cut → direct shadow per layer | §6.11; no 3D transform/group composite shadow |+| Data/freeform | Series depth → area first + line above; organic card → closed cubic; shaped image → [`shared-standards-core.md`](./shared-standards-core.md) §1.2 path clip | §6.11 / §6.9 |+| Radial | Donut/gauge → explicit arcs; sunburst → sector per node; position-insensitive ring → shorthand | §6.10; shorthand has 90° preview/native offset |+| Arrow | Manual diagonal arrowhead → calculated triangle; ordinary connector → marker | §6.10 / §1.1 |+| Unsupported | Dense grain, complex composite, or skew → explicit alternative or baked asset | §6.12; foreground text/data stay editable SVG |++---diff --git a/skills/ppt-master/references/svg-image-embedding.md b/skills/ppt-master/references/svg-image-embedding.mdindex 42de359c..be6273e6 100644--- a/skills/ppt-master/references/svg-image-embedding.md+++ b/skills/ppt-master/references/svg-image-embedding.md@@ -1,4 +1,4 @@-> See shared-standards.md for common technical constraints.+> See [`shared-standards-core.md`](./shared-standards-core.md) for common technical constraints.# SVG Image Embedding Guide@@ -28,7 +28,7 @@ Defined in the Design Specification & Content Outline; each image carries an `Ac|--------|---------|-------------------|| **Pending** | Acquisition needed (`Acquire Via: ai` / `web`) or derivation needed (`Acquire Via: slice`); not yet attempted | Image Acquisition Phase (Step 5) consumes this; must not remain after Step 5 || **Generated** | AI-generated file exists at expected path, or sliced element file exists at expected path | Reference from `../images/`; no on-slide credit needed. **Exception**: an `Illustration Sheet` row is only a slice source — it lives in §VIII but never in `spec_lock.md images`, so the Executor never places it |-| **Sourced** | Web-sourced file exists at expected path | Reference from `../images/`; check `image_sources.json` for `license_tier` — if `attribution-required`, render an inline credit element on the slide (see [executor-base.md §6](./executor-base.md) and [image-searcher.md §7](./image-searcher.md) for the visual spec) |+| **Sourced** | Web-sourced file exists at expected path | Reference from `../images/`; check `image_sources.json` for `license_tier` — if `attribution-required`, render an inline credit element on the slide (see [`executor-web-image.md`](./executor-web-image.md) §1 and [`image-searcher.md`](./image-searcher.md) §7 for the visual spec) || **Rendered** | Deterministic formula PNG exists at expected path (`Acquire Via: formula`) | Reference from `../images/`; use `preserveAspectRatio="xMidYMid meet"` and do not crop || **Needs-Manual** | Acquisition attempted once + one retry, failed; for `slice`, parent sheet is unavailable | Dashed placeholder unless user has manually supplied the file. For `slice` rows, place the parent sheet and rerun `slice_images.py`; do not hand-place individual element files || **Existing** | User already has image (`Acquire Via: user`) | Place in `images/`, reference with `<image>` |@@ -175,7 +175,7 @@ project/### Rounded Corner / Non-rectangular Image Cropping-`clipPath` **on `<image>` elements** is conditionally allowed — authoritative constraints in [shared-standards.md §1.2](shared-standards.md); do not restate or relax here.+`clipPath` **on `<image>` elements** is conditionally allowed — authoritative constraints in [`shared-standards-core.md`](./shared-standards-core.md) §1.2; do not restate or relax here.Fallback when `clipPath` doesn't fit: bake rounded corners into the source image (PNG with alpha) before embedding.diff --git a/skills/ppt-master/references/template-designer.md b/skills/ppt-master/references/template-designer.mdindex 7d21eca4..361d7c0c 100644--- a/skills/ppt-master/references/template-designer.md+++ b/skills/ppt-master/references/template-designer.md@@ -1,4 +1,4 @@-> See shared-standards.md for common technical constraints.+> See [`shared-standards-core.md`](./shared-standards-core.md) for common technical constraints.# Template Designer — Template Design Role@@ -82,7 +82,7 @@ color scheme. Do not copy an expanded import carrier/preview/fingerprintbundle into an authored template. `mirror` instead preserves the supportedexpanded lossless source representation. The exact syntax and validationcontract remain owned by-[`shared-standards.md`](./shared-standards.md) and the native-shape reference.+[`shared-standards-core.md`](./shared-standards-core.md) and the native-shape reference.**Hard rule — complete mirror graph**: Preserve every supported source Layout represented by the validated import,including Layouts unused by source Slides. Emit one complete source-page@@ -177,8 +177,8 @@ When the brief sets `Replication mode: mirror`, materialize a new template works**Scope rule — package-specific rules only.** A Deck `design_spec.md` describes its recurring application plus integrated identity and structure. A Layout spec describes only brand-neutral reusable structure and may state supported content shapes/delivery settings without owning a communication objective or narrative. Neither restates generic constraints — those live in the canonical references and are already loaded by every downstream role:-- General SVG required / forbidden / conditional interfaces → [`shared-standards.md`](shared-standards.md)-- Generic layout pattern library, spacing bands, font-size ratio bands → [`templates/design_spec_reference.md`](../templates/design_spec_reference.md) (read by Strategist when authoring the **project** design_spec)+- Always-on SVG rules and conditional-module routing → [`shared-standards-core.md`](./shared-standards-core.md)+- Generic layout pattern library, spacing bands, font-size ratio bands → [`strategist.md`](strategist.md) (used when authoring the **project** design spec)- Canonical placeholder vocabulary → §4 below- Content methodology (pyramid / SCQA / MECE) → [`strategist.md`](strategist.md)@@ -314,10 +314,10 @@ Sections to **omit** from template `design_spec.md` (sourced elsewhere — listi| Don't write | Source ||---|---|-| General SVG technical / compatibility rules | `shared-standards.md` |-| Generic layout pattern library (centered card / three-column / timeline / …) | `design_spec_reference.md` §V |-| Generic spacing bands (margin 40-60px, card gap 20-32px, etc.) | `design_spec_reference.md` §V |-| Generic font-size hierarchy (cover 2.5-5x body, page title 1.5-2x, …) | `design_spec_reference.md` §IV |+| Always-on SVG rules and conditional-module routing | `shared-standards-core.md` |+| Generic layout pattern library (centered card / three-column / timeline / …) | `strategist.md` §4 |+| Generic spacing bands (margin 40-60px, card gap 20-32px, etc.) | `strategist.md` §4 |+| Generic font-size hierarchy (cover 2.5-5x body, page title 1.5-2x, …) | `strategist.md` §g || Canonical placeholder table (`{{TITLE}}`, `{{PAGE_NUM}}`, …) | §4 below || Content methodology (pyramid / SCQA / MECE) | `strategist.md` || "Usage Instructions" boilerplate (copy template / select page / …) | `create-template.md` |diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex 9dd26068..4f46824c 100644--- a/skills/ppt-master/scripts/README.md+++ b/skills/ppt-master/scripts/README.md@@ -49,7 +49,7 @@ python3 scripts/update_repo.py| SVG pipeline | `preset_shape_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` | [docs/svg-pipeline.md](./docs/svg-pipeline.md); [native preset authoring](../references/native-shape-authoring.md) || PPTX transitions | `pptx_transitions.py` | [docs/pptx-transitions.md](./docs/pptx-transitions.md) || PPTX animations | `pptx_animations.py`, `animation_config.py` | [docs/pptx-animations.md](./docs/pptx-animations.md) |-| Spec maintenance | `update_spec.py` | [docs/update_spec.md](./docs/update_spec.md) |+| Spec maintenance | `update_spec.py`, `chart_recall.py` | [docs/update_spec.md](./docs/update_spec.md); [docs/chart-recall.md](./docs/chart-recall.md) || Image tools | `image_gen.py`, `latex_render.py`, `analyze_images.py`, `gemini_watermark_remover.py` | [docs/image.md](./docs/image.md) || Repo maintenance | `update_repo.py` | README install/update section || Troubleshooting | validation, preview, export, dependency issues | [docs/troubleshooting.md](./docs/troubleshooting.md) |@@ -73,9 +73,18 @@ Project setup:```bashpython3 scripts/project_manager.py init <project_name> --format ppt169python3 scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...> --move+python3 scripts/project_manager.py scaffold-spec <project_path>+python3 scripts/project_manager.py scaffold-lock <project_path>python3 scripts/project_manager.py validate <project_path>```+Chart candidate recall:++```bash+python3 scripts/chart_recall.py recall --page P03 --tag "time series" --tag "three metrics" --tag "direction over time"+python3 scripts/chart_recall.py validate line_chart+```+Template source import:```bash@@ -176,7 +185,7 @@ carrier, preview wrapper, or stored preview fingerprint. PPTX import andround-trip SVGs deliberately keep their expanded carrier/preview evidence andare not rewritten into this authored form. Keep ordinary rectangles, ellipses,freeform geometry, charts, icons, and ambiguous silhouettes as regular SVG.-See [`references/shared-standards.md`](../references/shared-standards.md) for+See [`references/shared-standards-core.md`](../references/shared-standards-core.md) §1.5 forthe normative contract and[`references/native-shape-authoring.md`](../references/native-shape-authoring.md)for selection and authoring guidance.diff --git a/skills/ppt-master/scripts/analyze_images.py b/skills/ppt-master/scripts/analyze_images.pyindex d8fa5088..aa501b66 100644--- a/skills/ppt-master/scripts/analyze_images.py+++ b/skills/ppt-master/scripts/analyze_images.py@@ -5,7 +5,7 @@ Image Size Analysis ToolReports objective parameters (width, height, aspect ratio, category) for allimages in a folder. Intentionally does NOT prescribe a layout — the Strategistdecides narrative intent (hero / atmosphere / side-by-side / accent) per-references/strategist.md §h; this tool only supplies the numbers.+references/strategist-image.md; this tool only supplies the numbers.When a canvas is specified, also reports the reference image/text area sizesthat would apply *if* an image is placed side-by-side with body text. Those@@ -406,7 +406,7 @@ def print_results(results: list[ImageAnalysis]) -> None:if has_layout:print("\nNote: 'Img (SxS)' shows the image area *if* the Strategist chooses the")print("side-by-side intent for this image. Decide narrative intent first — see")- print("references/strategist.md §h. Hero / atmosphere / accent intents ignore it.\n")+ print("references/strategist-image.md. Hero / atmosphere / accent intents ignore it.\n")print(f"{'No.':<4} {'Width':<7} {'Height':<7} {'Ratio':<7} {'Source':<8} {'Refs':<5} {'Size':<10} {'Category':<20} {'Img (SxS)':<14} {'Filename'}")else:print(f"\n{'No.':<4} {'Width':<7} {'Height':<7} {'Ratio':<7} {'Source':<8} {'Refs':<5} {'Size':<10} {'Category':<20} {'Filename'}")@@ -484,7 +484,7 @@ def generate_markdown(results: list[ImageAnalysis], canvas_key: str) -> None:print(f"\n## Image Resource Inventory (Auto-scan Results — {fmt_name})\n")print("> Decide narrative intent per image (hero / atmosphere / side-by-side /")- print("> accent) per `references/strategist.md` §h before filling the table. The")+ print("> accent) per `references/strategist-image.md` before filling the table. The")print("> `Img Area (SxS)` / `Text Area (SxS)` columns only apply if the chosen")print("> intent is side-by-side; ignore them for hero / atmosphere / accent intents.\n")@@ -520,7 +520,7 @@ def save_csv(results: list[ImageAnalysis], csv_path: str) -> None:has_layout = 'layout_type' in results[0] if results else False# NOTE: ImageArea_SxS / TextArea_SxS apply only if Strategist picks the- # side-by-side intent for this image (see strategist.md §h). The tool+ # side-by-side intent for this image (see strategist-image.md). The tool# does not prescribe a layout.with open(csv_path, 'w', encoding='utf-8') as f:if has_layout:diff --git a/skills/ppt-master/scripts/config.py b/skills/ppt-master/scripts/config.pyindex bd35ae92..04820712 100644--- a/skills/ppt-master/scripts/config.py+++ b/skills/ppt-master/scripts/config.py@@ -489,11 +489,18 @@ LAYOUT_MARGINS = {# SVG Policy Reference# ============================================================-# Do not mirror element/attribute rules here. The shared standard is the-# authoring authority and the quality checker enforces it.-# Keep the exported key for compatibility with existing config consumers.+# Do not mirror element/attribute rules here. The router selects the mandatory+# core and feature-triggered interfaces; the quality checker enforces them.+# Keep the exported authority key as the compatibility router for existing+# config consumers.SVG_CONSTRAINTS = {'authority': 'skills/ppt-master/references/shared-standards.md',+ 'core_authority': 'skills/ppt-master/references/shared-standards-core.md',+ 'conditional_authorities': {+ 'effects': 'skills/ppt-master/references/svg-effects.md',+ 'native_data': 'skills/ppt-master/references/native-data-interface.md',+ 'pptx_structure': 'skills/ppt-master/references/pptx-structure-interface.md',+ },'validator': 'skills/ppt-master/scripts/svg_quality_checker.py',}diff --git a/skills/ppt-master/scripts/docs/chart-recall.md b/skills/ppt-master/scripts/docs/chart-recall.mdnew file mode 100644index 00000000..f318ac8d--- /dev/null+++ b/skills/ppt-master/scripts/docs/chart-recall.md@@ -0,0 +1,45 @@+# Chart Candidate Recall++`chart_recall.py` gives the Strategist a bounded, deterministic shortlist without loading the full chart catalog into the runtime prompt. It reads `templates/charts/charts_index.json` on every invocation, so the catalog remains the only template registry.++## Recall candidates++Describe one page's information shape with 3-8 concise English semantic tags. Translate source-language or industry terms into structural meaning before invoking the script.++```bash+python3 skills/ppt-master/scripts/chart_recall.py recall \+ --page P03 \+ --tag "time series" \+ --tag "three metrics" \+ --tag "direction over time" \+ --limit 6+```++`--limit` accepts 3-8 and defaults to 6. It is a maximum, not a padding target: the deterministic JSON contains only positive-scoring candidates, up to the requested limit. Zero positive matches return an empty `candidates` list plus the explicit `no-template-match` option.++| Field | Contract |+|---|---|+| `page` | Input `P<NN>` page key |+| `semantic_tags` | Deduplicated input tags |+| `confidence` | Lexical recall strength; never a selection decision |+| `candidates` | Ranked keys, SVG paths, verbatim catalog summaries, scores, and matched tags |+| `no_template_match` | Explicit fallback option when every candidate conflicts with the page |++The scorer treats the key and the summary's Pick clause as positive evidence and the Skip clause as negative evidence. A term found only in Skip cannot make a candidate eligible, and Skip matches explicitly reduce a candidate's score. Unicode input is NFKC-normalized before matching. The Strategist still applies semantic judgment: inspect every returned summary, reject candidates whose Skip clause matches, and prefer the most specific valid structure. A low score does not authorize a forced match; when no candidate has a positive final score, the result carries an empty shortlist and the explicit fallback.++## Validate selected keys++Validate every selected template key before writing `design_spec.md §VII` or `spec_lock.md page_charts`:++```bash+python3 skills/ppt-master/scripts/chart_recall.py validate line_chart quadrant_text_bullets+```++The command is read-only. It exits `0` when every key exists and `1` when any key is absent. A page recorded as `no-template-match` is not a key and must not appear in `page_charts`.++## Selection boundary++- Preserve the two-lens review: numeric/data pages and structural-information pages.+- Record the selected candidate's returned `summary` verbatim as the Section VII `summary-quote`.+- Record real returned runners-up and page-specific rejection reasons.+- Open only the selected `<key>.svg` before authoring that visualization; do not load unrelated catalog SVGs.diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.mdindex ea80d43f..0beeded2 100644--- a/skills/ppt-master/scripts/docs/confirm_ui.md+++ b/skills/ppt-master/scripts/docs/confirm_ui.md@@ -239,7 +239,7 @@ After Stage 2 is confirmed, overwrite it with Stage-3 production recommendationsThe shape above is the **final** result: Stage 1 owns the communication contract, Stage 2 owns the complete deck solution (including color / typography / icons / images), and Stage 3 adds production mechanics. Intermediate writes carry the accumulated earlier fields with `stage1-confirmed` or `stage2-confirmed`; legacy `tier1` / `tier2` remain read-compatible but are no longer written.- Any option field may instead hold a **free-text custom string** (the user picked **Custom**); `color` / `typography` custom entries set `name: "custom"`. Image usage is not a custom string in new results: it is a source-id array, with free-text strategy captured in `image_notes`.-- `image_ai_path` and `image_strategy` are omitted from `result.json` unless `image_usage` includes `ai`. Both are honored downstream as confirmed choices — and the page is only a convenience surface over the **canonical chat channel**: the same choices made in chat are honored identically when no `result.json` exists. `image_ai_path` drives the Step 5 generation path (`image-generator.md` §7 — `host-native` forces the host tool even when `IMAGE_BACKEND` is set); the chosen `image_strategy` candidate is locked verbatim by Strategist h.5 (no re-pick).+- `image_ai_path` and `image_strategy` are omitted from `result.json` unless `image_usage` includes `ai`. Both are honored downstream as confirmed choices — and the page is only a convenience surface over the **canonical chat channel**: the same choices made in chat are honored identically when no `result.json` exists. `image_ai_path` drives the Step 5 generation path (`image-generator.md` §7 — `host-native` forces the host tool even when `IMAGE_BACKEND` is set); the chosen `image_strategy` candidate is locked verbatim by [`strategist-image.md`](../../references/strategist-image.md) §2 (no re-pick).- After the user clicks the **final Confirm** (Stage 3, or single-pass), the page saves `result.json` and shuts the server down (auto-close). Stage-1 **Confirm contract & continue** and Stage-2 **Confirm solution & continue** keep the page open while it polls for the once-authored downstream stage. In the default flow, the first `--daemon --wait` returns on the stage-1 result, `--wait-only --wait-stage stage2` returns on the stage-2 result, and the final `--wait-only` returns on the final result; the AI reads each immediately — no extra chat confirmation is required. Chat confirmation remains the fallback when the page cannot be used. Either way, Step 4 ends with a `--shutdown` cleanup so a never-confirmed page cannot keep holding port 5050 ahead of the Step 6 live preview.## Scopediff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.mdindex 4c9badec..12083681 100644--- a/skills/ppt-master/scripts/docs/project.md+++ b/skills/ppt-master/scripts/docs/project.md@@ -13,6 +13,8 @@ Main entry point for project setup and validation.```bashpython3 scripts/project_manager.py init <project_name> --format ppt169python3 scripts/project_manager.py import-sources <project_path> <source1_or_dir> [<source2_or_dir> ...]+python3 scripts/project_manager.py scaffold-spec <project_path>+python3 scripts/project_manager.py scaffold-lock <project_path>python3 scripts/project_manager.py validate <project_path>python3 scripts/project_manager.py info <project_path>```@@ -28,6 +30,17 @@ Notes:note), to avoid leaving unintended artifacts that could be committed by mistake.Pass `--copy` to force a copy for in-repo sources instead.- `--move` and `--copy` are mutually exclusive.+- `scaffold-spec` creates `design_spec.md` from+ `templates/scaffolds/design_spec.md`; `scaffold-lock` creates `spec_lock.md`+ from `templates/scaffolds/spec_lock.md`. Both substitute project/canvas+ metadata deterministically and refuse to overwrite an existing artifact.+- `validate` parses the existing Markdown artifacts against+ `templates/schemas/design_spec.schema.json` and+ `templates/schemas/spec_lock.schema.json`. It reports missing sections and+ fields, illegal enums, malformed page keys, and unmet conditional sections;+ it does not rewrite either artifact. Versioned scaffolds carry the schema+ marker. Markerless legacy artifacts are left on their prior validation path+ with a warning; malformed or unsupported markers are errors.- PPTX-family inputs are enriched automatically under `analysis/` withper-deck `<stem>.identity.json` / `<stem>.slide_library.json` plus the sharedmulti-deck index `source_profile.json` (`decks[]`).@@ -47,6 +60,8 @@ Examples:```bashpython3 scripts/project_manager.py init my_presentation --format ppt169+python3 scripts/project_manager.py scaffold-spec projects/my_presentation_ppt169_20251116+python3 scripts/project_manager.py scaffold-lock projects/my_presentation_ppt169_20251116python3 scripts/project_manager.py validate projects/my_presentation_ppt169_20251116python3 scripts/project_manager.py info projects/my_presentation_ppt169_20251116```diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.mdindex eec26bf6..d820f547 100644--- a/skills/ppt-master/scripts/docs/svg-pipeline.md+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md@@ -63,7 +63,7 @@ check and export rerender the locked registry to validate that group, so thecompact form has no hidden carrier, preview wrapper, or serialized previewfingerprint. `pptx_to_svg.py` continues to emit the expanded carrier/previewevidence required for import and round-trip decisions. The normative boundary-is owned by [`shared-standards.md`](../../references/shared-standards.md), with+is owned by [`shared-standards-core.md`](../../references/shared-standards-core.md) §1.5, withauthoring guidance in[`native-shape-authoring.md`](../../references/native-shape-authoring.md).@@ -489,9 +489,11 @@ Replaces `<use data-icon="chunk-filled/name" .../>`, `<use data-icon="tabler-fil## SVG Compatibility Contract-The canonical SVG authoring and native-mapping contract lives exclusively in-[`shared-standards.md`](../../references/shared-standards.md). This tool guide-does not repeat accepted syntax, rejected constructs, or conditional limits.+The always-on SVG authoring contract lives in+[`shared-standards-core.md`](../../references/shared-standards-core.md), with+advanced effects, native data objects, and structured PPTX metadata owned by+their conditionally loaded modules. This tool guide does not repeat accepted+syntax, rejected constructs, or conditional limits.`svg_quality_checker.py` validates source SVG before finalization.`finalize_svg.py` and native export apply the preprocessing required by thatdiff --git a/skills/ppt-master/scripts/error_helper.py b/skills/ppt-master/scripts/error_helper.pyindex 68b8f262..19b3a5fc 100644--- a/skills/ppt-master/scripts/error_helper.py+++ b/skills/ppt-master/scripts/error_helper.py@@ -112,7 +112,7 @@ class ErrorHelper:'Remove <foreignObject> elements','Use <text> + <tspan> for manual line wrapping','This is a project technical specification requirement',- 'Reference: references/shared-standards.md'+ 'Reference: references/shared-standards-core.md'],'severity': 'error'},@@ -121,7 +121,7 @@ class ErrorHelper:'solutions': ['Remove clip-path from shapes / groups / text','Draw the target geometry directly with the matching native element: <circle> / <ellipse> / <rect rx="..."> / <polygon> / <path>. A rect clipped to a circle is just a <circle>.',- 'clip-path on <image> is conditionally allowed — see references/shared-standards.md §1.2'+ 'clip-path on <image> is conditionally allowed — see references/shared-standards-core.md §1.2'],'severity': 'error'},@@ -130,7 +130,7 @@ class ErrorHelper:'solutions': ['Define the referenced <clipPath id="..."> inside <defs>','The clipPath must contain exactly one shape child (circle / ellipse / rect with rx,ry / path / polygon)',- 'Reference: references/shared-standards.md §1.2'+ 'Reference: references/shared-standards-core.md §1.2'],'severity': 'error'},@@ -181,14 +181,14 @@ class ErrorHelper:'severity': 'error'},# Note: <marker> and marker-end are NO LONGER forbidden — they are- # conditionally allowed (see references/shared-standards.md §1.1).+ # conditionally allowed (see references/shared-standards-core.md §1.1).# The converter maps qualifying markers to native DrawingML arrow heads.'marker_orphan_ref': {'message': 'marker-start/marker-end references a marker id, but no <marker> element is defined','solutions': ['Define the <marker> inside <defs>','Or remove the marker-start/marker-end attribute',- 'See shared-standards.md §1.1 for marker constraints',+ 'See shared-standards-core.md §1.1 for marker constraints',],'severity': 'error'},diff --git a/skills/ppt-master/scripts/prompt_audit.py b/skills/ppt-master/scripts/prompt_audit.pyindex 69191af0..7ea7f2b0 100644--- a/skills/ppt-master/scripts/prompt_audit.py+++ b/skills/ppt-master/scripts/prompt_audit.py@@ -1273,6 +1273,7 @@ def _has_schema_grammar_signal(line: str, schema_field: str) -> bool:or re.search(r"\b(formats?|grammars?|schemas?|syntaxes?|keys?|values?)\b", line, re.I)or re.search(r"P<NN>\s*:", line)or re.search(rf"{re.escape(schema_field)}\s*[:=]", line)+ or re.search(rf'"{re.escape(schema_field)}"\s*:', line)or (" | " in line and re.search(r"<[^>]+>", line)))diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.jsonindex 2ab88f46..410142a4 100644--- a/skills/ppt-master/scripts/prompt_audit_manifest.json+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json@@ -8,20 +8,32 @@"include": ["AGENTS.md","skills/ppt-master/**/*.md",- "skills/ppt-master/templates/charts/charts_index.json"+ "skills/ppt-master/templates/charts/charts_index.json",+ "skills/ppt-master/templates/schemas/*.json"],"exclude": [],"max_tokens": 365000},"file_budgets": {- "AGENTS.md": 2200,+ "AGENTS.md": 2300,"skills/ppt-master/SKILL.md": 800,- "skills/ppt-master/references/executor-base.md": 16500,- "skills/ppt-master/references/shared-standards.md": 33000,- "skills/ppt-master/references/strategist.md": 25000,- "skills/ppt-master/templates/design_spec_reference.md": 7700,- "skills/ppt-master/templates/spec_lock_reference.md": 5800,- "skills/ppt-master/workflows/generate-pptx.md": 15000,+ "skills/ppt-master/references/executor-base.md": 6900,+ "skills/ppt-master/references/executor-structured.md": 5300,+ "skills/ppt-master/references/executor-chart.md": 3100,+ "skills/ppt-master/references/executor-image.md": 800,+ "skills/ppt-master/references/executor-web-image.md": 500,+ "skills/ppt-master/references/executor-notes.md": 900,+ "skills/ppt-master/references/shared-standards.md": 250,+ "skills/ppt-master/references/shared-standards-core.md": 10800,+ "skills/ppt-master/references/svg-effects.md": 11600,+ "skills/ppt-master/references/native-data-interface.md": 6200,+ "skills/ppt-master/references/pptx-structure-interface.md": 4300,+ "skills/ppt-master/references/strategist.md": 11250,+ "skills/ppt-master/references/strategist-image.md": 1650,+ "skills/ppt-master/references/strategist-template.md": 1700,+ "skills/ppt-master/templates/design_spec_reference.md": 700,+ "skills/ppt-master/templates/spec_lock_reference.md": 1200,+ "skills/ppt-master/workflows/generate-pptx.md": 11050,"skills/ppt-master/workflows/stages/apply-template-workspace.md": 1800},"load_sets": {@@ -33,10 +45,10 @@"skills/ppt-master/SKILL.md","skills/ppt-master/workflows/routing.md"],- "max_tokens": 5000+ "max_tokens": 5200},"route.create-template.brand": {- "description": "Create Brand path; Template_Designer is not activated.",+ "description": "Create Brand path; it authors no SVG and does not activate Template_Designer or SVG modules.","scope": "cumulative","include": ["bootstrap.routing"@@ -47,10 +59,10 @@"skills/ppt-master/templates/README.md","skills/ppt-master/templates/brands/README.md"],- "max_tokens": 30000+ "max_tokens": 40600},"route.create-template.deck": {- "description": "Create Deck path through Template_Designer and shared SVG constraints.",+ "description": "Create Deck path through Template_Designer, SVG core, and the structured PPTX interface.","scope": "cumulative","include": ["bootstrap.routing"@@ -59,15 +71,16 @@"skills/ppt-master/workflows/create-template.md","skills/ppt-master/workflows/create-template/create-deck.md","skills/ppt-master/references/template-designer.md",- "skills/ppt-master/references/shared-standards.md",+ "skills/ppt-master/references/shared-standards-core.md",+ "skills/ppt-master/references/pptx-structure-interface.md","skills/ppt-master/references/canvas-formats.md","skills/ppt-master/templates/README.md","skills/ppt-master/templates/decks/README.md"],- "max_tokens": 75000+ "max_tokens": 57100},"route.create-template.layout": {- "description": "Create Layout path through Template_Designer and shared SVG constraints.",+ "description": "Create Layout path through Template_Designer, SVG core, and the structured PPTX interface.","scope": "cumulative","include": ["bootstrap.routing"@@ -76,12 +89,13 @@"skills/ppt-master/workflows/create-template.md","skills/ppt-master/workflows/create-template/create-layout.md","skills/ppt-master/references/template-designer.md",- "skills/ppt-master/references/shared-standards.md",+ "skills/ppt-master/references/shared-standards-core.md",+ "skills/ppt-master/references/pptx-structure-interface.md","skills/ppt-master/references/canvas-formats.md","skills/ppt-master/templates/README.md","skills/ppt-master/templates/layouts/README.md"],- "max_tokens": 75000+ "max_tokens": 57300},"route.enhance-native-pptx": {"description": "Finished-PPTX native enhancement route.",@@ -92,7 +106,7 @@"files": ["skills/ppt-master/workflows/native-enhance-pptx.md"],- "max_tokens": 8000+ "max_tokens": 8100},"route.fill-native-pptx": {"description": "Raw-PPTX native fill route.",@@ -103,10 +117,10 @@"files": ["skills/ppt-master/workflows/template-fill-pptx.md"],- "max_tokens": 11000+ "max_tokens": 10800},"route.generate.planning": {- "description": "Fixed Generate-PPTX planning context through Strategist output.",+ "description": "Fixed Generate-PPTX planning context through the Strategist core; schemas and scaffolds are tool-consumed.","scope": "cumulative","include": ["bootstrap.routing"@@ -115,13 +129,10 @@"skills/ppt-master/workflows/generate-pptx.md","skills/ppt-master/references/artifact-ownership.md","skills/ppt-master/references/strategist.md",- "skills/ppt-master/templates/design_spec_reference.md",- "skills/ppt-master/templates/spec_lock_reference.md","skills/ppt-master/references/modes/_index.md","skills/ppt-master/references/visual-styles/_index.md","skills/ppt-master/scripts/docs/confirm_ui.md","skills/ppt-master/templates/icons/README.md",- "skills/ppt-master/templates/charts/charts_index.json",{"glob": "skills/ppt-master/references/visual-styles/*.md","exclude": [@@ -132,18 +143,27 @@"registry": "visual-styles"}],- "max_tokens": 80000+ "max_tokens": 46250},"route.generate.planning-image": {- "description": "Generate-PPTX planning context when the image resource list is active.",+ "description": "Generate-PPTX planning context after a non-none image source is proposed or confirmed.","scope": "cumulative","include": [- "route.generate.planning"+ "route.generate.planning",+ "stage.generate.strategist.image-layout"],- "files": [- "skills/ppt-master/references/image-layout-patterns.md"+ "files": [],+ "max_tokens": 53800+ },+ "route.generate.planning-formula": {+ "description": "Formula-only planning context with no non-formula image resource or layout catalog.",+ "scope": "cumulative",+ "include": [+ "route.generate.planning",+ "stage.generate.strategist.image"],- "max_tokens": 86000+ "files": [],+ "max_tokens": 47000},"route.generate.planning-ai": {"description": "Generate-PPTX planning context when AI image direction is available.",@@ -154,7 +174,7 @@"files": ["skills/ppt-master/references/image-renderings/_index.md"],- "max_tokens": 88000+ "max_tokens": 55800},"stage.generate.apply-template-workspace": {"description": "Conditional Step 3 workspace validation, installation, and fusion framework.",@@ -262,10 +282,11 @@"scope": "cumulative","include": ["route.generate.planning",- "stage.generate.executor.flat"+ "stage.generate.executor.flat",+ "stage.generate.executor.notes"],"files": [],- "max_tokens": 135000+ "max_tokens": 67650},"route.generate.flat-ai-two-types": {"description": "Generate-PPTX context with AI images, one rendering, and two local types.",@@ -273,20 +294,24 @@"include": ["route.generate.planning-ai","stage.generate.executor.flat",+ "stage.generate.executor.image",+ "stage.generate.executor.notes","stage.generate.image.ai-two-types"],"files": [],- "max_tokens": 163500+ "max_tokens": 103500},"route.generate.flat-in-hand-image": {"description": "Generate-PPTX context with provided, placeholder, or formula images and no acquisition role.","scope": "cumulative","include": ["route.generate.planning-image",- "stage.generate.executor.flat"+ "stage.generate.executor.flat",+ "stage.generate.executor.image",+ "stage.generate.executor.notes"],"files": [],- "max_tokens": 140500+ "max_tokens": 80650},"route.generate.flat-web-image": {"description": "Generate-PPTX context with web image acquisition.",@@ -294,10 +319,12 @@"include": ["route.generate.planning-image","stage.generate.executor.flat",+ "stage.generate.executor.web-image",+ "stage.generate.executor.notes","stage.generate.image.web"],"files": [],- "max_tokens": 147500+ "max_tokens": 88000},"route.enhance-native-pptx.audio": {"description": "Enhance Native PPTX with the shared narration-audio stage.",@@ -317,51 +344,56 @@"profile.generate.beautify-pptx"],"files": [],- "max_tokens": 141500+ "max_tokens": 74400},"route.generate.flat-no-image-chart": {- "description": "Default flat Generate-PPTX path with the chart verification stage.",+ "description": "Default flat Generate-PPTX path with chart authoring, native-data replacement, and verification.","scope": "cumulative","include": ["route.generate.flat-no-image",+ "stage.generate.executor.chart",+ "stage.generate.executor.native-data","stage.generate.chart-authoring","stage.generate.verify-charts"],"files": [],- "max_tokens": 152500+ "max_tokens": 94900},"route.generate.brand-flat-no-image": {"description": "Brand-preset flat Generate-PPTX path without image acquisition.","scope": "cumulative","include": [- "route.generate.planning",+ "route.generate.planning-template","stage.generate.executor.flat",+ "stage.generate.executor.notes","stage.generate.template.brand"],"files": [],- "max_tokens": 139500+ "max_tokens": 74250},"route.generate.deck-structured-no-image": {"description": "Deck-preset structured Generate-PPTX path without image acquisition.","scope": "cumulative","include": [- "route.generate.planning",+ "route.generate.planning-template","stage.generate.executor.structured",+ "stage.generate.executor.notes","stage.generate.template.deck"],"files": [],- "max_tokens": 140500+ "max_tokens": 84600},"route.generate.layout-structured-no-image": {"description": "Layout-preset structured Generate-PPTX path without image acquisition.","scope": "cumulative","include": [- "route.generate.planning",+ "route.generate.planning-template","stage.generate.executor.structured",+ "stage.generate.executor.notes","stage.generate.template.layout"],"files": [],- "max_tokens": 141000+ "max_tokens": 84900},"route.generate.topic-only-flat-no-image": {"description": "Topic research followed by the default flat no-image Generate-PPTX path.",@@ -371,15 +403,14 @@"route.generate.flat-no-image"],"files": [],- "max_tokens": 136500+ "max_tokens": 69450},"stage.generate.executor.flat": {- "description": "Incremental flat Executor rules with one locked mode and visual style.",+ "description": "Incremental flat Executor core with one locked mode and visual style.","scope": "incremental","files": ["skills/ppt-master/references/executor-base.md",- "skills/ppt-master/references/shared-standards.md",- "skills/ppt-master/references/native-shape-authoring.md",+ "skills/ppt-master/references/shared-standards-core.md","skills/ppt-master/references/semantic-svg.md",{"glob": "skills/ppt-master/references/modes/*.md",@@ -401,16 +432,19 @@"allow_repeat": true}],- "max_tokens": 55500+ "max_tokens": 20700},"stage.generate.executor.structured": {- "description": "Structured Executor uses the same current mandatory references; structured interfaces remain inside shared-standards.",+ "description": "Structured template execution layered on the flat/shared core.","scope": "incremental","include": ["stage.generate.executor.flat"],- "files": [],- "max_tokens": 55500+ "files": [+ "skills/ppt-master/references/executor-structured.md",+ "skills/ppt-master/references/pptx-structure-interface.md"+ ],+ "max_tokens": 30150},"stage.generate.image.ai-two-types": {"description": "Incremental AI-image role with one preset rendering and two selected local types.",@@ -442,7 +476,7 @@"registry": "image-type-templates"}],- "max_tokens": 22500+ "max_tokens": 21000},"stage.generate.image.web": {"description": "Incremental web-image acquisition role.",@@ -454,20 +488,29 @@"max_tokens": 7000},"stage.generate.resume-execute": {- "description": "Fresh-session resume plus the shared Executor set and resume-only image references.",+ "description": "Fresh-session resume plus the flat Executor core and post-SVG notes rules.","scope": "fresh-session","include": ["bootstrap.routing",- "stage.generate.executor.flat"+ "stage.generate.executor.flat",+ "stage.generate.executor.notes"],"files": ["skills/ppt-master/workflows/generate-pptx.md","skills/ppt-master/workflows/stages/resume-execute.md",- "skills/ppt-master/references/artifact-ownership.md",- "skills/ppt-master/references/image-layout-spec.md",- "skills/ppt-master/references/svg-image-embedding.md"+ "skills/ppt-master/references/artifact-ownership.md"+ ],+ "max_tokens": 41800+ },+ "stage.generate.resume-execute-image": {+ "description": "Fresh-session resume when the locked resource plan contains image rows.",+ "scope": "fresh-session",+ "include": [+ "stage.generate.resume-execute",+ "stage.generate.executor.image"],- "max_tokens": 84000+ "files": [],+ "max_tokens": 47250},"stage.generate.topic-research": {"description": "Topic-only intake stage.",@@ -561,7 +604,7 @@"files": ["skills/ppt-master/workflows/governance/failure-recovery.md"],- "max_tokens": 2000+ "max_tokens": 2100},"stage.shared.conversion-reference": {"description": "Conditional source-conversion and import compatibility reference.",@@ -586,6 +629,123 @@"skills/ppt-master/references/native-shape-authoring.md"],"max_tokens": 2600+ },+ "route.generate.planning-template": {+ "description": "Generate-PPTX planning context after an explicit template workspace is installed.",+ "scope": "cumulative",+ "include": [+ "route.generate.planning",+ "stage.generate.strategist.template"+ ],+ "files": [],+ "max_tokens": 47900+ },+ "route.generate.planning-template-ai": {+ "description": "Explicit template workspace plus confirmed AI-image planning.",+ "scope": "cumulative",+ "include": [+ "route.generate.planning-template",+ "route.generate.planning-ai"+ ],+ "files": [],+ "max_tokens": 57450+ },+ "stage.generate.artifact-schema-guide": {+ "description": "Compact human guide loaded only to diagnose planning-artifact schema or scaffold failures.",+ "scope": "incremental",+ "files": [+ "skills/ppt-master/templates/design_spec_reference.md",+ "skills/ppt-master/templates/spec_lock_reference.md"+ ],+ "max_tokens": 1900+ },+ "stage.generate.executor.chart": {+ "description": "Conditional chart/table page execution rules.",+ "scope": "incremental",+ "files": [+ "skills/ppt-master/references/executor-chart.md"+ ],+ "max_tokens": 3100+ },+ "stage.generate.strategist.image": {+ "description": "Conditional Strategist image/formula policy module without a resource-layout catalog.",+ "scope": "incremental",+ "files": [+ "skills/ppt-master/references/strategist-image.md"+ ],+ "max_tokens": 1800+ },+ "stage.generate.strategist.image-layout": {+ "description": "Non-formula image planning plus the image-layout pattern catalog required for Section VIII rows.",+ "scope": "incremental",+ "include": [+ "stage.generate.strategist.image"+ ],+ "files": [+ "skills/ppt-master/references/image-layout-patterns.md"+ ],+ "max_tokens": 7800+ },+ "stage.generate.strategist.template": {+ "description": "Conditional Strategist module for an explicitly installed template workspace.",+ "scope": "incremental",+ "files": [+ "skills/ppt-master/references/strategist-template.md"+ ],+ "max_tokens": 1700+ },+ "stage.generate.executor.native-data": {+ "description": "Conditional preset-pattern and native chart/table metadata interface.",+ "scope": "incremental",+ "files": [+ "skills/ppt-master/references/native-data-interface.md"+ ],+ "max_tokens": 6200+ },+ "stage.generate.executor.image": {+ "description": "Conditional image embedding and layout execution rules.",+ "scope": "incremental",+ "files": [+ "skills/ppt-master/references/executor-image.md",+ "skills/ppt-master/references/image-layout-spec.md",+ "skills/ppt-master/references/svg-image-embedding.md"+ ],+ "max_tokens": 5600+ },+ "stage.generate.executor.web-image": {+ "description": "Conditional sourced-image attribution layered on image execution.",+ "scope": "incremental",+ "include": [+ "stage.generate.executor.image"+ ],+ "files": [+ "skills/ppt-master/references/executor-web-image.md"+ ],+ "max_tokens": 6100+ },+ "stage.generate.executor.notes": {+ "description": "Post-SVG speaker-notes generation rules.",+ "scope": "incremental",+ "files": [+ "skills/ppt-master/references/executor-notes.md"+ ],+ "max_tokens": 900+ },+ "stage.generate.executor.native-shape": {+ "description": "Conditional stock PowerPoint shape selection and fragment contract.",+ "scope": "incremental",+ "files": [+ "skills/ppt-master/references/native-shape-authoring.md"+ ],+ "max_tokens": 2600+ },+ "stage.shared.svg-effects": {+ "description": "Conditional advanced SVG paint, effects, transforms, and geometry for Generate Executor or Create Template.",+ "scope": "incremental",+ "files": [+ "skills/ppt-master/references/svg-effects.md"+ ],+ "max_tokens": 11600}},"duplicates": {@@ -626,15 +786,6 @@],"reason": "Brand preset scaffolds share fixed section boilerplate by design."},- {- "kind": "exact",- "fingerprint": "e7a8a8eeee32",- "paths": [- "skills/ppt-master/references/shared-standards.md",- "skills/ppt-master/references/strategist.md"- ],- "reason": "One-line pointer to the canvas-formats authority; a cross-reference, not a second definition."- },{"kind": "exact","fingerprint": "0d0f56615a1f",@@ -704,9 +855,39 @@"to": "skills/ppt-master/templates/decks/README.md"},{- "concern": "svg-technical-contract",+ "concern": "svg-core-contract","from": "skills/ppt-master/references/executor-base.md",- "to": "skills/ppt-master/references/shared-standards.md"+ "to": "skills/ppt-master/references/shared-standards-core.md"+ },+ {+ "concern": "structured-execution-contract",+ "from": "skills/ppt-master/references/executor-structured.md",+ "to": "skills/ppt-master/references/pptx-structure-interface.md"+ },+ {+ "concern": "native-data-contract",+ "from": "skills/ppt-master/references/executor-chart.md",+ "to": "skills/ppt-master/references/native-data-interface.md"+ },+ {+ "concern": "strategist-image-routing",+ "from": "skills/ppt-master/references/strategist.md",+ "to": "skills/ppt-master/references/strategist-image.md"+ },+ {+ "concern": "strategist-template-routing",+ "from": "skills/ppt-master/references/strategist.md",+ "to": "skills/ppt-master/references/strategist-template.md"+ },+ {+ "concern": "design-spec-schema",+ "from": "skills/ppt-master/templates/design_spec_reference.md",+ "to": "skills/ppt-master/templates/schemas/design_spec.schema.json"+ },+ {+ "concern": "spec-lock-schema",+ "from": "skills/ppt-master/templates/spec_lock_reference.md",+ "to": "skills/ppt-master/templates/schemas/spec_lock.schema.json"}],"registries": [@@ -826,7 +1007,7 @@],"schema_grammars": [{- "source": "skills/ppt-master/templates/spec_lock_reference.md",+ "source": "skills/ppt-master/templates/schemas/spec_lock.schema.json","fields": ["font_family","image_rendering",@@ -907,6 +1088,26 @@{"glob": "skills/ppt-master/scripts/pptx_shapes/data/NOTICE.md","reason": "License notice; never loaded as prompt context."+ },+ {+ "glob": "skills/ppt-master/references/shared-standards.md",+ "reason": "Compatibility router only; runtime load sets select the core and triggered modules directly."+ },+ {+ "glob": "skills/ppt-master/scripts/docs/chart-recall.md",+ "reason": "Maintainer command contract; Strategist core carries the complete runtime recall procedure."+ },+ {+ "glob": "skills/ppt-master/templates/scaffolds/*.md",+ "reason": "Versioned tool-copy assets; project_manager materializes them into the project rather than prompt-loading them."+ },+ {+ "glob": "skills/ppt-master/templates/charts/charts_index.json",+ "reason": "Machine-consumed chart-recall registry; Strategist receives only the ranked candidate summaries."+ },+ {+ "glob": "skills/ppt-master/templates/schemas/*.json",+ "reason": "Machine-consumed validation schemas; they are not loaded into model runtime context."}]}diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.pyindex 39189407..072438e4 100644--- a/skills/ppt-master/scripts/svg_quality_checker.py+++ b/skills/ppt-master/scripts/svg_quality_checker.py@@ -862,7 +862,7 @@ PPT_SAFE_FONTS = {}# Ramp envelope for font-size drift detection.-# From design_spec_reference.md §IV — Font Size Hierarchy: the ramp spans+# From strategist.md §g — Font Size Ramp: the ramp spans# from page-number floor (0.5x body) to cover-title ceiling (5.0x body).# Intermediate px values within this envelope are permitted per# executor-base.md §2.1 ("Executor may use an intermediate size ... provided@@ -1417,7 +1417,7 @@ class SVGQualityChecker:f"Invalid XML: {e} — SVG must be well-formed XML. "f"Use raw Unicode for typography (—, ©, →, NBSP); "f"escape XML reserved chars as & < > " ' "- f"(see references/shared-standards.md §1)."+ f"(see references/shared-standards-core.md §1).")return None@@ -3716,7 +3716,7 @@ class SVGQualityChecker:"will fail schema validation ('needs to be repaired'). ""Use one of: smGrid / lgGrid / dotGrid (grids), ""ltUpDiag / dkUpDiag / cross / diagCross / weave / plaid / "- "horzBrick (others); see references/shared-standards.md §7 "+ "horzBrick (others); see references/native-data-interface.md §1 ""for the full authoring enum.")@@ -4209,8 +4209,9 @@ class SVGQualityChecker:metadata), font-family, and font-size.Emits per-file warnings summarising the drift counts; exact driftingvalues are accumulated in self._drift_summary for the end-of-run- aggregation. When spec_lock.md is missing, silently skip (consistent- with executor-base.md §2.1's 'missing lock → warn and proceed' policy).+ aggregation. When spec_lock.md is missing, silently skip this local+ drift check; the Generate route's required-artifact gate owns whether+ execution may begin."""lock = self._get_spec_lock(svg_path)if lock is None:@@ -4277,7 +4278,7 @@ class SVGQualityChecker:# Font families: default `font_family` plus any per-role `*_family`# override (title_family / body_family / emphasis_family / code_family,- # per spec_lock_reference.md). Any of these is a legitimate declared+ # per templates/schemas/spec_lock.schema.json). Any of these is a legitimate declared# value; an SVG that uses any one of them is not drifting.allowed_fonts = set()if typo:diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml/paths.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml/paths.pyindex b4fa4346..aba92947 100644--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml/paths.py+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml/paths.py@@ -1,6 +1,6 @@"""SVG path parsing, normalization, and DrawingML path command generation.-See references/shared-standards.md §6.9 for the project freeform grammar.+See references/svg-effects.md §6.9 for the project freeform grammar."""from __future__ import annotationsdiff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml/utils.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml/utils.pyindex c2626dca..71cbb534 100644--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml/utils.py+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml/utils.py@@ -1,7 +1,8 @@"""Coordinate, transform, color, and font helpers for DrawingML conversion.-See references/shared-standards.md §2.1 and §6.2–§6.8 for project geometry,-paint/effects, image-fit, line-presentation, and transform authoring contracts.+See references/shared-standards-core.md §2.1 for project geometry and+references/svg-effects.md §§6.2–6.8 for paint, image-fit, line-presentation,+and transform authoring contracts."""from __future__ import annotationsdiff --git a/skills/ppt-master/templates/README.md b/skills/ppt-master/templates/README.mdindex 4350c769..bd60622c 100644--- a/skills/ppt-master/templates/README.md+++ b/skills/ppt-master/templates/README.md@@ -74,17 +74,18 @@ readable; directory shape alone does not indicate legacy Master/Layout semantics## Design specification references-[`design_spec_reference.md`](./design_spec_reference.md) is the project-level-Strategist reference for the generated presentation's full specification and-content outline. Reusable template `design_spec.md` files are deliberately-smaller: they contain portable metadata and only the identity, structure, or-application rules owned by that package. General SVG/PPT rules remain-centralized in-[`shared-standards.md`](../references/shared-standards.md).+[`schemas/design_spec.schema.json`](./schemas/design_spec.schema.json) and+[`scaffolds/design_spec.md`](./scaffolds/design_spec.md) own the machine+structure and starting artifact; [`design_spec_reference.md`](./design_spec_reference.md)+is their compact authoring index. Reusable template `design_spec.md` files are+deliberately smaller: they contain portable metadata and only the identity,+structure, or application rules owned by that package. General SVG rules live+in [`shared-standards-core.md`](../references/shared-standards-core.md), with+effects and PowerPoint interfaces loaded only when triggered.## Visualization Templates-The `charts/` directory contains 57 standardized visualization templates. For backward compatibility, the directory name remains `charts/`, but its scope includes charts, infographics, process diagrams, relationship diagrams, strategic frameworks, and system architecture diagrams:+The `charts/` directory contains the registered visualization templates. For backward compatibility, the directory name remains `charts/`, but its scope includes charts, infographics, process diagrams, relationship diagrams, strategic frameworks, and system architecture diagrams:- KPI Cards- Bar Chart / Stacked Bar Chartdiff --git a/skills/ppt-master/templates/charts/CHART_STYLE_GUIDE.md b/skills/ppt-master/templates/charts/CHART_STYLE_GUIDE.mdindex 0e711225..a27f8fe0 100644--- a/skills/ppt-master/templates/charts/CHART_STYLE_GUIDE.md+++ b/skills/ppt-master/templates/charts/CHART_STYLE_GUIDE.md@@ -6,9 +6,9 @@## 0. 上游规范引用本文档只定义 **图表模板专用** 的美学与实现配方。项目级 SVG-创作、兼容性例外与条件映射统一以+创作、兼容性例外与条件映射由[`references/shared-standards.md`](../../references/shared-standards.md)-为权威;本指南不摘录、不放宽该合同。+路由到各自的权威模块;本指南不摘录、不放宽这些合同。---@@ -272,7 +272,7 @@ font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Micr## 6. 通用 SVG 技术约束-本指南不定义或摘录项目级 SVG 允许项、禁用项与条件映射。当前合同统一见+本指南不定义或摘录项目级 SVG 允许项、禁用项与条件映射。当前合同入口见[`shared-standards.md`](../../references/shared-standards.md);新增或修改模板时,必须对目标文件运行 `svg_quality_checker.py` 并通过校验。@@ -354,12 +354,22 @@ expanded 无损表达属于独立合同,不得复制为新模板创作格式```- **`key`** = SVG 文件名去掉 `.svg`,下划线小写(如 `bullet_chart`)-- **`summary`** 是**选型句**,不是描述句。语法见 `meta.summaryGrammar`:先说什么时候选它,再用 `Skip if ... (use <other_key>)` 指向最容易混淆的兄弟模板+- **`summary`** 是**选型句**,不是描述句。语法见 `meta.summaryGrammar`:先说什么时候选它,再用 `Skip if ... (use <other_key>)` 指向最容易混淆的兄弟模板;该句会原样进入候选召回输出- **`meta.total`** 同步 +1-> **不需要** `label` / `categories` / `quickLookup` / `keywords` —— 这些都已经移除。Strategist 全量读取 summary 列表后语义匹配,不依赖任何预计算索引。**注意**:summary 是英文,但 source 文档常含中文/行业术语("中台"、"架构图"、"管道"),Strategist 自己负责语义翻译再匹配。如果一个模板的命中强依赖某个中文短语,把它的英文等价物写进 summary 的 Pick 子句里。+> **不需要** `label` / `categories` / `quickLookup` / `keywords`。[`chart_recall.py`](../../scripts/chart_recall.py) 每次从当前 registry 动态召回候选,不维护第二份索引。`summary` 使用英文;Strategist 先把中文或行业术语("中台"、"架构图"、"管道")翻译为 3–8 个英文内容形态标签,再调用脚本。若模板命中依赖某个概念,把其英文等价物写进 `Pick for` 子句。-### 9.2 反例+### 9.2 召回烟测++修改 `summary` 后,用一个正向页面形态执行召回,并确认目标模板进入候选;再验证模板 key:++```bash+python3 skills/ppt-master/scripts/chart_recall.py recall \+ --page P03 --tag "time series" --tag "three metrics" --tag "trend" --limit 6+python3 skills/ppt-master/scripts/chart_recall.py validate line_chart+```++### 9.3 反例❌ 只写"是什么":`"summary": "Bidirectional comparison chart for two datasets"`✅ 写"何时选":`"summary": "Pick for two mirrored datasets sharing a common axis (age pyramid, A/B). Skip for >2 sides (use grouped_bar_chart)."`diff --git a/skills/ppt-master/templates/charts/README.md b/skills/ppt-master/templates/charts/README.mdindex a3e0132b..4d2df8c6 100644--- a/skills/ppt-master/templates/charts/README.md+++ b/skills/ppt-master/templates/charts/README.md@@ -4,9 +4,9 @@ This directory contains the standardized SVG visualization templates used by PPT## Source of truth-[`charts_index.json`](./charts_index.json) is the single source of truth for the library: total count + one selection-rule `summary` per template (format: `"Pick for X. Skip if Y (use other_key)."`). Both human readers and AI roles read it in full — there is no category/keyword sub-index. Selection is done by semantic match against the summary list in one pass.+[`charts_index.json`](./charts_index.json) is the single source of truth for the library: total count + one selection-rule `summary` per template (format: `"Pick for X. Skip if Y (use other_key)."`). [`chart_recall.py`](../../scripts/chart_recall.py) can recall a bounded candidate set from this live registry without maintaining a second category or keyword index.-To browse the library, open `charts_index.json` and scan the `charts` block top-to-bottom; each entry's `summary` answers "when do I pick this, when do I skip" directly.+For one planned page, provide 3-8 English semantic content-shape tags, then inspect the positive-scoring returned summaries plus the explicit `no-template-match` option. The requested 3-8 limit is a cap: the tool never pads a weak result with zero-score keys, and zero positive matches returns only the fallback. See [`chart-recall.md`](../../scripts/docs/chart-recall.md). The Generate workflow remains the authority for when Strategist uses this helper; maintainers may still open the registry directly when editing or auditing the catalog.## Style rules@@ -60,8 +60,8 @@ Native replacement authoring remains active for all 23 currently supported data-| Specialty business charts | `waterfall_chart`, `funnel_chart`, `stock_chart`, `radar_chart` | ChartEx or classic specialty charts || Text-grid tables | `basic_table`, `financial_statement_table` | Native DrawingML tables |-Replacement payloads must include explicit `name`, `x`, `y`, `width`, and `height` fields so the native frame aligns with the fallback drawing. Keep legends, explanatory cards, source notes, center KPIs, and custom callouts outside the marked group when they must remain separate shapes; otherwise accept and review the native-object export warning. Canonical rectangular merged text cells may use anchor-only `row_span` / `col_span` metadata with blank covered cells; nonrectangular merges and graphical cells (harvey balls, rating dots, avatars) stay unmarked on the SVG fallback route. Per-side borders, plain multi-paragraph cells, and the closed run-rich paragraph schema use the contracts in [`shared-standards.md`](../../references/shared-standards.md#powerpoint-native-chart--table-replacement-markers-opt-in). Relationship-bearing text, structural line breaks, fields, tabs, bullets, and arbitrary rich-text OOXML stay on the SVG fallback route.+Replacement payloads must include explicit `name`, `x`, `y`, `width`, and `height` fields so the native frame aligns with the fallback drawing. Keep legends, explanatory cards, source notes, center KPIs, and custom callouts outside the marked group when they must remain separate shapes; otherwise accept and review the native-object export warning. Canonical rectangular merged text cells may use anchor-only `row_span` / `col_span` metadata with blank covered cells; nonrectangular merges and graphical cells (harvey balls, rating dots, avatars) stay unmarked on the SVG fallback route. Per-side borders, plain multi-paragraph cells, and the closed run-rich paragraph schema use the contracts in [`native-data-interface.md`](../../references/native-data-interface.md#2-powerpoint-native-chart--table-replacement-markers-opt-in). Relationship-bearing text, structural line breaks, fields, tabs, bullets, and arbitrary rich-text OOXML stay on the SVG fallback route.## Usage-Before generating a chart page, open the corresponding `<key>.svg` file to read its structure and layout. Files are named after the `key` field in `charts_index.json` (e.g. `column_chart.svg`, `quadrant_bubble_scatter.svg`). Templates are named by visual structure, not by business-model name — keywords like SWOT, BCG, PEST, OKR, Porter's Five Forces, Value Chain are matched via each template's `summary` field.+Before generating a chart page, open the selected `<key>.svg` file to read its structure and layout. Files are named after the `key` field in `charts_index.json` (e.g. `column_chart.svg`, `quadrant_bubble_scatter.svg`). Templates are named by visual structure, not by business-model name — terms like SWOT, BCG, PEST, OKR, Porter's Five Forces, and Value Chain are translated into semantic content-shape tags before candidate recall.diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.mdindex 6640aea4..5f1ca760 100644--- a/skills/ppt-master/templates/design_spec_reference.md+++ b/skills/ppt-master/templates/design_spec_reference.md@@ -1,363 +1,70 @@-# {project_name} - Design Spec+# Design Spec Structure-> Human-readable design narrative — rationale, audience, style, color choices, content outline. Read once by downstream roles for context.->-> Machine-readable communication + execution contract: `spec_lock.md` (compact communication trace plus color / typography / icon / image / structure locks). Executor re-reads it before every SVG page to resist purpose and design drift. Keep both in sync; on divergence, `spec_lock.md` wins.+Project-level `design_spec.md` is an English-heading Markdown artifact. Its machine contract is [`schemas/design_spec.schema.json`](./schemas/design_spec.schema.json); authoring starts from [`scaffolds/design_spec.md`](./scaffolds/design_spec.md).-## I. Project Information+## 1. Create the artifact-| Item | Value |-| ---- | ----- |-| **Project Name** | {project_name} |-| **Canvas Format** | {canvas_info['name']} ({canvas_info['dimensions']}) |-| **Page Count** | [Filled by Strategist] |-| **Target Audience** | [Filled by Strategist] |-| **Communication Intent** | [Open prose: what the presentation must accomplish; preserve multiple purposes plus priority / sequence when present. Common purpose names are prompts, not enum values.] |-| **Desired Audience Outcome** | [The observable success condition: what the audience will know, understand, believe, decide, or do.] |-| **Core Message / Ask / Action** | [The claim(s), decision request(s), or action(s) that must land; preserve their relationship when several coexist.] |-| **Delivery Context** | [Presenter-led / reader-led / hybrid / recorded; occasion, time constraint, and interaction context.] |-| **Artifact Afterlife** | [Review / approval / audit / archive / hand-off / reuse / none planned; state what the file must support after the event.] |-| **Reading Mode** | [`text` read-close / `balanced` business / `presentation`; Confirm UI compatibility key: `delivery_purpose`, execution-lock key: `consumption_mode`. Defines how meaning is divided among the page, visuals, presenter, and notes; therefore drives page grammar, granularity, density / rhythm, page-count recommendation, and note burden. The body baseline is a downstream typography default, not the definition shown to the user. See strategist.md §6.1.] |-| **Content Strategy** | [Material divergence — the user's free-text intent on how closely to follow the source vs how freely to reshape it (or "balanced default"); facts stay sourced however free. Confirmed at c; consumed when authoring §IX. Not in spec_lock.] |-| **Design Style** | {design_style} |-| **Template Reuse Scope** | [`mirror` / `layout` / `style` — include only when Step 3 loaded a deck/layout template; omit for free design and brand-only templates. `mirror` requires a mirror-capable workspace; `style` uses the flat route.] |-| **Template Adherence** | [`adaptive` / `strict` — include only when Template Reuse Scope is `mirror` or `layout`; omit for `style`. Also written under `spec_lock.md pptx_structure`.] |-| **Created Date** | {date_str} |+Run the scaffold command once, then replace every `[fill]` value while preserving the section headings:------## II. Canvas Specification--| Property | Value |-| -------- | ----- |-| **Format** | {canvas_info['name']} |-| **Dimensions** | {canvas_info['dimensions']} |-| **viewBox** | `{canvas_info['viewbox']}` |-| **Margins** | [Recommended by Strategist, e.g., left/right 60px, top/bottom 50px] |-| **Content Area** | [Calculated from canvas] |-------## III. Visual Theme--### Theme Style--- **Mode**: [pyramid / narrative / instructional / showcase / briefing — narrative skeleton, locked at d Layer 1]-- **Visual style**: [preset name or custom — aesthetic, locked at d Layer 2; carries no HEX]-- **Theme**: [Light theme / Dark theme]-- **Tone**: [Filled by Strategist, e.g., tech, professional, modern, innovative]--### Color Scheme--> Strategist: determine values from project content, industry, brand colors.-> Step 4 Confirm UI: present **≥3** color candidates (creative recommendations always offer real choice — same rule as h.5; fewer only on the honest-shortfall exception, with a stated reason), each with a user-facing core `palette` (background / secondary_bg / primary / accent / secondary_accent / body_text), in `confirm_ui/recommendations.json`; the confirmed candidate from `result.json` seeds this table. Strategist derives the remaining text, border, state, and style-neutral colors when writing this full scheme. Schema: [`scripts/docs/confirm_ui.md`](../scripts/docs/confirm_ui.md).--| Role | HEX | Purpose |-| ---- | --- | ------- |-| **Background** | `#......` | Page background (light theme typically white; dark theme dark gray/navy) |-| **Secondary bg** | `#......` | Card background, section background |-| **Primary** | `#......` | Title decorations, key sections, icons |-| **Accent** | `#......` | Data highlights, key information, links |-| **Secondary accent** | `#......` | Secondary emphasis, gradient transitions |-| **Body text** | `#......` | Main body text (dark theme uses light text) |-| **Secondary text** | `#......` | Captions, annotations |-| **Tertiary text** | `#......` | Supplementary info, footers |-| **Border/divider** | `#......` | Card borders, divider lines |-| **Success** | `#......` | Positive indicators (green family) |-| **Warning** | `#......` | Issue markers (red family) |--> **Reference**: Industry colors in `references/strategist.md` or `scripts/config.py` under `INDUSTRY_COLORS`--### AI Image Strategy (fill only when §VIII has `ai` rows)--- **Image Rendering**: [one of the 20 names in `references/image-renderings/_index.md` (e.g. `vector-illustration`), or `custom`]-- **Image Rendering Behavior**: [required when Rendering is `custom`; one-paragraph prose per `image-renderings/_index.md §1.5`]--> Strategist: lock rendering once per deck in h.5; every AI image inherits it. Image color is not independently confirmed: Image_Generator reads the ordinary §III Color Scheme / `spec_lock.md colors` roles directly. Leave this section out if §VIII has no `ai` rows; omit the Behavior row for a preset rendering.--### Gradient Scheme (if needed, using SVG syntax)--```xml-<!-- Title gradient -->-<linearGradient id="titleGradient" x1="0%" y1="0%" x2="100%" y2="100%">- <stop offset="0%" stop-color="#[primary]"/>- <stop offset="100%" stop-color="#[secondary accent]"/>-</linearGradient>--<!-- Background decorative gradient (explicit stop-opacity keeps the palette reusable) -->-<radialGradient id="bgDecor" cx="80%" cy="20%" r="50%">- <stop offset="0%" stop-color="#[primary]" stop-opacity="0.15"/>- <stop offset="100%" stop-color="#[primary]" stop-opacity="0"/>-</radialGradient>+```bash+python3 skills/ppt-master/scripts/project_manager.py scaffold-spec <project_path>```------## IV. Typography System--### Font Plan--> **Per-role families are expected, not optional.** Title / Body / Emphasis / Code may each use a different family (e.g., display serif title + geometric sans body). One family throughout is not required. See [strategist.md §g — Font Combinations](../references/strategist.md) for starting directions; you may propose a combination not listed.->-> **⚠️ PPT-safe stack discipline (HARD rule).** PPTX stores concrete exported Latin / EA typefaces per run — no runtime fallback. Every stack's exported Latin / EA typefaces MUST resolve to cross-platform pre-installed fonts: `"Microsoft YaHei"` / `SimSun` / `Arial` / `"Times New Roman"` / `Consolas`. Stacks that export non-preinstalled typefaces (Inter / Google Fonts / brand typefaces) are allowed only when this spec notes the font-install or embedding requirement.--**Typography direction**: [Fill in one phrase, e.g., "modern CJK sans" / "academic serif" / "brand-specific: McKinsey Bower (requires font install)"]--> Step 4 Confirm UI: present **≥3** typography candidates (creative recommendations always offer real choice — same rule as h.5; fewer only on the honest-shortfall exception, with a stated reason), each splitting CJK + Latin for `heading` and `body` (with `css` preview stacks), in `confirm_ui/recommendations.json`. The Stage-2 reading mode supplies one shared initial `body_size` baseline in **px** (the system's only unit, every canvas); switching font / direction cards preserves the current sizing state. The confirmed `result.json` carries px directly — no conversion. Schema: [`scripts/docs/confirm_ui.md`](../scripts/docs/confirm_ui.md).--Two views on the same font decisions — fill both, keep them consistent:--- **Role breakdown** (table below) — lists the *pieces* per role: CJK font, Latin font, CSS generic fallback. Human-readable design language.-- **Per-role font stacks** (after the table) — the *ordered* CSS `font-family` strings that actually go into SVG `font-family=""` and `spec_lock.md`'s `*_family` lines. Order controls browser rendering (Latin-led vs. CJK-led), so this is the **actual data** — not derivable from the table alone.--| Role | Chinese | English | Fallback tail |-| ---- | ------- | ------- | ------------- |-| **Title** | [e.g., `"Microsoft YaHei"`, or `"Microsoft YaHei", "PingFang SC"` for macOS preview nicety] | [e.g., `Georgia`] | [e.g., `serif`] |-| **Body** | [e.g., `"Microsoft YaHei", "PingFang SC"`] | [e.g., `Arial`] | [e.g., `sans-serif`] |-| **Emphasis** | [e.g., `SimSun`, or `—` for Latin-only] | [e.g., `Georgia`] | [e.g., `serif`] |-| **Code** | — | [e.g., `Consolas, "Courier New"`] | [e.g., `monospace`] |--**Per-role font stacks** (CSS `font-family` strings, one per role — arrange the table's pieces in the order your design intends):--- Title: `[Fill in stack, e.g. Georgia, "Microsoft YaHei", serif for Latin-led; or "Microsoft YaHei", "PingFang SC", Georgia, serif for CJK-led]`-- Body: `[Fill in stack — may be same as Title]`-- Emphasis: `[Fill in stack, or write "same as Body" to omit the override]`-- Code: `[Fill in monospace stack, e.g. Consolas, "Courier New", monospace]`--> **Stack ordering — why it matters**: CSS `font-family` falls back font-by-font (not char-by-char) — the browser uses the **first installed** font for everything it can render, skipping to the next only when a glyph is missing. So:-> - `Georgia, "Microsoft YaHei", serif` → Latin in Georgia (elegant serif), CJK falls through to Microsoft YaHei. **Use when Latin typography is the primary design statement** (academic / editorial / Latin-heavy covers).-> - `"Microsoft YaHei", Georgia, serif` → Everything in Microsoft YaHei (Latin uses YaHei's Latin glyphs — a different design tone). **Use when the deck is CJK-primary and Latin is incidental**.->-> The converter (`drawingml/utils.py parse_font_family`) maps these to PPTX `<a:latin>` / `<a:ea>` regardless of order — but browser preview and SVG native rendering reflect stack order. Pick the order matching your design intent.--> **Why two views**: the breakdown shows role assignment at a glance; stacks carry the ordering info the breakdown can't encode. Keep both consistent — table cells should be exactly the fonts in the stacks (any order).--### Font Size Hierarchy--> **Ramp discipline, not a fixed menu.** `body` is the single anchor; every other size is a ratio of it. Each row below gives the role's allowed ratio band. **Structural roles (page title / body / subtitle / annotation / footnote) resolve to one size each and stay that size deck-wide** — pick the value once, lock it, reuse it on every page; same-role drift is what makes a deck look unprofessional. The in-band freedom to use an intermediate value without pre-declaring is for **special / feature elements** (hero number, cover / section display headline, one-off emphasis); if such a size recurs, declare it as its own slot so it too stays consistent.-> **Unit boundary (HARD rule).** Author this section in **unitless px** — the system's only unit, every canvas. There is no pt layer and no conversion: the confirmed value is already px. Never write `pt`, `px`, `em`, or any unit in `spec_lock.md` or SVG. Geometry (margins / gaps / card sizes) is px everywhere.-> **Baseline selection**: after reading mode has made the information-carriage decision, the Confirm UI uses it to seed one fixed body baseline and derives unpinned role sizes locally. This is a typography default, not part of the reading-mode label or card description. Communication intent, content density, and visual style drive page treatment / rhythm / the *other* roles, **not** the body size.--**Baseline (unitless px)**: Body font size = [fill in]. For PPT 16:9, the initial typography default is **`text`** `20`, **`balanced`** `24` (default), **`presentation`** `32`. The browser applies `reading mode → body baseline → unpinned role sizes` locally without regenerating Stage 2. A user-edited body or role value is pinned; every confirmed `result.json typography.body_size` / `sizes` value is already px and becomes the locked slot verbatim. For non-PPT canvases, author px from the confirmed canvas scale (see [strategist.md §g](../references/strategist.md) per-canvas table).--| Purpose | Ratio to body | Example @ body=32 (`presentation`) | Example @ body=24 (`balanced`) | Weight |-| ------- | ------------- | --------------------------- | ------------------------- | ------ |-| Cover title (hero headline) | 2.5-5x | 80-160 | 60-120 | Bold / Heavy |-| Chapter / section opener | 2-2.5x | 64-80 | 48-60 | Bold |-| Page title | 1.5-2x | 48-64 | 36-48 | Bold |-| Hero number (consulting KPIs) | 1.5-2x | 48-64 | 36-48 | Bold |-| Subtitle | 1.2-1.5x | 38-48 | 29-36 | SemiBold |-| Lead-in / intro | 1.1-1.4x | 35-45 | 26-34 | Regular / Medium |-| Subheading | 1.1-1.3x | 35-42 | 26-31 | SemiBold |-| **Body content** | **1x** | **32** | **24** | Regular |-| Annotation / caption | 0.7-0.85x | 22-27 | 17-20 | Regular |-| Page number / footnote | 0.5-0.65x | 16-21 | 12-16 | Regular |--> **Subtitle / lead-in / subheading bands overlap by design** — choose among them by *role*, not size: `subtitle` sits under a title, `lead` is a lead-in / pull-quote in the body flow, `subheading` labels a block inside the content area. Each is its own slot, declared only when the deck uses it, and then held at one size deck-wide like any structural role. Font stays at the **family** level (no new typeface per role): `subheading` → heading / `title_family`, `lead` → `body_family` or `emphasis_family` — size + weight carry the hierarchy.-> The two px columns are illustrations for common baselines. For any other `body` value, multiply by each row's ratio. All size values here and in `spec_lock.md` are px (no pt anywhere). The checker (`svg_quality_checker._check_spec_lock_drift`) reads the live `body` (px) from `spec_lock.md` and applies the bands, so no code change is needed for a different baseline.--> Sizes outside **every** band remain forbidden — surface the need and extend `spec_lock.md typography` (e.g., `cover_title: 96`) rather than invent a one-off value.--> **Hero in single-focus / breathing pages**: when one element *is* the entire page — a large number, a headline, a key phrase — it is the visual subject, not body content. Such heroes may borrow the cover-title band (2.5–5×); for greater emphasis, declare a hero slot in `spec_lock.md` (e.g., `hero_number` / `hero_headline`) — checker exempts declared slots with no fixed upper limit. The row above "Hero number (consulting KPIs) 1.5–2×" applies only to numeric KPIs in dashboard/data layouts, not to full-page focal elements.-------## V. Layout Principles--### Page Structure--- **Header area**: [Height and content description]-- **Content area**: [Height and content description]-- **Footer area**: [Height and content description]--### Layout Pattern Library (combine or break as content demands)--> **Principle — proportion follows information weight, not preset ratios.** The table below is a pattern library, not a menu. Combine two patterns on one page, break the grid entirely for a `breathing` page, or propose a pattern not listed when content calls for it. Defaulting every page to a symmetric grid produces the "AI-generated" look — vary intentionally.--| Pattern | Suitable Scenarios |-| ------- | ----------------- |-| **Single column centered** | Covers, conclusions, key points |-| **Symmetric split (5:5)** | Comparisons where two sides carry equal weight |-| **Asymmetric split (3:7 / 2:8)** | One side dominates — data chart vs. brief takeaway, image vs. caption |-| **Top-bottom split** | Processes, timelines, ultra-wide image + text |-| **Three/four column cards** | Feature lists, parallel points, team intros |-| **Matrix grid (2×2)** | Two-axis classifications, strategic quadrants |-| **Z-pattern / waterfall** | Storytelling, case studies — content blocks alternate left/right guiding the eye |-| **Center-radiating** | Core concept + surrounding nodes, ecosystem / stakeholder maps |-| **Full-bleed + floating text** | `breathing` / feature pages — image fills canvas, text floats with opacity overlay |-| **Figure-text overlap** | Hero moments — headline / big number sits over or against an image edge instead of beside it |-| **Negative-space-driven** | A single element in 40-60% whitespace — lets one idea land with weight |--### Spacing Specification--> Spacing defaults depend on **container type**. Cards are one option, not the universal default. Tables below split by container type; a page may consult only one set (e.g., a `breathing` page with no cards uses only universal + non-card entries).--**Universal** (any container type):--| Element | Recommended Range | Current Project |-| ------- | ---------------- | --------------- |-| Safe margin from canvas edge | 40-60px | [fill in] |-| Content block gap | 24-40px | [fill in] |-| Icon-text gap | 8-16px | [fill in] |--**Card-based layouts** (consult only when the page uses cards — typically `dense` pages with parallel containers):--| Element | Recommended Range | Current Project |-| ------- | ---------------- | --------------- |-| Card gap | 20-32px | [fill in] |-| Card padding | 20-32px | [fill in] |-| Card border radius | 8-16px | [fill in] |-| Single-row card height | 530-600px | [fill in] |-| Double-row card height | 265-295px each | [fill in] |-| Three-column card width | 360-380px each | [fill in] |--**Non-card containers** (naked text blocks / full-bleed imagery / divider-separated content — typical for `breathing` pages or minimalist designs):--- Vertical rhythm carried by **whitespace**, not gutters — block gaps run wider than card gaps since there's no container edge to separate content.-- **Line-height**: ~1.4–1.5× for dense/small-body text (CLReq comfortable minimum); 1.6–2.0× for large-type, sparse, or `breathing` pages.-- **Full-bleed text placement**: inset text away from the image's focal points; legibility over photographic backgrounds typically needs a gradient or opacity overlay.-- **Content width** is driven by reading comfort and image composition, not a card grid slot — don't back-compute "column width" when there's no column.+The command refuses to shadow any recognized existing design-spec artifact, including legacy filenames. Re-running it in an otherwise equivalent empty project produces the same bytes.----## VI. Icon Usage Specification--### Source--- **Built-in icon library**: `templates/icons/` (11,600+ icons across five libraries; see `templates/icons/README.md`)-- **Usage method**: SVG placeholder `<use data-icon="library/icon-name" .../>`; Design Spec should list approved `library/icon-name` entries for Executor.+## 2. Section contract-### Recommended Icon List (fill as needed)+| Section | Required content | Conditional content |+| --- | --- | --- |+| I. Project Information | Project and confirmed communication context | Template reuse rows only when a template workspace is active |+| II. Canvas Specification | Format, dimensions, viewBox, margins | — |+| III. Visual Theme | Mode, visual style, colors | `### AI Image Strategy` when §VIII contains an `ai` row |+| IV. Typography System | Per-role stacks and locked size slots | Additional recurring roles when used |+| V. Layout Principles | Page regions and project spacing | Template-specific constraints only when active |+| VI. Icon Usage Specification | Approved icon inventory | Empty table when no icons are used |+| VII. Visualization Reference List | Selected candidates or an empty table | Only pages with visualization work |+| VIII. Image Resource List | Image acquisition and placement rows or an empty table | AI-only columns apply to `ai` rows |+| IX. Content Outline | Ordered Slide blocks; each has `Audience move` | Page-specific facts, charts, images, and template mappings |+| X. Speaker Notes Requirements | Filename and content policy | — |-| Purpose | Icon Path | Page |-| ------- | --------- | ---- |-| [example] | `chunk-filled/circle-checkmark` | Slide XX |+**Hard rule**: Keep all ten `##` headings, even when §VII or §VIII contains no rows. Do not add a second schema description inside the project artifact.----## VII. Visualization Reference List (if needed)--> When pages map to a chart-library template (data charts OR structural patterns — team rosters, agendas, frameworks, etc.), Strategist lists them here for Executor reference. Single combined table — `summary-quote` column is the anti-fabrication audit, `path` + `usage` columns serve Executor lookup.--Catalog read: 76 templates--| Page | Template | Path | Summary-quote (verbatim from `charts_index.json`) | Usage |-| ---- | -------- | ---- | ------------------------------------------------- | ----- |-| P05 | grouped_bar_chart | `templates/charts/grouped_bar_chart.svg` | "Pick for 2-4 series side-by-side across the same categories (e.g. YoY/QoQ). Skip if showing composition within each category (use stacked_bar_chart)." | YoY revenue comparison by product line |+## 3. Machine validation-**Runners-up considered** (3 entries minimum, drawn from real second-best matches in this deck):--- `<key_A>` | rejected for P05: `<reason citing this deck's specifics>`-- `<key_B>` | rejected for P##: `<reason>`-- `<key_C>` | rejected for P##: `<reason>`+```bash+python3 skills/ppt-master/scripts/project_manager.py validate <project_path>+```-> **Audit rule**: `Summary-quote` must be copy-pasted verbatim — paraphrasing breaks the audit. Every template name listed must `grep` cleanly inside `charts_index.json` (so misspellings/inventions fail). If fewer than 3 viz pages exist, list what exists and note "fewer than 3 viz pages"; runners-up still required for each page that does exist.+Validation reads the Markdown directly. It reports missing or out-of-order I–X sections, unresolved `[fill...]` scaffold placeholders, missing per-slide `Audience move`, and a missing §III `AI Image Strategy` when an §VIII table selects `ai` acquisition.-> **Native-preset candidates → append to `Usage`**: for a page already in this list, when its content calls for a literal stock PowerPoint shape (chevron, block arrow, standard flowchart node, callout, banner, star — judged from the page plan, not a template's name), append a candidate note to that page's `Usage`, e.g. `…usage…; native-preset candidate: chevron; Executor applies executor-base §3.0`. The Executor still selects the exact preset, frame, and paint. See [`strategist.md`](../references/strategist.md) Template Match.+The schema owns structure only. Strategist role modules own field meaning, recommendation logic, page planning, image policy, and template policy. `spec_lock.md` owns the compact execution values; on divergence, the lock wins.----## VIII. Image Resource List (if needed)--| Filename | Dimensions | Ratio | Purpose | Type | Layout pattern | Acquire Via | Status | Reference | text_policy | page_role |-| -------- | --------- | ----- | ------- | ---- | -------------- | ----------- | ------ | --------- | ----------- | --------- |-| cover_bg.png | {canvas_info['dimensions']} | [ratio] | Atmospheric cover backdrop — SVG title overlays the calm region | Background | #1 full-bleed background with floating title + #29 two-stop scrim | ai | Pending | [subject + intent + composition, no style/HEX] | none | hero_page |-| comparison_p07.png | {canvas_info['dimensions']} | [ratio] | Three-panel approach comparison — panel labels stay inside the image | Diagram | #44 background image + native network/architecture diagram | ai | Pending | Three side-by-side schematic motifs comparing approach A / B / C, panel labels rendered inside each motif | embedded | local |-| formula_001.png | [actual dimensions from formula manifest / image_analysis] | [ratio] | Block equation on P03 | Latex Formula | formula-block | formula | Rendered | `E = mc^2` — energy-mass equation | | |--> **Layout pattern column is MANDATORY** — for non-formula rows, value is one or more `#<id> <name>` joined by ` + ` drawn verbatim from [`references/image-layout-patterns.md`](../references/image-layout-patterns.md) (Primary + optional Modifiers). Empty cells, paraphrased names, or invented ids invalidate the row. Formula rows are the only exception; use `formula-inline` or `formula-block`. See `strategist.md §h` GATE for the three-layer requirement (read → produce → image-as-canvas coverage).--**Type** (free-form category tag; common values):--- `Background` — cover / chapter / full-bleed atmosphere-- `Photography` — real-world photo-- `Illustration` — vector / flat / painterly art-- `Illustration Sheet` — a grid of several spot illustrations generated as one image to be sliced (the `ai` sheet row of a `slice` set; never placed itself)-- `Diagram` — schematic / architecture / flowchart-- `Portrait` — single-subject person-- `Latex Formula` — formula PNG rendered by `latex_render.py`--**Status**:--- **Pending** — needs AI generation or web sourcing-- **Rendered** — deterministic formula asset already exists under `images/`-- **Existing** — user-supplied, place in `images/`-- **Placeholder** — not yet processed, use dashed border in SVG--**Acquire Via**:--- `ai` — Step 5 Image_Generator-- `web` — Step 5 Image_Searcher-- `formula` — already rendered by `latex_render.py` before this spec was written-- `user` — user-supplied-- `placeholder` — intentionally deferred-- `slice` — a spot-illustration element derived in Step 5 by cutting it out of an `ai` sheet row (not generated on its own)--> **Spot-illustration sheets (`slice`).** When the deck draws several same-family spot illustrations from one generated sheet (see [`image-generator.md`](../references/image-generator.md) §4.3), write **two kinds of rows**: one **sheet row** (`Acquire Via: ai`, `Type: Illustration Sheet`, name the intended cell shape + placement purpose in `Reference`, e.g. `portrait side-accent spot set` or `landscape footer-vignette spot set`) that is generated but **never placed** — keep it out of `spec_lock.md images`; and one **element row per used element** (`Acquire Via: slice`, `Reference` naming the parent sheet + cell/element, dimensions filled after slicing) that **is** placed — list every element row in `spec_lock.md images` so the Executor may reference it. Strategist states the shape intent; Image_Generator chooses the exact sheet ratio, grid, and slice command. An element row with no sheet row, or a sliced file absent from `spec_lock.md images`, is an invalid spec. **Each element row's Layout pattern must come from the decorative-cutout family** (`#63` sticker, `#4` edge bleed, `#58` corner fragment, `#66` fade-out, `#69` rotation, `#49` cluster) — a transparent spot is an accessory placed at the margins / off-edge / behind text, never centered in a boxed tile.--**text_policy** (`ai` rows only; AI judges per row, no global default bias):+## 4. Minimal filled shape-- `none` — image carries no text; SVG overlays all labels-- `embedded` — image contains in-artwork text: decorative lettering, a designed title, hand-lettered keywords, or stable visual identifiers (axis labels, subplot letters, unit symbols). Body copy / data points / long quotes never go inside the image regardless — they must stay editable. Embedded text is frozen into the raster, so the exact characters are named literally in the prompt--**page_role** (`ai` rows only; leave blank for default):--- *blank / `local`* — image is a region block on an SVG page-- `hero_page` — image is the page's main voice; SVG overlay is minimal or empty. Use on covers, chapter dividers, mood transitions, single-number data heroes, closing quotes. Same rendering and deck colors as the rest of the deck regardless+```markdown+## III. Visual Theme-**Reference grammar** (`ai` rows): write **subject + intent + composition** only. Do NOT repeat style words or HEX values—rendering is locked by `design_spec §III AI Image Strategy`, and colors by `§III Color Scheme`. Image_Generator injects both.+### Theme Style+- **Mode**: briefing+- **Visual style**: swiss-minimal----+### Color Scheme+| Role | HEX | Purpose |+| --- | --- | --- |+| Background | `#FFFFFF` | Canvas |## IX. Content Outline-> **Native Layout boundary**: Each `Layout` line below always describes visual composition intent. On free-design, brand-only, and `template_reuse_scope: style` routes, it does not create native Master/Layout identity: `spec_lock.md` uses `pptx_structure.mode: flat`, omits `pptx_masters` / `pptx_layouts` / `page_pptx_layouts` / `page_layouts`, and every SVG object stays Slide-local. Export materializes one clean project-owned Master plus one Blank Layout from the current lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. `template_reuse_scope: mirror|layout` uses `mode: structured`: Strategist writes each unique Master/Layout definition once, assigns every page through `page_pptx_layouts`, and selects its authoring prototype through `page_layouts`. Strict preserves the prototype contract. Adaptive keeps its Master and may define and assign a new Layout key during page authoring only when fixed Layout atoms or slot topology/bounds change. Mirror also preserves literal visuals and text-node topology; layout permits project-controlled reflow/re-skinning. Legacy prototypes are not selectable; create a current workspace through [`create-template`](../workflows/create-template.md) and generate new SVG pages from it. No deferred distillation or immediate-compatibility fallback exists.--### Part 1: [Chapter Name]--#### Slide 01 - Cover--- **Cover impact**: [MANDATORY — see strategist.md §6.2. Name one concrete hook (provocative core claim / hero number / object-scene metaphor / founder-product-audience moment / distilled conflict) + one composition strategy (full-bleed image + floating title / typographic poster / hero object / data hook / editorial scene / high-contrast abstract geometry / or a fresh one the subject suggests). This is the cover's spine — do NOT fall back to "title + subtitle + decorative background".]-- **Audience move**: [How this opening changes the audience's state — establish relevance, tension, urgency, trust, or the decision frame. It must advance the global Desired Audience Outcome.]-- **Layout**: [realize the Cover impact above; choose the composition that delivers it — not a default centered title block]-- **Title**: [Main title]-- **Subtitle**: [Subtitle]-- **Info**: [Author / Date / Organization]--#### Slide 02 - [Page Name]--- **Layout**: [Choose a pattern from §V, combine two, or break the grid as the content demands]-- **Title**: [Page title]-- **Core message**: [the one thing this page exists to land — its spine, always phrased as one assertion sentence (prose by nature). One per page; can't name it → merge or cut the page.]-- **Audience move**: [the specific transition this page causes — e.g. unaware → aware, confused → understands cause, undecided → sees the trade-off, aligned → owns the next step. Must advance at least one purpose in the global Communication Intent.]-- **Fact IDs**: [stable IDs from `sources/*.facts.json` used on this page, e.g. `F001, F004`; omit when none]-- **Data class**: [`external` for sourced facts / `scenario` for invented demo KPIs, targets, internal ratios; identify the affected values when scenario; omit when the page has no factual/quantitative claims]-- **Visualization**: [visualization_type] (see VII. Visualization Reference List)-- **Content**: write each block in the phrasing that fits it (prose / bullet / keyword / … any phrasing the content calls for) and write it already in that mode, so the texture itself carries the intent — a prose block reads as a real sentence, not a fragment. One page may mix modes; blocks still sit under the core message, never replace it:- - [a connected sentence or two that argues the point]- - [parallel fragment] · [parallel fragment] · [parallel fragment]- - [label] / [label] / [label]--> **Visualization field**: add only when the page has data visualization or structured infographic elements. Type must be listed in §VII.-------[Strategist continues adding more pages based on source document content and page count planning...]-------#### Slide NN - Closing *(only if the deck genuinely lands on a conclusion / CTA / final-takeaway page — do NOT invent one to fill this slot; see strategist.md §6.2)*--- **Closing impact**: [MANDATORY for the closing page — name the one thing the audience leaves with (distilled takeaway / forward call / memorable restatement of the core claim) + one composition that lands it. Do NOT write a generic "Thank you" / contact-only / centered-title reprise of the cover.]-- **Audience move**: [the final transition or commitment that completes the Desired Audience Outcome.]-- **Layout**: [realize the Closing impact above — the deck's final impression, not a default sign-off]-- **Content**: [the takeaway / call-to-action itself, phrased to land]-------## X. Speaker Notes Requirements--One speaker note file per page, saved to `notes/`:+#### Slide 01 - Decision frame+- **Audience move**: undecided → understands the decision+- **Layout**: claim + evidence+- **Title**: Choose the funded path+```-- **Filename**: match SVG name (e.g., `01_cover.md`)-- **Content**: script key points, timing cues, transition phrases+Use the scaffold for the complete shape; this excerpt is not a second template.diff --git a/skills/ppt-master/templates/layouts/README.md b/skills/ppt-master/templates/layouts/README.mdindex 97731287..57f68305 100644--- a/skills/ppt-master/templates/layouts/README.md+++ b/skills/ppt-master/templates/layouts/README.md@@ -140,4 +140,5 @@ omitted.4. In library scope, register with `register_template.py <id> --kind layout`.General SVG/PPT rules remain authoritative in-[`shared-standards.md`](../../references/shared-standards.md).+[`shared-standards-core.md`](../../references/shared-standards-core.md) and+[`pptx-structure-interface.md`](../../references/pptx-structure-interface.md).diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.mdindex 17a6231b..043d608a 100644--- a/skills/ppt-master/templates/spec_lock_reference.md+++ b/skills/ppt-master/templates/spec_lock_reference.md@@ -1,234 +1,93 @@-# Execution Lock--> **⚠️ Skeleton for Strategist — do NOT copy verbatim into a project.** When producing `<project_path>/spec_lock.md`, emit only `##` sections with filled-in `-` data lines. Do NOT carry over any `>` blockquote guidance, HARD-rule notes, or override examples — those are author-time guidance, not runtime data. Every output line must be parseable data.->-> Machine-readable execution contract. Executor MUST `read_file` this before every SVG page. Values not listed here must NOT appear in SVGs. The compact communication section keeps every page aligned with why the deck exists; fuller rationale remains in `design_spec.md`.->-> After SVG generation begins, this is the canonical source for color / font / icon / image values. Supported color/font modifications should go through `scripts/update_spec.py` to keep this file and generated SVGs in sync. Canvas changes are intentionally not bulk-rewritten by that tool.--## canvas-- viewBox: 0 0 1280 720-- format: PPT 16:9--> Strategist: fill viewBox and format for the chosen canvas. New authoring uses the canonical `0 0 W H` spelling with positive integer pixels. Every generated page and internal Layout prototype must match this numeric canvas. Common values: `0 0 1280 720` (PPT 16:9), `0 0 1024 768` (PPT 4:3), `0 0 1242 1660` (Xiaohongshu), `0 0 1080 1080` (WeChat Moments), `0 0 1080 1920` (Story). Changing the canvas after authoring starts requires re-authoring and re-validating affected SVGs; `update_spec.py` does not propagate canvas changes.--## communication-- audience: Executive committee with finance and product leads-- communication_intent: Report progress and expose delivery risk first; then obtain a decision on the next investment-- audience_outcome: The committee can compare the options, accepts the risk framing, and chooses one funded path-- core_message: Fund option B now because it protects the launch date at an acceptable incremental cost-- delivery_context: Presenter-led 20-minute leadership review; recording and deck shared afterward-- artifact_afterlife: Approval record, project hand-off reference, and quarterly audit trail-- consumption_mode: balanced--> Strategist: copy the confirmed Stage-1 prose plus Stage-2 reading mode. All keys above remain present; any Stage-1 prose value may be empty after explicit confirmation. Do not restore recommendation text into an empty value. `communication_intent` is open prose and may preserve several purposes plus priority / sequence; never replace it with one enum label. `consumption_mode` is the canonical execution name for the Confirm UI compatibility key `delivery_purpose`; use `text` / `balanced` / `presentation` on PPT canvases and omit it on non-PPT canvases. It is an execution constraint on page grammar, granularity, density / rhythm, and note burden—not a font-size label. Typography sizes remain separately locked below. Do not copy `content_divergence` here—its effect is already authored into §IX. Executor checks this global contract against every page's `Audience move`.--## mode-- mode: pyramid--> Strategist: the deck's narrative skeleton, locked at confirmation `d` Layer 1. One of `pyramid` / `narrative` / `instructional` / `showcase` / `briefing` — see [`references/modes/_index.md`](../references/modes/_index.md). Executor reads only the locked mode's file. Deck-wide. Or the literal `custom` for a bespoke direction no preset captures (a special cadence, a multi-mode fusion, a particular posture) — user-requested or Strategist-recommended (user confirms, like every lock). Then add a sibling `- mode_behavior:` paragraph (how the argument advances, title voice, page rhythm, register) that the Executor follows in place of a preset file. One deck locks one value; don't default to `custom` when a preset fits.--## visual_style-- visual_style: swiss-minimal--> Strategist: the deck's visual aesthetic, locked at confirmation `d` Layer 2. A preset name from [`references/visual-styles/_index.md`](../references/visual-styles/_index.md), **or** the literal `custom`. Reference intent (shape / decoration / whitespace / texture) — **not a whitelist**, and **carries no HEX** (color truth stays in `colors`). Executor reads only the locked style's file.->-> **`custom`** — add a sibling `- visual_style_behavior:` row with a one-paragraph aesthetic description (shape language, decoration density, whitespace, typographic character, texture); no HEX, no color names. Tail-case, not a default.--## colors-- bg: #FFFFFF-- primary: #......-- accent: #......-- secondary_accent: #......-- text: #......-- text_secondary: #......-- border: #......-- image_rendering: vector-illustration--> Strategist: fill only colors actually used. Add extra rows as needed; delete unused rows rather than leave as `#......`.->-> **PowerPoint theme roles.** Flat and structured export map `bg` / `background` / `master_bg` → `lt1`, `secondary_bg` / `bg_secondary` → `lt2`, `text` / `body_text` → `dk1`, `text_secondary` → `dk2`, `primary` → `accent1`, `accent` → `accent2`, `secondary_accent` → `accent3`, and `border` → `accent4`. The first two additional non-black/non-white roles become `accent5` / `accent6`; remaining colors stay fixed. Mapping is usage-aware, so a background HEX is not automatically reused for inverse text.->-> **`image_rendering`** — required only when `images` below contains `ai`-sourced files. It is a valid name from `references/image-renderings/_index.md`, or the literal `custom`. Image_Generator applies it deck-wide and derives image color instructions directly from the ordinary color-role rows above. Omit it when the deck has no AI-generated images. An existing lock that omits this active key uses the declared inference in [`image-generator.md`](../references/image-generator.md) §3 Step 2. A missing whole lock stops at the Step 5 gate. New flows never author an independent `image_palette`; the current generation flow ignores a historical row, which cannot override these HEX roles.->-> **`custom` escape hatch.** When set to `custom`, add `image_rendering_behavior` with a one-paragraph description. Image_Generator splices it into the prompt in place of the preset rendering snippet. Tail-case only—see [`image-renderings/_index.md`](../references/image-renderings/_index.md) §1.5.->-> ```-> - image_rendering: custom-> - image_rendering_behavior: "Hand-screened poster aesthetic — slightly misregistered halftone overlays, 3 flat ink colors with visible dot pattern at 12% opacity, no gradients, no anti-aliased edges; reads as silkscreen print."-> ```--## typography-- font_family: "Microsoft YaHei", Arial, sans-serif-- title_family: Georgia, SimSun, serif-- body_family: "Microsoft YaHei", "PingFang SC", Arial, sans-serif-- emphasis_family: Georgia, SimSun, serif-- code_family: Consolas, "Courier New", monospace-- body: 24-- title: 42-- subtitle: 32-- annotation: 18-- footnote: 16--> **All five family lines are listed explicitly** so Strategist considers every role — `code_family` and `emphasis_family` are easily forgotten. In a real `spec_lock.md`:-> - Keep any `*_family` whose role genuinely differs from `font_family`.-> - **Omit** any `*_family` equal to `font_family` — Executor falls back to `font_family` for missing roles, so writing it twice is noise. (Exception: keep `code_family` even when equal — monospace is conceptually distinct.)-> - `code_family` applies to code snippets only. LaTeX formulas rendered by `latex_render.py` are PNG image assets and must be listed under `images`.->-> `font_family` is required and is the default fallback for omitted role-specific families. Every declared family is a CSS font-stack string.->-> **Source**: copy verbatim from the *Per-role font stacks* list in `design_spec.md §IV Font Plan`. Stack **order** encodes browser-rendering intent (Latin-led vs. CJK-led) that the breakdown table cannot — strings here must match character-for-character. See `design_spec.md §IV` for the explainer.->-> Sizes (`body` / `title` / etc.) are **unitless px numbers** — the execution unit and the same values recorded in `design_spec.md §IV`. The system is px-only on every canvas: there is no pt layer and no conversion — the confirmed value is already px (e.g. `balanced` body `24`, title `42`, subtitle `32`, annotation `18`, footnote `16` — clean even px). Do not write `pt` / `px` / `em` or any unit. `body` is the **required baseline anchor** — all other sizes derive as clean-even ratios of it (ramp table: `design_spec_reference.md §IV`).->-> **Size slots are anchors, not a closed menu.** Common slots (`title` / `subtitle` / `annotation`) cover frequent cases. Add role-specific slots (e.g. `cover_title: 88`, `hero_number: 56`, `subheading: 32`, `lead: 30`, `footnote: 16`, `chart_annotation: 16`) for the roles the deck actually uses — common for cover-heavy decks, consulting-style hero numbers, dense pages. **Mandatory — scan `§IX` and declare a slot for every role that recurs across pages, not just the four defaults.** A report / `text`-mode deck almost always recurs a per-page **core-message / lead line** and **page numbers / source credits / footnotes** → declare `lead` and `footnote` for them. `subheading` and `lead` sit between `subtitle` and `body` (their bands overlap `subtitle`) — pick by role, not size — and the core-message `lead` is a **primary** line, **always ≥ `body`**, never smaller. Leaving a recurring lead / footnote undeclared forces the Executor to improvise an unlocked size (and a core line improvised below `body` inverts the hierarchy). **Structural roles (title / body / subtitle / annotation / footnote) render at their locked size on every page — one role, one size, deck-wide.** Intermediate in-band sizes are for special / feature elements only (hero number, display title, one-off emphasis); declare a recurring one as its own slot so it stays consistent too.->-> **Generated Master defaults**: `pptx_structure.mode: flat` and `mode: structured` require unitless `title` and `body`. Native export writes `title` into every generated Master `titleStyle` default and derives a deterministic nine-level, non-increasing size hierarchy from `body` for `bodyStyle` / `otherStyle`. It changes only each level's `a:defRPr@sz`, preserving indentation, bullets, and paragraph settings. Direct page-run sizes and role-specific structured-Layout placeholder prototype sizes remain unchanged.->-> **⚠️ PPT-safe stack discipline (HARD rule).** Flat and structured export map `title_family` to the PowerPoint theme major font and `body_family` (or `font_family`) to the theme minor font. Runs whose resolved face matches either role use `+mj-*` / `+mn-*` theme tokens; other role families remain concrete per-run typefaces. Every exported Latin / EA face MUST therefore resolve to cross-platform pre-installed fonts: `"Microsoft YaHei"` / `SimSun` / `Arial` / `"Times New Roman"` / `Consolas`. Stacks that resolve to non-preinstalled typefaces (Inter / Google Fonts / brand typefaces) may be used only when the Design Spec notes the font-install or embedding requirement.->-> **Stack length discipline.** 3-4 fonts per stack is the sweet spot. Converter only writes the **first** Latin and **first** CJK font into PPTX — everything after is silently dropped. macOS-only families (`Songti SC`, `Menlo`, `Monaco`, `Helvetica`) are auto-mapped to Windows equivalents via `FONT_FALLBACK_WIN` (see `scripts/svg_to_pptx/drawingml/utils.py`); stacking both is redundant. Lead with Windows-preinstalled fonts (`Microsoft YaHei` / `SimSun` / `Arial` / `Georgia` / `Consolas`); keep at most **one** macOS-exclusive family (typically `"PingFang SC"`) as a browser-preview nicety.--## icons-- library: chunk-filled-- brand_library: simple-icons-- inventory: target, bolt, shield, users, chart-bar, lightbulb--> `library` MUST be exactly one of `chunk-filled` / `tabler-filled` / `tabler-outline` / `phosphor-duotone` — mixing is forbidden. `brand_library: simple-icons` is optional; include only when the deck uses real company / product brand marks, otherwise omit. `inventory` lists approved icon names (no library prefix); Executor may only use icons from this list. Names are case-sensitive filenames: bundled-library inventory values are the exact verified lowercase basenames (`award`, never `Award`); custom icon names preserve the custom file's exact case.->-> **`stroke_width` (stroke-style libraries only)** — required in every new lock when `library` is stroke-based (currently `tabler-outline`); allowed values `1.5` / `2` / `3`. Executor MUST apply this value to every `<use data-icon="...">` placeholder via `stroke-width`, deck-wide. An existing lock that omits the active field follows the fixed compatibility rule in [`executor-base.md`](../references/executor-base.md) §4. Omit for non-stroke libraries (`chunk-filled` / `tabler-filled` / `phosphor-duotone`) — ignored there. For heavier weight switch library; do not exceed `3` (at 24×24 strokes merge and the icon stops reading as line art).->-> Example for stroke-style libraries:-> ```-> - library: tabler-outline-> - stroke_width: 2-> - inventory: home, chart-bar, users, bulb-> ```--## images-- cover_bg: images/cover_bg.jpg-- q3_revenue_chart: images/q3_revenue.png | no-crop-- formula_001: images/formula_001.png | no-crop--> One entry per image file used. Append ` | no-crop` only for images that must not lose pixels (data screenshots, charts, certificates, rendered LaTeX formulas) — Executor will size the container to native ratio and use `preserveAspectRatio="xMidYMid meet"`. Untagged entries default to croppable (`slice`). Remove the section entirely if no images.--## page_rhythm-- P01: anchor-- P02: dense-- P03: breathing-- P04: dense-- P05: dense-- P06: breathing-- P07: anchor--> One entry per page. Key: `P<NN>` (zero-padded, matching `§IX Content Outline` in `design_spec.md`). Value: one of the three rhythm tags. Executor reads per page and applies the tag's layout discipline — breaks the "every page looks the same" pattern.->-> **Vocabulary** (exactly these three values):-> - `anchor` — Structural pages (cover / chapter opener / TOC / ending). Follow the template as-is.-> - `dense` — Information-heavy pages (data, KPIs, comparisons, multi-point lists). Card grids, multi-column layouts, tables, charts all permitted.-> - `breathing` — Low-density pages (single concept, hero quote, big image + caption, section transition). Avoid **multi-card grid layouts** (multiple parallel rounded containers as the primary structure); organize via naked text, dividers, whitespace, or full-bleed imagery. Single rounded elements (hero image corners, callouts, tags, one emphasis block) are fine. Proportions follow information weight — not a preset ratio menu.->-> **Rhythm follows narrative**: `breathing` pages appear where narrative genuinely pauses — section transitions, a single argument worth standalone emphasis, a deliberate stop after a dense sequence. A data briefing or consulting analysis may legitimately be nearly all `dense` — **do not invent filler pages** to pad rhythm. Validation: every `breathing` page must answer "what independent thing is this page saying?".->-> **Missing or empty section — compatibility fallback** → follow the fixed default owned by [`executor-base.md`](../references/executor-base.md) §2.1. New authoring MUST fill the section.--## pptx_structure-- mode: flat--> One deck-wide native PowerPoint structure policy. Free-design, brand-only, and template style-reference routes use `flat`; template layout/mirror routes use `structured`.->-> `flat` keeps every SVG object Slide-local. Export materializes one clean project-owned Master plus one Blank Layout, maps the current color/typography lock into the theme and Master defaults, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks. In this mode, omit `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`, and do not add root Master/Layout identity, `data-pptx-layer`, or `data-pptx-placeholder*` metadata to generated pages.->-> When a loaded deck/layout template is used only as a visual-style reference, write:-> ```-> - mode: flat-> - template_reuse_scope: style-> ```-> `style` may retain template-derived color/typography/decoration values elsewhere in this lock, but it MUST omit `template_adherence` and every structured mapping.->-> For layout-system reuse, replace the `flat` row above with:-> ```-> - mode: structured-> - template_reuse_scope: layout-> - template_adherence: adaptive-> ```-> Use `strict` instead of `adaptive` when the selected Layout contract cannot change. For literal page replacement from a mirror-capable workspace, write:-> ```-> - mode: structured-> - template_reuse_scope: mirror-> - template_adherence: strict-> ```-> `mirror` is legal only when the installed template frontmatter declares `replication_mode: mirror`; it preserves literal visuals and the complete `<text>` / `<tspan>` topology while replacing visible values. Both `layout` and `mirror` require complete `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts` sections. Existing legacy template SVGs that lack the current root Master identity, grouped slot/carrier contract, or positive bounds cannot be selected or upgraded in place. Create a current workspace through [`create-template`](../workflows/create-template.md), then generate new structured pages from it.+# Execution Lock Structure+`spec_lock.md` is a compact Markdown data contract. Its machine contract is [`schemas/spec_lock.schema.json`](./schemas/spec_lock.schema.json); authoring starts from [`scaffolds/spec_lock.md`](./scaffolds/spec_lock.md).++## 1. Create the artifact++Run the scaffold command once, then fill or remove placeholder data lines:++```bash+python3 skills/ppt-master/scripts/project_manager.py scaffold-lock <project_path>+```++The command refuses to overwrite an existing `spec_lock.md`. Re-running it with the same project metadata produces the same bytes.++**Hard rule**: A project lock contains only `##` sections and `- key: value` data lines, except `## forbidden`, whose list items are literal rules. Do not copy guidance paragraphs into the lock.++---++## 2. Base sections++| Section | Required keys | Notes |+| --- | --- | --- |+| `canvas` | `viewBox`, `format` | `format` is the canonical display name (for example `PPT 16:9`); `viewBox` is the matching exact geometry |+| `communication` | `audience`, `communication_intent`, `audience_outcome`, `core_message`, `delivery_context`, `artifact_afterlife` | Values may be empty after explicit confirmation; `consumption_mode` is optional off PPT canvases |+| `mode` | `mode` | Preset or `custom` |+| `visual_style` | `visual_style` | Preset or `custom` |+| `colors` | Used color roles | `image_rendering` appears only for AI images |+| `typography` | `font_family`, `body`, `title` | Sizes are unitless numbers |+| `icons` | `library`, `inventory` | `stroke_width` is conditional |+| `page_rhythm` | One `P<NN>` row per page | Values: `anchor`, `dense`, `breathing` |+| `pptx_structure` | `mode` | Values: `flat`, `structured` |+| `forbidden` | Literal list items | General standards stay in their owning reference |++Optional data sections: `images`, `page_charts`.++---++## 3. Conditional sections and fields++| Trigger | Required addition |+| --- | --- |+| `mode.mode: custom` | `mode_behavior` in `mode` |+| `visual_style.visual_style: custom` | `visual_style_behavior` in `visual_style` |+| `colors.image_rendering: custom` | `image_rendering_behavior` in `colors` |+| `icons.library: tabler-outline` | `stroke_width: 1.5`, `2`, or `3` |+| `pptx_structure.mode: structured` | `template_reuse_scope: layout\|mirror`, `template_adherence`, plus `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts` |+| `pptx_structure.template_reuse_scope: mirror` | `mode: structured` and `template_adherence: strict` |+| `pptx_structure.template_reuse_scope: style` | `mode: flat`; omit structured mapping sections |+| `pptx_structure.mode: flat` | Omit all four structured mapping sections |++Structured section value shapes:++```markdown## pptx_masters- master-default: Default Master-> Structured `template_reuse_scope: mirror|layout` routes only. One row per Master: `<master_key>: <PowerPoint picker name>`. A key contains 1–64 ASCII letters, digits, dots, underscores, or hyphens; its first character is a letter or digit. Spaces belong only in the PowerPoint picker name, never in the key. Keys are deck-unique and stable. Omit this entire section when `pptx_structure.mode: flat`.-## pptx_layouts-- cover-hero-split: master-default | Cover — Hero Split | template:01_cover-- kpi-band-trio: master-default | KPI Band Trio | P02-- content-two-column: master-default | Two Column | template:03a_content_abstract-- quote-focus: master-default | Quote Focus | template:04_quote_focus--> Structured `template_reuse_scope: mirror|layout` routes only. This is the unique reusable Layout roster, not a page roster. Layout keys use the same grammar as Master keys. Value format: `<master_key> | <PowerPoint layout name> | <prototype source>`. Supply all three non-empty fields separated by `|`. A prototype source is either `P<NN>` for one generated page carrying that exact Layout contract, or `template:<basename>` for an installed `templates/<basename>.svg`; the `template:` prefix is required, so a bare basename is invalid. Omit this section when `pptx_structure.mode: flat`.->-> Every Layout key appears exactly once, belongs to exactly one declared Master, and is globally unique even when two Masters use the same picker name. Every declared Master owns at least one Layout definition. A Layout may remain unused by generated pages; such a Layout must use `template:<basename>` so export can register it without manufacturing a published slide.->-> The definition prototype repeats its identity through root `data-pptx-master`, `data-pptx-master-name`, `data-pptx-layout`, and `data-pptx-layout-name`. Strategist plans the initial roster. If adaptive use genuinely changes reusable framing or slot topology/bounds, Executor adds a new definition and updates the page assignment immediately; never mutate a reused key silently.->-> Reuse one `(master_key, layout_key)` only when its ordered Layout atoms and slot ids/types/indices/bounds/binding modes are identical. Current text, imagery, crop, or Slide-local geometry does not define Layout identity.->-> **Different reusable composition → different key.** Name keys after the composition (`timeline-spine`, `kpi-band-trio`), never after PowerPoint stock roles or page topics. Distinct compositions collapsing into stock-role keys (`title-content` for eight different pages) and one shared skeleton splitting into per-topic keys (`allocation-fengqing` / `allocation-luoping` over identical framing) both produce Layout rosters that do not match the deck; the quality checker flags the second as duplicate Layouts.->-> A Layout may have zero slots. Do not create an empty `utility` kind or a full-page fake `object` slot; the named Layout and its fixed atoms are sufficient.+- content-two-column: master-default | Two Column | template:03_content## page_pptx_layouts-- P01: cover-hero-split-- P02: kpi-band-trio-- P03: content-two-column-- P04: content-two-column--> Structured `template_reuse_scope: mirror|layout` routes only. Include exactly one row per generated page. The value is one key declared in `pptx_layouts`; Master and picker name come from that unique definition and are not repeated per page. The generated SVG root must match the assigned definition. Omit this section when `pptx_structure.mode: flat`.+- P01: content-two-column## page_layouts-- P01: 01_cover-- P03: 02a_chapter-- P04: 03a_content_abstract--> For `template_reuse_scope: mirror|layout`, include one entry per page. Key: `P<NN>` matching §IX. Value: the template SVG basename without extension. This is the authoring-input prototype mapping; `page_pptx_layouts` is the output page assignment, while `pptx_layouts` defines the unique reusable roster. Strict preserves the prototype Master/Layout/slot contract. Adaptive retains its Master contract and may explicitly define and assign a new Layout key while authoring. `layout` skin follows the project lock; `mirror` preserves literal visual/text topology.->-> **No entry for a page** is an error in structured template mode.->-> **Hard rule**: Use both `page_layouts` and `page_charts` only with a compatible shell. Adaptive mode may start from a neutral content template and finalize a new explicit Layout after design; strict mode must choose an existing compatible Layout or revise the outline.->-> **Whole section omitted** → required for free-design, brand-only, and `template_reuse_scope: style` flat routes. `mirror` / `layout` strict/adaptive routes require complete `page_layouts`. A legacy package that cannot satisfy the current structured contract must migrate before use; it never enters a compatibility branch inside normal generation.->-> **Strategist source**: record each project-page choice in project `design_spec.md §IX Content Outline`, using the copied template package's `templates/design_spec.md §V Page Roster` descriptions as the roster authority. Basenames must match files in `templates/` exactly. A typo is a blocking contract error: stop before drawing and report it; never fall back to free design inside template mode.--## page_charts-- P05: column_chart-- P09: timeline_horizontal-- P12: quadrant_bubble_scatter--> One entry per page **that adapts a `templates/charts/` chart template**. Key: `P<NN>` matching §IX. Value: chart template basename without `.svg` (must match a key in `templates/charts/charts_index.json`).->-> **No entry for a page** → no chart on that page (or a chart that did not match any catalog template — Strategist's `no-template-match` fallback). Both cases mean Executor designs the visualization from scratch per `design_spec.md §VII`.->-> **Whole section omitted** → no data-visualization pages in this deck.->-> **Strategist source**: copy from `design_spec.md §VII Visualization Reference List` — only the rows whose `reference template path` points to a `templates/charts/` file. Pages marked `no-template-match` in §VII MUST NOT appear here.--## forbidden-- Mixing icon libraries-- `mask`, `<style>`, `class`, external CSS, `<foreignObject>`, `textPath`, `@font-face`, `<animate*>`, `<set>`, `<script>` / event attributes, `<iframe>`-- HTML named entities in text; write typography as raw Unicode and escape XML reserved characters--> **Execution reminder — not authoring authority**: the baseline blacklist above-> is intentionally terse. Add only deck-specific execution locks. General SVG-> required / forbidden / conditional rules are owned by-> [`shared-standards.md`](../references/shared-standards.md); do not copy its-> feature matrix or parameter contracts into `spec_lock.md`. In particular, do-> not move supported-but-non-default spellings such as `rgba()` or compatible-> `<g opacity>` into the generic forbidden list merely to enforce a generation-> preference; their checker warnings remain advisory.+- P01: 03_content+```++`page_charts` values must exist as keys in `charts/charts_index.json`; pages using the explicit `no-template-match` result do not appear there.++---++## 4. Field Grammar Index++- `font_family` grammar: one PPT-safe family name; role-specific families may extend it in the same section.+- `image_rendering` grammar: one catalog id, or `custom` with `image_rendering_behavior`.+- `stroke_width` grammar: `1.5`, `2`, or `3`; present only for `tabler-outline`.+- `page_rhythm` grammar: `P` + at least two digits (`P01`, `P100`) followed by `anchor|dense|breathing`.+- `page_charts` grammar: `P` + at least two digits followed by a `charts_index` key; the key and `<key>.svg` must both exist.+- `pptx_masters` grammar: `<master_key>: <PowerPoint picker name>`.+- `pptx_layouts` grammar: `<layout_key>: <master_key> | <PowerPoint layout name> | <prototype source>`.+- `page_pptx_layouts` grammar: `P` + at least two digits followed by a declared Layout key.+- `page_layouts` grammar: `P` + at least two digits followed by a template SVG basename.++---++## 5. Machine Validation++```bash+python3 skills/ppt-master/scripts/project_manager.py validate <project_path>+```++Validation reads the existing Markdown form. It reports unresolved `[fill...]` scaffold placeholders, wrong section or field casing, unknown sections or fields, illegal declared enums, malformed page keys, catalog keys without their corresponding SVG asset, broken structured-layout references, and unmet required / forbidden conditional sections. It does not rewrite the lock and is not an automatic generation gate.++Field meaning and selection logic stay in the owning Strategist modules. Executor branch references own consumption behavior. The schema owns only artifact grammar and structural conditions.diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.mdindex 9ac0ab11..6cfcf5f2 100644--- a/skills/ppt-master/workflows/create-template.md+++ b/skills/ppt-master/workflows/create-template.md@@ -575,7 +575,7 @@ Slide-local/slot object's initial authoring hash still matches. Fixed layers areunsupported or edited objects keep the current SVG fallback and are reportedrather than silently replaced by stale metadata. Do not reproduce the presetsyntax here; its single authority is-[`shared-standards.md`](../references/shared-standards.md), with selection and+[`shared-standards-core.md`](../references/shared-standards-core.md), with selection andusage guidance in the native-shape reference.Downstream, a mirror-created workspace supports three separately confirmed reuse scopes. `mirror` and `layout` use `pptx_structure.mode: structured`; `page_layouts` selects one complete authoring prototype per page, `pptx_masters` / `pptx_layouts` declare unique reusable definitions, and `page_pptx_layouts` assigns generated pages. Strict preserves the selected prototype contract. Adaptive keeps its Master and may explicitly create and assign a new Layout key/name while authoring the page that needs it. `mirror` additionally preserves literal visuals/text topology; `layout` allows project-controlled reflow/re-skinning. `style` uses `mode: flat` and takes only the workspace's design language. A retained Layout may remain unassigned while still registering through its definition SVG. No scope forces a future generated deck to keep the source page count or order.@@ -604,7 +604,7 @@ Mirror mode does not simplify the visual target or synthesize layer ownership. T**Expected outputs from this step** (full spec → [template-designer.md](../references/template-designer.md)):-1. `design_spec.md` — **package-specific rules only**. A deck writes an application-bearing Template Overview, Color Scheme, Signature Design Elements, and Page Roster with content policies; Typography / Assets / Placeholder Overrides are conditional. A layout writes only structure-owned Signature Design Elements and Page Roster; its frontmatter `summary` carries concise selection context, and it omits the deck-only Template Overview plus every identity section. The Page Roster must match the actual SVG files on disk. Declare portable brief frontmatter; `register_template.py` consumes it only in library scope. **Do not** restate generic SVG constraints, layout pattern libraries, font-size ratio bands, the canonical placeholder table, or content methodology — those are sourced from `shared-standards.md` / `design_spec_reference.md` / `strategist.md` and are already in the downstream reader's context. Full scope rule and skeleton: [template-designer.md §1](../references/template-designer.md#1-must-generate-design_specmd).+1. `design_spec.md` — **package-specific rules only**. A deck writes an application-bearing Template Overview, Color Scheme, Signature Design Elements, and Page Roster with content policies; Typography / Assets / Placeholder Overrides are conditional. A layout writes only structure-owned Signature Design Elements and Page Roster; its frontmatter `summary` carries concise selection context, and it omits the deck-only Template Overview plus every identity section. The Page Roster must match the actual SVG files on disk. Declare portable brief frontmatter; `register_template.py` consumes it only in library scope. **Do not** restate generic SVG constraints, layout pattern libraries, font-size ratio bands, the canonical placeholder table, or content methodology — those are sourced from `shared-standards-core.md` / `pptx-structure-interface.md` / `strategist.md` and are already in the downstream reader's context. Full scope rule and skeleton: [template-designer.md §1](../references/template-designer.md#1-must-generate-design_specmd).2. Page roster — see [Page Roster](../references/template-designer.md#page-roster) for `standard` / `fidelity` / `mirror` mode rosters, variant naming, and TOC handling3. Placeholder vocabulary — pages should adopt the conventional names (`{{TITLE}}`, `{{CONTENT_AREA}}`, ...) when they fit. Full reference: [Placeholder Reference](../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template). When a template style legitimately needs different vocabulary (consulting → `{{KEY_MESSAGE}}`, branded cover → `{{BRAND_LOGO}}`), declare a `placeholders:` block in `design_spec.md` frontmatter so the registrar and quality checker treat it as the template's authoritative contract. **Avoid** one-off indexed families such as `{{CHAPTER_01_TITLE}}` — use the indexed TOC pattern instead.- `{{...}}` placeholders are the authoring vocabulary used to generate final slide content. Each emitted SVG also carries the native structure contract: root Master/Layout key/name, direct atomic Master/Layout elements, and direct slot `<g>` elements with explicit design-zone bounds plus exactly one compatible carrier. A validated compact canonical authored-preset `<g>` counts as one semantic atom or one `object` carrier; ordinary groups do not. Composite regions use only the explicit `object` + `proxy` downgrade. Minimal structural `data-pptx-role` hints are added only when specialized metadata cannot express required behavior. Both strict and adaptive downstream set `mode: structured` and require complete `page_layouts`, `page_pptx_layouts`, `pptx_masters`, and `pptx_layouts` from planning onward.@@ -878,7 +878,7 @@ The next Generate PPTX Step 3 input is the exact `<template_workspace>/` root in## Notes-1. **SVG technical constraints**: See [shared-standards.md](../references/shared-standards.md) — do not restate them in the template's `design_spec.md`+1. **SVG technical constraints**: Create Layout/Create Deck load [shared-standards-core.md](../references/shared-standards-core.md) plus [pptx-structure-interface.md](../references/pptx-structure-interface.md), and load [svg-effects.md](../references/svg-effects.md) only when the authored design uses those effects. Create Brand authors no SVG and loads none of these SVG modules. Do not restate the contracts in the template's `design_spec.md`.2. **Color consistency**: Create Deck SVG files must use the same color scheme as `design_spec.md §II Color Scheme`; Create Layout owns no identity colors, and Create Brand owns no SVG files3. **Native-object mapping**: Treat Theme/Master/Layout/Placeholder as compiled PowerPoint objects, not template kinds. Layout owns topology and placement, Brand owns identity values/assets, and Deck adds the reusable application contract.4. **Placeholder convention**: `{{}}` format only; default names listed in [Placeholder Reference](../references/template-designer.md#4-placeholder-reference-canonical-convention-overridable-per-template). Override per template via `placeholders:` frontmatter when needed.diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex 2e7f67b1..2645258a 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -35,7 +35,7 @@ description: Generate PPTX route authority for source intake, planning, SVG auth| Main pipeline sequencing | This file | Owns Step 1–7 order, gates, role switching, and mandatory commands || Artifact ownership | [`artifact-ownership.md`](../references/artifact-ownership.md) | Owns fact channels, source/derived artifact boundaries, and regeneration rules || Failure recovery | [`failure-recovery.md`](./governance/failure-recovery.md) | Owns stop/continue policy and resume pointers |-| Confirm UI details | [`confirm_ui.md`](../scripts/docs/confirm_ui.md) | Owns schema, launcher behavior, port strategy, and chat fallback details |+| Confirm UI details | [`confirm_ui.md`](../scripts/docs/confirm_ui.md) | Owns the JSON schema, launcher behavior, staged-result contract, port strategy, and chat fallback details || Explicit template workspace | [`apply-template-workspace.md`](./stages/apply-template-workspace.md) | Owns Step 3 validation, installation, and fusion; load only when Step 3's explicit-path trigger fires |## Workflow@@ -140,12 +140,19 @@ Bare names, style descriptions, brand mentions, vague template intent, and silen🚧 **GATE**: Step 3 complete; default free-design path taken, or (if triggered) template files copied or confirmed in place in the project.-First, read the role definition:+First, read the role core, then only the modules triggered by the current plan:```Read references/strategist.md```-> ⚠️ **Mandatory gate**: before writing `design_spec.md`, Strategist MUST `read_file templates/design_spec_reference.md` and follow its full I–X section structure. See `strategist.md` Section 1.+| Deterministic trigger | Additional Strategist reference |+|---|---|+| Step 3 installed an explicit Brand/Layout/Deck workspace | `references/strategist-template.md` |+| The core's proposed Stage 2 `image_usage` contains a source other than `none`, the user supplied an explicit non-`none` image constraint, or formula-worthy content activates formula planning | `references/strategist-image.md` before authoring image renderings, production detail, formula resources, or §VIII |++The core first chooses the proposed Stage 2 source ids. Load the image module before writing Stage 2 whenever that proposal is non-`none`; after confirmation, keep it active only for confirmed non-`none` sources or an active formula plan. A confirmed `none` path with no formula work writes no image rows. Bare template names and style language do not load the template module.++> ⚠️ **Mandatory structure gate**: for new planning artifacts, create the versioned I–X and lock skeletons with `project_manager.py scaffold-spec` / `scaffold-lock`; do not reconstruct their grammar from memory. The commands and validator consume the machine contracts under `templates/schemas/`. The compact reference indexes are only for schema/scaffold troubleshooting, not the normal generation load.**Artifact ownership**: fact-channel and source/derived artifact boundaries are defined in [`references/artifact-ownership.md`](../references/artifact-ownership.md). This Step uses those ownership rules; it does not redefine them.@@ -153,96 +160,41 @@ Read references/strategist.md**Channel ownership — read each fact once from its owning channel.** In the main pipeline the **content contract is the content-type files in `sources/`** — primarily `<stem>.md`, but also any user-supplied content the import archived there: `.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml` (a `metrics.json` or `data.csv` may carry core content — judge by what the file holds). Text, tables, chart data values, and SmartArt node wording come from these (`ppt_to_md` transcribes native charts as Markdown tables and SmartArt nodes as hierarchical bullets). **Do NOT read pipeline sidecars in `sources/` as content**: `*.conversion_profile.json` (conversion audit) and `*_files/image_manifest.json` (asset index) are process metadata — open them only to audit a conversion or resolve assets, never as slide content. Converted-source originals archived in `sources/` (`.pdf` / `.pptx` / `.docx` / `.xlsx` / `.html` / `.epub` / `.tex` / `.rst` / `.ipynb` / `.typ`, etc.) are read via their converted `<stem>.md`, not scanned directly in the main pipeline. The `analysis/` chart / table / diagram entries are a **structural digest** for outline decisions (which slides carried charts, tables, or SmartArt; chart types / series names; SmartArt layout and hierarchy) — not a second copy of the content values; do NOT also pull chart values or SmartArt wording from `<stem>.slide_library.json` in the main pipeline. The `<stem>.slide_library.json` full structured data is owned by the direct-PPTX workflows: template-fill uses it as the native fill contract while preserving SmartArt unchanged; beautify uses it for native chart / table data and SmartArt relationships while keeping all wording from the Markdown.-**Strategist confirmation stage** (full template: `templates/design_spec_reference.md`):+**Confirmation orchestration**: field meaning and recommendation logic belong to the active Strategist modules; [`confirm_ui.md`](../scripts/docs/confirm_ui.md) owns the JSON schema, server lifecycle, staged-result contract, port behavior, and equivalent chat fallback.-⛔ **BLOCKING**: present the Strategist confirmation stage and **wait for explicit user confirmation or modification** before outputting Design Specification & Content Outline. This is the single core confirmation gate — once the final confirmation lands, all subsequent steps proceed automatically. The default Confirm UI delivers the gate in **three stages** (communication contract → complete deck solution → resources / production; see below); the chat fallback mirrors the same staged order.+⛔ **BLOCKING**: final confirmation is the single user gate before the planning artifacts are written. Stage 1 and Stage 2 are intermediate handoffs inside one uninterrupted agent turn; after either wait returns, immediately author the next stage without yielding or asking in chat. Each stage is authored once, and the user's submitted value—including an empty string or an unusual mix of overrides—is authoritative.-1. Communication contract — target audience; open-ended `communication_intent` (one or several purposes, with priority / sequence when useful); desired `audience_outcome`; `core_message` / decision ask / action; delivery context; artifact afterlife-2. Source-treatment intent — open-ended `content_divergence`; facts remain sourced at every level-3. Canvas format-4. Complete deck solution — reading mode (JSON compatibility key `delivery_purpose`); narrative mode; page count; visual / template direction; color; icons; typography; image sources and generated-image rendering-5. Production plan — conditional AI-image acquisition path; formula rendering policy; execution mode; optional spec-refinement toggle--**Confirm UI Auto-Launch (Mandatory — default visual confirmation surface)**: by default the Strategist confirmation stage is presented through an interactive local page in **three stages within one browser session**. Stage 1 confirms the scene and communication contract before asking the user to select tools. The AI then authors Stage 2's **complete deck solution once** from the user's actual contract: argument structure, reading density, template use, visual system, and image direction are judged together. After Stage 2 is confirmed, Stage 3 is authored once and asks only how to produce the already-decided solution. A change inside the current page never asks the AI or server to regenerate that stage. Color swatches, live font previews, icon samples, rendering references, and coordinated direction candidates appear where they help judgment; the chat path is the always-valid fallback. [`scripts/docs/confirm_ui.md`](../scripts/docs/confirm_ui.md) owns the schema, server lifecycle, port strategy, and fallback details; this section keeps the orchestration contract. The split:--| Stage | Confirms | Driven by |+| Stage | Strategist writes | Completion evidence ||---|---|---|-| **1 — communication contract** | audience · open-ended `communication_intent` (may combine several purposes) · `audience_outcome` · `core_message` / delivery context / artifact afterlife · `content_divergence` (all prose fields may be blank) · canvas | the source + user intent |-| **2 — complete deck solution** (derived once from Stage 1) | reading mode (`delivery_purpose`, PPT only) · narrative `mode` · page count · `visual_style` · conditional template reuse / adherence · color · typography · icons · image usage · generated-image rendering | the confirmed communication contract |-| **3 — resources / production** (derived once from Stage 1 + Stage 2) | conditional AI-image acquisition path · formula policy · generation mode · refine-spec toggle | the confirmed solution |--> **Why three stages.** A presentation may serve several purposes at once (for example, report progress, expose risk, and request a decision), so Stage 1 uses open prose rather than a purpose enum. Every editable Stage-1 prose field is non-blocking: the user may retain, revise, or clear the recommendation, and confirmation makes the field's current value authoritative, including an empty string. Blank means no explicit user constraint; derive downstream defaults from the source and request without writing the old recommendation back into `result.json`. Stage 2 chooses tools only after that contract is known and keeps mutually dependent choices together: `mode` is the argument strategy, template reuse is the inheritance strategy, and reading mode decides how meaning is divided among the page, visuals, and presenter. It therefore drives content grammar, page granularity, density / rhythm, speaker-note burden, and the body baseline; the visual / image fields form the remaining deck system. `delivery_purpose` remains the compatibility key for **reading mode**, not communication purpose. Page count is derived from content volume × audience outcome × reading mode. Generated images inherit the chosen deck color roles directly; the user confirms rendering, not a second image palette. Stage 3 therefore contains production mechanics only, never another aesthetic decision. Each stage is authored once; documented deterministic UI dependencies may update visible values locally, but there is no same-stage AI recomputation.+| `stage1` | Communication contract, `content_divergence`, and canvas only | `status: stage1-confirmed` |+| `stage2` | Complete deck solution from the confirmed contract; never skip for a template | `status: stage2-confirmed` |+| `stage3` | Production mechanics only: conditional AI path, formula policy, generation mode, refine-spec | `stage: final`, `status: confirmed` |-Steps:+1. Write Stage 1 `confirm_ui/recommendations.json` per the Confirm UI contract, then launch and wait:-> ⛔ **Steps 2 → 3 → 4 are ONE uninterrupted run — do NOT yield to the user mid-flow.** When an intermediate `--wait` returns, the AI **immediately and autonomously** derives and writes the next stage once in the **same turn**: do **not** summarize, ask a question, report progress, or end the turn in between. The browser is sitting on a "deriving…" spinner polling for the next stage you must write — stopping here strands the page and the user must prod you in chat to finish (a bug, not the intended flow). **Stage-1 and Stage-2 confirmations are intermediate machine handoffs, not stopping points.** The single ⛔ BLOCKING wait is the **final** confirmation at the end of step 4. (Chat-fallback path — only when the page never opened — is the exception: there you do present each stage in chat and wait for a reply.)--1. **Write Stage 1** to `<project_path>/confirm_ui/recommendations.json` with `"stage": "stage1"` and only the communication-contract fields. New recommendations MUST use the canonical `stage` selector. Put only the recommended `canvas` id in `recommend`. Write `audience`, `communication_intent`, `audience_outcome`, `core_message`, `delivery_context`, `artifact_afterlife`, and `content_divergence` as `{ "value": "<free text>" }`. Seed concrete editable recommendations where the source and request support them; all seven prose values may be blank and none blocks confirmation. The submitted current value is the sole truth: preserve a user-cleared field as `""` through every later stage and the final `result.json`; never restore the earlier recommendation. `communication_intent` is deliberately open prose: it may combine several purposes and state their priority or sequence; the nine common paths are prompt examples only and MUST NOT become a checkbox / enum. `content_divergence` asks how closely to follow the source vs how freely to reshape it (blank = balanced; facts stay sourced at every level); it is consumed while authoring `§IX`, recorded in `design_spec.md §I`, and is not written to `spec_lock.md`. A profile may make this field read-only with `{ "value": "...", "locked": true }`; Beautify uses that contract and is the only exception to user editing. Do **not** include reading mode, `mode`, `visual_style`, page count, template, color, typography, icon, or image fields in Stage 1. Set `lang` to the page language (`zh` / `en` / `ja`); visible text matches `lang`, or provide multilingual name / note variants as documented by the Confirm UI.-2. **Launch + wait for Stage 1.** Background launch; the parent returns when the page writes the stage-1 `result.json`. **Long tool timeout — 600000 ms** (the `--wait` ≈590 s budget):```bashpython3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon --wait```- Page opens at the launch-log URL such as `http://127.0.0.1:5050` — the **same port as the Step 6 live preview** (they never run at once: this page shuts down at the end of Step 4). If 5050 is held, the launcher **auto-advances** (5051, …) — read the actual URL from the launch log and report it. The page does **not** close after Stage 1: it shows a "deriving…" state and polls for Stage 2. **Launch or wait failure is non-fatal**: if it fails or times out (flask missing, port blocked, no GUI / remote / web host), do **NOT** troubleshoot — **on any non-zero exit, re-check `result.json` once** for a fresh `status: stage1-confirmed` before dropping to the chat fallback. **On success (exit 0 with a stage-1 result), do not pause or report — go straight to step 3 in the same turn.**-3. **Derive Stage 2 once from the confirmed communication contract, write it, then wait for the solution handoff — immediately, same turn (the page is polling for it).** Read the stage-1 `result.json` (`status: stage1-confirmed`). Using the user's **actual** contract (not your originals), **overwrite** `recommendations.json` with `"stage": "stage2"` and author the complete deck solution:- - Recommend PPT-only reading mode through the compatibility key `recommend.delivery_purpose` (`text` / `balanced` / `presentation`) from the confirmed audience, delivery context, and artifact afterlife. `text` makes the page self-contained with complete prose and detail; `balanced` shares meaning between page and presenter; `presentation` uses one idea, concise claims, and visual evidence per page while speech / notes carry explanation. Then recommend one narrative `mode` and page count from source volume × desired audience outcome × reading mode. Reading mode governs content grammar and page granularity as well as the body baseline; it is not a font-size preset. The page applies `reading mode → body baseline → unpinned role sizes` as a deterministic browser-only dependency. This never calls the backend, and a manually edited size is pinned against later reading-mode changes.- - When Step 3 loaded a deck/layout template, recommend `template_reuse_scope` now: `mirror`, `layout`, or `style`; `mirror` is legal only for `replication_mode: mirror`. Include `template_adherence: strict|adaptive` only for `mirror|layout`; `style` hides it and later writes `pptx_structure.mode: flat`. For a Deck, first compare its application contract—situations, audiences/outcomes, required narrative/page roles, and content policy—with the confirmed Stage-1 contract; do not treat the stored application as truth when the current request differs. Select from scenario fit: literal recurring artifact → consider `mirror`; compatible reusable structure with new content → `layout`; identity only or a contract that needs a different structure → `style`. Omit both fields for free design and brand-only templates.- - Author `design_directions` with ≥3 coordinated candidates (safe / shifted / bold; honest-shortfall exception unchanged). Each candidate carries one compatible `visual_style`, color object, typography object, icon id, and—when `image_usage` includes `ai`—one generated-image **rendering** object. The page applies a candidate as one coherent starting point and then exposes the component fields for deliberate override. Do not generate Cartesian combinations or random mix-and-match defaults.- - Color candidates carry background / secondary_bg / primary / accent / secondary_accent / body_text. Typography splits CJK + Latin for heading/body, includes topic-matched sample text, and uses one fixed body baseline per reading mode (`text` 20 / `balanced` 24 / `presentation` 32 on PPT). Font and direction cards change font character while preserving the current reading-mode sizing state. Recommend one or more `image_usage` source ids (`["ai"]`, `["ai","provided"]`, `["web","placeholder"]`, or `["none"]`; `none` is exclusive) and keep mixed-source / page-role guidance in `image_notes`. When AI is included, each direction's `image_strategy` contains rendering / visual / mood only; **never offer or submit a separate image palette**. Image HEX and role behavior come directly from that direction's deck color object. Spot-illustration lean remains rationale, not a field.-- **Stage 2 is never skipped** — an installed template is an input to the decision, not a substitute for deciding how it serves the contract. Never jump `recommendations.json` from `stage1` to `stage3`: the server refuses to render a skipped stage. The still-open page polls, renders Stage 2, and preserves Stage 1. Then attach to the already-running page; if Windows cleaned up the server, `--wait-only` auto-recovers it on the recorded/default port so the browser reconnects:++2. Read the Stage 1 result. Derive proposed image sources in core and load `strategist-image.md` before constructing Stage 2 when its trigger fires; apply `strategist-template.md` when active. Overwrite the recommendations with Stage 2, then wait:+```bashpython3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage2```- This returns when the page writes the stage-2 `result.json` (`status: stage2-confirmed`). On a non-zero exit, re-check `result.json` once before falling back to chat — except a `stage skip detected` error, which is not a page failure: you wrote a stage out of order; rewrite `recommendations.json` with the stage the error names and re-attach.-4. **Derive Stage 3 once from the confirmed solution, then wait for the final confirmation.** Read the stage-2 `result.json`. **Do not reopen aesthetic choices.** Overwrite `recommendations.json` with `"stage": "stage3"` and recommend only production mechanics: enumerable `formula_policy`; conditional `image_ai_path` when confirmed `image_usage` includes `ai`; `generation_mode`; and `refine_spec`. The page shows the confirmed image-source summary as read-only context. Then attach to the already-running page; `--wait-only` auto-recovers a dead server as above (same 600000 ms budget):++3. Read the Stage 2 result, overwrite recommendations with Stage 3, then perform the final blocking wait:+```bashpython3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only```- This is the ⛔ BLOCKING completion: returns when the page writes the final `result.json` (`status: confirmed`, `stage: final`, carrying Stage 1 + Stage 2 + Stage 3 fields). On a non-zero exit, re-check `result.json` once (a `stage skip detected` error means Stage 2 was never confirmed — go back to step 3, not the chat fallback). Confirmed sizes are **already px** (the system is px-only — no pt anywhere, no conversion): write `result.json` `typography.body_size` / `sizes` into `design_spec.md` / `spec_lock.md` / SVG verbatim. `generation_mode: "split"` / `refine_spec: true` are explicit user choices.-5. **Close the confirm page (Mandatory cleanup — every path).** Shut the server down before leaving Step 4 so it cannot keep holding port 5050 (which Step 6 live preview reuses):++4. On any non-zero wait, re-read `result.json` once before using the documented chat fallback. A stage-skip result returns to the missing stage; it is not a browser failure. After final confirmation or chat fallback, always release the server:+```bashpython3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --shutdown```- **Idempotent and required regardless of whether Confirm was clicked**: clicking the final Confirm already shuts the page down (then a no-op); the chat-fallback path leaves it running. Run it after reading the confirmation, before Step 5.--**Always also print each stage's recommendations + URL in chat** as the always-valid fallback. **The chat fallback is staged too**: if the page never opens or a wait times out with no fresh result, present Stage 1 as open communication questions (the common purposes are examples, never a numbered pick-list) → get confirmation → derive and present Stage 2 → get confirmation → derive and present Stage 3 → get confirmation → take those values. Either path converges.--**Honoring the confirmation (result.json is authoritative — Mandatory)**: the confirmed values **override your own recommendations** when you write `design_spec.md` / `spec_lock.md`. A user who changed any field changed it on purpose. In particular, map `image_usage` to §VIII `Acquire Via` (its value names differ from §h options — translate). `image_usage` may be either a legacy single string or a Confirm UI multi-select array; for arrays, apply every selected source. `image_notes`, when present, is a user-authored image intent note that Strategist must honor while assigning per-page §VIII rows:--For a confirmed template route, map `template_reuse_scope` mechanically: `style` → `pptx_structure.mode: flat` and omit `template_adherence`, `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`; `layout` / `mirror` → `mode: structured`, retain the confirmed `template_adherence`, and write the complete mappings. Never infer mirror behavior from the template workspace's `replication_mode` alone—the confirmed reuse scope is the downstream execution authority.--| `result.json.image_usage` | §VIII `Acquire Via` | h.5 + Step 5 generation |-|---|---|---|-| `ai` | `ai` rows | Run h.5 (lock rendering; inherit deck colors); Step 5 generates |-| `web` | `web` rows | None |-| `provided` | **`user`** rows | None — never generate |-| `placeholder` | `placeholder` rows | None |-| `none` | no image rows (§h option A) | None |-| Legacy custom prose | Infer the intended rows from the prose | Run h.5 only if the prose includes AI |--When the confirmed `image_usage` does not include `ai` (and no legacy custom prose includes AI), do **NOT** run h.5, do **NOT** write `ai` rows, and do **NOT** generate images in Step 5 — regardless of what you recommended. `none` is exclusive: if confirmed, write no §VIII image rows. The same "confirmed value wins" rule applies to every field (color → §III, typography → §IV, etc.).--**Small spot illustrations are a Strategist judgment, not a confirmation field.** The user chooses image *source* through `image_usage`; whether the deck leans into decorative illustrations is anchored by the locked `visual_style`'s **illustration propensity** (`core` / `supportive` / `sparse`), expressed only in the `image_notes` rationale — never a new confirmation control. An explicit user request to use or skip illustrations overrides that default either way; `image_usage: none` still wins (write no illustration rows); and source still comes from `image_usage` — a `core` style does not silently generate AI spots when the user did not pick AI. They are ordinary §VIII image rows (`Type: Illustration` / `Illustration Sheet`) using normal `Acquire Via` values. If the plan needs ≥3 same-family AI spot illustrations, use the `ai` Illustration Sheet + `slice` workflow by default; do not generate one AI image per spot. Full rule + precedence: [`references/strategist.md`](../references/strategist.md) §h. Use them on suitable pages and omit them where they would weaken clarity.--**One authored recommendation per stage; final visible state wins (Mandatory).** Author each stage exactly once. A user edit inside Stage 2 MUST NOT trigger AI / backend re-recommendation, and confirmation MUST NOT be followed by a hidden repair pass that changes any displayed field. The page may apply only documented deterministic local dependencies: reading mode sets the default body baseline, body sets unpinned role sizes, and manual size edits pin those values. Font / direction changes preserve the current sizing state. No other advanced override silently rewrites a sibling choice.-Writing `design_spec.md` / `spec_lock.md` and later pages is **consumption of the confirmed state**, not another confirmation-stage calculation. Preserve every confirmed field verbatim and use it as an execution constraint:--| Confirmed anchor | Consume it in |-|---|---|-| `communication_intent` / `audience_outcome` / `core_message` | outline obligations, argument emphasis, and audience moves |-| `delivery_context` / `artifact_afterlife` | page-vs-presenter information load, standalone completeness, notes / citation depth, and hand-off structure |-| `visual_style` (§d Layer 2) | layout treatment, shape language, and visual rhythm while preserving the separately confirmed color / icon / typography values |-| `mode` (§d Layer 1) | outline structure and register (§IX) |-| `delivery_purpose` compatibility key (reading mode, §g) | content grammar, page granularity, notes burden, and per-page density / rhythm (§6.1); use the already-confirmed body / role sizes verbatim |-| `audience` (§c) | tone, evidence depth, and outline emphasis (§IX) |-| `color` HEX (§e) | exact deck roles and AI prompt color-role instructions; never invent or restore an image-palette choice |--If a deliberately mixed set of advanced overrides is unusual, honor it rather than silently “fixing” it. Canvas remains the explicit exception only in the sense that changing canvas does not rescale font sizes (see strategist §g); it still does not trigger a second stage calculation.--**Opt-out**: if the user has said they don't want the page (e.g. "不要网页" / "just confirm in chat" / "纯聊天确认"), skip the launch entirely (step 2) and present the Strategist confirmation stage in chat as before — steps 1, 3, 4 still apply (recommendations summary in chat; wait; take chat values).--The page is a **confirmation surface only** — Strategist still authors every recommendation; the page never generates content.+If the user opted out of the page, skip launch and run the same three stages in chat. Otherwise report the launch URL and keep the staged chat summaries available as fallback. Both paths must preserve the final visible values; writing `design_spec.md`, `spec_lock.md`, and later pages consumes that state without a hidden repair or second recommendation pass. Map confirmed image sources through `strategist.md` §h, apply `strategist-template.md` §3 for an active template, and never write a separate image palette.**Mandatory — split-mode note** (not a separate confirmation): after listing the Strategist confirmation stage details, you MUST append exactly one short line (rendered in the user's language, prefixed with 💡) about generation mode. Pick the variant by qualitative read of upstream-load signals — recommended page count, source-material bulk, whether `topic-research` ran with substantial web-fetch accumulation:@@ -255,38 +207,29 @@ This line is required output every run — the user must always see the mode cho**Mandatory — spec-refinement note** (not a separate confirmation): after the split-mode line, you MUST append one short opt-in line (rendered in the user's language, prefixed with 💡) telling the user they may **refine the spec first** — Strategist will produce the full design spec, then stop for review/revision of any part of it before any generation, via the [refine-spec](stages/refine-spec.md) stage. Default is OFF: no request → the spec is written in one go and the pipeline auto-proceeds as usual. Only when the user explicitly asks in chat (e.g. "refine the spec first") or confirms `refine_spec: true` through Confirm UI does the [refine-spec](stages/refine-spec.md) stage take over after the Strategist confirmation stage. This line, like the split-mode line, is required output every run — the user must see the choice exists; whether to act on it is theirs. When the Confirm UI is used, this choice also appears as the in-page refine-spec toggle and is captured in `result.json` (`refine_spec`); the chat-summary fallback still prints this line.-**Formula rendering policy lives inside item 7 (Typography plan)**:--| Policy | Behavior |-|---|---|-| `mixed` (default) | Strategist renders complex formula-worthy expressions as PNG assets; simple inline expressions remain editable text / Unicode |-| `render-all` | Strategist renders every formula-worthy expression as PNG assets |-| `text-only` | No formula rendering; formulas remain editable text / Unicode |--After the Strategist confirmation stage is approved and **before outputting `design_spec.md` / `spec_lock.md`**, if the confirmed formula policy is `mixed` or `render-all` and the content contains formula-worthy expressions, Strategist MUST:--1. Identify explicit LaTeX and any source expressions that should be faithfully structured as formulas.-2. Write `<project_path>/images/formula_manifest.json` with only the formulas selected for rendering.-3. Run:- ```bash- python3 ${SKILL_DIR}/scripts/latex_render.py <project_path>- ```-4. Include each formula as an `Acquire Via: formula`, `Type: Latex Formula` row in `design_spec.md §VIII Image Resource List`: use `Status: Rendered` when the PNG exists, or `Status: Needs-Manual` after provider exhaustion. List every formula in `spec_lock.md images` with `| no-crop`.--The formula renderer uses a provider fallback chain by default: `codecogs,quicklatex,mathpad,wikimedia`. The first three are color-aware; Wikimedia is an availability fallback. If every provider fails for a selected formula, report its manifest item, LaTeX source, target filename, and provider errors; mark only that row `Needs-Manual` and continue without claiming `Rendered`. The user may supply the exact target PNG before the Step 7 image-readiness gate or change the formula policy. Formula PNGs are transparent by default: manifest `background` is the temporary render matte and transparency-removal reference, not a retained final background unless `transparent: false` is set for that item. Do not scan `spec_lock.md` for `$...$` or `$$...$$`. Dollar-delimited math in source material is only a signal for Strategist; the renderer consumes the explicit manifest.+**Formula policy**: Stage 3 confirms `mixed`, `render-all`, or `text-only`. When the confirmed policy requires rendering formula-worthy content, load [`strategist-image.md`](../references/strategist-image.md) even if `image_usage` is `none`, and follow its formula-resource contract before filling the planning artifacts. `text-only` creates no formula image rows.If the user provided images or formula PNGs were rendered, run analysis **before outputting the design spec**. It writes `analysis/image_analysis.csv` — the authoritative regenerated image-fact view in the `analysis/` folder, which MUST be read before authoring §VIII:```bashpython3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images```-> 🔁 **Image facts are regenerated on demand, never a durable store.** `images/` is a live working folder — pictures are extracted from the source at import, the user may drop or replace files at any time, and Step 5 writes web/AI images into it. The single source of truth is therefore the **current contents of `images/`**, and `analysis/image_analysis.csv` is a *regenerated view* of it, not a fact to keep in sync. Re-run `analyze_images.py <project_path>/images` immediately **before any step that reads image facts** so the view reflects the live folder: before the §h image-usage recommendation (see [strategist.md](../references/strategist.md) §h), here before authoring §VIII, after Step 5 acquisition (so web/AI files join the view), and again any time the user says they added or replaced images. This is the staleness strategy — re-derive on use, no cache to invalidate.+> 🔁 **Image facts are regenerated on demand, never a durable store.** `images/` is a live working folder — pictures are extracted from the source at import, the user may drop or replace files at any time, and Step 5 writes web/AI images into it. The single source of truth is therefore the **current contents of `images/`**, and `analysis/image_analysis.csv` is a *regenerated view* of it, not a fact to keep in sync. Re-run `analyze_images.py <project_path>/images` immediately **before any step that reads image facts** so the view reflects the live folder: before the image-source recommendation (see [strategist.md](../references/strategist.md) §h), here before authoring §VIII, after Step 5 acquisition (so web/AI files join the view), and again any time the user says they added or replaced images. This is the staleness strategy — re-derive on use, no cache to invalidate.> ⚠️ **Image handling**: NEVER directly read / open / view image files (`.jpg`, `.png`, etc.). All image info comes from `analyze_images.py` output (`analysis/image_analysis.csv`) or the Design Spec's Image Resource List.**Output**:- `<project_path>/design_spec.md` — human-readable design narrative-- `<project_path>/spec_lock.md` — machine-readable communication + execution contract (skeleton: `templates/spec_lock_reference.md`); Executor re-reads before every page+- `<project_path>/spec_lock.md` — machine-readable communication + execution contract; Executor re-reads before every page++For a new artifact pair, run these commands once after final confirmation and before filling the files; each refuses to overwrite an existing artifact:++```bash+python3 ${SKILL_DIR}/scripts/project_manager.py scaffold-spec <project_path>+python3 ${SKILL_DIR}/scripts/project_manager.py scaffold-lock <project_path>+```++After filling both files, run `python3 ${SKILL_DIR}/scripts/project_manager.py validate <project_path>` and repair schema findings in their owning artifact before the checkpoint. A resume path edits the existing files and never re-scaffolds them.**✅ Checkpoint — Phase deliverables complete, auto-proceed to next step**:```markdown@@ -376,14 +319,27 @@ Workflow:Read the execution references for this deck's locked `mode` + `visual_style` (from `spec_lock.md`):```-Read references/executor-base.md # REQUIRED: common guidelines-Read references/shared-standards.md # REQUIRED: SVG/PPT technical constraints-Read references/native-shape-authoring.md # REQUIRED: stock-shape selection and fragment helper contract+Read references/executor-base.md # REQUIRED: flat/shared execution core+Read references/shared-standards-core.md # REQUIRED: SVG compatibility core+Read references/semantic-svg.md # REQUIRED: semantic metadata boundaryRead references/modes/<locked-mode>.md # narrative skeleton (spec_lock.md `mode`)Read references/visual-styles/<locked-style>.md # aesthetic (spec_lock.md `visual_style`)```-> Read executor-base + shared-standards + native-shape-authoring + the one locked mode file + the one locked visual-style file. For `mode: custom` or `visual_style: custom`, skip that preset file and follow `mode_behavior` / `visual_style_behavior` from `spec_lock.md` instead. Never glob `modes/` or `visual-styles/`.+> Read only the five always-on references above plus the conditionally triggered modules below. For `mode: custom` or `visual_style: custom`, skip that preset file and follow `mode_behavior` / `visual_style_behavior` from `spec_lock.md` instead. Never glob `modes/` or `visual-styles/`.++| Deterministic trigger | Additional references |+|---|---|+| `pptx_structure.mode: structured` | `executor-structured.md` + `pptx-structure-interface.md` |+| `spec_lock.page_charts` has any row, or §VII/current page declares a chart or text-grid table | `executor-chart.md` |+| A page will use a preset pattern fill or evaluate native chart/table replacement | `native-data-interface.md` before deciding eligibility or emitting metadata |+| `spec_lock.md images` or §VIII contains at least one image/formula row, or an active template carries bundled images | `executor-image.md` + `image-layout-spec.md` + `svg-image-embedding.md` |+| At least one placed image has `Status: Sourced` | `executor-web-image.md` after the image branch |+| The locked style/current page calls for noncanonical or alpha paint, dash/cap/join, tracking/decoration/outline, gradient/filter/glow/shadow, path/transform/clipping, or another constructed effect | `svg-effects.md` before authoring that value or effect |+| A page calls for a literal PowerPoint stock shape | `native-shape-authoring.md` before selecting or emitting that shape |+| All SVG pages and SVG quality gates are complete | `executor-notes.md` before generating speaker notes |++No branch is loaded by analogy. Evaluate these triggers from `spec_lock.md`, §VII/§VIII, the selected style, and the current page plan.**Design Parameter Confirmation (Mandatory)**: before the first SVG, output key design parameters from the spec (canvas dimensions, color scheme, font plan, body font size). See executor-base.md §2.@@ -398,7 +354,7 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon- **Do NOT read or apply submitted annotations during generation.** Users may annotate at any time, but Executor proceeds without touching them. The window to apply annotations opens only after Step 7 completes — see [`workflows/stages/live-preview.md`](stages/live-preview.md).- The editor also supports **staged direct edits** (text content + SVG element attributes previewed immediately, then written to `svg_output/` only when the user clicks **Apply changes**; `Ctrl+Z` / Undo drops staged edits) alongside annotation; re-export stays chat-driven. Full scope and editor details: see [`workflows/stages/live-preview.md`](stages/live-preview.md) Notes.-**Pre-generation Template Read (Mandatory)**: first read `templates/template_execution_manifest.json` when present. It is the compact prototype roster and points each prototype to one `text_slots_path`. Use the roster to select prototypes; before each mirror page, read that prototype's text-slot sidecar and complete `templates/<basename>.svg`. Layout reuse reads the selected complete SVG but does not apply mirror-only text topology restrictions. When the manifest or selected sidecar is unavailable, batch-read every distinct layout SVG referenced in `spec_lock.page_layouts` once before the first page and apply the full-SVG mirror/layout rules. In all cases, batch-read every distinct chart SVG referenced in `spec_lock.page_charts` (plus any §VII backup charts) once up front. Do not substitute a manifest or sidecar for the selected full prototype. See executor-base.md §1.0.+**Conditional pre-generation reads**: on a structured route, follow `executor-structured.md` to read the template execution roster/sidecars and every distinct locked layout SVG; flat routes skip that template read. When `spec_lock.page_charts` or §VII names selected chart templates, follow `executor-chart.md` and batch-read those distinct chart SVGs once before the first affected page. A summary or sidecar never substitutes for the selected full SVG.> Image facts: trust the `analysis/image_analysis.csv` regenerated at the end of Step 5. If `images/` changed since (the user swapped or added files), re-run `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` before laying images out — facts are re-derived on use, never a stale store (Step 4 image-facts note).@@ -409,7 +365,7 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon**Visual Construction Phase**: generate SVG pages sequentially, one at a time, in one continuous pass → `<project_path>/svg_output/`-Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Before drawing a literal stock shape, apply [`native-shape-authoring.md`](../references/native-shape-authoring.md): use the stdout-only helper when one PowerPoint preset exactly matches, keep basic SVG primitives for rect/round-rect/ellipse, and keep free SVG for custom semantics. Diagram relationships are Shape-first: use ordinary line/path shapes with registered arrow markers for thin edges and ordinary shape presets for solid block arrows; do not default to connector-family presets or author attachment metadata. Never infer a preset from contour similarity.+Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. When a page actually needs a literal stock shape, load and apply [`native-shape-authoring.md`](../references/native-shape-authoring.md) before drawing it. Diagram relationships remain Shape-first; do not infer a preset from contour similarity.`template_reuse_scope: mirror|layout` pages MUST start from the complete `page_layouts` SVG, keep all inherited visible objects in `svg_output/`, and preserve the locked root Master/Layout identity plus stable atomic Master/Layout and slot ids. Strict keeps the prototype structure unchanged. Adaptive keeps its Master contract and, when Layout atoms or slot topology/bounds genuinely evolve, assigns a new key/name and updates `spec_lock.md` immediately. `layout` pages may reflow and re-skin to the project lock; `mirror` pages preserve literal visuals and may change only visible `<text>` / `<tspan>` values while keeping text/tspan count, order, nesting, and every attribute unchanged. `template_reuse_scope: style` follows the flat free-design paragraph below and does not inherit template structure metadata.@@ -433,7 +389,7 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final- Run against `svg_output/` (not after `finalize_svg.py` — finalize rewrites SVG and masks violations).- The JSON report is written to `exports/svg_quality_report.json`. `inherited` prototype diagnostics and `source-import` compatibility losses are informational provenance; only changed/new warnings remain `introduced`, and all release-blocking failures remain `blocking`.-**Logic Construction Phase**: generate speaker notes → `<project_path>/notes/total.md`+**Logic Construction Phase**: after the SVG quality gate passes, load [`executor-notes.md`](../references/executor-notes.md) and generate speaker notes → `<project_path>/notes/total.md`**✅ Checkpoint — Confirm all SVGs and notes are fully generated and quality-checked. Run the applicable conditional gates below, then proceed to Step 7**:```markdowndiff --git a/skills/ppt-master/workflows/governance/failure-recovery.md b/skills/ppt-master/workflows/governance/failure-recovery.mdindex 5084f4e7..fe38a6f4 100644--- a/skills/ppt-master/workflows/governance/failure-recovery.md+++ b/skills/ppt-master/workflows/governance/failure-recovery.md@@ -64,9 +64,9 @@ Here, **final confirmation evidence** means either the explicit final confirmati| Last good state | Resume from ||---|---|| Stage 1 confirmation exists, Stage 2 missing | Write Stage 2 recommendations, then `confirm_ui/server.py <project> --wait-only --wait-stage stage2` |-| Stage 2 confirmation exists, final confirmation missing | Resume [`generate-pptx`](../generate-pptx.md) Step 4 substep 4, "Derive Stage 3 once from the confirmed solution, then wait for the final confirmation." |-| Final confirmation evidence exists; `design_spec.md` is missing, with or without a surviving `spec_lock.md` | Return to [`strategist.md`](../../references/strategist.md) §6 steps 1–4 and regenerate `design_spec.md` and `spec_lock.md` together from the source material and confirmed state; do not reconstruct the outline from an orphan lock. |-| Final confirmation evidence exists; `design_spec.md` exists and `spec_lock.md` missing | Return to [`strategist.md`](../../references/strategist.md) §6 step 4 and regenerate `spec_lock.md`. |+| Stage 2 confirmation exists, final confirmation missing | Resume [`generate-pptx`](../generate-pptx.md) Step 4 confirmation orchestration at Stage 3: derive production mechanics from the confirmed solution, then perform the final wait. |+| Final confirmation evidence exists; `design_spec.md` is missing, with or without a surviving `spec_lock.md` | Return to Generate Step 4 and [`strategist.md`](../../references/strategist.md) §6.2; scaffold the missing artifact and regenerate `design_spec.md` and `spec_lock.md` together from the source material and confirmed state. Do not reconstruct the outline from an orphan lock. |+| Final confirmation evidence exists; `design_spec.md` exists and `spec_lock.md` missing | Return to Generate Step 4, run `project_manager.py scaffold-lock`, and fill the lock from the confirmed state plus the design spec under [`strategist.md`](../../references/strategist.md) §6.2. || No final confirmation evidence is available | Resume Step 4 from the latest stage evidenced by `confirm_ui/result.json`; if no stage is persisted, restart Step 4 at Stage 1. Do not infer confirmed choices from partial planning artifacts. || `design_spec.md` and `spec_lock.md` complete, split mode selected | [`resume-execute`](../stages/resume-execute.md) || Images acquired but SVGs not started | [`generate-pptx`](../generate-pptx.md) Step 6 |diff --git a/skills/ppt-master/workflows/profiles/beautify-pptx.md b/skills/ppt-master/workflows/profiles/beautify-pptx.mdindex 17ba4aa9..09d7cbf9 100644--- a/skills/ppt-master/workflows/profiles/beautify-pptx.md+++ b/skills/ppt-master/workflows/profiles/beautify-pptx.md@@ -24,7 +24,7 @@ Re-lays-out an existing `.pptx`: the text is preserved **verbatim**, the source**Hard rule — not a patch, not a fill**: this regenerates a native deck through Strategist → Executor → export ([`generate-pptx`](../generate-pptx.md) Steps 4–7). It does **not** edit the source file in place, and it is **not** [`template-fill-pptx`](../template-fill-pptx.md) (which clones source slides and replaces text). It also does not parse an arbitrary third-party template for text-only substitution (the rejected #53 direction) — it builds every page from scratch.-**Distinct from mirror templates**: `replication_mode: mirror` (executor §1.1) keeps layout + visuals verbatim and edits text. Beautify is the inverse — content verbatim, layout redone, identity inherited.+**Distinct from mirror templates**: `replication_mode: mirror` ([`executor-structured.md`](../../references/executor-structured.md) §1.1) keeps layout + visuals verbatim and edits text. Beautify is the inverse — content verbatim, layout redone, identity inherited.**When this profile is wrong — re-architecture belongs to the default main pipeline**: this profile preserves the source's page count and page order 1:1. It is for "keep this deck, just lay it out better". When the user instead wants the original page breakdown reconsidered — merge / split / reorder pages, re-outline the structure, build a *better deck* from the same content rather than a prettier version of the same pages — do not activate this profile. This includes re-pagination for fit: "keep every word but split a crowded page so it reads better" changes page count. Convert the deck with [`ppt_to_md`](../../scripts/source_to_md/ppt_to_md.py) and run the default main pipeline, where the Strategist re-architects the outline freely from the extracted content. The deciding question: is the source's page split information to preserve, or just the previous author's structure to improve? Preserve → activate this profile; improve → default main pipeline.diff --git a/skills/ppt-master/workflows/stages/refine-spec.md b/skills/ppt-master/workflows/stages/refine-spec.mdindex fa438790..39473af9 100644--- a/skills/ppt-master/workflows/stages/refine-spec.md+++ b/skills/ppt-master/workflows/stages/refine-spec.md@@ -49,7 +49,7 @@ These overlap with what the locked `mode`, visual style, and §6.1 already shape**Keep both files in sync on every change.** Any revision the user approves must land in both `design_spec.md` and `spec_lock.md`; on divergence `spec_lock.md` wins (see [`strategist.md`](../../references/strategist.md) §6.2). Iterate as many rounds as the user wants. The loop ends only when the user explicitly approves the spec.-**Re-run the route/template preflight after reuse revisions.** If the user changes `template_reuse_scope`, `template_adherence`, `page_layouts`, the Master/Layout definition roster, or any `page_pptx_layouts` assignment, repeat the Strategist preflight in [`strategist.md`](../../references/strategist.md) §6.2 before approval and hand-back. Switching to `style` rewrites the route to `pptx_structure.mode: flat` and removes all structure mappings/adherence; switching to `mirror` / `layout` restores a complete structured contract. Every newly selected structured prototype must declare root Master/Layout identity, direct atomic Master/Layout visuals, and valid top-level slot groups with positive bounds plus one compatible carrier or explicit composite `object` proxy. A zero-slot Layout is valid. Update `pptx_masters`, unique `pptx_layouts` definitions, and complete `page_pptx_layouts` assignments in both artifacts immediately. A legacy prototype is not selectable; create a current workspace through [`create-template`](../create-template.md) before refinement.+**Re-run the route/template preflight after reuse revisions.** If the user changes `template_reuse_scope`, `template_adherence`, `page_layouts`, the Master/Layout definition roster, or any `page_pptx_layouts` assignment, repeat the preflight in [`strategist-template.md`](../../references/strategist-template.md) before approval and hand-back. Switching to `style` rewrites the route to `pptx_structure.mode: flat` and removes all structure mappings/adherence; switching to `mirror` / `layout` restores a complete structured contract. Every newly selected structured prototype must declare root Master/Layout identity, direct atomic Master/Layout visuals, and valid top-level slot groups with positive bounds plus one compatible carrier or explicit composite `object` proxy. A zero-slot Layout is valid. Update `pptx_masters`, unique `pptx_layouts` definitions, and complete `page_pptx_layouts` assignments in both artifacts immediately. A legacy prototype is not selectable; create a current workspace through [`create-template`](../create-template.md) before refinement.---diff --git a/skills/ppt-master/workflows/stages/resume-execute.md b/skills/ppt-master/workflows/stages/resume-execute.mdindex 4036e9b4..8d603169 100644--- a/skills/ppt-master/workflows/stages/resume-execute.md+++ b/skills/ppt-master/workflows/stages/resume-execute.md@@ -49,7 +49,7 @@ Read skills/ppt-master/workflows/generate-pptx.mdThen jump to `### Step 6: Executor Phase` and run the documented pipeline:-- Read references (executor-base + shared-standards + the locked `mode` file under `modes/` + the locked `visual_style` file under `visual-styles/` + image-layout-spec + svg-image-embedding)+- Read the Step 6 flat core (`executor-base`, `shared-standards-core`, and the locked mode / visual-style files), then only the branches selected by its condition table- Design Parameter Confirmation- Pre-generation Batch Read (every layout / chart SVG referenced in `spec_lock`)- Per-page `spec_lock` re-read + sequential page generationdiff --git a/skills/ppt-master/workflows/stages/verify-charts.md b/skills/ppt-master/workflows/stages/verify-charts.mdindex 861557fa..03ca701f 100644--- a/skills/ppt-master/workflows/stages/verify-charts.md+++ b/skills/ppt-master/workflows/stages/verify-charts.md@@ -60,7 +60,7 @@ For each page in the Step 1 list:1. Read `<project_path>/svg_output/<page>.svg`.2. Locate the plot-area definition:- - Preferred: `<!-- chart-plot-area: ... -->` marker placed by Executor (see [executor-base.md §3.1](../../references/executor-base.md)). Read coordinates directly.+ - Preferred: `<!-- chart-plot-area: ... -->` marker placed by Executor (see [executor-chart.md §2.1](../../references/executor-chart.md)). Read coordinates directly.- If missing: derive the plot area from the SVG's axis lines (rectangular charts) or center/radius elements (radial charts). Then **add the marker back to the SVG** so future runs are not paying this cost again.3. Read the data series from the SVG's `<text>` label/value elements.4. **Read axis tick labels for every axis-based chart.** Locate the `<text>` elements along the value axis — X-axis labels for horizontal bars, Y-axis labels for vertical bars, and Y-axis labels for line-like charts. Extract the first and last tick values to determine the axis range (e.g. `0%` to `120%` → range `0,120`). Pass this range as `--value-range`, `--y-range`, or `--x-range` as appropriate. Radar uses `--max-value` instead of a range: read the outermost ring's tick value and pass it as `--max-value`. If the SVG has no explicit tick labels (data labels only, no grid), omit the range and let the calculator auto-normalize — but flag the receipt as `scale=auto (no ticks)`.