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

refactor(prompts): keep svg-effects to the form the model writes

hugohe34a955ab82cf8
diff --git a/skills/ppt-master/references/svg-effects.md b/skills/ppt-master/references/svg-effects.md
index 4e56de99..a19838b4 100644
--- a/skills/ppt-master/references/svg-effects.md
+++ b/skills/ppt-master/references/svg-effects.md
@@ -2,7 +2,7 @@
# SVG Effects and Geometry Specification
-Authority for advanced paint, effects, transforms, freeform/radial geometry, and constructed visual styles. Default and Quick Generate load it before SVG authoring; other SVG-authoring routes follow their workflow trigger.
+Authority for advanced paint, effects, transforms, freeform/radial geometry, and constructed visual styles. Default and Quick Generate load it before SVG authoring; other SVG-authoring routes follow their workflow trigger. It keeps the form the model writes and the design decisions behind each technique; the complete grammar the checker and exporter enforce for every section is in [`svg-contract.md`](../scripts/docs/svg-contract.md) Part II, section for section.
**Cross-reference map**: unqualified §1, §2, and §4 references point to [`shared-standards-core.md`](./shared-standards-core.md); §6 references are local to this file.
@@ -53,13 +53,11 @@ simplify any competing scaffold without a separate communication job.
#### Visual Job Router
**Reference — not a quota**: recall candidates for a diagnosed problem from
-this table. A
-page may use no listed technique, one technique, or several techniques with
-different jobs. The table recalls constructions rather than bounding them: one
-it never names is equally valid when it satisfies every applicable technical
-contract — the shared core's closed authoring surface, this file, the route's
-other required construction references, and any triggered module. Those
-contracts are the boundary; membership in this table is not.
+this table. A page may use no listed technique, one technique, or several
+techniques with different jobs. The table recalls constructions rather than
+bounding them: one it never names is equally valid when it satisfies every
+applicable technical contract. Those contracts are the boundary; membership in
+this table is not.
| Diagnosed visual problem | Candidate technique | Authority / stop |
|---|---|---|
@@ -89,7 +87,7 @@ modifier or prepared-asset treatments, resolve its implementation here.
| `M3 · 01/02/05` · frame, print frame, contour/cut edge | Registered native stroke/path; §6.6 |
| `M3 · 03; M1 · 09` · rotation, misregistration, Riso offset | Transform + explicit duplicate layers; §6.8 / §6.11 |
| `M1 · 03` + effect-only forms · paper cut, facets/folds, ribbon, staging | Ordered paths/facets + consistent paint/light; §6.11 / [`native-shape-authoring.md`](./native-shape-authoring.md) §7 |
-| `M1 · 01/02/04–08` · crop, opening, subtraction, reveal | Direct clip or materialized Boolean; no `<mask>`; [`shared-standards-core.md`](./shared-standards-core.md) §1.2 / [`native-shape-authoring.md`](./native-shape-authoring.md) §6 |
+| `M1 · 01/02/04–08` · crop, opening, subtraction, reveal | Direct clip or materialized Boolean; no `<mask>`; §1.2 / [`native-shape-authoring.md`](./native-shape-authoring.md) §6 |
| Effect-only · faux glass | Visible field + translucent panel + highlight; no blur or frosted-crop substitution; §6.5 |
| `A1 · 02–04; A3 · 02/03` · blur, duotone, blend, frost, desaturation | Prepared local bitmap/composite/derivative; registered frost is a blurred derivative; §6.12 |
@@ -97,122 +95,41 @@ modifier or prepared-asset treatments, resolve its implementation here.
generated pages choose paint from the Default locked or Quick-resolved identity
anchors, visual style, content semantics, and current composition. A contextual
tint, gradient stop, shadow/glow paint, or one-off display color need not
-already be a persistent identity role;
-promote it only when it becomes a recurring named role. Fidelity labels are defined
-in [`shared-standards-core.md`](./shared-standards-core.md). Review an `Approximate` result in native PPTX
-when the effect carries material meaning.
+already be a persistent identity role; promote it only when it becomes a
+recurring named role. Review an `Approximate` result in native PPTX when the
+effect carries material meaning.
---
### 6.2 Color, Alpha, and Opacity
-Compatible paint grammar includes recognized named colors, `rgb()` / `rgba()`,
-`hsl()` / `hsla()`, and `#RGB` / `#RGBA` / `#RRGGBB` / `#RRGGBBAA`. The
-converter also tolerates legacy bare 3/4/6/8-digit hexadecimal tokens. The
-shared converter implementation for §§6.2–6.8 is
-[`utils.py`](../scripts/svg_to_pptx/drawingml/utils.py).
-
-**Default — canonical generated paint tokens (may preserve compatible
-alternatives)**: New `svg_output/` and reusable template SVGs write solid paint
-as uppercase six-digit `#RRGGBB`. `fill` / `stroke` may instead use lowercase
-`none` or the exact local reference form `url(#id)`. Named colors, lowercase or
-short/alpha HEX, functional colors, and bare legacy HEX remain supported input.
-The quality checker prints an optional canonical rewrite as a recommendation
-warning; it does not require modification or block export.
-Explicit empty, malformed, or unrecognized paint values are errors in both
-Checker and exporter preflight; neither converts unknown intent into
-`noFill` or default black. Omitted properties still follow their own element
-contract, such as SVG's default fill or §6.3's required gradient-stop color.
-
-| Intent | Canonical authoring | Native result / fidelity |
-|---|---|---|
-| Solid fill or text paint | `fill="#RRGGBB"` | Solid DrawingML paint; `Native-stable` |
-| Fill/text alpha | Opaque `fill` + `fill-opacity="0..1"` | Fill/run alpha; `Native-stable` |
-| Stroke alpha | Opaque `stroke` + `stroke-opacity="0..1"` | Line/outline alpha; `Native-stable` |
-| Gradient-stop alpha | Opaque `stop-color` + `stop-opacity="0..1"` | Per-stop alpha; `Native-stable` |
-| Shadow/glow alpha | Opaque `flood-color` + `flood-opacity="0..1"` | Glow is `Native-stable`; outer shadow is visually calibrated `Approximate` within §6.4 |
-| Picture fade | `<image opacity="0..1">` | Picture `<a:alphaModFix>`; `Native-stable` |
-| One atomic whole-object fade | Non-group element `opacity="0..1"` | Alpha compiled into its supported paint/effect channels; `Native-normalized` |
-| Pattern alpha | Opaque pattern child paint + child fill/stroke opacity | Conditional; [`native-data-interface.md`](./native-data-interface.md) |
-| CSS color alpha | Alpha-bearing named/functional/HEX paint | `Native-normalized`; recommendation warning only |
-| Group fade | `<g opacity>` compatibility | `Approximate`; fidelity warning; §2.2 |
-
-```text
-effective fill alpha
-= color alpha × ancestor group opacity × element opacity × fill-opacity
-```
+Write solid paint as uppercase `#RRGGBB`, `none`, or an exact local `url(#id)`.
+Put alpha on the channel that owns it — `fill-opacity`, `stroke-opacity`,
+`stop-opacity`, or `flood-opacity` as a unitless `0..1` — and use element
+`opacity` only for an `<image>` or one non-group atomic object that fades all
+of its channels together. Do not use element `opacity` as an alias for
+`rgba()` on a fill-only object, and prefer descendant alpha over group opacity
+(§2.2). Alpha multiplies down the tree: color alpha × ancestor group opacity ×
+element opacity × channel opacity. Named colors, short/alpha HEX, `rgb()` /
+`hsl()`, and percentages remain compatible input that the checker only
+recommends normalizing.
-**Default — opaque color authority (may preserve compatible alpha colors)**:
-New generated SVG puts alpha on the semantic channel that owns it. Existing or
-intentional alpha-bearing color tokens remain convertible; they normalize into
-the matching DrawingML color/alpha channels.
-
-**Default — channel-specific alpha (may override for one atomic whole-object
-fade)**: use `fill-opacity`, `stroke-opacity`, `stop-opacity`, or
-`flood-opacity` when only that channel fades. Use element `opacity` only when
-an image or one non-group atomic object intentionally fades all of its
-supported paint/effect channels together. Do not use element `opacity` as an
-alias for `rgba()` on a fill-only object.
-
-**Default — alpha grammar (may preserve compatible alternatives)**: write
-`opacity`, `fill-opacity`, `stroke-opacity`, `stop-opacity`, and
-`flood-opacity` as finite unitless numbers from `0` to `1`. The converter also
-accepts finite numeric values that SVG/CSS clamps into that interval;
-`stop-opacity` and `flood-opacity` additionally accept finite percentages. The
-checker reports those supported non-default spellings as recommendation warnings.
-Malformed or non-finite values are errors in both Checker and exporter
-preflight; neither substitutes an opaque default for unknown intent.
-`fill="transparent"` / `stroke="transparent"` become no fill/line; use a color
-plus alpha when a painted transparent layer must remain represented. Prefer
-descendant alpha over group opacity when isolated compositing matters (§2.2).
-
-PPTX import is a user-input boundary, not generated authoring. Tolerant mode
-retains recognized color semantics, omits only unsupported paint properties,
-and records the decision in `conversion-report.json`; `--strict` keeps the
-closed parser checks. See
-[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).
---
### 6.3 Gradients and Paint Effects
-| Concern | Contract |
-|---|---|
-| Definition | Direct `<linearGradient>` / `<radialGradient>` child of `<defs>` with unique `id` |
-| Reference | Exact local `url(#id)` |
-| Stops | ≥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`, 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 |
-|---|---|
-| `<rect>`, `<circle>`, `<ellipse>`, `<path>`, `<polygon>` fill/stroke | Linear `Native-normalized`; radial `Approximate` |
-| `<line>` / `<polyline>` | Gradient stroke only; linear `Native-normalized`, radial `Approximate` |
-| `<text>` / non-positional `<tspan>` | Gradient fill only; no gradient text outline |
-| `<image>` | No gradient paint; use §6.5 overlays |
-
-Linear export preserves stops/alpha 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. 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;
-`--strict` keeps the closed parser contract. See
-[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).
-Checker/exporter preflight share this validation.
-Gradient-stop colors are contextual paint values. Keep them coherent with the
-deck anchors and page intent; they are not required to duplicate existing
-Default `spec_lock.colors` literals or Quick-resolved anchors.
-
-**Hard rule — non-degenerate gradient geometry**: an `objectBoundingBox`
-gradient stroke requires non-zero intrinsic width and height. SVG stroke width
-does not expand that object bounding box, so a perfectly horizontal or vertical
-gradient ribbon disappears even when its stroke is thick. Author such a ribbon
-as a closed shape with gradient `fill`, or use a path whose intrinsic geometry
-has both dimensions. Checker and exporter reject the degenerate stroke form.
+A gradient is a direct `<linearGradient>` / `<radialGradient>` in `<defs>` with
+≥2 explicit-color stops at non-decreasing `0..1` offsets, referenced by exact
+`url(#id)`, in `objectBoundingBox` units — no `gradientTransform`,
+`spreadMethod`, or CSS gradients. Linear exports as an angle
+(`Native-normalized`); radial keeps only its focus point and normalizes the
+outer circle to the object (`Approximate`), so place the hotspot with `fx/fy`
+inside the object and expect the rim to differ. Text takes gradient fill only;
+images take no gradient paint (use §6.5 overlays). A gradient *stroke* needs a
+path with both width and height — a perfectly horizontal or vertical gradient
+ribbon disappears, so author it as a closed gradient-filled band. Stop colors
+are contextual paint: keep them coherent with the deck anchors and page
+intent without duplicating a lock row.
```xml
<defs>
@@ -225,23 +142,12 @@ has both dimensions. Checker and exporter reject the degenerate stroke form.
stroke="url(#flow)" stroke-width="12"/>
```
-**Native text picture/texture fill**:
-
-| Concern | Contract |
-|---|---|
-| Target | Direct `fill="url(#id)"` on `<text>` or a non-positional `<tspan>`; the text remains editable |
-| Definition | Direct `<pattern>` child of `<defs>` with unique `id` and exact `data-pptx-text-image-fill="stretch"` or `"tile"` |
-| Image | Exactly one direct SVG-namespace `<image>` child; project-local or data-URI source; explicit positive `width` / `height` |
-| Native result | `stretch` → run-level `a:blipFill/a:stretch`; `tile` → run-level `a:blipFill/a:tile` |
-| Alpha | Text `fill-opacity` multiplies the native picture-fill alpha |
-| Forbidden | Preset-pattern attributes; `patternTransform`; additional pattern children; image style/alpha/clip/filter/mask/transform; use outside text; unannotated custom image patterns; multi-image/layer knockout composites |
-
-Use this registered pattern when the design calls for a photograph, material,
-or texture inside editable glyphs. The pattern is an authoring carrier for a
-PowerPoint run picture fill, not a general SVG pattern promise. PowerPoint owns
-the final run bounding box: `stretch` is `Native-normalized`, while `tile` may
-normalize tile scale or phase and needs visual review. Forward SVG→PPTX export
-is native; PPTX→SVG does not reconstruct run-level picture fills yet.
+**Native text picture/texture fill**: when the design calls for a photograph,
+material, or texture inside editable glyphs, fill the `<text>` (or a
+non-positional `<tspan>`) with a registered single-image `<pattern>` marked
+`data-pptx-text-image-fill="stretch"` or `"tile"`. It exports as a PowerPoint
+run picture fill (`stretch` `Native-normalized`; `tile` needs visual review),
+not as a general SVG pattern; the text stays editable.
```xml
<defs>
@@ -265,48 +171,16 @@ Preset patterns are a separate PPT interface in [`native-data-interface.md`](./n
### 6.4 Shadows, Glow, and Elevation
-Filters are native-effect metadata, not a general pixel-filter surface.
-
-| Concern | Contract |
-|---|---|
-| Definition/reference | Direct `<defs><filter id="...">` child with unique id; direct `filter="url(#id)"` attribute, never inline style |
-| Public targets | `<rect>`, `<circle>`, `<image>`, `<path>`, `<text>`; one validated compact authored shape-preset `<g>` from [`native-shape-authoring.md`](./native-shape-authoring.md) §4; an exact outer `<g filter>` whose sole visual child is one clipped `<image>` |
-| Required primitive | `feDropShadow` or `feGaussianBlur` |
-| Generated glow form | Zero-offset `feDropShadow` with flood paint, or the complete blur + flood + composite + merge graph below; never bare blur |
-| Required parameters | Explicit `stdDeviation` on either effect primitive; explicit `dx`, `dy`, and `flood-opacity` on `feDropShadow`; explicit `flood-opacity` on `feFlood`; explicit `slope` on linear `feFuncA` |
-| Accepted helpers | `feOffset`, `feFlood`, `feComposite`, `feMerge`, `feMergeNode`, `feComponentTransfer`, linear `feFuncA` |
-| Alpha transfer | Linear `feFuncA` maps multiplicative `slope` only; `intercept` is unsupported |
-| Blur sampling | `feGaussianBlur edgeMode` is unsupported; native effects do not expose the SVG edge-sampling modes |
-| Primitive coordinates | Omit `primitiveUnits` or use `userSpaceOnUse`; `objectBoundingBox` coordinates are unsupported |
-| Numeric values | Finite unitless values; non-negative `stdDeviation`; finite `dx` / `dy`; `feFuncA slope` within `0..1`; mapped glow `rad = stdDeviation × 9525`, shadow `blurRad = stdDeviation × 2 × 9525`, and shadow `dist = hypot(dx,dy) × 9525` must round into DrawingML `0..27273042316900` |
-| Classification | Meaningful non-zero offset → one outer shadow; zero/no offset → one glow |
-| Fidelity | `Approximate`; one filter becomes one DrawingML effect |
-
-Flood opacity, linear `feFuncA slope`, and element opacity multiply. The
-converter-only historical path may also multiply flood-color alpha and
-ancestor group opacity.
-Native export does not preserve filter-region, `in/in2/result`, merge order, or
-composite topology. Other primitives, multiple independent effects, filters on
-`<tspan>` / ordinary `<g>` / unsupported targets are forbidden; apply the
-effect to supported objects or use explicit layers.
-Special `<g filter>` targets are limited to the helper-authored compact shape
-preset above, 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
-viewport. The compact preset applies its filter once to the logical shape; its
-direct registry paths remain unfiltered. None of these cases authorizes ordinary
-group filters or creates a second PowerPoint object.
-PPTX import maps one classifiable shape/connector/picture outer shadow or glow
-to this contract. Unsupported effects and outer-shadow variants whose scale,
-skew, alignment, or rotation semantics cannot be retained become import
-diagnostics instead of a silently simplified authoring surface. See
-[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary)
-for tolerant, strict, and release-handling behavior.
-The quality checker and exporter preflight enforce the same definition,
-reference, primitive, target, and numeric-value contract. Missing required
-geometry and malformed values are never replaced by effect defaults during
-native export.
+A filter is native-effect metadata, not a pixel-filter surface: one direct
+`<defs><filter>` referenced as a direct `filter="url(#id)"` on a `<rect>`,
+`<circle>`, `<image>`, `<path>`, `<text>`, or a helper-authored preset group,
+built from `feDropShadow` or the blur + flood + composite + merge graph below
+with explicit `stdDeviation`, `dx`/`dy`, and `flood-opacity`. A meaningful
+offset becomes one outer shadow; zero offset — even `feDropShadow` with
+`dx="0" dy="0"` — becomes one glow. Both are `Approximate`: one filter, one
+DrawingML effect. Filters on `<tspan>` or ordinary `<g>` and every other
+primitive are forbidden; use an existing accent color for glow, since black
+reads as diffuse shadow.
```xml
<defs>
@@ -330,10 +204,6 @@ native export.
</defs>
```
-Even `feDropShadow` with `dx="0" dy="0"` becomes glow. Use an existing accent
-color; black reads as diffuse shadow. Bare `feGaussianBlur` remains compatible
-input but is never generated: preview blurs the object while export emits glow.
-
| Elevation | Use | `dy` | `stdDeviation` | Alpha |
|---|---|---:|---:|---:|
| Floor | Backgrounds, dividers, equal peers, body containers, decorative lines/icons, single-layer pages | — | — | — |
@@ -351,81 +221,33 @@ one light direction.
**Reference — not a constraint**: use no more elevation categories than the
hierarchy needs; a page may reuse one category across several related objects.
-Same-family colored shadow is reserved for a focal accent.
-On dark backgrounds a light hairline or restrained glow separates surfaces; glow on body copy reduces legibility.
-For older/strict renderers, replace a filter with two or three offset
-translucent shapes behind the object:
-alpha `0.03–0.05`, increasing offset/radius, and optional same-family tint near
-`0.04` (`Native-stable`).
+Same-family colored shadow is reserved for a focal accent. On dark backgrounds
+a light hairline or restrained glow separates surfaces; glow on body copy
+reduces legibility. For older/strict renderers, replace a filter with two or
+three offset translucent shapes behind the object: alpha `0.03–0.05`,
+increasing offset/radius, and optional same-family tint near `0.04`
+(`Native-stable`).
---
### 6.5 Image Treatments, Overlays, and Glass-like Surfaces
-#### Image Carrier and Crop Contracts
-
| Need | Authoring contract | Fidelity |
|---|---|---|
-| Cover/crop | Readable raster dimensions + aligned `slice` | Native `srcRect`; `Native-stable`; otherwise native crop cannot be guaranteed |
+| Cover/crop | Readable raster dimensions + aligned `slice` | Native `srcRect`; `Native-stable` |
| Contain/fit | Aligned `meet` | Fitted picture frame; `Native-normalized` |
| Stretch | `preserveAspectRatio="none"` | Native stretched frame |
| Uniform fade | `<image opacity="...">` | Native picture alpha |
| Shaped picture | §1.2 image-only `clip-path` | Preset/custom picture geometry |
-**Hard rule — closed image aspect-ratio grammar**: on `<image>`, omit
-`preserveAspectRatio` for the default `xMidYMid meet`, use `none` alone for
-stretch, or use one of the nine case-sensitive alignments (`xMinYMin`,
-`xMidYMin`, `xMaxYMin`, `xMinYMid`, `xMidYMid`, `xMaxYMid`, `xMinYMax`,
-`xMidYMax`, `xMaxYMax`) followed by explicit `meet` or `slice`. Generated SVG
-always includes the mode on an aligned value. An alignment without a mode and
-values needing whitespace normalization are compatible input and receive a
-Checker recommendation. Empty values, `defer`, unknown/wrong-case alignments or
-modes, `none` with a mode, and extra tokens are errors; the converter never
-guesses a fallback.
-
-**Hard rule — fit/clip interaction**: a non-trivial clip disables `meet`
-frame-fit. Match the image box to the source ratio or use `slice`. 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.
-The carrier may keep object-local id, role, transform, and
-`data-pptx-carrier`. It may own `data-pptx-layer="master|layout"` only when
-the carrier itself is the direct fixed atom. It must not own
-`data-pptx-placeholder`, `data-pptx-binding`, or chart/table replacement
-metadata; keep slot ownership on the outer placeholder boundary.
-
-**Hard rule — picture frames and sources are explicit and decodable**: every
-SVG `<image>` has explicit positive `width`/`height` and exactly one non-empty
-`href` or compatible `xlink:href`. A data URI must use a supported `image/*`
-MIME type, valid strict base64 when marked
-`base64`, a non-empty payload, and bytes that decode as the declared format.
-An external asset must resolve, use a supported extension, be non-empty, and
-decode as that extension. The registered formats are PNG, JPEG, GIF, WebP,
-BMP, TIFF, SVG, EMF, and WMF. Explicit template substitution tokens may remain
-unresolved only during template checking; export requires the resolved image.
-Missing, ambiguous, corrupt, mislabeled, or unsupported sources are errors and
-must never be dropped or packaged as invalid zero-byte media.
-
-**Hard rule — nested SVG is picture-crop transport, not a general viewport**:
-every non-root `<svg>` is the exact wrapper accepted by the shared crop parser:
-
-| Part | Required form |
-|---|---|
-| Outer | Registered `x`, `y`, positive `width`/`height`; four ordinary-decimal unit coordinates in `viewBox`; `preserveAspectRatio="none"`; `overflow="hidden"` |
-| Child | Exactly one direct empty `<image>` with one non-empty `href`/`xlink:href`, `x="0" y="0" width="1" height="1" preserveAspectRatio="none"` |
-| Context | Only root SVG / ordinary visual `<g>` ancestors; outer may add `id`, supported `transform`, registered layer/carrier metadata, and `data-pptx-frame`, `data-pptx-object`, `data-pptx-shape-id`, `data-pptx-shape-name`, `data-pptx-shape-scope`; an exact imported picture carrier may hold its one §6.4 filter outside this viewport |
-| Shape crop | Exact outer `data-pptx-crop="1"`; authored wrappers put the registered, locally resolving image-only clip on the inner image, using `userSpaceOnUse` geometry matching the visible `viewBox`; legacy imported outer clips remain compatible |
-
-The inner image may add only registered `opacity` and that clip. Quantize the
-`viewBox` without clamping: every signed crop fits
-`-2147483648..2147483647`, with `l + r < 100000` and `t + b < 100000`.
-Retain negative/outside-source crops exactly; write redundant `0 0 1 1` as a
-plain `<image>`. Extra, indirect, or character content; unknown attributes;
-malformed or unrepresentable crops; and general nested viewports fail. Checker
-and converter share this parser.
-
-#### Image Overlay and Material Techniques
+Every `<image>` has explicit positive `width`/`height`, one decodable
+project-local or data-URI `href`, and — when not the default `xMidYMid meet` —
+an aligned `preserveAspectRatio` with explicit `meet` or `slice`, or `none`
+alone. A clip disables `meet` frame-fit, so match the box to the source ratio
+or use `slice`; put a §6.4 filter directly on an unclipped image, and for a
+clipped one on an exact outer `<g>` whose sole visual child is that image —
+never both on the same `<image>`. A nested `<svg>` is only the exact
+single-image crop wrapper the crop parser accepts, not a general viewport.
| Overlay | Construction | Typical stops / alpha |
|---|---|---|
@@ -445,39 +267,15 @@ fidelity.
### 6.6 Lines, Connectors, Borders, and Markers
-| Surface | Contract / native result |
-|---|---|
-| Solid stroke/width/alpha | `Native-stable` editable line |
-| `4,4`; `6,3`; `2,2`; `8,4`; `8,4,2,4` (comma or space separators) | `dash`; `dash`; `sysDot`; `lgDash`; `lgDashDot` (`Native-normalized`) |
-| Canonical custom dash | Exactly two positive finite unitless ordinary decimals (`dash gap`); export scales/quantizes against stroke width; `Native-normalized` |
-| Compatible custom dash | Three or more positive finite unitless values are accepted but reduce to the first pair with a Checker recommendation; compatible numeric spellings also warn |
-| `stroke-linecap` | `butt`, `round`, `square`; `Native-stable` |
-| `stroke-linejoin` | `miter`, `round`, `bevel`; `Native-stable` |
-| `vector-effect` | Exactly `none` or `non-scaling-stroke`; export resolves the choice into native line width (`Native-normalized`) |
-| `stroke-dashoffset` | No general line mapping; allowed only as a direct finite unitless ordinary-decimal attribute on a §6.10 thick-circle shorthand (`px` suffix is compatible input and warns) |
-| Gradient stroke | §6.3; re-import may flatten to first stop |
-| `marker-start` / `marker-end` | §1.1 native line end; type `Native-normalized`, size `Approximate` (`sm/med/lg`) |
-
-PPTX import treats unsupported line properties as source diagnostics: tolerant
-mode retains the object and omits only the unsupported outline; `--strict`
-retains the closed rejection behavior. See
-[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).
-
-The dash grammar is closed: exact lowercase `none`, or at least two finite
-unitless numbers separated by whitespace or one comma. Generated SVG uses
-ordinary decimal spellings. A leading plus sign, exponent, trailing decimal
-point, surrounding whitespace, or longer custom list is compatible input and
-produces a non-blocking normalization recommendation. Unknown units, one-value
-arrays, empty or repeated comma fields, non-finite values, and negative or zero
-entries are errors. The only zero exception is a gap declared directly on the
-§6.10 thick-circle element.
-
-Generated cap, join, and `vector-effect` values use the exact lowercase tokens
-in the table. Surrounding whitespace is compatible input and produces a
-recommendation; every other token is an error.
+A solid stroke with width and alpha is an editable native line. Dashes map to
+the five presets (`4,4` / `6,3` dash, `2,2` sysDot, `8,4` lgDash, `8,4,2,4`
+lgDashDot) or to one custom `dash gap` pair; caps are `butt` / `round` /
+`square`, joins `miter` / `round` / `bevel`, `vector-effect` `none` or
+`non-scaling-stroke`. Markers follow §1.1 (type native, size approximate); a
+gradient stroke follows §6.3.
**Default — relationship-fit dash rhythm (may override when style calls for
-another rhythm)**: After §6.1 selects dash, preserve direction markers and
+another rhythm)**: after §6.1 selects dash, preserve direction markers and
branch-owned placeholder patterns.
| Already-dashed/dotted job (illustrative) | Dash |
@@ -487,39 +285,17 @@ branch-owned placeholder patterns.
| Optional/future timeline/flow connector | `8,4` |
| Technical/dimension line | `8,4,2,4` |
+**Default — contour-fit joins (may override when the resolved style calls for
+another character)**: smooth polyline/organic form → `round`; technical
+diagram → `bevel`; crisp rectangle/arrow → `miter`.
+
```xml
-<!-- General boundary versus quiet non-image placeholder -->
<rect x="60" y="60" width="400" height="240" rx="12"
fill="none" stroke="#999999" stroke-width="2" stroke-dasharray="4,4"/>
-<line x1="100" y1="360" x2="1180" y2="360"
- stroke="#CCCCCC" stroke-width="1" stroke-dasharray="2,2"/>
-
-<!-- Optional/future timeline connector versus technical dimension line -->
<line x1="100" y1="420" x2="500" y2="420"
stroke="#1A73E8" stroke-width="2" stroke-dasharray="8,4"/>
-<line x1="620" y1="420" x2="1020" y2="420"
- stroke="#555555" stroke-width="2" stroke-dasharray="8,4,2,4"/>
-```
-
-**Default — contour-fit joins (may override when the resolved style calls for
-another character)**:
-
-| Contour/job (illustrative) | Join |
-|---|---|
-| Smooth polyline/organic form | `round` |
-| Technical diagram | `bevel` |
-| Crisp rectangle/arrow | `miter` |
-
-```xml
-<!-- Smooth series: round avoids a miter spike at the turn. -->
<polyline points="100,200 200,100 300,200" fill="none"
stroke="#1A73E8" stroke-width="3" stroke-linejoin="round"/>
-
-<!-- Technical corner versus crisp rectangle -->
-<polyline points="400,200 500,100 600,200" fill="none"
- stroke="#555555" stroke-width="3" stroke-linejoin="bevel"/>
-<rect x="740" y="120" width="180" height="160" fill="none"
- stroke="#333333" stroke-width="3" stroke-linejoin="miter"/>
```
Match marker paint to the parent stroke using the shape-specific channel from
@@ -537,105 +313,21 @@ fixed-density preset pattern:
### 6.7 Advanced Text Treatments
-**Hard rule — closed text property grammar**: generated text uses only the
-values in the `Canonical authoring` column. Registered compatible input remains
-convertible and receives a non-blocking normalization recommendation. Every
-other value is invalid; the converter must not replace it with a default.
-
-| Property | Canonical authoring | Compatible input | DrawingML mapping / rejection boundary |
-|---|---|---|---|
-| `font-weight` | `normal`, `bold`, or an exact integer hundred from `100` through `900` | `medium` → `500`; `semibold` → `600` | `normal` and `100..500` map to regular; `bold` and `600..900` map to `b="1"`; therefore numeric weights are `Native-normalized` |
-| `font-style` | `normal` or `italic` | None | `italic` maps to `i="1"`; oblique, angle, relative, and CSS-wide values are invalid |
-| `text-anchor` | `start`, `middle`, or `end` on `<svg>`, `<g>`, or `<text>` | None | Maps to left/center/right paragraph alignment plus normalized frame position; it is invalid on `<tspan>` because run-level anchoring has no mapping |
-| `text-decoration` | `none`, `underline`, `line-through`, or `underline line-through` | `line-through underline` → canonical order | Maps to the single underline and strike run properties; unknown, repeated, or substring-like tokens are invalid |
-| `baseline-shift` | Exact direct `super` or `sub` on `<tspan>` | None | Maps to editable ordinary-text `a:rPr@baseline` at `30000` or `-25000`; it does not resize the run, is invalid as inline style or on any other element, and cannot combine with an inline formula marker |
-| `letter-spacing` | Finite unitless ordinary decimal SVG px | The same ordinary decimal with `px`, `pt`, or `em`; normalize to unitless px | Maps to `a:rPr@spc`; the final value must fit DrawingML `-400000..400000`, and negative tracking must leave every generated DrawingML run with a positive estimated advance and its text frame with a positive extent; keywords, percentages, exponents, leading plus signs, trailing decimal points, non-finite values, and other units are invalid |
-
-The registered inheritable text properties follow SVG inheritance, including
-declarations on the root `<svg>`: inline `style` overrides the same element's
-direct attribute, which overrides its ancestor. `baseline-shift` is the narrow
-exception: declare it directly on the owning `<tspan>`; nested inline content
-inherits that run shift, while surrounding text keeps its own baseline.
-Relative font sizes and `em` tracking resolve against the same effective
-inherited size in Checker and converter. Every declaration is validated even
-when a later declaration overrides it, so hidden garbage cannot bypass
-preflight.
-
-The DrawingML character-spacing range is necessary but not sufficient for
-negative tracking. After run assembly, each output run must retain a positive
-estimated advance using the quantized `sz` and `spc` values that will actually
-be written; a wider sibling run or paragraph line cannot hide a run whose
-aggregate advance would reverse or collapse, which can reorder or drop
-characters across PowerPoint-compatible renderers. The generated text frame
-must also retain a positive horizontal and vertical extent. Checker rejects
-directly measurable single-line violations, and the converter revalidates
-every generated run and text frame before writing OOXML. It must not clamp,
-take the absolute value of, or otherwise hide a non-positive advance or extent.
-Adjacent authored runs with identical final DrawingML run properties form one
-output run before sizing and validation; splitting text across equivalent
-`<tspan>` nodes is not a tracking escape hatch. Tracking and width estimates
-count the registered project text clusters rather than raw Unicode code points:
-combining marks, variation selectors, emoji modifiers and ZWJ sequences,
-paired regional indicators, and same-script virama conjuncts do not receive
-internal spacing.
-An unchanged imported native text body reuses the geometry carrier's positive
-shape frame and attaches the preserved `txBody` payload instead of regenerating
-runs or a text frame from the SVG estimate.
-
-**Hard rule — element-specific text surface**:
-
-- Inheritable text declarations belong only on `<svg>`, `<g>`, `<text>`, or
- `<tspan>`; placing them on geometry, image, definition, or reuse elements is
- an error rather than ignored decoration.
-- `<text>` accepts `x`, `y`, registered paint/alpha/run properties, the text
- properties above, `font-family`, `font-size`, direct `filter`, direct
- `transform`, `xml:space`, `id`, and project `data-*` metadata.
-- `<tspan>` accepts `x`, `y`, `dx`, `dy`, registered paint/alpha/run
- properties, `font-family`, `font-size`, `font-weight`, `font-style`,
- `letter-spacing`, `text-decoration`, direct `baseline-shift`, `xml:space`,
- `id`, and project `data-*` metadata. It does not accept `text-anchor`,
- `filter`, or `transform`.
-- `word-spacing`, `dominant-baseline`, `alignment-baseline`,
- font shorthand/variant/stretch/feature/variation/synthesis controls,
- `font-kerning`/`kerning`, `font-size-adjust`, `line-height`, text alignment,
- indent/shadow/rendering controls, white-space/word-break/hyphenation
- controls, `writing-mode`, `vertical-align`, `direction`, `unicode-bidi`, and
- `text-transform` have no registered native mapping and are errors as direct
- attributes or inline style.
-- Any other unregistered `font-*` or `text-*` property is also an error; the
- closed grammar must not grow through an ignored CSS spelling.
-
-**Hard rule — project text whitespace**:
-
-- `xml:space` is the project's closed authoring control for significant text
- whitespace. It is valid only as an exact direct attribute on `<text>` or
- `<tspan>`, accepts only the case-sensitive values `default` and `preserve`,
- inherits through the text tree, and may be reset on a child `<tspan>`.
-- The project maps this control to the visible Chromium/SVG2 behavior used by
- Live Preview; it does not claim the legacy SVG 1.1 newline-deletion model.
- XML line endings and tabs become U+0020 SPACE. In `default` mode, contiguous
- U+0020 characters collapse across inline run boundaries and leading or
- trailing default-mode spaces in the resulting text chunk are removed. In
- `preserve` mode, every resulting U+0020 character remains significant.
-- Only XML whitespace is normalized. NBSP, ideographic space, and other
- Unicode spacing characters remain literal text and must not be rewritten by
- a generic Unicode-whitespace regular expression.
-- Source line breaks do not create PowerPoint paragraphs. Use the registered
- positioned-`tspan`/paragraph structure for visual lines, and preserve DOM
- text/tail order plus original style inheritance when normalizing that
- structure.
-
-These allowlists are additive to the global structural blacklist and the
-paint, font-size, opacity, filter, and transform value contracts owned by their
-respective sections; they do not weaken those contracts.
+Generated text uses only the canonical values: `font-weight` `normal` / `bold`
+/ an integer hundred, `font-style` `normal` / `italic`, `text-anchor` on
+`<text>` or above, `text-decoration` `underline` / `line-through` / both,
+direct `baseline-shift="super|sub"` on `<tspan>`, and unitless-px
+`letter-spacing` and `font-size`. Inheritable text declarations belong only on
+`<svg>`, `<g>`, `<text>`, or `<tspan>`; `xml:space="preserve"` on `<text>` /
+`<tspan>` is the one whitespace control. Every other `font-*` / `text-*`
+property has no native mapping and is an error.
| Treatment | SVG surface | Result / boundary |
|---|---|---|
| Underline / strike / both | `text-decoration="underline"`, `line-through`, or both | `Native-stable`; both emits both run properties |
| Mixed runs | Non-positional `<tspan>` | One `Native-normalized` editable frame; §4.2 |
-| Superscript / subscript | Direct `baseline-shift="super|sub"` on `<tspan>` | Editable ordinary-text run at PowerPoint's native baseline offset; set `font-size` on the same run when a smaller glyph is intended |
-| Font size | Generated default is a finite unitless SVG px value; compatible `px`, `pt`, `pc`/`pica`, `in`, `cm`, `mm`, `q`, `em`, and `rem` values receive a recommendation warning only | Converted to SVG px, then editable DrawingML point size; unsupported units/percentages error |
-| Tracking | §6.7 closed `letter-spacing` grammar | `Native-normalized`; compatible units normalize to SVG px before DrawingML conversion |
+| Superscript / subscript | Direct `baseline-shift="super|sub"` on `<tspan>` | Editable run at PowerPoint's native baseline offset; set `font-size` on the same run when a smaller glyph is intended |
+| Tracking | Unitless-px `letter-spacing` | `Native-normalized`; negative tracking must leave every run a positive advance |
| Transparency | `opacity` / `fill-opacity` on text/run | `Native-normalized` run alpha, not isolated compositing |
| Gradient fill | §6.3 gradient on text/run | Editable fill; geometry normalizes |
| Outline | Solid `stroke`, `stroke-width`, `stroke-opacity` | `Native-normalized` editable run outline; re-import does not reconstruct it |
@@ -658,85 +350,50 @@ conventionally read as polarity.
</text>
```
-**Underline**: conventionally marks links, key terms, or local emphasis.
+**Underline** conventionally marks links, key terms, or local emphasis —
+decorate the linked run, not the whole sentence. **Strikethrough** marks
+removed/former values; it is ordinary notation, not a style-exclusive effect.
```xml
-<!-- Key term -->
-<text x="100" y="200" font-size="20" fill="#333333"
- text-decoration="underline">Important Term</text>
-
-<!-- Link: decorate the linked run, not the whole sentence. -->
<text x="100" y="240" font-size="18" fill="#333333">Read <a
href="https://example.com"><tspan text-decoration="underline">the guide</tspan></a>.</text>
+<text x="100" y="200" font-size="20" xml:space="preserve">Current <tspan
+ fill="#999999" text-decoration="line-through">old</tspan> value</text>
+<text x="100" y="240" font-size="20">CO<tspan
+ baseline-shift="sub" font-size="14">2</tspan></text>
```
-**Hard rule — generated decorative lettering ownership**: Approved AI
+**Hard rule — generated decorative lettering ownership**: approved AI
decorative lettering is a prepared `<image>` asset under the image contracts,
not an advanced native-text treatment. Keep ordinary editable titles and
subtitles as normal `<text>`; this contract does not add WordArt, text warp, or
text-on-path authoring.
-```xml
-<text x="100" y="200" font-size="20" xml:space="preserve">Current <tspan
- fill="#999999" text-decoration="line-through">old</tspan> value</text>
-<text x="100" y="240" font-size="20">CO<tspan
- baseline-shift="sub" font-size="14">2</tspan></text>
-```
-
-Strikethrough conventionally marks removed/former values; it is ordinary notation, not a
-style-exclusive effect. Imported double underline/strike normalizes to single.
-Bullet detection allows optional leading whitespace, requires non-empty content,
-and leaves non-leading decorative glyphs as ordinary text.
-CJK tracking defaults near/below 2% of font size and above 5% triggers review. Text outline is solid only. `textPath`, masks, blend
-modes, generated effects, and text-image knockouts are outside editable text.
+CJK tracking defaults near/below 2% of font size and above 5% triggers review.
+Text outline is solid only. `textPath`, masks, blend modes, generated effects,
+and text-image knockouts are outside editable text.
---
### 6.8 Transforms, Layering, and Static Reuse
-| Surface | Contract / fidelity |
-|---|---|
-| `rotate(angle[, cx, cy])` | Geometry/image/text/ordinary group; `Native-normalized` |
-| `translate(x y)` | Geometry/image/group; pure translation also safe on text; `Native-normalized` |
-| Positive scale / negative mirror | Geometry/image or a group/use whose expanded visual subtree is geometry/image only; explicit pivot; `Native-normalized` |
-| `matrix(a b c d e f)` | Geometry/image or the same geometry/image-only group/use; transformed axes finite, non-zero, orthogonal; excludes rounded rectangles and subtrees containing them; `Native-normalized` |
-| Source order | Back-to-front PPT z-order; `Native-stable` |
-| `<g opacity>` | Compatible approximate mapping; generated SVG prefers descendant alpha, §2.2 |
-| Local `<use>` | §1.3 compile-time reuse; `Native-normalized` |
-
-**Hard rule — closed transform grammar**: Use only lowercase `translate`,
-`scale`, `rotate`, and `matrix` with exact finite unitless argument counts:
-`translate` 1/2, `scale` 1/2, `rotate` 1/3, and `matrix` 6. Separate arguments
-and operations with whitespace or one comma. Leading/trailing/repeated commas,
-adjacent operations without a separator, units, unknown functions, and
-incomplete input fail quality check and export. Generated numeric tokens use
-ordinary decimals; a supported leading `+`, exponent, or trailing decimal point
-remains compatible input and receives a non-blocking normalization warning.
-Model-facing translation values, rotation centers, and matrix `e/f` use at
-most two decimals under §1.4; angles, scale arguments, and matrix `a/b/c/d`
-retain the precision required by the transform.
-
-Set text size/position directly. A text transform is either a translate-only
-list or one rotate operation; do not scale, matrix-transform, or mix operations
-on text. A group containing text follows the same translate-only/single-rotate
-limit. `skewX`, `skewY`, zero/non-orthogonal axes, and shear matrices are
-forbidden. Native chart/table markers allow translate/scale only. The §6.10
-thick-circle shortcut does not inherit general transform support. Positive
-rotation is clockwise and pivoted rotation normalizes the native frame. Every
-cumulative matrix, including transforms split across ancestors, must remain
-finite, non-zero, and orthogonal; importer/live-editor matrices do not expand
-the hand-authored contract.
-Mirror around vertical pivot `cx` with
-`translate(cx 0) scale(-1 1) translate(-cx 0)`; use the analogous Y sequence
-for a horizontal pivot. During mirror materialization, imported PowerPoint
-groups with an axis flip keep their geometry reflection, while each descendant
-SVG text node receives the matching counter-reflection so browser previews keep
-glyphs upright. The tool-side native record retains the source group flip.
+Use only lowercase `translate`, `scale`, `rotate`, and `matrix` with finite
+unitless arguments; `rotate` is clockwise and may take a pivot. Geometry,
+images, and geometry-only groups accept any of them (`Native-normalized`) as
+long as the cumulative matrix stays finite, non-zero, and orthogonal — no
+`skewX` / `skewY` or shear, and `matrix` excludes rounded rectangles. Text, and
+any group containing text, takes only a translate-only list or one rotate; set
+text size/position directly. Native chart/table markers allow translate/scale
+only. Mirror around a vertical pivot `cx` with
+`translate(cx 0) scale(-1 1) translate(-cx 0)`, and never mirror text, logos,
+or directional evidence.
Layer back-to-front: background/image → scrim/shadow → main geometry → labels /
-icons → top annotation. Finalization and native export independently expand
-`<use>` into cloned editable primitives; PowerPoint does not retain a symbol /
-instance graph.
+icons → top annotation; source order is PPT z-order. Local `<use>` (§1.3) is
+compile-time reuse — finalization and native export expand it into cloned
+editable primitives, and PowerPoint retains no symbol/instance graph. Group
+opacity remains an approximate compatibility mapping; generated SVG prefers
+descendant alpha (§2.2).
---
@@ -750,24 +407,13 @@ instance graph.
| `A` | Cubic segments of at most 90° | `Approximate` |
| `Z`; polygon/polyline | Closed/open freeform | `Native-normalized` |
-**Hard rule — complete freeform grammar**: Generated `path@d` and
-`polygon` / `polyline@points` use finite unitless ordinary decimals and only
-the commands registered above. Native export consumes the complete attribute;
-it never extracts recognizable fragments while ignoring other characters.
-Finite scientific notation, a leading plus sign, and a trailing decimal point
-remain read-compatible and receive recommendation warnings; generated SVG does
-not write them. Unknown commands or characters, misplaced/repeated commas,
-non-finite numbers, missing attributes, incomplete command groups, and odd
-point counts are invalid. A path starts with `M` / `m`; `A` radii are
-non-negative and both arc flags are exactly `0` or `1`. Each registered path
-command accepts its uppercase absolute and lowercase relative form. Legal
-separator-free arc flag sequences remain valid and are parsed as individual
-flag tokens. A polygon has at least three coordinate pairs and a polyline at
-least two.
-
-**Validation**: Checker and native export consume the same parser in
-[`paths.py`](../scripts/svg_to_pptx/drawingml/paths.py); native-object fallback
-bounds reuse its normalized commands rather than a second path grammar.
+Write `path@d` and `points` with finite unitless ordinary decimals and only
+these commands; a path starts with `M`, arc flags are `0`/`1`, a polygon has
+≥3 pairs and a polyline ≥2. Command identity, relative coordinates, shorthand,
+arc parameters, and original handles are not retained; geometry needs non-zero
+bounds. Do not depend on `fill-rule="evenodd"` — build explicit visible
+geometry, bake an essential knockout, or on a fixed background use a
+background-colored overlay.
**Reference — not a constraint**: use the fewest curve segments and control
points that preserve the intended silhouette. Set endpoints and tangent
@@ -781,29 +427,19 @@ preserve deliberate tangent continuity.
fill="none" stroke="#0F766E" stroke-width="4" stroke-linecap="round"/>
```
-Command identity, relative coordinates, shorthand, arc parameters, and original
-handles are not retained. Geometry needs non-zero bounds. Before authoring a
-freeform, apply [`native-shape-authoring.md`](./native-shape-authoring.md):
+Before authoring a freeform, apply [`native-shape-authoring.md`](./native-shape-authoring.md):
prefer editable primitives and exact Office presets, independently composed
when possible; materialize a Boolean only when one contour requires it. Use a
-closed cubic path only for an organic silhouette those
-cannot express, polygon/closed path for unmatched ribbons/facets, and an open
-path only for a required data curve, custom route, or locked or Quick-resolved
-hand-drawn / organic style. Straight relationships use `<line>`; exact stock bends/curves
+closed cubic path only for an organic silhouette those cannot express,
+polygon/closed path for unmatched ribbons/facets, and an open path only for a
+required data curve, custom route, or locked or Quick-resolved hand-drawn /
+organic style. Straight relationships use `<line>`; exact stock bends/curves
use an authored native Connector preset. Multi-`M` paths remain available for
-exact linework, and a [`shared-standards-core.md`](./shared-standards-core.md)
-§1.2 path clip for unmatched organic pictures. Filled silhouettes end with
-`Z`; open paths use `fill="none"`. Do not depend on
-`fill-rule="evenodd"`; build explicit visible geometry or bake an essential
-knockout.
-For a fixed background, a background-colored overlay is also valid.
-
-| Rounded rect input | Result |
-|---|---|
-| One positive radius, or `0 < rx == ry <= min(width,height)/2` | `Native-stable` adjustable `roundRect` without distorting transforms; the same short-side limit applies to one-radius input |
-| `0 < abs(rx-ry) < 0.5px` after scaling | One normalized native radius; `Approximate` |
-| `abs(rx-ry) >= 0.5px`, either positive | Cubic custom geometry; no radius handle; `Approximate` |
-| Equal radius above half the short side | Native short-side clamp may differ from SVG; `Approximate` |
+exact linework, and a §1.2 path clip for unmatched organic pictures. Filled
+silhouettes end with `Z`; open paths use `fill="none"`. A rounded `<rect>`
+stays a native adjustable `roundRect` only while `rx == ry` and the radius is at
+most half the short side; unequal radii become custom geometry without a
+handle.
---
@@ -820,10 +456,8 @@ For clockwise pie/donut sectors, default to `-90°` only when the chart starts a
12 o'clock. A full-circle percentage sector spans `percentage × 360°`;
large-arc is `1` above `180°`; outer sweep is `1`, inner return is `0`. Split
both outer and inner boundaries of a full ring into at least two arcs each.
-Calculated endpoints survive subject to EMU rounding; `A` curves remain cubic
-approximations. Verify all spans plus gaps against the planned sweep.
-Explicit arc sectors are editable `Approximate` freeforms. Thin circles using a
-§6.6 preset/two-number dash stay `Native-normalized` ellipse lines.
+Verify all spans plus gaps against the planned sweep. Explicit arc sectors are
+editable `Approximate` freeforms.
```xml
<!-- 75% donut: center 400,400; outer 180; inner 100; -90° → 180°. -->
@@ -834,26 +468,19 @@ Explicit arc sectors are editable `Approximate` freeforms. Thin circles using a
**Gauge**: require `max > min`, `p = clamp((value-min)/(max-min),0,1)`, and
`0 < planned clockwise sweep <= 360°`; value sweep is `p × planned sweep`.
`valueEndAngle = startAngle + valueSweep`; large-arc is `1` iff
-`abs(valueSweep) > 180°`.
-Omit the value sector at `p=0`. At `p=1` with `360°`, split both boundaries into
-at least two arcs. Track/value share center, radii, start, and sweep flags.
-
-**Sunburst — `Approximate`**: one explicit annular sector per node; each depth owns one radius
-band and child angular intervals partition the parent. Do not use one `evenodd`
-compound ring.
-
-**Thick-circle shorthand — `Approximate`, non-position-sensitive only**:
-
-- One circle per segment; `fill="none"`; the circle may use one `rotate` for its
- start angle, and ancestor transforms must be translate-only.
-- Exactly two non-preset finite unitless ordinary-decimal values (`dash gap`);
- `stroke-dashoffset` is a direct finite unitless ordinary-decimal attribute.
-- `0 < stroke-width < 2r`, `stroke-width/r >= 0.15`,
- `0 < dash < 2πr`, `gap >= 0`, and `dash + gap >= 2πr - 1` SVG unit. The
- one-unit tolerance exists only for integer-rounded circumference values.
-- Native construction uses only the first dash and re-imports as a freeform.
- Its native start is 90° counterclockwise from the SVG preview; use explicit
- arcs whenever start angle, cap, or radial precision matters.
+`abs(valueSweep) > 180°`. Omit the value sector at `p=0`. At `p=1` with
+`360°`, split both boundaries into at least two arcs. Track/value share center,
+radii, start, and sweep flags.
+
+**Sunburst — `Approximate`**: one explicit annular sector per node; each depth
+owns one radius band and child angular intervals partition the parent. Do not
+use one `evenodd` compound ring.
+
+**Thick-circle shorthand — `Approximate`, non-position-sensitive only**: one
+`fill="none"` circle per segment with a two-value `dash gap` covering the
+circumference and a direct `stroke-dashoffset`; native construction keeps only
+the first dash and starts 90° counterclockwise from the SVG preview, so use
+explicit arcs whenever start angle, cap, or radial precision matters.
```xml
<circle cx="400" cy="400" r="140" fill="none" stroke="#2563EB"
@@ -952,10 +579,6 @@ halftone and route dense full-slide texture to §6.12.
glow; it does not blur the object or backdrop. Use a low-alpha raster for dense
grain and explicit circles/paths only for sparse editable marks.
-Unsupported source effects remain visible where possible and retain their
-import diagnostics. Resolve those diagnostics before release export; see
-[`conversion.md`](../scripts/docs/conversion.md#import-compatibility-and-recovery-boundary).
-
---
### 6.13 Page-Level Composition Recipes
@@ -974,6 +597,6 @@ back-to-front and omit every layer without a distinct job.
| Evidence / metric | Context field → local contrast → native leaders/labels/metric → optional focus/elevation | Claims stay native |
| Comparison | Matched planes → optional shared wash/divider → matched labels → one difference marker | Keep crop, elevation, and paint symmetric unless asymmetry is the claim |
| Closing / CTA | Receded field → echoed contour/gradient → native action → optional raised accent | Keep the native action legible |
-| Cross-page motif | Reuse contour, gradient direction, line language, texture, or light logic; vary scale, crop, or position by page job | Preserve recognition without copying the page or adding novelty effects |
+| Cross-page motif | Reuse contour, gradient direction, line language, texture, or light logic; vary scale, crop, position by page job | Preserve recognition without copying the page or adding novelty effects |
---
diff --git a/skills/ppt-master/scripts/docs/svg-contract.md b/skills/ppt-master/scripts/docs/svg-contract.md
index f6015ea7..5072796e 100644
--- a/skills/ppt-master/scripts/docs/svg-contract.md
+++ b/skills/ppt-master/scripts/docs/svg-contract.md
@@ -452,3 +452,356 @@ Only a wholly off-canvas direct-root Morph endpoint may set
Morph uses an explicit pair, and the marker never excuses partial page
overflow. Primitive fallback (a root with no top-level `<g>` at all) is capped
at 8 visible primitives.
+
+---
+
+# Part II — Effects and Geometry Grammar (`svg-effects.md` §6)
+
+Section numbers mirror [`svg-effects.md`](../../references/svg-effects.md).
+The shared converter implementation for §§6.2–6.8 is
+[`utils.py`](../svg_to_pptx/drawingml/utils.py); paths use
+[`paths.py`](../svg_to_pptx/drawingml/paths.py).
+
+## §6.2 Color, alpha, and opacity
+
+Compatible paint grammar includes recognized named colors, `rgb()` / `rgba()`,
+`hsl()` / `hsla()`, and `#RGB` / `#RGBA` / `#RRGGBB` / `#RRGGBBAA`; the
+converter also tolerates legacy bare 3/4/6/8-digit hexadecimal tokens. The
+generated canonical form is uppercase six-digit `#RRGGBB`; the checker prints
+an optional canonical rewrite as a recommendation warning that never blocks
+export. Explicit empty, malformed, or unrecognized paint values are errors in
+both checker and exporter preflight; neither converts unknown intent into
+`noFill` or default black.
+
+| Intent | Canonical authoring | Native result / fidelity |
+|---|---|---|
+| Solid fill or text paint | `fill="#RRGGBB"` | Solid DrawingML paint; `Native-stable` |
+| Fill/text alpha | Opaque `fill` + `fill-opacity="0..1"` | Fill/run alpha; `Native-stable` |
+| Stroke alpha | Opaque `stroke` + `stroke-opacity="0..1"` | Line/outline alpha; `Native-stable` |
+| Gradient-stop alpha | Opaque `stop-color` + `stop-opacity="0..1"` | Per-stop alpha; `Native-stable` |
+| Shadow/glow alpha | Opaque `flood-color` + `flood-opacity="0..1"` | Glow `Native-stable`; outer shadow visually calibrated `Approximate` |
+| Picture fade | `<image opacity="0..1">` | Picture `<a:alphaModFix>`; `Native-stable` |
+| One atomic whole-object fade | Non-group element `opacity="0..1"` | Alpha compiled into its supported paint/effect channels; `Native-normalized` |
+| Pattern alpha | Opaque pattern child paint + child fill/stroke opacity | Conditional; `native-data-interface.md` |
+| CSS color alpha | Alpha-bearing named/functional/HEX paint | `Native-normalized`; recommendation warning only |
+| Group fade | `<g opacity>` compatibility | `Approximate`; fidelity warning; §2.2 |
+
+```text
+effective fill alpha
+= color alpha × ancestor group opacity × element opacity × fill-opacity
+```
+
+`opacity`, `fill-opacity`, `stroke-opacity`, `stop-opacity`, and
+`flood-opacity` are finite unitless numbers from `0` to `1`; the converter also
+accepts finite numeric values that SVG/CSS clamps into that interval, and
+`stop-opacity` / `flood-opacity` additionally accept finite percentages (the
+checker reports those spellings as recommendation warnings). Malformed or
+non-finite values are errors. `fill="transparent"` / `stroke="transparent"`
+become no fill/line. PPTX import is a user-input boundary: tolerant mode
+retains recognized color semantics, omits only unsupported paint properties,
+and records the decision in `conversion-report.json`; `--strict` keeps the
+closed parser checks.
+
+## §6.3 Gradients and text picture fill
+
+| Concern | Contract |
+|---|---|
+| 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`, and the 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 |
+|---|---|
+| `<rect>`, `<circle>`, `<ellipse>`, `<path>`, `<polygon>` fill/stroke | Linear `Native-normalized`; radial `Approximate` |
+| `<line>` / `<polyline>` | Gradient stroke only; linear `Native-normalized`, radial `Approximate` |
+| `<text>` / non-positional `<tspan>` | Gradient fill only; no gradient text outline |
+| `<image>` | No gradient paint; use §6.5 overlays |
+
+Linear export preserves stops/alpha 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. 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 focus and records a diagnostic. Gradient strokes stay
+editable; reverse import may keep the first stop only. Stop alpha multiplies
+element opacity. An `objectBoundingBox` gradient stroke requires non-zero
+intrinsic width and height (a perfectly horizontal or vertical gradient ribbon
+disappears); checker and exporter reject the degenerate form.
+
+**Native text picture/texture fill**:
+
+| Concern | Contract |
+|---|---|
+| Target | Direct `fill="url(#id)"` on `<text>` or a non-positional `<tspan>`; the text remains editable |
+| Definition | Direct `<pattern>` child of `<defs>` with unique `id` and exact `data-pptx-text-image-fill="stretch"` or `"tile"` |
+| Image | Exactly one direct SVG-namespace `<image>` child; project-local or data-URI source; explicit positive `width` / `height` |
+| Native result | `stretch` → run-level `a:blipFill/a:stretch`; `tile` → run-level `a:blipFill/a:tile` |
+| Alpha | Text `fill-opacity` multiplies the native picture-fill alpha |
+| Forbidden | Preset-pattern attributes; `patternTransform`; additional pattern children; image style/alpha/clip/filter/mask/transform; use outside text; unannotated custom image patterns; multi-image/layer knockout composites |
+
+`stretch` is `Native-normalized`; `tile` may normalize tile scale or phase and
+needs visual review. Forward SVG→PPTX export is native; PPTX→SVG does not
+reconstruct run-level picture fills yet. Preset patterns are a separate
+interface in `native-data-interface.md`.
+
+## §6.4 Shadows and glow
+
+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>`; one validated compact authored shape-preset `<g>`; an exact outer `<g filter>` whose sole visual child is one clipped `<image>` |
+| Required primitive | `feDropShadow` or `feGaussianBlur` |
+| Generated glow form | Zero-offset `feDropShadow` with flood paint, or the complete blur + flood + composite + merge graph; never bare blur |
+| Required parameters | Explicit `stdDeviation` on either effect primitive; explicit `dx`, `dy`, and `flood-opacity` on `feDropShadow`; explicit `flood-opacity` on `feFlood`; explicit `slope` on linear `feFuncA` |
+| Accepted helpers | `feOffset`, `feFlood`, `feComposite`, `feMerge`, `feMergeNode`, `feComponentTransfer`, linear `feFuncA` |
+| Alpha transfer | Linear `feFuncA` maps multiplicative `slope` only; `intercept` is unsupported |
+| Blur sampling | `feGaussianBlur edgeMode` is unsupported |
+| Primitive coordinates | Omit `primitiveUnits` or use `userSpaceOnUse`; `objectBoundingBox` coordinates are unsupported |
+| Numeric values | Finite unitless values; non-negative `stdDeviation`; finite `dx` / `dy`; `feFuncA slope` within `0..1`; mapped glow `rad = stdDeviation × 9525`, shadow `blurRad = stdDeviation × 2 × 9525`, and shadow `dist = hypot(dx,dy) × 9525` must round into DrawingML `0..27273042316900` |
+| Classification | Meaningful non-zero offset → one outer shadow; zero/no offset → one glow |
+| Fidelity | `Approximate`; one filter becomes one DrawingML effect |
+
+Flood opacity, linear `feFuncA slope`, and element opacity multiply; the
+converter-only historical path may also multiply flood-color alpha and
+ancestor group opacity. Native export does not preserve filter-region,
+`in/in2/result`, merge order, or composite topology. Other primitives,
+multiple independent effects, and filters on `<tspan>` / ordinary `<g>` /
+unsupported targets are forbidden. Special `<g filter>` targets are limited to
+the helper-authored compact shape preset, the exact single clipped-image form,
+the hash-locked `data-pptx-part="geometry-preview"` transport of an imported
+preset, and the exact imported picture-crop carrier. Bare `feGaussianBlur`
+remains compatible input but is never generated: preview blurs the object
+while export emits glow. PPTX import maps one classifiable
+shape/connector/picture outer shadow or glow to this contract; unsupported
+effects and outer-shadow variants whose scale, skew, alignment, or rotation
+semantics cannot be retained become import diagnostics. Checker and exporter
+preflight enforce the same definition, reference, primitive, target, and
+numeric-value contract; missing required geometry is never replaced by effect
+defaults.
+
+## §6.5 Image carriers and crop transport
+
+| Need | Authoring contract | Fidelity |
+|---|---|---|
+| Cover/crop | Readable raster dimensions + aligned `slice` | Native `srcRect`; `Native-stable`; otherwise native crop cannot be guaranteed |
+| Contain/fit | Aligned `meet` | Fitted picture frame; `Native-normalized` |
+| Stretch | `preserveAspectRatio="none"` | Native stretched frame |
+| Uniform fade | `<image opacity="...">` | Native picture alpha |
+| Shaped picture | §1.2 image-only `clip-path` | Preset/custom picture geometry |
+
+**Closed aspect-ratio grammar**: on `<image>`, omit `preserveAspectRatio` for
+the default `xMidYMid meet`, use `none` alone for stretch, or use one of the
+nine case-sensitive alignments (`xMinYMin`, `xMidYMin`, `xMaxYMin`,
+`xMinYMid`, `xMidYMid`, `xMaxYMid`, `xMinYMax`, `xMidYMax`, `xMaxYMax`)
+followed by explicit `meet` or `slice`. An alignment without a mode and values
+needing whitespace normalization are compatible input with a recommendation.
+Empty values, `defer`, unknown/wrong-case alignments or modes, `none` with a
+mode, and extra tokens are errors.
+
+**Fit/clip interaction**: a non-trivial clip disables `meet` 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>`. The
+carrier may keep object-local id, role, transform, and `data-pptx-carrier`; it
+may own `data-pptx-layer="master|layout"` only when the carrier itself is the
+direct fixed atom, and never `data-pptx-placeholder`, `data-pptx-binding`, or
+chart/table replacement metadata.
+
+**Decodable sources**: every `<image>` has explicit positive `width`/`height`
+and exactly one non-empty `href` or compatible `xlink:href`. A data URI must use
+a supported `image/*` MIME type, valid strict base64 when marked `base64`, a
+non-empty payload, and bytes that decode as the declared format. An external
+asset must resolve, use a supported extension, be non-empty, and decode as
+that extension. Registered formats: PNG, JPEG, GIF, WebP, BMP, TIFF, SVG, EMF,
+WMF. Explicit template substitution tokens may remain unresolved only during
+template checking. Missing, ambiguous, corrupt, mislabeled, or unsupported
+sources are errors and are never packaged as zero-byte media.
+
+**Nested SVG is picture-crop transport, not a general viewport**: every
+non-root `<svg>` is the exact wrapper accepted by the shared crop parser:
+
+| Part | Required form |
+|---|---|
+| Outer | Registered `x`, `y`, positive `width`/`height`; four ordinary-decimal unit coordinates in `viewBox`; `preserveAspectRatio="none"`; `overflow="hidden"` |
+| Child | Exactly one direct empty `<image>` with one non-empty `href`/`xlink:href`, `x="0" y="0" width="1" height="1" preserveAspectRatio="none"` |
+| Context | Only root SVG / ordinary visual `<g>` ancestors; outer may add `id`, supported `transform`, registered layer/carrier metadata, and `data-pptx-frame`, `data-pptx-object`, `data-pptx-shape-id`, `data-pptx-shape-name`, `data-pptx-shape-scope`; an exact imported picture carrier may hold its one §6.4 filter outside this viewport |
+| Shape crop | Exact outer `data-pptx-crop="1"`; authored wrappers put the registered, locally resolving image-only clip on the inner image, using `userSpaceOnUse` geometry matching the visible `viewBox`; legacy imported outer clips remain compatible |
+
+The inner image may add only registered `opacity` and that clip. Quantize the
+`viewBox` without clamping: every signed crop fits
+`-2147483648..2147483647`, with `l + r < 100000` and `t + b < 100000`. Retain
+negative/outside-source crops exactly; write redundant `0 0 1 1` as a plain
+`<image>`. Extra, indirect, or character content; unknown attributes;
+malformed or unrepresentable crops; and general nested viewports fail.
+
+## §6.6 Lines, dashes, caps, joins, markers
+
+| Surface | Contract / native result |
+|---|---|
+| Solid stroke/width/alpha | `Native-stable` editable line |
+| `4,4`; `6,3`; `2,2`; `8,4`; `8,4,2,4` (comma or space separators) | `dash`; `dash`; `sysDot`; `lgDash`; `lgDashDot` (`Native-normalized`) |
+| Canonical custom dash | Exactly two positive finite unitless ordinary decimals (`dash gap`); export scales/quantizes against stroke width; `Native-normalized` |
+| Compatible custom dash | Three or more positive finite unitless values reduce to the first pair with a checker recommendation; compatible numeric spellings also warn |
+| `stroke-linecap` | `butt`, `round`, `square`; `Native-stable` |
+| `stroke-linejoin` | `miter`, `round`, `bevel`; `Native-stable` |
+| `vector-effect` | Exactly `none` or `non-scaling-stroke`; export resolves the choice into native line width (`Native-normalized`) |
+| `stroke-dashoffset` | No general line mapping; allowed only as a direct finite unitless ordinary-decimal attribute on a §6.10 thick-circle shorthand (`px` suffix warns) |
+| Gradient stroke | §6.3; re-import may flatten to first stop |
+| `marker-start` / `marker-end` | §1.1 native line end; type `Native-normalized`, size `Approximate` (`sm/med/lg`) |
+
+The dash grammar is closed: exact lowercase `none`, or at least two finite
+unitless numbers separated by whitespace or one comma. A leading plus sign,
+exponent, trailing decimal point, surrounding whitespace, or longer custom list
+is compatible input with a non-blocking normalization recommendation. Unknown
+units, one-value arrays, empty or repeated comma fields, non-finite values,
+and negative or zero entries are errors (the only zero exception is a gap on
+the §6.10 thick-circle element). Cap, join, and `vector-effect` accept only the
+exact lowercase tokens above; surrounding whitespace warns, every other token
+is an error. PPTX import treats unsupported line properties as source
+diagnostics: tolerant mode retains the object and omits only the unsupported
+outline; `--strict` retains the closed rejection behavior.
+
+## §6.7 Text property grammar
+
+| Property | Canonical authoring | Compatible input | DrawingML mapping / rejection boundary |
+|---|---|---|---|
+| `font-weight` | `normal`, `bold`, or an exact integer hundred from `100` through `900` | `medium` → `500`; `semibold` → `600` | `normal` and `100..500` map to regular; `bold` and `600..900` map to `b="1"`; numeric weights are `Native-normalized` |
+| `font-style` | `normal` or `italic` | None | `italic` maps to `i="1"`; oblique, angle, relative, and CSS-wide values are invalid |
+| `text-anchor` | `start`, `middle`, or `end` on `<svg>`, `<g>`, or `<text>` | None | Maps to left/center/right paragraph alignment plus normalized frame position; invalid on `<tspan>` |
+| `text-decoration` | `none`, `underline`, `line-through`, or `underline line-through` | `line-through underline` → canonical order | Maps to the single underline and strike run properties; unknown, repeated, or substring-like tokens are invalid |
+| `baseline-shift` | Exact direct `super` or `sub` on `<tspan>` | None | Maps to editable `a:rPr@baseline` at `30000` or `-25000`; does not resize the run; invalid as inline style or on any other element; cannot combine with an inline formula marker |
+| `letter-spacing` | Finite unitless ordinary decimal SVG px | The same decimal with `px`, `pt`, or `em`; normalized to unitless px | Maps to `a:rPr@spc`; the final value must fit DrawingML `-400000..400000`, and negative tracking must leave every generated run with a positive estimated advance and its text frame with a positive extent; keywords, percentages, exponents, leading plus signs, trailing decimal points, non-finite values, and other units are invalid |
+| `font-size` | Finite unitless SVG px | `px`, `pt`, `pc`/`pica`, `in`, `cm`, `mm`, `q`, `em`, `rem` (recommendation warning) | Converted to SVG px, then editable DrawingML point size; unsupported units/percentages error |
+
+Registered inheritable text properties follow SVG inheritance, including
+declarations on the root `<svg>`: inline `style` overrides the same element's
+direct attribute, which overrides its ancestor. `baseline-shift` is the narrow
+exception: declare it directly on the owning `<tspan>`. Every declaration is
+validated even when a later declaration overrides it.
+
+**Negative tracking**: after run assembly, each output run must retain a
+positive estimated advance using the quantized `sz` and `spc` values that will
+be written; a wider sibling run or paragraph line cannot hide a run whose
+aggregate advance would reverse or collapse. The generated text frame must
+retain a positive horizontal and vertical extent. The checker rejects directly
+measurable single-line violations, and the converter revalidates every run and
+frame before writing OOXML without clamping or hiding a non-positive value.
+Adjacent authored runs with identical final run properties form one output run
+before sizing; splitting text across equivalent `<tspan>` nodes is not a
+tracking escape hatch. Width estimates count the registered project text
+clusters (combining marks, variation selectors, emoji modifiers and ZWJ
+sequences, paired regional indicators, same-script virama conjuncts receive no
+internal spacing). An unchanged imported native text body reuses the geometry
+carrier's frame and attaches the preserved `txBody` payload.
+
+**Element-specific text surface**:
+
+- Inheritable text declarations belong only on `<svg>`, `<g>`, `<text>`, or `<tspan>`; placing them on geometry, image, definition, or reuse elements is an error.
+- `<text>` accepts `x`, `y`, registered paint/alpha/run properties, the text properties above, `font-family`, `font-size`, direct `filter`, direct `transform`, `xml:space`, `id`, and project `data-*` metadata.
+- `<tspan>` accepts `x`, `y`, `dx`, `dy`, registered paint/alpha/run properties, `font-family`, `font-size`, `font-weight`, `font-style`, `letter-spacing`, `text-decoration`, direct `baseline-shift`, `xml:space`, `id`, and project `data-*` metadata. It does not accept `text-anchor`, `filter`, or `transform`.
+- `word-spacing`, `dominant-baseline`, `alignment-baseline`, font shorthand/variant/stretch/feature/variation/synthesis controls, `font-kerning`/`kerning`, `font-size-adjust`, `line-height`, text alignment, indent/shadow/rendering controls, white-space/word-break/hyphenation controls, `writing-mode`, `vertical-align`, `direction`, `unicode-bidi`, `text-transform`, and any other unregistered `font-*` / `text-*` property are errors as direct attributes or inline style.
+
+**Project text whitespace**: `xml:space` is valid only as an exact direct
+attribute on `<text>` or `<tspan>`, accepts only `default` and `preserve`,
+inherits through the text tree, and may be reset on a child `<tspan>`. The
+project maps it to the visible Chromium/SVG2 behavior used by Live Preview:
+XML line endings and tabs become U+0020; in `default` mode contiguous spaces
+collapse across inline run boundaries and leading/trailing default-mode spaces
+in the resulting chunk are removed; in `preserve` mode every U+0020 remains
+significant. Only XML whitespace is normalized — NBSP, ideographic space, and
+other Unicode spacing characters remain literal. Source line breaks do not
+create PowerPoint paragraphs.
+
+Bullet detection allows optional leading whitespace, requires non-empty
+content, and leaves non-leading decorative glyphs as ordinary text; `·`/`•`
+become `•`, the other registered leaders (`● ▪ ■ ◆ ◇ ◦ ‣`) stay unchanged, and
+the marker run supplies color/alpha. Imported double underline/strike
+normalizes to single. Text outline is solid only; shadow/glow applies to
+`<text>` only and is `Approximate`.
+
+## §6.8 Closed transform grammar
+
+| Surface | Contract / fidelity |
+|---|---|
+| `rotate(angle[, cx, cy])` | Geometry/image/text/ordinary group; `Native-normalized` |
+| `translate(x y)` | Geometry/image/group; pure translation also safe on text; `Native-normalized` |
+| Positive scale / negative mirror | Geometry/image or a group/use whose expanded visual subtree is geometry/image only; explicit pivot; `Native-normalized` |
+| `matrix(a b c d e f)` | Geometry/image or the same geometry/image-only group/use; transformed axes finite, non-zero, orthogonal; excludes rounded rectangles and subtrees containing them; `Native-normalized` |
+| Source order | Back-to-front PPT z-order; `Native-stable` |
+| `<g opacity>` | Compatible approximate mapping; §2.2 |
+| Local `<use>` | §1.3 compile-time reuse; `Native-normalized` |
+
+Use only lowercase `translate`, `scale`, `rotate`, and `matrix` with exact
+finite unitless argument counts: `translate` 1/2, `scale` 1/2, `rotate` 1/3,
+`matrix` 6. Separate arguments and operations with whitespace or one comma.
+Leading/trailing/repeated commas, adjacent operations without a separator,
+units, unknown functions, and incomplete input fail quality check and export.
+A supported leading `+`, exponent, or trailing decimal point is compatible
+input with a normalization warning. Model-facing translation values, rotation
+centers, and matrix `e/f` use at most two decimals (§1.4); angles, scale
+arguments, and matrix `a/b/c/d` retain the precision the transform requires.
+
+A text transform is either a translate-only list or one rotate operation; a
+group containing text follows the same limit. `skewX`, `skewY`, zero or
+non-orthogonal axes, and shear matrices are forbidden. Native chart/table
+markers allow translate/scale only. The §6.10 thick-circle shortcut does not
+inherit general transform support. Positive rotation is clockwise and pivoted
+rotation normalizes the native frame. Every cumulative matrix, including
+transforms split across ancestors, must remain finite, non-zero, and
+orthogonal; importer/live-editor matrices do not expand the hand-authored
+contract. During mirror materialization, imported PowerPoint groups with an
+axis flip keep their geometry reflection while each descendant SVG text node
+receives the matching counter-reflection; the tool-side native record retains
+the source group flip.
+
+## §6.9 Freeform grammar and rounded rectangles
+
+| Input | Native normalization | Fidelity |
+|---|---|---|
+| `M/L/H/V`, absolute or relative | Absolute `M/L` | `Native-normalized` |
+| `C` | Cubic Bézier | `Native-normalized` |
+| `S/Q/T` | Explicit cubic controls | `Native-normalized` |
+| `A` | Cubic segments of at most 90° | `Approximate` |
+| `Z`; polygon/polyline | Closed/open freeform | `Native-normalized` |
+
+Generated `path@d` and `polygon` / `polyline@points` use finite unitless
+ordinary decimals and only the commands above; each command accepts its
+uppercase absolute and lowercase relative form. Native export consumes the
+complete attribute and never extracts recognizable fragments while ignoring
+other characters. Finite scientific notation, a leading plus sign, and a
+trailing decimal point are read-compatible with recommendation warnings.
+Unknown commands or characters, misplaced/repeated commas, non-finite numbers,
+missing attributes, incomplete command groups, and odd point counts are
+invalid. A path starts with `M` / `m`; `A` radii are non-negative and both arc
+flags are exactly `0` or `1` (separator-free flag sequences parse as
+individual tokens). A polygon has at least three coordinate pairs and a
+polyline at least two. Command identity, relative coordinates, shorthand, arc
+parameters, and original handles are not retained; geometry needs non-zero
+bounds. Do not depend on `fill-rule="evenodd"`.
+
+| Rounded rect input | Result |
+|---|---|
+| One positive radius, or `0 < rx == ry <= min(width,height)/2` | `Native-stable` adjustable `roundRect` without distorting transforms; the same short-side limit applies to one-radius input |
+| `0 < abs(rx-ry) < 0.5px` after scaling | One normalized native radius; `Approximate` |
+| `abs(rx-ry) >= 0.5px`, either positive | Cubic custom geometry; no radius handle; `Approximate` |
+| Equal radius above half the short side | Native short-side clamp may differ from SVG; `Approximate` |
+
+## §6.10 Thick-circle shorthand
+
+`Approximate`, non-position-sensitive use only:
+
+- One circle per segment; `fill="none"`; the circle may use one `rotate` for its start angle, and ancestor transforms must be translate-only.
+- Exactly two non-preset finite unitless ordinary-decimal values (`dash gap`); `stroke-dashoffset` is a direct finite unitless ordinary-decimal attribute.
+- `0 < stroke-width < 2r`, `stroke-width/r >= 0.15`, `0 < dash < 2πr`, `gap >= 0`, and `dash + gap >= 2πr - 1` SVG unit (the one-unit tolerance exists only for integer-rounded circumference values).
+- Native construction uses only the first dash and re-imports as a freeform. Its native start is 90° counterclockwise from the SVG preview; use explicit arcs whenever start angle, cap, or radial precision matters.
+
+Explicit arc sectors are editable `Approximate` freeforms; calculated endpoints
+survive subject to EMU rounding, and `A` curves remain cubic approximations.
+Thin circles using a §6.6 preset/two-number dash stay `Native-normalized`
+ellipse lines.
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index e0a1248a..4b7d6265 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -30,7 +30,7 @@
"skills/ppt-master/references/executor-notes.md": 1000,
"skills/ppt-master/references/shared-standards.md": 500,
"skills/ppt-master/references/shared-standards-core.md": 7000,
- "skills/ppt-master/references/svg-effects.md": 16000,
+ "skills/ppt-master/references/svg-effects.md": 9500,
"skills/ppt-master/references/native-data-interface.md": 7750,
"skills/ppt-master/references/pptx-structure-interface.md": 4750,
"skills/ppt-master/references/preset-shape-vocabulary.md": 2750,