Skip to content

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

docs(svg-effects): define clipped picture carriers

hugohe378d4e00ae969
diff --git a/docs/powerpoint-svg-mapping.md b/docs/powerpoint-svg-mapping.md
index d6628345..006705fe 100644
--- a/docs/powerpoint-svg-mapping.md
+++ b/docs/powerpoint-svg-mapping.md
@@ -145,7 +145,7 @@ preset selection and authoring behavior are documented in
| Crop picture to fill | One registered alignment plus explicit `slice` | Native `a:srcRect` crop | `Native-stable` when source dimensions are readable | Alignment is case-sensitive; unknown modes and extra tokens are errors |
| Fit picture inside frame | Omitted default, or one registered alignment plus explicit `meet` | Native fitted picture frame | `Native-normalized` | Alignment-only shorthand is compatible input that receives a normalization recommendation |
| Picture transparency | Atomic image `opacity` | Native `a:alphaModFix` | `Native-stable` | Value must be finite and within the accepted opacity grammar |
-| Picture shadow or glow | One registered effect filter on `<image>`; imported crops use the private outer carrier | Native `p:pic/p:spPr/a:effectLst` | `Approximate`; one effect round-trips | Other primitives, effect DAGs, and multiple independent effects remain unsupported |
+| Picture shadow or glow | One registered effect filter directly on an unclipped `<image>`; a clipped image or imported crop uses its exact single-picture outer carrier | Native `p:pic/p:spPr/a:effectLst` | `Approximate`; one effect round-trips as one editable picture | `filter` and `clip-path` cannot share one `<image>`; ordinary group filters, other primitives, effect DAGs, and multiple independent effects remain unsupported |
| Picture clipped to a shape | Registered image/crop-wrapper `clip-path` with one SVG-namespace shape | Picture preset or custom geometry | `Native-normalized` | Circle/ellipse/rect presets must cover the complete picture frame; use path/polygon for partial or offset contours; masks and winding-rule-dependent contours are not accepted |
| Imported cropped picture | Exact SVG-namespace nested crop wrapper produced by import, containing one direct unit-frame image in the visual root/`g` tree | Native signed `a:srcRect` on re-export | `Native-stable` within the crop contract, including negative crop values | Any generalized nested viewport, non-visual/render-only owner, extra visual child, unrepresentable crop window, redundant uncropped wrapper, or unresolved clip-marker pair is rejected |
| Picture recolor, artistic filter, blur, or complex mask | No general authoring mapping | Rebuild with supported overlays or pre-render | `Bake-required` | Unregistered SVG filters and blend modes fail the main contract |
diff --git a/docs/zh/powerpoint-svg-mapping.md b/docs/zh/powerpoint-svg-mapping.md
index de8e192b..d8bccf24 100644
--- a/docs/zh/powerpoint-svg-mapping.md
+++ b/docs/zh/powerpoint-svg-mapping.md
@@ -140,7 +140,7 @@ PowerPoint 意图
| 图片裁剪填充 | 一个已登记对齐值加显式 `slice` | 原生 `a:srcRect` 裁剪 | 源尺寸可读时为 `Native-stable` | 对齐值区分大小写;未知模式与额外 token 为 error |
| 图片适应框 | 省略时使用默认值,或一个已登记对齐值加显式 `meet` | 原生 fitted picture frame | `Native-normalized` | 仅写对齐值是兼容输入,Checker 会给出规范化建议 |
| 图片透明度 | 原子 image `opacity` | 原生 `a:alphaModFix` | `Native-stable` | 值必须有限,并在可接受 opacity 语法内 |
-| 图片阴影或发光 | `<image>` 上一个已登记效果 filter;导入裁剪图使用私有外层载体 | 原生 `p:pic/p:spPr/a:effectLst` | `Approximate`;单一效果可往返 | 其他 primitive、效果 DAG 与多个独立效果仍不支持 |
+| 图片阴影或发光 | 未裁剪 `<image>` 直接承载一个已登记效果 filter;裁剪图片或导入 crop 使用精确单图片外层载体 | 原生 `p:pic/p:spPr/a:effectLst` | `Approximate`;单一效果以一个可编辑图片往返 | `filter` 与 `clip-path` 不得同挂一个 `<image>`;普通组 filter、其他 primitive、效果 DAG 与多个独立效果仍不支持 |
| 图片裁成形状 | 作用于 image/crop wrapper 且只含一个 SVG 命名空间形状的已登记 `clip-path` | picture preset 或 custom geometry | `Native-normalized` | circle/ellipse/rect preset 必须覆盖完整图片 frame;局部或偏移轮廓使用 path/polygon;不接受任意 mask 或依赖绕组规则(winding rule)的轮廓 |
| 导入的裁剪图片 | 导入器产生的精确 SVG 命名空间嵌套 crop wrapper,在可视根/`g` 树中内含一个直接 unit-frame image | 重新导出为原生 signed `a:srcRect` | crop 合同内为 `Native-stable`,包括负裁剪值 | 拒绝通用嵌套 viewport、非可视或仅渲染所属容器、额外可视子元素、不可表示的 crop window、无裁剪的冗余 wrapper,以及无法解析的 clip-marker 配对 |
| 图片重着色、艺术滤镜、模糊或复杂 mask | 无通用创作映射 | 使用受支持 overlay 重建或预渲染 | `Bake-required` | 未登记 SVG filter 和 blend mode 违反主合同 |
diff --git a/skills/ppt-master/references/image-layout-patterns.md b/skills/ppt-master/references/image-layout-patterns.md
index 22d0a74f..d50bbbb5 100644
--- a/skills/ppt-master/references/image-layout-patterns.md
+++ b/skills/ppt-master/references/image-layout-patterns.md
@@ -202,7 +202,7 @@ The following three patterns are topologically different and are not interchange
59. **Image divider band** — replace a line between content regions with a narrow visual strip.
-36. **Shadow under an image panel** — apply one §6.4 filter to a standalone `<image>`; when the lifted object includes a frame or caption, shadow that supporting shape instead.
+36. **Shadow under an image panel** — apply one §6.4 filter directly to a standalone unclipped `<image>`; for a clipped picture, keep `clip-path` on the image and put the filter on its exact single-image outer carrier. When the lifted object includes a frame or caption, shadow that supporting shape instead.
37. **Glow on an overlay shape** — emphasize an overlay boundary within the supported effect contract.
diff --git a/skills/ppt-master/references/svg-effects.md b/skills/ppt-master/references/svg-effects.md
index aa06e6a9..4a9090ea 100644
--- a/skills/ppt-master/references/svg-effects.md
+++ b/skills/ppt-master/references/svg-effects.md
@@ -176,7 +176,7 @@ 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>`, `<image>`, `<path>`, `<text>` |
+| Public targets | `<rect>`, `<circle>`, `<image>`, `<path>`, `<text>`; an exact outer `<g filter>` is also registered when its sole visual child is one clipped `<image>` |
| 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` |
@@ -192,9 +192,10 @@ 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
-`<tspan>` / `<g>` / unsupported targets are forbidden; apply the
+`<tspan>` / ordinary `<g>` / unsupported targets are forbidden; apply the
effect to supported objects or use explicit layers.
-Private `<g filter>` carriers are limited to the hash-locked
+Special `<g filter>` carriers are limited to the exact single clipped-image
+form in §6.5, the hash-locked
`data-pptx-part="geometry-preview"` transport in §1.4—a direct child of an
imported preset object referencing the hidden geometry carrier's filter—and the
exact imported picture-crop carrier in §6.5, which keeps the effect outside its
@@ -285,8 +286,11 @@ 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`. One §6.4
-filter may apply directly to `<image>`.
+frame-fit. Match the image box to the source ratio or use `slice`. Put one §6.4
+filter directly on an unclipped `<image>`. For a clipped picture, keep
+`clip-path` on the `<image>` and put the filter on an exact outer `<g>` whose
+sole visual child is that image. Never combine `filter` and `clip-path` on the
+same `<image>`: SVG would clip the preview effect while PowerPoint would not.
**Hard rule — picture frames and sources are explicit and decodable**: every
SVG `<image>` has explicit positive `width`/`height` and exactly one non-empty
@@ -772,9 +776,9 @@ remain authoritative in the owning subsection.
#### Page-Level Stacks
-Choose the skeleton in
-[`image-layout-patterns.md`](./image-layout-patterns.md), read each stack
-back-to-front, and omit every layer without a distinct job.
+Use the planned page skeleton; when images are active, select it through
+[`image-layout-patterns.md`](./image-layout-patterns.md). Read each stack
+back-to-front and omit every layer without a distinct job.
| Page job | Back-to-front stack | Stop |
|---|---|---|
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index 779fb1b1..4fb1a176 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -12,7 +12,7 @@
"skills/ppt-master/templates/schemas/*.json"
],
"exclude": [],
- "max_tokens": 396701
+ "max_tokens": 396842
},
"file_budgets": {
"AGENTS.md": 2400,
@@ -25,7 +25,7 @@
"skills/ppt-master/references/executor-notes.md": 900,
"skills/ppt-master/references/shared-standards.md": 250,
"skills/ppt-master/references/shared-standards-core.md": 11100,
- "skills/ppt-master/references/svg-effects.md": 12524,
+ "skills/ppt-master/references/svg-effects.md": 12637,
"skills/ppt-master/references/native-data-interface.md": 6200,
"skills/ppt-master/references/pptx-structure-interface.md": 4300,
"skills/ppt-master/references/strategist.md": 14487,
@@ -186,7 +186,7 @@
"skills/ppt-master/references/svg-effects.md",
"skills/ppt-master/references/native-shape-authoring.md"
],
- "max_tokens": 54277
+ "max_tokens": 54390
},
"route.generate.quick-generate.topic-research": {
"description": "Quick Generate with gap-targeted factual research before direct resource preparation and SVG authoring.",
@@ -196,7 +196,7 @@
"stage.generate.topic-research"
],
"files": [],
- "max_tokens": 55789
+ "max_tokens": 55902
},
"route.generate.quick-generate.icon": {
"description": "Quick Generate with project-local bundled icon selection and synchronization.",
@@ -207,7 +207,7 @@
"files": [
"skills/ppt-master/templates/icons/README.md"
],
- "max_tokens": 56189
+ "max_tokens": 56302
},
"route.generate.quick-generate.in-hand-image": {
"description": "Quick Generate with supplied, extracted, or placeholder image resources prepared before SVG authoring.",
@@ -217,7 +217,7 @@
"stage.generate.executor.image"
],
"files": [],
- "max_tokens": 64333
+ "max_tokens": 64474
},
"route.generate.quick-generate.formula": {
"description": "Quick Generate with manifest-driven formula rendering and formula-image realization.",
@@ -229,7 +229,7 @@
"files": [
"skills/ppt-master/scripts/docs/image.md"
],
- "max_tokens": 67519
+ "max_tokens": 67660
},
"route.generate.quick-generate.ai-two-types": {
"description": "Quick Generate with AI resource preparation, representative rendering inputs, and two local image types.",
@@ -240,7 +240,7 @@
"stage.generate.executor.image"
],
"files": [],
- "max_tokens": 87438
+ "max_tokens": 87579
},
"route.generate.quick-generate.web-image": {
"description": "Quick Generate with web resource preparation, provenance, attribution, and image execution.",
@@ -251,7 +251,7 @@
"stage.generate.executor.web-image"
],
"files": [],
- "max_tokens": 72086
+ "max_tokens": 72227
},
"route.generate.planning-image": {
"description": "Generate-PPTX planning context after a non-none image source is proposed or confirmed, including the compact layout math and vocabulary.",
@@ -261,7 +261,7 @@
"stage.generate.strategist.image"
],
"files": [],
- "max_tokens": 71401
+ "max_tokens": 71429
},
"route.generate.planning-formula": {
"description": "Formula-only planning context, including the shared image/formula layout math and vocabulary.",
@@ -271,7 +271,7 @@
"stage.generate.strategist.image"
],
"files": [],
- "max_tokens": 71401
+ "max_tokens": 71429
},
"route.generate.planning-ai": {
"description": "Generate-PPTX planning when AI image direction is available, including representative multi-source custom rendering synthesis.",
@@ -291,7 +291,7 @@
"registry": "image-renderings"
}
],
- "max_tokens": 75643
+ "max_tokens": 75671
},
"stage.generate.apply-template-workspace": {
"description": "Conditional Step 3 workspace validation, installation, and fusion framework.",
@@ -403,7 +403,7 @@
"stage.generate.executor.notes"
],
"files": [],
- "max_tokens": 105817
+ "max_tokens": 105930
},
"route.generate.flat-ai-two-types": {
"description": "Generate-PPTX context with AI images, representative multi-source custom rendering, and two local types.",
@@ -461,7 +461,7 @@
"profile.generate.beautify-pptx"
],
"files": [],
- "max_tokens": 112824
+ "max_tokens": 112937
},
"route.generate.flat-no-image-chart": {
"description": "Default flat Generate-PPTX path with chart authoring, native-data replacement, and verification.",
@@ -474,7 +474,7 @@
"stage.generate.verify-charts"
],
"files": [],
- "max_tokens": 130153
+ "max_tokens": 130266
},
"route.generate.brand-flat-no-image": {
"description": "Brand-preset flat Generate-PPTX path without image acquisition.",
@@ -486,7 +486,7 @@
"stage.generate.template.brand"
],
"files": [],
- "max_tokens": 112849
+ "max_tokens": 112962
},
"route.generate.deck-structured-no-image": {
"description": "Deck-preset structured Generate-PPTX path without image acquisition.",
@@ -498,7 +498,7 @@
"stage.generate.template.deck"
],
"files": [],
- "max_tokens": 122786
+ "max_tokens": 122899
},
"route.generate.layout-structured-no-image": {
"description": "Layout-preset structured Generate-PPTX path without image acquisition.",
@@ -510,7 +510,7 @@
"stage.generate.template.layout"
],
"files": [],
- "max_tokens": 123235
+ "max_tokens": 123348
},
"route.generate.topic-only-flat-no-image": {
"description": "Topic research followed by the default flat no-image Generate-PPTX path.",
@@ -520,7 +520,7 @@
"route.generate.flat-no-image"
],
"files": [],
- "max_tokens": 107329
+ "max_tokens": 107442
},
"stage.generate.executor.flat": {
"description": "Incremental flat Executor core with complete visual-construction authorities and representative multi-source custom mode/style execution.",
@@ -622,7 +622,7 @@
"skills/ppt-master/workflows/stages/resume-execute.md",
"skills/ppt-master/references/artifact-ownership.md"
],
- "max_tokens": 68027
+ "max_tokens": 68140
},
"stage.generate.resume-execute-image": {
"description": "Fresh-session resume when the locked resource plan contains image rows.",
@@ -796,7 +796,7 @@
"skills/ppt-master/references/image-layout-spec.md",
"skills/ppt-master/references/image-layout-patterns.md"
],
- "max_tokens": 8300
+ "max_tokens": 8321
},
"stage.generate.strategist.template": {
"description": "Conditional Strategist module for an explicitly installed template workspace.",
@@ -823,7 +823,7 @@
"skills/ppt-master/references/image-layout-patterns.md",
"skills/ppt-master/references/svg-image-embedding.md"
],
- "max_tokens": 10075
+ "max_tokens": 10084
},
"stage.generate.executor.web-image": {
"description": "Conditional sourced-image attribution layered on image execution.",
@@ -858,7 +858,7 @@
"files": [
"skills/ppt-master/references/svg-effects.md"
],
- "max_tokens": 12524
+ "max_tokens": 12637
}
},
"duplicates": {