From 1682603705225fc351b017098ee34acbe8d67f15 Mon Sep 17 00:00:00 2001 From: KeyInfo Bot Date: Sun, 12 Jul 2026 00:01:51 +0800 Subject: [PATCH] Sync third-party and MCP marketplace plugins Constraint: Public skills are published only by explicit administrator action unless they are tracked third-party market sources. Confidence: high Scope-risk: narrow Directive: Keep private/internal skills out of the public marketplace and preserve normal incremental market Git history. Tested: Marketplace validation passed. --- config/external-sources.lock.json | 8 +- .../plugins/mcp-playwright/MCP_SOURCE.json | 2 +- .../next-skills/THIRD_PARTY_SOURCE.json | 4 +- plugins/codex/plugins/ppt-master/README.md | 4 +- .../ppt-master/THIRD_PARTY_SOURCE.json | 4 +- .../ppt-master/skills/ppt-master/SKILL.md | 118 +- .../ppt-master/references/animations.md | 103 +- .../references/artifact-ownership.md | 18 +- .../ppt-master/references/executor-base.md | 16 +- .../references/image-layout-patterns.md | 15 +- .../ppt-master/references/shared-standards.md | 1400 ++++++++--------- .../ppt-master/references/strategist.md | 5 +- .../references/svg-image-embedding.md | 14 +- .../references/template-designer.md | 71 +- .../references/visual-styles/blueprint.md | 2 +- .../references/visual-styles/chalkboard.md | 2 +- .../references/visual-styles/dark-tech.md | 2 +- .../visual-styles/data-journalism.md | 2 +- .../references/visual-styles/glassmorphism.md | 2 +- .../references/visual-styles/paper-cut.md | 2 +- .../references/visual-styles/soft-rounded.md | 2 +- .../skills/ppt-master/requirements.txt | 21 +- .../skills/ppt-master/scripts/README.md | 9 +- .../ppt-master/scripts/animation_config.py | 28 +- .../ppt-master/scripts/beautify_inventory.py | 17 +- .../skills/ppt-master/scripts/config.py | 74 +- .../ppt-master/scripts/docs/conversion.md | 9 +- .../scripts/docs/pptx-animations.md | 194 +++ .../scripts/docs/pptx-transitions.md | 148 ++ .../ppt-master/scripts/docs/svg-pipeline.md | 66 +- .../scripts/docs/troubleshooting.md | 13 +- .../skills/ppt-master/scripts/error_helper.py | 44 +- .../skills/ppt-master/scripts/finalize_svg.py | 122 +- .../scripts/native_narration_pptx.py | 285 ++-- .../ppt-master/scripts/pptx_animations.py | 1088 +++++++++++-- .../skills/ppt-master/scripts/pptx_intake.py | 52 +- .../scripts/pptx_to_svg/pic_to_svg.py | 19 +- .../ppt-master/scripts/pptx_transitions.py | 1359 ++++++++++++++++ .../ppt-master/scripts/project_manager.py | 4 +- .../scripts/source_to_md/ppt_to_md.py | 67 +- .../ppt-master/scripts/svg_editor/server.py | 64 +- .../scripts/svg_editor/static/app.js | 45 +- .../svg_finalize/align_embed_images.py | 12 +- .../scripts/svg_finalize/fix_image_aspect.py | 9 +- .../scripts/svg_finalize/svg_rect_to_path.py | 13 +- .../ppt-master/scripts/svg_quality_checker.py | 508 +++++- .../skills/ppt-master/scripts/svg_to_pptx.py | 3 +- .../scripts/svg_to_pptx/animation_config.py | 366 ++++- .../scripts/svg_to_pptx/drawingml/context.py | 29 +- .../svg_to_pptx/drawingml/converter.py | 193 ++- .../scripts/svg_to_pptx/drawingml/elements.py | 152 +- .../scripts/svg_to_pptx/drawingml/styles.py | 244 ++- .../svg_to_pptx/drawingml/theme_fonts.py | 136 +- .../scripts/svg_to_pptx/drawingml/utils.py | 164 +- .../svg_to_pptx/geometry_properties.py | 140 ++ .../native_objects/marker_common.py | 3 +- .../svg_to_pptx/pptx_package/builder.py | 574 +++++-- .../scripts/svg_to_pptx/pptx_package/cli.py | 419 +++-- .../svg_to_pptx/pptx_package/discovery.py | 2 +- .../svg_to_pptx/pptx_package/narration.py | 445 ++++-- .../svg_to_pptx/pptx_package/slide_xml.py | 14 +- .../pptx_package/template_structure.py | 96 +- .../pptx_package/template_validation.py | 793 ++++++++++ .../scripts/svg_to_pptx/use_expander.py | 435 ++++- .../scripts/template_fill_pptx/analyzer.py | 41 +- .../scripts/template_fill_pptx/applier.py | 78 +- .../scripts/template_fill_pptx/checker.py | 28 +- .../template_fill_pptx/diagram_read.py | 569 +++++++ .../scripts/template_fill_pptx/transitions.py | 108 +- .../templates/charts/CHART_STYLE_GUIDE.md | 115 +- .../templates/charts/harvey_balls_table.svg | 3 +- .../ppt-master/templates/decks/README.md | 2 +- .../templates/decks/中国电信/design_spec.md | 17 +- .../templates/decks/中国电建/design_spec.md | 29 +- .../templates/decks/中汽研/design_spec.md | 24 +- .../templates/decks/招商银行/design_spec.md | 19 +- .../templates/decks/重庆大学/design_spec.md | 23 +- .../templates/design_spec_reference.md | 24 +- .../ppt-master/templates/layouts/README.md | 6 +- .../layouts/academic_defense/design_spec.md | 26 +- .../templates/layouts/ai_ops/design_spec.md | 29 +- .../layouts/government_blue/design_spec.md | 26 +- .../layouts/government_red/design_spec.md | 26 +- .../layouts/medical_university/design_spec.md | 33 +- .../layouts/pixel_retro/design_spec.md | 29 +- .../psychology_attachment/design_spec.md | 34 +- .../templates/spec_lock_reference.md | 10 +- .../ppt-master/workflows/beautify-pptx.md | 10 +- .../ppt-master/workflows/create-template.md | 125 +- .../workflows/customize-animations.md | 52 +- .../ppt-master/workflows/generate-audio.md | 2 +- .../skills/ppt-master/workflows/index.md | 2 +- .../workflows/native-enhance-pptx.md | 20 + .../ppt-master/workflows/refine-spec.md | 2 +- .../skills/ppt-master/workflows/routing.md | 4 +- .../workflows/template-fill-pptx.md | 17 +- 96 files changed, 9209 insertions(+), 2598 deletions(-) create mode 100644 plugins/codex/plugins/ppt-master/skills/ppt-master/scripts/docs/pptx-animations.md create mode 100644 plugins/codex/plugins/ppt-master/skills/ppt-master/scripts/docs/pptx-transitions.md create mode 100644 plugins/codex/plugins/ppt-master/skills/ppt-master/scripts/pptx_transitions.py create mode 100644 plugins/codex/plugins/ppt-master/skills/ppt-master/scripts/svg_to_pptx/geometry_properties.py create mode 100644 plugins/codex/plugins/ppt-master/skills/ppt-master/scripts/svg_to_pptx/pptx_package/template_validation.py create mode 100644 plugins/codex/plugins/ppt-master/skills/ppt-master/scripts/template_fill_pptx/diagram_read.py diff --git a/config/external-sources.lock.json b/config/external-sources.lock.json index 64d6e55d..0c419de1 100644 --- a/config/external-sources.lock.json +++ b/config/external-sources.lock.json @@ -87,8 +87,8 @@ "repo": "https://github.com/hugohe3/ppt-master.git", "ref": "main", "adapter": "claude-skill", - "commit": "3f3f2418163ccb438d010f3acbce4a3651b758a5", - "syncedAt": "2026-07-10T16:00:00Z" + "commit": "dbf1e363abb4dba36f7c883ee7ba1495073394d0", + "syncedAt": "2026-07-11T15:59:59Z" }, { "id": "next-skills", @@ -96,8 +96,8 @@ "repo": "https://github.com/vercel/next.js.git", "ref": "canary", "adapter": "skill-collection", - "commit": "46681d90f0fd92bb22fbf38b43b507faad47a812", - "syncedAt": "2026-07-10T16:00:00Z" + "commit": "1bd2fd585aac793ca2589e6f18f17a412fd11005", + "syncedAt": "2026-07-11T15:59:59Z" } ] } diff --git a/plugins/codex/plugins/mcp-playwright/MCP_SOURCE.json b/plugins/codex/plugins/mcp-playwright/MCP_SOURCE.json index b8f84f38..709a252d 100644 --- a/plugins/codex/plugins/mcp-playwright/MCP_SOURCE.json +++ b/plugins/codex/plugins/mcp-playwright/MCP_SOURCE.json @@ -3,5 +3,5 @@ "name": "playwright浏览器自动化操作", "version": "20260605", "keySource": "none", - "syncedAt": "2026-07-10T16:01:26Z" + "syncedAt": "2026-07-11T16:01:50Z" } diff --git a/plugins/codex/plugins/next-skills/THIRD_PARTY_SOURCE.json b/plugins/codex/plugins/next-skills/THIRD_PARTY_SOURCE.json index 28e58567..e411eb28 100644 --- a/plugins/codex/plugins/next-skills/THIRD_PARTY_SOURCE.json +++ b/plugins/codex/plugins/next-skills/THIRD_PARTY_SOURCE.json @@ -2,8 +2,8 @@ "sourceId": "next-skills", "repo": "https://github.com/vercel/next.js.git", "ref": "canary", - "commit": "46681d90f0fd92bb22fbf38b43b507faad47a812", + "commit": "1bd2fd585aac793ca2589e6f18f17a412fd11005", "adapter": "skill-collection", "sourcePath": "skills", - "syncedAt": "2026-07-10T16:00:00Z" + "syncedAt": "2026-07-11T15:59:59Z" } diff --git a/plugins/codex/plugins/ppt-master/README.md b/plugins/codex/plugins/ppt-master/README.md index da4de955..86f765c2 100644 --- a/plugins/codex/plugins/ppt-master/README.md +++ b/plugins/codex/plugins/ppt-master/README.md @@ -90,7 +90,7 @@ English | [中文](./README_CN.md) --- -Drop in your source material, and the deck you get back is **more than just editable**: it has native slide transitions and entrance animations, speaker notes that can become audio narration, charts and tables that can ship as real data-backed PowerPoint objects, and it can follow your own PPT template — a complete deck you can present as-is and keep refining. How to use each capability → [Getting Started](./docs/getting-started.md). +Drop in your source material, and the deck you get back is **more than just editable**: it has native slide transitions plus opt-in entrance animations (off by default), speaker notes that can become audio narration, charts and tables that can ship as real data-backed PowerPoint objects, and it can follow your own PPT template — a complete deck you can present as-is and keep refining. How to use each capability → [Getting Started](./docs/getting-started.md). ## Product Positioning @@ -306,7 +306,7 @@ AI: Sure. Let's confirm the design spec: The AI handles everything — content analysis, visual design, SVG generation, and PPTX export. -> **Output:** Native-shapes `.pptx` (directly editable) saved to `exports/_.pptx`. A copy of `svg_output/` is always snapshotted to `backup//svg_output/` for re-export / archival. Pass `--svg-snapshot` to additionally emit an SVG-image preview pptx alongside the native pptx in `exports/` (see [FAQ](./docs/faq.md)). Requires Office 2016+. By default charts and tables export as SVG-derived shapes (pixel-consistent across PowerPoint / Keynote / WPS); pass `--native-objects` to instead emit them as **real editable PowerPoint chart / table objects backed by data** (rendering may vary across apps), saved as `exports/__native_charts.pptx`. +> **Output:** The SVG pipeline has one PPTX export route: PPT Master's converter reads `svg_output/` and writes a directly editable native DrawingML deck to `exports/_.pptx`. Step 7 still always runs `finalize_svg.py`, producing self-contained files in `svg_final/` for visual inspection or manual insertion as SVG pictures; PowerPoint's manual **Convert to Shape** command is outside the supported contract. A copy of `svg_output/` is always snapshotted to `backup//svg_output/` for re-export / archival. By default charts and tables export as SVG-derived shapes (pixel-consistent across PowerPoint / Keynote / WPS); pass `--native-objects` to instead emit them as **real editable PowerPoint chart / table objects backed by data** (rendering may vary across apps), saved as `exports/__native_charts.pptx`. > **Already have a `.pptx` you want to reuse?** Hand the AI that deck plus your material and ask it to "fill this deck with the new content" — it fills text, table, and chart data into your existing design and exports only the pages you pick, staying natively editable. See the [FAQ](./docs/faq.md) and [template-fill workflow](./skills/ppt-master/workflows/template-fill-pptx.md). diff --git a/plugins/codex/plugins/ppt-master/THIRD_PARTY_SOURCE.json b/plugins/codex/plugins/ppt-master/THIRD_PARTY_SOURCE.json index 21320ad4..1949a596 100644 --- a/plugins/codex/plugins/ppt-master/THIRD_PARTY_SOURCE.json +++ b/plugins/codex/plugins/ppt-master/THIRD_PARTY_SOURCE.json @@ -2,8 +2,8 @@ "sourceId": "ppt-master", "repo": "https://github.com/hugohe3/ppt-master.git", "ref": "main", - "commit": "3f3f2418163ccb438d010f3acbce4a3651b758a5", + "commit": "dbf1e363abb4dba36f7c883ee7ba1495073394d0", "adapter": "claude-skill", "sourcePath": "skills/ppt-master", - "syncedAt": "2026-07-10T16:00:00Z" + "syncedAt": "2026-07-11T15:59:59Z" } diff --git a/plugins/codex/plugins/ppt-master/skills/ppt-master/SKILL.md b/plugins/codex/plugins/ppt-master/skills/ppt-master/SKILL.md index 6e81d7a5..7cd3a3de 100644 --- a/plugins/codex/plugins/ppt-master/skills/ppt-master/SKILL.md +++ b/plugins/codex/plugins/ppt-master/skills/ppt-master/SKILL.md @@ -16,7 +16,8 @@ description: "多格式源文档到高质量 SVG 页面再导出 PPTX 的多阶 | Any route that authors or regenerates slide visuals through SVG | `svg_output/` is the complete page-design source: every visible text, image, shape, chart/table fallback, and layout element that should appear on the exported slide is present in that page SVG or referenced by it. | | Templates, `design_spec.md`, and `spec_lock.md` | Authoring/control inputs. They guide SVG creation but MUST NOT supply visible slide content that is absent from the completed SVG during export. | | Semantic SVG markers | Minimal rendering-neutral compiler hints used only after existing Layout/Layer/Placeholder/Native metadata has been considered. They never replace native SVG geometry, text, styles, grouping, or asset references. | -| SVG-to-PPTX export | Translation only: map SVG content to DrawingML/native objects and reorganize represented content into Master/Layout/Slide structure without inventing new visible page content. | +| `svg_final/` | Mandatory derived, self-contained SVG visual preview. It may be opened directly or inserted into PowerPoint as an SVG picture, but it is not a supported PPTX source and carries no manual Convert-to-Shape compatibility contract. | +| SVG-to-PPTX export | The only supported generated-PPTX route reads `svg_output/` and maps its content through the project converter to DrawingML/native objects. It may reorganize represented content into Master/Layout/Slide structure but MUST NOT invent new visible page content. | | Direct PPTX and presentation-behavior workflows | Remain separate. `template-fill-pptx`, `native-enhance-pptx`, animations, transitions, speaker notes, narration, and package relationships are not required to round-trip through SVG. | **MUST — page-design closure**: For an SVG-authoring route, inspect the final page SVG to determine what the exported slide looks like. Do not reinterpret “SVG is the page-design language” as “SVG is the complete PPTX package description language.” @@ -78,7 +79,7 @@ description: "多格式源文档到高质量 SVG 页面再导出 PPTX 的多阶 | Script | Purpose | |--------|---------| | `${SKILL_DIR}/scripts/source_to_md.py` | Unified source-to-Markdown dispatcher — default Step 1 entry for explicit file(s) or URL(s) | -| `${SKILL_DIR}/scripts/pptx_intake.py` | Standard PPTX intake enrichment — canvas / identity / slide geometry / tables / native chart data | +| `${SKILL_DIR}/scripts/pptx_intake.py` | Standard PPTX intake enrichment — canvas / identity / slide geometry / tables / native chart data / SmartArt structure | | `${SKILL_DIR}/scripts/project_manager.py` | Project init / validate / manage | | `${SKILL_DIR}/scripts/icon_sync.py` | Copy chosen library icons into `/icons/` at selection time; missing names reported + non-zero (re-pick gate) | | `${SKILL_DIR}/scripts/analyze_images.py` | Image analysis | @@ -197,7 +198,7 @@ For PPTX sources, `import-sources` automatically runs the standard intake enrich python3 ${SKILL_DIR}/scripts/pptx_intake.py /sources/ -o /analysis ``` -For each PPTX it writes `.identity.json` (canvas, theme palette/fonts, observed usage) and `.slide_library.json` (text slots, geometry, native tables, native chart caches), and merges that deck's Strategist-facing digest into the single multi-deck index `analysis/source_profile.json` (`decks[]`, one self-contained entry per source deck, with prefixed artifact pointers). In the main generation path these are source facts and recommendation candidates, not replica constraints; beautify and template-fill workflows decide separately which fields become locked constraints. +For each PPTX it writes `.identity.json` (canvas, theme palette/fonts, observed usage) and `.slide_library.json` (text slots, geometry, native tables, native chart caches, SmartArt nodes/connections), and merges that deck's Strategist-facing digest into the single multi-deck index `analysis/source_profile.json` (`decks[]`, one self-contained entry per source deck, with prefixed artifact pointers). In the main generation path these are source facts and recommendation candidates, not replica constraints; beautify and template-fill workflows decide separately which fields become locked constraints. Multi-deck: several PPTX files may be imported into one main-pipeline project — each gets its own `.*` artifacts and a deck entry in `source_profile.json`. `source_profile.json` stays the single must-read index (one entry for a one-deck project, several for a combined-source project). Stems must be distinct; re-importing the same stem replaces that deck's entry. The beautify / template-fill workflows remain single-deck (1:1 to one chosen source deck) and read that deck's `.*` artifacts. @@ -217,11 +218,12 @@ Multi-deck: several PPTX files may be imported into one main-pipeline project Do **not** reinterpret this boundary as 1:1 redesign or free SVG generation. Use `template-fill` for raw PPTX template + generated PPTX requests; use `beautify` only when the source deck's page count, order, and wording are preserved. -**Template flow triggers ONLY on explicit directory paths** supplied by the user in their initial message. The trigger rule is mechanical, not interpretive: +**Template flow triggers ONLY on explicit directory paths** supplied by the user in their initial message, plus one narrow workflow handoff: a project-scoped `create-template` run in the current conversation may pass its exact validated `/templates/` output directly into this Step. The trigger rule is mechanical, not interpretive: | User input contains | Step 3 action | |---|---| | One or more explicit template directory paths (each resolves to a directory containing `design_spec.md` with `kind: brand` / `kind: layout` / `kind: deck` in its YAML frontmatter) | Read each spec's `kind`, dispatch per the kind matrix below, fuse if multiple | +| Current `create-template` workflow just completed project scope and validated its exact `/templates/` output | Consume that single directory in place; it cannot join multi-path fusion | | Anything else — bare template names ("用 academic_defense"), style descriptions ("麦肯锡风格"), brand mentions ("招商银行风格"), vague intent ("想用个模板"), or silence | Skip Step 3, free design | There is no slug matching, no name lookup, no fuzzy resolution. A name without a path does not trigger — the user must give a path the AI can `cd` into. @@ -261,16 +263,40 @@ The architecture has three independent reference bundles. Full schema in [`docs/ | `kind: deck` | `design_spec.md` + template SVGs → `/templates/`; logos / backgrounds / other **bitmaps** → `/images/`. Strategist locks all segments; Strategist confirmation stage narrows to deck-content fields (audience / page count / outline / tone tweaks). | ```bash -TEMPLATE_DIR= +TEMPLATE_DIR="" +PROJECT_TEMPLATES="/templates" +resolve_path() { + python3 -c 'from pathlib import Path; import sys; print(Path(sys.argv[1]).resolve())' "$1" +} # Bitmaps join the project's single runtime image pool (images/, referenced as # ../images/); the spec + template SVGs + other non-image assets stay in # templates/ as design reference the Strategist/Executor read but never render. -cp -r ${TEMPLATE_DIR}/* /templates/ -find /templates -type f \( -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.gif' -o -iname '*.webp' -o -iname '*.bmp' \) -exec mv {} /images/ \; +if [ "$(resolve_path "${TEMPLATE_DIR}")" = "$(resolve_path "${PROJECT_TEMPLATES}")" ]; then + # Project-scoped create-template output is already staged in place. + true +else + cp -r "${TEMPLATE_DIR}"/. "${PROJECT_TEMPLATES}/" + find "${PROJECT_TEMPLATES}" -type f \( -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.gif' -o -iname '*.webp' -o -iname '*.bmp' \) -exec mv {} "/images/" \; +fi ``` The same split applies to all three kinds — bitmaps always land in `images/`, the rest in `templates/`. The spec's `kind` field tells Strategist how to read the `templates/` side; downstream code doesn't distinguish. (Template SVGs in `templates/` are reference material only — the rendered pages live in `svg_output/` and reference images via `../images/`.) +When `create-template` used project output scope, its directory is already the +target project's `templates/` root and its bitmap/icon runtime copies are already +in their final project pools. Resolve both paths before copying: equality means +**in-place consumption**, so skip both the copy and bitmap move. An in-place +directory is one complete bundle and cannot participate in multi-path fusion; +use external library bundles for fusion. Never place the local bundle under a +nested `templates/local_master/` directory because the confirmation and quality +gates read the project `templates/` root. + +A project-scoped bundle belongs only to its target project: its SVGs may refer +to sibling `../images/` and runtime `../icons/` pools that are outside the +template root. Do not copy another project's `templates/` root as an external +bundle. For cross-project reuse, recreate/promote the design with +`create-template` library scope so the package is self-contained. + Legacy template packages may ship `native_structure.json` + `source_template.pptx`; keep the pair together in `/templates/` for backward-compatible `preserve` export. Current `create-template` output does not package this pair: it rebuilds complete, explicitly layered SVG templates instead. During fusion, never mix one legacy contract with another template's source package. The Strategist confirmation stage decides whether the selected template is used `strict` or `adaptive`. Both use `pptx_structure.mode: template` for current templates and map every page to one reference SVG plus one output PowerPoint layout. `strict` keeps the referenced layout contract unchanged; `adaptive` may create a new layout key while keeping the template Master contract. Legacy `preserve` remains strict-only compatibility behavior. @@ -330,26 +356,26 @@ Single-path Step 3 does **not** add provenance (the source is self-evident from The fused frontmatter `kind` describes the resulting bundle: `deck` when both identity and structure are present, `layout` when only structure is present, and `brand` when only identity is present. Keep this field accurate; the Strategist confirmation server uses it to show template adherence only for bundles that actually own page structure. -**✅ Checkpoint — Default path proceeds to Step 4 without user interaction. If the user supplied one or more explicit template paths, those have been dispatched (or fused) into `/templates/` before advancing.** +**✅ Checkpoint — Default path proceeds to Step 4 without user interaction. If the user supplied one or more explicit template paths, those have been copied, staged in place, or fused into `/templates/` before advancing.** --- ### Step 4: Strategist Phase (MANDATORY — cannot be skipped) -🚧 **GATE**: Step 3 complete; default free-design path taken, or (if triggered) template files copied into the project. +🚧 **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: ``` 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–XI section structure. See `strategist.md` Section 1. +> ⚠️ **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. **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. -**`/analysis/` is the project's intermediate-analysis folder: the canonical home for machine-extracted source/asset facts — the PPTX intake bundle (`source_profile.json` index + per-deck `.identity.json` / `.slide_library.json`) and `image_analysis.csv`. It holds facts, not design contracts — `design_spec.md` / `spec_lock.md` stay at the project root.** The MUST-read contract covers only the **compact structured data files (`.json` / `.csv`)**; other artifacts that may live under `analysis/` (e.g. a beautify `source_svg_import/` vector reference package) are NOT bulk-read — they are read selectively only when a specific workflow step calls for them. Before the Strategist confirmation stage, Strategist MUST read the auto-extracted fact files already in `analysis/` — currently `source_profile.json` (PPTX intake), when present. This file is the multi-deck index: read it once for the `decks[]` digests (canvas / chart / table entries per source deck), then open a specific deck's `.identity.json` / `.slide_library.json` only if you need its full raw facts. Use these entries as **factual source context** (format default + content facts); when several decks are present, synthesize across all of them. The source's **palette / typography / visual identity are a reference, not a constraint**: the main pipeline may inherit them where they fit the content and the confirmed style, or design fresh where they don't — the Strategist's judgment, never an obligation to either keep or discard. (Template-fill preserves the native source design by editing cloned slides directly; beautify defaults to the source identity but still follows the confirmed values; the main pipeline treats source identity as reference only and defaults to fresh design.) (`image_analysis.csv` lands later, at the image-analysis step below, and is the authoritative regenerated image-fact view there — re-derived from the live `images/` folder, not a durable store.) +**`/analysis/` is the project's intermediate-analysis folder: the canonical home for machine-extracted source/asset facts — the PPTX intake bundle (`source_profile.json` index + per-deck `.identity.json` / `.slide_library.json`) and `image_analysis.csv`. It holds facts, not design contracts — `design_spec.md` / `spec_lock.md` stay at the project root.** The MUST-read contract covers only the **compact structured data files (`.json` / `.csv`)**; other artifacts that may live under `analysis/` (e.g. a beautify `source_svg_import/` vector reference package) are NOT bulk-read — they are read selectively only when a specific workflow step calls for them. Before the Strategist confirmation stage, Strategist MUST read the auto-extracted fact files already in `analysis/` — currently `source_profile.json` (PPTX intake), when present. This file is the multi-deck index: read it once for the `decks[]` digests (canvas / chart / table / SmartArt entries per source deck), then open a specific deck's `.identity.json` / `.slide_library.json` only if you need its full raw facts. Use these entries as **factual source context** (format default + content facts); when several decks are present, synthesize across all of them. The source's **palette / typography / visual identity are a reference, not a constraint**: the main pipeline may inherit them where they fit the content and the confirmed style, or design fresh where they don't — the Strategist's judgment, never an obligation to either keep or discard. (Template-fill preserves the native source design by editing cloned slides directly; beautify defaults to the source identity but still follows the confirmed values; the main pipeline treats source identity as reference only and defaults to fresh design.) (`image_analysis.csv` lands later, at the image-analysis step below, and is the authoritative regenerated image-fact view there — re-derived from the live `images/` folder, not a durable store.) -**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 `.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, and chart data values come from these (`ppt_to_md` now transcribes native chart data into Markdown tables). **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 `.md`, not scanned directly in the main pipeline. The `analysis/` chart / table entries are a **structural digest** for outline decisions (which slides carried charts, type, series names) — not a second copy of the values; do NOT also pull chart values from `.slide_library.json` in the main pipeline. The `.slide_library.json` full structured data is owned by the direct-PPTX workflows: template-fill uses it as the native fill contract; beautify uses it for native chart / table data while keeping slide text from the Markdown. +**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 `.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 `.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 `.slide_library.json` in the main pipeline. The `.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`): @@ -641,18 +667,19 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py > ⚠️ Run the three sub-steps **one at a time** — each must complete successfully before the next. > ❌ **NEVER** combine them into a single code block or shell invocation. -Canonical three-command pipeline (mirrors `references/shared-standards.md` §5): +Canonical three-command pipeline (this step is the workflow authority; +`references/shared-standards.md` §5 points here): **Step 7.1** — Split speaker notes: ```bash python3 ${SKILL_DIR}/scripts/total_md_split.py ``` -**Step 7.2** — SVG post-processing (icon embedding / image crop & embed / raster image optimization / text flattening / rounded rect to path): +**Step 7.2** — SVG post-processing (icon embedding / image crop & embed / raster image optimization / text flattening): ```bash python3 ${SKILL_DIR}/scripts/finalize_svg.py ``` -Default raster handling for `svg_final/`: images are embedded at the rendered SVG size budget (`--image-scale 2`, `--max-dimension 2560`), opaque PNG photos may be written as JPEG, and transparent assets remain PNG. Use `--no-compress` or a higher `--max-dimension` only for diagnostic / high-fidelity SVG snapshots. +This mandatory step writes self-contained visual-preview SVGs to `svg_final/`. Those files may be opened directly or manually inserted into PowerPoint as SVG pictures. Default raster handling embeds images at the rendered SVG size budget (`--image-scale 2`, `--max-dimension 2560`); opaque PNG photos may be written as JPEG, and transparent assets remain PNG. The existing EMF/WMF exception still applies: Office vector assets stay externally referenced for lossless native-PPTX passthrough, so the native PPTX remains the source of truth for pages that use them. Use `--no-compress` or a higher `--max-dimension` only for diagnostic / high-fidelity SVG previews. **Step 7.3** — Export PPTX (embeds speaker notes by default): ```bash @@ -663,9 +690,6 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py # backup//templates/{native_structure.json,source_template.pptx} # ← preserve mode only # backup//spec_lock.md ← preserve mode only -# -# Add --svg-snapshot to additionally emit the SVG-image preview pptx alongside the native pptx: -# exports/__svg.pptx ← SVG preview pptx (reads svg_final/) # Add --native-objects to emit real editable chart/table objects instead of flattened shapes: # exports/__native_charts.pptx ← native chart/table objects (data-pptx-native markers) # Re-export with --recorded-narration audio (generate-audio workflow) embeds per-slide narration: @@ -686,11 +710,19 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py > The `svg_output/` > snapshot in `backup//` is always written so the project can be > re-exported from frozen SVG sources without re-running the LLM. The SVG-rendered -> preview pptx is opt-in via `--svg-snapshot`. Preserve mode also backs up the -> paired native structure/source files and `spec_lock.md` under the same timestamp. -> Live preview already provides the -> SVG visual reference, so it's only needed when you want a self-contained file -> to share. Pass `-s output` or `-s final` to force a single source if you need it. +> preview remains the mandatory `svg_final/` artifact from Step 7.2; it is not +> packaged as a second PPTX. Preserve mode also backs up the paired native +> structure/source files and `spec_lock.md` under the same timestamp. Use the +> default source selection for release exports. `-s final` is diagnostic-only +> when comparing conversion behavior against the post-processed SVGs; it does +> not change `svg_output/` ownership or establish a supported release route. + +> **Supported PPTX boundary** — the only supported generated-PPTX path is +> `svg_output/` → the project SVG-to-DrawingML converter → native PPTX. The +> project does not emit an SVG-image PPTX and does not support PowerPoint's +> manual **Convert to Shape** operation on `svg_final/`. Inserted `svg_final/` +> pages remain ordinary SVG pictures unless the user independently accepts the +> results of an unsupported Office conversion. > **PPTX structure mode** — native export first reads > `spec_lock.md` `pptx_structure.mode`, then falls back to `baseline` when the @@ -776,6 +808,21 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py > template use stay on this deterministic route. Adaptive pages may define new > layout keys, but they repeat the same Master layer and one internally > consistent Layout/placeholder contract. +> Template export also installs the locked `typography.title` size into every +> Master `titleStyle` level and the locked `typography.body` size into every +> `bodyStyle` and `otherStyle` level. Each text-bearing Layout placeholder also +> writes its prototype run size to `a:lstStyle/a:lvl1pPr/a:defRPr@sz`, so a +> newly inserted or reset placeholder keeps that Layout's local size before it +> falls back to the Master. Generated slide runs and Layout prompt runs keep +> their direct sizes. Missing or invalid locked title/body sizes fail template +> export. Baseline, preserve, and flat modes do not apply either text-default +> update. +> Before publishing the temporary PPTX, template export reopens the finished +> package and verifies `Presentation → Master ↔ Layout ← Slide` registration, +> named custom Layout parts and content types, collision-free placeholder +> identities, prototype bounds, and prompt/level-one sizes. This read-back gate +> is template-only and does not compare later same-Layout slides' local geometry +> or direct text formatting. > In template mode, `pptx_layouts` contains exactly one locked > layout key/name per page; reuse a key for a shared structure instead of > creating one key per content instance. @@ -801,11 +848,26 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py > claiming editability. **Optional animation flags** (page transitions are on by default; per-element entrance is off by default — turn it on only when the user asks for it): -- `-t ` — page transition. Default `fade`. Options: `fade` / `push` / `wipe` / `split` / `strips` / `cover` / `random` / `none`. +- `-t ` — page transition. Default `fade`. Options: `fade` / `push` / `wipe` / `split` / `strips` / `cover` / `random` / `none`. `none` removes only the visual transition; an explicit automatic advance remains valid. - `-a ` — per-element entrance animation. **Default `none`** — pages appear as a whole, no auto-firing element builds (the unsolicited cascade reads as the "AI deck" tell). Opt in with `auto` (map effect from group id: chart→wipe, card-/step-/pillar-→fly, title/takeaway→fade; image-like ids `hero` / `figure-` / `image` / `img-` / `kpi` cycle a richer pool — zoom / dissolve / circle / box / diamond / wheel — so multiple images vary across the deck), a specific effect like `fade`, or `mixed` for the legacy 16-effect cycle. Requires top-level `` groups (already required by Executor). - `--animation-trigger {on-click,with-previous,after-previous}` — Start mode (matches PowerPoint's animation-pane Start dropdown). Default `after-previous` (click-free cascade; pace via `--animation-stagger`). Use `on-click` for presenter-paced reveals, or `with-previous` for all-at-once. - `--animation-config ` — optional object-level sidecar. Default: `/animations.json` when present. -- `--auto-advance ` — kiosk-style auto-play. +- `--auto-advance ` — kiosk-style auto-play. Click remains enabled, so click or timer may advance the slide. + +**Animation compatibility gate**: the default element animation remains `none`. +When animation is enabled, unknown effects/modes/triggers, invalid numeric or +order values, missing slide/group references, and explicit structural layer, +static-role, or static-placeholder targets fail export; they never downgrade +or disappear silently. An explicit +sidecar group may override only the legacy chrome-name heuristic. `random` +resolution is stable for the same effective input; with `--conversion-trace`, +its resolved rows are written to the trace. Generated export performs per-slide semantic +read-back plus package timing/`p:cTn`/`p:spTgt` validation. Narration merges +audio timing into the existing DOM and preserves animation rows. Direct-PPTX +routes preserve source object animation, compare its object-animation fingerprint +before/after allowed edits, and validate structure; they do not author +animation effects. The exact 22 tuples and OOXML rules live in +[`scripts/docs/pptx-animations.md`](scripts/docs/pptx-animations.md). **Optional custom animations** (only when the user asks to tune animation order/effects/timing for specific objects): @@ -818,11 +880,11 @@ Run the standalone [`generate-audio`](workflows/generate-audio.md) workflow. The Do NOT call `notes_to_audio.py` directly without going through the workflow — `--voice` / `--voice-id` is required and the workflow produces the locale/provider-aware recommendation that makes the choice meaningful. Full effect list, anchor logic, and limits: [`references/animations.md`](references/animations.md). +The compatibility contract covers PowerPoint OOXML; do not promise identical +animation playback in Keynote or other presentation applications. > ❌ **NEVER** substitute `cp` for `finalize_svg.py` — finalize performs multiple critical processing steps -> ❌ **NEVER** force `-s output` for the legacy/preview pptx (PowerPoint's internal SVG parser drops icons and rounded corners). The default auto-split already gives native the high-fidelity source it needs without touching legacy. -> ❌ **NEVER** use `--only` in the standard pipeline. Keep it only for explicit -> one-product diagnostics or compatibility checks. +> ❌ **NEVER** use `-s final` for a release export. It is a diagnostic comparison only; the supported native route reads `svg_output/`. > **Post-export annotation window**: the preview service from Step 6 typically remains running after export. If the user submitted annotations in the browser (during Executor or after export) and now asks to apply them — they may quote the browser prompt (`Changes saved to svg_output...` / `修改已保存到 svg_output...`), say "apply my annotations" / "应用注解" / equivalent — run [`live-preview`](workflows/live-preview.md) Step 2 to apply and re-export. Annotations submitted during generation are also handled here, not earlier. diff --git a/plugins/codex/plugins/ppt-master/skills/ppt-master/references/animations.md b/plugins/codex/plugins/ppt-master/skills/ppt-master/references/animations.md index 091c17fc..44c5ca7b 100644 --- a/plugins/codex/plugins/ppt-master/skills/ppt-master/references/animations.md +++ b/plugins/codex/plugins/ppt-master/skills/ppt-master/references/animations.md @@ -1,17 +1,21 @@ # Page Transitions & Per-Element Animations -PPT Master's exported PPTX supports **page transitions** (slide-to-slide) and **per-element entrance animations** (within a slide). Both are controlled by `svg_to_pptx.py` CLI flags and ship as real OOXML — they animate inside PowerPoint and Keynote, no embedded video. +PPT Master's exported PPTX supports **page transitions** and **per-element +entrance animations** as real PowerPoint OOXML. Other applications may +interpret timing differently; this contract makes no unconditional Keynote guarantee. -## Defaults +## 1. Defaults | Layer | Default | Why | |---|---|---| -| Page transition | `fade`, 0.4s | Calm baseline that suits most decks | +| Page transition | CLI: `fade`, 0.4s | Calm baseline that suits most decks; the public Python builder retains its legacy 0.5s default | | Per-element animation | **`none` (off)** | A page appears as a whole. Auto-firing element builds are an unsolicited "AI deck" tell, so element entrance is opt-in. Turn it on with `-a auto` (or another effect): effects map from group id (chart→wipe, card-/step-/pillar-→fly, title/takeaway→fade); image-like ids (`hero` / `figure-` / `image` / `img-` / `kpi`) cycle a richer visual pool (zoom / dissolve / circle / box / diamond / wheel) so multiple images vary across the deck; unmatched ids cycle a small fade/wipe/fly/zoom pool | -To regenerate a deck with different settings, rerun `svg_to_pptx.py` against the same `svg_output/` (or `svg_final/`) — no need to rerun the LLM. To turn per-element animation on for the whole deck, pass `-a auto`. +To regenerate a deck with different settings, rerun `svg_to_pptx.py` against the same `svg_output/` — no need to rerun the LLM. `-s final` is reserved for diagnostic comparison and is not a supported release source. To turn per-element animation on for the whole deck, pass `-a auto`. -## Custom Object-Level Animation +--- + +## 2. Custom Object-Level Animation Per-element animation is off by default. To enable it deck-wide, pass `-a auto` at export (no config needed). When a deck instead needs specific object timing — for example title first, chart second, annotation last — use the optional `animations.json` sidecar. The SVG remains static visual source; the sidecar only controls PPTX export behavior. @@ -28,18 +32,23 @@ python3 skills/ppt-master/scripts/animation_config.py validate python3 skills/ppt-master/scripts/svg_to_pptx.py ``` -Minimal sidecar: +Single-slide sidecar excerpt (repeat the complete slide block for every SVG in `svg_output/`): ```json { "version": 1, + "defaults": { + "transition": { "effect": "fade", "duration": 0.4 }, + "animation": { "effect": "auto", "duration": 0.4, "stagger": 0.5, "trigger": "after-previous" } + }, "slides": { "03_market": { + "transition": { "effect": "fade", "duration": 0.4 }, + "animation": { "effect": "auto", "duration": 0.4, "stagger": 0.5, "trigger": "after-previous" }, "groups": { "title": { "effect": "fade", "order": 1 }, "chart": { "effect": "wipe", "order": 2, "duration": 0.6 }, - "insight": { "effect": "fly", "order": 3, "delay": 0.2 }, - "footer": { "effect": "none" } + "insight": { "effect": "fly", "order": 3, "delay": 0.2 } } } } @@ -53,31 +62,42 @@ Rules: - `effect: none` removes that group from the entrance sequence. - `order` changes animation order only; it does not change slide layering. - `delay` is seconds before that group starts in `after-previous` mode. -- `duration` overrides the per-group entrance duration. +- `duration` overrides the per-group schedule duration. `appear` remains a 1ms visibility flip; its configured duration spaces the next `after-previous` row. - `--animation none` overrides the sidecar and disables all per-element animation. +- An explicit sidecar group may override the legacy chrome-name heuristic, but it cannot override `data-pptx-layer` or an explicit static role/placeholder marker. +- Unknown effects, modes, or triggers and invalid numeric/order fields fail validation; no fallback effect is substituted. -## Page Transitions +--- + +## 3. Page Transitions ```bash # Pick a different effect python3 skills/ppt-master/scripts/svg_to_pptx.py -t push --transition-duration 0.6 -# Disable +# Remove the visual transition python3 skills/ppt-master/scripts/svg_to_pptx.py -t none # Auto-advance every 5 seconds (kiosk-style playback) python3 skills/ppt-master/scripts/svg_to_pptx.py --auto-advance 5 + +# Auto-advance with no visual transition +python3 skills/ppt-master/scripts/svg_to_pptx.py -t none --auto-advance 5 ``` Available effects: `fade`, `push`, `wipe`, `split`, `strips`, `cover`, `random`. Flags: -- `-t/--transition` — effect name, or `none` to disable. Default: `fade`. +- `-t/--transition` — effect name, or `none` for no visual transition. Default: `fade`. `none` does not remove an explicitly configured automatic advance. - `--transition-duration` — seconds, default `0.4`. -- `--auto-advance` — seconds; omit for presenter-controlled advance. +- `--auto-advance` — seconds; click remains enabled, so the slide advances on click or when the timer expires. Omit for presenter-controlled advance. -## Per-Element Animations +**Hard rule — no silent downgrade**: an unknown transition effect or invalid/non-finite duration fails export. It is never replaced by `fade`. Recorded narration keeps the resolved visual transition; `-t none --recorded-narration ...` writes narration-driven advance timing without restoring a visual effect. + +--- + +## 4. Per-Element Animations Off by default — enable deck-wide with `-a auto` (or another effect). Once enabled, three Start modes are available — these mirror PowerPoint's animation-pane "Start" dropdown: @@ -103,14 +123,16 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py --animation mixed \ --animation-stagger 0.7 --animation-duration 0.5 # All groups animate in unison on slide entry -python3 skills/ppt-master/scripts/svg_to_pptx.py --animation-trigger with-previous +python3 skills/ppt-master/scripts/svg_to_pptx.py -a auto --animation-trigger with-previous ``` 22 single effects: `appear`, `fade`, `fly`, `cut`, `zoom`, `wipe`, `split`, `blinds`, `checkerboard`, `dissolve`, `random_bars`, `peek`, `wheel`, `box`, `circle`, `diamond`, `plus`, `strips`, `wedge`, `stretch`, `expand`, `swivel`. Plus three auto-vary modes: +These names preserve the established filter / `presetID` / `presetSubtype` tuples documented in [`pptx-animations.md`](../scripts/docs/pptx-animations.md#3-compatibility-contract). `cut` is a legacy public key; compatibility promises its existing tuple, not a semantic interpretation inferred from an external preset-id table. + - `auto` (recommended when enabling) — map effect from the group's SVG id. Information-dense elements get a single stable effect: `chart` / `table` / `legend` / `timeline` / `track` → `wipe`; `card-*` / `pillar-*` / `item-*` / `step-*` / `stage-*` / `tier-*` / `principle-*` → `fly`; `title` / `chapter-*` / `section-*` / `cover-*` / `tagline` / `subtitle` → `fade`; `takeaway` / `callout` / `quote` / `source` / `conclusion` / `note` → `fade`. Image-like ids `hero` / `figure-*` / `image` / `img-*` / `kpi` instead cycle a richer visual pool (`zoom` / `dissolve` / `circle` / `box` / `diamond` / `wheel`) so multiple images vary across the deck. Unmatched ids cycle through `fade` / `wipe` / `fly` / `zoom`. - `mixed` (legacy) — deterministic. The first animated group on each slide uses `fade`; later groups cycle through a 16-effect pool (`blinds` / `checkerboard` / `dissolve` / `fly` / `cut` / `random_bars` / `box` / `split` / `strips` / `wedge` / `wheel` / `wipe` / `expand` / `fade` / `swivel` / `zoom`) across the deck. Kept for backward compatibility. -- `random` — samples from the legacy 16-effect pool. +- `random` — samples from the legacy 16-effect pool. Resolution is seeded from the effective deck input, so the same input produces the same choices; `--conversion-trace` records every resolved effect when diagnostics are enabled. `appear` is excluded from every variation pool because it has no visible motion. @@ -124,13 +146,15 @@ Flags: > Note: `--recorded-narration` rejects `on-click`; use `after-previous` or `with-previous` for video-ready narrated decks. -## Anchor Logic — Top-Level `` +--- -Per-element animations are anchored on **top-level `` content groups** in the SVG (e.g. ``, ``). One group = one click reveal. +## 5. Anchor Logic — Top-Level `` + +Per-element animations are anchored on **top-level `` content groups** in the SVG (e.g. ``, ``). One group produces one animation-pane entrance row; whether that row needs a click depends on the selected Start mode. Aim for **3–8 content groups per slide**. This is also the granularity PowerPoint uses for group-select / group-move, so it improves editing ergonomics regardless of animation. -**Chrome groups skip the cascade automatically.** Top-level groups that look like page chrome (background, header/footer, decorations, watermark, page number, nav, logo, dividing rule) are excluded from the click sequence and appear together with the slide. Detection is done on the `id`: after splitting on `-` and `_`, if any token matches `background` / `bg` / `decoration` / `decorations` / `decor` / `header` / `footer` / `chrome` / `watermark` / `pagenumber` / `pagenum` / `nav` / `logo` / `rule`, the group is treated as chrome. Examples that auto-skip: ``, ``, ``, ``, ``, ``, ``, ``, ``. Examples that still animate: ``, ``, ``, ``. Don't strip the `` wrapper to avoid animation — keep it (PowerPoint group-select needs it) and just name it appropriately. +**Chrome groups skip the cascade automatically.** Explicit SVG role and placeholder semantics are authoritative. A group with `data-pptx-layer` or an explicit static role/placeholder marker can never animate. For marker-free legacy SVGs only, top-level groups whose id tokens look like page chrome (background, header/footer, decorations, watermark, page number, nav, logo, dividing rule) are excluded and appear with the slide. An explicit `animations.json` group entry may override this id-name heuristic, but never an explicit structural marker. Examples that auto-skip by legacy id: ``, ``, ``, ``, ``, ``, ``, ``, ``. Examples that still animate: ``, ``, ``, ``. Do not strip the `` wrapper to avoid animation — keep it for PowerPoint group selection and use `effect: none` when the content should remain static. **Fallback for flat SVGs** (no top-level `` wrappers, only raw `` / `` / `` at the root): @@ -139,25 +163,44 @@ Aim for **3–8 content groups per slide**. This is also the granularity PowerPo Executors should wrap logical sections in `` regardless of whether you plan to animate. The Executor reference (`skills/ppt-master/references/shared-standards.md`) requires it. -## Limitations +--- -- **Native shapes mode only.** Per-element animation needs editable shape anchors. `--only legacy` produces one image per slide and has no element granularity to animate; that mode is unaffected by `-a/--animation` and only honors `-t/--transition`. -- **Office version drift on element animations.** Effects use the `` path (vs. `presetID` lookup tables) to stay stable across Office versions. Most filters render identically in PowerPoint 2016+; older Office may downgrade some filters to plain Appear. -- **PNG fallback (compat mode) is for visual rendering only.** Transitions and animations live in the slide XML, not in the PNG, so disabling compat mode does not affect either layer. +## 6. Validation and Read-Back -## Quick Reference +Animation configuration is strict. Export fails on an unknown effect, mode, or trigger; a boolean or non-finite duration/delay/stagger; a non-positive duration; a negative delay/stagger; a non-positive or non-integer order; a missing slide/group reference; or any attempt to animate a structural layer. These errors never downgrade to another effect or silently omit a requested target. + +Generated export reads each slide's timing tree back and checks row count/order, trigger, shape target, resolved effect tuple, duration, and timeline offset. Package validation then checks root timing placement, unique and valid `p:cTn` ids, and every `p:spTgt` reference. The writer does not emit `p:bldP` for groups or pictures. Direct-PPTX preserve mode tolerates unchanged legacy group/picture `p:bldP` rows from earlier PPT Master exports; new generated packages remain strict. + +Narration injection merges audio timing into an existing direct `p:sld/p:timing` DOM and preserves entrance rows. A source timing tree nested in `mc:AlternateContent` or another non-root container fails safely instead of being rewritten or duplicated. Direct-PPTX routes fingerprint source object-animation timing before and after their allowed edits, then run structural package validation; they do not author or normalize animation effects. + +--- + +## 7. Limitations + +- **Native DrawingML output only.** Page transitions and per-element animations are authored on the PPTX produced by the project converter from `svg_output/`. `svg_final/` remains a static SVG visual preview, not an animated or alternate PPTX route. +- **PowerPoint OOXML scope.** Effects preserve their established filter / `presetID` / `presetSubtype` tuples and are validated against the serialized PowerPoint package. Rendering in Keynote, LibreOffice, WPS, or other applications is outside the unconditional compatibility guarantee. +- **Manual SVG shape conversion is unsupported.** Inserting an `svg_final/` page as an SVG picture does not establish element animation anchors; use the native PPTX when editable animated shapes are required. +- **Source extension preservation.** Direct-PPTX routes preserve unknown transition `AlternateContent` when configured to keep the source. When advance timing changes, Choice and Fallback receive the same `advClick` / `advTm` values. + +--- + +## 8. Quick Reference | Goal | Command | |---|---| -| Disable transitions | `-t none` | +| Remove visual transition | `-t none` | | Change transition effect | `-t push` (or any from the list above) | | Slower transition | `--transition-duration 0.8` | | Auto-play | `--auto-advance 5` | | Disable element animation | `-a none` | -| Switch to on-click trigger | `--animation-trigger on-click` | +| Switch to on-click trigger | `-a auto --animation-trigger on-click` | | Use a single effect instead of auto | `--animation fade` | -| All groups animate together | `--animation-trigger with-previous` | -| Slower per-element reveal | `--animation-duration 0.5` | -| Wider gap in after-previous | `--animation-stagger 0.7` | +| All groups animate together | `-a auto --animation-trigger with-previous` | +| Slower per-element reveal | `-a auto --animation-duration 0.5` | +| Wider gap in after-previous | `-a auto --animation-stagger 0.7` | -See also: [`scripts/docs/svg-pipeline.md`](../scripts/docs/svg-pipeline.md) for the full `svg_to_pptx.py` reference. +See also: + +- [`scripts/docs/svg-pipeline.md`](../scripts/docs/svg-pipeline.md) for the full `svg_to_pptx.py` reference. +- [`pptx-transitions.md`](../scripts/docs/pptx-transitions.md) for the shared OOXML writer, MCE preservation, and read-back contract. +- [`pptx-animations.md`](../scripts/docs/pptx-animations.md) for the exact effect tuples, timing-tree rules, and animation package validator. diff --git a/plugins/codex/plugins/ppt-master/skills/ppt-master/references/artifact-ownership.md b/plugins/codex/plugins/ppt-master/skills/ppt-master/references/artifact-ownership.md index c7d31820..51b03d96 100644 --- a/plugins/codex/plugins/ppt-master/skills/ppt-master/references/artifact-ownership.md +++ b/plugins/codex/plugins/ppt-master/skills/ppt-master/references/artifact-ownership.md @@ -10,12 +10,12 @@ Global artifact ownership rules for PPT Master projects. | Artifact | Owner | Role | Read/write contract | |---|---|---|---| -| `sources/` content-type files | Content contract | Main pipeline source for text, tables, and chart data values | Strategist reads content-type files (`.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml`) and judges by content; do not replace values with PPTX geometry JSON in the main pipeline | +| `sources/` content-type files | Content contract | Main pipeline source for text, tables, chart data values, and SmartArt node wording | Strategist reads content-type files (`.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml`) and judges by content; do not replace values with PPTX geometry JSON in the main pipeline | | `sources/` converted-source originals | Source archive | Imported source files that have a converted content contract (`.pdf` / `.pptx` / `.docx` / `.xlsx` / `.html` / `.epub` / `.tex` / `.rst` / `.ipynb` / `.typ`, etc.) and source-adjacent extracted assets | Read via the converted `.md` in the main pipeline; direct-PPTX workflows read the `.pptx` by route | | `sources/*.conversion_profile.json`, `sources/*_files/image_manifest.json` | Pipeline sidecar | Conversion audit record / asset index | NOT read as slide content; open only to audit a conversion or resolve assets | | `analysis/source_profile.json` | Machine fact index | Compact Strategist-facing PPTX intake digest | Main pipeline reads as factual context and recommendation candidates | | `analysis/.identity.json` | Native deck identity facts | Canvas, theme palette/fonts, observed usage | Read selectively when detailed identity facts are needed | -| `analysis/.slide_library.json` | Native PPTX structure facts | Text slots, geometry, native tables, native chart caches | Direct PPTX workflows use as native fill/structure contract | +| `analysis/.slide_library.json` | Native PPTX structure facts | Text slots, geometry, native tables, native chart caches, SmartArt nodes/connections | Direct PPTX workflows use as native fill/structure contract | | `analysis/image_analysis.csv` | Regenerated image fact view | Measured facts about the current `images/` folder | Re-run `analyze_images.py` before reading image facts after changes | | `design_spec.md` | Human design narrative | Explains design intent, outline, rationale, and resource plan | Strategist writes; humans and later roles read for intent | | `spec_lock.md` | Execution contract | Literal colors, typography, icons, images, page rhythm, templates, and charts | Executor re-reads before every page; values must be used verbatim | @@ -27,8 +27,8 @@ Global artifact ownership rules for PPT Master projects. | `svg_output/` | Page-design author source | Main-agent handwritten SVG pages containing the complete visible design | Quality checker and native PPTX export read this as the canonical visual/page-layout source; templates and locks do not add missing visible objects at export | | `notes/total.md` | Speaker-note source | Complete notes before splitting | Step 6 writes; Step 7.1 splits | | `notes/slide_*.md` | Split notes | Per-slide notes generated from `total.md` | Derived by `total_md_split.py` | -| `svg_final/` | Derived preview/export SVGs | Self-contained post-processed SVGs | Rebuild from `svg_output/` with `finalize_svg.py` | -| `exports/` | Delivery artifacts | Native PPTX and optional SVG snapshot PPTX | Step 7.3 writes final outputs | +| `svg_final/` | Derived visual preview | Self-contained post-processed SVGs that may be opened directly or inserted as SVG pictures | Rebuild from `svg_output/` with `finalize_svg.py`; do not use as a supported PPTX source | +| `exports/` | Delivery artifacts | Native DrawingML PPTX and its explicit native-object/narration variants | Step 7.3 writes final outputs from `svg_output/` | | `backup//svg_output/` | Frozen author-source archive | Re-export source without re-running LLM | `svg_to_pptx.py` writes a snapshot during export | | `animations.json` | Optional animation config | Object-level animation sidecar | Created only by explicit animation workflow/request | @@ -38,16 +38,17 @@ Global artifact ownership rules for PPT Master projects. | Invariant | Rule | |---|---| -| Content values | Main pipeline text, tables, and chart values come from content-type files in `sources/` (`.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml`), not from `slide_library.json`. | +| Content values | Main pipeline text, tables, chart values, and SmartArt node wording come from content-type files in `sources/` (`.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml`), not from `slide_library.json`. | | Sources read policy | In `sources/`, read content-type files (`.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml`) and judge by content — a `.json` / `.csv` may be core content or just data. Exclude known sidecars: `*.conversion_profile.json` and `*_files/image_manifest.json`. `analysis/` facts (`source_profile.json`, `.slide_library.json`) are read per Step 4 / direct-PPTX workflow, not in the `sources/` content scan. | -| PPTX structure | `slide_library.json` owns native geometry and slot facts for direct PPTX workflows. | +| PPTX structure | `slide_library.json` owns native geometry, slot facts, and SmartArt layout/relationships for direct PPTX workflows. | | Design contract | `design_spec.md` explains; `spec_lock.md` executes. Executor must not infer execution values from prose. | | Image facts | `images/` is live state; `analysis/image_analysis.csv` is a regenerated view, not a durable cache. | | SVG source | `svg_output/` is the only author source for generated pages. | | Page-design closure | On SVG-authoring routes, every visible exported-slide object exists in the corresponding page SVG or an explicitly referenced visual asset. | | Package-behavior separation | Speaker notes, animations, transitions, narration, and direct native-PPTX workflows keep their owning artifacts; do not force them into SVG metadata. | -| Post-processed SVG | `svg_final/` is disposable and must be rebuildable from `svg_output/`. | -| Export source | Native PPTX export reads `svg_output/` by default. SVG snapshot export reads `svg_final/` only when requested. | +| Post-processed SVG | `svg_final/` is disposable, must be rebuilt in Step 7.2, and serves only as a self-contained visual preview / manually insertable SVG picture. | +| Export source | The only supported generated-PPTX route reads `svg_output/` through the project SVG-to-DrawingML converter. A diagnostic `-s final` override does not change ownership or create a supported release route. | +| Shape-conversion boundary | PowerPoint's manual Convert-to-Shape operation on `svg_final/` is outside the project compatibility contract. | | Confirmation | Final `confirm_ui/result.json` or chat confirmation overrides recommendations. | **Forbidden - mixed ownership**: Do not copy chart values from Markdown into `analysis/` by hand, do not edit `svg_final/` as the source of a fix, and do not treat `design_spec.md` prose as a replacement for `spec_lock.md`. @@ -62,6 +63,5 @@ Global artifact ownership rules for PPT Master projects. | `notes/slide_*.md` | `notes/total.md` | `python3 ${SKILL_DIR}/scripts/total_md_split.py ` | | `svg_final/` | `svg_output/` plus project assets | `python3 ${SKILL_DIR}/scripts/finalize_svg.py ` | | Native PPTX | `svg_output/` plus notes/assets | `python3 ${SKILL_DIR}/scripts/svg_to_pptx.py ` | -| SVG snapshot PPTX | `svg_final/` | `svg_to_pptx.py --svg-snapshot` | **Default - regenerate derived views**: When a source artifact changes, regenerate the derived artifact at the owning step instead of patching the derived file directly. diff --git a/plugins/codex/plugins/ppt-master/skills/ppt-master/references/executor-base.md b/plugins/codex/plugins/ppt-master/skills/ppt-master/references/executor-base.md index 8e3e3378..9ce469ad 100644 --- a/plugins/codex/plugins/ppt-master/skills/ppt-master/references/executor-base.md +++ b/plugins/codex/plugins/ppt-master/skills/ppt-master/references/executor-base.md @@ -6,6 +6,8 @@ **Hard rule — minimal semantics without semantic loss**: `baseline` / free-design roots declare `data-pptx-page-role`; `template` / `preserve` roots already use `data-pptx-layout` and do not duplicate that identity. Add `data-pptx-role` only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by layer, placeholder, or native-object metadata; the marked element uses a stable unique `id`. Ordinary page content keeps normal SVG structure without duplicate semantic classification. 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. --- @@ -262,7 +264,7 @@ grep "chart-plot-area" /svg_output/.svg - **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 connector 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 `` or `` 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. Examples of this technique appear in many imported corporate decks; see `projects/01_template_import/svg_output/slide_01.svg` shape-158 for a reference (gradient-filled inward-pointing arrow). 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. Full rules in shared-standards.md §6. +- **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 Native Object Metadata Marker (MANDATORY on eligible data-chart and text-grid table pages) @@ -280,7 +282,7 @@ grep "chart-plot-area" /svg_output/.svg - 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 `` 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.) when role sizes differ; if omitted, the exporter infers shared font family and base chart text size from visible fallback text inside the native marker. 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. If a fallback role has no explicit size, use the compact three-tier chart defaults from [shared-standards.md](shared-standards.md). +- 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; the native object is a data-editable counterpart with PowerPoint-default styling that users restyle by hand after export. Never simplify the SVG design to match what a native object could show. @@ -500,21 +502,21 @@ Auto-split `notes/total.md` into per-page files in `notes/`. > **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. -**Post-processing & Export** (same canonical pipeline as [shared-standards.md §5](shared-standards.md)): +**Post-processing & Export** (canonical workflow: [`SKILL.md` Step 7](../SKILL.md)): ```bash # 1. Split speaker notes python3 scripts/total_md_split.py -# 2. SVG post-processing (auto-embed icons, images, etc.) +# 2. SVG post-processing (auto-embed icons/images and flatten positioned text) python3 scripts/finalize_svg.py +# Output: svg_final/ self-contained SVG visual previews # 3. Export PPTX python3 scripts/svg_to_pptx.py # Output (default-flow mode): # exports/_.pptx ← native pptx (canonical output) # backup//svg_output/ ← Executor SVG source backup (always written) -# -# Add --svg-snapshot to additionally emit: -# exports/__svg.pptx ← SVG snapshot pptx (sibling of native pptx) ``` + +`svg_final/` may be opened directly or manually inserted into PowerPoint as an SVG picture. It is not a second PPTX route. Use `-s final` only for converter diagnostics; release exports use the default `svg_output/` source. Manual Convert-to-Shape behavior is unsupported. diff --git a/plugins/codex/plugins/ppt-master/skills/ppt-master/references/image-layout-patterns.md b/plugins/codex/plugins/ppt-master/skills/ppt-master/references/image-layout-patterns.md index 04bcbf7d..06476304 100644 --- a/plugins/codex/plugins/ppt-master/skills/ppt-master/references/image-layout-patterns.md +++ b/plugins/codex/plugins/ppt-master/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 per 24. **Custom path crop (blob, arrow, leaf, silhouette)** — ``; allows any curved or organic shape. PowerPoint export translates this to `custGeom` and survives roundtrip. -25. **Layered paper-cut stack** — multiple image or shape layers each with `clipPath` + a small `` offset to fake physical layering depth. Each layer casts a shadow onto the next, producing real-looking craft depth. +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. 26. **Triptych baked into a single wide image** — one wide `` 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. @@ -170,9 +170,9 @@ Stack any of these freely on top of a Primary structure. Multiple Modifiers per 33. **Spotlight mask — clear region surrounded by darkness** — cover the canvas with `` filled by a `` whose inner stop is fully transparent and outer stop is opaque dark. Reads as a flashlight beam on the focal area. Use sparingly — it kills everything outside the spotlight. -34. **Gaussian-blur backdrop** — `` applied to the background image, with sharp content layered on top unblurred. Reads as depth-of-field. Be aware that filters have inconsistent PPT export support — if fidelity matters, bake the blur into the source image instead. +34. **Gaussian-blur backdrop** — blur the background in the source image, then layer sharp SVG content above it. Native filter export maps the supported blur graph to a glow/shadow effect; it does not preserve a blurred-image backdrop. -35. **Duotone treatment** — two-color mapping of a photograph (e.g. deep navy shadows + warm cream highlights). Most reliable when baked into the source image at generation time. Runtime SVG duotone via `` + `` is possible but the filter chain is fragile through PPT export — only attempt if you control the renderer. +35. **Duotone treatment** — two-color mapping of a photograph (e.g. deep navy shadows + warm cream highlights). Bake it into the source image; the native PPT route does not support a runtime duotone filter chain. 36. **Drop shadow under image panel** — `` applied to the image's container `` (or to the `` itself). Standard depth lift. @@ -204,7 +204,7 @@ Stack any of these freely on top of a Primary structure. Multiple Modifiers per 67. **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. SVG-level `` is forbidden in this project (PPT export breaks). The only reliable way: bake this effect into the image at generation time by prompting for "large lettering revealing the underlying scene through letterforms." Treat as a pre-rendered artistic choice, not a runtime effect. +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. 69. **Image rotated at a slight angle for editorial feel** — `transform="rotate(angle cx cy)"` on the `` or its container ``; 2–6 degrees typical. Adds dynamism without breaking layout. @@ -252,9 +252,10 @@ 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. -- `` on `` and transparency encoding (`fill-opacity` / `stop-opacity`, never `rgba()`) — authoritative form in [`shared-standards.md`](shared-standards.md) §1.2 and §2; do not restate or relax here. -- No ``, no `` for alpha compositing. Alpha-effect routing (gradient overlays, clipPath crops, filter shadows, baked-in source image) is the table in [`shared-standards.md`](shared-standards.md) §1.0. -- `` / `` are accepted but PPT export is inconsistent — bake into the source image when fidelity is critical. +- All project-wide SVG compatibility exceptions and conditional mappings are + owned by [`shared-standards.md`](shared-standards.md). This catalog neither + restates nor relaxes that contract; each pattern records only its + scenario-specific rendering choice. --- diff --git a/plugins/codex/plugins/ppt-master/skills/ppt-master/references/shared-standards.md b/plugins/codex/plugins/ppt-master/skills/ppt-master/references/shared-standards.md index 1decf297..05fe67b3 100644 --- a/plugins/codex/plugins/ppt-master/skills/ppt-master/references/shared-standards.md +++ b/plugins/codex/plugins/ppt-master/skills/ppt-master/references/shared-standards.md @@ -1,12 +1,68 @@ # Shared Technical Standards -Common technical constraints for PPT Master, eliminating cross-role file duplication. +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. + +**Document map**: + +| Section | Owns | Strength | +|---|---|---| +| §1 Required Foundation, Forbidden Features, and Conditional Interfaces | XML validity, the exhaustive structural blacklist, native line ends, image clipping, and static local reuse | Required / Forbidden / Conditional | +| §2 Conditional Compatibility Mappings | Inline geometry and approximate group opacity | Conditional | +| §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 | +|---|---|---| +| Color and transparency | CSS alpha colors; fill, stroke, text, picture, stop, element, and 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 | +| 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 — one-way fidelity vocabulary**: the labels above describe the +`svg_output/` → generated PPTX path. They do not promise reconstruction of the +original SVG syntax, `` graph, `` structure, path commands, or +`` 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. SVG Banned Features Blacklist - -The following are **forbidden** in generated SVGs — PPT export breaks otherwise: +## 1. Required Foundation, Forbidden Features, and Conditional Interfaces ### 1.0 Text characters: must be well-formed XML @@ -17,7 +73,7 @@ SVG is strict XML. Two rules for all text and attribute values: | 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. Numeric refs (` ` / ` `) are XML-legal but discouraged. +One offending character invalidates the file and aborts export. **Structural blacklist** (in addition to the character rules above): @@ -25,139 +81,169 @@ One offending character invalidates the file and aborts export. Numeric refs (`& |----------------|-------------| | `mask` | Masks | | `