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(gradients): bound radial focus to the canonical circle

hugohe32bab6ba64696
diff --git a/docs/powerpoint-svg-mapping.md b/docs/powerpoint-svg-mapping.md
index d10f4ee0..5d76a75b 100644
--- a/docs/powerpoint-svg-mapping.md
+++ b/docs/powerpoint-svg-mapping.md
@@ -158,7 +158,7 @@ preset selection and authoring behavior are documented in
| Solid fill | Canonical `fill="#RRGGBB"`, either a named lock anchor or contextual page paint | `a:solidFill`, with a theme token when an anchor role is exactly reusable | `Native-stable` | Compatible spellings may warn; malformed colors fail, while valid contextual colors are informational |
| Fill transparency | Opaque fill plus `fill-opacity` | Native alpha | `Native-stable` | Generated values are finite unitless numbers from 0 to 1 |
| Linear gradient fill | Registered `<linearGradient>` in `<defs>` | Native `a:gradFill` | `Native-normalized` | Stops, coordinates, transforms, and references must follow the closed contract |
-| Radial gradient fill | Registered `<radialGradient>` | Point-focused circular DrawingML gradient | `Approximate`; effective focus round-trips while outer center/radius normalize | Review radius- or outer-center-sensitive designs |
+| Radial gradient fill | Registered `<radialGradient>` | Point-focused circular DrawingML gradient | `Approximate`; an in-circle effective focus round-trips while outer center/radius normalize | Effective focus must lie inside the canonical centered radius-0.5 circle; import centers an outside focus with a diagnostic; review radius- or outer-center-sensitive designs |
| Pattern fill | Annotated project pattern definition | Native `a:pattFill` | `Native-normalized` | Only registered PowerPoint preset patterns are supported |
| No outline | `stroke="none"` or the registered absence of a line | `a:noFill` under `a:ln` | `Native-stable` | Do not simulate absence with zero-width ambiguous CSS |
| Solid outline | Registered `stroke` and width | Native `a:ln` | `Native-stable` | Width and paint must use canonical units/grammar |
diff --git a/docs/zh/powerpoint-svg-mapping.md b/docs/zh/powerpoint-svg-mapping.md
index e9fbdc0a..1da52094 100644
--- a/docs/zh/powerpoint-svg-mapping.md
+++ b/docs/zh/powerpoint-svg-mapping.md
@@ -153,7 +153,7 @@ PowerPoint 意图
| 纯色填充 | 已锁定规范 `fill="#RRGGBB"` | `a:solidFill`;当锁定角色可精确复用时使用 theme token | `Native-stable` | 兼容颜色拼法可产生 warning;格式错误或生成未锁定值失败 |
| 填充透明度 | 不透明 fill 加 `fill-opacity` | 原生 alpha | `Native-stable` | 生成值为 0 到 1 的有限无单位数 |
| 线性渐变填充 | `<defs>` 中已登记 `<linearGradient>` | 原生 `a:gradFill` | `Native-normalized` | stop、坐标、transform 与引用必须遵循封闭合同 |
-| 径向渐变填充 | 已登记 `<radialGradient>` | 可偏心单点焦点的圆形 DrawingML 渐变 | `Approximate`;有效焦点可往返,外圆中心与半径会归一化 | 对半径或外圆中心敏感的设计需复核 |
+| 径向渐变填充 | 已登记 `<radialGradient>` | 可偏心单点焦点的圆形 DrawingML 渐变 | `Approximate`;位于规范圆内的有效焦点可往返,外圆中心与半径会归一化 | 有效焦点必须落在中心 `(0.5,0.5)`、半径 `0.5` 的规范圆内;回导会居中越界焦点并记录诊断;对半径或外圆中心敏感的设计需复核 |
| 图案填充 | 带注解的项目 pattern 定义 | 原生 `a:pattFill` | `Native-normalized` | 仅支持已登记 PowerPoint 预设 pattern |
| 无轮廓 | `stroke="none"` 或已登记线缺省 | `a:ln` 内的 `a:noFill` | `Native-stable` | 不得用零线宽模糊 CSS 模拟缺省 |
| 实线轮廓 | 已登记 `stroke` 与宽度 | 原生 `a:ln` | `Native-stable` | 宽度与 paint 必须使用规范单位/语法 |
diff --git a/skills/ppt-master/references/svg-effects.md b/skills/ppt-master/references/svg-effects.md
index 753802c8..dce733fc 100644
--- a/skills/ppt-master/references/svg-effects.md
+++ b/skills/ppt-master/references/svg-effects.md
@@ -123,7 +123,7 @@ closed parser checks. See
| Definition | Direct `<linearGradient>` / `<radialGradient>` child of `<defs>` with unique `id` |
| Reference | Exact local `url(#id)` |
| Stops | ≥2 direct `<stop>` children; explicit color; finite non-decreasing offset in `0..1` or `0%..100%` (ties form hard edges); optional alpha |
-| Coordinates | `objectBoundingBox` only. Generated values: `0..1`; omitted linear axis = `(0,0) → (1,0)`. Only import-normalized linear projections may reach `-0.105..1.105`; radial values stay in `0..1` |
+| Coordinates | `objectBoundingBox` only. Generated values: `0..1`; omitted linear axis = `(0,0) → (1,0)`. Only import-normalized linear projections may reach `-0.105..1.105`; radial values stay in `0..1`, and their effective focus must lie inside the circle centered at `(0.5,0.5)` with radius `0.5` |
| Forbidden | External/quoted refs, `href` inheritance, `gradientTransform`, `spreadMethod`, CSS gradients |
| Target | Contract and fidelity |
@@ -136,7 +136,10 @@ closed parser checks. See
Linear export preserves stops/alpha and reduces direction to an angle;
coincident endpoints are invalid. Radial export preserves the effective focus
(`fx/fy`, otherwise `cx/cy`) as a point-focused circle; its outer center and
-radius normalize to `0.5`, so distinct outer `cx/cy` and `r` are dropped.
+radius normalize to `0.5`, so distinct outer `cx/cy` and `r` are dropped. A
+focus outside that canonical circle is invalid because SVG renderers clamp it
+to the circumference while DrawingML retains the rectangle coordinates;
+reverse import centers such a source focus and records a diagnostic.
Gradient strokes stay editable;
reverse import may keep the first stop only. Stop alpha multiplies element opacity.
PPTX import normalizes gradients and reports degradation;
@@ -331,7 +334,7 @@ and converter share this parser.
|---|---|---|
| Directional scrim | Linear rect, darkest beside text | `0%: 0.88; 55%: 0.30; 100%: 0` |
| Bottom title fade | Vertical rect over lower image | black `0 → 0.72` |
-| Vignette/spotlight | Radial rect; place the hotspot with `fx/fy` or `cx/cy`; outer center/radius remain approximate | black `0 → 0.58` |
+| Vignette/spotlight | Radial rect; place the hotspot with `fx/fy` or `cx/cy` inside the canonical focus circle; outer center/radius remain approximate | black `0 → 0.58` |
| Brand wash | Directional existing brand-color gradient | `0.80 → 0.10` |
| Faux glass | Visible fields + diagonal linear panel (`0,0 → 1,1`) + highlight stroke; optional §6.4 elevation | white `0.38 → 0.12`; stroke about `0.55` |
diff --git a/skills/ppt-master/scripts/docs/mask-gradient-smoke.md b/skills/ppt-master/scripts/docs/mask-gradient-smoke.md
index 3c388e98..aca5cc26 100644
--- a/skills/ppt-master/scripts/docs/mask-gradient-smoke.md
+++ b/skills/ppt-master/scripts/docs/mask-gradient-smoke.md
@@ -17,6 +17,7 @@ from xml.etree import ElementTree as ET
scripts = Path("skills/ppt-master/scripts").resolve()
sys.path.insert(0, str(scripts))
+from pptx_to_svg.color_resolver import ColorPalette
from pptx_to_svg.fill_to_svg import _angle_to_unit_endpoints, resolve_fill
from svg_quality_checker import SVGQualityChecker
from svg_to_pptx.drawingml.converter import (
@@ -81,6 +82,46 @@ assert 'cx="0.5" cy="0.5" r="0.5" fx="0.8" fy="0.2"' in restored.defs[0]
assert '<a:fillToRect l="80000" t="20000" r="20000" b="80000"/>' in (
build_gradient_fill(ET.fromstring(restored.defs[0]))
)
+radial.set("fx", "0")
+radial.set("fy", "0")
+outside_focus_errors = project_gradient_errors(valid)
+assert any(
+ "must lie within the canonical circle" in error
+ for error in outside_focus_errors
+), outside_focus_errors
+try:
+ build_gradient_fill(radial)
+except ValueError as exc:
+ assert "must lie within the canonical circle" in str(exc)
+else:
+ raise AssertionError("outside radial focus reached DrawingML")
+radial.set("fx", "0.8")
+radial.set("fy", "0.2")
+
+diagnostics = []
+palette = ColorPalette(
+ None,
+ None,
+ strict=False,
+ diagnostic_sink=lambda code, message, fallback: diagnostics.append(
+ (code, message, fallback)
+ ),
+)
+outside_native_xml = focused_xml.replace(
+ 'l="80000" t="20000" r="20000" b="80000"',
+ 'l="0" t="0" r="100000" b="100000"',
+)
+outside_native_gradient = ET.fromstring(
+ f'<root xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">'
+ f"{outside_native_xml}</root>"
+)[0]
+normalized = resolve_fill(outside_native_gradient, palette)
+assert " fx=" not in normalized.defs[0]
+assert " fy=" not in normalized.defs[0]
+assert any(
+ code == "path-gradient-focus-normalized"
+ for code, _message, _fallback in diagnostics
+)
with tempfile.TemporaryDirectory(prefix="ppt-master-gradient-smoke-") as tmp:
source = Path(tmp) / "gradient.svg"
@@ -222,9 +263,11 @@ print("Mask and gradient smoke: passed")
PY
```
-The three invalid-gradient cases, all three direct mask forms, and a mask
-hidden inside a `data-icon` asset must produce the named shared-validator
-errors in both Checker and direct export. The legal cases must retain stop
-alpha, promote the full-canvas gradient to one native `p:bg`, default an
-unpositioned linear gradient to horizontal, and recover approximately 30
-degrees from the importer's out-of-unit-box endpoint form.
+The three invalid-gradient cases, the outside-circle radial focus, all three
+direct mask forms, and a mask hidden inside a `data-icon` asset must produce
+the named shared-validator errors in both Checker and direct export. The legal
+cases must retain stop alpha, round-trip an in-circle focus, center an imported
+outside-circle focus with a diagnostic, promote the full-canvas gradient to
+one native `p:bg`, default an unpositioned linear gradient to horizontal, and
+recover approximately 30 degrees from the importer's out-of-unit-box endpoint
+form.
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index a02517d2..7089b699 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": 396912
+ "max_tokens": 397338
},
"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": 12707,
+ "skills/ppt-master/references/svg-effects.md": 12779,
"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": 54460
+ "max_tokens": 54532
},
"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": 55972
+ "max_tokens": 56044
},
"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": 56372
+ "max_tokens": 56444
},
"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": 64544
+ "max_tokens": 64616
},
"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": 67730
+ "max_tokens": 67802
},
"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": 87649
+ "max_tokens": 87721
},
"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": 72297
+ "max_tokens": 72369
},
"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.",
@@ -403,7 +403,7 @@
"stage.generate.executor.notes"
],
"files": [],
- "max_tokens": 106000
+ "max_tokens": 106072
},
"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": 113007
+ "max_tokens": 113079
},
"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": 130336
+ "max_tokens": 130408
},
"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": 113032
+ "max_tokens": 113104
},
"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": 122969
+ "max_tokens": 123041
},
"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": 123418
+ "max_tokens": 123490
},
"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": 107512
+ "max_tokens": 107584
},
"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": 68210
+ "max_tokens": 68282
},
"stage.generate.resume-execute-image": {
"description": "Fresh-session resume when the locked resource plan contains image rows.",
@@ -858,7 +858,7 @@
"files": [
"skills/ppt-master/references/svg-effects.md"
],
- "max_tokens": 12707
+ "max_tokens": 12779
}
},
"duplicates": {