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

fix(pptx-to-svg): block vertical text run-effect loss

hugohe3ac7d10f17632
diff --git a/docs/powerpoint-svg-mapping.md b/docs/powerpoint-svg-mapping.md
index 5fbb110a..622f0bdf 100644
--- a/docs/powerpoint-svg-mapping.md
+++ b/docs/powerpoint-svg-mapping.md
@@ -160,7 +160,7 @@ preset selection and authoring behavior are documented in
| Line arrowheads | Registered start/end markers | Native head/tail end properties | `Approximate` for marker size | See the conditional marker contract |
| Outer shadow | One supported shadow filter graph | Native outer shadow in `a:effectLst` | `Approximate`; one imported shape/connector source `outerShdw` is reconstructed only when its non-zero offset remains classifiable | Zero-offset source shadows and unsupported graph shapes are not silently reclassified |
| Glow | One supported glow filter graph | Native glow in `a:effectLst` | `Approximate`; one imported shape/connector source glow keeps the registered radius conversion | Review when the glow carries semantic emphasis |
-| Imported text-run effect | Unchanged `metadata[data-pptx-part="txbody"]` on a logical shape | Original native run effect inside `p:txBody` | `Native-stable` only while the raw payload remains usable; edits that would drop a non-empty run `effectLst` / `effectDag` block | Not public authoring syntax; the separate vertical-text output, relationship-bearing text bodies, and table-cell text bodies remain outside this guard |
+| Imported text-run effect | Unchanged `metadata[data-pptx-part="txbody"]` on a logical shape; import-only blocking effect status for separate vertical-text output | Original native run effect inside `p:txBody` | `Native-stable` only while the raw payload remains usable; edits or vertical-text normalization that would drop a non-empty run `effectLst` / `effectDag` block | Not public authoring syntax; relationship-bearing text bodies and table-cell text bodies remain outside this guard |
| Whole-object transparency | Atomic element `opacity` | Alpha distributed into supported native channels | `Native-normalized` | Prefer channel-specific alpha unless the whole atomic object fades |
| Group transparency | Compatible `<g opacity>` | Descendant-normalized approximation | `Approximate` with a warning | Generated SVG should prefer descendant alpha |
| Inner shadow, soft edge, reflection, blur, turbulence, blend mode, or arbitrary mask | No registered native mapping | Explicit geometry alternative or raster asset | `Bake-required`; PPTX import keeps the base object and emits blocking diagnostics for unsupported shape/connector effects, picture/group effect DAGs, and non-empty picture/group effect lists | Handled object effects cannot be reclassified or omitted; text-run safety follows the unchanged-`txBody` row above |
diff --git a/docs/zh/powerpoint-svg-mapping.md b/docs/zh/powerpoint-svg-mapping.md
index e5e29c35..0f2347b5 100644
--- a/docs/zh/powerpoint-svg-mapping.md
+++ b/docs/zh/powerpoint-svg-mapping.md
@@ -155,7 +155,7 @@ PowerPoint 意图
| 线条箭头 | 已登记起点/终点 marker | 原生 head/tail end 属性 | marker 大小为 `Approximate` | 见条件 marker 合同 |
| 外阴影 | 一个受支持 shadow filter 图 | `a:effectLst` 中的原生外阴影 | `Approximate`;仅当非零偏移仍可稳定分类时,才重建单一 shape/connector 来源 `outerShdw` | 零偏移来源阴影和不支持的图结构不会被静默改成其他效果 |
| 发光 | 一个受支持 glow filter 图 | `a:effectLst` 中的原生发光 | `Approximate`;单一 shape/connector 来源发光保持已登记的半径换算 | 发光承载语义强调时需复核 |
-| 导入的文字 run 效果 | 逻辑 shape 上未变更的 `metadata[data-pptx-part="txbody"]` | `p:txBody` 内原始原生 run 效果 | 仅在原始 payload 仍可用时为 `Native-stable`;会丢失非空 run `effectLst` / `effectDag` 的编辑将被阻断 | 不是公开创作语法;独立竖排输出路径、含关系引用的文本内容及表格单元格文本尚不在该保护范围内 |
+| 导入的文字 run 效果 | 逻辑 shape 上未变更的 `metadata[data-pptx-part="txbody"]`;独立竖排输出使用仅限导入的阻塞效果状态 | `p:txBody` 内原始原生 run 效果 | 仅在原始 payload 仍可用时为 `Native-stable`;会丢失非空 run `effectLst` / `effectDag` 的编辑或竖排文本规范化将被阻断 | 不是公开创作语法;含关系引用的文本内容及表格单元格文本尚不在该保护范围内 |
| 整个对象透明度 | 原子元素 `opacity` | alpha 分发至受支持原生通道 | `Native-normalized` | 除非整个原子对象需要淡出,否则优先通道专属 alpha |
| 组透明度 | 兼容 `<g opacity>` | 后代归一化近似 | `Approximate`,并产生 warning | 生成 SVG 应优先后代 alpha |
| 内阴影、柔化边缘、倒影、模糊、湍流、混合模式或任意 mask | 无已登记原生映射 | 显式几何替代或栅格资产 | `Bake-required`;PPTX 回导保留基础对象,并对不支持的 shape/connector 效果、图片/组效果 DAG 及非空图片/组效果列表产生阻塞诊断 | 已处理的对象效果不能被改成其他类型或静默省略;文字 run 安全边界见上方未变更 `txBody` 行 |
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index bbee6b84..2b334714 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -276,7 +276,7 @@ attributes, and no separate source-payload opt-in marker exists.
| `data-pptx-geometry-kind="custom"` + `data-pptx-custgeom` | Custom-geometry carrier | Preserve the validated original `a:custGeom` subtree. If the visible path hash is unchanged, export restores formulas, handles, connection sites, text rectangle, and path list exactly; edited paths compile from current SVG geometry. |
| `data-pptx-start/end-shape-id/site` | Connector logical `<g>` and carrier | Restore `a:stCxn` / `a:endCxn` after scoped shape-id allocation. A connector may retain one zero frame axis; it must not be expanded from visible stroke or marker bounds. |
| `data-pptx-shape-style` | Native carrier | Preserve a relationship-free `p:style` independently of text, including shapes with no visible text. |
-| `data-pptx-effect-status="unsupported"` + `data-pptx-effect-reason` | Imported `p:sp` / `p:cxnSp` logical object and native carrier; imported `p:pic` carrier and logical object; imported `p:grpSp` logical group | Record why an encountered source `effectLst` / `effectDag` cannot enter the registered target-specific effect mapping without changing semantics. Checker and export stop with the recorded reason; these attributes are diagnostics, not a preserved effect payload or authoring syntax. |
+| `data-pptx-effect-status="unsupported"` + `data-pptx-effect-reason` | Imported `p:sp` / `p:cxnSp` logical object and native carrier; imported `p:pic` carrier and logical object; imported `p:grpSp` logical group | Record why an encountered source object or text-run `effectLst` / `effectDag` cannot enter the registered target-specific effect mapping without changing semantics. Checker and export stop with the recorded reason; these attributes are diagnostics, not a preserved effect payload or authoring syntax. |
| `metadata[data-pptx-part="txbody"]` | Logical shape `<g>` | Preserve unchanged `p:txBody`, including an empty text body. Content, whitespace, positioning, visible typography, or incompatible child-topology edits invalidate the payload. A source payload with run-level effects then blocks checker/export instead of losing those effects; an effect-free payload uses the normal SVG text fallback. |
**Import/authoring representation split**:
@@ -789,9 +789,13 @@ unchanged `metadata[data-pptx-part="txbody"]` payload. If visible text,
typography, or child topology invalidates that payload, checker and exporter
stop when the source `rPr` / `defRPr` / `endParaRPr` contains a non-empty
`effectLst` or `effectDag`; effect-free edited text keeps the normal fallback.
+The separate vertical-text output cannot carry that payload. When its source
+text body contains the same non-empty run-effect containers, import keeps the
+normalized geometry and visible vertical text but stamps the logical shape and
+native carrier with the blocking §1.4 effect status; effect-free and empty
+effect containers keep the existing normalized fallback.
This conditional guard is not a public run-effect authoring surface and does
-not cover the separate vertical-text output, relationship-bearing text bodies,
-or table-cell text bodies.
+not cover relationship-bearing text bodies or table-cell text bodies.
The quality checker and exporter preflight enforce the same definition,
reference, primitive, target, and numeric-value contract; malformed values are
never replaced by effect defaults during native export.
diff --git a/skills/ppt-master/scripts/pptx_effects.py b/skills/ppt-master/scripts/pptx_effects.py
index 88464272..25b4e0c1 100644
--- a/skills/ppt-master/scripts/pptx_effects.py
+++ b/skills/ppt-master/scripts/pptx_effects.py
@@ -14,6 +14,16 @@ _EFFECT_OBJECT_IDENTITY_ATTRS = (
"data-pptx-shape-id",
"data-pptx-shape-scope",
)
+_DML_NAMESPACE = "http://schemas.openxmlformats.org/drawingml/2006/main"
+_TEXT_PROPERTY_TAGS = frozenset({
+ f"{{{_DML_NAMESPACE}}}defRPr",
+ f"{{{_DML_NAMESPACE}}}endParaRPr",
+ f"{{{_DML_NAMESPACE}}}rPr",
+})
+_RUN_EFFECT_CONTAINER_TAGS = frozenset({
+ f"{{{_DML_NAMESPACE}}}effectLst",
+ f"{{{_DML_NAMESPACE}}}effectDag",
+})
def project_effect_status_errors(root: ET.Element) -> list[str]:
@@ -68,6 +78,22 @@ def unsupported_effect_metadata(reason: str) -> dict[str, str]:
}
+def txbody_has_run_effects(txbody: ET.Element | None) -> bool:
+ """Return whether rebuilding a text body would discard a run effect."""
+ if txbody is None:
+ return False
+ for properties in txbody.iter():
+ if properties.tag not in _TEXT_PROPERTY_TAGS:
+ continue
+ for child in properties:
+ if child.tag in _RUN_EFFECT_CONTAINER_TAGS and any(
+ isinstance(effect.tag, str)
+ for effect in child
+ ):
+ return True
+ return False
+
+
def _element_label(elem: ET.Element) -> str:
tag = elem.tag.rsplit("}", 1)[-1]
elem_id = elem.get("id") or elem.get("data-name")
diff --git a/skills/ppt-master/scripts/pptx_to_svg/slide_to_svg.py b/skills/ppt-master/scripts/pptx_to_svg/slide_to_svg.py
index bdb7f848..ee05ca23 100644
--- a/skills/ppt-master/scripts/pptx_to_svg/slide_to_svg.py
+++ b/skills/ppt-master/scripts/pptx_to_svg/slide_to_svg.py
@@ -35,7 +35,12 @@ from pptx_shapes import (
svg_native_fallback_markup_fingerprint,
svg_text_fingerprint,
)
-from pptx_effects import EFFECT_REASON_ATTR, EFFECT_STATUS_ATTR
+from pptx_effects import (
+ EFFECT_REASON_ATTR,
+ EFFECT_STATUS_ATTR,
+ txbody_has_run_effects,
+ unsupported_effect_metadata,
+)
from .color_resolver import ColorPalette, find_color_elem, resolve_color
from .chart_to_svg import CHART_URI, CHARTEX_URI, extract_native_chart_payload
@@ -338,12 +343,17 @@ def _convert_shape(node: ShapeNode, ctx: AssemblyContext, *, top_level: bool) ->
blip_image = _clip_blip_image(blip_result.svg, geom, ctx)
ctx.media.update(blip_result.media)
- # Geometry (fill is "none" when blipFill is present, so only stroke draws)
- geom_xml = _build_geometry_xml(node, sp_pr, ctx, geom=geom)
-
# Text body (a:txBody)
tx_body = node.xml.find("p:txBody", NS)
is_vertical = is_vertical_txbody(tx_body, node.xfrm)
+ if is_vertical and geom is not None and txbody_has_run_effects(tx_body):
+ geom.attrs.update(unsupported_effect_metadata(
+ "unsupported-run-effect-route:vertical-text"
+ ))
+
+ # Geometry (fill is "none" when blipFill is present, so only stroke draws)
+ geom_xml = _build_geometry_xml(node, sp_pr, ctx, geom=geom)
+
text_default_fill = _resolve_text_style_default(node, ctx)
if tx_body is not None and is_vertical:
text_result = convert_vertical_txbody(
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml/converter.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml/converter.py
index f3da51cb..4435785e 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml/converter.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml/converter.py
@@ -18,7 +18,7 @@ from pptx_shapes import (
svg_text_fingerprint,
validate_ooxml_xfrm,
)
-from pptx_effects import project_effect_status_errors
+from pptx_effects import project_effect_status_errors, txbody_has_run_effects
from pptx_to_svg.preset_authoring import (
materialize_compact_authored_preset_tree,
validate_authored_preset_tree,
@@ -455,14 +455,6 @@ def _txbody_metadata(elem: ET.Element) -> ET.Element | None:
_TXBODY_UNCHANGED_ATTR = 'data-pptx-runtime-txbody-unchanged'
_PREVIEW_UNCHANGED_ATTR = 'data-pptx-runtime-preview-unchanged'
-_DML_NAMESPACE = 'http://schemas.openxmlformats.org/drawingml/2006/main'
-_TEXT_PROPERTY_TAGS = frozenset({
- f'{{{_DML_NAMESPACE}}}defRPr',
- f'{{{_DML_NAMESPACE}}}endParaRPr',
- f'{{{_DML_NAMESPACE}}}rPr',
-})
-_EFFECT_LIST_TAG = f'{{{_DML_NAMESPACE}}}effectLst'
-_EFFECT_DAG_TAG = f'{{{_DML_NAMESPACE}}}effectDag'
def _mark_unchanged_txbody_groups(root: ET.Element) -> None:
@@ -555,28 +547,14 @@ def _decode_unchanged_txbody(
'txbody metadata must not contain part-local relationship attributes'
)
if not unchanged:
- if _txbody_has_run_effects(txbody):
+ if txbody_has_run_effects(txbody):
raise SvgNativeConversionError(
'Visible text or typography was edited while the source '
'txBody contains run-level effects; export stopped to avoid '
'silently discarding those effects'
)
return None
- return decoded, _txbody_has_run_effects(txbody)
-
-
-def _txbody_has_run_effects(txbody: ET.Element) -> bool:
- """Return whether fallback text rebuilding would discard a run effect."""
- for properties in txbody.iter():
- if properties.tag not in _TEXT_PROPERTY_TAGS:
- continue
- for child in properties:
- if child.tag in {_EFFECT_LIST_TAG, _EFFECT_DAG_TAG} and any(
- isinstance(effect.tag, str)
- for effect in child
- ):
- return True
- return False
+ return decoded, txbody_has_run_effects(txbody)
def _append_shape_text(
diff --git a/skills/ppt-master/scripts/test_svg_quality_checker.py b/skills/ppt-master/scripts/test_svg_quality_checker.py
index 9efeedc9..5e63e4b4 100644
--- a/skills/ppt-master/scripts/test_svg_quality_checker.py
+++ b/skills/ppt-master/scripts/test_svg_quality_checker.py
@@ -57,7 +57,6 @@ from svg_to_pptx.canvas_contract import (
)
from svg_to_pptx.drawingml.converter import (
SvgNativeConversionError,
- _txbody_has_run_effects,
convert_svg_to_slide_shapes,
)
from svg_to_pptx.pptx_package.builder import create_pptx_with_native_svg
@@ -92,7 +91,7 @@ from template_import.manifest import (
build_manifest,
)
from template_import.native_structure import build_native_structure
-from pptx_effects import project_effect_status_errors
+from pptx_effects import project_effect_status_errors, txbody_has_run_effects
class SVGQualityCheckerCompatibilityTests(unittest.TestCase):
@@ -271,6 +270,73 @@ class SVGQualityCheckerCompatibilityTests(unittest.TestCase):
target.writestr(info, replacements.get(info.filename, data))
rewritten.replace(path)
+ @staticmethod
+ def _write_vertical_run_effect_fixture(
+ path: Path,
+ effects: list[str | None],
+ ) -> None:
+ """Write vertical text slides with supplied run-effect containers."""
+ presentation = Presentation()
+ blank = presentation.slide_layouts[6]
+ for index, _effect in enumerate(effects, start=1):
+ slide = presentation.slides.add_slide(blank)
+ shape = slide.shapes.add_shape(
+ MSO_SHAPE.RECTANGLE,
+ Emu(914400),
+ Emu(914400),
+ Emu(1371600),
+ Emu(2743200),
+ )
+ shape.name = f'VERTICAL EFFECT TEXT {index}'
+ shape.text = '甲乙'
+ presentation.save(path)
+
+ pml = 'http://schemas.openxmlformats.org/presentationml/2006/main'
+ dml = 'http://schemas.openxmlformats.org/drawingml/2006/main'
+ with zipfile.ZipFile(path, 'r') as source:
+ members = [(info, source.read(info.filename)) for info in source.infolist()]
+ member_data = {info.filename: data for info, data in members}
+ replacements: dict[str, bytes] = {}
+
+ for index, effect_xml in enumerate(effects, start=1):
+ slide_part = f'ppt/slides/slide{index}.xml'
+ slide_root = ET.fromstring(member_data[slide_part])
+ target = next(
+ shape
+ for shape in slide_root.findall(f'.//{{{pml}}}sp')
+ if (
+ shape.find(f'{{{pml}}}nvSpPr/{{{pml}}}cNvPr')
+ is not None
+ and shape.find(
+ f'{{{pml}}}nvSpPr/{{{pml}}}cNvPr'
+ ).get('name') == f'VERTICAL EFFECT TEXT {index}'
+ )
+ )
+ tx_body = target.find(f'{{{pml}}}txBody')
+ assert tx_body is not None
+ body_pr = tx_body.find(f'{{{dml}}}bodyPr')
+ assert body_pr is not None
+ body_pr.set('vert', 'eaVert')
+ run = tx_body.find(f'.//{{{dml}}}r')
+ assert run is not None
+ run_properties = run.find(f'{{{dml}}}rPr')
+ if run_properties is None:
+ run_properties = ET.Element(f'{{{dml}}}rPr')
+ run.insert(0, run_properties)
+ if effect_xml is not None:
+ run_properties.append(ET.fromstring(effect_xml))
+ replacements[slide_part] = ET.tostring(
+ slide_root,
+ encoding='utf-8',
+ xml_declaration=True,
+ )
+
+ rewritten = path.with_name(f'{path.stem}-rewritten.pptx')
+ with zipfile.ZipFile(rewritten, 'w') as target:
+ for info, data in members:
+ target.writestr(info, replacements.get(info.filename, data))
+ rewritten.replace(path)
+
@classmethod
def _write_picture_group_effect_fixture(cls, path: Path) -> None:
"""Write one real picture and one group with source effects."""
@@ -2564,6 +2630,74 @@ class SVGQualityCheckerCompatibilityTests(unittest.TestCase):
):
convert_svg_to_slide_shapes(artifact_path)
+ def test_vertical_text_run_effect_import_fails_closed(self):
+ dml = 'http://schemas.openxmlformats.org/drawingml/2006/main'
+ effects = [
+ f'''<a:effectLst xmlns:a="{dml}">
+ <a:outerShdw blurRad="38100" dist="38100" dir="5400000">
+ <a:srgbClr val="000000"/>
+ </a:outerShdw>
+</a:effectLst>''',
+ f'<a:effectLst xmlns:a="{dml}"/>',
+ f'<a:effectDag xmlns:a="{dml}"/>',
+ None,
+ ]
+ with tempfile.TemporaryDirectory() as tmp_dir:
+ root_dir = Path(tmp_dir)
+ pptx_path = root_dir / 'vertical-run-effects.pptx'
+ self._write_vertical_run_effect_fixture(pptx_path, effects)
+ imported = convert_pptx_to_svg(
+ pptx_path,
+ options=ConvertOptions(inheritance_mode='flat'),
+ )
+ self.assertEqual(len(imported.slides), 4)
+
+ effect_svg = imported.slides[0].svg
+ effect_root = ET.fromstring(effect_svg)
+ self.assertIn('甲', ''.join(effect_root.itertext()))
+ self.assertIn('乙', ''.join(effect_root.itertext()))
+ self.assertFalse(any(
+ elem.get('data-pptx-part') == 'txbody'
+ for elem in effect_root.iter()
+ ))
+ marked = [
+ elem
+ for elem in effect_root.iter()
+ if elem.get('data-pptx-effect-status') == 'unsupported'
+ ]
+ self.assertEqual(len(marked), 2)
+ self.assertEqual(
+ {elem.get('data-pptx-effect-reason') for elem in marked},
+ {'unsupported-run-effect-route:vertical-text'},
+ )
+ status_errors = project_effect_status_errors(effect_root)
+ self.assertEqual(len(status_errors), 1)
+ self.assertIn(
+ 'unsupported-run-effect-route:vertical-text',
+ status_errors[0],
+ )
+ self._assert_checker_and_exporter_reject(
+ effect_svg,
+ 'unsupported-run-effect-route:vertical-text',
+ 'unsupported imported PPTX effect',
+ )
+
+ for artifact in imported.slides[1:]:
+ with self.subTest(slide=artifact.index):
+ root = ET.fromstring(artifact.svg)
+ self.assertEqual(project_effect_status_errors(root), [])
+ self.assertFalse(any(
+ elem.get('data-pptx-effect-status') is not None
+ for elem in root.iter()
+ ))
+ svg_path = root_dir / f'vertical-{artifact.index}.svg'
+ svg_path.write_text(artifact.svg, encoding='utf-8')
+ checker_result = SVGQualityChecker().check_file(
+ str(svg_path)
+ )
+ self.assertTrue(checker_result['passed'])
+ convert_svg_to_slide_shapes(svg_path)
+
def test_picture_and_group_effect_import_is_explicit(self):
dml = 'http://schemas.openxmlformats.org/drawingml/2006/main'
empty_sp_pr = ET.fromstring(
@@ -4365,9 +4499,9 @@ class SVGQualityCheckerCompatibilityTests(unittest.TestCase):
'<a:t>AB</a:t></a:r></a:p>'
)
- self.assertTrue(_txbody_has_run_effects(inherited_list))
- self.assertTrue(_txbody_has_run_effects(paragraph_end_dag))
- self.assertFalse(_txbody_has_run_effects(empty_containers))
+ self.assertTrue(txbody_has_run_effects(inherited_list))
+ self.assertTrue(txbody_has_run_effects(paragraph_end_dag))
+ self.assertFalse(txbody_has_run_effects(empty_containers))
def test_checker_does_not_trust_authored_runtime_txbody_snapshot(self):
root = ET.fromstring(