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(svg-quality): move internals behind stable script shim

hugohe35b305b9de9c2
diff --git a/docs/rules/code-style.md b/docs/rules/code-style.md
index b9b3fc50..189b2b28 100644
--- a/docs/rules/code-style.md
+++ b/docs/rules/code-style.md
@@ -339,4 +339,4 @@ Existing files take precedence. If a current script contradicts a rule here, dec
| A small CLI utility | [`total_md_split.py`](../../skills/ppt-master/scripts/total_md_split.py), [`gemini_watermark_remover.py`](../../skills/ppt-master/scripts/gemini_watermark_remover.py) |
| A multi-backend / dispatcher CLI | [`image_search.py`](../../skills/ppt-master/scripts/image_search.py), [`image_gen.py`](../../skills/ppt-master/scripts/image_gen.py) |
| A library / shared helper | [`image_sources/provider_common.py`](../../skills/ppt-master/scripts/image_sources/provider_common.py), [`image_backends/backend_common.py`](../../skills/ppt-master/scripts/image_backends/backend_common.py) |
-| A class-based checker / validator | [`svg_quality_checker.py`](../../skills/ppt-master/scripts/svg_quality_checker.py) |
+| A class-based checker / validator | [`svg_quality/checker.py`](../../skills/ppt-master/scripts/svg_quality/checker.py) |
diff --git a/skills/ppt-master/scripts/svg_quality/__init__.py b/skills/ppt-master/scripts/svg_quality/__init__.py
new file mode 100644
index 00000000..8c3c7741
--- /dev/null
+++ b/skills/ppt-master/scripts/svg_quality/__init__.py
@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+"""PPT Master SVG quality-check internals.
+
+Use the stable ``scripts/svg_quality_checker.py`` entry point for CLI execution
+and compatibility imports.
+
+Usage:
+ Import through ``svg_quality_checker``.
+
+Examples:
+ from svg_quality_checker import SVGQualityChecker
+
+Dependencies:
+ Local PPT Master validation modules.
+"""
diff --git a/skills/ppt-master/scripts/svg_quality/checker.py b/skills/ppt-master/scripts/svg_quality/checker.py
new file mode 100644
index 00000000..43b3a004
--- /dev/null
+++ b/skills/ppt-master/scripts/svg_quality/checker.py
@@ -0,0 +1,8137 @@
+#!/usr/bin/env python3
+"""PPT Master SVG quality-check implementation.
+
+Owns SVG, project-contract, template, and report validation. The stable CLI and
+compatibility import surface remain in ``scripts/svg_quality_checker.py``.
+
+Usage:
+ Import through ``svg_quality_checker`` or invoke the stable script.
+
+Examples:
+ from svg_quality_checker import SVGQualityChecker
+
+Dependencies:
+ Standard library plus local PPT Master validation modules.
+"""
+
+import copy
+import hashlib
+import html
+import json
+import math
+import re
+from pathlib import Path
+from collections import Counter, defaultdict
+from typing import Dict, List, Tuple
+from urllib.parse import unquote, urlsplit
+from xml.etree import ElementTree as ET
+
+from native_payloads import NativePayloadError, hydrate_native_payload_refs
+from slide_roster import discover_slide_svgs
+
+try:
+ from project_utils import CANVAS_FORMATS, validate_communication_trace
+except ImportError:
+ print("Warning: Unable to import project_utils")
+ CANVAS_FORMATS = {}
+ validate_communication_trace = None
+
+try:
+ from pptx_effects import (
+ EFFECT_REASON_ATTR as _EFFECT_REASON_ATTR,
+ EFFECT_STATUS_ATTR as _EFFECT_STATUS_ATTR,
+ project_effect_status_errors as _project_effect_status_errors,
+ )
+except ImportError:
+ _EFFECT_REASON_ATTR = 'data-pptx-effect-reason'
+ _EFFECT_STATUS_ATTR = 'data-pptx-effect-status'
+ _project_effect_status_errors = None
+
+from svg_to_pptx.canvas_contract import (
+ CanvasContractError,
+ parse_project_svg_root,
+ parse_project_viewbox,
+)
+
+try:
+ from project_management.project_specs import (
+ parse_spec_lock as _parse_spec_lock,
+ parse_spec_lock_image_value as _parse_spec_lock_image_value,
+ )
+except ImportError:
+ _parse_spec_lock = None # spec_lock anchor comparison will be skipped
+ _parse_spec_lock_image_value = None
+
+try:
+ from svg_to_pptx.animation_config import (
+ load_animation_config as _load_animation_config,
+ usable_animation_group_id as _usable_animation_group_id,
+ validate_animation_config as _validate_animation_config,
+ validate_animation_config_errors as _validate_animation_config_errors,
+ validate_transition_config as _validate_transition_config,
+ )
+except ImportError as exc:
+ _load_animation_config = None
+ _validate_animation_config = None
+ _validate_animation_config_errors = None
+ _validate_transition_config = None
+ _animation_config_import_error = str(exc)
+
+ def _usable_animation_group_id(raw: str | None) -> str | None:
+ return raw if raw and raw.strip() else None
+else:
+ _animation_config_import_error = None
+
+try:
+ from svg_to_pptx.drawingml.utils import (
+ DRAWINGML_TEXT_FONT_SIZE_MAX as _DRAWINGML_TEXT_FONT_SIZE_MAX,
+ DRAWINGML_TEXT_FONT_SIZE_MIN as _DRAWINGML_TEXT_FONT_SIZE_MIN,
+ IDENTITY_MATRIX as _IDENTITY_MATRIX,
+ PROJECT_OPACITY_PROPERTIES as _OPACITY_PROPERTIES,
+ PROJECT_PAINT_PROPERTIES as _PAINT_PROPERTIES,
+ PROJECT_PERCENTAGE_OPACITY_PROPERTIES as _PERCENTAGE_OPACITY_PROPERTIES,
+ detect_text_lang as _detect_text_lang,
+ format_project_geometry_length as _format_project_geometry_length,
+ format_project_image_aspect_ratio as _format_project_image_aspect_ratio,
+ format_project_opacity as _format_project_opacity,
+ font_px_to_hpt as _font_px_to_hpt,
+ is_canonical_project_geometry_length as _is_canonical_project_geometry_length,
+ is_project_opacity_default_form as _is_project_opacity_default_form,
+ is_project_paint_default_form as _is_project_paint_default_form,
+ iter_project_geometry_lengths as _iter_project_geometry_lengths,
+ iter_project_image_aspect_ratios as _iter_project_image_aspect_ratios,
+ iter_project_opacities as _iter_project_opacities,
+ iter_project_paints as _iter_project_paints,
+ iter_project_stroke_styles as _iter_project_stroke_styles,
+ iter_project_transforms as _iter_project_transforms,
+ matrix_multiply as _matrix_multiply,
+ noncanonical_stroke_dash_numbers as _noncanonical_stroke_dash_numbers,
+ noncanonical_transform_numbers as _noncanonical_transform_numbers,
+ parse_inline_style as _parse_inline_style,
+ parse_project_geometry_length as _parse_project_geometry_length,
+ parse_project_image_aspect_ratio as _parse_project_image_aspect_ratio,
+ parse_project_opacity as _parse_project_opacity,
+ parse_project_paint as _parse_project_paint,
+ parse_project_stroke_dasharray as _parse_project_stroke_dasharray,
+ parse_project_stroke_enum as _parse_project_stroke_enum,
+ parse_svg_color as _parse_export_color,
+ parse_svg_length as _parse_export_length,
+ parse_transform_matrix as _parse_transform_matrix,
+ project_definition_errors as _project_definition_errors,
+ project_filter_errors as _project_filter_errors,
+ project_gradient_errors as _project_gradient_errors,
+ project_image_aspect_ratio_errors as _project_image_aspect_ratio_errors,
+ project_mask_errors as _project_mask_errors,
+ project_marker_errors as _project_marker_errors,
+ project_opacity_errors as _project_opacity_errors,
+ project_paint_errors as _project_paint_errors,
+ project_paint_reference_errors as _project_paint_reference_errors,
+ project_stroke_style_errors as _project_stroke_style_errors,
+ project_transform_errors as _project_transform_errors,
+ rect_to_dml_xfrm as _rect_to_dml_xfrm,
+ transform_point as _transform_point,
+ unsafe_exported_font_faces as _unsafe_exported_font_faces,
+ validate_dml_shape_matrix as _validate_dml_shape_matrix,
+ )
+except ImportError:
+ _DRAWINGML_TEXT_FONT_SIZE_MAX = None
+ _DRAWINGML_TEXT_FONT_SIZE_MIN = None
+ _IDENTITY_MATRIX = None
+ _OPACITY_PROPERTIES = None
+ _PAINT_PROPERTIES = None
+ _PERCENTAGE_OPACITY_PROPERTIES = None
+ _detect_text_lang = None
+ _format_project_geometry_length = None
+ _format_project_image_aspect_ratio = None
+ _format_project_opacity = None
+ _font_px_to_hpt = None
+ _is_canonical_project_geometry_length = None
+ _is_project_opacity_default_form = None
+ _is_project_paint_default_form = None
+ _iter_project_geometry_lengths = None
+ _iter_project_image_aspect_ratios = None
+ _iter_project_opacities = None
+ _iter_project_paints = None
+ _iter_project_stroke_styles = None
+ _iter_project_transforms = None
+ _matrix_multiply = None
+ _noncanonical_stroke_dash_numbers = None
+ _noncanonical_transform_numbers = None
+ _parse_inline_style = None
+ _parse_project_geometry_length = None
+ _parse_project_image_aspect_ratio = None
+ _parse_project_opacity = None
+ _parse_project_paint = None
+ _parse_project_stroke_dasharray = None
+ _parse_project_stroke_enum = None
+ _parse_export_color = None
+ _parse_export_length = None
+ _parse_transform_matrix = None
+ _project_definition_errors = None
+ _project_filter_errors = None
+ _project_gradient_errors = None
+ _project_image_aspect_ratio_errors = None
+ _project_mask_errors = None
+ _project_marker_errors = None
+ _project_opacity_errors = None
+ _project_paint_errors = None
+ _project_paint_reference_errors = None
+ _project_stroke_style_errors = None
+ _project_transform_errors = None
+ _rect_to_dml_xfrm = None
+ _transform_point = None
+ _unsafe_exported_font_faces = None
+ _validate_dml_shape_matrix = None
+
+try:
+ from svg_to_pptx.drawingml.paths import (
+ iter_project_freeform_geometry as _iter_project_freeform_geometry,
+ noncanonical_path_numbers as _noncanonical_path_numbers,
+ noncanonical_points_numbers as _noncanonical_points_numbers,
+ project_gradient_geometry_errors as _project_gradient_geometry_errors,
+ )
+except ImportError:
+ _iter_project_freeform_geometry = None
+ _noncanonical_path_numbers = None
+ _noncanonical_points_numbers = None
+ _project_gradient_geometry_errors = None
+
+try:
+ from svg_to_pptx.drawingml.converter import (
+ SvgNativeConversionError as _SvgNativeConversionError,
+ collect_unsupported_visuals as _collect_unsupported_visuals,
+ preserved_native_text_body as _preserved_native_text_body,
+ )
+except ImportError:
+ _SvgNativeConversionError = None
+ _collect_unsupported_visuals = None
+ _preserved_native_text_body = None
+
+try:
+ from svg_to_pptx.drawingml.elements import (
+ drawingml_text_frame_width_emu as _drawingml_text_frame_width_emu,
+ estimate_single_line_text_frame_width as _estimate_single_line_text_frame_width,
+ project_clip_path_errors as _project_clip_path_errors,
+ project_image_errors as _project_image_errors,
+ project_nested_svg_crop_errors as _project_nested_svg_crop_errors,
+ validate_single_line_text_run_advances as _validate_single_line_text_run_advances,
+ validate_preset_geometry_metadata as _validate_preset_geometry_metadata,
+ )
+except ImportError:
+ _drawingml_text_frame_width_emu = None
+ _estimate_single_line_text_frame_width = None
+ _project_clip_path_errors = None
+ _project_image_errors = None
+ _project_nested_svg_crop_errors = None
+ _validate_single_line_text_run_advances = None
+ _validate_preset_geometry_metadata = None
+
+try:
+ from svg_to_pptx.drawingml.text_properties import (
+ normalize_project_text_segments as _normalize_project_text_segments,
+ parse_project_font_weight as _parse_project_font_weight,
+ parse_project_text_anchor as _parse_project_text_anchor,
+ project_text_property_diagnostics as _project_text_property_diagnostics,
+ resolve_project_xml_space as _resolve_project_xml_space,
+ resolve_project_font_sizes as _resolve_project_font_sizes,
+ resolve_project_letter_spacings as _resolve_project_letter_spacings,
+ )
+except ImportError:
+ _normalize_project_text_segments = None
+ _parse_project_font_weight = None
+ _parse_project_text_anchor = None
+ _project_text_property_diagnostics = None
+ _resolve_project_xml_space = None
+ _resolve_project_font_sizes = None
+ _resolve_project_letter_spacings = None
+
+try:
+ from pptx_to_svg.preset_authoring import (
+ AUTHORING_ATTR as _AUTHORING_ATTR,
+ authored_preset_encoding as _authored_preset_encoding,
+ validate_authored_preset_group as _validate_authored_preset_group,
+ validate_authored_preset_tree as _validate_authored_preset_tree,
+ )
+except ImportError:
+ _AUTHORING_ATTR = 'data-pptx-authoring'
+ _authored_preset_encoding = None
+ _validate_authored_preset_group = None
+ _validate_authored_preset_tree = None
+
+try:
+ from pptx_shapes import (
+ CONNECTOR_PRESET_TYPES as _CONNECTOR_PRESET_TYPES,
+ resolve_preset_preview_hash as _resolve_preset_preview_hash,
+ svg_preset_preview_fingerprint as _svg_preset_preview_fingerprint,
+ )
+except ImportError:
+ _CONNECTOR_PRESET_TYPES = frozenset()
+ _resolve_preset_preview_hash = None
+ _svg_preset_preview_fingerprint = None
+
+try:
+ from svg_to_pptx.native_objects import (
+ validate_native_object_marker as _validate_native_object_marker,
+ )
+except ImportError:
+ _validate_native_object_marker = None
+
+try:
+ from svg_to_pptx.native_objects import (
+ validate_native_object_marker_with_warnings as _validate_native_object_marker_with_warnings,
+ )
+except ImportError:
+ _validate_native_object_marker_with_warnings = None
+
+try:
+ from svg_to_pptx.native_objects import (
+ native_object_marker_warnings as _native_object_marker_warnings,
+ )
+except ImportError:
+ _native_object_marker_warnings = None
+
+try:
+ from svg_to_pptx.native_objects import (
+ native_fallback_kind as _native_fallback_kind,
+ native_marker_legacy_warnings as _native_marker_legacy_warnings,
+ native_replacement_kind as _native_replacement_kind,
+ native_replacement_status as _native_replacement_status,
+ )
+except ImportError:
+ _native_fallback_kind = None
+ _native_marker_legacy_warnings = None
+ _native_replacement_kind = None
+ _native_replacement_status = None
+
+try:
+ from svg_to_pptx.native_objects.marker_status import (
+ native_marker_release_block_reason as _native_marker_release_block_reason,
+ native_marker_status_errors as _native_marker_status_errors,
+ )
+except ImportError:
+ _native_marker_release_block_reason = None
+ _native_marker_status_errors = None
+
+try:
+ from svg_to_pptx.semantic_markers import (
+ SEMANTIC_ATTRS as _SEMANTIC_ATTRS,
+ is_static_page_frame as _is_static_page_frame,
+ validate_semantic_markers as _validate_semantic_markers,
+ )
+except ImportError:
+ _SEMANTIC_ATTRS = frozenset({
+ 'data-pptx-page-role',
+ 'data-pptx-role',
+ })
+ _is_static_page_frame = None
+ _validate_semantic_markers = None
+
+try:
+ from svg_to_pptx.geometry_properties import (
+ materialize_inline_geometry_properties as _materialize_inline_geometry_properties,
+ validate_inline_geometry_properties as _validate_inline_geometry_properties,
+ )
+except ImportError:
+ _materialize_inline_geometry_properties = None
+ _validate_inline_geometry_properties = None
+
+try:
+ from svg_to_pptx.use_expander import (
+ UseExpansionError as _UseExpansionError,
+ expand_local_use_references as _expand_local_use_references,
+ validate_local_use_references as _validate_local_use_references,
+ )
+except ImportError:
+ _UseExpansionError = None
+ _expand_local_use_references = None
+ _validate_local_use_references = None
+
+try:
+ from svg_to_pptx.tspan_flattener import (
+ flatten_positional_tspans as _flatten_positional_tspans,
+ nested_positional_tspan_errors as _nested_positional_tspan_errors,
+ )
+except ImportError:
+ _flatten_positional_tspans = None
+ _nested_positional_tspan_errors = None
+
+try:
+ from svg_to_pptx.pptx_package.template_structure import (
+ TemplateStructureError as _TemplateStructureError,
+ _is_authored_preset_atom as _is_authored_preset_atom,
+ load_pptx_structure_lock as _load_pptx_structure_lock,
+ parse_template_slide as _parse_template_structure_slide,
+ parse_template_slides as _parse_template_structure_slides,
+ _structure_subtree_signature as _structure_subtree_signature,
+ template_lock_errors as _template_lock_errors,
+ template_prototype_errors as _template_prototype_errors,
+ validate_template_svg as _validate_template_structure_svg,
+ )
+except ImportError:
+ _TemplateStructureError = None
+ _is_authored_preset_atom = None
+ _load_pptx_structure_lock = None
+ _parse_template_structure_slide = None
+ _parse_template_structure_slides = None
+ _structure_subtree_signature = None
+ _template_lock_errors = None
+ _template_prototype_errors = None
+ _validate_template_structure_svg = None
+
+try:
+ from svg_to_pptx.drawingml.theme_colors import (
+ ThemeColorError as _ThemeColorError,
+ load_theme_color_spec as _load_theme_color_spec,
+ )
+ from svg_to_pptx.drawingml.theme_fonts import (
+ ThemeFontError as _ThemeFontError,
+ load_master_text_style_spec as _load_master_text_style_spec,
+ load_theme_font_spec as _load_theme_font_spec,
+ )
+except ImportError:
+ _ThemeColorError = None
+ _ThemeFontError = None
+ _load_theme_color_spec = None
+ _load_master_text_style_spec = None
+ _load_theme_font_spec = None
+
+try:
+ from svg_finalize.embed_icons import (
+ resolve_icon_path as _resolve_icon_path,
+ suggest_icon_name as _suggest_icon_name,
+ )
+except ImportError:
+ _resolve_icon_path = None
+ _suggest_icon_name = None
+
+try:
+ from resource_paths import (
+ SVG_WORK_DIR_NAMES as _SVG_WORK_DIR_NAMES,
+ icon_search_dirs_for_svg as _icon_search_dirs_for_svg,
+ project_root_for_svg_path as _project_root_for_svg_path,
+ resolve_external_image_reference as _resolve_external_image_reference,
+ )
+except ImportError:
+ _SVG_WORK_DIR_NAMES = frozenset()
+ _icon_search_dirs_for_svg = None
+ _project_root_for_svg_path = None
+ _resolve_external_image_reference = None
+
+
+HEX_VALUE_RE = re.compile(
+ r"#(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})"
+)
+
+# Master/Layout preflight validation. Structured deck/layout-template projects
+# are checked at authoring time; the exporter remains the final OOXML/package
+# authority. Flat projects only receive the negative guard that rejects authored
+# structure metadata. Template roster/placeholder checks always run. Current
+# bundled templates opt in to complete structure validation through their
+# native_structure_mode: structured declaration. Legacy template-mode packages
+# fail closed; Create Template must author a new current-contract workspace.
+_CHECK_PPTX_STRUCTURED_PROJECT = True
+
+_BARE_HEX_VALUE_RE = re.compile(
+ r"(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})"
+)
+_CANONICAL_PAINT_ALPHA_PROPERTY = {
+ 'fill': 'fill-opacity',
+ 'stroke': 'stroke-opacity',
+ 'stop-color': 'stop-opacity',
+ 'flood-color': 'flood-opacity',
+}
+SVG_NS = "http://www.w3.org/2000/svg"
+XLINK_NS = "http://www.w3.org/1999/xlink"
+_NON_VISUAL_SVG_TAGS = frozenset({
+ 'defs',
+ 'desc',
+ 'metadata',
+ 'style',
+ 'title',
+})
+_BOUNDS_ATTR = 'data-pptx-bounds'
+_BOUNDS_OVERFLOW_TOLERANCE = 1.0
+_BOUNDS_OVERFLOW_ERROR_RATIO = 0.05
+_PARAGRAPH_LINE_GAP_MIN_RATIO = 0.9
+_PARAGRAPH_LINE_GAP_MAX_RATIO = 2.05
+_PARAGRAPH_LINE_X_TOLERANCE = 0.5
+_PARAGRAPH_LINE_MIN_TOTAL_CHARS = 12
+_PARAGRAPH_LINE_MIN_LONGEST_CHARS = 8
+_PARAGRAPH_LINE_TERMINATOR_RE = re.compile(r'[.!?。!?;;]["\'”’))]*$')
+_PARAGRAPH_LIST_MARKER_RE = re.compile(
+ r'^\s*(?:[•·・▪◦‣]\s*|[-–—*]\s+|\d+[.)、]\s+|[((]\d+[))]\s*)\S+'
+)
+_LEGACY_PPTX_ATTRIBUTE_RENAMES = {
+ 'data-pptx-module-bounds': _BOUNDS_ATTR,
+ 'data-pptx-placeholder-bounds': _BOUNDS_ATTR,
+ 'data-pptx-placeholder-carrier': 'data-pptx-carrier',
+ 'data-pptx-placeholder-binding': 'data-pptx-binding',
+ 'data-pptx-placeholder-idx': 'data-pptx-idx',
+}
+_PPTX_ROOT_STRUCTURE_ATTRS = (
+ 'data-pptx-master',
+ 'data-pptx-master-name',
+ 'data-pptx-layout',
+ 'data-pptx-layout-name',
+)
+_PPTX_ROOT_VISIBILITY_ATTRS = (
+ 'data-pptx-show-master-shapes',
+ 'data-pptx-show-inherited-shapes',
+)
+_PPTX_STRUCTURE_ATTRS = frozenset({
+ *_PPTX_ROOT_STRUCTURE_ATTRS,
+ *_PPTX_ROOT_VISIBILITY_ATTRS,
+ 'data-pptx-layer',
+ 'data-pptx-layout-kind',
+ 'data-pptx-placeholder',
+ 'data-pptx-binding',
+ 'data-pptx-carrier',
+ 'data-pptx-idx',
+})
+_PPTX_PLACEHOLDER_DETAIL_ATTRS = frozenset({
+ 'data-pptx-binding',
+ 'data-pptx-idx',
+})
+_PPTX_STRUCTURE_SECTION_RE = re.compile(
+ r"(?ms)^##[ \t]+pptx_structure[ \t]*\r?\n(.*?)(?=^##[ \t]+|\Z)"
+)
+_PPTX_STRUCTURE_MODE_RE = re.compile(
+ r"(?m)^-[ \t]+mode[ \t]*:[ \t]*([^\s#]+)[ \t]*(?:#.*)?$"
+)
+_SUPPORTED_INLINE_STYLE_PROPERTIES = frozenset({
+ 'cx', 'cy', 'fill', 'fill-opacity', 'filter', 'flood-color',
+ 'flood-opacity', 'font-family', 'font-size', 'font-style', 'font-weight',
+ 'height', 'letter-spacing', 'opacity', 'r', 'rx', 'ry',
+ 'shape-rendering', 'stop-color', 'stop-opacity', 'stroke',
+ 'stroke-dasharray', 'stroke-linecap', 'stroke-linejoin', 'stroke-opacity',
+ 'stroke-width', 'text-anchor', 'text-decoration', 'vector-effect',
+ 'width', 'x', 'y',
+})
+_BAKE_REQUIRED_VISUAL_PROPERTIES = frozenset({
+ 'backdrop-filter',
+ 'isolation',
+ 'mix-blend-mode',
+})
+_SHARED_FAIL_CLOSED_STYLE_PROPERTIES = frozenset({'mask'})
+
+
+def _compact_preset_ancestor_paint(
+ root: ET.Element,
+) -> list[tuple[str, tuple[str, ...]]]:
+ """Return compact presets affected by compatible ancestor paint."""
+ if (
+ _authored_preset_encoding is None
+ or _validate_authored_preset_group is None
+ ):
+ return []
+ parents = {
+ child: parent
+ for parent in root.iter()
+ for child in parent
+ }
+ affected: list[tuple[str, tuple[str, ...]]] = []
+ for group in root.iter():
+ if (
+ _authored_preset_encoding(group) != 'compact'
+ or _validate_authored_preset_group(group)
+ ):
+ continue
+ relevant = {'opacity'}
+ if group.get('fill') != 'none' and group.get('fill-opacity') is None:
+ relevant.add('fill-opacity')
+ if group.get('stroke') != 'none':
+ for name in (
+ 'stroke-opacity',
+ 'stroke-dasharray',
+ 'stroke-linecap',
+ 'stroke-linejoin',
+ ):
+ if group.get(name) is None:
+ relevant.add(name)
+
+ inherited: set[str] = set()
+ ancestor = parents.get(group)
+ while ancestor is not None:
+ declarations = {
+ name: ancestor.get(name) or ''
+ for name in relevant
+ if ancestor.get(name) is not None
+ }
+ for declaration in (ancestor.get('style') or '').split(';'):
+ name, separator, value = declaration.partition(':')
+ name = name.strip().lower()
+ if separator and name in relevant:
+ declarations[name] = value.strip()
+ for name, value in declarations.items():
+ normalized = value.strip().lower()
+ if name in {'opacity', 'fill-opacity', 'stroke-opacity'}:
+ try:
+ if float(normalized) == 1:
+ continue
+ except ValueError:
+ pass
+ elif name == 'stroke-dasharray' and normalized == 'none':
+ continue
+ elif name == 'stroke-linecap' and normalized == 'butt':
+ continue
+ elif name == 'stroke-linejoin' and normalized == 'miter':
+ continue
+ inherited.add(name)
+ ancestor = parents.get(ancestor)
+ if inherited:
+ affected.append((
+ group.get('id') or '(no id)',
+ tuple(sorted(inherited)),
+ ))
+ return affected
+
+
+def _declared_pptx_structure_mode(project_path: Path) -> str | None:
+ """Return the explicitly locked SVG structure mode without a fallback."""
+ lock_path = project_path / 'spec_lock.md'
+ try:
+ content = lock_path.read_text(encoding='utf-8')
+ except OSError:
+ return None
+ section_match = _PPTX_STRUCTURE_SECTION_RE.search(content)
+ if section_match is None:
+ return None
+ mode_match = _PPTX_STRUCTURE_MODE_RE.search(section_match.group(1))
+ return mode_match.group(1).strip().lower() if mode_match else None
+
+
+def _generated_theme_contract_errors(project_path: Path) -> List[str]:
+ """Validate the current-project theme contract required by release export."""
+ if (
+ _ThemeColorError is None
+ or _ThemeFontError is None
+ or _load_theme_color_spec is None
+ or _load_master_text_style_spec is None
+ or _load_theme_font_spec is None
+ ):
+ return [
+ "PowerPoint theme contract validation is unavailable because the "
+ "theme loader modules could not be imported."
+ ]
+ try:
+ theme_font_spec = _load_theme_font_spec(project_path)
+ _load_master_text_style_spec(project_path)
+ theme_color_spec = _load_theme_color_spec(project_path)
+ except (_ThemeFontError, _ThemeColorError) as exc:
+ return [str(exc)]
+
+ missing: List[str] = []
+ if theme_font_spec is None:
+ missing.append("typography font_family/title_family/body_family")
+ if theme_color_spec is None:
+ missing.append("colors")
+ if not missing:
+ return []
+ return [
+ "spec_lock.md generated PowerPoint theme contract is missing: "
+ + ", ".join(missing)
+ ]
+
+
+def _parse_positive_bounds(
+ value: str,
+) -> Tuple[float, float, float, float]:
+ """Parse one positive x/y/width/height boundary."""
+ raw_values = [item for item in re.split(r"[\s,]+", value.strip()) if item]
+ if len(raw_values) != 4:
+ raise ValueError("must contain exactly four numbers: x y width height")
+ try:
+ values = tuple(float(item) for item in raw_values)
+ except ValueError as exc:
+ raise ValueError("must contain only numeric values") from exc
+ if not all(math.isfinite(item) for item in values):
+ raise ValueError("must contain only finite values")
+ if values[2] <= 0 or values[3] <= 0:
+ raise ValueError("must use positive width and height")
+ return values
+
+
+def _placeholder_bounds_error(value: str) -> str | None:
+ """Return a concise error for invalid design-zone bounds."""
+ try:
+ _parse_positive_bounds(value)
+ except ValueError as exc:
+ return str(exc)
+ return None
+
+
+def _local_pptx_structure_errors(
+ root: ET.Element,
+ svg_path: Path,
+ *,
+ require_structure: bool,
+) -> List[str]:
+ """Validate the authoring shape of the structured SVG contract."""
+ errors: List[str] = []
+ root_values = {
+ attr: (root.get(attr) or '').strip()
+ for attr in _PPTX_ROOT_STRUCTURE_ATTRS
+ }
+ has_root_structure = any(root_values.values())
+ if require_structure or has_root_structure:
+ missing = [attr for attr, value in root_values.items() if not value]
+ if missing:
+ errors.append(
+ f"{svg_path.name}: structured SVG root is missing "
+ + ', '.join(missing)
+ )
+ for attr in _PPTX_ROOT_VISIBILITY_ATTRS:
+ raw = root.get(attr)
+ if raw is not None and raw not in {'true', 'false'}:
+ errors.append(
+ f"{svg_path.name}: root {attr} must be exactly 'true' or 'false'"
+ )
+
+ parent_by_id = {
+ id(child): parent
+ for parent in root.iter()
+ for child in list(parent)
+ }
+ for elem in root.iter():
+ tag = elem.tag.rsplit('}', 1)[-1]
+ element_id = elem.get('id') or f"<{tag}>"
+ parent = parent_by_id.get(id(elem))
+
+ if elem is not root:
+ nested_root_attrs = [
+ attr for attr in (
+ *_PPTX_ROOT_STRUCTURE_ATTRS,
+ *_PPTX_ROOT_VISIBILITY_ATTRS,
+ )
+ if elem.get(attr) is not None
+ ]
+ if nested_root_attrs:
+ errors.append(
+ f"{svg_path.name}: {element_id} carries root-only metadata "
+ + ', '.join(nested_root_attrs)
+ )
+
+ if elem.get('data-pptx-layout-kind') is not None:
+ errors.append(
+ f"{svg_path.name}: data-pptx-layout-kind is a legacy distillation "
+ "attribute; restore the page to the structured contract"
+ )
+
+ layer = (elem.get('data-pptx-layer') or '').strip().lower()
+ placeholder = (elem.get('data-pptx-placeholder') or '').strip().lower()
+ if layer in {'master', 'layout'}:
+ if parent is not root:
+ errors.append(
+ f"{svg_path.name}: {element_id} data-pptx-layer={layer!r} "
+ "must be a direct child of the root <svg>"
+ )
+ if tag == 'g' and not (
+ _is_authored_preset_atom is not None
+ and _is_authored_preset_atom(elem)
+ ):
+ errors.append(
+ f"{svg_path.name}: {element_id} is a <g> marked as {layer}; "
+ "Master/Layout fixed visuals must be root-level atomic elements"
+ )
+ if placeholder:
+ errors.append(
+ f"{svg_path.name}: {element_id} cannot be both a fixed "
+ f"{layer} element and a placeholder slot"
+ )
+
+ detail_attrs = [
+ attr for attr in _PPTX_PLACEHOLDER_DETAIL_ATTRS
+ if elem.get(attr) is not None
+ ]
+ if detail_attrs and not placeholder:
+ errors.append(
+ f"{svg_path.name}: {element_id} uses placeholder detail metadata "
+ "without data-pptx-placeholder"
+ )
+
+ if placeholder:
+ if parent is not root:
+ errors.append(
+ f"{svg_path.name}: placeholder slot {element_id} must be a "
+ "direct child of the root <svg>"
+ )
+ if tag != 'g':
+ errors.append(
+ f"{svg_path.name}: placeholder slot {element_id} must be a "
+ "root-level <g>"
+ )
+ if not (elem.get('id') or '').strip():
+ errors.append(
+ f"{svg_path.name}: every placeholder slot <g> requires a stable id"
+ )
+ wrapper_attrs = sorted(
+ attr.rsplit('}', 1)[-1]
+ for attr in elem.attrib
+ if attr != 'id'
+ and not attr.rsplit('}', 1)[-1].startswith('data-pptx-')
+ )
+ if wrapper_attrs:
+ errors.append(
+ f"{svg_path.name}: placeholder slot {element_id} is an "
+ "authoring boundary and may carry only id/data-pptx-*; remove "
+ + ', '.join(wrapper_attrs)
+ )
+ bounds = (elem.get('data-pptx-bounds') or '').strip()
+ if not bounds:
+ errors.append(
+ f"{svg_path.name}: placeholder slot {element_id} requires "
+ "data-pptx-bounds"
+ )
+ else:
+ bounds_error = _placeholder_bounds_error(bounds)
+ if bounds_error:
+ errors.append(
+ f"{svg_path.name}: placeholder slot {element_id} bounds "
+ + bounds_error
+ )
+
+ binding = (
+ elem.get('data-pptx-binding') or 'carrier'
+ ).strip().lower()
+ if binding not in {'carrier', 'proxy'}:
+ errors.append(
+ f"{svg_path.name}: placeholder slot {element_id} has unknown "
+ f"binding {binding!r}; use carrier or proxy"
+ )
+ carrier_descendants = [
+ child for child in elem.iter()
+ if child is not elem
+ and child.get('data-pptx-carrier') is not None
+ ]
+ visual_children = [
+ child for child in list(elem)
+ if child.tag.rsplit('}', 1)[-1] not in _NON_VISUAL_SVG_TAGS
+ ]
+ direct_carriers = [
+ child for child in visual_children
+ if (child.get('data-pptx-carrier') or '').strip().lower()
+ == 'true'
+ ]
+ nested_carriers = [
+ child for child in carrier_descendants
+ if parent_by_id.get(id(child)) is not elem
+ ]
+ if nested_carriers:
+ names = ', '.join(
+ child.get('id') or f"<{child.tag.rsplit('}', 1)[-1]}>"
+ for child in nested_carriers
+ )
+ errors.append(
+ f"{svg_path.name}: placeholder slot {element_id} has nested "
+ f"carrier marker(s): {names}; the carrier must be a direct child"
+ )
+ if binding == 'carrier':
+ if len(visual_children) != 1 or len(direct_carriers) != 1:
+ errors.append(
+ f"{svg_path.name}: placeholder slot {element_id} requires "
+ "exactly one visual direct child, marked "
+ "data-pptx-carrier=\"true\""
+ )
+ if binding == 'proxy':
+ if placeholder != 'object':
+ errors.append(
+ f"{svg_path.name}: proxy binding is allowed only for an "
+ f"object placeholder, not {placeholder!r}"
+ )
+ if carrier_descendants:
+ errors.append(
+ f"{svg_path.name}: proxy placeholder slot {element_id} must "
+ "not declare a visible placeholder carrier"
+ )
+ if not visual_children:
+ errors.append(
+ f"{svg_path.name}: proxy placeholder slot {element_id} must "
+ "contain visible Slide-local content"
+ )
+
+ carrier_value = elem.get('data-pptx-carrier')
+ if carrier_value is not None:
+ if carrier_value.strip().lower() != 'true':
+ errors.append(
+ f"{svg_path.name}: {element_id} "
+ "data-pptx-carrier must equal true"
+ )
+ if parent is None or not (
+ parent.get('data-pptx-placeholder') or ''
+ ).strip():
+ errors.append(
+ f"{svg_path.name}: placeholder carrier {element_id} must be a "
+ "direct child of a root placeholder slot"
+ )
+
+ if tag in _NON_VISUAL_SVG_TAGS and (layer or placeholder):
+ errors.append(
+ f"{svg_path.name}: non-visual {element_id} cannot carry "
+ "Master/Layout/placeholder ownership"
+ )
+
+ return list(dict.fromkeys(errors))
+
+
+def _normalize_hex_rgb(value: str) -> str | None:
+ """Normalize 3/4/6/8-digit HEX to alpha-free ``RRGGBB``."""
+ if not HEX_VALUE_RE.fullmatch(value):
+ return None
+ color = value[1:]
+ if len(color) in {3, 4}:
+ color = ''.join(channel * 2 for channel in color)
+ return color[:6].upper()
+
+
+# Cheap numeric envelope for font-size role enforcement. Semantic role assignment
+# is prompt-owned; Checker only verifies that a used value is close to at least
+# one declared size anchor.
+FONT_SIZE_ANCHOR_TOLERANCE_PX = 2.0
+SPARSE_UNDECLARED_FONT_SIZE_MAX_OCCURRENCES = 2
+
+# Oversampling alone does not imply distortion and is often harmless for small
+# logos. Warn about downscaling only when the source also has material on-disk
+# weight, because PPTX embeds the compressed source asset rather than raw pixels.
+IMAGE_DOWNSIZE_WARN_RATIO = 4.0
+IMAGE_DOWNSIZE_WARN_MIN_BYTES = 1024 * 1024
+
+def _design_spec_is_brand(spec_path: Path) -> bool:
+ """Return True when a design_spec.md frontmatter declares ``kind: brand``.
+
+ Lightweight detector that does not require PyYAML — scans only the
+ frontmatter block (``---`` delimited) for a ``kind:`` line whose value
+ contains ``brand``. Used by ``check_directory`` to select Brand schema
+ validation instead of SVG-roster validation.
+ """
+ try:
+ text = spec_path.read_text(encoding='utf-8')
+ except OSError:
+ return False
+ if not text.startswith('---\n'):
+ return False
+ end = text.find('\n---\n', 4)
+ if end == -1:
+ return False
+ fm_block = text[4:end]
+ for line in fm_block.splitlines():
+ stripped = line.strip()
+ if stripped.startswith('kind:'):
+ value = stripped.split(':', 1)[1].strip().strip('"\'')
+ return value == 'brand'
+ return False
+
+
+def _declared_template_structure_mode(target_path: Path) -> str | None:
+ """Return a template directory's explicit native structure mode."""
+ directory = target_path.parent if target_path.is_file() else target_path
+ spec_path = directory / 'design_spec.md'
+ try:
+ text = spec_path.read_text(encoding='utf-8')
+ except OSError:
+ return None
+ if not text.startswith('---\n'):
+ return None
+ end = text.find('\n---\n', 4)
+ if end == -1:
+ return None
+ match = re.search(
+ r'^native_structure_mode:\s*([A-Za-z0-9_-]+)\s*$',
+ text[4:end],
+ re.MULTILINE,
+ )
+ return match.group(1).lower() if match else None
+
+
+def _declared_template_canvas_viewbox(target_path: Path) -> str | None:
+ """Return a template design spec's locked root-canvas value."""
+ directory = target_path.parent if target_path.is_file() else target_path
+ spec_path = directory / 'design_spec.md'
+ try:
+ text = spec_path.read_text(encoding='utf-8')
+ except OSError:
+ return None
+ if not text.startswith('---\n'):
+ return None
+ end = text.find('\n---\n', 4)
+ if end == -1:
+ return None
+ match = re.search(
+ r'^canvas_viewbox:\s*["\']?([^"\'\r\n]+?)["\']?\s*$',
+ text[4:end],
+ re.MULTILINE,
+ )
+ return match.group(1).strip() if match else None
+
+
+def _template_structure_checks_enabled(target_path: Path) -> bool:
+ """Return whether positive structure checks apply to this template."""
+ return _declared_template_structure_mode(target_path) == 'structured'
+
+
+def _local_name(elem: ET.Element) -> str:
+ """Return an XML element's namespace-free local tag name."""
+ tag = elem.tag
+ if not isinstance(tag, str):
+ return ''
+ return tag.rsplit('}', 1)[-1] if '}' in tag else tag
+
+
+def _direct_defs_index(
+ root: ET.Element,
+) -> tuple[Dict[str, ET.Element], set[str]]:
+ """Return direct ``<defs>`` children by id plus duplicate ids."""
+ definitions: Dict[str, ET.Element] = {}
+ duplicates: set[str] = set()
+ for defs_elem in root.iter():
+ if _local_name(defs_elem) != 'defs':
+ continue
+ for child in defs_elem:
+ definition_id = (child.get('id') or '').strip()
+ if not definition_id:
+ continue
+ if definition_id in definitions:
+ duplicates.add(definition_id)
+ definitions[definition_id] = child
+ return definitions, duplicates
+
+
+def _element_label(elem: ET.Element) -> str:
+ """Return a compact element label for validation messages."""
+ tag = _local_name(elem)
+ elem_id = (elem.get('id') or '').strip()
+ return f'<{tag} id="{elem_id}">' if elem_id else f'<{tag}>'
+
+
+def _effective_presentation_value(
+ elem: ET.Element,
+ name: str,
+ parent_by_id: Dict[int, ET.Element],
+) -> str | None:
+ """Resolve one inherited presentation property for validation."""
+ current: ET.Element | None = elem
+ while current is not None:
+ style_values = (
+ _parse_inline_style(current.get('style'))
+ if _parse_inline_style is not None else {}
+ )
+ if name in style_values:
+ return style_values[name]
+ direct = current.get(name)
+ if direct is not None:
+ return direct
+ current = parent_by_id.get(id(current))
+ return None
+
+
+def _parse_viewbox_values(viewbox: str) -> Tuple[float, float, float, float] | None:
+ """Parse a root viewBox into four numeric values."""
+ try:
+ parsed = parse_project_viewbox(viewbox)
+ except CanvasContractError:
+ return None
+ return 0.0, 0.0, float(parsed.width), float(parsed.height)
+
+
+def _parse_placeholders_fallback(block: str) -> Dict[str, Tuple[str, ...]]:
+ """Tiny YAML-free reader for the documented ``placeholders:`` shape.
+
+ Used only when PyYAML is unavailable. Recognized lines (indentation-aware,
+ two-space indent assumed):
+
+ .. code-block:: yaml
+
+ placeholders:
+ 01_cover: ["{{TITLE}}", "{{LOGO}}"]
+ 03_content: []
+ 03a_content_two_col:
+ - "{{LEFT_TITLE}}"
+ - "{{RIGHT_TITLE}}"
+
+ Anything outside this minimal grammar is silently skipped — designers who
+ rely on advanced YAML should install pyyaml.
+ """
+ out: Dict[str, Tuple[str, ...]] = {}
+ inline_re = re.compile(
+ r"^\s{2}([A-Za-z0-9_]+)\s*:\s*\[(.*)\]\s*$"
+ )
+ empty_re = re.compile(r"^\s{2}([A-Za-z0-9_]+)\s*:\s*\[\s*\]\s*$")
+ block_header_re = re.compile(r"^\s{2}([A-Za-z0-9_]+)\s*:\s*$")
+ item_re = re.compile(r'^\s{4}-\s*"?([^"]+)"?\s*$')
+
+ in_section = False
+ current_block_key: str | None = None
+ current_items: List[str] = []
+
+ def _flush_block() -> None:
+ nonlocal current_block_key, current_items
+ if current_block_key is not None:
+ out[current_block_key] = tuple(current_items)
+ current_block_key = None
+ current_items = []
+
+ for line in block.splitlines():
+ if line.startswith("placeholders:"):
+ in_section = True
+ continue
+ if not in_section:
+ continue
+
+ # End of section: dedent to a non-key line.
+ if line and not line.startswith(" "):
+ _flush_block()
+ in_section = False
+ continue
+
+ if current_block_key is not None:
+ m = item_re.match(line)
+ if m:
+ value = m.group(1).strip().strip('"').strip("'")
+ if value:
+ current_items.append(value)
+ continue
+ # Block ended.
+ _flush_block()
+
+ if empty_re.match(line):
+ key = empty_re.match(line).group(1)
+ out[key] = ()
+ continue
+
+ m = inline_re.match(line)
+ if m:
+ key, raw = m.group(1), m.group(2)
+ items = [p.strip().strip('"').strip("'") for p in raw.split(",")]
+ out[key] = tuple(item for item in items if item)
+ continue
+
+ m = block_header_re.match(line)
+ if m:
+ current_block_key = m.group(1)
+ current_items = []
+ continue
+
+ _flush_block()
+ return out
+
+
+class SVGQualityChecker:
+ """SVG quality checker"""
+
+ # Default placeholder convention per page-type prefix. This is a *hint*,
+ # not a hard contract: templates may define their own placeholder vocabulary
+ # via `placeholders:` in design_spec.md frontmatter (see
+ # references/template-designer.md §4). Missing default placeholders surface
+ # as warnings, never errors — designers may legitimately swap
+ # `{{THANK_YOU}}` for `{{CLOSING_MESSAGE}}`, omit `{{DATE}}` when irrelevant,
+ # or build content variants with bespoke slot vocabularies.
+ #
+ # Variants reuse the parent type's expectation (`03a_content_two_col.svg`
+ # is matched by the same `content` rules as `03_content.svg`).
+ #
+ # Keys are page-type tokens, not numbered stems: template numbering is
+ # presentation order within one template and shifts when the optional
+ # TOC page is present (`02_chapter` in a four-page roster, `03_chapter`
+ # in a five-page roster with `02_toc`), so the defaults must apply to
+ # both spellings.
+ DEFAULT_PLACEHOLDER_CONVENTION = {
+ "cover": ("{{TITLE}}",), # only the title is universally expected
+ "chapter": ("{{CHAPTER_TITLE}}",),
+ "toc": (), # TOC layouts vary too widely to assert anything
+ "content": ("{{PAGE_TITLE}}",),
+ "ending": (), # ending pages legitimately use varied vocabularies
+ }
+
+ def __init__(
+ self,
+ *,
+ template_mode: bool = False,
+ quick_generate: bool = False,
+ ):
+ self.template_mode = template_mode
+ self.quick_generate = quick_generate
+ self.results = []
+ self.summary = {
+ 'total': 0,
+ 'passed': 0,
+ 'warnings': 0,
+ 'errors': 0
+ }
+ self.issue_types = defaultdict(int)
+ # spec_lock anchor comparison state (populated only when
+ # _parse_spec_lock is available and a spec_lock.md is found near the SVG)
+ self._lock_cache: Dict[Path, Dict] = {}
+ self._anchor_value_summary: Dict[str, Dict[str, set]] = {
+ 'colors': defaultdict(set),
+ 'fonts': defaultdict(set),
+ 'sizes': defaultdict(set),
+ }
+ self._undeclared_size_occurrences: Counter[str] = Counter()
+ self._undeclared_size_counts_ready = False
+ self._lock_seen = False # True once we locate at least one spec_lock.md
+ self._source_manifest_cache: Dict[
+ Path,
+ Tuple[Dict, str | None],
+ ] = {}
+ self._source_manifest_errors_reported: set[Path] = set()
+ # Template-mode aggregation (populated by check_directory when
+ # template_mode=True). Each entry is (severity, kind, message) where
+ # severity is 'error' or 'warning'. Printed in print_summary.
+ self._template_issues: List[Tuple[str, str, str]] = []
+ self._brand_template_checked = False
+ self._animation_issues: List[Tuple[str, str]] = []
+ self._illustration_issues: List[Tuple[str, str, str]] = []
+ self._communication_trace_issues: List[Tuple[str, str]] = []
+ self._pptx_structure_issues: List[Tuple[str, str]] = []
+ self._has_incomplete_page_roster = False
+ self._prototype_by_output: Dict[Path, Path] = {}
+ self._active_prototype_path: Path | None = None
+ self._active_template_reuse_scope: str | None = None
+ self._prototype_root_cache: Dict[Path, ET.Element | None] = {}
+ self._source_import_summary: Dict[str, object] = {
+ 'warning_count': 0,
+ 'by_code': {},
+ }
+ self._aggregate_counts_applied = False
+
+ @staticmethod
+ def _append_inherited_info(
+ result: Dict,
+ kind: str,
+ message: str,
+ ) -> None:
+ """Record prototype-owned diagnostics outside the warning channel."""
+ result['info'].setdefault('inherited', []).append({
+ 'kind': kind,
+ 'message': message,
+ })
+
+ def _active_prototype_root(self) -> ET.Element | None:
+ """Parse the selected mirror prototype once for inherited checks."""
+ if (
+ self._active_template_reuse_scope != 'mirror'
+ or self._active_prototype_path is None
+ ):
+ return None
+ path = self._active_prototype_path.resolve()
+ if path in self._prototype_root_cache:
+ return self._prototype_root_cache[path]
+ try:
+ root = ET.parse(path).getroot()
+ hydrate_native_payload_refs(root, path)
+ except (OSError, ET.ParseError, NativePayloadError):
+ root = None
+ self._prototype_root_cache[path] = root
+ return root
+
+ def check_file(
+ self,
+ svg_file: str,
+ expected_format: str = None,
+ *,
+ expected_viewbox: str | None = None,
+ expected_viewbox_label: str = "expected canvas",
+ ) -> Dict:
+ """
+ Check a single SVG file
+
+ Args:
+ svg_file: SVG file path
+ expected_format: Expected canvas format (e.g., 'ppt169')
+
+ Returns:
+ Check result dictionary
+ """
+ svg_path = Path(svg_file)
+
+ if not svg_path.exists():
+ return {
+ 'file': str(svg_file),
+ 'exists': False,
+ 'errors': ['File does not exist'],
+ 'warnings': [],
+ 'passed': False
+ }
+
+ result = {
+ 'file': svg_path.name,
+ 'path': str(svg_path),
+ 'exists': True,
+ 'errors': [],
+ 'warnings': [],
+ 'info': {},
+ 'passed': True
+ }
+
+ try:
+ source_bytes = svg_path.read_bytes()
+ result['source_sha256'] = hashlib.sha256(source_bytes).hexdigest()
+ content = source_bytes.decode('utf-8')
+
+ # 0. Parse XML once — every other check assumes the file is valid
+ # XML. Bail early on failure so the regex-based checks below don't
+ # produce misleading errors on a broken document.
+ root = self._parse_xml_root(content, result)
+ if root is not None:
+ try:
+ hydrated_payloads = hydrate_native_payload_refs(root, svg_path)
+ except NativePayloadError as exc:
+ result['errors'].append(
+ f"Invalid native payload reference: {exc}"
+ )
+ else:
+ if hydrated_payloads:
+ result['info']['native_payload_refs'] = hydrated_payloads
+
+ # 1. Check viewBox
+ self._check_viewbox(
+ root,
+ svg_path,
+ result,
+ expected_format,
+ expected_viewbox=expected_viewbox,
+ expected_viewbox_label=expected_viewbox_label,
+ )
+ self._check_legacy_pptx_attributes(root, svg_path, result)
+
+ # 1a. Validate exact importer transport before compatible
+ # inline geometry is materialized on the shared tree.
+ self._check_nested_svg_crop_contract(root, result)
+
+ # 2. Check forbidden elements
+ self._check_forbidden_elements(content, root, result)
+ self._check_mask_contract(root, result)
+
+ # 2a. Validate direct geometry lengths and stroke widths.
+ self._check_geometry_length_values(root, result)
+
+ # 2b. Validate line-presentation grammar and mappings.
+ self._check_stroke_style_values(root, result)
+
+ # 2c. Validate image fit/crop grammar and mappings.
+ self._check_image_contract(root, svg_path, result)
+ self._check_image_aspect_ratio_values(root, result)
+
+ # 2d. Validate complete path-data and point-list grammar.
+ self._check_freeform_geometry_values(root, result)
+
+ # 2e. Validate complete transform grammar and native mappings.
+ self._check_transform_values(root, result)
+
+ # 2f. Validate opacity grammar and native alpha mappings.
+ self._check_opacity_values(root, result)
+
+ # 2g. Validate the closed authoring-property surface and
+ # conditional definition interfaces before export.
+ self._check_authoring_property_contract(root, result)
+ self._check_text_property_contract(root, result)
+ self._check_preserved_txbody_contract(root, result)
+ self._check_paint_compatibility(root, result)
+ self._check_reference_spelling(root, result)
+ self._check_definition_contract(root, result)
+ self._check_paint_reference_contract(root, result)
+ self._check_marker_contract(root, result)
+ self._check_clip_path_contract(root, result)
+
+ # 2h. Validate the supported shadow/glow filter interface.
+ self._check_imported_effect_status(root, result)
+ self._check_filter_effects(root, result)
+
+ # 2i. Validate gradient definitions, stops, and coordinates.
+ self._check_gradient_interfaces(root, result)
+
+ # 3. Check font-size values
+ self._check_font_size_values(content, result)
+
+ # 4. Check fonts
+ self._check_fonts(content, result)
+
+ # 5. Check text wrapping methods
+ self._check_text_elements(content, root, result)
+
+ # 6. Check image references (file existence and resolution)
+ self._check_image_references(root, svg_path, result)
+
+ # 7. Check icon placeholders resolve before post-processing.
+ self._check_icon_placeholders(root, svg_path, result)
+
+ # 7b. Reject visual elements the native converter cannot dispatch.
+ self._check_unsupported_visual_elements(root, result)
+
+ # 7c. Fail closed on invalid PPTX preset/adjustment metadata.
+ self._check_preset_geometry_metadata(root, result)
+ self._check_preset_geometry_transforms(root, result)
+
+ # 8. Check object-level animation anchor quality.
+ self._check_animation_group_ids(root, svg_path, result)
+
+ # 8b. Check <pattern> elements declare a PPTX preset.
+ self._check_pattern_fills(root, result)
+
+ # 8c. Check opt-in native table/chart markers before export.
+ self._check_native_object_markers(root, result)
+
+ # 8d. Validate explicit master/layout/placeholder metadata.
+ if (
+ _template_structure_checks_enabled(svg_path)
+ if self.template_mode
+ else _CHECK_PPTX_STRUCTURED_PROJECT
+ ):
+ self._check_pptx_structure_metadata(root, svg_path, result)
+
+ # 8e. Validate rendering-neutral page/structure compiler hints.
+ self._check_semantic_markers(root, svg_path, result)
+
+ # 9. Compare values with spec_lock anchors. Additional colors
+ # and fonts are informational. Generated-page type sizes may
+ # stay sparse twice; the third occurrence is an error. Other
+ # spec-backed SVG locations retain advisory review. Templates
+ # do not ship a spec_lock.md, so skip in template mode.
+ if not self.template_mode:
+ self._check_spec_lock_alignment(
+ content,
+ svg_path,
+ result,
+ root=root,
+ )
+
+ # 10. Check web-sourced image attribution. Templates don't carry
+ # image_sources.json; skip in template mode.
+ if not self.template_mode:
+ self._check_sourced_image_attribution(
+ root,
+ svg_path,
+ result,
+ )
+
+ # Determine pass/fail
+ result['passed'] = len(result['errors']) == 0
+
+ except Exception as e:
+ result['errors'].append(f"Failed to read file: {e}")
+ result['passed'] = False
+
+ # Update statistics
+ self.summary['total'] += 1
+ if result['passed']:
+ if result['warnings']:
+ self.summary['warnings'] += 1
+ else:
+ self.summary['passed'] += 1
+ else:
+ self.summary['errors'] += 1
+
+ # Categorize issue types
+ for error in result['errors']:
+ self.issue_types[self._categorize_issue(error)] += 1
+
+ self.results.append(result)
+ return result
+
+ def _parse_xml_root(self, content: str, result: Dict) -> ET.Element | None:
+ """Parse the SVG content as well-formed XML.
+
+ SVG is strict XML. AI-generated decks frequently produce content that
+ looks fine in HTML5-tolerant previews but fails strict XML parsing —
+ common causes are HTML named entities (&nbsp; &mdash; &copy;…) and
+ bare XML reserved characters in text (R&D, error < 5%). Such pages
+ cannot be exported to PPTX, so we surface them here as a hard error
+ before any downstream check looks at them.
+
+ Returns the parsed root when the document is well-formed; otherwise
+ appends an error and returns None.
+ """
+ try:
+ return ET.fromstring(content)
+ except ET.ParseError as e:
+ result['errors'].append(
+ f"Invalid XML: {e} — SVG must be well-formed XML. "
+ f"Use raw Unicode for typography (—, ©, →, NBSP); "
+ f"escape XML reserved chars as &amp; &lt; &gt; &quot; &apos; "
+ f"(see references/shared-standards-core.md §1)."
+ )
+ return None
+
+ def _check_viewbox(
+ self,
+ root: ET.Element,
+ svg_path: Path,
+ result: Dict,
+ expected_format: str = None,
+ *,
+ expected_viewbox: str | None = None,
+ expected_viewbox_label: str = "expected canvas",
+ ):
+ """Validate the root page canvas and its project-level locks."""
+ viewbox = root.get('viewBox')
+ try:
+ parsed = parse_project_svg_root(
+ root,
+ context=svg_path.name,
+ )
+ except CanvasContractError as exc:
+ result['errors'].append(str(exc))
+ return
+ assert viewbox is not None
+ result['info']['viewbox'] = viewbox
+ if viewbox != parsed.canonical or not parsed.has_integer_dimensions:
+ if parsed.has_integer_dimensions:
+ recommendation = f'write viewBox="{parsed.canonical}"'
+ else:
+ recommendation = (
+ "fractional dimensions are reserved for compatible imported "
+ "custom slide sizes; new authoring uses integer pixels"
+ )
+ result['warnings'].append(
+ f"Compatible non-canonical root viewBox {viewbox!r}; {recommendation}."
+ )
+
+ contracts: list[tuple[str, str]] = []
+ if expected_viewbox is not None:
+ contracts.append((expected_viewbox_label, expected_viewbox))
+ elif not self.template_mode:
+ lock = self._get_spec_lock(svg_path)
+ if lock is not None and 'canvas' in lock:
+ locked_viewbox = lock.get('canvas', {}).get('viewBox')
+ if not locked_viewbox:
+ result['errors'].append(
+ "spec_lock.md canvas section must declare viewBox"
+ )
+ else:
+ contracts.append(("spec_lock canvas", locked_viewbox))
+
+ if expected_format and expected_format in CANVAS_FORMATS:
+ contracts.append((
+ f"canvas format {expected_format!r}",
+ CANVAS_FORMATS[expected_format]['viewbox'],
+ ))
+ elif expected_format:
+ result['errors'].append(f"Unsupported canvas format: {expected_format}")
+
+ seen_contracts: set[tuple[str, str]] = set()
+ for label, raw_expected in contracts:
+ contract_key = (label, raw_expected)
+ if contract_key in seen_contracts:
+ continue
+ seen_contracts.add(contract_key)
+ try:
+ expected = parse_project_viewbox(
+ raw_expected,
+ context=f"{label} viewBox",
+ )
+ except CanvasContractError as exc:
+ result['errors'].append(str(exc))
+ continue
+ if parsed != expected:
+ result['errors'].append(
+ f"viewBox mismatch: {label} requires '{expected.canonical}', "
+ f"got '{parsed.canonical}'"
+ )
+
+ def _check_forbidden_elements(self, content: str, root: ET.Element, result: Dict):
+ """Check forbidden elements (blocklist)"""
+ content_lower = content.lower()
+ elems = list(root.iter())
+ local_names = {_local_name(elem).lower() for elem in elems}
+
+ # ============================================================
+ # Forbidden elements blocklist - PPT incompatible
+ # ============================================================
+
+ # Style system
+ if 'style' in local_names:
+ result['errors'].append("Detected forbidden <style> element (use inline attributes instead)")
+ if re.search(r'\bclass\s*=', content):
+ result['errors'].append("Detected forbidden class attribute (use inline styles instead)")
+ # id attribute: only report error when <style> also exists (id is harmful only with CSS selectors)
+ # id inside <defs> for linearGradient/filter etc. is required, Inkscape also auto-adds id to elements,
+ # standalone id attributes have no impact on PPT export
+ if 'style' in local_names and re.search(r'\bid\s*=', content):
+ result['errors'].append(
+ "Detected id attribute used with <style> (CSS selectors forbidden, use inline styles instead)"
+ )
+ if re.search(r'<\?xml-stylesheet\b', content_lower):
+ result['errors'].append("Detected forbidden xml-stylesheet (external CSS references forbidden)")
+ if re.search(r'<link[^>]*rel\s*=\s*["\']stylesheet["\']', content_lower):
+ result['errors'].append("Detected forbidden <link rel=\"stylesheet\"> (external CSS references forbidden)")
+ if re.search(r'@import\s+', content_lower):
+ result['errors'].append("Detected forbidden @import (external CSS references forbidden)")
+ if _validate_inline_geometry_properties is None:
+ result['warnings'].append(
+ "Unable to import inline geometry validator; "
+ "native export will still validate geometry styles."
+ )
+ else:
+ geometry_errors = _validate_inline_geometry_properties(root)
+ for error in geometry_errors:
+ result['errors'].append(f"Invalid inline geometry property: {error}")
+ if not geometry_errors:
+ _materialize_inline_geometry_properties(root)
+
+ # Structure / nesting
+ if 'foreignobject' in local_names:
+ result['errors'].append(
+ "Detected forbidden <foreignObject> element (use <tspan> for manual line breaks)")
+ has_generic_use = any(
+ _local_name(elem).lower() == 'use' and elem.get('data-icon') is None
+ for elem in elems
+ )
+ if has_generic_use:
+ if _validate_local_use_references is None:
+ result['warnings'].append(
+ "Detected local <use> references, but the shared validator "
+ "could not be imported; native export will still validate them."
+ )
+ else:
+ for error in _validate_local_use_references(root):
+ result['errors'].append(f"Invalid local <use> reference: {error}")
+ # Text / fonts
+ if 'textpath' in local_names:
+ result['errors'].append("Detected forbidden <textPath> element (path text is incompatible with PPT)")
+ if '@font-face' in content_lower:
+ result['errors'].append("Detected forbidden @font-face (use system font stack)")
+
+ # Animation / interaction
+ if any(name.startswith('animate') for name in local_names):
+ result['errors'].append("Detected forbidden SMIL animation element <animate*> (SVG animations are not exported)")
+ if 'set' in local_names:
+ result['errors'].append("Detected forbidden SMIL animation element <set> (SVG animations are not exported)")
+ if 'script' in local_names:
+ result['errors'].append("Detected forbidden <script> element (scripts and event handlers forbidden)")
+ if re.search(r'\bon\w+\s*=', content): # onclick, onload etc.
+ result['errors'].append("Detected forbidden event attributes (e.g., onclick, onload)")
+
+ # Other discouraged elements
+ if 'iframe' in local_names:
+ result['errors'].append("Detected <iframe> element (should not appear in SVG)")
+
+ def _check_paint_compatibility(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Reject unsupported paint and advise one generated-SVG spelling.
+
+ The exporter parser owns compatibility. Any paint it can parse remains
+ valid input; the checker only warns when that spelling differs from the
+ generated-SVG default (uppercase ``#RRGGBB`` plus explicit alpha).
+ """
+ helpers = (
+ _PAINT_PROPERTIES,
+ _PERCENTAGE_OPACITY_PROPERTIES,
+ _format_project_opacity,
+ _is_project_paint_default_form,
+ _iter_project_paints,
+ _parse_inline_style,
+ _parse_project_opacity,
+ _parse_project_paint,
+ _project_paint_errors,
+ )
+ if any(helper is None for helper in helpers):
+ result['warnings'].append(
+ "Unable to import svg_to_pptx paint parsers; skipped paint syntax check"
+ )
+ return
+
+ result['errors'].extend(_project_paint_errors(root))
+ recommendations: Counter[tuple[str, str, str]] = Counter()
+ recommendation_examples: Dict[tuple[str, str, str], List[str]] = defaultdict(list)
+
+ def remember_example(store: Dict, key: tuple, label: str) -> None:
+ labels = store[key]
+ if label not in labels and len(labels) < 3:
+ labels.append(label)
+
+ for elem, name, raw_value, source in _iter_project_paints(root):
+ try:
+ kind, normalized, color_alpha = _parse_project_paint(
+ raw_value,
+ name,
+ )
+ except ValueError:
+ continue
+ if _is_project_paint_default_form(raw_value, name):
+ continue
+
+ source_label = f'{_element_label(elem)} {source}'
+ if kind == 'none':
+ replacement = f'{name}="none"'
+ elif kind == 'reference':
+ replacement = f'{name}="url(#{normalized})"'
+ elif name in {'fill', 'stroke'} and raw_value.strip().lower() == 'transparent':
+ replacement = f'{name}="none"'
+ else:
+ replacement = f'{name}="#{normalized}"'
+ alpha_name = _CANONICAL_PAINT_ALPHA_PROPERTY.get(name)
+ if color_alpha < 1.0 and alpha_name is not None:
+ style_values = _parse_inline_style(elem.get('style'))
+ existing_alpha_raw = (
+ style_values.get(alpha_name) or elem.get(alpha_name)
+ )
+ if existing_alpha_raw is None:
+ existing_alpha = 1.0
+ else:
+ try:
+ existing_alpha = _parse_project_opacity(
+ existing_alpha_raw,
+ allow_percentage=(
+ alpha_name in _PERCENTAGE_OPACITY_PROPERTIES
+ ),
+ )
+ except ValueError:
+ existing_alpha = None
+ effective_alpha = (
+ color_alpha * existing_alpha
+ if existing_alpha is not None else color_alpha
+ )
+ replacement += (
+ f' {alpha_name}="'
+ f'{_format_project_opacity(effective_alpha)}"'
+ )
+ elif color_alpha < 1.0:
+ replacement += (
+ '; put alpha on the matching pattern child fill/stroke '
+ 'opacity'
+ )
+
+ key = (name, raw_value, replacement)
+ recommendations[key] += 1
+ remember_example(recommendation_examples, key, source_label)
+
+ for (name, raw_value, replacement), count in sorted(recommendations.items()):
+ examples = ', '.join(
+ recommendation_examples[(name, raw_value, replacement)]
+ )
+ result['warnings'].append(
+ f"Recommendation: {name}={raw_value!r} is converter-compatible "
+ f"in {count} location(s) ({examples}); generated SVG should "
+ f"prefer {replacement}. No change is required for export."
+ )
+
+ def _check_reference_spelling(self, root: ET.Element, result: Dict) -> None:
+ """Recommend SVG 2 ``href`` while retaining legacy XLink input."""
+ labels = []
+ xlink_href = f'{{{XLINK_NS}}}href'
+ for elem in root.iter():
+ if _local_name(elem).lower() not in {'image', 'use'}:
+ continue
+ if elem.get(xlink_href) is not None:
+ labels.append(_element_label(elem))
+ if labels:
+ examples = ', '.join(labels[:3])
+ suffix = f' (+{len(labels) - 3} more)' if len(labels) > 3 else ''
+ result['warnings'].append(
+ f"Recommendation: legacy xlink:href is supported on {len(labels)} "
+ f"reference(s) ({examples}{suffix}); generated SVG should prefer "
+ "href. No change is required for export."
+ )
+
+ def _check_opacity_values(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Reject malformed opacity and advise generated-SVG values."""
+ helpers = (
+ _PERCENTAGE_OPACITY_PROPERTIES,
+ _format_project_opacity,
+ _is_project_opacity_default_form,
+ _iter_project_opacities,
+ _parse_inline_style,
+ _parse_project_opacity,
+ _project_opacity_errors,
+ )
+ if any(helper is None for helper in helpers):
+ result['warnings'].append(
+ "Unable to import svg_to_pptx opacity validators; native "
+ "export will still validate opacity syntax."
+ )
+ return
+
+ result['errors'].extend(_project_opacity_errors(root))
+ recommendations: Counter[tuple[str, str, str]] = Counter()
+ examples: Dict[tuple[str, str, str], List[str]] = defaultdict(list)
+ fidelity_warnings: set[str] = set()
+
+ for elem, property_name, raw, source in _iter_project_opacities(root):
+ try:
+ value = _parse_project_opacity(
+ raw,
+ allow_percentage=(
+ property_name in _PERCENTAGE_OPACITY_PROPERTIES
+ ),
+ )
+ except ValueError:
+ continue
+ if _is_project_opacity_default_form(raw):
+ continue
+ normalized = _format_project_opacity(value)
+ key = (property_name, raw, normalized)
+ recommendations[key] += 1
+ label = f'{_element_label(elem)} {source}'
+ if label not in examples[key] and len(examples[key]) < 3:
+ examples[key].append(label)
+
+ for elem in root.iter():
+ if _local_name(elem).lower() != 'g':
+ continue
+ style_values = _parse_inline_style(elem.get('style'))
+ raw_opacity = (
+ style_values['opacity']
+ if 'opacity' in style_values else elem.get('opacity')
+ )
+ if raw_opacity is None:
+ continue
+ try:
+ opacity = _parse_project_opacity(raw_opacity)
+ except ValueError:
+ continue
+ if opacity < 1.0:
+ fidelity_warnings.add(
+ f"Fidelity warning: {_element_label(elem)} uses group "
+ f"opacity={raw_opacity!r}. The converter distributes this "
+ "alpha to descendants and cannot preserve isolated group "
+ "compositing; generated SVG should prefer descendant alpha. "
+ "Existing input remains convertible and does not require "
+ "modification."
+ )
+
+ for (property_name, raw, normalized), count in sorted(
+ recommendations.items()
+ ):
+ shown_examples = ', '.join(
+ examples[(property_name, raw, normalized)]
+ )
+ result['warnings'].append(
+ f"Recommendation: {property_name}={raw!r} is "
+ f"converter-compatible in {count} location(s) "
+ f"({shown_examples}); generated SVG should prefer "
+ f'{property_name}="{normalized}". No change is required '
+ "for export."
+ )
+ result['warnings'].extend(sorted(fidelity_warnings))
+
+ def _check_authoring_property_contract(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Validate inline CSS and attributes against the authoring surface."""
+ errors: set[str] = set()
+ validated_value_properties = set(_OPACITY_PROPERTIES or ())
+ validated_value_properties.update(_PAINT_PROPERTIES or ())
+ for elem in root.iter():
+ label = _element_label(elem)
+ for fragment in (elem.get('style') or '').split(';'):
+ fragment = fragment.strip()
+ if not fragment:
+ continue
+ if ':' not in fragment:
+ if fragment.lower() not in validated_value_properties:
+ errors.add(
+ f"{label} has malformed inline style declaration "
+ f"{fragment!r}"
+ )
+ continue
+ name, value = fragment.split(':', 1)
+ name = name.strip().lower()
+ value = value.strip()
+ if not name or not value:
+ if name not in validated_value_properties:
+ errors.add(
+ f"{label} has malformed inline style declaration "
+ f"{fragment!r}"
+ )
+ continue
+ if name in _BAKE_REQUIRED_VISUAL_PROPERTIES:
+ errors.add(
+ f"{label} uses Bake-required visual property {name!r}; "
+ "bake the effect or rebuild it with supported geometry"
+ )
+ elif (
+ name not in _SUPPORTED_INLINE_STYLE_PROPERTIES
+ and name not in _SHARED_FAIL_CLOSED_STYLE_PROPERTIES
+ ):
+ errors.add(
+ f"{label} uses unsupported inline style property {name!r}; "
+ "native PPTX export would ignore it"
+ )
+ if '!important' in value.lower():
+ errors.add(
+ f"{label} inline style property {name!r} cannot use !important"
+ )
+
+ for attr_name in elem.attrib:
+ local_attr = attr_name.rsplit('}', 1)[-1]
+ if local_attr in _BAKE_REQUIRED_VISUAL_PROPERTIES:
+ errors.add(
+ f"{label} uses Bake-required visual attribute {local_attr!r}; "
+ "bake the effect or rebuild it with supported geometry"
+ )
+
+ result['errors'].extend(sorted(errors))
+
+ def _check_text_property_contract(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Validate text property names and values with the export contract."""
+ if _project_text_property_diagnostics is None:
+ result['warnings'].append(
+ "Unable to import the shared text-property validator; native "
+ "export will still validate text properties."
+ )
+ return
+
+ errors: set[str] = set()
+ recommendations: Counter[tuple[str, str, str]] = Counter()
+ examples: Dict[tuple[str, str, str], List[str]] = defaultdict(list)
+ for diagnostic in _project_text_property_diagnostics(root):
+ if diagnostic.severity == 'error':
+ errors.add(diagnostic.message)
+ continue
+ if diagnostic.canonical is None:
+ continue
+ key = (
+ diagnostic.name,
+ diagnostic.raw,
+ diagnostic.canonical,
+ )
+ recommendations[key] += 1
+ if (
+ diagnostic.label not in examples[key]
+ and len(examples[key]) < 3
+ ):
+ examples[key].append(diagnostic.label)
+
+ result['errors'].extend(sorted(errors))
+ for (name, raw, canonical), count in sorted(recommendations.items()):
+ shown_examples = ', '.join(examples[(name, raw, canonical)])
+ result['warnings'].append(
+ f"Recommendation: text property {name}={raw!r} is "
+ f"converter-compatible in {count} location(s) "
+ f"({shown_examples}); generated SVG should prefer "
+ f'{name}="{canonical}". No change is required for export.'
+ )
+
+ def _check_definition_contract(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Require conditional definitions to be direct, uniquely identified defs."""
+ if _project_definition_errors is None:
+ result['warnings'].append(
+ "Unable to import the shared definition validator; native "
+ "export will still validate local definitions."
+ )
+ return
+ result['errors'].extend(_project_definition_errors(root))
+
+ def _check_paint_reference_contract(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Validate paint-server resolution and native target contexts."""
+ if _project_paint_reference_errors is None:
+ result['warnings'].append(
+ "Unable to import the shared paint-reference validator; native "
+ "export will still validate local paint references."
+ )
+ return
+ result['errors'].extend(_project_paint_reference_errors(root))
+
+ def _check_marker_contract(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Validate marker references against the native line-end contract."""
+ if _project_marker_errors is None:
+ result['warnings'].append(
+ 'Unable to import the shared marker validator; native export '
+ 'will still validate line-end markers.'
+ )
+ return
+ result['errors'].extend(_project_marker_errors(root))
+
+ def _check_clip_path_contract(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Validate image clip paths against the native picture geometry mapping."""
+ if _project_clip_path_errors is None:
+ result['errors'].append(
+ 'Unable to import the clip-path validator; cannot verify '
+ 'native picture geometry references'
+ )
+ return
+ result['errors'].extend(_project_clip_path_errors(root))
+
+ def _check_mask_contract(self, root: ET.Element, result: Dict) -> None:
+ """Reject SVG masks through the native exporter's shared validator."""
+ if _project_mask_errors is None:
+ result['errors'].append(
+ 'Unable to import the shared mask validator; cannot verify '
+ 'that native PPTX export will preserve all visible effects'
+ )
+ return
+ result['errors'].extend(_project_mask_errors(root))
+
+ def _check_filter_effects(self, root: ET.Element, result: Dict) -> None:
+ """Validate filters against the native shadow/glow approximation."""
+ if _project_filter_errors is None:
+ result['warnings'].append(
+ "Unable to import the shared filter validator; native export "
+ "will still validate shadow/glow filters."
+ )
+ return
+ result['errors'].extend(_project_filter_errors(root))
+
+ def _check_imported_effect_status(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Reject source PPTX effects that have no faithful SVG mapping."""
+ if _project_effect_status_errors is None:
+ if any(
+ elem.get(_EFFECT_STATUS_ATTR) is not None
+ or elem.get(_EFFECT_REASON_ATTR) is not None
+ for elem in root.iter()
+ ):
+ result['errors'].append(
+ 'Unable to import the PPTX effect-status validator; '
+ 'cannot verify imported effect fidelity'
+ )
+ return
+ result['errors'].extend(_project_effect_status_errors(root))
+
+ def _check_gradient_interfaces(self, root: ET.Element, result: Dict) -> None:
+ """Validate the normalized native gradient authoring interface."""
+ if (
+ _project_gradient_errors is None
+ or _project_gradient_geometry_errors is None
+ ):
+ result['warnings'].append(
+ "Unable to import the shared gradient validator; native export "
+ "will still validate gradient definitions."
+ )
+ return
+ gradient_errors = set(_project_gradient_errors(root))
+ gradient_errors.update(_project_gradient_geometry_errors(root))
+ if (
+ _expand_local_use_references is not None
+ and _UseExpansionError is not None
+ ):
+ expanded_root = copy.deepcopy(root)
+ try:
+ _expand_local_use_references(expanded_root)
+ except _UseExpansionError:
+ # The local-reference check owns the actionable diagnostic.
+ pass
+ else:
+ gradient_errors.update(
+ _project_gradient_geometry_errors(expanded_root)
+ )
+ result['errors'].extend(sorted(gradient_errors))
+
+ def _check_geometry_length_values(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Reject invalid project geometry and advise the unitless spelling."""
+ if (
+ _format_project_geometry_length is None
+ or _is_canonical_project_geometry_length is None
+ or _iter_project_geometry_lengths is None
+ or _parse_project_geometry_length is None
+ ):
+ result['warnings'].append(
+ "Unable to import svg_to_pptx geometry length validators; "
+ "native export will still validate project geometry."
+ )
+ return
+
+ errors: set[str] = set()
+ recommendations: Counter[tuple[str, str, str]] = Counter()
+ examples: Dict[tuple[str, str, str], List[str]] = defaultdict(list)
+
+ for elem, attribute, raw, source in _iter_project_geometry_lengths(root):
+ label = f'{_element_label(elem)} {source}'
+ try:
+ value = _parse_project_geometry_length(raw, attribute)
+ except ValueError as exc:
+ errors.add(f"{label} {attribute}={raw!r}: {exc}")
+ continue
+ if _is_canonical_project_geometry_length(raw):
+ continue
+ normalized = _format_project_geometry_length(value)
+ key = (attribute, raw, normalized)
+ recommendations[key] += 1
+ if label not in examples[key] and len(examples[key]) < 3:
+ examples[key].append(label)
+
+ result['errors'].extend(sorted(errors))
+ for (attribute, raw, normalized), count in sorted(recommendations.items()):
+ shown_examples = ', '.join(examples[(attribute, raw, normalized)])
+ result['warnings'].append(
+ f"Recommendation: project geometry {attribute}={raw!r} is "
+ f"converter-compatible in {count} location(s) ({shown_examples}); "
+ f"generated SVG should prefer the unitless px spelling "
+ f'{attribute}="{normalized}". No change is required for export.'
+ )
+
+ def _check_stroke_style_values(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Reject invalid line styles and advise project-canonical spellings."""
+ helpers = (
+ _format_project_geometry_length,
+ _is_canonical_project_geometry_length,
+ _iter_project_stroke_styles,
+ _noncanonical_stroke_dash_numbers,
+ _parse_project_geometry_length,
+ _parse_project_stroke_dasharray,
+ _parse_project_stroke_enum,
+ _project_stroke_style_errors,
+ )
+ if any(helper is None for helper in helpers):
+ result['warnings'].append(
+ "Unable to import svg_to_pptx line-style validators; native "
+ "export will still validate line-presentation syntax."
+ )
+ return
+
+ result['errors'].extend(_project_stroke_style_errors(root))
+ recommendations: Counter[tuple[str, str, str, str]] = Counter()
+ examples: Dict[tuple[str, str, str, str], List[str]] = defaultdict(list)
+
+ for elem, attribute, raw, source in _iter_project_stroke_styles(root):
+ label = f'{_element_label(elem)} {source}'
+ normalized = None
+ reason = ''
+
+ if attribute == 'stroke-dasharray':
+ try:
+ parsed = _parse_project_stroke_dasharray(
+ raw,
+ allow_zero_gap=True,
+ )
+ noncanonical = _noncanonical_stroke_dash_numbers(raw)
+ except ValueError:
+ continue
+ if parsed is None:
+ if raw != 'none':
+ normalized = 'none'
+ reason = 'remove surrounding whitespace'
+ else:
+ preset, values = parsed
+ longer_custom = preset is None and len(values) > 2
+ if noncanonical or longer_custom or raw != raw.strip():
+ kept_values = values[:2] if longer_custom else values
+ normalized = ' '.join(
+ _format_project_geometry_length(value)
+ for value in kept_values
+ )
+ reasons = []
+ if noncanonical:
+ reasons.append('use ordinary decimal numbers')
+ if longer_custom:
+ reasons.append(
+ 'make the first-pair export normalization explicit'
+ )
+ if raw != raw.strip():
+ reasons.append('remove surrounding whitespace')
+ reason = '; '.join(reasons)
+ elif attribute == 'stroke-dashoffset':
+ try:
+ value = _parse_project_geometry_length(raw, attribute)
+ except ValueError:
+ continue
+ if not _is_canonical_project_geometry_length(raw):
+ normalized = _format_project_geometry_length(value)
+ reason = 'use the unitless px spelling'
+ else:
+ try:
+ value = _parse_project_stroke_enum(attribute, raw)
+ except ValueError:
+ continue
+ if raw != value:
+ normalized = value
+ reason = 'remove surrounding whitespace'
+
+ if normalized is None:
+ continue
+ key = (attribute, raw, normalized, reason)
+ recommendations[key] += 1
+ if label not in examples[key] and len(examples[key]) < 3:
+ examples[key].append(label)
+
+ for (attribute, raw, normalized, reason), count in sorted(
+ recommendations.items()
+ ):
+ shown_examples = ', '.join(
+ examples[(attribute, raw, normalized, reason)]
+ )
+ result['warnings'].append(
+ f"Recommendation: line style {attribute}={raw!r} is "
+ f"converter-compatible in {count} location(s) "
+ f"({shown_examples}); generated SVG should prefer "
+ f'{attribute}="{normalized}" to {reason}. No change is '
+ "required for export."
+ )
+
+ def _check_image_aspect_ratio_values(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Reject ambiguous image fit/crop values and advise canonical forms."""
+ helpers = (
+ _format_project_image_aspect_ratio,
+ _iter_project_image_aspect_ratios,
+ _parse_project_image_aspect_ratio,
+ _project_image_aspect_ratio_errors,
+ )
+ if any(helper is None for helper in helpers):
+ result['warnings'].append(
+ "Unable to import svg_to_pptx image aspect-ratio validators; "
+ "native export will still validate image fit/crop syntax."
+ )
+ return
+
+ result['errors'].extend(_project_image_aspect_ratio_errors(root))
+ recommendations: Counter[tuple[str, str]] = Counter()
+ examples: Dict[tuple[str, str], List[str]] = defaultdict(list)
+
+ for elem, raw in _iter_project_image_aspect_ratios(root):
+ try:
+ align, mode = _parse_project_image_aspect_ratio(raw)
+ except ValueError:
+ continue
+ normalized = _format_project_image_aspect_ratio(align, mode)
+ if raw == normalized:
+ continue
+ key = (raw, normalized)
+ recommendations[key] += 1
+ label = _element_label(elem)
+ if label not in examples[key] and len(examples[key]) < 3:
+ examples[key].append(label)
+
+ for (raw, normalized), count in sorted(recommendations.items()):
+ shown_examples = ', '.join(examples[(raw, normalized)])
+ result['warnings'].append(
+ f"Recommendation: image preserveAspectRatio={raw!r} is "
+ f"converter-compatible in {count} location(s) "
+ f"({shown_examples}); generated SVG should prefer "
+ f'preserveAspectRatio="{normalized}". No change is required '
+ "for export."
+ )
+
+ def _check_nested_svg_crop_contract(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Reserve nested SVG for the imported picture-crop transport."""
+ if _project_nested_svg_crop_errors is None:
+ result['errors'].append(
+ 'Unable to import the nested SVG crop validator; cannot '
+ 'verify imported picture-crop wrappers'
+ )
+ return
+ result['errors'].extend(_project_nested_svg_crop_errors(root))
+
+ def _check_image_contract(
+ self,
+ root: ET.Element,
+ svg_path: Path,
+ result: Dict,
+ ) -> None:
+ """Validate picture frames, references, and bytes before export."""
+ if _project_image_errors is None:
+ result['errors'].append(
+ 'Unable to import the image validator; cannot verify picture '
+ 'frames or media'
+ )
+ return
+ _working_root, _parent_by_id, images = self._visible_image_elements(root)
+ for image in images:
+ result['errors'].extend(
+ _project_image_errors(
+ image,
+ svg_path.parent,
+ allow_template_placeholders=self.template_mode,
+ )
+ )
+
+ def _check_freeform_geometry_values(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Reject malformed path/points syntax and advise decimal spelling."""
+ helpers = (
+ _format_project_geometry_length,
+ _iter_project_freeform_geometry,
+ _noncanonical_path_numbers,
+ _noncanonical_points_numbers,
+ )
+ if any(helper is None for helper in helpers):
+ result['warnings'].append(
+ "Unable to import svg_to_pptx freeform geometry validators; "
+ "native export will still validate path and points syntax."
+ )
+ return
+
+ errors: set[str] = set()
+ recommendations: Counter[tuple[str, str, str]] = Counter()
+ examples: Dict[tuple[str, str, str], List[str]] = defaultdict(list)
+
+ for elem, attribute, raw, min_points in _iter_project_freeform_geometry(root):
+ label = _element_label(elem)
+ try:
+ if raw is None:
+ tag = _local_name(elem)
+ raise ValueError(f'<{tag}> requires {attribute}')
+ if attribute == 'd':
+ compatible_numbers = _noncanonical_path_numbers(raw)
+ else:
+ required_points = min_points or 2
+ compatible_numbers = _noncanonical_points_numbers(
+ raw,
+ min_points=required_points,
+ )
+ except ValueError as exc:
+ errors.add(f'{label} {attribute}: {exc}')
+ continue
+
+ for number in compatible_numbers:
+ normalized = _format_project_geometry_length(float(number))
+ key = (attribute, number, normalized)
+ recommendations[key] += 1
+ if label not in examples[key] and len(examples[key]) < 3:
+ examples[key].append(label)
+
+ result['errors'].extend(sorted(errors))
+ for (attribute, raw, normalized), count in sorted(recommendations.items()):
+ shown_examples = ', '.join(examples[(attribute, raw, normalized)])
+ result['warnings'].append(
+ f"Recommendation: freeform geometry {attribute} numeric token "
+ f"{raw!r} is converter-compatible in {count} occurrence(s) "
+ f"({shown_examples}); generated SVG should prefer the ordinary "
+ f"decimal spelling {normalized!r}. No change is required for export."
+ )
+
+ def _check_transform_values(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Reject invalid transforms and advise ordinary decimal spelling."""
+ helpers = (
+ _format_project_geometry_length,
+ _iter_project_transforms,
+ _noncanonical_transform_numbers,
+ _project_transform_errors,
+ )
+ if any(helper is None for helper in helpers):
+ result['warnings'].append(
+ "Unable to import svg_to_pptx transform validators; "
+ "native export will still validate transform syntax."
+ )
+ return
+
+ transform_errors = set(_project_transform_errors(root))
+ if (
+ not transform_errors
+ and _expand_local_use_references is not None
+ and _UseExpansionError is not None
+ ):
+ expanded_root = copy.deepcopy(root)
+ try:
+ _expand_local_use_references(expanded_root)
+ except _UseExpansionError:
+ # The local-reference check owns the actionable diagnostic.
+ pass
+ else:
+ transform_errors.update(_project_transform_errors(expanded_root))
+ result['errors'].extend(
+ f'Invalid SVG transform: {error}'
+ for error in sorted(transform_errors)
+ )
+
+ recommendations: Counter[tuple[str, str]] = Counter()
+ examples: Dict[tuple[str, str], List[str]] = defaultdict(list)
+ for elem, raw in _iter_project_transforms(root):
+ try:
+ compatible_numbers = _noncanonical_transform_numbers(raw)
+ except ValueError:
+ continue
+ for number in compatible_numbers:
+ normalized = _format_project_geometry_length(float(number))
+ key = (number, normalized)
+ recommendations[key] += 1
+ label = _element_label(elem)
+ if label not in examples[key] and len(examples[key]) < 3:
+ examples[key].append(label)
+
+ for (raw, normalized), count in sorted(recommendations.items()):
+ shown_examples = ', '.join(examples[(raw, normalized)])
+ result['warnings'].append(
+ f"Recommendation: transform numeric token {raw!r} is "
+ f"converter-compatible in {count} occurrence(s) "
+ f"({shown_examples}); generated SVG should prefer the ordinary "
+ f"decimal spelling {normalized!r}. No change is required for export."
+ )
+
+ def _check_font_size_values(self, content: str, result: Dict):
+ """Keep supported font-size units compatible and recommend unitless px."""
+ canonical_re = re.compile(r'^(?:\d+(?:\.\d+)?|\.\d+)$')
+ values = set()
+
+ for match in re.finditer(r'\bfont-size\s*=\s*(["\'])(.*?)\1', content, re.IGNORECASE):
+ values.add(match.group(2).strip())
+
+ for match in re.finditer(r'\bfont-size\s*:\s*([^;"\']+)', content, re.IGNORECASE):
+ values.add(match.group(1).strip())
+
+ if _parse_export_length is None:
+ result['warnings'].append(
+ "Unable to import svg_to_pptx length parser; skipped font-size syntax check"
+ )
+ return
+
+ unsupported = set()
+ drawingml_out_of_range = set()
+ compatible_noncanonical = set()
+ for raw in values:
+ try:
+ parsed_px = _parse_export_length(raw, math.nan, font_size=16)
+ except (TypeError, ValueError):
+ unsupported.add(raw)
+ continue
+ if not math.isfinite(parsed_px) or parsed_px < 0:
+ unsupported.add(raw)
+ continue
+ if _font_px_to_hpt is not None:
+ try:
+ _font_px_to_hpt(parsed_px)
+ except ValueError:
+ drawingml_out_of_range.add(raw)
+ continue
+ if not canonical_re.fullmatch(raw):
+ compatible_noncanonical.add(raw)
+
+ if unsupported:
+ shown_values = sorted(unsupported)
+ shown = ', '.join(shown_values[:5])
+ more = len(shown_values) - 5
+ suffix = f" (+{more} more)" if more > 0 else ""
+ result['errors'].append(
+ f"Unsupported font-size value(s): {shown}{suffix}. Use a finite "
+ "non-negative SVG length supported by svg_to_pptx."
+ )
+
+ if drawingml_out_of_range:
+ shown_values = sorted(drawingml_out_of_range)
+ shown = ', '.join(shown_values[:5])
+ more = len(shown_values) - 5
+ suffix = f" (+{more} more)" if more > 0 else ""
+ result['errors'].append(
+ f"font-size value(s) {shown}{suffix} are outside the DrawingML "
+ f"range sz={_DRAWINGML_TEXT_FONT_SIZE_MIN}.."
+ f"{_DRAWINGML_TEXT_FONT_SIZE_MAX} (1..4000pt); PowerPoint would "
+ "repair the exported file. Do not use tiny transparent text as "
+ "a placeholder carrier: leave a text carrier blank or use the "
+ "composite object proxy contract."
+ )
+
+ if compatible_noncanonical:
+ shown_values = sorted(compatible_noncanonical)
+ shown = ', '.join(shown_values[:5])
+ more = len(shown_values) - 5
+ suffix = f" (+{more} more)" if more > 0 else ""
+ result['warnings'].append(
+ f"Recommendation: font-size value(s) {shown}{suffix} are "
+ "converter-compatible; generated SVG should prefer unitless px "
+ "values such as font-size=\"28\". No change is required for export."
+ )
+
+ def _check_fonts(self, content: str, result: Dict):
+ """Check font usage.
+
+ PPTX stores concrete typefaces per run with no CSS fallback. The
+ converter resolves each SVG font stack to exported latin / EA typefaces;
+ validate those exported values rather than the visual-preview tail.
+ """
+ font_matches = self._font_family_values(content)
+
+ if not font_matches:
+ return
+
+ result['info']['fonts'] = sorted(set(font_matches))
+ if _unsafe_exported_font_faces is None:
+ result['warnings'].append(
+ "Unable to import svg_to_pptx font resolver; skipped exported-font safety check"
+ )
+ return
+
+ for font_family in font_matches:
+ unsafe = [
+ f"{role}={family}"
+ for role, family in _unsafe_exported_font_faces(font_family).items()
+ ]
+ if unsafe:
+ result['warnings'].append(
+ "Font stack exports non-PPT-safe typeface(s) to PPTX "
+ f"({', '.join(unsafe)}): {font_family}"
+ )
+ break
+
+ @staticmethod
+ def _font_family_values(content: str) -> List[str]:
+ """Extract SVG font-family values from attributes and inline styles."""
+ return SVGQualityChecker._svg_property_values(content, 'font-family')
+
+ @staticmethod
+ def _svg_property_values(content: str, property_name: str) -> List[str]:
+ """Extract a SVG property from direct attributes and inline styles."""
+ values: List[str] = []
+ attr_re = re.compile(
+ rf'\b{re.escape(property_name)}\s*=\s*(["\'])(.*?)\1',
+ re.IGNORECASE | re.DOTALL,
+ )
+ for match in attr_re.finditer(content):
+ values.append(html.unescape(match.group(2)).strip())
+
+ for match in re.finditer(r'\bstyle\s*=\s*(["\'])(.*?)\1', content, re.IGNORECASE | re.DOTALL):
+ style_value = html.unescape(match.group(2))
+ for part in style_value.split(';'):
+ if ':' not in part:
+ continue
+ name, value = part.split(':', 1)
+ if name.strip().lower() == property_name.lower():
+ values.append(value.strip())
+ return [value for value in values if value]
+
+ def _check_text_elements(self, content: str, root: ET.Element, result: Dict):
+ """Check text elements and wrapping methods"""
+ # Count text and tspan elements
+ text_count = content.count('<text')
+ tspan_count = content.count('<tspan')
+
+ result['info']['text_elements'] = text_count
+ result['info']['tspan_elements'] = tspan_count
+
+ self._check_module_bounds_contract(root, result)
+ self._check_text_output_geometry(root, result)
+ self._check_root_module_text_bounds(root, result)
+ self._check_fragmented_paragraph_text(root, result)
+ self._check_unmergeable_leading_text(root, result)
+ self._check_nested_positional_tspans(root, result)
+
+ def _check_nested_positional_tspans(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Reject nested baseline jumps that DrawingML runs cannot represent."""
+ if _nested_positional_tspan_errors is None:
+ return
+ result['errors'].extend(_nested_positional_tspan_errors(root))
+
+ @classmethod
+ def _single_line_text_runs(
+ cls,
+ text_el: ET.Element,
+ ) -> List[Tuple[ET.Element, str]] | None:
+ """Return normalized inline runs, or ``None`` for positioned text."""
+ if (
+ _normalize_project_text_segments is None
+ or _resolve_project_xml_space is None
+ ):
+ return None
+ raw_runs: List[Tuple[ET.Element, str, str]] = []
+
+ def append_run(owner: ET.Element, raw: str, xml_space: str) -> None:
+ if raw:
+ raw_runs.append((owner, xml_space, raw))
+
+ def collect(container: ET.Element, inherited_xml_space: str) -> bool:
+ try:
+ xml_space = _resolve_project_xml_space(
+ container,
+ inherited_xml_space,
+ )
+ except ValueError:
+ return False
+ if container.text:
+ append_run(container, container.text, xml_space)
+ for child in list(container):
+ if not cls._is_tspan(child):
+ return False
+ if any(child.get(name) is not None for name in ('x', 'y', 'dx', 'dy')):
+ return False
+ if any(
+ name.startswith('data-paragraph-')
+ for name in child.attrib
+ ):
+ return False
+ if not collect(child, xml_space):
+ return False
+ if child.tail:
+ append_run(container, child.tail, xml_space)
+ return True
+
+ if not collect(text_el, 'default'):
+ return None
+ normalized = _normalize_project_text_segments([
+ (xml_space, raw)
+ for _owner, xml_space, raw in raw_runs
+ ])
+ return [
+ (raw_runs[index][0], text)
+ for index, text in normalized
+ ]
+
+ @staticmethod
+ def _unchanged_txbody_group_ids(
+ root: ET.Element,
+ ) -> set[int]:
+ """Return imported shape groups whose original text body will survive."""
+ if _preserved_native_text_body is None:
+ return set()
+ unchanged: set[int] = set()
+ for group in root.iter(f'{{{SVG_NS}}}g'):
+ try:
+ if _preserved_native_text_body(
+ group,
+ trust_runtime_snapshot=False,
+ ) is not None:
+ unchanged.add(id(group))
+ except _SvgNativeConversionError:
+ # The dedicated txBody contract check owns the diagnostic.
+ continue
+ return unchanged
+
+ @staticmethod
+ def _check_preserved_txbody_contract(
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Validate imported txBody payloads independently of text geometry."""
+ if _preserved_native_text_body is None:
+ return
+ errors: set[str] = set()
+ for group in root.iter(f'{{{SVG_NS}}}g'):
+ try:
+ _preserved_native_text_body(
+ group,
+ trust_runtime_snapshot=False,
+ )
+ except _SvgNativeConversionError as exc:
+ errors.add(
+ f'{_element_label(group)} cannot preserve source '
+ f'txBody: {exc}'
+ )
+ result['errors'].extend(sorted(errors))
+
+ @staticmethod
+ def _has_ancestor_id(
+ elem: ET.Element,
+ parent_by_id: Dict[int, ET.Element],
+ ancestor_ids: set[int],
+ ) -> bool:
+ current = parent_by_id.get(id(elem))
+ while current is not None:
+ if id(current) in ancestor_ids:
+ return True
+ current = parent_by_id.get(id(current))
+ return False
+
+ @classmethod
+ def _resolved_single_line_text_runs(
+ cls,
+ text_el: ET.Element,
+ parent_by_id: Dict[int, ET.Element],
+ font_sizes: Dict[int, float],
+ letter_spacings: Dict[int, float],
+ ) -> List[Dict] | None:
+ """Resolve the same run metrics used by generated text-frame sizing."""
+ source_runs = cls._single_line_text_runs(text_el)
+ if source_runs is None:
+ return None
+ resolved: List[Dict] = []
+ for owner, text in source_runs:
+ raw_weight = (
+ _effective_presentation_value(
+ owner,
+ 'font-weight',
+ parent_by_id,
+ )
+ or 'normal'
+ ).strip().lower()
+ weight = _parse_project_font_weight(raw_weight).canonical
+ family = (
+ _effective_presentation_value(
+ owner,
+ 'font-family',
+ parent_by_id,
+ )
+ or ''
+ )
+ opacity_chain: List[str] = []
+ current: ET.Element | None = owner
+ while current is not None:
+ style_values = (
+ _parse_inline_style(current.get('style'))
+ if _parse_inline_style is not None else {}
+ )
+ raw_opacity = style_values.get('opacity')
+ if raw_opacity is None:
+ raw_opacity = current.get('opacity')
+ if raw_opacity is not None:
+ opacity_chain.append(raw_opacity.strip())
+ current = parent_by_id.get(id(current))
+ resolved.append({
+ 'owner': owner,
+ 'text': text,
+ 'font_size': font_sizes[id(owner)],
+ 'font_weight': weight,
+ 'font_family': family,
+ 'letter_spacing': letter_spacings[id(owner)],
+ 'font_style': _effective_presentation_value(
+ owner,
+ 'font-style',
+ parent_by_id,
+ ) or 'normal',
+ 'text_decoration': _effective_presentation_value(
+ owner,
+ 'text-decoration',
+ parent_by_id,
+ ) or 'none',
+ 'fill_raw': _effective_presentation_value(
+ owner,
+ 'fill',
+ parent_by_id,
+ ) or '#000000',
+ 'fill_opacity': _effective_presentation_value(
+ owner,
+ 'fill-opacity',
+ parent_by_id,
+ ) or '1',
+ 'stroke_raw': _effective_presentation_value(
+ owner,
+ 'stroke',
+ parent_by_id,
+ ) or 'none',
+ 'stroke_width': _effective_presentation_value(
+ owner,
+ 'stroke-width',
+ parent_by_id,
+ ) or '1',
+ 'stroke_opacity': _effective_presentation_value(
+ owner,
+ 'stroke-opacity',
+ parent_by_id,
+ ) or '1',
+ 'opacity_chain': tuple(reversed(opacity_chain)),
+ })
+ return cls._coalesce_checker_text_runs(resolved)
+
+ @staticmethod
+ def _coalesce_checker_text_runs(runs: List[Dict]) -> List[Dict]:
+ """Join only runs whose resolved source styles are provably equal."""
+ if _detect_text_lang is None:
+ return runs
+ style_keys = (
+ 'font_size',
+ 'font_weight',
+ 'font_family',
+ 'letter_spacing',
+ 'font_style',
+ 'text_decoration',
+ 'fill_raw',
+ 'fill_opacity',
+ 'stroke_raw',
+ 'stroke_width',
+ 'stroke_opacity',
+ 'opacity_chain',
+ )
+
+ def signature(run: Dict) -> Tuple:
+ return (
+ _detect_text_lang(str(run.get('text', ''))),
+ *(run.get(key) for key in style_keys),
+ )
+
+ merged: List[Dict] = []
+ previous_signature: Tuple | None = None
+ for run in runs:
+ current_signature = signature(run)
+ if merged and current_signature == previous_signature:
+ candidate = {
+ **merged[-1],
+ 'text': (
+ str(merged[-1].get('text', ''))
+ + str(run.get('text', ''))
+ ),
+ }
+ candidate_signature = signature(candidate)
+ if candidate_signature == previous_signature:
+ merged[-1] = candidate
+ previous_signature = candidate_signature
+ continue
+ merged.append(run)
+ previous_signature = current_signature
+ return merged
+
+ def _check_text_output_geometry(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Reject measurable run advances or frames with non-positive geometry."""
+ helpers = (
+ _drawingml_text_frame_width_emu,
+ _estimate_single_line_text_frame_width,
+ _parse_project_font_weight,
+ _resolve_project_font_sizes,
+ _resolve_project_letter_spacings,
+ _validate_single_line_text_run_advances,
+ )
+ if any(helper is None for helper in helpers):
+ return
+ try:
+ font_sizes = _resolve_project_font_sizes(root)
+ letter_spacings = _resolve_project_letter_spacings(root, font_sizes)
+ except ValueError:
+ return
+
+ parent_by_id = {
+ id(child): parent
+ for parent in root.iter()
+ for child in list(parent)
+ }
+ unchanged_groups = self._unchanged_txbody_group_ids(root)
+ errors: List[str] = []
+ for text_el in root.iter(f'{{{SVG_NS}}}text'):
+ chain: List[ET.Element] = []
+ current: ET.Element | None = text_el
+ while current is not None:
+ chain.append(current)
+ current = parent_by_id.get(id(current))
+ if any(
+ _local_name(current) in _NON_VISUAL_SVG_TAGS
+ for current in chain
+ ):
+ continue
+ if self._has_ancestor_id(text_el, parent_by_id, unchanged_groups):
+ continue
+ try:
+ runs = self._resolved_single_line_text_runs(
+ text_el,
+ parent_by_id,
+ font_sizes,
+ letter_spacings,
+ )
+ if not runs:
+ continue
+ if not ''.join(str(run['text']) for run in runs).strip():
+ continue
+ text_width = _estimate_single_line_text_frame_width(runs)
+ ext_cx = _drawingml_text_frame_width_emu(
+ text_width,
+ font_sizes[id(text_el)],
+ )
+ except (KeyError, TypeError, ValueError):
+ continue
+ if ext_cx < 1:
+ errors.append(
+ f'{_element_label(text_el)} negative letter-spacing '
+ 'produces a non-positive DrawingML text-frame extent '
+ f'(cx={ext_cx})'
+ )
+ continue
+ try:
+ _validate_single_line_text_run_advances(runs)
+ except ValueError as exc:
+ errors.append(f'{_element_label(text_el)} {exc}')
+ result['errors'].extend(errors)
+
+ @classmethod
+ def _positioned_text_lines(
+ cls,
+ text_el: ET.Element,
+ parent_by_id: Dict[int, ET.Element],
+ font_sizes: Dict[int, float],
+ letter_spacings: Dict[int, float],
+ ) -> List[Tuple[ET.Element, float, float, List[Dict], float]] | None:
+ """Resolve direct positioned tspans into estimable visual lines."""
+ if _parse_project_geometry_length is None:
+ return None
+ children = list(text_el)
+ if not children or (text_el.text or '').strip():
+ return None
+ if any(
+ not cls._is_tspan(child)
+ or not cls._is_line_tspan(child)
+ or child.get('x') is None
+ or (child.tail or '').strip()
+ for child in children
+ ):
+ return None
+
+ try:
+ current_y = _parse_project_geometry_length(
+ text_el.get('y') or '0',
+ 'y',
+ )
+ except ValueError:
+ return None
+
+ lines: List[Tuple[ET.Element, float, float, List[Dict], float]] = []
+ for child in children:
+ try:
+ line_x = _parse_project_geometry_length(child.get('x'), 'x')
+ line_y = (
+ _parse_project_geometry_length(child.get('y'), 'y')
+ if child.get('y') is not None
+ else current_y
+ )
+ if child.get('dx') is not None:
+ line_x += _parse_project_geometry_length(
+ child.get('dx'),
+ 'dx',
+ )
+ if child.get('dy') is not None:
+ line_y += _parse_project_geometry_length(
+ child.get('dy'),
+ 'dy',
+ )
+ runs = cls._resolved_single_line_text_runs(
+ child,
+ parent_by_id,
+ font_sizes,
+ letter_spacings,
+ )
+ except (KeyError, TypeError, ValueError):
+ return None
+ current_y = line_y
+ if not runs:
+ continue
+ try:
+ font_size = max(float(run['font_size']) for run in runs)
+ except (KeyError, TypeError, ValueError):
+ return None
+ lines.append((child, line_x, line_y, runs, font_size))
+ return lines or None
+
+ @classmethod
+ def _estimated_text_line_bounds(
+ cls,
+ line_el: ET.Element,
+ x: float,
+ y: float,
+ runs: List[Dict],
+ font_size: float,
+ parent_by_id: Dict[int, ET.Element],
+ ) -> Tuple[float, float, float, float] | None:
+ """Estimate one line's transformed visible bounds in SVG coordinates."""
+ if any(helper is None for helper in (
+ _estimate_single_line_text_frame_width,
+ _IDENTITY_MATRIX,
+ _matrix_multiply,
+ _parse_project_text_anchor,
+ _parse_transform_matrix,
+ _transform_point,
+ )):
+ return None
+ try:
+ width = float(_estimate_single_line_text_frame_width(runs))
+ raw_anchor = (
+ _effective_presentation_value(
+ line_el,
+ 'text-anchor',
+ parent_by_id,
+ )
+ or 'start'
+ ).strip().lower()
+ anchor = _parse_project_text_anchor(raw_anchor).value
+ except (TypeError, ValueError):
+ return None
+ if not all(math.isfinite(value) for value in (x, y, width, font_size)):
+ return None
+ if width <= 0 or font_size <= 0:
+ return None
+
+ if anchor == 'middle':
+ left = x - width / 2
+ right = x + width / 2
+ elif anchor == 'end':
+ left = x - width
+ right = x
+ elif anchor == 'start':
+ left = x
+ right = x + width
+ else:
+ return None
+ top = y - font_size * 0.85
+ bottom = y + font_size * 0.35
+
+ return cls._transformed_rect_bounds(
+ line_el,
+ (left, top, right - left, bottom - top),
+ parent_by_id,
+ )
+
+ @classmethod
+ def _estimated_text_bounds(
+ cls,
+ text_el: ET.Element,
+ parent_by_id: Dict[int, ET.Element],
+ font_sizes: Dict[int, float],
+ letter_spacings: Dict[int, float],
+ ) -> Tuple[float, float, float, float] | None:
+ """Estimate one single- or multi-line text carrier's visual bounds."""
+ lines: List[Tuple[ET.Element, float, float, List[Dict], float]] | None
+ try:
+ runs = cls._resolved_single_line_text_runs(
+ text_el,
+ parent_by_id,
+ font_sizes,
+ letter_spacings,
+ )
+ except (KeyError, TypeError, ValueError):
+ return None
+ if runs:
+ try:
+ lines = [(
+ text_el,
+ _parse_project_geometry_length(text_el.get('x') or '0', 'x'),
+ _parse_project_geometry_length(text_el.get('y') or '0', 'y'),
+ runs,
+ max(float(run['font_size']) for run in runs),
+ )]
+ except (KeyError, TypeError, ValueError):
+ return None
+ else:
+ lines = cls._positioned_text_lines(
+ text_el,
+ parent_by_id,
+ font_sizes,
+ letter_spacings,
+ )
+ if not lines:
+ return None
+
+ bounds = [
+ cls._estimated_text_line_bounds(
+ line_el,
+ x,
+ y,
+ line_runs,
+ font_size,
+ parent_by_id,
+ )
+ for line_el, x, y, line_runs, font_size in lines
+ ]
+ resolved = [item for item in bounds if item is not None]
+ if not resolved:
+ return None
+ return (
+ min(item[0] for item in resolved),
+ min(item[1] for item in resolved),
+ max(item[2] for item in resolved),
+ max(item[3] for item in resolved),
+ )
+
+ @staticmethod
+ def _accumulated_transform_matrix(
+ element: ET.Element,
+ parent_by_id: Dict[int, ET.Element],
+ ):
+ """Return the element-to-root transform matrix when available."""
+ if any(helper is None for helper in (
+ _IDENTITY_MATRIX,
+ _matrix_multiply,
+ _parse_transform_matrix,
+ )):
+ return None
+ chain: List[ET.Element] = []
+ current: ET.Element | None = element
+ while current is not None:
+ chain.append(current)
+ current = parent_by_id.get(id(current))
+ matrix = _IDENTITY_MATRIX
+ try:
+ for current in reversed(chain):
+ raw_transform = current.get('transform')
+ if raw_transform:
+ matrix = _matrix_multiply(
+ matrix,
+ _parse_transform_matrix(raw_transform),
+ )
+ except (TypeError, ValueError):
+ return None
+ return matrix
+
+ @classmethod
+ def _transformed_rect_bounds(
+ cls,
+ element: ET.Element,
+ bounds: Tuple[float, float, float, float],
+ parent_by_id: Dict[int, ET.Element],
+ ) -> Tuple[float, float, float, float] | None:
+ """Transform one local rectangle into root SVG coordinates."""
+ if _transform_point is None:
+ return None
+ matrix = cls._accumulated_transform_matrix(element, parent_by_id)
+ if matrix is None:
+ return None
+ x, y, width, height = bounds
+ try:
+ corners = [
+ _transform_point(matrix, corner_x, corner_y)
+ for corner_x, corner_y in (
+ (x, y),
+ (x + width, y),
+ (x + width, y + height),
+ (x, y + height),
+ )
+ ]
+ except (TypeError, ValueError):
+ return None
+ xs = [point[0] for point in corners]
+ ys = [point[1] for point in corners]
+ return min(xs), min(ys), max(xs), max(ys)
+
+ @classmethod
+ def _transformed_rect_edge_lengths(
+ cls,
+ element: ET.Element,
+ bounds: Tuple[float, float, float, float],
+ parent_by_id: Dict[int, ET.Element],
+ ) -> Tuple[float, float] | None:
+ """Return frame-axis lengths after accumulated SVG transforms."""
+ if _transform_point is None:
+ return None
+ matrix = cls._accumulated_transform_matrix(element, parent_by_id)
+ if matrix is None:
+ return None
+ x, y, width, height = bounds
+ try:
+ origin = _transform_point(matrix, x, y)
+ width_end = _transform_point(matrix, x + width, y)
+ height_end = _transform_point(matrix, x, y + height)
+ except (TypeError, ValueError):
+ return None
+ rendered_w = math.hypot(
+ width_end[0] - origin[0],
+ width_end[1] - origin[1],
+ )
+ rendered_h = math.hypot(
+ height_end[0] - origin[0],
+ height_end[1] - origin[1],
+ )
+ if rendered_w <= 0 or rendered_h <= 0:
+ return None
+ return rendered_w, rendered_h
+
+ @staticmethod
+ def _resolved_root_module_bounds(
+ group: ET.Element,
+ ) -> Tuple[str, Tuple[float, float, float, float]] | None:
+ """Return one root module's explicit boundary in root coordinates."""
+ raw = group.get(_BOUNDS_ATTR)
+ if raw is None:
+ return None
+ try:
+ x, y, width, height = _parse_positive_bounds(raw)
+ except ValueError:
+ return None
+ return _BOUNDS_ATTR, (x, y, x + width, y + height)
+
+ @staticmethod
+ def _bounds_overflow_metrics(
+ inner: Tuple[float, float, float, float],
+ outer: Tuple[float, float, float, float],
+ *,
+ tolerance: float = _BOUNDS_OVERFLOW_TOLERANCE,
+ ) -> Tuple[str, float, float] | None:
+ """Return overflow axes and ratios relative to the outer dimensions."""
+ left, top, right, bottom = inner
+ outer_left, outer_top, outer_right, outer_bottom = outer
+ left_overflow = max(outer_left - left, 0.0)
+ right_overflow = max(right - outer_right, 0.0)
+ top_overflow = max(outer_top - top, 0.0)
+ bottom_overflow = max(bottom - outer_bottom, 0.0)
+ horizontal = (
+ left_overflow > tolerance
+ or right_overflow > tolerance
+ )
+ vertical = (
+ top_overflow > tolerance
+ or bottom_overflow > tolerance
+ )
+ if not horizontal and not vertical:
+ return None
+
+ outer_width = outer_right - outer_left
+ outer_height = outer_bottom - outer_top
+ if outer_width <= 0.0 or outer_height <= 0.0:
+ return None
+ horizontal_ratio = (
+ max(left_overflow, right_overflow) / outer_width
+ if horizontal else 0.0
+ )
+ vertical_ratio = (
+ max(top_overflow, bottom_overflow) / outer_height
+ if vertical else 0.0
+ )
+ if horizontal and vertical:
+ axes = 'horizontal and vertical'
+ elif horizontal:
+ axes = 'horizontal'
+ else:
+ axes = 'vertical'
+ return axes, horizontal_ratio, vertical_ratio
+
+ @classmethod
+ def _record_bounds_overflow(
+ cls,
+ result: Dict,
+ *,
+ subject: str,
+ inner: Tuple[float, float, float, float],
+ container: str,
+ outer: Tuple[float, float, float, float],
+ repair: str,
+ ) -> None:
+ """Record a warning through 5% overflow and an error above it."""
+ metrics = cls._bounds_overflow_metrics(inner, outer)
+ if metrics is None:
+ return
+ axes, horizontal_ratio, vertical_ratio = metrics
+ overflow_ratio = max(horizontal_ratio, vertical_ratio)
+ exceeds_error_ratio = (
+ overflow_ratio > _BOUNDS_OVERFLOW_ERROR_RATIO
+ and not math.isclose(
+ overflow_ratio,
+ _BOUNDS_OVERFLOW_ERROR_RATIO,
+ rel_tol=0.0,
+ abs_tol=1e-9,
+ )
+ )
+ bucket = (
+ result['errors']
+ if exceeds_error_ratio
+ else result['warnings']
+ )
+ left, top, right, bottom = inner
+ outer_left, outer_top, outer_right, outer_bottom = outer
+ bucket.append(
+ f'{subject} exceeds {container} on the {axes} axis: '
+ f'content ({left:.1f}, {top:.1f})-({right:.1f}, '
+ f'{bottom:.1f}), container ({outer_left:.1f}, '
+ f'{outer_top:.1f})-({outer_right:.1f}, '
+ f'{outer_bottom:.1f}), overflow horizontal '
+ f'{horizontal_ratio:.1%}, vertical {vertical_ratio:.1%}; '
+ f'{repair}'
+ )
+
+ @staticmethod
+ def _is_hidden_element(
+ element: ET.Element,
+ parent_by_id: Dict[int, ET.Element],
+ ) -> bool:
+ """Return whether inherited display or visibility hides an element."""
+ current: ET.Element | None = element
+ while current is not None:
+ style_values = (
+ _parse_inline_style(current.get('style'))
+ if _parse_inline_style is not None
+ else {}
+ )
+ display = style_values.get('display')
+ if display is None:
+ display = current.get('display')
+ if display and display.strip().lower() == 'none':
+ return True
+ current = parent_by_id.get(id(current))
+ visibility = (
+ _effective_presentation_value(
+ element,
+ 'visibility',
+ parent_by_id,
+ )
+ or ''
+ ).strip().lower()
+ return visibility in {'hidden', 'collapse'}
+
+ @staticmethod
+ def _has_zero_opacity(
+ element: ET.Element,
+ parent_by_id: Dict[int, ET.Element],
+ ) -> bool:
+ """Return whether an element or ancestor has zero effective opacity."""
+ current: ET.Element | None = element
+ while current is not None:
+ style_values = (
+ _parse_inline_style(current.get('style'))
+ if _parse_inline_style is not None
+ else {}
+ )
+ raw = style_values.get('opacity')
+ if raw is None:
+ raw = current.get('opacity')
+ if raw is not None:
+ value = raw.strip()
+ try:
+ opacity = (
+ float(value[:-1]) / 100
+ if value.endswith('%')
+ else float(value)
+ )
+ except ValueError:
+ pass
+ else:
+ if opacity <= 0:
+ return True
+ current = parent_by_id.get(id(current))
+ return False
+
+ @classmethod
+ def _visible_image_elements(
+ cls,
+ root: ET.Element,
+ ) -> Tuple[ET.Element, Dict[int, ET.Element], List[ET.Element]]:
+ """Return rendered image instances after expanding static local uses."""
+ working_root = copy.deepcopy(root)
+ if (
+ _expand_local_use_references is not None
+ and _UseExpansionError is not None
+ ):
+ try:
+ _expand_local_use_references(working_root)
+ except _UseExpansionError:
+ # The local-reference validator owns the actionable failure.
+ working_root = copy.deepcopy(root)
+
+ parent_by_id = {
+ id(child): parent
+ for parent in working_root.iter()
+ for child in list(parent)
+ }
+ images = [
+ element
+ for element in working_root.iter(f'{{{SVG_NS}}}image')
+ if not cls._is_hidden_element(element, parent_by_id)
+ and not cls._has_non_visual_ancestor(
+ element,
+ working_root,
+ parent_by_id,
+ )
+ and not cls._has_zero_opacity(element, parent_by_id)
+ ]
+ return working_root, parent_by_id, images
+
+ @staticmethod
+ def _has_non_visual_ancestor(
+ element: ET.Element,
+ module: ET.Element,
+ parent_by_id: Dict[int, ET.Element],
+ ) -> bool:
+ """Return whether an element lives in a non-rendered module subtree."""
+ current: ET.Element | None = element
+ while current is not None and current is not module:
+ if _local_name(current) in _NON_VISUAL_SVG_TAGS:
+ return True
+ current = parent_by_id.get(id(current))
+ return False
+
+ def _check_module_bounds_contract(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Validate direct root module boundaries in the SVG canvas."""
+ parent_by_id = {
+ id(child): parent
+ for parent in root.iter()
+ for child in list(parent)
+ }
+ viewbox = _parse_viewbox_values(root.get('viewBox') or '')
+ canvas = None
+ if viewbox is not None:
+ x, y, width, height = viewbox
+ canvas = (x, y, x + width, y + height)
+
+ for element in root.iter():
+ if element.get(_BOUNDS_ATTR) is None:
+ continue
+ if _local_name(element) != 'g':
+ result['errors'].append(
+ f'{_element_label(element)} {_BOUNDS_ATTR} is valid '
+ 'only on <g> layout modules'
+ )
+
+ missing: List[str] = []
+ root_groups = [
+ child
+ for child in list(root)
+ if _local_name(child) == 'g'
+ ]
+ require_bounds = (
+ self.template_mode
+ or root.get('data-pptx-page-role') is not None
+ or any(
+ root.get(attribute) is not None
+ for attribute in _PPTX_ROOT_STRUCTURE_ATTRS
+ )
+ )
+ for group in root_groups:
+ if self._is_hidden_element(group, parent_by_id):
+ continue
+ raw_bounds = group.get(_BOUNDS_ATTR)
+ if raw_bounds is None:
+ missing.append(_element_label(group))
+ continue
+ try:
+ _parse_positive_bounds(raw_bounds)
+ except ValueError as exc:
+ result['errors'].append(
+ f'{_element_label(group)} {_BOUNDS_ATTR} {exc}'
+ )
+ continue
+
+ resolved = self._resolved_root_module_bounds(group)
+ if resolved is None or canvas is None:
+ continue
+ attribute, bounds = resolved
+ self._record_bounds_overflow(
+ result,
+ subject=f'{_element_label(group)} {attribute}',
+ inner=bounds,
+ container='canvas viewBox',
+ outer=canvas,
+ repair=(
+ 'keep the root module subcanvas inside the SVG viewBox'
+ ),
+ )
+
+ if missing:
+ sample = '; '.join(missing[:3])
+ suffix = '' if len(missing) <= 3 else f'; +{len(missing) - 3} more'
+ bucket = result['errors'] if require_bounds else result['warnings']
+ prefix = 'Detected' if require_bounds else 'Reference SVG: detected'
+ bucket.append(
+ f'{prefix} {len(missing)} visible root-level <g> '
+ f'module(s) without explicit {_BOUNDS_ATTR} '
+ f'({sample}{suffix}); every final-page/template root <g> declares '
+ 'its root-coordinate layout subcanvas even when it also carries '
+ 'data-pptx-frame or native chart/table coordinates'
+ )
+
+ def _check_root_module_text_bounds(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Grade visible text against its direct root module subcanvas."""
+ helpers = (
+ _estimate_single_line_text_frame_width,
+ _parse_project_font_weight,
+ _parse_project_geometry_length,
+ _parse_project_text_anchor,
+ _resolve_project_font_sizes,
+ _resolve_project_letter_spacings,
+ )
+ if any(helper is None for helper in helpers):
+ return
+ try:
+ font_sizes = _resolve_project_font_sizes(root)
+ letter_spacings = _resolve_project_letter_spacings(
+ root,
+ font_sizes,
+ )
+ except ValueError:
+ return
+
+ parent_by_id = {
+ id(child): parent
+ for parent in root.iter()
+ for child in list(parent)
+ }
+ unchanged_groups = self._unchanged_txbody_group_ids(root)
+ root_groups = [
+ child
+ for child in list(root)
+ if _local_name(child) == 'g'
+ ]
+ for module in root_groups:
+ if self._is_hidden_element(module, parent_by_id):
+ continue
+ resolved_module = self._resolved_root_module_bounds(module)
+ if resolved_module is None:
+ continue
+ boundary_attribute, boundary = resolved_module
+ for text_element in module.iter(f'{{{SVG_NS}}}text'):
+ if self._has_ancestor_id(
+ text_element,
+ parent_by_id,
+ unchanged_groups,
+ ):
+ continue
+ if self._has_non_visual_ancestor(
+ text_element,
+ module,
+ parent_by_id,
+ ):
+ continue
+ if self._is_hidden_element(text_element, parent_by_id):
+ continue
+ visible_text = ''.join(text_element.itertext())
+ if (
+ not visible_text.strip()
+ or ('{{' in visible_text and '}}' in visible_text)
+ ):
+ continue
+ estimated = self._estimated_text_bounds(
+ text_element,
+ parent_by_id,
+ font_sizes,
+ letter_spacings,
+ )
+ if estimated is None:
+ continue
+ self._record_bounds_overflow(
+ result,
+ subject=_element_label(text_element),
+ inner=estimated,
+ container=(
+ f'{_element_label(module)} {boundary_attribute}'
+ ),
+ outer=boundary,
+ repair=(
+ 'expand the root module bounds into available '
+ 'non-overlapping space; otherwise reflow the text'
+ ),
+ )
+
+ def _check_unmergeable_leading_text(self, root: ET.Element, result: Dict) -> None:
+ """Warn when leading text cannot be normalized into one PPT text frame."""
+ risky = []
+ for text_el in root.iter(f'{{{SVG_NS}}}text'):
+ if not (text_el.text or "").strip():
+ continue
+ children = list(text_el)
+ if not any(self._is_line_tspan(child) for child in children):
+ continue
+
+ reason = self._leading_text_normalizer_reject_reason(text_el)
+ if reason is not None:
+ risky.append(reason)
+
+ if risky:
+ sample = '; '.join(risky[:3])
+ suffix = '' if len(risky) <= 3 else f"; +{len(risky) - 3} more"
+ result['warnings'].append(
+ "Detected multi-line <text> with leading direct text that cannot "
+ f"be normalized into one PPT text frame ({sample}{suffix})"
+ )
+
+ def _check_fragmented_paragraph_text(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Warn on high-confidence prose lines split into sibling text frames."""
+ helpers = (
+ _parse_project_geometry_length,
+ _resolve_project_font_sizes,
+ )
+ if any(helper is None for helper in helpers):
+ return
+ try:
+ font_sizes = _resolve_project_font_sizes(root)
+ except ValueError:
+ return
+
+ parent_by_id = {
+ id(child): parent
+ for parent in root.iter()
+ for child in list(parent)
+ }
+ unchanged_groups = self._unchanged_txbody_group_ids(root)
+ style_properties = (
+ 'fill',
+ 'fill-opacity',
+ 'font-family',
+ 'font-style',
+ 'font-weight',
+ 'letter-spacing',
+ 'opacity',
+ 'stroke',
+ 'stroke-opacity',
+ 'stroke-width',
+ 'text-decoration',
+ )
+
+ def line_record(element: ET.Element) -> Dict | None:
+ if (
+ _local_name(element) != 'text'
+ or list(element)
+ or element.get('x') is None
+ or element.get('y') is None
+ or any(element.get(name) is not None for name in ('dx', 'dy'))
+ or element.get('transform') is not None
+ or self._is_hidden_element(element, parent_by_id)
+ or self._has_ancestor_id(
+ element,
+ parent_by_id,
+ unchanged_groups,
+ )
+ ):
+ return None
+ text = (element.text or '').strip()
+ compact_text = re.sub(r'\s+', '', text)
+ if (
+ not compact_text
+ or ('{{' in text and '}}' in text)
+ or _PARAGRAPH_LIST_MARKER_RE.match(text)
+ ):
+ return None
+ anchor = (
+ _effective_presentation_value(
+ element,
+ 'text-anchor',
+ parent_by_id,
+ )
+ or 'start'
+ ).strip().lower()
+ if anchor != 'start':
+ return None
+ try:
+ x = _parse_project_geometry_length(element.get('x'), 'x')
+ y = _parse_project_geometry_length(element.get('y'), 'y')
+ font_size = float(font_sizes[id(element)])
+ except (KeyError, TypeError, ValueError):
+ return None
+ if font_size <= 0:
+ return None
+ style = tuple(
+ (
+ _effective_presentation_value(
+ element,
+ name,
+ parent_by_id,
+ )
+ or ''
+ ).strip().lower()
+ for name in style_properties
+ )
+ return {
+ 'chars': len(compact_text),
+ 'font_size': font_size,
+ 'style': style,
+ 'text': text,
+ 'x': x,
+ 'y': y,
+ }
+
+ suspects: List[str] = []
+ for group in list(root):
+ if (
+ _local_name(group) != 'g'
+ or self._is_hidden_element(group, parent_by_id)
+ ):
+ continue
+ current_run: List[Dict] = []
+
+ def flush_run() -> None:
+ if len(current_run) < 2:
+ return
+ total_chars = sum(line['chars'] for line in current_run)
+ longest_line = max(line['chars'] for line in current_run)
+ if (
+ total_chars < _PARAGRAPH_LINE_MIN_TOTAL_CHARS
+ or longest_line < _PARAGRAPH_LINE_MIN_LONGEST_CHARS
+ ):
+ return
+ first = current_run[0]
+ last = current_run[-1]
+ suspects.append(
+ f'{_element_label(group)} x={first["x"]:.1f}, '
+ f'y={first["y"]:.1f}..{last["y"]:.1f}, '
+ f'{len(current_run)} lines'
+ )
+
+ for child in list(group):
+ line = line_record(child)
+ if line is None:
+ flush_run()
+ current_run = []
+ continue
+ if current_run:
+ previous = current_run[-1]
+ line_gap = line['y'] - previous['y']
+ same_frame = (
+ abs(line['x'] - previous['x'])
+ <= _PARAGRAPH_LINE_X_TOLERANCE
+ and line['style'] == previous['style']
+ and math.isclose(
+ line['font_size'],
+ previous['font_size'],
+ rel_tol=0.0,
+ abs_tol=1e-6,
+ )
+ and line_gap
+ >= line['font_size'] * _PARAGRAPH_LINE_GAP_MIN_RATIO
+ and line_gap
+ <= line['font_size'] * _PARAGRAPH_LINE_GAP_MAX_RATIO
+ and not _PARAGRAPH_LINE_TERMINATOR_RE.search(
+ previous['text']
+ )
+ )
+ if not same_frame:
+ flush_run()
+ current_run = []
+ current_run.append(line)
+ flush_run()
+
+ if not suspects:
+ return
+ sample = '; '.join(suspects[:3])
+ suffix = '' if len(suspects) <= 3 else f'; +{len(suspects) - 3} more'
+ result['warnings'].append(
+ f'Detected {len(suspects)} paragraph-like line run(s) split '
+ f'across sibling <text> elements ({sample}{suffix}). If each run '
+ 'is one prose paragraph, combine it into one <text>: keep its '
+ 'first line as direct text and use direct <tspan> children with '
+ 'the parent x and positive relative dy values for later lines. '
+ 'An all-<tspan> form may start with dy="0". Keep semantically '
+ 'independent text frames separate.'
+ )
+
+ @staticmethod
+ def _is_tspan(elem: ET.Element) -> bool:
+ return elem.tag == f'{{{SVG_NS}}}tspan'
+
+ @classmethod
+ def _is_line_tspan(cls, elem: ET.Element) -> bool:
+ if not cls._is_tspan(elem):
+ return False
+ if elem.get('x') is not None or elem.get('y') is not None:
+ return True
+ dy = elem.get('dy')
+ if dy is None:
+ return False
+ try:
+ return float(re.match(r'^[\s,]*([+-]?(?:\d+\.?\d*|\d*\.\d+))', dy).group(1)) != 0
+ except (AttributeError, ValueError):
+ return True
+
+ @classmethod
+ def _leading_text_normalizer_reject_reason(cls, text_el: ET.Element) -> str | None:
+ if text_el.get('x') is None:
+ return '<text> has no x anchor'
+
+ for child in list(text_el):
+ if not cls._is_tspan(child):
+ return '<text> has non-tspan child'
+ if (child.tail or "").strip():
+ return '<tspan> has non-empty tail text'
+
+ return None
+
+ def _check_image_references(self, root: ET.Element, svg_path: Path, result: Dict):
+ """Check image file existence and effective rendered resolution."""
+ svg_dir = svg_path.parent
+ working_root, parent_by_id, images = self._visible_image_elements(root)
+
+ for image in images:
+ href = image.get('href') or image.get(f'{{{XLINK_NS}}}href')
+ if not href or href.startswith('data:'):
+ continue
+ if self.template_mode and '{{' in href and '}}' in href:
+ continue
+ if _resolve_external_image_reference is None:
+ result['warnings'].append(
+ "Detected image references, but shared image resolver could not be imported; "
+ "export will still validate them."
+ )
+ return
+
+ img_path = _resolve_external_image_reference(svg_dir, href)
+ if img_path is None:
+ # The shared image-source contract already reports the
+ # blocking resolution failure. This pass adds quality advice
+ # only for valid, resolved images.
+ continue
+
+ # Check resolution vs display size
+ display_owner = image
+ parent = parent_by_id.get(id(image))
+ if (
+ parent is not None
+ and parent is not working_root
+ and parent.tag == f'{{{SVG_NS}}}svg'
+ ):
+ # Imported crops use a unit-frame inner image. Quality advice
+ # must compare the source against the visible outer frame.
+ display_owner = parent
+ display_w_str = display_owner.get('width')
+ display_h_str = display_owner.get('height')
+ if not display_w_str or not display_h_str:
+ continue
+
+ try:
+ display_x = float(display_owner.get('x') or '0')
+ display_y = float(display_owner.get('y') or '0')
+ local_display_w = float(display_w_str)
+ local_display_h = float(display_h_str)
+ except (ValueError, TypeError):
+ continue
+ if local_display_w <= 0 or local_display_h <= 0:
+ continue
+ display_w = local_display_w
+ display_h = local_display_h
+ transformed_size = self._transformed_rect_edge_lengths(
+ display_owner,
+ (display_x, display_y, local_display_w, local_display_h),
+ parent_by_id,
+ )
+ if transformed_size is not None:
+ display_w, display_h = transformed_size
+ axis_scale_x = display_w / local_display_w
+ axis_scale_y = display_h / local_display_h
+
+ try:
+ from PIL import Image as PILImage, ImageOps
+ with PILImage.open(img_path) as img:
+ actual_w, actual_h = ImageOps.exif_transpose(img).size
+ source_bytes = img_path.stat().st_size
+
+ visible_w = float(actual_w)
+ visible_h = float(actual_h)
+ fit_owner = image
+ if display_owner is not image:
+ fit_owner = display_owner
+ viewbox = (display_owner.get('viewBox') or '').split()
+ if len(viewbox) == 4:
+ try:
+ viewbox_w = float(viewbox[2])
+ viewbox_h = float(viewbox[3])
+ except ValueError:
+ pass
+ else:
+ if 0 < viewbox_w <= 1 and 0 < viewbox_h <= 1:
+ visible_w *= viewbox_w
+ visible_h *= viewbox_h
+
+ raw_aspect = fit_owner.get('preserveAspectRatio')
+ try:
+ align, mode = (
+ _parse_project_image_aspect_ratio(raw_aspect)
+ if _parse_project_image_aspect_ratio is not None
+ else ('xMidYMid', 'meet')
+ )
+ except ValueError:
+ continue
+
+ local_scale_x = local_display_w / visible_w
+ local_scale_y = local_display_h / visible_h
+ if align == 'none':
+ render_scale = max(
+ local_scale_x * axis_scale_x,
+ local_scale_y * axis_scale_y,
+ )
+ fit_label = 'none'
+ elif mode == 'slice':
+ render_scale = (
+ max(local_scale_x, local_scale_y)
+ * max(axis_scale_x, axis_scale_y)
+ )
+ fit_label = 'slice'
+ else:
+ render_scale = (
+ min(local_scale_x, local_scale_y)
+ * max(axis_scale_x, axis_scale_y)
+ )
+ fit_label = 'meet'
+
+ if render_scale > 1.0:
+ result['warnings'].append(
+ f"Image {href} is {actual_w}x{actual_h} and renders at "
+ f"{render_scale:.2f}x scale in a "
+ f"{int(display_w)}x{int(display_h)} {fit_label} frame "
+ "— may appear blurry"
+ )
+ elif (
+ render_scale < 1.0 / IMAGE_DOWNSIZE_WARN_RATIO
+ and source_bytes >= IMAGE_DOWNSIZE_WARN_MIN_BYTES
+ ):
+ source_mib = source_bytes / (1024 * 1024)
+ result['warnings'].append(
+ f"Image {href} is {actual_w}x{actual_h} and renders at "
+ f"{render_scale:.2f}x scale in a "
+ f"{int(display_w)}x{int(display_h)} {fit_label} frame; "
+ f"the source is {source_mib:.1f} MiB — file-size "
+ "advisory only, not an aspect-ratio warning; consider "
+ "a smaller source asset"
+ )
+ except ImportError:
+ pass # PIL not available, skip resolution check
+ except Exception:
+ pass # Image unreadable, skip resolution check
+
+ def _check_icon_placeholders(self, root: ET.Element, svg_path: Path, result: Dict) -> None:
+ """Check that <use data-icon="..."> placeholders resolve."""
+ placeholders = [
+ elem for elem in root.iter()
+ if _local_name(elem).lower() == 'use' and elem.get('data-icon') is not None
+ ]
+ if not placeholders:
+ return
+
+ if _resolve_icon_path is None:
+ result['warnings'].append(
+ "Detected data-icon placeholders, but icon resolver could not be imported; "
+ "post-processing/export will still validate them."
+ )
+ return
+ if _icon_search_dirs_for_svg is None:
+ result['warnings'].append(
+ "Detected data-icon placeholders, but shared icon search helper could not be imported; "
+ "post-processing/export will still validate them."
+ )
+ return
+
+ icons_dir, fallback_dir = _icon_search_dirs_for_svg(svg_path)
+ require_project_local = self._requires_project_local_icons(svg_path)
+ project_icons_dir = (
+ _project_root_for_svg_path(svg_path) / 'icons'
+ if _project_root_for_svg_path is not None
+ else None
+ )
+ seen = set()
+ for elem in placeholders:
+ icon_name = (elem.get('data-icon') or '').strip()
+ if not icon_name:
+ result['errors'].append("Icon placeholder has empty data-icon value")
+ continue
+ if icon_name in seen:
+ continue
+ seen.add(icon_name)
+
+ if require_project_local and project_icons_dir is not None:
+ local_path, _ = _resolve_icon_path(
+ icon_name,
+ project_icons_dir,
+ None,
+ )
+ if not local_path.exists():
+ result['errors'].append(
+ f"Icon is not prepared in the project: {icon_name} "
+ f"(expected under {project_icons_dir}); return to "
+ "Strategist preparation instead of using the global fallback"
+ )
+ continue
+
+ icon_path, _ = _resolve_icon_path(icon_name, icons_dir, fallback_dir)
+ if not icon_path.exists():
+ fallback_msg = f", then {fallback_dir}" if fallback_dir else ""
+ suggestion = (
+ _suggest_icon_name(icon_name, icons_dir, fallback_dir)
+ if _suggest_icon_name is not None else None
+ )
+ hint = (
+ f"; identifiers are case-sensitive; use '{suggestion}'"
+ if suggestion else ""
+ )
+ result['errors'].append(
+ f"Icon not found: {icon_name} (searched {icons_dir}"
+ f"{fallback_msg}){hint}"
+ )
+ continue
+ try:
+ icon_root = ET.parse(icon_path).getroot()
+ hydrated = hydrate_native_payload_refs(icon_root, icon_path)
+ except (OSError, ET.ParseError, NativePayloadError) as exc:
+ result['errors'].append(
+ f"Icon {icon_name} has invalid native payload metadata: {exc}"
+ )
+ continue
+ if _project_mask_errors is not None:
+ result['errors'].extend(
+ f'Icon {icon_name}: {error}'
+ for error in _project_mask_errors(icon_root)
+ )
+ if hydrated:
+ result['info']['native_icon_payload_refs'] = (
+ result['info'].get('native_icon_payload_refs', 0) + hydrated
+ )
+
+ @staticmethod
+ def _requires_project_local_icons(svg_path: Path) -> bool:
+ """Return whether a generated page belongs to a versioned project."""
+ if svg_path.parent.name != 'svg_output' or _project_root_for_svg_path is None:
+ return False
+ lock_path = _project_root_for_svg_path(svg_path) / 'spec_lock.md'
+ try:
+ first_line = next(
+ (
+ line.strip()
+ for line in lock_path.read_text(encoding='utf-8-sig').splitlines()
+ if line.strip()
+ ),
+ '',
+ )
+ except OSError:
+ return False
+ return bool(
+ re.fullmatch(
+ r'<!--[ \t]+ppt-master-schema:[ \t]*spec-lock/v[1-9][0-9]*[ \t]+-->',
+ first_line,
+ re.IGNORECASE,
+ )
+ )
+
+ def _check_unsupported_visual_elements(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Reject authored visual elements with no native converter dispatch."""
+ if _collect_unsupported_visuals is None:
+ result['errors'].append(
+ "Unable to import native visual-element preflight; "
+ "cannot verify SVG element support"
+ )
+ return
+ if _expand_local_use_references is None or _UseExpansionError is None:
+ result['errors'].append(
+ "Unable to import local <use> expansion; "
+ "cannot verify SVG element support"
+ )
+ return
+
+ expanded_root = copy.deepcopy(root)
+ try:
+ _expand_local_use_references(expanded_root)
+ except _UseExpansionError:
+ # _check_forbidden_elements already reports the actionable
+ # local-reference validation error.
+ return
+
+ unsupported = _collect_unsupported_visuals(
+ expanded_root,
+ allow_data_icon_use=True,
+ )
+ if not unsupported:
+ return
+
+ preview = '; '.join(unsupported[:8])
+ suffix = '' if len(unsupported) <= 8 else f'; +{len(unsupported) - 8} more'
+ result['errors'].append(
+ f"Unsupported visual SVG element(s) for native PPTX export: "
+ f"{preview}{suffix}"
+ )
+
+ def _check_preset_geometry_metadata(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Validate round-trip preset metadata with the exporter's parser."""
+ marked = [
+ elem
+ for elem in root.iter()
+ if (
+ elem.get('data-pptx-prst') is not None
+ or elem.get('data-pptx-frame') is not None
+ or elem.get('data-pptx-geometry-status') is not None
+ or elem.get('data-pptx-geometry-reason') is not None
+ or elem.get('data-pptx-geometry-kind') is not None
+ or elem.get('data-pptx-custgeom') is not None
+ or elem.get('data-pptx-preview-sha256') is not None
+ or elem.get('data-pptx-shape-id') is not None
+ or elem.get('data-pptx-shape-scope') is not None
+ or elem.get('data-pptx-shape-style') is not None
+ or elem.get(_AUTHORING_ATTR) is not None
+ or any(attr.startswith('data-pptx-av-') for attr in elem.attrib)
+ )
+ ]
+ if not marked:
+ return
+ if _validate_preset_geometry_metadata is None:
+ result['errors'].append(
+ 'Unable to import PPTX preset metadata validator; '
+ 'cannot verify native shape restoration'
+ )
+ return
+
+ issues = set()
+ for elem in marked:
+ tag = _local_name(elem)
+ elem_id = elem.get('id')
+ label = f'<{tag} id="{elem_id}">' if elem_id else f'<{tag}>'
+ for error in _validate_preset_geometry_metadata(elem):
+ issues.add(f'{label} has invalid PPTX shape metadata: {error}')
+ if _validate_authored_preset_tree is None:
+ if any(
+ elem.get(_AUTHORING_ATTR) is not None
+ for elem in root.iter()
+ ):
+ issues.add(
+ 'Unable to import authored PPTX preset validator'
+ )
+ else:
+ for error in _validate_authored_preset_tree(root):
+ issues.add(f'Invalid authored PPTX preset: {error}')
+ if (
+ _svg_preset_preview_fingerprint is None
+ or _resolve_preset_preview_hash is None
+ ):
+ issues.add('Unable to import PPTX preset preview fingerprint validator')
+ else:
+ for elem in root.iter():
+ if (
+ _local_name(elem) != 'g'
+ or elem.get('data-pptx-object') not in {'shape', 'connector'}
+ or elem.get('data-pptx-prst') is None
+ ):
+ continue
+ try:
+ expected = _resolve_preset_preview_hash(elem)
+ except ValueError as exc:
+ elem_id = elem.get('id') or '(no id)'
+ issues.add(
+ f'<g id="{elem_id}"> has an invalid PPTX preset '
+ f'preview contract: {exc}'
+ )
+ continue
+ if expected is None:
+ continue
+ actual = _svg_preset_preview_fingerprint(elem)
+ if actual != expected:
+ elem_id = elem.get('id') or '(no id)'
+ issues.add(
+ f'<g id="{elem_id}"> has a stale PPTX preset preview; '
+ 'update the native carrier or restore the generated detail paths'
+ )
+ result['errors'].extend(sorted(issues))
+ if (
+ _authored_preset_encoding is not None
+ and _validate_authored_preset_group is not None
+ ):
+ expanded = [
+ elem.get('id') or '(no id)'
+ for elem in root.iter()
+ if _authored_preset_encoding(elem) == 'expanded'
+ and not _validate_authored_preset_group(elem)
+ ]
+ if expanded:
+ examples = ', '.join(expanded[:3])
+ suffix = '' if len(expanded) <= 3 else f', +{len(expanded) - 3} more'
+ result['warnings'].append(
+ 'Compatible expanded authored-preset fragment(s) detected '
+ f'({len(expanded)}: {examples}{suffix}). New project-authored '
+ 'pages and templates use the compact helper form; the '
+ 'expanded carrier/preview form remains readable for compatibility. '
+ 'No change is required while it remains ordinary Slide-local input.'
+ )
+ inherited_paint = _compact_preset_ancestor_paint(root)
+ if inherited_paint:
+ examples = ', '.join(
+ f'{element_id} ({"/".join(properties)})'
+ for element_id, properties in inherited_paint[:3]
+ )
+ suffix = (
+ ''
+ if len(inherited_paint) <= 3
+ else f', +{len(inherited_paint) - 3} more'
+ )
+ result['warnings'].append(
+ 'Compact authored preset(s) use compatible ancestor paint or '
+ f'opacity ({examples}{suffix}). Canonical page/template authoring '
+ 'keeps preset paint local and reruns the helper with channel alpha; '
+ 'export remains supported.'
+ )
+
+ def _check_preset_geometry_transforms(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Reject preset transforms that DrawingML cannot represent exactly."""
+ helpers = (
+ _IDENTITY_MATRIX,
+ _matrix_multiply,
+ _parse_transform_matrix,
+ _rect_to_dml_xfrm,
+ _validate_dml_shape_matrix,
+ )
+ if any(helper is None for helper in helpers):
+ return
+
+ relevant: set[ET.Element] = set()
+
+ def mark_relevant(element: ET.Element) -> bool:
+ found = element.get('data-pptx-prst') is not None
+ for child in element:
+ found = mark_relevant(child) or found
+ if found:
+ relevant.add(element)
+ return found
+
+ mark_relevant(root)
+ issues = set()
+
+ def visit(element: ET.Element, parent_matrix) -> None:
+ if element not in relevant:
+ return
+ matrix = parent_matrix
+ transform = element.get('transform')
+ if transform:
+ try:
+ local_matrix = _parse_transform_matrix(transform)
+ matrix = _matrix_multiply(parent_matrix, local_matrix)
+ except ValueError as exc:
+ issues.add(
+ f'<{_local_name(element)}> has invalid preset '
+ f'transform: {exc}'
+ )
+ return
+ if element.get('data-pptx-prst') is not None:
+ try:
+ raw_frame = element.get('data-pptx-frame')
+ if raw_frame:
+ frame = tuple(
+ float(part)
+ for part in re.split(r'[\s,]+', raw_frame.strip())
+ )
+ if len(frame) != 4:
+ raise ValueError(
+ 'data-pptx-frame must contain four numbers'
+ )
+ preset = element.get('data-pptx-prst') or ''
+ _rect_to_dml_xfrm(
+ frame[0],
+ frame[1],
+ frame[2],
+ frame[3],
+ matrix,
+ preserve_degenerate_axes=(
+ element.get('data-pptx-object') == 'connector'
+ or preset in _CONNECTOR_PRESET_TYPES
+ ),
+ )
+ else:
+ _validate_dml_shape_matrix(matrix)
+ except ValueError as exc:
+ elem_id = element.get('id') or '(no id)'
+ issues.add(
+ f'<{_local_name(element)} id="{elem_id}"> has '
+ f'unsupported preset transform: {exc}'
+ )
+ for child in element:
+ visit(child, matrix)
+
+ visit(root, _IDENTITY_MATRIX)
+ result['errors'].extend(sorted(issues))
+
+ @staticmethod
+ def _is_full_canvas_root_rect(
+ root: ET.Element,
+ element: ET.Element,
+ ) -> bool:
+ """Return whether one direct rect is the ordinary full-page backdrop."""
+ if (
+ _local_name(element) != 'rect'
+ or _parse_project_geometry_length is None
+ or any(
+ element.get(attribute)
+ for attribute in ('transform', 'filter', 'clip-path')
+ )
+ ):
+ return False
+ viewbox = _parse_viewbox_values(root.get('viewBox') or '')
+ if viewbox is None:
+ return False
+
+ parent_by_id = {id(element): root}
+
+ def inherited(name: str, default: str) -> str:
+ return _effective_presentation_value(
+ element,
+ name,
+ parent_by_id,
+ ) or default
+
+ try:
+ values = {
+ name: _parse_project_geometry_length(
+ element.get(name) or '0',
+ name,
+ )
+ for name in ('x', 'y', 'width', 'height', 'rx', 'ry')
+ }
+ stroke_width = _parse_project_geometry_length(
+ inherited('stroke-width', '1'),
+ 'stroke-width',
+ )
+ stroke_opacity = (
+ _parse_project_opacity(inherited('stroke-opacity', '1'))
+ if _parse_project_opacity is not None else 1.0
+ )
+ except ValueError:
+ return False
+ fill = inherited('fill', '#000000').strip().lower()
+ stroke = inherited('stroke', 'none').strip().lower()
+ if (
+ fill == 'none'
+ or (
+ stroke != 'none'
+ and stroke_width > 0
+ and stroke_opacity > 0
+ )
+ ):
+ return False
+
+ view_x, view_y, view_width, view_height = viewbox
+ tolerance = 0.5
+ return (
+ values['rx'] == 0
+ and values['ry'] == 0
+ and abs(values['x'] - view_x) <= tolerance
+ and abs(values['y'] - view_y) <= tolerance
+ and abs(values['width'] - view_width) <= tolerance
+ and abs(values['height'] - view_height) <= tolerance
+ )
+
+ def _check_animation_group_ids(
+ self,
+ root: ET.Element,
+ svg_path: Path,
+ result: Dict,
+ ):
+ """Validate top-level animation anchors without policing inner groups."""
+ non_visual = {'defs', 'title', 'desc', 'metadata', 'style'}
+ group_indexes: Dict[str, List[int]] = defaultdict(list)
+ ungrouped: List[str] = []
+ ungrouped_signatures: List[Tuple[object, ...]] = []
+ visual_index = 0
+
+ for child in root:
+ tag = _local_name(child)
+ if tag in non_visual:
+ continue
+ visual_index += 1
+ is_first_visual = visual_index == 1
+
+ if tag == 'g':
+ group_id = _usable_animation_group_id(child.get('id'))
+ if group_id is None:
+ result['warnings'].append(
+ f"Top-level visible <g> #{visual_index} has no id; "
+ "object-level animation config cannot reference it"
+ )
+ continue
+ group_indexes[group_id].append(visual_index)
+ continue
+
+ if svg_path.parent.name != 'svg_output':
+ continue
+ if child.get('data-pptx-layer') is not None:
+ continue
+ if (
+ _is_static_page_frame is not None
+ and _is_static_page_frame(
+ child.get('data-pptx-role'),
+ child.get('data-pptx-placeholder'),
+ )
+ ):
+ continue
+ if is_first_visual and self._is_full_canvas_root_rect(root, child):
+ continue
+ child_id = (child.get('id') or '').strip()
+ ungrouped.append(
+ f'<{tag} id="{child_id}">'
+ if child_id else f'<{tag}> #{visual_index}'
+ )
+ ungrouped_signatures.append(
+ self._prototype_element_signature(child)
+ )
+
+ for group_id, indexes in sorted(group_indexes.items()):
+ if len(indexes) > 1:
+ positions = ', '.join(str(item) for item in indexes)
+ result['errors'].append(
+ f'Duplicate top-level group id {group_id!r} at visible '
+ f'positions {positions}; animation target ids must be unique'
+ )
+
+ if ungrouped:
+ samples = ', '.join(ungrouped[:3])
+ if len(ungrouped) > 3:
+ samples += ', ...'
+ message = (
+ f'{len(ungrouped)} ungrouped top-level Slide-local element(s) '
+ f'in svg_output ({samples}); group only logical content units '
+ 'in a top-level <g id="...">. Keep genuine static page framing '
+ 'as a root primitive and declare a supported data-pptx-role such '
+ 'as "background" or "decoration"'
+ )
+ prototype_root = self._active_prototype_root()
+ prototype_ungrouped = (
+ self._ungrouped_slide_local_facts(prototype_root)
+ if prototype_root is not None
+ else ([], [])
+ )
+ if (
+ prototype_root is not None
+ and ungrouped == prototype_ungrouped[0]
+ and ungrouped_signatures == prototype_ungrouped[1]
+ ):
+ self._append_inherited_info(
+ result,
+ 'animation_anchor',
+ message,
+ )
+ else:
+ result['warnings'].append(message)
+
+ @staticmethod
+ def _prototype_element_signature(
+ element: ET.Element,
+ ) -> Tuple[object, ...]:
+ """Compare warning-owned topology/style while ignoring visible text."""
+ return (
+ _local_name(element),
+ tuple(sorted(element.attrib.items())),
+ tuple(
+ SVGQualityChecker._prototype_element_signature(child)
+ for child in element
+ ),
+ )
+
+ def _ungrouped_slide_local_facts(
+ self,
+ root: ET.Element,
+ ) -> Tuple[List[str], List[Tuple[object, ...]]]:
+ """Describe and fingerprint top-level non-group Slide-local atoms."""
+ non_visual = {'defs', 'title', 'desc', 'metadata', 'style'}
+ descriptors: List[str] = []
+ signatures: List[Tuple[object, ...]] = []
+ visual_index = 0
+ for child in root:
+ tag = _local_name(child)
+ if tag in non_visual:
+ continue
+ visual_index += 1
+ if tag == 'g' or child.get('data-pptx-layer') is not None:
+ continue
+ if (
+ _is_static_page_frame is not None
+ and _is_static_page_frame(
+ child.get('data-pptx-role'),
+ child.get('data-pptx-placeholder'),
+ )
+ ):
+ continue
+ if visual_index == 1 and self._is_full_canvas_root_rect(root, child):
+ continue
+ child_id = (child.get('id') or '').strip()
+ descriptors.append(
+ f'<{tag} id="{child_id}">'
+ if child_id else f'<{tag}> #{visual_index}'
+ )
+ signatures.append(self._prototype_element_signature(child))
+ return descriptors, signatures
+
+ # OOXML ST_PresetPatternVal enum — anything outside this set produces a
+ # PPTX schema violation ("PowerPoint found a problem with the content").
+ _OOXML_PATTERN_PRESETS = frozenset({
+ 'pct5', 'pct10', 'pct20', 'pct25', 'pct30', 'pct40', 'pct50', 'pct60',
+ 'pct70', 'pct75', 'pct80', 'pct90',
+ 'horz', 'vert', 'ltHorz', 'ltVert', 'dkHorz', 'dkVert',
+ 'narHorz', 'narVert', 'dashHorz', 'dashVert',
+ 'cross', 'dnDiag', 'upDiag', 'ltDnDiag', 'ltUpDiag', 'dkDnDiag',
+ 'dkUpDiag', 'wdDnDiag', 'wdUpDiag',
+ 'dashDnDiag', 'dashUpDiag', 'diagCross',
+ 'smCheck', 'lgCheck', 'smGrid', 'lgGrid', 'dotGrid', 'smConfetti',
+ 'lgConfetti', 'horzBrick', 'diagBrick', 'solidDmnd', 'openDmnd',
+ 'dotDmnd', 'plaid', 'sphere', 'weave', 'wave', 'trellis', 'zigZag',
+ 'divot', 'shingle',
+ })
+
+ def _check_pattern_fills(self, root: ET.Element, result: Dict):
+ """Audit <pattern> defs that drive PPTX <a:pattFill> output.
+
+ svg_to_pptx maps <pattern fill> to native <a:pattFill prst="...">. The
+ preset name comes from `data-pptx-pattern` (e.g. `lgGrid` / `smGrid` /
+ `dkUpDiag`). Two failure modes worth catching pre-export:
+
+ 1. Missing annotation → the converter compatibility fallback chooses
+ `ltUpDiag` (diagonal stripes), which is not an authoring contract.
+ 2. Invalid preset name → PPTX schema rejects the file; PowerPoint
+ opens it with "needs to be repaired". OOXML
+ `ST_PresetPatternVal` is a closed enum — only the names in
+ `_OOXML_PATTERN_PRESETS` are legal. Inventing `ltGrid` (no such
+ value) is the canonical mistake; the only grids are `smGrid` /
+ `lgGrid` / `dotGrid`.
+ """
+ definitions, _duplicates = _direct_defs_index(root)
+ referenced_patterns: set[str] = set()
+ for elem in root.iter():
+ style_values = (
+ _parse_inline_style(elem.get('style'))
+ if _parse_inline_style is not None else {}
+ )
+ fill = style_values.get('fill') or elem.get('fill')
+ match = re.fullmatch(r'url\(#([^)]+)\)', (fill or '').strip())
+ if match is None:
+ continue
+ definition = definitions.get(match.group(1))
+ if definition is not None and _local_name(definition) == 'pattern':
+ referenced_patterns.add(match.group(1))
+
+ for pattern in (
+ elem for elem in root.iter()
+ if _local_name(elem) == 'pattern'
+ ):
+ pat_id = pattern.get('id', '<unnamed>')
+ prst = pattern.get('data-pptx-pattern')
+ if pat_id in referenced_patterns and not prst:
+ result['warnings'].append(
+ f"Fidelity warning: <pattern id=\"{pat_id}\"> has no "
+ "data-pptx-pattern attribute, so the converter will use its "
+ "compatible `ltUpDiag` fallback. Generated SVG should declare a valid "
+ "data-pptx-pattern to make the intended preset explicit; "
+ "set data-pptx-fg/data-pptx-bg or matching child paints "
+ "when explicit pattern colors are required. No change is "
+ "required for export."
+ )
+ if pat_id in referenced_patterns and pattern.get('patternTransform'):
+ result['errors'].append(
+ f"<pattern id=\"{pat_id}\"> cannot use patternTransform; "
+ "the native preset mapping does not preserve custom tile transforms"
+ )
+ if prst not in self._OOXML_PATTERN_PRESETS:
+ if not prst:
+ continue
+ result['errors'].append(
+ f"<pattern id=\"{pat_id}\"> uses data-pptx-pattern=\"{prst}\" "
+ "which is not in OOXML ST_PresetPatternVal — exported PPTX "
+ "will fail schema validation ('needs to be repaired'). "
+ "Use one of: smGrid / lgGrid / dotGrid (grids), "
+ "ltUpDiag / dkUpDiag / cross / diagCross / weave / plaid / "
+ "horzBrick (others); see references/native-data-interface.md §1 "
+ "for the full authoring enum."
+ )
+
+ def _check_native_object_markers(self, root: ET.Element, result: Dict) -> None:
+ """Validate opt-in native table/chart markers before PPTX export."""
+ invalid_status_elements: set[ET.Element] = set()
+ for elem in root.iter():
+ marker_id = elem.get('id') or elem.get('data-name') or '<unnamed>'
+ if elem.tag.rsplit('}', 1)[-1] == 'metadata':
+ continue
+ has_status = any(
+ elem.get(name) is not None
+ for name in (
+ 'data-pptx-replace-with',
+ 'data-pptx-native',
+ 'data-pptx-fallback-kind',
+ 'data-pptx-visual-status',
+ 'data-pptx-route-status',
+ 'data-pptx-replacement-status',
+ 'data-pptx-native-status',
+ 'data-pptx-import-source',
+ 'data-pptx-native-source',
+ )
+ )
+ if not has_status:
+ continue
+ if (
+ _native_marker_status_errors is None
+ or _native_marker_release_block_reason is None
+ ):
+ result['errors'].append(
+ "Unable to import native-object status validator; "
+ f"cannot verify PPTX graphic {marker_id}"
+ )
+ continue
+ status_errors = _native_marker_status_errors(elem)
+ for error in status_errors:
+ result['errors'].append(
+ f"PPTX graphic {marker_id} has invalid status metadata: {error}"
+ )
+ if status_errors:
+ invalid_status_elements.add(elem)
+ continue
+ if _native_marker_legacy_warnings is not None:
+ for warning in _native_marker_legacy_warnings(elem):
+ result['warnings'].append(
+ f"PPTX replacement marker {marker_id}: {warning}"
+ )
+ try:
+ fallback_kind = (
+ _native_fallback_kind(elem)
+ if _native_fallback_kind is not None else None
+ )
+ replacement_kind = (
+ _native_replacement_kind(elem)
+ if _native_replacement_kind is not None else ''
+ )
+ except ValueError:
+ # The shared status validator reported the alias conflict.
+ continue
+ if fallback_kind == 'placeholder':
+ route = (
+ "the native Chart/Table route may reconstruct its active marker"
+ if replacement_kind
+ else "default export keeps the visible placeholder"
+ )
+ result['warnings'].append(
+ f"PPTX graphic {marker_id} is a reconstruction-only placeholder; "
+ f"it has no baked preview and {route}"
+ )
+
+ for elem in root.iter():
+ if elem.tag.rsplit('}', 1)[-1] == 'metadata':
+ continue
+ if _native_replacement_status is None or _native_replacement_kind is None:
+ continue
+ try:
+ status = _native_replacement_status(elem)
+ replacement_kind = _native_replacement_kind(elem)
+ except ValueError:
+ continue
+ if not status or replacement_kind:
+ continue
+ marker_id = elem.get('id') or elem.get('data-name') or '<unnamed>'
+ result['warnings'].append(
+ f"Native PPTX object {marker_id} is fallback-only: {status}"
+ )
+
+ markers = [
+ elem for elem in root.iter()
+ if (
+ _native_replacement_kind is not None
+ and elem.tag.rsplit('}', 1)[-1] != 'metadata'
+ and elem not in invalid_status_elements
+ and _native_replacement_kind(elem)
+ )
+ ]
+ if not markers:
+ return
+ if _validate_native_object_marker is None:
+ result['warnings'].append(
+ "Detected data-pptx-replace-with markers, but replacement validator "
+ "could not be imported; export-time validation will still run."
+ )
+ return
+
+ parent_map = {
+ child: parent
+ for parent in root.iter()
+ for child in parent
+ }
+
+ def append_metadata_legacy_warnings(marker: ET.Element) -> None:
+ if _native_marker_legacy_warnings is None:
+ return
+ marker_id = marker.get('id') or '<unnamed>'
+ for child in marker:
+ if child.tag.rsplit('}', 1)[-1] != 'metadata':
+ continue
+ for warning in _native_marker_legacy_warnings(child):
+ result['warnings'].append(
+ f"PPTX replacement marker {marker_id}: {warning}"
+ )
+
+ for marker in markers:
+ marker_id = marker.get('id') or '<unnamed>'
+ ancestors = []
+ parent = parent_map.get(marker)
+ while parent is not None and parent is not root:
+ if parent.tag.rsplit('}', 1)[-1] == 'g':
+ ancestors.append(parent)
+ parent = parent_map.get(parent)
+ ancestors_tuple = tuple(reversed(ancestors))
+ if _validate_native_object_marker_with_warnings is not None:
+ try:
+ warnings = _validate_native_object_marker_with_warnings(
+ marker,
+ ancestors=ancestors_tuple,
+ document_root=root,
+ )
+ except RuntimeError as exc:
+ result['errors'].append(
+ f"Invalid data-pptx-replace-with marker {marker_id}: {exc}"
+ )
+ continue
+ for warning in warnings:
+ result['warnings'].append(
+ f"data-pptx-replace-with marker {marker_id}: {warning}"
+ )
+ append_metadata_legacy_warnings(marker)
+ continue
+
+ try:
+ _validate_native_object_marker(marker, ancestors=ancestors_tuple)
+ except RuntimeError as exc:
+ result['errors'].append(
+ f"Invalid data-pptx-replace-with marker {marker_id}: {exc}"
+ )
+ continue
+ append_metadata_legacy_warnings(marker)
+ if _native_object_marker_warnings is None:
+ continue
+ for warning in _native_object_marker_warnings(
+ marker,
+ ancestors=ancestors_tuple,
+ document_root=root,
+ ):
+ result['warnings'].append(
+ f"data-pptx-replace-with marker {marker_id}: {warning}"
+ )
+
+ def _check_pptx_structure_metadata(
+ self,
+ root: ET.Element,
+ svg_path: Path,
+ result: Dict,
+ ) -> None:
+ """Validate the intrinsic structured Master/Layout SVG contract."""
+ if self.quick_generate:
+ forbidden_attrs = sorted({
+ attr
+ for elem in root.iter()
+ for attr in _PPTX_STRUCTURE_ATTRS
+ if elem.get(attr) is not None
+ })
+ if forbidden_attrs:
+ result['errors'].append(
+ f"{svg_path.name}: Quick Generate uses flat export and "
+ "forbids Master/Layout/layer/placeholder metadata; remove "
+ + ', '.join(forbidden_attrs)
+ )
+ return
+ if not self.template_mode and svg_path.parent.name == 'svg_output':
+ declared_mode = _declared_pptx_structure_mode(
+ self._resolve_project_path(svg_path)
+ )
+ if declared_mode == 'flat':
+ forbidden_attrs = sorted({
+ attr
+ for elem in root.iter()
+ for attr in _PPTX_STRUCTURE_ATTRS
+ if elem.get(attr) is not None
+ })
+ if forbidden_attrs:
+ result['errors'].append(
+ f"{svg_path.name}: pptx_structure.mode: flat forbids "
+ "Master/Layout/layer/placeholder metadata; remove "
+ + ', '.join(forbidden_attrs)
+ )
+ return
+ if declared_mode != 'structured':
+ # The project-level gate emits one actionable migration error.
+ # Avoid burying it under repeated per-page structure failures.
+ return
+ has_structure_metadata = any(
+ elem.get(attr) is not None
+ for elem in root.iter()
+ for attr in _PPTX_STRUCTURE_ATTRS
+ )
+ require_structure = bool(
+ self.template_mode
+ or svg_path.parent.name == 'svg_output'
+ )
+ if not has_structure_metadata and not require_structure:
+ return
+ result['errors'].extend(_local_pptx_structure_errors(
+ root,
+ svg_path,
+ require_structure=require_structure,
+ ))
+ self._check_placeholder_carrier_flattening(root, svg_path, result)
+ if svg_path.parent.name == 'svg_output':
+ self._append_structure_coverage_warnings(root, result)
+ if _validate_template_structure_svg is None:
+ result['errors'].append(
+ "Structured PPTX metadata validator could not be imported; "
+ "the quality gate cannot verify this SVG"
+ )
+ return
+ result['errors'].extend(_validate_template_structure_svg(svg_path))
+ result['errors'] = list(dict.fromkeys(result['errors']))
+
+ @staticmethod
+ def _check_placeholder_carrier_flattening(
+ root: ET.Element,
+ svg_path: Path,
+ result: Dict,
+ ) -> None:
+ """Reject slot carriers that export as multiple native children.
+
+ Default export flattens non-mergeable positional ``<tspan>`` lines
+ before converting the surrounding slot group to DrawingML. Reuse that
+ exact transform here so the quality gate fails before the later
+ placeholder-unwrapping step does.
+ """
+ if _flatten_positional_tspans is None:
+ return
+
+ candidate_ids: List[str] = []
+ for slot in root.iter(f'{{{SVG_NS}}}g'):
+ if not (slot.get('data-pptx-placeholder') or '').strip():
+ continue
+ binding = (
+ slot.get('data-pptx-binding') or 'carrier'
+ ).strip().lower()
+ if binding != 'carrier':
+ continue
+ visual_children = [
+ child for child in list(slot)
+ if _local_name(child) not in _NON_VISUAL_SVG_TAGS
+ ]
+ carriers = [
+ child for child in visual_children
+ if (child.get('data-pptx-carrier') or '')
+ .strip()
+ .lower()
+ == 'true'
+ ]
+ slot_id = (slot.get('id') or '').strip()
+ if not slot_id or len(visual_children) != 1 or len(carriers) != 1:
+ continue
+ if not any(
+ _local_name(descendant) == 'tspan'
+ and any(
+ descendant.get(name) is not None
+ for name in ('x', 'y', 'dy')
+ )
+ for descendant in carriers[0].iter()
+ ):
+ continue
+ candidate_ids.append(slot_id)
+
+ if not candidate_ids:
+ return
+
+ flattened_root = copy.deepcopy(root)
+ try:
+ _flatten_positional_tspans(
+ ET.ElementTree(flattened_root),
+ merge_paragraphs=True,
+ preserve_line_breaks=True,
+ )
+ except ValueError:
+ # The shared text check reports the unsupported nested-position
+ # contract; avoid turning a quality result into a checker crash.
+ return
+ slots_by_id = {
+ (slot.get('id') or '').strip(): slot
+ for slot in flattened_root.iter(f'{{{SVG_NS}}}g')
+ if (slot.get('id') or '').strip()
+ }
+ for slot_id in candidate_ids:
+ slot = slots_by_id.get(slot_id)
+ if slot is None:
+ continue
+ native_children = [
+ child for child in list(slot)
+ if _local_name(child) not in _NON_VISUAL_SVG_TAGS
+ ]
+ if len(native_children) == 1:
+ continue
+ result['errors'].append(
+ f"{svg_path.name}: placeholder slot {slot_id} becomes "
+ f"{len(native_children)} native children after positional "
+ "<tspan> flattening; a carrier-bound slot must export as one "
+ "text or picture carrier. Use one single-frame dy-stacked text "
+ "frame, or move independently positioned lines outside the slot"
+ )
+
+ def _append_structure_coverage_warnings(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Warn on mapped pages that compile to bare Masters / empty Layouts.
+
+ Zero-slot and framing-only Layouts are legal contracts, so these stay
+ advisory warnings. They neither fail the workflow gate nor require a
+ per-warning disposition.
+ """
+ messages = self._structure_coverage_messages(root)
+ if not messages:
+ return
+ prototype_root = self._active_prototype_root()
+ if (
+ prototype_root is not None
+ and messages == self._structure_coverage_messages(prototype_root)
+ ):
+ for message in messages:
+ self._append_inherited_info(
+ result,
+ 'structure_coverage',
+ message,
+ )
+ return
+ result['warnings'].extend(messages)
+
+ @staticmethod
+ def _structure_coverage_messages(root: ET.Element) -> List[str]:
+ """Return advisory coverage messages for one structured page."""
+ if not (root.get('data-pptx-layout') or '').strip():
+ return []
+ messages: List[str] = []
+ has_layer_mark = any(
+ elem.get('data-pptx-layer') is not None
+ for elem in root.iter()
+ )
+ has_layout_atom = any(
+ child.get('data-pptx-layer') == 'layout'
+ for child in list(root)
+ )
+ has_placeholder = any(
+ elem.get('data-pptx-placeholder') is not None
+ for elem in root.iter()
+ )
+ if not has_layer_mark:
+ messages.append(
+ 'Mapped page declares data-pptx-layout but no data-pptx-layer '
+ 'mark; the exported Master gets no shared background/chrome '
+ 'and the Layout gets no static framing. Generated templates '
+ 'should mark the deck-wide '
+ 'background data-pptx-layer="master" and this layout key\'s '
+ 'framing data-pptx-layer="layout". No change or disposition '
+ 'is required.'
+ )
+ if not has_placeholder and not has_layout_atom:
+ messages.append(
+ 'Mapped page has no placeholder slot and no '
+ 'data-pptx-layer="layout" atom; its Layout exports empty. '
+ 'Generated templates should declare the slots the page actually '
+ 'has (title / subtitle / '
+ 'body / picture / slide-number / footer) and mark the layout '
+ 'key\'s static framing unless this is intentionally a fixed '
+ 'zero-slot composition. No change or disposition is required.'
+ )
+ elif not has_placeholder:
+ messages.append(
+ 'Mapped Layout has static framing but no insertable '
+ 'placeholder slot. Generated templates should declare the '
+ 'slots the page actually has (title / subtitle / body / '
+ 'picture / slide-number / footer) unless zero-slot is the '
+ 'intended reusable contract. No change or disposition is required.'
+ )
+ return messages
+
+ @staticmethod
+ def _check_legacy_pptx_attributes(
+ root: ET.Element,
+ svg_path: Path,
+ result: Dict,
+ ) -> None:
+ """Reject superseded long-form authoring attributes."""
+ for element in root.iter():
+ for legacy, canonical in _LEGACY_PPTX_ATTRIBUTE_RENAMES.items():
+ if element.get(legacy) is None:
+ continue
+ result['errors'].append(
+ f'{svg_path.name}: {_element_label(element)} uses legacy '
+ f'{legacy}; rename it to {canonical}'
+ )
+
+ def _check_semantic_markers(
+ self,
+ root: ET.Element,
+ svg_path: Path,
+ result: Dict,
+ ) -> None:
+ """Validate minimal compiler hints without changing SVG rendering."""
+ has_semantics = any(
+ elem.get(attr) is not None
+ for elem in root.iter()
+ for attr in _SEMANTIC_ATTRS
+ )
+ require_page_role = (
+ svg_path.parent.name in {'svg_output', 'svg_final'}
+ and root.get('data-pptx-layout') is None
+ )
+ if _validate_semantic_markers is None:
+ if has_semantics:
+ result['warnings'].append(
+ "Detected Semantic SVG markers, but their validator could "
+ "not be imported."
+ )
+ return
+ for issue in _validate_semantic_markers(
+ root,
+ require_page_role=require_page_role,
+ ):
+ if issue.severity == 'error':
+ result['errors'].append(issue.message)
+ else:
+ result['warnings'].append(issue.message)
+
+ def _get_spec_lock(self, svg_path: Path):
+ """Locate and parse spec_lock.md near the SVG. Returns dict or None.
+
+ Looks in svg_path.parent and svg_path.parent.parent (covers the two
+ common layouts: SVG directly under <project>/ or under
+ <project>/svg_output/). Results are cached per lock path.
+ """
+ if self.quick_generate:
+ return None
+ if _parse_spec_lock is None:
+ return None
+ for candidate in (svg_path.parent / 'spec_lock.md',
+ svg_path.parent.parent / 'spec_lock.md'):
+ if candidate in self._lock_cache:
+ return self._lock_cache[candidate]
+ if candidate.exists():
+ try:
+ data = _parse_spec_lock(candidate)
+ except Exception:
+ data = None
+ self._lock_cache[candidate] = data
+ if data is not None:
+ self._lock_seen = True
+ return data
+ return None
+
+ def _prototype_drift_allowances(
+ self,
+ ) -> Tuple[set[str], set[str], set[str]]:
+ """Return color/font/size values owned by the selected mirror page."""
+ prototype_root = self._active_prototype_root()
+ if prototype_root is None:
+ return set(), set(), set()
+ try:
+ content = self._active_prototype_path.read_text(encoding='utf-8')
+ except (AttributeError, OSError):
+ return set(), set(), set()
+
+ colors: set[str] = set()
+ for attribute in _PAINT_PROPERTIES or ():
+ for raw_value in self._svg_property_values(content, attribute):
+ normalized = raw_value.strip()
+ if normalized.lower() in {'none', 'transparent'} or re.fullmatch(
+ r'url\(#[^)]+\)', normalized
+ ):
+ continue
+ if _parse_export_color is not None:
+ color, _alpha = _parse_export_color(normalized)
+ else:
+ color = _normalize_hex_rgb(normalized)
+ if color:
+ colors.add(color)
+ fonts = {
+ self._normalize_font_stack(value)
+ for value in self._font_family_values(content)
+ if self._normalize_font_stack(value)
+ }
+ sizes = set(self._effective_text_size_counts(prototype_root))
+ return colors, fonts, sizes
+
+ def _declared_typography_size_anchors(
+ self,
+ lock: Dict,
+ ) -> Tuple[Dict, set[str], List[float], List[str]]:
+ """Return valid declared size anchors and malformed lock rows."""
+ typography = lock.get('typography', {})
+ positive_numeric_re = re.compile(
+ r'^(?=.*[1-9])(?:[0-9]+(?:\.[0-9]+)?|\.[0-9]+)$'
+ )
+ locked_sizes: set[str] = set()
+ anchor_sizes: List[float] = []
+ invalid_sizes: List[str] = []
+ for key, raw_value in typography.items():
+ if key == 'font_family' or key.endswith('_family'):
+ continue
+ value = raw_value.strip()
+ if positive_numeric_re.fullmatch(value) is None:
+ invalid_sizes.append(f"{key}: {raw_value}")
+ continue
+ try:
+ anchor = float(value)
+ except (TypeError, ValueError):
+ invalid_sizes.append(f"{key}: {raw_value}")
+ continue
+ if not math.isfinite(anchor) or anchor <= 0:
+ invalid_sizes.append(f"{key}: {raw_value}")
+ continue
+ locked_sizes.add(self._canonical_font_size_key(anchor))
+ anchor_sizes.append(anchor)
+ return typography, locked_sizes, anchor_sizes, invalid_sizes
+
+ def _count_undeclared_size_occurrences(
+ self,
+ root: ET.Element,
+ *,
+ locked_sizes: set[str],
+ anchor_sizes: List[float],
+ prototype_sizes: set[str],
+ ) -> Counter[str]:
+ """Count text objects using valid sizes outside all declared bands."""
+ counts: Counter[str] = Counter()
+ if not locked_sizes:
+ return counts
+ for value, occurrence_count in self._effective_text_size_counts(root).items():
+ if value in prototype_sizes and value not in locked_sizes:
+ continue
+ if value in locked_sizes:
+ continue
+ try:
+ used_px = float(value)
+ except (TypeError, ValueError):
+ continue
+ if not math.isfinite(used_px) or used_px < 0:
+ continue
+ if any(
+ abs(used_px - anchor_px) <= FONT_SIZE_ANCHOR_TOLERANCE_PX
+ for anchor_px in anchor_sizes
+ ):
+ continue
+ counts[value] += occurrence_count
+ return counts
+
+ def _effective_text_size_counts(self, root: ET.Element) -> Counter[str]:
+ """Count each effective size once per non-empty SVG text object."""
+ counts: Counter[str] = Counter()
+ if _resolve_project_font_sizes is None:
+ return counts
+ working_root = root
+ if (
+ _expand_local_use_references is not None
+ and _UseExpansionError is not None
+ ):
+ expanded_root = copy.deepcopy(root)
+ try:
+ _expand_local_use_references(expanded_root)
+ except _UseExpansionError:
+ pass
+ else:
+ working_root = expanded_root
+ try:
+ effective_sizes = _resolve_project_font_sizes(working_root)
+ except ValueError:
+ return counts
+
+ def collect_text_object_sizes(element: ET.Element) -> set[str]:
+ values: set[str] = set()
+
+ def visit(node: ET.Element) -> None:
+ if (node.text or '').strip():
+ values.add(
+ self._canonical_font_size_key(effective_sizes[id(node)])
+ )
+ for child in node:
+ visit(child)
+ if (child.tail or '').strip():
+ values.add(
+ self._canonical_font_size_key(
+ effective_sizes[id(node)]
+ )
+ )
+
+ visit(element)
+ return values
+
+ definition_containers = {
+ 'clippath',
+ 'defs',
+ 'marker',
+ 'mask',
+ 'pattern',
+ 'symbol',
+ }
+
+ def visit_visible(element: ET.Element) -> None:
+ local_name = _local_name(element).casefold()
+ if local_name in definition_containers:
+ return
+ if local_name == 'text':
+ counts.update(collect_text_object_sizes(element))
+ return
+ for child in element:
+ visit_visible(child)
+
+ visit_visible(working_root)
+ return counts
+
+ @staticmethod
+ def _canonical_font_size_key(value: float) -> str:
+ """Canonicalize equivalent numeric spellings for deck-wide counting."""
+ return format(value, '.12g')
+
+ def _prepare_undeclared_size_occurrences(
+ self,
+ svg_files: List[Path],
+ ) -> None:
+ """Pre-count sparse undeclared sizes before per-file diagnostics."""
+ previous_prototype = self._active_prototype_path
+ try:
+ for svg_path in svg_files:
+ lock = self._get_spec_lock(svg_path)
+ if lock is None:
+ continue
+ _typography, locked_sizes, anchor_sizes, _invalid = (
+ self._declared_typography_size_anchors(lock)
+ )
+ self._active_prototype_path = self._prototype_by_output.get(
+ svg_path.resolve()
+ )
+ _colors, _fonts, prototype_sizes = (
+ self._prototype_drift_allowances()
+ )
+ try:
+ content = svg_path.read_text(encoding='utf-8')
+ except OSError:
+ continue
+ try:
+ root = ET.fromstring(content)
+ except ET.ParseError:
+ continue
+ self._undeclared_size_occurrences.update(
+ self._count_undeclared_size_occurrences(
+ root,
+ locked_sizes=locked_sizes,
+ anchor_sizes=anchor_sizes,
+ prototype_sizes=prototype_sizes,
+ )
+ )
+ finally:
+ self._active_prototype_path = previous_prototype
+ self._undeclared_size_counts_ready = True
+
+ def _check_spec_lock_alignment(
+ self,
+ content: str,
+ svg_path: Path,
+ result: Dict,
+ *,
+ root: ET.Element,
+ ):
+ """Compare SVG values with reusable anchors in spec_lock.md.
+
+ Covers colors (fill / stroke / stop-color / flood-color / pattern
+ metadata), font-family, and font-size.
+ Additional colors and font families are valid contextual authoring and
+ are recorded as information. A valid undeclared display size may occur
+ at most twice across generated pages; its third occurrence makes it a
+ recurring role and blocks ``svg_output`` until the role is declared.
+ Structural text still maps to declared role bands. Exact mirror-
+ prototype values remain inherited information. Exact values are
+ accumulated in self._anchor_value_summary for end-of-run aggregation.
+ When spec_lock.md is missing, silently skip this local comparison; the
+ Generate route's required-artifact gate owns whether execution may begin.
+ """
+ lock = self._get_spec_lock(svg_path)
+ if lock is None:
+ return
+ prototype_colors, prototype_fonts, prototype_sizes = (
+ self._prototype_drift_allowances()
+ )
+
+ # Build allow-sets from the lock
+ allowed_colors = set()
+ for v in lock.get('colors', {}).values():
+ if _parse_export_color is not None:
+ color, _alpha = _parse_export_color(v)
+ if color:
+ allowed_colors.add(color)
+ else:
+ color = _normalize_hex_rgb(v)
+ if color:
+ allowed_colors.add(color)
+
+ # A validated compact preset may contain registry-derived darken/lighten
+ # layer colors. Their base paint still comes from spec_lock; the exact
+ # child HEX values are deterministic compiler evidence, not color drift.
+ if (
+ _authored_preset_encoding is not None
+ and _validate_authored_preset_group is not None
+ ):
+ for group in root.iter():
+ if (
+ _authored_preset_encoding(group) != 'compact'
+ or _validate_authored_preset_group(group)
+ ):
+ continue
+ for child in group:
+ for attribute in ('fill', 'stroke'):
+ raw_value = child.get(attribute)
+ if raw_value is None:
+ continue
+ if _parse_export_color is not None:
+ color, _alpha = _parse_export_color(raw_value)
+ else:
+ color = _normalize_hex_rgb(raw_value)
+ if color:
+ allowed_colors.add(color)
+ locked_colors = set(allowed_colors)
+ allowed_colors.update(prototype_colors)
+
+ typo, locked_sizes, anchor_sizes, invalid_lock_sizes = (
+ self._declared_typography_size_anchors(lock)
+ )
+ if invalid_lock_sizes:
+ shown = ', '.join(invalid_lock_sizes[:5])
+ more = len(invalid_lock_sizes) - 5
+ suffix = f" (+{more} more)" if more > 0 else ""
+ result['errors'].append(
+ f"spec_lock typography sizes must be positive finite unitless px values; "
+ f"found {shown}{suffix}."
+ )
+
+ # Font families: default `font_family` plus any per-role `*_family`
+ # override (title_family / body_family / emphasis_family / code_family,
+ # per templates/schemas/spec_lock.schema.json). Any of these is a legitimate declared
+ # value; an SVG that uses any one of them is not drifting.
+ allowed_fonts = set()
+ if typo:
+ default_font = typo.get('font_family', '').strip()
+ if default_font:
+ allowed_fonts.add(self._normalize_font_stack(default_font))
+ for k, v in typo.items():
+ if k == 'font_family' or not k.endswith('_family'):
+ continue
+ v_clean = v.strip()
+ # Skip placeholder text like "same as body (omit if identical)"
+ if not v_clean or v_clean.lower().startswith('same as'):
+ continue
+ allowed_fonts.add(self._normalize_font_stack(v_clean))
+ locked_fonts = set(allowed_fonts)
+ allowed_fonts.update(prototype_fonts)
+
+ # Sizes: declared slots are anchors. Checker cannot infer which role a
+ # text node carries, so it uses the union of their ±2px bands as a cheap
+ # numeric safety net; prompt rules own semantic role mapping.
+ # Scan SVG for used values
+ color_drifts = set()
+ inherited_colors = set()
+ for attr in _PAINT_PROPERTIES or ():
+ for raw_value in self._svg_property_values(content, attr):
+ normalized = raw_value.strip()
+ if normalized.lower() in {'none', 'transparent'} or re.fullmatch(
+ r'url\(#[^)]+\)', normalized
+ ):
+ continue
+ if _BARE_HEX_VALUE_RE.fullmatch(normalized):
+ continue
+ if _parse_export_color is not None:
+ val, _alpha = _parse_export_color(normalized)
+ if val is None:
+ continue
+ else:
+ val = _normalize_hex_rgb(normalized)
+ if val is None:
+ continue
+ if val not in allowed_colors:
+ color_drifts.add(f'#{val}')
+ elif val in prototype_colors and val not in locked_colors:
+ inherited_colors.add(f'#{val}')
+
+ font_drifts = set()
+ inherited_fonts = set()
+ for val in self._font_family_values(content):
+ normalized_font = self._normalize_font_stack(val)
+ if allowed_fonts and normalized_font not in allowed_fonts:
+ font_drifts.add(val)
+ elif (
+ normalized_font in prototype_fonts
+ and normalized_font not in locked_fonts
+ ):
+ inherited_fonts.add(val)
+
+ size_drift_counts = self._count_undeclared_size_occurrences(
+ root,
+ locked_sizes=locked_sizes,
+ anchor_sizes=anchor_sizes,
+ prototype_sizes=prototype_sizes,
+ )
+ size_drifts = set(size_drift_counts)
+ inherited_sizes = set()
+ for val in self._effective_text_size_counts(root):
+ if val in prototype_sizes and val not in locked_sizes:
+ inherited_sizes.add(val)
+
+ # Record in run-wide aggregation. Colors/fonts beyond the anchor set are
+ # contextual values, not release issues. Generated-page sizes enforce
+ # role-anchor ownership; other spec-backed locations retain review.
+ fname = svg_path.name
+ for v in color_drifts:
+ self._anchor_value_summary['colors'][v].add(fname)
+ for v in font_drifts:
+ self._anchor_value_summary['fonts'][v].add(fname)
+ for v in size_drifts:
+ self._anchor_value_summary['sizes'][v].add(fname)
+
+ contextual_values = {}
+ if color_drifts:
+ contextual_values['colors'] = sorted(color_drifts)
+ if font_drifts:
+ contextual_values['font_families'] = sorted(font_drifts)
+ if contextual_values:
+ result['info']['contextual_values'] = contextual_values
+
+ sparse_sizes = {}
+ recurring_sizes = {}
+ for value, local_count in size_drift_counts.items():
+ total_count = (
+ self._undeclared_size_occurrences.get(value, local_count)
+ if self._undeclared_size_counts_ready
+ else local_count
+ )
+ target = (
+ sparse_sizes
+ if total_count <= SPARSE_UNDECLARED_FONT_SIZE_MAX_OCCURRENCES
+ else recurring_sizes
+ )
+ target[value] = total_count
+
+ if sparse_sizes:
+ result['info']['sparse_typography_sizes'] = {
+ value: count for value, count in sorted(sparse_sizes.items())
+ }
+
+ if recurring_sizes:
+ shown = ', '.join(
+ f"{value} ({count} occurrences)"
+ for value, count in sorted(recurring_sizes.items())
+ )
+ size_issue = (
+ f"undeclared font-size {shown} exceeds the sparse-display limit "
+ f"of {SPARSE_UNDECLARED_FONT_SIZE_MAX_OCCURRENCES} occurrences"
+ )
+ if svg_path.parent.name == 'svg_output':
+ result['errors'].append(
+ "spec_lock typography-size recurrence: "
+ f"{size_issue}. Structural text must return to its declared "
+ "role band; a genuinely recurring display treatment needs a "
+ "justified named role in the Design Spec and spec_lock."
+ )
+ else:
+ result['warnings'].append(
+ f"spec_lock typography-size recurrence review: {size_issue}"
+ )
+ inherited_parts = []
+ if inherited_colors:
+ inherited_parts.append(f"{len(inherited_colors)} color(s)")
+ if inherited_fonts:
+ inherited_parts.append(f"{len(inherited_fonts)} font-family value(s)")
+ if inherited_sizes:
+ inherited_parts.append(f"{len(inherited_sizes)} font-size value(s)")
+ if inherited_parts:
+ self._append_inherited_info(
+ result,
+ 'spec_lock_alignment',
+ f"{', '.join(inherited_parts)} come unchanged from mirror "
+ "prototype and are accepted without expanding spec_lock.md",
+ )
+
+ def _find_image_sources_manifest(self, svg_path: Path) -> Path | None:
+ """Locate image_sources.json for a project SVG.
+
+ Quality checks run primarily on <project>/svg_output/*.svg, but this
+ also supports SVGs checked from project root or svg_final.
+ """
+ bases = (svg_path.parent, svg_path.parent.parent, svg_path.parent.parent.parent)
+ for base in bases:
+ candidate = base / 'images' / 'image_sources.json'
+ if candidate.exists():
+ return candidate
+ return None
+
+ def _load_image_sources_manifest(
+ self,
+ svg_path: Path,
+ ) -> Tuple[Dict, str | None, Path | None]:
+ manifest_path = self._find_image_sources_manifest(svg_path)
+ if manifest_path is None:
+ return {}, None, None
+ payload, error = self._read_image_sources_manifest(manifest_path)
+ return payload, error, manifest_path
+
+ def _read_image_sources_manifest(
+ self,
+ manifest_path: Path,
+ ) -> Tuple[Dict, str | None]:
+ """Read one provenance manifest without accepting damaged state."""
+ if manifest_path in self._source_manifest_cache:
+ return self._source_manifest_cache[manifest_path]
+ try:
+ payload = json.loads(manifest_path.read_text(encoding='utf-8'))
+ except (OSError, json.JSONDecodeError) as exc:
+ payload = {}
+ error = f"cannot read {manifest_path}: {exc}"
+ else:
+ if not isinstance(payload, dict):
+ error = f"{manifest_path} must contain a JSON object"
+ payload = {}
+ elif not isinstance(payload.get('items'), list):
+ error = f"{manifest_path} must contain an items array"
+ payload = {}
+ elif any(not isinstance(item, dict) for item in payload['items']):
+ error = f"{manifest_path} items must contain JSON objects"
+ payload = {}
+ else:
+ seen_filenames: set[str] = set()
+ error = None
+ for index, item in enumerate(payload['items']):
+ filename = item.get('filename')
+ if (
+ not isinstance(filename, str)
+ or not filename.strip()
+ or filename in {'.', '..'}
+ or '/' in filename
+ or '\\' in filename
+ or ':' in filename
+ or Path(filename).is_absolute()
+ ):
+ error = (
+ f"{manifest_path} items[{index}].filename must be "
+ "a non-empty bare filename"
+ )
+ break
+ if filename in seen_filenames:
+ error = (
+ f"{manifest_path} contains duplicate filename "
+ f"{filename!r}"
+ )
+ break
+ seen_filenames.add(filename)
+ if error:
+ payload = {}
+ self._source_manifest_cache[manifest_path] = (payload, error)
+ return payload, error
+
+ @staticmethod
+ def _external_image_reference_basename(href: str) -> str | None:
+ """Return a decoded basename for one local external image href."""
+ if not href or href.startswith('data:'):
+ return None
+ decoded_href = html.unescape(href)
+ parsed = urlsplit(decoded_href)
+ if parsed.scheme and parsed.scheme != 'file':
+ return None
+ path_part = (
+ parsed.path
+ if parsed.scheme
+ else decoded_href.split('?', 1)[0].split('#', 1)[0]
+ )
+ return Path(unquote(path_part)).name or None
+
+ @classmethod
+ def _referenced_image_basenames(cls, root: ET.Element) -> set[str]:
+ """Return external image basenames rendered by one parsed SVG."""
+ filenames = set()
+ _working_root, _parent_by_id, images = cls._visible_image_elements(root)
+ for elem in images:
+ href = elem.get('href') or elem.get(f'{{{XLINK_NS}}}href')
+ filename = cls._external_image_reference_basename(href or '')
+ if filename:
+ filenames.add(filename)
+ return filenames
+
+ def _check_sourced_image_attribution(
+ self,
+ root: ET.Element,
+ svg_path: Path,
+ result: Dict,
+ ):
+ """Require visible credit text for attribution-required web images.
+
+ image_search.py records the legal tier in images/image_sources.json;
+ Executor must render compact credit text into the SVG. This check
+ binds each credit to the referenced image's author and license instead
+ of accepting one generic deck-level CC token.
+ """
+ manifest, error, manifest_path = self._load_image_sources_manifest(svg_path)
+ if error:
+ if (
+ manifest_path is not None
+ and manifest_path not in self._source_manifest_errors_reported
+ ):
+ result['errors'].append(
+ f"Invalid image source manifest: {error}"
+ )
+ self._source_manifest_errors_reported.add(manifest_path)
+ return
+
+ items = manifest.get('items') or []
+ if not items:
+ return
+
+ credit_blocks = self._visible_svg_text_blocks(root)
+ referenced_filenames = self._referenced_image_basenames(root)
+
+ for item in items:
+ if not item.get('attribution_required') and item.get('license_tier') != 'attribution-required':
+ continue
+
+ filename = str(item.get('filename') or '')
+ if not filename or filename not in referenced_filenames:
+ continue
+
+ license_name = str(item.get('license_name') or '').upper()
+ license_token = 'CC BY-SA' if 'BY-SA' in license_name else 'CC BY'
+ author = str(item.get('author') or '').strip()
+ has_credit = bool(author) and any(
+ author.casefold() in block.casefold()
+ and license_token in block.upper()
+ for block in credit_blocks
+ )
+ if not has_credit:
+ result['errors'].append(
+ f"Missing image-specific inline attribution for sourced "
+ f"image {filename} ({author or 'unknown author'}; "
+ f"{license_token}). Add compact author + license credit per "
+ f"references/image-searcher.md §7."
+ )
+
+ @classmethod
+ def _visible_svg_text_blocks(cls, root: ET.Element) -> List[str]:
+ """Return rendered text blocks, excluding hidden/non-visual content."""
+ working_root = copy.deepcopy(root)
+ if (
+ _expand_local_use_references is not None
+ and _UseExpansionError is not None
+ ):
+ try:
+ _expand_local_use_references(working_root)
+ except _UseExpansionError:
+ working_root = copy.deepcopy(root)
+ parent_by_id = {
+ id(child): parent
+ for parent in working_root.iter()
+ for child in list(parent)
+ }
+
+ blocks: List[str] = []
+ for element in working_root.iter(f'{{{SVG_NS}}}text'):
+ if (
+ cls._is_hidden_element(element, parent_by_id)
+ or cls._has_non_visual_ancestor(
+ element,
+ working_root,
+ parent_by_id,
+ )
+ or cls._has_zero_opacity(element, parent_by_id)
+ ):
+ continue
+ text = re.sub(r'\s+', ' ', ' '.join(element.itertext())).strip()
+ if text:
+ blocks.append(text)
+ return blocks
+
+ @staticmethod
+ def _normalize_size(value: str) -> str:
+ """Normalize a font-size value for drift comparison.
+
+ Unit-bearing SVG values are reported as errors before drift checking.
+ The legacy `px` strip remains to avoid a duplicate drift warning after
+ the hard error has already identified the unit problem.
+ """
+ v = value.strip().lower()
+ if v.endswith('px'):
+ v = v[:-2].strip()
+ return v
+
+ @staticmethod
+ def _normalize_font_stack(stack: str) -> str:
+ """Normalize a font-family stack for comparison: split on commas, strip
+ quotes / whitespace, lowercase, rejoin. Collapses cosmetic differences
+ (comma spacing, single vs double quotes, case) so that
+ `Consolas,'Courier New',monospace` matches `Consolas, "Courier New", monospace`."""
+ parts = [p.strip().strip('"\'').lower() for p in stack.split(',')]
+ return ','.join(p for p in parts if p)
+
+ def _categorize_issue(self, error_msg: str) -> str:
+ """Categorize issue type"""
+ if 'Invalid XML' in error_msg:
+ return 'XML well-formedness'
+ elif 'viewBox' in error_msg:
+ return 'viewBox issues'
+ elif 'foreignObject' in error_msg:
+ return 'foreignObject'
+ elif 'paint' in error_msg.lower() or 'color value' in error_msg.lower():
+ return 'Paint issues'
+ elif 'font' in error_msg.lower():
+ return 'Font issues'
+ else:
+ return 'Other'
+
+ def _configure_prototype_context(
+ self,
+ target_path: Path,
+ svg_files: List[Path],
+ ) -> None:
+ """Map generated pages to selected prototypes for inherited diagnostics."""
+ self._prototype_by_output = {}
+ self._active_prototype_path = None
+ self._active_template_reuse_scope = None
+ self._source_import_summary = {
+ 'warning_count': 0,
+ 'by_code': {},
+ }
+ if (
+ self.template_mode
+ or self.quick_generate
+ or _load_pptx_structure_lock is None
+ ):
+ return
+ project_path = self._resolve_project_path(target_path)
+ try:
+ structure_lock = _load_pptx_structure_lock(project_path)
+ except (_TemplateStructureError, OSError):
+ # The project-level structure gate reports the actionable parser
+ # error. Inherited classification is optional and stays silent.
+ return
+ if structure_lock is None:
+ return
+ self._active_template_reuse_scope = getattr(
+ structure_lock,
+ 'template_reuse_scope',
+ None,
+ )
+ references = {
+ reference.slide_num: reference.svg_path
+ for reference in structure_lock.prototypes
+ }
+ if target_path.is_file():
+ sibling_files = discover_slide_svgs(target_path.parent)
+ resolved_target = target_path.resolve()
+ slide_num = next(
+ (
+ index
+ for index, sibling in enumerate(sibling_files, start=1)
+ if sibling.resolve() == resolved_target
+ ),
+ 1,
+ )
+ prototype = references.get(slide_num)
+ if prototype is not None:
+ self._prototype_by_output[resolved_target] = prototype.resolve()
+ else:
+ for slide_num, svg_path in enumerate(svg_files, start=1):
+ prototype = references.get(slide_num)
+ if prototype is not None:
+ self._prototype_by_output[svg_path.resolve()] = prototype.resolve()
+
+ if self._active_template_reuse_scope not in {'mirror', 'layout'}:
+ return
+ manifest_path = (
+ project_path / 'templates' / 'template_execution_manifest.json'
+ )
+ try:
+ manifest = json.loads(manifest_path.read_text(encoding='utf-8'))
+ except (FileNotFoundError, OSError, json.JSONDecodeError):
+ return
+ if manifest.get('schema') != 'ppt-master.template-execution-manifest.v1':
+ return
+ source_import = manifest.get('source_import')
+ if isinstance(source_import, dict):
+ self._source_import_summary = source_import
+
+ def check_directory(self, directory: str, expected_format: str = None) -> List[Dict]:
+ """
+ Check all SVG files in a directory
+
+ Args:
+ directory: Directory path
+ expected_format: Expected canvas format
+
+ Returns:
+ List of check results
+ """
+ dir_path = Path(directory)
+ self._has_incomplete_page_roster = False
+ self._undeclared_size_occurrences = Counter()
+ self._undeclared_size_counts_ready = False
+
+ if not dir_path.exists():
+ print(f"[ERROR] Directory does not exist: {directory}")
+ self.summary['errors'] += 1
+ self.issue_types['Input issues'] += 1
+ return []
+
+ # Brand-only workspaces have no SVG roster. Validate their portable
+ # identity schema through the same authority used by library
+ # registration, while keeping project scope independent of global
+ # indexes and directory names.
+ if self.template_mode and dir_path.is_dir():
+ nested_spec = dir_path / 'templates' / 'design_spec.md'
+ spec = nested_spec if nested_spec.is_file() else dir_path / 'design_spec.md'
+ if spec.exists() and _design_spec_is_brand(spec):
+ self._brand_template_checked = True
+ self.summary['total'] += 1
+ brand_valid = True
+ print(
+ f"[INFO] Brand directory detected (kind: brand) — "
+ f"validating design_spec.md and referenced assets."
+ )
+ workspace_root = (
+ spec.parent.parent
+ if spec.parent.name == 'templates'
+ else spec.parent
+ )
+ try:
+ from register_template import (
+ SpecParseError,
+ validate_brand_workspace,
+ )
+ validate_brand_workspace(workspace_root)
+ except ImportError as exc:
+ brand_valid = False
+ self._template_issues.append((
+ 'error',
+ 'brand_contract',
+ f"Brand schema validator could not be imported: {exc}",
+ ))
+ except (OSError, SpecParseError) as exc:
+ brand_valid = False
+ self._template_issues.append((
+ 'error',
+ 'brand_contract',
+ str(exc),
+ ))
+ if brand_valid:
+ self.summary['passed'] += 1
+ return self.results
+
+ # Find all SVG files
+ if dir_path.is_file():
+ svg_files = [dir_path]
+ else:
+ if self.template_mode:
+ # Template directories live at templates/{layouts,decks}/<id>/.
+ svg_files = discover_slide_svgs(dir_path)
+ else:
+ svg_output = dir_path / \
+ 'svg_output' if (
+ dir_path / 'svg_output').exists() else dir_path
+ svg_files = discover_slide_svgs(svg_output)
+
+ if not svg_files:
+ print(f"[ERROR] No SVG files found in: {directory}")
+ self.summary['errors'] += 1
+ self.issue_types['Input issues'] += 1
+ return []
+
+ self._configure_prototype_context(dir_path, svg_files)
+ if not self.template_mode:
+ self._prepare_undeclared_size_occurrences(svg_files)
+
+ directory_expected_viewbox: str | None = None
+ directory_expected_label = "the first SVG canvas"
+ directory_lock_has_canvas = False
+ if self.template_mode:
+ template_viewbox = _declared_template_canvas_viewbox(dir_path)
+ if template_viewbox:
+ directory_expected_viewbox = template_viewbox
+ directory_expected_label = "design_spec canvas_viewbox"
+ else:
+ directory_expected_viewbox = ""
+ directory_expected_label = "design_spec canvas_viewbox"
+ if expected_format is None and directory_expected_viewbox is None:
+ lock = (
+ None
+ if self.template_mode
+ else self._get_spec_lock(svg_files[0])
+ )
+ if lock is not None:
+ if 'canvas' in lock:
+ directory_lock_has_canvas = True
+ locked_viewbox = lock.get('canvas', {}).get('viewBox')
+ if locked_viewbox:
+ directory_expected_viewbox = locked_viewbox
+ directory_expected_label = "spec_lock canvas"
+ else:
+ directory_expected_viewbox = ""
+ directory_expected_label = "spec_lock canvas"
+ if (
+ directory_expected_viewbox is None
+ and not directory_lock_has_canvas
+ ):
+ for svg_file in svg_files:
+ try:
+ root = ET.parse(svg_file).getroot()
+ first_canvas = parse_project_viewbox(
+ root.get('viewBox'),
+ context=f"{svg_file.name} root viewBox",
+ )
+ except (OSError, ET.ParseError, CanvasContractError):
+ continue
+ directory_expected_viewbox = first_canvas.canonical
+ directory_expected_label = f"first SVG {svg_file.name}"
+ break
+
+ print(f"\n[SCAN] Checking {len(svg_files)} SVG file(s)...\n")
+
+ for svg_file in svg_files:
+ self._active_prototype_path = self._prototype_by_output.get(
+ svg_file.resolve()
+ )
+ result = self.check_file(
+ str(svg_file),
+ expected_format,
+ expected_viewbox=directory_expected_viewbox,
+ expected_viewbox_label=directory_expected_label,
+ )
+ self._print_result(result)
+
+ if self.template_mode:
+ check_structure = _template_structure_checks_enabled(dir_path)
+ if check_structure:
+ self._check_pptx_structure_contract(dir_path, svg_files)
+ if dir_path.is_dir():
+ self._check_template_contract(
+ dir_path,
+ svg_files,
+ check_structure=check_structure,
+ )
+ elif _CHECK_PPTX_STRUCTURED_PROJECT:
+ self._check_pptx_structure_contract(dir_path, svg_files)
+ if (
+ not self.template_mode
+ and not self.quick_generate
+ and dir_path.is_dir()
+ ):
+ self._check_animation_config_contract(dir_path)
+ self._check_illustration_resource_contract(dir_path)
+ if (
+ not self.template_mode
+ and not self.quick_generate
+ and validate_communication_trace is not None
+ ):
+ project_path = self._resolve_project_path(dir_path)
+ self._communication_trace_issues.extend(
+ ('error', message)
+ for message in validate_communication_trace(project_path)
+ )
+
+ return self.results
+
+ def _check_pptx_structure_contract(
+ self,
+ target_path: Path,
+ svg_files: List[Path],
+ ) -> None:
+ """Validate the all-page structured lock and reusable contracts."""
+ if self.quick_generate:
+ return
+ project_path = self._resolve_project_path(target_path)
+ standard_project = bool(
+ not self.template_mode
+ and (project_path / 'svg_output').is_dir()
+ )
+ declared_mode = (
+ _declared_pptx_structure_mode(project_path)
+ if standard_project
+ else None
+ )
+ if standard_project and declared_mode in {'flat', 'structured'}:
+ self._pptx_structure_issues.extend(
+ ('error', message)
+ for message in _generated_theme_contract_errors(project_path)
+ )
+ if standard_project and declared_mode == 'flat':
+ if (
+ _load_pptx_structure_lock is None
+ or _TemplateStructureError is None
+ ):
+ self._pptx_structure_issues.append((
+ 'error',
+ 'Flat PPTX project validation is unavailable because the '
+ 'template_structure module could not be imported.',
+ ))
+ return
+ try:
+ structure_lock = _load_pptx_structure_lock(project_path)
+ except _TemplateStructureError as exc:
+ self._pptx_structure_issues.append(('error', str(exc)))
+ return
+ if structure_lock is None or structure_lock.mode != 'flat':
+ self._pptx_structure_issues.append((
+ 'error',
+ 'spec_lock.md must contain one complete '
+ 'pptx_structure.mode: flat contract.',
+ ))
+ return
+ has_metadata = False
+ for svg_path in svg_files:
+ try:
+ root = ET.parse(svg_path).getroot()
+ except (OSError, ET.ParseError):
+ continue
+ if any(
+ elem.get(attr) is not None
+ for elem in root.iter()
+ for attr in _PPTX_STRUCTURE_ATTRS
+ ):
+ has_metadata = True
+ break
+
+ if not standard_project and not self.template_mode and not has_metadata:
+ return
+ if (
+ _load_pptx_structure_lock is None
+ or _parse_template_structure_slide is None
+ or _parse_template_structure_slides is None
+ or _structure_subtree_signature is None
+ or _template_lock_errors is None
+ or _TemplateStructureError is None
+ ):
+ self._pptx_structure_issues.append((
+ 'error',
+ 'Structured PPTX project validation is unavailable because the '
+ 'template_structure module could not be imported.',
+ ))
+ return
+
+ if self.template_mode:
+ try:
+ specs = _parse_template_structure_slides(svg_files)
+ except _TemplateStructureError as exc:
+ self._pptx_structure_issues.append(('error', str(exc)))
+ return
+ self._pptx_structure_issues.extend(
+ ('error', message)
+ for message in self._shared_fixed_layer_errors(specs)
+ )
+ self._pptx_structure_issues.extend(
+ ('warning', message)
+ for message in self._duplicate_layout_key_warnings(specs)
+ )
+ return
+
+ if standard_project and declared_mode != 'structured':
+ label = repr(declared_mode) if declared_mode else (
+ 'missing (legacy implicit baseline)'
+ )
+ self._pptx_structure_issues.append((
+ 'error',
+ 'release SVG projects require an explicit spec_lock.md '
+ 'pptx_structure.mode: flat (free design / brand-only) or '
+ f'structured (deck/layout template); found {label}. New '
+ 'free-design projects use mode: flat; create a new template '
+ 'workspace through skills/ppt-master/workflows/create-template.md, '
+ 'then generate new structured SVG pages before export. Existing '
+ 'PPTX/SVG files are not upgraded in place.',
+ ))
+ return
+
+ try:
+ structure_lock = _load_pptx_structure_lock(project_path)
+ except _TemplateStructureError as exc:
+ self._pptx_structure_issues.append(('error', str(exc)))
+ return
+ if structure_lock is None or structure_lock.mode != 'structured':
+ self._pptx_structure_issues.append((
+ 'error',
+ 'spec_lock.md must contain one complete '
+ 'pptx_structure.mode: structured contract.',
+ ))
+ return
+ complete_roster = target_path.is_dir()
+ try:
+ if not complete_roster and target_path.is_file():
+ sibling_files = discover_slide_svgs(target_path.parent)
+ resolved_target = target_path.resolve()
+ slide_num = next(
+ (
+ index
+ for index, sibling in enumerate(sibling_files, start=1)
+ if sibling.resolve() == resolved_target
+ ),
+ 1,
+ )
+ specs = [
+ _parse_template_structure_slide(target_path, slide_num)
+ ]
+ else:
+ specs = _parse_template_structure_slides(svg_files)
+ except _TemplateStructureError as exc:
+ self._pptx_structure_issues.append(('error', str(exc)))
+ return
+
+ if complete_roster:
+ actual_slides = {spec.slide_num for spec in specs}
+ expected_slides = {
+ reference.slide_num
+ for reference in structure_lock.layouts
+ }
+ expected_slides.update(
+ reference.slide_num
+ for reference in structure_lock.prototypes
+ )
+ self._has_incomplete_page_roster = bool(
+ expected_slides - actual_slides
+ )
+ self._pptx_structure_issues.extend(
+ ('error', message)
+ for message in _template_lock_errors(specs, structure_lock)
+ )
+ else:
+ self._pptx_structure_issues.extend(
+ ('error', message)
+ for message in self._partial_structure_lock_errors(
+ specs,
+ structure_lock,
+ )
+ )
+ if _template_prototype_errors is not None:
+ self._pptx_structure_issues.extend(
+ ('error', message)
+ for message in _template_prototype_errors(
+ specs,
+ structure_lock,
+ require_complete_roster=complete_roster,
+ )
+ )
+ self._pptx_structure_issues.extend(
+ ('error', message)
+ for message in self._shared_fixed_layer_errors(specs)
+ )
+ self._pptx_structure_issues.extend(
+ ('warning', message)
+ for message in self._duplicate_layout_key_warnings(specs)
+ )
+
+ @staticmethod
+ def _partial_structure_lock_errors(specs, structure_lock) -> List[str]:
+ """Compare explicitly checked pages without requiring the full roster."""
+ references = {
+ reference.slide_num: reference
+ for reference in structure_lock.layouts
+ }
+ master_names = {
+ master.master_key: master.master_name
+ for master in structure_lock.masters
+ }
+ definitions = {
+ definition.layout_key: definition
+ for definition in structure_lock.layout_definitions
+ }
+ errors: List[str] = []
+ for spec in specs:
+ page = f"P{spec.slide_num:02d}"
+ reference = references.get(spec.slide_num)
+ if reference is None:
+ errors.append(
+ f"spec_lock.md page_pptx_layouts is missing {page}"
+ )
+ continue
+ definition = definitions.get(reference.layout_key)
+ if definition is None:
+ errors.append(
+ f"spec_lock.md pptx_layouts is missing Layout "
+ f"{reference.layout_key!r}"
+ )
+ continue
+ if spec.master_key != definition.master_key:
+ errors.append(
+ f"{spec.svg_path.name}: data-pptx-master={spec.master_key!r} "
+ f"does not match spec_lock Layout {reference.layout_key!r} "
+ f"Master key {definition.master_key!r}"
+ )
+ if spec.layout_key != reference.layout_key:
+ errors.append(
+ f"{spec.svg_path.name}: data-pptx-layout={spec.layout_key!r} "
+ f"does not match spec_lock {page} layout key "
+ f"{reference.layout_key!r}"
+ )
+ if spec.layout_name != definition.layout_name:
+ errors.append(
+ f"{spec.svg_path.name}: data-pptx-layout-name="
+ f"{spec.layout_name!r} does not match spec_lock Layout "
+ f"{reference.layout_key!r} name {definition.layout_name!r}"
+ )
+ expected_master_name = master_names.get(spec.master_key)
+ if expected_master_name != spec.master_name:
+ errors.append(
+ f"{spec.svg_path.name}: data-pptx-master-name="
+ f"{spec.master_name!r} does not match spec_lock Master "
+ f"{spec.master_key!r} name {expected_master_name!r}"
+ )
+ return errors
+
+ def _duplicate_layout_key_warnings(self, specs) -> List[str]:
+ """Flag distinct layout keys whose static contracts are identical.
+
+ Keys split by page topic over one shared skeleton compile into
+ duplicate PowerPoint Layouts; the fingerprint compares the
+ id-insensitive layout-layer drawing plus the placeholder contract.
+ """
+ prototypes: Dict[Tuple[str, str], Path] = {}
+ for spec in specs:
+ prototypes.setdefault(
+ (getattr(spec, 'master_key', ''), spec.layout_key),
+ spec.svg_path,
+ )
+ if len(prototypes) < 2:
+ return []
+ fingerprint_keys: Dict[tuple, List[str]] = {}
+ for (master_key, layout_key), svg_path in prototypes.items():
+ fingerprint = self._layout_contract_fingerprint(svg_path)
+ if fingerprint is None:
+ continue
+ fingerprint_keys.setdefault(
+ (master_key, fingerprint),
+ [],
+ ).append(layout_key)
+ messages = []
+ for keys in fingerprint_keys.values():
+ if len(keys) < 2:
+ continue
+ joined = ', '.join(sorted(keys))
+ messages.append(
+ f"layout keys {joined} declare identical static Layout framing "
+ "and placeholder contracts; they compile to duplicate Layouts. "
+ "Either merge them into one reusable key (spec_lock.md "
+ "pptx_layouts + each SVG root), or — when their reusable "
+ "contracts genuinely differ — assign distinct explicit default "
+ "placeholder bounds and/or mark only truly stable framing as "
+ 'data-pptx-layer="layout". Slide-local content geometry does not '
+ "define a Layout. This recommendation is advisory; no change or "
+ "disposition is required."
+ )
+ return messages
+
+ @classmethod
+ def _shared_fixed_layer_errors(cls, specs) -> List[str]:
+ """Reject fixed atoms whose payload varies inside one reuse scope."""
+ master_groups = defaultdict(list)
+ layout_groups = defaultdict(list)
+ for spec in specs:
+ master_groups[spec.master_key].append(spec)
+ layout_groups[(spec.master_key, spec.layout_key)].append(spec)
+
+ try:
+ errors = cls._fixed_layer_group_errors(master_groups, 'master')
+ errors.extend(cls._fixed_layer_group_errors(layout_groups, 'layout'))
+ except _TemplateStructureError as exc:
+ return [str(exc)]
+ return errors
+
+ @classmethod
+ def _fixed_layer_group_errors(cls, groups, layer: str) -> List[str]:
+ """Compare fixed atom payloads across grouped slide specifications."""
+ errors = []
+ for scope_key, group_specs in groups.items():
+ if len(group_specs) < 2:
+ continue
+ variants = defaultdict(lambda: defaultdict(list))
+ for spec in group_specs:
+ payloads = cls._fixed_layer_payloads(spec, layer)
+ for element_id, payload in payloads.items():
+ variants[element_id][payload].append(spec)
+ for element_id, payload_specs in variants.items():
+ if len(payload_specs) < 2:
+ continue
+ slide_names = ', '.join(
+ spec.svg_path.name
+ for spec in sorted(group_specs, key=lambda item: item.slide_num)
+ )
+ if layer == 'master':
+ scope = f"Master {scope_key!r}"
+ else:
+ master_key, layout_key = scope_key
+ scope = (
+ f"Layout {layout_key!r} under Master {master_key!r}"
+ )
+ if element_id is None:
+ subject = "fixed visual resources"
+ verb = "differ"
+ else:
+ subject = f"fixed element {element_id!r}"
+ verb = "differs"
+ errors.append(
+ f"{scope} {subject} {verb} across slides: "
+ f"{slide_names}. Values marked data-pptx-layer={layer!r} must "
+ "remain identical throughout their reuse scope; move variable "
+ "text or images into a placeholder slot or keep them Slide-local."
+ )
+ return errors
+
+ @staticmethod
+ def _fixed_layer_payloads(spec, layer: str) -> Dict[object, tuple]:
+ """Return resolved fixed-layer visual payloads keyed by SVG id."""
+ elements = (
+ spec.master_elements if layer == 'master' else spec.layout_elements
+ )
+ if not elements:
+ return {}
+ signature = _structure_subtree_signature(
+ spec.svg_path,
+ elements,
+ include_skin=True,
+ include_text=True,
+ asset_identity=True,
+ )
+ return {
+ None if element_id == '__visual_resources__' else element_id: payload
+ for element_id, payload in signature
+ }
+
+ @staticmethod
+ def _layout_contract_fingerprint(svg_path: Path):
+ """Id-insensitive static contract: layout-layer XML + placeholder slots."""
+ try:
+ root = ET.parse(str(svg_path)).getroot()
+ except (OSError, ET.ParseError):
+ return None
+ layout_parts = []
+ placeholder_parts = []
+ for child in list(root):
+ if child.get('data-pptx-layer') == 'layout':
+ clone = copy.deepcopy(child)
+ for elem in clone.iter():
+ elem.attrib.pop('id', None)
+ xml = ET.tostring(clone, encoding='unicode')
+ layout_parts.append(re.sub(r'\s+', ' ', xml).strip())
+ placeholder = child.get('data-pptx-placeholder')
+ if placeholder is not None:
+ carrier_tags = tuple(
+ grandchild.tag.rsplit('}', 1)[-1]
+ for grandchild in list(child)
+ if (
+ grandchild.get('data-pptx-carrier') or ''
+ ).strip().lower() == 'true'
+ )
+ placeholder_parts.append((
+ placeholder,
+ child.tag.rsplit('}', 1)[-1],
+ child.get('data-pptx-bounds') or '',
+ child.get('data-pptx-idx') or '',
+ (
+ child.get('data-pptx-binding') or 'carrier'
+ ).strip().lower(),
+ carrier_tags,
+ ))
+ return (
+ tuple(layout_parts),
+ tuple(sorted(placeholder_parts)),
+ )
+
+ def _check_illustration_resource_contract(self, dir_path: Path) -> None:
+ """Project-level planned-image and illustration resource checks."""
+ project_path = self._resolve_project_path(dir_path)
+ spec_path = project_path / 'design_spec.md'
+ if not spec_path.exists():
+ return
+
+ try:
+ spec_text = spec_path.read_text(encoding='utf-8')
+ except OSError as exc:
+ self._illustration_issues.append((
+ 'warning',
+ 'spec_unreadable',
+ f"could not read {spec_path}: {exc}",
+ ))
+ return
+
+ current_contract = (
+ '<!-- ppt-master-schema: design-spec/v1 -->' in spec_text
+ )
+ rows = self._extract_image_resource_rows(spec_text)
+ if not rows and not current_contract:
+ return
+
+ lock_entries, lock_error = self._load_project_lock_image_entries(
+ project_path
+ )
+ lock_images = set(lock_entries)
+ svg_references, inline_image_counts, image_placements = (
+ self._load_project_svg_image_references(project_path)
+ )
+ all_svg_references = (
+ set().union(*(
+ set(references)
+ for references in svg_references.values()
+ ))
+ if svg_references
+ else set()
+ )
+
+ sheet_rows = [
+ row
+ for row in rows
+ if self._row_type(row).lower() == 'illustration sheet'
+ ]
+ slice_rows = [row for row in rows if self._row_acquire(row) == 'slice']
+ for row in sheet_rows:
+ filename = self._row_filename(row)
+ if not filename:
+ continue
+ if filename in lock_images:
+ self._illustration_issues.append((
+ 'error',
+ 'sheet_in_lock',
+ f"{filename} is an Illustration Sheet but is listed in spec_lock.md images; "
+ "only sliced element rows may be listed.",
+ ))
+ if filename in all_svg_references:
+ self._illustration_issues.append((
+ 'error',
+ 'sheet_referenced',
+ f"{filename} is an Illustration Sheet but is referenced by an SVG; "
+ "generate it only as a slice source, never place it.",
+ ))
+ if (
+ self._row_status(row) == 'generated'
+ and not (project_path / 'images' / filename).is_file()
+ ):
+ self._illustration_issues.append((
+ 'error',
+ 'sheet_file_missing',
+ f"{filename} is a Generated Illustration Sheet but "
+ f"images/{filename} does not exist.",
+ ))
+
+ if current_contract:
+ self._check_planned_image_closure(
+ rows,
+ project_path,
+ lock_entries,
+ lock_error,
+ svg_references,
+ inline_image_counts,
+ image_placements,
+ )
+ else:
+ for row in slice_rows:
+ filename = self._row_filename(row)
+ if not filename:
+ continue
+ if filename not in lock_images:
+ self._illustration_issues.append((
+ 'error',
+ 'slice_missing_lock',
+ f"{filename} is a slice row but is absent from spec_lock.md images.",
+ ))
+ if (
+ self._row_status(row) == 'generated'
+ and not (project_path / 'images' / filename).exists()
+ ):
+ self._illustration_issues.append((
+ 'error',
+ 'slice_file_missing',
+ f"{filename} is a Generated slice row but "
+ f"images/{filename} does not exist.",
+ ))
+
+ @staticmethod
+ def _resolve_project_path(dir_path: Path) -> Path:
+ """Resolve a checker target directory to its project root."""
+ candidate = dir_path.parent if dir_path.is_file() else dir_path
+ if (
+ _project_root_for_svg_path is not None
+ and candidate.name in _SVG_WORK_DIR_NAMES
+ ):
+ return _project_root_for_svg_path(candidate)
+ if (
+ (candidate / 'svg_output').exists()
+ or (candidate / 'design_spec.md').exists()
+ ):
+ return candidate
+ return candidate.parent
+
+ @staticmethod
+ def _split_md_table_row(line: str) -> List[str]:
+ """Split a simple Markdown table row into stripped cells."""
+ return [cell.strip().strip('`') for cell in line.strip().strip('|').split('|')]
+
+ @classmethod
+ def _extract_image_resource_rows(cls, spec_text: str) -> List[Dict[str, str]]:
+ """Extract rows from design_spec.md §VIII Image Resource List."""
+ section_match = re.search(
+ r"^##\s+VIII\.\s+Image Resource List\b.*?(?=^##\s+|\Z)",
+ spec_text,
+ re.MULTILINE | re.DOTALL,
+ )
+ if not section_match:
+ return []
+
+ lines = section_match.group(0).splitlines()
+ header = None
+ rows: List[Dict[str, str]] = []
+ in_resource_table = False
+ for line in lines:
+ if not line.strip().startswith('|'):
+ if in_resource_table and rows:
+ break
+ continue
+
+ cells = cls._split_md_table_row(line)
+ if not cells:
+ continue
+ if header is None:
+ if any(cell.lower() == 'filename' for cell in cells):
+ header = cells
+ in_resource_table = True
+ continue
+ if set(cell.replace('-', '').strip() for cell in cells) == {''}:
+ continue
+ if not in_resource_table:
+ continue
+ row = {header[i]: cells[i] if i < len(cells) else '' for i in range(len(header))}
+ filename = row.get('Filename', '').strip()
+ if (
+ filename.lower() != 'filename'
+ and any(value.strip() for value in row.values())
+ ):
+ rows.append(row)
+
+ return rows
+
+ @staticmethod
+ def _row_filename(row: Dict[str, str]) -> str:
+ return Path(row.get('Filename', '').strip()).name
+
+ @staticmethod
+ def _row_raw_filename(row: Dict[str, str]) -> str:
+ return row.get('Filename', '').strip()
+
+ @staticmethod
+ def _row_type(row: Dict[str, str]) -> str:
+ return row.get('Type', '').strip()
+
+ @staticmethod
+ def _row_acquire(row: Dict[str, str]) -> str:
+ return row.get('Acquire Via', '').strip().lower()
+
+ @staticmethod
+ def _row_status(row: Dict[str, str]) -> str:
+ return row.get('Status', '').strip().lower()
+
+ @staticmethod
+ def _row_layout(row: Dict[str, str]) -> str:
+ return row.get('Layout pattern', '').strip()
+
+ @staticmethod
+ def _row_crop(row: Dict[str, str]) -> str:
+ return row.get('Crop Policy', '').strip().lower()
+
+ @staticmethod
+ def _layout_projection_matches(left: str, right: str) -> bool:
+ """Compare one Strategist recommendation without locking its wording."""
+ left_ids = re.findall(r'#([0-9]+)(?![0-9])', left)
+ right_ids = re.findall(r'#([0-9]+)(?![0-9])', right)
+ if left_ids or right_ids:
+ return left_ids == right_ids
+
+ def normalize(value: str) -> str:
+ return re.sub(r'\s+', ' ', value.replace('`', '')).strip()
+
+ return normalize(left) == normalize(right)
+
+ def _load_project_lock_image_entries(
+ self,
+ project_path: Path,
+ ) -> Tuple[Dict[str, List[Dict[str, str]]], str | None]:
+ """Return parsed image-lock rows keyed by basename."""
+ lock_path = project_path / 'spec_lock.md'
+ if not lock_path.exists():
+ return {}, f"{lock_path} does not exist"
+ if _parse_spec_lock is None:
+ return {}, "spec_lock parser is unavailable"
+ if _parse_spec_lock_image_value is None:
+ return {}, "spec_lock image parser is unavailable"
+ try:
+ lock = _parse_spec_lock(lock_path)
+ except Exception as exc:
+ return {}, f"cannot parse {lock_path}: {exc}"
+
+ entries: Dict[str, List[Dict[str, str]]] = defaultdict(list)
+ legacy_metadata_keys = {
+ 'image_rendering',
+ 'image_rendering_references',
+ 'image_rendering_behavior',
+ }
+ errors: List[str] = []
+ for key, value in lock.get('images', {}).items():
+ if str(key).strip().lower() in legacy_metadata_keys:
+ continue
+ try:
+ parsed = _parse_spec_lock_image_value(str(key), str(value))
+ except ValueError as exc:
+ errors.append(f"images row {key!r} {exc}")
+ continue
+ path_part = parsed['path']
+ filename = Path(path_part).name
+ if not filename:
+ continue
+ entries[filename].append({
+ 'key': str(key),
+ 'path': path_part,
+ 'source': parsed['source'],
+ 'pattern': parsed['pattern'],
+ 'crop': parsed['crop'],
+ 'legacy': parsed['legacy'],
+ })
+ error = (
+ f"{lock_path}: " + "; ".join(errors)
+ if errors
+ else None
+ )
+ return dict(entries), error
+
+ def _load_project_lock_images(self, project_path: Path) -> set[str]:
+ """Return filenames listed under spec_lock.md images."""
+ entries, _error = self._load_project_lock_image_entries(project_path)
+ return set(entries)
+
+ @classmethod
+ def _load_project_svg_image_references(
+ cls,
+ project_path: Path,
+ ) -> Tuple[
+ Dict[Path, Dict[str, set[Path]]],
+ Dict[Path, int],
+ Dict[str, List[Tuple[Path, str, Tuple[str, ...]]]],
+ ]:
+ """Parse rendered image instances, paths, and crop mechanisms."""
+ svg_dir = project_path / 'svg_output'
+ if not svg_dir.exists():
+ return {}, {}, {}
+ out: Dict[Path, Dict[str, set[Path]]] = {}
+ inline_counts: Dict[Path, int] = {}
+ placements: Dict[
+ str,
+ List[Tuple[Path, str, Tuple[str, ...]]],
+ ] = defaultdict(list)
+ for svg_path in discover_slide_svgs(svg_dir):
+ try:
+ root = ET.parse(svg_path).getroot()
+ except (OSError, ET.ParseError):
+ continue
+ working_root, parent_by_id, images = cls._visible_image_elements(root)
+ references: Dict[str, set[Path]] = defaultdict(set)
+ inline_count = 0
+ for element in images:
+ href = (
+ element.get('href')
+ or element.get(f'{{{XLINK_NS}}}href')
+ or ''
+ )
+ if href.lstrip().lower().startswith('data:'):
+ inline_count += 1
+ continue
+ filename = cls._external_image_reference_basename(href)
+ if not filename:
+ continue
+ references.setdefault(filename, set())
+ placements[filename].append((
+ svg_path,
+ element.get('preserveAspectRatio') or '',
+ cls._image_crop_mechanisms(
+ element,
+ working_root,
+ parent_by_id,
+ ),
+ ))
+ if _resolve_external_image_reference is not None:
+ resolved = _resolve_external_image_reference(
+ svg_path.parent,
+ href,
+ )
+ if resolved is not None:
+ references[filename].add(resolved.resolve())
+ out[svg_path] = dict(references)
+ if inline_count:
+ inline_counts[svg_path] = inline_count
+ return out, inline_counts, dict(placements)
+
+ @staticmethod
+ def _image_crop_mechanisms(
+ image: ET.Element,
+ root: ET.Element,
+ parent_by_id: Dict[int, ET.Element],
+ ) -> Tuple[str, ...]:
+ """Return objective clipping mechanisms affecting one image instance."""
+ mechanisms: List[str] = []
+ current: ET.Element | None = image
+ while current is not None:
+ tag = _local_name(current)
+ style_values = (
+ _parse_inline_style(current.get('style'))
+ if _parse_inline_style is not None
+ else {}
+ )
+ for property_name in ('clip-path', 'mask'):
+ value = style_values.get(property_name)
+ if value is None:
+ value = current.get(property_name)
+ if value and value.strip().lower() != 'none':
+ mechanisms.append(f"<{tag}> {property_name}")
+ overflow = style_values.get('overflow')
+ if overflow is None:
+ overflow = current.get('overflow')
+ if overflow and overflow.strip().lower() in {'hidden', 'clip'}:
+ mechanisms.append(f"<{tag}> overflow={overflow.strip()!r}")
+ if current is not root and tag == 'svg':
+ mechanisms.append('nested <svg> viewport')
+ current = parent_by_id.get(id(current))
+ return tuple(dict.fromkeys(mechanisms))
+
+ def _check_planned_image_closure(
+ self,
+ rows: List[Dict[str, str]],
+ project_path: Path,
+ lock_entries: Dict[str, List[Dict[str, str]]],
+ lock_error: str | None,
+ svg_references: Dict[Path, Dict[str, set[Path]]],
+ inline_image_counts: Dict[Path, int],
+ image_placements: Dict[
+ str,
+ List[Tuple[Path, str, Tuple[str, ...]]],
+ ],
+ ) -> None:
+ """Close Design Spec, execution lock, files, SVGs, and provenance."""
+ project_root = project_path.resolve()
+ if inline_image_counts:
+ total = sum(inline_image_counts.values())
+ shown = ', '.join(
+ f"{path.name} ({count})"
+ for path, count in sorted(inline_image_counts.items())
+ )
+ self._illustration_issues.append((
+ 'error',
+ 'svg_inline_image_untracked',
+ f"svg_output contains {total} inline data-URI image(s): "
+ f"{shown}. Current projects must keep external project-local "
+ "image hrefs so every placement closes through Design Spec "
+ "§VIII and spec_lock.md.",
+ ))
+ valid_acquisitions = {
+ 'ai',
+ 'web',
+ 'user',
+ 'formula',
+ 'placeholder',
+ 'slice',
+ }
+ valid_statuses = {
+ 'pending',
+ 'failed',
+ 'generated',
+ 'sourced',
+ 'rendered',
+ 'needs-manual',
+ 'existing',
+ 'placeholder',
+ }
+ terminal_by_acquisition = {
+ 'ai': {'generated', 'needs-manual'},
+ 'web': {'sourced', 'needs-manual'},
+ 'user': {'existing', 'needs-manual'},
+ 'formula': {'rendered', 'needs-manual'},
+ 'placeholder': {'placeholder'},
+ 'slice': {'generated', 'needs-manual'},
+ }
+ current_image_contract = (
+ any('Crop Policy' in row for row in rows)
+ or any(
+ entry.get('legacy') == 'false'
+ for entries in lock_entries.values()
+ for entry in entries
+ )
+ )
+ seen_filenames: set[str] = set()
+ for row in rows:
+ raw_filename = self._row_raw_filename(row)
+ filename = self._row_filename(row)
+ acquire = self._row_acquire(row)
+ status = self._row_status(row)
+ layout = self._row_layout(row)
+ crop = self._row_crop(row)
+ filename_is_bare = bool(filename) and (
+ filename not in {'.', '..'}
+ and '/' not in filename
+ and '\\' not in filename
+ and ':' not in filename
+ )
+ filename_is_canonical = raw_filename in {
+ filename,
+ f"images/{filename}",
+ }
+ if not filename_is_bare or not filename_is_canonical:
+ self._illustration_issues.append((
+ 'error',
+ 'planned_image_invalid_filename',
+ f"Design Spec §VIII Filename {raw_filename!r} must be "
+ "a non-empty bare filename or canonical "
+ "images/<filename> path.",
+ ))
+ elif filename in seen_filenames:
+ self._illustration_issues.append((
+ 'error',
+ 'planned_image_duplicate_filename',
+ f"Design Spec §VIII repeats Filename {filename!r}; "
+ "one resource must have one authoritative row.",
+ ))
+ else:
+ seen_filenames.add(filename)
+
+ if current_image_contract and not layout:
+ self._illustration_issues.append((
+ 'error',
+ 'planned_image_missing_pattern',
+ f"{filename or '(missing filename)'} has an empty Design "
+ "Spec §VIII Layout pattern; preserve one non-empty "
+ "Strategist recommendation without locking SVG geometry.",
+ ))
+ if current_image_contract and crop not in {'adaptive', 'no-crop'}:
+ self._illustration_issues.append((
+ 'error',
+ 'planned_image_invalid_crop_policy',
+ f"{filename or '(missing filename)'} has invalid Design "
+ f"Spec §VIII Crop Policy "
+ f"{row.get('Crop Policy', '').strip()!r}; use adaptive "
+ "or no-crop.",
+ ))
+
+ if acquire not in valid_acquisitions:
+ self._illustration_issues.append((
+ 'error',
+ 'planned_image_invalid_acquisition',
+ f"{filename or '(missing filename)'} has invalid "
+ f"Acquire Via {row.get('Acquire Via', '').strip()!r}.",
+ ))
+ continue
+ if status not in valid_statuses:
+ self._illustration_issues.append((
+ 'error',
+ 'planned_image_invalid_status',
+ f"{filename or '(missing filename)'} has invalid "
+ f"Status {row.get('Status', '').strip()!r}.",
+ ))
+ continue
+ if status in {'pending', 'failed'}:
+ self._illustration_issues.append((
+ 'error',
+ 'planned_image_not_terminal',
+ f"{filename or '(missing filename)'} has non-terminal "
+ f"Status {row.get('Status', '').strip()!r}; finish the "
+ "owning acquisition or mark it Needs-Manual before export.",
+ ))
+ elif status not in terminal_by_acquisition[acquire]:
+ expected = ', '.join(sorted(terminal_by_acquisition[acquire]))
+ self._illustration_issues.append((
+ 'error',
+ 'planned_image_status_mismatch',
+ f"{filename or '(missing filename)'} uses Acquire Via "
+ f"{acquire!r} but Status {status!r}; terminal status must "
+ f"be one of: {expected}.",
+ ))
+
+ if lock_error:
+ self._illustration_issues.append((
+ 'error',
+ 'image_lock_unreadable',
+ lock_error,
+ ))
+ return
+
+ placed_rows = [
+ row for row in rows
+ if self._row_type(row).lower() != 'illustration sheet'
+ and self._row_acquire(row)
+ in {'ai', 'web', 'user', 'formula', 'placeholder', 'slice'}
+ ]
+ rows_by_filename = {
+ self._row_filename(row): row
+ for row in placed_rows
+ if self._row_filename(row)
+ }
+ referenced_paths: Dict[str, set[Path]] = defaultdict(set)
+ for references in svg_references.values():
+ for filename, paths in references.items():
+ referenced_paths[filename].update(paths)
+ referenced = set(referenced_paths)
+
+ for filename, row in rows_by_filename.items():
+ if filename not in lock_entries:
+ self._illustration_issues.append((
+ 'error',
+ 'planned_image_missing_lock',
+ f"{filename} is a placed Design Spec image row but is "
+ "absent from spec_lock.md images.",
+ ))
+ continue
+ if current_image_contract and any(
+ entry.get('legacy') != 'false'
+ for entry in lock_entries[filename]
+ ):
+ self._illustration_issues.append((
+ 'error',
+ 'planned_image_legacy_lock_projection',
+ f"{filename} uses the current Design Spec image contract "
+ "but its spec_lock.md row does not provide complete "
+ "source=..., pattern=..., and crop=... metadata.",
+ ))
+
+ for filename in sorted(referenced - set(rows_by_filename)):
+ lock_note = (
+ ""
+ if filename in lock_entries
+ else " and is absent from spec_lock.md images"
+ )
+ self._illustration_issues.append((
+ 'error',
+ 'svg_image_missing_spec',
+ f"svg_output references {filename}, but it has no placed "
+ f"Design Spec §VIII row{lock_note}.",
+ ))
+
+ for filename, entries in lock_entries.items():
+ row = rows_by_filename.get(filename)
+ if row is None:
+ self._illustration_issues.append((
+ 'error',
+ 'locked_image_missing_spec',
+ f"{filename} is listed in spec_lock.md images but has no "
+ "placed row in Design Spec §VIII.",
+ ))
+ continue
+
+ acquire = self._row_acquire(row)
+ status = self._row_status(row)
+ layout_pattern = self._row_layout(row)
+ crop_policy = self._row_crop(row)
+ if len(entries) > 1:
+ keys = ', '.join(repr(entry.get('key', '')) for entry in entries)
+ self._illustration_issues.append((
+ 'error',
+ 'locked_image_duplicate_entries',
+ f"{filename} appears in multiple spec_lock.md image rows "
+ f"({keys}); one resource must have one authoritative row.",
+ ))
+ for entry in entries:
+ if entry.get('legacy') != 'false':
+ continue
+ if entry.get('source') != acquire:
+ self._illustration_issues.append((
+ 'error',
+ 'locked_image_source_mismatch',
+ f"{filename} spec_lock source={entry.get('source')!r} "
+ f"does not match Design Spec §VIII Acquire Via "
+ f"{acquire!r}.",
+ ))
+ if entry.get('crop') != crop_policy:
+ self._illustration_issues.append((
+ 'error',
+ 'locked_image_crop_mismatch',
+ f"{filename} spec_lock crop={entry.get('crop')!r} "
+ f"does not match Design Spec §VIII Crop Policy "
+ f"{crop_policy!r}.",
+ ))
+ if not self._layout_projection_matches(
+ entry.get('pattern', ''),
+ layout_pattern,
+ ):
+ self._illustration_issues.append((
+ 'error',
+ 'locked_image_pattern_mismatch',
+ f"{filename} spec_lock pattern="
+ f"{entry.get('pattern')!r} does not preserve the "
+ "Design Spec §VIII Layout pattern recommendation "
+ f"{layout_pattern!r}. This Design Spec-to-spec_lock "
+ "projection check compares ordered catalog ids when "
+ "present, otherwise normalized text; it does not "
+ "compare SVG geometry or restrict the Executor's "
+ "realization.",
+ ))
+ candidate_paths: List[Path] = []
+ for entry in entries:
+ raw_path = entry.get('path', '')
+ if not raw_path:
+ continue
+ lock_path = Path(raw_path)
+ legacy_bare_filename = (
+ not lock_path.is_absolute()
+ and raw_path not in {'.', '..'}
+ and '/' not in raw_path
+ and '\\' not in raw_path
+ and ':' not in raw_path
+ )
+ if lock_path.is_absolute():
+ path = lock_path
+ elif legacy_bare_filename:
+ path = project_path / 'images' / raw_path
+ else:
+ path = project_path / raw_path
+ resolved_path = path.resolve()
+ try:
+ resolved_path.relative_to(project_root)
+ except ValueError:
+ self._illustration_issues.append((
+ 'error',
+ 'locked_image_path_outside_project',
+ f"{filename} lock path {entry['path']!r} resolves "
+ "outside the project workspace.",
+ ))
+ continue
+ candidate_paths.append(resolved_path)
+
+ distinct_candidate_paths = set(candidate_paths)
+ if len(distinct_candidate_paths) > 1:
+ shown = ', '.join(
+ str(path.relative_to(project_root))
+ for path in sorted(distinct_candidate_paths)
+ )
+ self._illustration_issues.append((
+ 'error',
+ 'locked_image_ambiguous_paths',
+ f"{filename} resolves to multiple locked project paths: "
+ f"{shown}. One resource must have one authoritative asset.",
+ ))
+
+ expected_paths = {
+ path
+ for path in distinct_candidate_paths
+ if path.is_file()
+ }
+ asset_exists = bool(expected_paths)
+ file_required = status in {
+ 'existing',
+ 'generated',
+ 'sourced',
+ 'rendered',
+ }
+ if not asset_exists and file_required:
+ expected = entries[0].get('path') or f"images/{filename}"
+ self._illustration_issues.append((
+ 'error',
+ 'locked_image_file_missing',
+ f"{filename} is locked and has terminal Status "
+ f"{row.get('Status', '').strip()!r}, but {expected} "
+ "does not exist.",
+ ))
+
+ actual_paths = referenced_paths.get(filename, set())
+ unexpected_paths = actual_paths - expected_paths
+ if unexpected_paths:
+ shown = ', '.join(
+ str(path.relative_to(project_root))
+ if path.is_relative_to(project_root)
+ else str(path)
+ for path in sorted(unexpected_paths)
+ )
+ self._illustration_issues.append((
+ 'error',
+ 'locked_image_reference_mismatch',
+ f"{filename} is referenced from {shown}, not exclusively "
+ "from its locked project path.",
+ ))
+
+ should_be_referenced = (
+ acquire != 'placeholder'
+ and asset_exists
+ and status
+ in {
+ 'existing',
+ 'generated',
+ 'sourced',
+ 'rendered',
+ 'needs-manual',
+ }
+ )
+ if should_be_referenced and not (actual_paths & expected_paths):
+ self._illustration_issues.append((
+ 'error',
+ 'locked_image_unreferenced',
+ f"{filename} has usable terminal content but its locked "
+ "file is not referenced by any svg_output <image> element.",
+ ))
+
+ effective_no_crop = (
+ crop_policy == 'no-crop'
+ or acquire == 'formula'
+ or any(entry.get('crop') == 'no-crop' for entry in entries)
+ )
+ if effective_no_crop:
+ placements_by_svg: Dict[
+ Path,
+ List[Tuple[str, Tuple[str, ...]]],
+ ] = defaultdict(list)
+ for svg_path, raw_aspect, mechanisms in image_placements.get(
+ filename,
+ [],
+ ):
+ placements_by_svg[svg_path].append((
+ raw_aspect,
+ mechanisms,
+ ))
+
+ for svg_path, placements in placements_by_svg.items():
+ parsed_placements = []
+ for raw_aspect, mechanisms in placements:
+ try:
+ align, mode = (
+ _parse_project_image_aspect_ratio(raw_aspect or None)
+ if _parse_project_image_aspect_ratio is not None
+ else ('', '')
+ )
+ except ValueError:
+ # The per-SVG aspect-ratio validator owns malformed syntax.
+ continue
+ parsed_placements.append((
+ raw_aspect,
+ mechanisms,
+ align,
+ mode,
+ ))
+
+ has_complete_placement = any(
+ align != 'none'
+ and mode == 'meet'
+ and not mechanisms
+ for _raw_aspect, mechanisms, align, mode
+ in parsed_placements
+ )
+
+ for raw_aspect, _mechanisms, align, _mode in parsed_placements:
+ if align != 'none':
+ continue
+ actual = raw_aspect or '(implicit xMidYMid meet)'
+ self._illustration_issues.append((
+ 'error',
+ 'no_crop_image_fit_mismatch',
+ f"{svg_path.name}: {filename} is no-crop but its "
+ f"rendered placement uses "
+ f"preserveAspectRatio={actual!r}; stretching is not "
+ "a detail crop and remains forbidden.",
+ ))
+
+ if has_complete_placement:
+ continue
+
+ for raw_aspect, mechanisms, align, mode in parsed_placements:
+ if align != 'none' and mode != 'meet':
+ actual = raw_aspect or '(implicit xMidYMid meet)'
+ self._illustration_issues.append((
+ 'error',
+ 'no_crop_image_fit_mismatch',
+ f"{svg_path.name}: {filename} is no-crop but "
+ "this page has no complete placement and uses "
+ f"preserveAspectRatio={actual!r}; keep at least "
+ "one unclipped placement with a legal alignment "
+ "anchor and meet.",
+ ))
+ if mechanisms:
+ self._illustration_issues.append((
+ 'error',
+ 'no_crop_image_clipped',
+ f"{svg_path.name}: {filename} is no-crop but "
+ "this page has no complete placement; its "
+ "rendered placement is affected by "
+ f"{', '.join(mechanisms)}. Keep at least one "
+ "unclipped meet placement so every source pixel "
+ "remains visible.",
+ ))
+
+ self._check_sourced_image_provenance(
+ rows_by_filename,
+ project_path,
+ )
+
+ def _check_sourced_image_provenance(
+ self,
+ rows_by_filename: Dict[str, Dict[str, str]],
+ project_path: Path,
+ ) -> None:
+ """Require one valid provenance item for every Sourced web row."""
+ sourced = {
+ filename: row
+ for filename, row in rows_by_filename.items()
+ if self._row_acquire(row) == 'web'
+ and self._row_status(row) == 'sourced'
+ }
+ if not sourced:
+ return
+
+ manifest_path = project_path / 'images' / 'image_sources.json'
+ if not manifest_path.exists():
+ self._illustration_issues.append((
+ 'error',
+ 'image_sources_missing',
+ "Sourced web images are used, but "
+ "images/image_sources.json does not exist.",
+ ))
+ return
+
+ payload, error = self._read_image_sources_manifest(manifest_path)
+ if error:
+ if manifest_path not in self._source_manifest_errors_reported:
+ self._illustration_issues.append((
+ 'error',
+ 'image_sources_invalid',
+ error,
+ ))
+ self._source_manifest_errors_reported.add(manifest_path)
+ return
+
+ manifest_items = {
+ str(item.get('filename') or ''): item
+ for item in payload['items']
+ if item.get('filename')
+ }
+ valid_tiers = {
+ 'no-attribution',
+ 'attribution-required',
+ 'manual',
+ }
+ for filename in sourced:
+ item = manifest_items.get(filename)
+ if item is None:
+ self._illustration_issues.append((
+ 'error',
+ 'sourced_image_missing_provenance',
+ f"{filename} is Sourced but has no matching entry in "
+ "images/image_sources.json.",
+ ))
+ continue
+
+ tier = str(item.get('license_tier') or '').strip()
+ if tier not in valid_tiers:
+ self._illustration_issues.append((
+ 'error',
+ 'sourced_image_invalid_license_tier',
+ f"{filename} has invalid license_tier {tier!r} in "
+ "images/image_sources.json.",
+ ))
+ if tier != 'manual' and not str(
+ item.get('attribution_text') or ''
+ ).strip():
+ self._illustration_issues.append((
+ 'error',
+ 'sourced_image_missing_attribution_text',
+ f"{filename} has license_tier {tier!r} but no "
+ "attribution_text in images/image_sources.json.",
+ ))
+ if tier == 'attribution-required' and not str(
+ item.get('author') or ''
+ ).strip():
+ self._illustration_issues.append((
+ 'error',
+ 'sourced_image_missing_author',
+ f"{filename} requires attribution but has no author in "
+ "images/image_sources.json.",
+ ))
+
+ def _check_animation_config_contract(self, dir_path: Path) -> None:
+ """Project-level animations.json reference checks."""
+ project_path = self._resolve_project_path(dir_path)
+ config_path = project_path / 'animations.json'
+ if (
+ _load_animation_config is None
+ or _validate_animation_config is None
+ or _validate_animation_config_errors is None
+ or _validate_transition_config is None
+ ):
+ if config_path.is_file():
+ detail = _animation_config_import_error or 'unknown import error'
+ self._animation_issues.append((
+ 'error',
+ f'animations.json validation is unavailable: {detail}',
+ ))
+ return
+ try:
+ config = _load_animation_config(project_path)
+ except Exception as exc:
+ self._animation_issues.append(('error', f"animations.json is invalid: {exc}"))
+ return
+ if not config:
+ return
+ fatal_errors = list(dict.fromkeys(
+ _validate_transition_config(config)
+ + _validate_animation_config_errors(config)
+ ))
+ for error in fatal_errors:
+ self._animation_issues.append(('error', error))
+ for message in _validate_animation_config(project_path, config):
+ severity = (
+ 'warning'
+ if ' has no id and cannot be customized in animations.json' in message
+ else 'error'
+ )
+ self._animation_issues.append((severity, message))
+
+ def _check_template_contract(
+ self,
+ dir_path: Path,
+ svg_files: List[Path],
+ *,
+ check_structure: bool,
+ ) -> None:
+ """Check reusable-template structure, roster, and placeholder hints.
+
+ - **Roster mismatch (orphan / missing)** is reported as an *error*: a
+ stale roster will produce a wrong ``layouts_index.json`` entry.
+ - **Explicit structure gaps** are errors when positive structure checks
+ are enabled: every current reusable SVG declares its Master and Layout
+ identity. Zero-placeholder Layouts are valid. Legacy template-mode
+ packages fail and must be replaced by a new create-template workspace.
+ - **Placeholder gaps** are reported as *warnings*. Templates may
+ legitimately omit conventional placeholders or swap them out (e.g.
+ ``{{CLOSING_MESSAGE}}`` instead of ``{{THANK_YOU}}``), and a content
+ variant may use a bespoke slot vocabulary. Designers can declare
+ their own per-stem expectations via ``placeholders:`` frontmatter
+ in ``design_spec.md`` to suppress these warnings explicitly.
+
+ Issues are aggregated and printed in :py:meth:`print_summary` so the
+ per-file report stays focused on intrinsic SVG validity.
+ """
+ spec_path = dir_path / 'design_spec.md'
+ spec_text = spec_path.read_text(encoding='utf-8') if spec_path.exists() else ""
+ declared_structure_mode = _declared_template_structure_mode(dir_path)
+ mode_error_recorded = False
+ if declared_structure_mode != 'structured':
+ mode_error_recorded = True
+ self._template_issues.append((
+ 'error',
+ 'explicit_structure_mode',
+ "design_spec.md frontmatter must declare "
+ "native_structure_mode: structured; legacy template-mode "
+ "workspaces must be re-created through create-template",
+ ))
+ if check_structure:
+ native_contract_path = dir_path / 'native_structure.json'
+ source_template_path = dir_path / 'source_template.pptx'
+ legacy_structure_detected = False
+ for svg_file in svg_files:
+ try:
+ root = ET.parse(svg_file).getroot()
+ except (OSError, ET.ParseError):
+ continue
+ if not root.get('data-pptx-master'):
+ legacy_structure_detected = True
+ self._template_issues.append((
+ 'error',
+ 'explicit_master_missing',
+ f"{svg_file.name}: reusable templates require root "
+ "data-pptx-master metadata",
+ ))
+ if not root.get('data-pptx-master-name'):
+ legacy_structure_detected = True
+ self._template_issues.append((
+ 'error',
+ 'explicit_master_name_missing',
+ f"{svg_file.name}: reusable templates require root "
+ "data-pptx-master-name metadata",
+ ))
+ if not root.get('data-pptx-layout'):
+ self._template_issues.append((
+ 'error',
+ 'explicit_structure_missing',
+ f"{svg_file.name}: reusable templates require root "
+ "data-pptx-layout metadata",
+ ))
+ if not root.get('data-pptx-layout-name'):
+ self._template_issues.append((
+ 'error',
+ 'explicit_structure_name_missing',
+ f"{svg_file.name}: reusable templates require root "
+ "data-pptx-layout-name metadata",
+ ))
+ if root.get('data-pptx-layout-kind') is not None:
+ legacy_structure_detected = True
+ self._template_issues.append((
+ 'error',
+ 'deck_instance_layout_kind',
+ f"{svg_file.name}: reusable template prototypes must omit "
+ "legacy data-pptx-layout-kind metadata",
+ ))
+ if any(
+ child.get('data-pptx-placeholder') is not None
+ and child.tag.rsplit('}', 1)[-1] != 'g'
+ for child in list(root)
+ ):
+ legacy_structure_detected = True
+ missing_bounds = [
+ child.get('id') or child.tag.rsplit('}', 1)[-1]
+ for child in list(root)
+ if child.get('data-pptx-placeholder') is not None
+ and child.get('data-pptx-bounds') is None
+ ]
+ if missing_bounds:
+ legacy_structure_detected = True
+ self._template_issues.append((
+ 'error',
+ 'placeholder_bounds_missing',
+ f"{svg_file.name}: reusable templates require "
+ "explicit design-zone data-pptx-bounds; missing: "
+ + ', '.join(missing_bounds),
+ ))
+ if native_contract_path.exists() or source_template_path.exists():
+ legacy_structure_detected = True
+ self._template_issues.append((
+ 'error',
+ 'legacy_native_structure_pair',
+ "legacy native_structure.json/source_template.pptx template "
+ "contracts must be replaced through "
+ "skills/ppt-master/workflows/create-template.md",
+ ))
+
+ if declared_structure_mode != 'structured':
+ legacy_structure_detected = True
+ if not mode_error_recorded:
+ self._template_issues.append((
+ 'error',
+ 'explicit_structure_mode',
+ "design_spec.md frontmatter must declare "
+ "native_structure_mode: structured",
+ ))
+ if legacy_structure_detected:
+ self._template_issues.append((
+ 'error',
+ 'legacy_structure_contract',
+ "legacy template structure detected; create a new current "
+ "workspace through skills/ppt-master/workflows/"
+ "create-template.md before Step 3 consumption",
+ ))
+ spec_pages = self._extract_spec_roster(spec_text) if spec_text else []
+ custom_contract = self._extract_frontmatter_placeholders(spec_text) if spec_text else {}
+
+ on_disk = {p.stem for p in svg_files}
+
+ if spec_pages:
+ spec_set = set(spec_pages)
+ orphan = sorted(on_disk - spec_set)
+ missing = sorted(spec_set - on_disk)
+ for page in orphan:
+ self._template_issues.append((
+ 'error',
+ 'roster_orphan',
+ f"{page}.svg exists on disk but is not listed in design_spec.md Page Roster",
+ ))
+ for page in missing:
+ self._template_issues.append((
+ 'error',
+ 'roster_missing',
+ f"design_spec.md Page Roster lists {page} but {page}.svg is missing on disk",
+ ))
+ elif spec_path.exists():
+ # design_spec.md is present but the roster parser found nothing —
+ # reusable template workspaces always fail closed.
+ self._template_issues.append((
+ 'error',
+ 'roster_unknown',
+ f"could not extract page roster from {spec_path.name}; "
+ "skipping orphan/missing checks",
+ ))
+ else:
+ self._template_issues.append((
+ 'error',
+ 'spec_missing',
+ f"{spec_path.name} not found — required for every library template",
+ ))
+
+ # Per-file placeholder coverage. Variants reuse the parent type's set
+ # (e.g. 03a_content_two_col.svg ↔ 03_content rules) unless the spec
+ # frontmatter overrides that page (custom_contract takes precedence).
+ for svg_file in svg_files:
+ expected = self._lookup_template_contract(
+ svg_file.stem, overrides=custom_contract,
+ )
+ if expected is None:
+ continue # extension pages or stems with no convention
+ try:
+ content = svg_file.read_text(encoding='utf-8')
+ except OSError:
+ continue
+ for placeholder in expected:
+ if placeholder not in content:
+ self._template_issues.append((
+ 'warning',
+ 'placeholder_hint',
+ f"{svg_file.name}: missing conventional placeholder {placeholder} "
+ "(declare 'placeholders:' frontmatter in design_spec.md to silence)",
+ ))
+
+ @staticmethod
+ def _extract_frontmatter_placeholders(spec_text: str) -> Dict[str, Tuple[str, ...]]:
+ """Read the optional ``placeholders:`` map from design_spec.md frontmatter.
+
+ Shape:
+
+ .. code-block:: yaml
+
+ placeholders:
+ 01_cover: ["{{TITLE}}", "{{BRAND_LOGO}}"]
+ 03_content: [] # explicitly assert "no expectation"
+ 03a_content_two_col: # variant-specific override
+ - "{{LEFT_TITLE}}"
+ - "{{RIGHT_TITLE}}"
+
+ Each key is a stem (full filename without ``.svg``) or page-type prefix
+ (``01_cover``). An empty list silences the default convention for that
+ stem; a populated list replaces the default. Stems / prefixes not
+ listed fall back to ``DEFAULT_PLACEHOLDER_CONVENTION``.
+
+ We parse with PyYAML when available; otherwise we fall back to a
+ minimal regex that handles the documented shape.
+ """
+ if not spec_text.startswith("---\n"):
+ return {}
+ end = spec_text.find("\n---\n", 4)
+ if end == -1:
+ return {}
+ block = spec_text[4:end]
+
+ try:
+ import yaml # type: ignore
+ except ImportError:
+ return _parse_placeholders_fallback(block)
+
+ try:
+ data = yaml.safe_load(block) or {}
+ except yaml.YAMLError:
+ return {}
+ if not isinstance(data, dict):
+ return {}
+ raw = data.get("placeholders")
+ if not isinstance(raw, dict):
+ return {}
+
+ out: Dict[str, Tuple[str, ...]] = {}
+ for stem, value in raw.items():
+ if not isinstance(stem, str):
+ continue
+ if isinstance(value, list):
+ out[stem] = tuple(str(v) for v in value)
+ elif value is None:
+ out[stem] = ()
+ return out
+
+ @staticmethod
+ def _extract_spec_roster(spec_text: str) -> List[str]:
+ """Best-effort: extract the page roster from design_spec.md.
+
+ Templates do not share a uniform section index for the roster — the
+ personality-only skeleton puts it at §V "Page Roster"; legacy specs use
+ §VI "Page Roster" or bury filenames under §VII "Page Types" as
+ ``### N. Cover Page (01_cover.svg)``. We match by title (any roman
+ index), then fall back to scanning the whole document for any
+ backtick-wrapped ``<stem>.svg`` reference.
+
+ Returns the deduplicated stem list in document order. Empty result
+ means we can't determine the roster confidently — caller should treat
+ that as "skip orphan/missing checks", not as "no pages declared".
+ """
+ # Pass 1: explicit roster section, any roman numeral.
+ sections = list(re.finditer(
+ r"^##\s+[IVX]+\.\s+(?:(?:SVG\s+)?Page Roster|Page Structure|Pages|Page Types)\b.*?(?=^##\s+|\Z)",
+ spec_text,
+ re.MULTILINE | re.DOTALL | re.IGNORECASE,
+ ))
+ roster_scope = next(
+ (
+ section.group(0)
+ for section in sections
+ if re.match(
+ r"^##\s+[IVX]+\.\s+(?:SVG\s+)?Page Roster\b",
+ section.group(0),
+ re.IGNORECASE,
+ )
+ ),
+ None,
+ )
+ scope = roster_scope or next(
+ (
+ section.group(0)
+ for section in sections
+ if re.search(r"[`\(][0-9A-Za-z_]+\.svg[`\)]", section.group(0))
+ ),
+ sections[0].group(0) if sections else None,
+ )
+
+ # Pass 2: full document. We *only* trust this scan when the explicit
+ # roster scan came up empty (no `<stem>.svg` references inside it) —
+ # otherwise the explicit section's deliberate roster wins over loose
+ # mentions elsewhere.
+ explicit_scope = bool(
+ scope and re.search(r"[`\(][0-9A-Za-z_]+\.svg[`\)]", scope)
+ )
+ if explicit_scope:
+ text = scope
+ else:
+ text = spec_text
+
+ stems: List[str] = []
+ seen: set = set()
+ # Accept backtick-quoted (`01_cover.svg`) and parenthesized
+ # (01_cover.svg) forms — existing specs use either.
+ svg_ref_re = re.compile(r"[`\(]([0-9A-Za-z_]+\.svg)[`\)]")
+ for match in svg_ref_re.finditer(text):
+ stem = match.group(1)[:-4]
+ if stem in seen or (not explicit_scope and not re.match(r"^\d", stem)):
+ continue
+ seen.add(stem)
+ stems.append(stem)
+
+ # If the explicit §VI scan listed bare stems (without .svg), accept
+ # those as fallback — but only when they were inside that section.
+ if not stems and scope:
+ for match in re.finditer(r"`([0-9]{2}[a-z]?_[A-Za-z0-9_]+)`", scope):
+ stem = match.group(1)
+ if stem in seen:
+ continue
+ seen.add(stem)
+ stems.append(stem)
+
+ return stems
+
+ @classmethod
+ def _lookup_template_contract(
+ cls, stem: str, *,
+ overrides: Dict[str, Tuple[str, ...]] | None = None,
+ ) -> Tuple[str, ...] | None:
+ """Resolve a SVG stem to its expected placeholder set.
+
+ Resolution order, first hit wins:
+ 1. ``overrides[stem]`` — frontmatter entry for the exact filename
+ 2. ``overrides[<page_type_prefix>]`` — frontmatter entry for the
+ variant's parent type (e.g. ``03_content`` for
+ ``03a_content_two_col``)
+ 3. ``DEFAULT_PLACEHOLDER_CONVENTION[<page_type>]`` — keyed by the
+ type token alone, so it applies regardless of where the type
+ lands in the template's presentation-order numbering
+
+ Returns ``None`` for stems with no matching convention or override —
+ e.g. extension pages like ``05_section_break``. ``()`` (empty tuple)
+ is a valid value meaning "no expected placeholders" — used to
+ explicitly silence the default convention.
+ """
+ overrides = overrides or {}
+ if stem in overrides:
+ return overrides[stem]
+
+ # Variant convention: <NN><letter>?_<rest>; strip the letter to find
+ # the parent type prefix, e.g. "03a_content_two_col" -> "03_content".
+ match = re.match(r"^(\d{2})([a-z])?_([a-z]+)", stem)
+ if not match:
+ return None
+ num, _letter, kind = match.groups()
+ key = f"{num}_{kind}"
+ if key in overrides:
+ return overrides[key]
+ return cls.DEFAULT_PLACEHOLDER_CONVENTION.get(kind)
+
+ def _print_result(self, result: Dict):
+ """Print check result for a single file"""
+ if result['passed']:
+ if result['warnings']:
+ icon = "[WARN]"
+ status = "Passed (with warnings)"
+ else:
+ icon = "[OK]"
+ status = "Passed"
+ else:
+ icon = "[ERROR]"
+ status = "Failed"
+
+ print(f"{icon} {result['file']} - {status}")
+
+ # Display basic info
+ if result['info']:
+ info_items = []
+ if 'viewbox' in result['info']:
+ info_items.append(f"viewBox: {result['info']['viewbox']}")
+ if info_items:
+ print(f" {' | '.join(info_items)}")
+
+ # Display errors
+ if result['errors']:
+ for error in result['errors']:
+ print(f" [ERROR] {error}")
+
+ # Display the complete warning set from this run. The generation
+ # workflow reviews all findings before one consolidated repair pass.
+ if result['warnings']:
+ for warning in result['warnings']:
+ print(f" [WARN] {warning}")
+
+ print()
+
+ def print_summary(self):
+ """Print check summary"""
+ self._apply_aggregated_issue_counts()
+
+ print("=" * 80)
+ print("[SUMMARY] Check Summary")
+ print("=" * 80)
+
+ print(f"\nTotal files: {self.summary['total']}")
+ print(
+ f" [OK] Fully passed: {self.summary['passed']} ({self._percentage(self.summary['passed'])}%)")
+ print(
+ f" [WARN] With warnings: {self.summary['warnings']} ({self._percentage(self.summary['warnings'])}%)")
+ print(
+ f" [ERROR] With errors: {self.summary['errors']} ({self._percentage(self.summary['errors'])}%)")
+
+ if self.issue_types:
+ print(f"\nIssue categories:")
+ for issue_type, count in sorted(self.issue_types.items(), key=lambda x: x[1], reverse=True):
+ print(f" {issue_type}: {count}")
+
+ # spec_lock anchor comparison (only printed when a lock was found)
+ self._print_anchor_value_summary()
+
+ # Template-mode aggregation (orphan/missing roster + placeholder hints)
+ self._print_template_summary()
+
+ # Animation config aggregation.
+ self._print_animation_summary()
+
+ # Illustration strategy aggregation.
+ self._print_illustration_summary()
+
+ # Communication contract and per-page audience movement.
+ self._print_communication_trace_summary()
+
+ # Explicit PowerPoint master/layout structure aggregation.
+ self._print_pptx_structure_summary()
+
+ # Source-owned import recovery belongs to the template, not this run.
+ self._print_source_import_summary()
+
+ # Fix suggestions
+ if self.summary['errors'] > 0 or self.summary['warnings'] > 0:
+ print(f"\n[TIP] Common fixes:")
+ print(f" 1. XML well-formedness: write typography as raw Unicode (—, ©, →, NBSP); escape XML reserved chars as &amp; &lt; &gt; &quot; &apos; — never use HTML named entities like &nbsp; &mdash; &copy;")
+ print(f" 2. viewBox issues: root viewBox is the canvas authority (see references/canvas-formats.md)")
+ print(
+ " 3. Paint recommendation: generated SVG prefers uppercase "
+ "#RRGGBB plus channel-specific opacity; compatible alternatives "
+ "remain non-blocking"
+ )
+ print(f" 4. foreignObject: Use <text> + <tspan> for manual line breaks")
+ print(f" 5. Font issues: use PPT-safe exported typefaces (e.g. Microsoft YaHei / Arial / Consolas)")
+
+ def _print_animation_summary(self):
+ """Print animations.json validation issues if present."""
+ if not self._animation_issues:
+ return
+
+ errors = [item for item in self._animation_issues if item[0] == 'error']
+ warnings = [item for item in self._animation_issues if item[0] == 'warning']
+
+ print("\n[ANIMATION] animations.json checks")
+ for _severity, msg in errors:
+ print(f" [ERROR] {msg}")
+ for _severity, msg in warnings:
+ print(f" [WARN] {msg}")
+
+ def _print_illustration_summary(self):
+ """Print project-level illustration strategy issues if present."""
+ if not self._illustration_issues:
+ return
+
+ errors = [item for item in self._illustration_issues if item[0] == 'error']
+ warnings = [item for item in self._illustration_issues if item[0] == 'warning']
+
+ print("\n[IMAGES] Image resource checks")
+ if errors:
+ print(f" Errors ({len(errors)}):")
+ for _severity, kind, msg in errors:
+ print(f" [{kind}] {msg}")
+ if warnings:
+ print(f" Warnings ({len(warnings)}):")
+ for _severity, kind, msg in warnings:
+ print(f" [{kind}] {msg}")
+
+ def _print_pptx_structure_summary(self):
+ """Print project-level PowerPoint structure contract issues."""
+ if not self._pptx_structure_issues:
+ return
+ print("\n[PPTX STRUCTURE] Master/layout contract checks")
+ for severity, message in self._pptx_structure_issues:
+ print(f" [{severity.upper()}] {message}")
+
+ def _print_communication_trace_summary(self):
+ """Print project-level communication trace issues."""
+ if not self._communication_trace_issues:
+ return
+ print("\n[COMMUNICATION TRACE] Contract and Audience move checks")
+ for severity, message in self._communication_trace_issues:
+ print(f" [{severity.upper()}] {message}")
+
+ def _print_source_import_summary(self):
+ """Print source-owned tolerant-import diagnostics as information."""
+ warning_count = _source_import_warning_count(
+ self._source_import_summary
+ )
+ if warning_count <= 0:
+ return
+ print("\n[SOURCE IMPORT] Template-owned compatibility diagnostics")
+ print(
+ f" [INFO] {warning_count} source-import warning(s); unchanged "
+ "template recovery is not attributed to generated content."
+ )
+ by_code = self._source_import_summary.get('by_code')
+ if isinstance(by_code, dict):
+ for code, count in sorted(by_code.items()):
+ print(f" {code}: {count}")
+
+ def _print_template_summary(self):
+ """Aggregate template-mode roster / placeholder issues at the bottom.
+
+ Errors land under the ``errors`` summary count (so the exit signal
+ from ``main`` agrees), warnings under ``warnings``. Both are listed
+ per file so the user can act on them directly.
+ """
+ if not self._template_issues and not self._brand_template_checked:
+ return
+
+ errors = [item for item in self._template_issues if item[0] == 'error']
+ warnings = [item for item in self._template_issues if item[0] == 'warning']
+
+ print("\n[TEMPLATE] Template mode checks")
+ if errors:
+ print(f" Errors ({len(errors)}):")
+ for _sev, kind, msg in errors:
+ print(f" [{kind}] {msg}")
+ if warnings:
+ print(f" Warnings ({len(warnings)}):")
+ for _sev, kind, msg in warnings:
+ print(f" [{kind}] {msg}")
+ if self._brand_template_checked and not errors:
+ print(" Brand design_spec.md schema and asset references passed.")
+ if not errors:
+ if not self._brand_template_checked:
+ print(" No structural roster issues.")
+ print(" Conventional placeholder-name hints may be declared through "
+ "'placeholders:' frontmatter. Placeholder bounds are mandatory "
+ "design-zone metadata.")
+
+ def _apply_aggregated_issue_counts(self):
+ """Mirror project-level aggregate issues into summary counters once."""
+ if self._aggregate_counts_applied:
+ return
+ self._aggregate_counts_applied = True
+
+ animation_errors = [item for item in self._animation_issues if item[0] == 'error']
+ animation_warnings = [item for item in self._animation_issues if item[0] == 'warning']
+ self.summary['errors'] += len(animation_errors)
+ self.summary['warnings'] += len(animation_warnings)
+ for severity, _msg in self._animation_issues:
+ self.issue_types[f'animation_config_{severity}'] += 1
+
+ template_errors = [item for item in self._template_issues if item[0] == 'error']
+ template_warnings = [item for item in self._template_issues if item[0] == 'warning']
+ self.summary['errors'] += len(template_errors)
+ self.summary['warnings'] += len(template_warnings)
+ for severity, kind, _msg in self._template_issues:
+ self.issue_types[f'template_{kind}_{severity}'] += 1
+
+ illustration_errors = [item for item in self._illustration_issues if item[0] == 'error']
+ illustration_warnings = [item for item in self._illustration_issues if item[0] == 'warning']
+ self.summary['errors'] += len(illustration_errors)
+ self.summary['warnings'] += len(illustration_warnings)
+ for severity, kind, _msg in self._illustration_issues:
+ self.issue_types[f'illustration_{kind}_{severity}'] += 1
+
+ communication_errors = [
+ item for item in self._communication_trace_issues
+ if item[0] == 'error'
+ ]
+ communication_warnings = [
+ item for item in self._communication_trace_issues
+ if item[0] == 'warning'
+ ]
+ self.summary['errors'] += len(communication_errors)
+ self.summary['warnings'] += len(communication_warnings)
+ for severity, _msg in self._communication_trace_issues:
+ self.issue_types[f'communication_trace_{severity}'] += 1
+
+ structure_errors = [item for item in self._pptx_structure_issues if item[0] == 'error']
+ structure_warnings = [item for item in self._pptx_structure_issues if item[0] == 'warning']
+ self.summary['errors'] += len(structure_errors)
+ self.summary['warnings'] += len(structure_warnings)
+ for severity, _msg in self._pptx_structure_issues:
+ self.issue_types[f'pptx_structure_{severity}'] += 1
+
+ def _print_anchor_value_summary(self):
+ """Print anchor comparisons without treating contextual paint/type as drift."""
+ if not self._lock_seen:
+ return
+ has_contextual = any(
+ self._anchor_value_summary[category]
+ for category in ('colors', 'fonts')
+ )
+ has_undeclared_sizes = bool(self._anchor_value_summary['sizes'])
+ if not has_contextual and not has_undeclared_sizes:
+ print(
+ "\n[OK] spec_lock anchor comparison: no additional contextual "
+ "colors/fonts or out-of-band font sizes"
+ )
+ return
+
+ if has_contextual:
+ print("\nContextual values beyond spec_lock anchors (informational):")
+ for category, label in (
+ ('colors', 'Colors'),
+ ('fonts', 'Font families'),
+ ):
+ items = self._anchor_value_summary.get(category, {})
+ if not items:
+ continue
+ entries = sorted(
+ items.items(), key=lambda item: (-len(item[1]), item[0])
+ )
+ print(f" {label}:")
+ for val, files in entries:
+ count = len(files)
+ suffix = "file" if count == 1 else "files"
+ print(f" {val} ({count} {suffix})")
+ print(
+ "Note: contextual page paint, gradient/effect colors, and "
+ "export-safe typefaces are allowed.\n"
+ " Add a spec_lock row only when a value becomes a "
+ "recurring named semantic role."
+ )
+
+ if has_undeclared_sizes:
+ print(
+ "\nTypography sizes outside every declared role anchor ±2px "
+ "(up to 2 occurrences are sparse; the 3rd is recurring):"
+ )
+ entries = sorted(
+ self._anchor_value_summary['sizes'].items(),
+ key=lambda item: (-len(item[1]), item[0]),
+ )
+ for val, files in entries:
+ occurrences = self._undeclared_size_occurrences.get(
+ val,
+ len(files),
+ )
+ file_count = len(files)
+ file_suffix = "file" if file_count == 1 else "files"
+ policy = (
+ "sparse"
+ if occurrences <= SPARSE_UNDECLARED_FONT_SIZE_MAX_OCCURRENCES
+ else "recurring — declare a role"
+ )
+ print(
+ f" {val} ({occurrences} occurrences in {file_count} "
+ f"{file_suffix}; {policy})"
+ )
+
+ def _percentage(self, count: int) -> int:
+ """Calculate percentage"""
+ if self.summary['total'] == 0:
+ return 0
+ return min(100, int(count / self.summary['total'] * 100))
+
+ def export_report(self, output_file: str = 'svg_quality_report.txt'):
+ """Export check report"""
+ with open(output_file, 'w', encoding='utf-8') as f:
+ f.write("PPT Master SVG Quality Check Report\n")
+ f.write("=" * 80 + "\n\n")
+
+ for result in self.results:
+ status = "[OK] Passed" if result['passed'] else "[ERROR] Failed"
+ f.write(f"{status} - {result['file']}\n")
+ f.write(f"Path: {result.get('path', 'N/A')}\n")
+
+ if result['info']:
+ f.write(f"Info: {result['info']}\n")
+
+ if result['errors']:
+ f.write(f"\nErrors:\n")
+ for error in result['errors']:
+ f.write(f" - {error}\n")
+
+ if result['warnings']:
+ f.write(f"\nWarnings:\n")
+ for warning in result['warnings']:
+ f.write(f" - {warning}\n")
+
+ f.write("\n" + "-" * 80 + "\n\n")
+
+ # Write summary
+ f.write("\n" + "=" * 80 + "\n")
+ f.write("Check Summary\n")
+ f.write("=" * 80 + "\n\n")
+ f.write(f"Total files: {self.summary['total']}\n")
+ f.write(f"Fully passed: {self.summary['passed']}\n")
+ f.write(f"With warnings: {self.summary['warnings']}\n")
+ f.write(f"With errors: {self.summary['errors']}\n")
+
+ print(f"\n[REPORT] Check report exported: {output_file}")
+
+ def export_json_report(
+ self,
+ output_file: str,
+ *,
+ target: str,
+ stage: str,
+ ) -> None:
+ """Write a machine-readable quality report with provenance classes."""
+ self._apply_aggregated_issue_counts()
+ introduced: List[Dict[str, str]] = []
+ blocking: List[Dict[str, str]] = []
+ inherited: List[Dict[str, str]] = []
+ for result in self.results:
+ filename = str(result.get('file') or '')
+ introduced.extend({
+ 'file': filename,
+ 'message': warning,
+ } for warning in result.get('warnings', []))
+ blocking.extend({
+ 'file': filename,
+ 'message': error,
+ } for error in result.get('errors', []))
+ info = result.get('info') or {}
+ for item in info.get('inherited', []):
+ if isinstance(item, dict):
+ inherited.append({
+ 'file': filename,
+ 'kind': str(item.get('kind') or 'prototype'),
+ 'message': str(item.get('message') or ''),
+ })
+
+ project_issues = {
+ 'template': [
+ {'severity': severity, 'kind': kind, 'message': message}
+ for severity, kind, message in self._template_issues
+ ],
+ 'animation': [
+ {'severity': severity, 'message': message}
+ for severity, message in self._animation_issues
+ ],
+ 'illustration': [
+ {'severity': severity, 'kind': kind, 'message': message}
+ for severity, kind, message in self._illustration_issues
+ ],
+ 'communication_trace': [
+ {'severity': severity, 'message': message}
+ for severity, message in self._communication_trace_issues
+ ],
+ 'pptx_structure': [
+ {'severity': severity, 'message': message}
+ for severity, message in self._pptx_structure_issues
+ ],
+ }
+ for group, issues in project_issues.items():
+ for issue in issues:
+ item = {
+ 'scope': group,
+ 'message': issue['message'],
+ }
+ if issue['severity'] == 'error':
+ blocking.append(item)
+ else:
+ introduced.append(item)
+
+ # Keep the legacy `drift` JSON field for report compatibility. Its
+ # colors/fonts entries are informational anchor comparisons; sparse
+ # size entries are informational until their third occurrence.
+ drift = {
+ category: {
+ value: sorted(files)
+ for value, files in sorted(values.items())
+ }
+ for category, values in self._anchor_value_summary.items()
+ }
+ source_import = dict(self._source_import_summary)
+ payload = {
+ 'schema': 'ppt-master.svg-quality-report.v1',
+ 'stage': stage,
+ 'target': str(Path(target).resolve()),
+ 'source_fingerprint': _quality_source_fingerprint(self.results),
+ 'summary': dict(self.summary),
+ 'issue_types': dict(sorted(self.issue_types.items())),
+ 'categories': {
+ 'blocking': {
+ 'count': len(blocking),
+ 'issues': blocking,
+ },
+ 'introduced': {
+ 'count': len(introduced),
+ 'issues': introduced,
+ },
+ 'inherited': {
+ 'count': len(inherited),
+ 'issues': inherited,
+ },
+ 'source-import': {
+ 'count': _source_import_warning_count(source_import),
+ 'summary': source_import,
+ },
+ },
+ 'drift': drift,
+ 'project_issues': project_issues,
+ 'files': self.results,
+ }
+ report_path = Path(output_file)
+ report_path.parent.mkdir(parents=True, exist_ok=True)
+ report_path.write_text(
+ json.dumps(payload, ensure_ascii=False, indent=2) + '\n',
+ encoding='utf-8',
+ )
+ print(f"\n[REPORT] JSON quality report exported: {report_path}")
+
+
+def _source_import_warning_count(summary: Dict[str, object]) -> int:
+ """Return only a schema-compatible non-negative warning count."""
+ value = summary.get('warning_count')
+ if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+ return 0
+ return value
+
+
+def _quality_source_fingerprint(results: List[Dict]) -> Dict[str, object]:
+ """Bind a quality report to the exact SVG bytes that were checked."""
+ files: List[Dict[str, object]] = []
+ aggregate = hashlib.sha256()
+ candidates = sorted(
+ (
+ result
+ for result in results
+ if result.get('exists') and result.get('path')
+ ),
+ key=lambda result: Path(str(result['path'])).name,
+ )
+ for result in candidates:
+ path = Path(str(result['path']))
+ file_sha256 = result.get('source_sha256')
+ if not isinstance(file_sha256, str):
+ files.append({
+ 'file': path.name,
+ 'sha256': None,
+ 'error': 'source bytes were not available during validation',
+ })
+ file_sha256 = 'unreadable'
+ else:
+ files.append({'file': path.name, 'sha256': file_sha256})
+ aggregate.update(path.name.encode('utf-8'))
+ aggregate.update(b'\0')
+ aggregate.update(file_sha256.encode('ascii'))
+ aggregate.update(b'\n')
+ return {
+ 'algorithm': 'sha256',
+ 'digest': aggregate.hexdigest(),
+ 'file_count': len(files),
+ 'files': files,
+ }
diff --git a/skills/ppt-master/scripts/svg_quality/cli.py b/skills/ppt-master/scripts/svg_quality/cli.py
new file mode 100644
index 00000000..b3819dff
--- /dev/null
+++ b/skills/ppt-master/scripts/svg_quality/cli.py
@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""PPT Master SVG quality-check CLI implementation.
+
+Parses the legacy command-line contract and delegates validation to the checker.
+
+Usage:
+ python3 scripts/svg_quality_checker.py <svg_file_or_project> [options]
+
+Examples:
+ python3 scripts/svg_quality_checker.py projects/demo --stage final --json
+
+Dependencies:
+ Standard library plus local PPT Master validation modules.
+"""
+
+import sys
+from pathlib import Path
+
+from slide_roster import discover_slide_svgs
+
+from .checker import SVGQualityChecker
+
+
+def _first_page_target(target: str) -> str:
+ """Resolve a project/directory target to its first authored SVG page."""
+ path = Path(target)
+ if path.is_file():
+ return str(path)
+ svg_root = path / "svg_output" if (path / "svg_output").is_dir() else path
+ svg_files = discover_slide_svgs(svg_root) if svg_root.is_dir() else []
+ return str(svg_files[0]) if svg_files else target
+
+
+def _default_json_report_path(
+ checker: SVGQualityChecker,
+ target: str,
+ stage: str,
+) -> Path:
+ """Choose a stage-specific report path without overwriting the final gate."""
+ target_path = Path(target)
+ project_path = checker._resolve_project_path(target_path)
+ report_name = (
+ "svg_quality_report.json"
+ if stage == "final"
+ else "svg_quality_first_page_report.json"
+ )
+ if (
+ (project_path / "svg_output").is_dir()
+ or (project_path / "design_spec.md").is_file()
+ ):
+ return project_path / "validation" / report_name
+ base = target_path if target_path.is_dir() else target_path.parent
+ return base / report_name
+
+
+def print_usage() -> None:
+ """Print CLI usage information."""
+ print("PPT Master - SVG Quality Check Tool\n")
+ print("Usage:")
+ print(" python3 scripts/svg_quality_checker.py <svg_file>")
+ print(" python3 scripts/svg_quality_checker.py <directory>")
+ print(" python3 scripts/svg_quality_checker.py <workspace>/templates --template-mode")
+ print(" python3 scripts/svg_quality_checker.py --all examples")
+ print("\nExamples:")
+ print(" python3 scripts/svg_quality_checker.py examples/project/svg_output/slide_01.svg")
+ print(" python3 scripts/svg_quality_checker.py examples/project/svg_output")
+ print(" python3 scripts/svg_quality_checker.py examples/project")
+ print(" python3 scripts/svg_quality_checker.py templates/layouts/presentation_core/templates --template-mode")
+ print(" python3 scripts/svg_quality_checker.py templates/decks/中国电信/templates --template-mode")
+ print("\nOptions:")
+ print(" --format <ppt169|ppt43|...> Expected canvas format")
+ print(" --stage <first-page|final> first-page checks only the first authored SVG")
+ print(" with a partial structure roster; final (default)")
+ print(" requires the complete declared page roster.")
+ print(" --json Write a machine-readable quality report")
+ print(" --json-output <path> Override the JSON report path")
+ print(" --quick-generate Validate lockless flat Quick Generate SVGs;")
+ print(" ignore design_spec.md and spec_lock.md.")
+ print(" --template-mode Validate a template workspace's templates/ directory:")
+ print(" Brand validates design_spec.md and referenced assets;")
+ print(" Layout/Deck glob *.svg directly, skip spec_lock checks,")
+ print(" enforce roster consistency, and emit placeholder hints.")
+ print(" native_structure_mode: structured also enables complete")
+ print(" per-file and cross-page structure validation. Legacy")
+ print(" native_structure_mode: template fails and must be")
+ print(" re-created through create-template before validation.")
+ print(" Warnings are advisory: they require no modification and do not affect exit status;")
+ print(" only errors make the command exit with status 1.")
+
+
+def main() -> None:
+ """Run the CLI entry point."""
+ if len(sys.argv) < 2:
+ print_usage()
+ sys.exit(0)
+
+ if sys.argv[1] in {"-h", "--help", "help"}:
+ print_usage()
+ sys.exit(0)
+
+ if sys.argv[1].startswith("--") and sys.argv[1] not in {"--all"}:
+ print(f"[ERROR] Missing target before option: {sys.argv[1]}")
+ print_usage()
+ sys.exit(1)
+
+ template_mode = "--template-mode" in sys.argv
+ quick_generate = "--quick-generate" in sys.argv
+ if template_mode and quick_generate:
+ print("[ERROR] --template-mode cannot be combined with --quick-generate")
+ sys.exit(1)
+ checker = SVGQualityChecker(
+ template_mode=template_mode,
+ quick_generate=quick_generate,
+ )
+
+ target = sys.argv[1]
+ expected_format = None
+ stage = "final"
+
+ if "--format" in sys.argv:
+ idx = sys.argv.index("--format")
+ if idx + 1 < len(sys.argv):
+ expected_format = sys.argv[idx + 1]
+ if "--stage" in sys.argv:
+ idx = sys.argv.index("--stage")
+ if idx + 1 >= len(sys.argv):
+ print("[ERROR] --stage requires first-page or final")
+ sys.exit(1)
+ stage = sys.argv[idx + 1]
+ if stage not in {"first-page", "final"}:
+ print(f"[ERROR] Unsupported quality-check stage: {stage}")
+ sys.exit(1)
+
+ if target == "--all":
+ if quick_generate:
+ print("[ERROR] --quick-generate does not support --all")
+ sys.exit(1)
+ if stage != "final":
+ print("[ERROR] --stage first-page does not support --all")
+ sys.exit(1)
+ base_dir = sys.argv[2] if len(sys.argv) > 2 else "examples"
+ from project_utils import find_all_projects
+
+ projects = find_all_projects(base_dir)
+
+ for project in projects:
+ print(f"\n{'=' * 80}")
+ print(f"Checking project: {project.name}")
+ print("=" * 80)
+ checker.check_directory(str(project))
+ else:
+ check_target = _first_page_target(target) if stage == "first-page" else target
+ checker.check_directory(check_target, expected_format)
+
+ if stage == "final" and Path(target).is_dir():
+ if checker._has_incomplete_page_roster:
+ print(
+ "[TIP] This final-stage run found an incomplete page roster. "
+ "During serial authoring, use --stage first-page for the first-page "
+ "gate; keep --stage final for the complete deck."
+ )
+
+ checker.print_summary()
+
+ if "--export" in sys.argv:
+ output_file = "svg_quality_report.txt"
+ if "--output" in sys.argv:
+ idx = sys.argv.index("--output")
+ if idx + 1 < len(sys.argv):
+ output_file = sys.argv[idx + 1]
+ checker.export_report(output_file)
+
+ if "--json" in sys.argv or "--json-output" in sys.argv:
+ if "--json-output" in sys.argv:
+ idx = sys.argv.index("--json-output")
+ if idx + 1 >= len(sys.argv):
+ print("[ERROR] --json-output requires a path")
+ sys.exit(1)
+ json_output = Path(sys.argv[idx + 1])
+ else:
+ json_output = _default_json_report_path(checker, target, stage)
+ checker.export_json_report(
+ str(json_output),
+ target=target,
+ stage=stage,
+ )
+
+ if checker.summary["errors"] > 0:
+ sys.exit(1)
+ else:
+ sys.exit(0)
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.py
index c6f101f2..319219dd 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -1,8316 +1,59 @@
#!/usr/bin/env python3
-"""
-PPT Master - SVG Quality Check Tool
+"""PPT Master - SVG Quality Check Tool
-Checks whether SVG files comply with project technical specifications.
+Stable CLI entry point and compatibility import surface for SVG validation.
+Implementation lives in ``svg_quality/``.
Usage:
python3 scripts/svg_quality_checker.py <svg_file>
python3 scripts/svg_quality_checker.py <directory>
python3 scripts/svg_quality_checker.py --all examples
+
+Examples:
+ python3 scripts/svg_quality_checker.py projects/demo --stage final --json
+
+Dependencies:
+ Same as svg_quality.cli.
"""
-import copy
import sys
-import re
-import json
-import html
-import math
-import hashlib
from pathlib import Path
-from typing import List, Dict, Tuple
-from collections import Counter, defaultdict
-from urllib.parse import unquote, urlsplit
-from xml.etree import ElementTree as ET
-
-from console_encoding import configure_utf8_stdio
-from native_payloads import NativePayloadError, hydrate_native_payload_refs
-from slide_roster import discover_slide_svgs
-
-configure_utf8_stdio()
-
-try:
- from project_utils import CANVAS_FORMATS, validate_communication_trace
-except ImportError:
- print("Warning: Unable to import project_utils")
- CANVAS_FORMATS = {}
- validate_communication_trace = None
-
-try:
- from pptx_effects import (
- EFFECT_REASON_ATTR as _EFFECT_REASON_ATTR,
- EFFECT_STATUS_ATTR as _EFFECT_STATUS_ATTR,
- project_effect_status_errors as _project_effect_status_errors,
- )
-except ImportError:
- _EFFECT_REASON_ATTR = 'data-pptx-effect-reason'
- _EFFECT_STATUS_ATTR = 'data-pptx-effect-status'
- _project_effect_status_errors = None
-
-from svg_to_pptx.canvas_contract import (
- CanvasContractError,
- parse_project_svg_root,
- parse_project_viewbox,
-)
-
-try:
- from project_management.project_specs import (
- parse_spec_lock as _parse_spec_lock,
- parse_spec_lock_image_value as _parse_spec_lock_image_value,
- )
-except ImportError:
- _parse_spec_lock = None # spec_lock anchor comparison will be skipped
- _parse_spec_lock_image_value = None
-
-try:
- from svg_to_pptx.animation_config import (
- load_animation_config as _load_animation_config,
- usable_animation_group_id as _usable_animation_group_id,
- validate_animation_config as _validate_animation_config,
- validate_animation_config_errors as _validate_animation_config_errors,
- validate_transition_config as _validate_transition_config,
- )
-except ImportError as exc:
- _load_animation_config = None
- _validate_animation_config = None
- _validate_animation_config_errors = None
- _validate_transition_config = None
- _animation_config_import_error = str(exc)
-
- def _usable_animation_group_id(raw: str | None) -> str | None:
- return raw if raw and raw.strip() else None
-else:
- _animation_config_import_error = None
-
-try:
- from svg_to_pptx.drawingml.utils import (
- DRAWINGML_TEXT_FONT_SIZE_MAX as _DRAWINGML_TEXT_FONT_SIZE_MAX,
- DRAWINGML_TEXT_FONT_SIZE_MIN as _DRAWINGML_TEXT_FONT_SIZE_MIN,
- IDENTITY_MATRIX as _IDENTITY_MATRIX,
- PROJECT_OPACITY_PROPERTIES as _OPACITY_PROPERTIES,
- PROJECT_PAINT_PROPERTIES as _PAINT_PROPERTIES,
- PROJECT_PERCENTAGE_OPACITY_PROPERTIES as _PERCENTAGE_OPACITY_PROPERTIES,
- detect_text_lang as _detect_text_lang,
- format_project_geometry_length as _format_project_geometry_length,
- format_project_image_aspect_ratio as _format_project_image_aspect_ratio,
- format_project_opacity as _format_project_opacity,
- font_px_to_hpt as _font_px_to_hpt,
- is_canonical_project_geometry_length as _is_canonical_project_geometry_length,
- is_project_opacity_default_form as _is_project_opacity_default_form,
- is_project_paint_default_form as _is_project_paint_default_form,
- iter_project_geometry_lengths as _iter_project_geometry_lengths,
- iter_project_image_aspect_ratios as _iter_project_image_aspect_ratios,
- iter_project_opacities as _iter_project_opacities,
- iter_project_paints as _iter_project_paints,
- iter_project_stroke_styles as _iter_project_stroke_styles,
- iter_project_transforms as _iter_project_transforms,
- matrix_multiply as _matrix_multiply,
- noncanonical_stroke_dash_numbers as _noncanonical_stroke_dash_numbers,
- noncanonical_transform_numbers as _noncanonical_transform_numbers,
- parse_inline_style as _parse_inline_style,
- parse_project_geometry_length as _parse_project_geometry_length,
- parse_project_image_aspect_ratio as _parse_project_image_aspect_ratio,
- parse_project_opacity as _parse_project_opacity,
- parse_project_paint as _parse_project_paint,
- parse_project_stroke_dasharray as _parse_project_stroke_dasharray,
- parse_project_stroke_enum as _parse_project_stroke_enum,
- parse_svg_color as _parse_export_color,
- parse_svg_length as _parse_export_length,
- parse_transform_matrix as _parse_transform_matrix,
- project_definition_errors as _project_definition_errors,
- project_filter_errors as _project_filter_errors,
- project_gradient_errors as _project_gradient_errors,
- project_image_aspect_ratio_errors as _project_image_aspect_ratio_errors,
- project_mask_errors as _project_mask_errors,
- project_marker_errors as _project_marker_errors,
- project_opacity_errors as _project_opacity_errors,
- project_paint_errors as _project_paint_errors,
- project_paint_reference_errors as _project_paint_reference_errors,
- project_stroke_style_errors as _project_stroke_style_errors,
- project_transform_errors as _project_transform_errors,
- rect_to_dml_xfrm as _rect_to_dml_xfrm,
- transform_point as _transform_point,
- unsafe_exported_font_faces as _unsafe_exported_font_faces,
- validate_dml_shape_matrix as _validate_dml_shape_matrix,
- )
-except ImportError:
- _DRAWINGML_TEXT_FONT_SIZE_MAX = None
- _DRAWINGML_TEXT_FONT_SIZE_MIN = None
- _IDENTITY_MATRIX = None
- _OPACITY_PROPERTIES = None
- _PAINT_PROPERTIES = None
- _PERCENTAGE_OPACITY_PROPERTIES = None
- _detect_text_lang = None
- _format_project_geometry_length = None
- _format_project_image_aspect_ratio = None
- _format_project_opacity = None
- _font_px_to_hpt = None
- _is_canonical_project_geometry_length = None
- _is_project_opacity_default_form = None
- _is_project_paint_default_form = None
- _iter_project_geometry_lengths = None
- _iter_project_image_aspect_ratios = None
- _iter_project_opacities = None
- _iter_project_paints = None
- _iter_project_stroke_styles = None
- _iter_project_transforms = None
- _matrix_multiply = None
- _noncanonical_stroke_dash_numbers = None
- _noncanonical_transform_numbers = None
- _parse_inline_style = None
- _parse_project_geometry_length = None
- _parse_project_image_aspect_ratio = None
- _parse_project_opacity = None
- _parse_project_paint = None
- _parse_project_stroke_dasharray = None
- _parse_project_stroke_enum = None
- _parse_export_color = None
- _parse_export_length = None
- _parse_transform_matrix = None
- _project_definition_errors = None
- _project_filter_errors = None
- _project_gradient_errors = None
- _project_image_aspect_ratio_errors = None
- _project_mask_errors = None
- _project_marker_errors = None
- _project_opacity_errors = None
- _project_paint_errors = None
- _project_paint_reference_errors = None
- _project_stroke_style_errors = None
- _project_transform_errors = None
- _rect_to_dml_xfrm = None
- _transform_point = None
- _unsafe_exported_font_faces = None
- _validate_dml_shape_matrix = None
-
-try:
- from svg_to_pptx.drawingml.paths import (
- iter_project_freeform_geometry as _iter_project_freeform_geometry,
- noncanonical_path_numbers as _noncanonical_path_numbers,
- noncanonical_points_numbers as _noncanonical_points_numbers,
- project_gradient_geometry_errors as _project_gradient_geometry_errors,
- )
-except ImportError:
- _iter_project_freeform_geometry = None
- _noncanonical_path_numbers = None
- _noncanonical_points_numbers = None
- _project_gradient_geometry_errors = None
-
-try:
- from svg_to_pptx.drawingml.converter import (
- SvgNativeConversionError as _SvgNativeConversionError,
- collect_unsupported_visuals as _collect_unsupported_visuals,
- preserved_native_text_body as _preserved_native_text_body,
- )
-except ImportError:
- _SvgNativeConversionError = None
- _collect_unsupported_visuals = None
- _preserved_native_text_body = None
-
-try:
- from svg_to_pptx.drawingml.elements import (
- drawingml_text_frame_width_emu as _drawingml_text_frame_width_emu,
- estimate_single_line_text_frame_width as _estimate_single_line_text_frame_width,
- project_clip_path_errors as _project_clip_path_errors,
- project_image_errors as _project_image_errors,
- project_nested_svg_crop_errors as _project_nested_svg_crop_errors,
- validate_single_line_text_run_advances as _validate_single_line_text_run_advances,
- validate_preset_geometry_metadata as _validate_preset_geometry_metadata,
- )
-except ImportError:
- _drawingml_text_frame_width_emu = None
- _estimate_single_line_text_frame_width = None
- _project_clip_path_errors = None
- _project_image_errors = None
- _project_nested_svg_crop_errors = None
- _validate_single_line_text_run_advances = None
- _validate_preset_geometry_metadata = None
-
-try:
- from svg_to_pptx.drawingml.text_properties import (
- normalize_project_text_segments as _normalize_project_text_segments,
- parse_project_font_weight as _parse_project_font_weight,
- parse_project_text_anchor as _parse_project_text_anchor,
- project_text_property_diagnostics as _project_text_property_diagnostics,
- resolve_project_xml_space as _resolve_project_xml_space,
- resolve_project_font_sizes as _resolve_project_font_sizes,
- resolve_project_letter_spacings as _resolve_project_letter_spacings,
- )
-except ImportError:
- _normalize_project_text_segments = None
- _parse_project_font_weight = None
- _parse_project_text_anchor = None
- _project_text_property_diagnostics = None
- _resolve_project_xml_space = None
- _resolve_project_font_sizes = None
- _resolve_project_letter_spacings = None
-
-try:
- from pptx_to_svg.preset_authoring import (
- AUTHORING_ATTR as _AUTHORING_ATTR,
- authored_preset_encoding as _authored_preset_encoding,
- validate_authored_preset_group as _validate_authored_preset_group,
- validate_authored_preset_tree as _validate_authored_preset_tree,
- )
-except ImportError:
- _AUTHORING_ATTR = 'data-pptx-authoring'
- _authored_preset_encoding = None
- _validate_authored_preset_group = None
- _validate_authored_preset_tree = None
-
-try:
- from pptx_shapes import (
- CONNECTOR_PRESET_TYPES as _CONNECTOR_PRESET_TYPES,
- resolve_preset_preview_hash as _resolve_preset_preview_hash,
- svg_preset_preview_fingerprint as _svg_preset_preview_fingerprint,
- )
-except ImportError:
- _CONNECTOR_PRESET_TYPES = frozenset()
- _resolve_preset_preview_hash = None
- _svg_preset_preview_fingerprint = None
-
-try:
- from svg_to_pptx.native_objects import (
- validate_native_object_marker as _validate_native_object_marker,
- )
-except ImportError:
- _validate_native_object_marker = None
-
-try:
- from svg_to_pptx.native_objects import (
- validate_native_object_marker_with_warnings as _validate_native_object_marker_with_warnings,
- )
-except ImportError:
- _validate_native_object_marker_with_warnings = None
-
-try:
- from svg_to_pptx.native_objects import (
- native_object_marker_warnings as _native_object_marker_warnings,
- )
-except ImportError:
- _native_object_marker_warnings = None
-
-try:
- from svg_to_pptx.native_objects import (
- native_fallback_kind as _native_fallback_kind,
- native_marker_legacy_warnings as _native_marker_legacy_warnings,
- native_replacement_kind as _native_replacement_kind,
- native_replacement_status as _native_replacement_status,
- )
-except ImportError:
- _native_fallback_kind = None
- _native_marker_legacy_warnings = None
- _native_replacement_kind = None
- _native_replacement_status = None
-
-try:
- from svg_to_pptx.native_objects.marker_status import (
- native_marker_release_block_reason as _native_marker_release_block_reason,
- native_marker_status_errors as _native_marker_status_errors,
- )
-except ImportError:
- _native_marker_release_block_reason = None
- _native_marker_status_errors = None
-
-try:
- from svg_to_pptx.semantic_markers import (
- SEMANTIC_ATTRS as _SEMANTIC_ATTRS,
- is_static_page_frame as _is_static_page_frame,
- validate_semantic_markers as _validate_semantic_markers,
- )
-except ImportError:
- _SEMANTIC_ATTRS = frozenset({
- 'data-pptx-page-role',
- 'data-pptx-role',
- })
- _is_static_page_frame = None
- _validate_semantic_markers = None
-
-try:
- from svg_to_pptx.geometry_properties import (
- materialize_inline_geometry_properties as _materialize_inline_geometry_properties,
- validate_inline_geometry_properties as _validate_inline_geometry_properties,
- )
-except ImportError:
- _materialize_inline_geometry_properties = None
- _validate_inline_geometry_properties = None
-
-try:
- from svg_to_pptx.use_expander import (
- UseExpansionError as _UseExpansionError,
- expand_local_use_references as _expand_local_use_references,
- validate_local_use_references as _validate_local_use_references,
- )
-except ImportError:
- _UseExpansionError = None
- _expand_local_use_references = None
- _validate_local_use_references = None
-
-try:
- from svg_to_pptx.tspan_flattener import (
- flatten_positional_tspans as _flatten_positional_tspans,
- nested_positional_tspan_errors as _nested_positional_tspan_errors,
- )
-except ImportError:
- _flatten_positional_tspans = None
- _nested_positional_tspan_errors = None
-
-try:
- from svg_to_pptx.pptx_package.template_structure import (
- TemplateStructureError as _TemplateStructureError,
- _is_authored_preset_atom as _is_authored_preset_atom,
- load_pptx_structure_lock as _load_pptx_structure_lock,
- parse_template_slide as _parse_template_structure_slide,
- parse_template_slides as _parse_template_structure_slides,
- _structure_subtree_signature as _structure_subtree_signature,
- template_lock_errors as _template_lock_errors,
- template_prototype_errors as _template_prototype_errors,
- validate_template_svg as _validate_template_structure_svg,
- )
-except ImportError:
- _TemplateStructureError = None
- _is_authored_preset_atom = None
- _load_pptx_structure_lock = None
- _parse_template_structure_slide = None
- _parse_template_structure_slides = None
- _structure_subtree_signature = None
- _template_lock_errors = None
- _template_prototype_errors = None
- _validate_template_structure_svg = None
-
-try:
- from svg_to_pptx.drawingml.theme_colors import (
- ThemeColorError as _ThemeColorError,
- load_theme_color_spec as _load_theme_color_spec,
- )
- from svg_to_pptx.drawingml.theme_fonts import (
- ThemeFontError as _ThemeFontError,
- load_master_text_style_spec as _load_master_text_style_spec,
- load_theme_font_spec as _load_theme_font_spec,
- )
-except ImportError:
- _ThemeColorError = None
- _ThemeFontError = None
- _load_theme_color_spec = None
- _load_master_text_style_spec = None
- _load_theme_font_spec = None
-
-try:
- from svg_finalize.embed_icons import (
- resolve_icon_path as _resolve_icon_path,
- suggest_icon_name as _suggest_icon_name,
- )
-except ImportError:
- _resolve_icon_path = None
- _suggest_icon_name = None
-
-try:
- from resource_paths import (
- SVG_WORK_DIR_NAMES as _SVG_WORK_DIR_NAMES,
- icon_search_dirs_for_svg as _icon_search_dirs_for_svg,
- project_root_for_svg_path as _project_root_for_svg_path,
- resolve_external_image_reference as _resolve_external_image_reference,
- )
-except ImportError:
- _SVG_WORK_DIR_NAMES = frozenset()
- _icon_search_dirs_for_svg = None
- _project_root_for_svg_path = None
- _resolve_external_image_reference = None
-
-
-HEX_VALUE_RE = re.compile(
- r"#(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})"
-)
-
-# Master/Layout preflight validation. Structured deck/layout-template projects
-# are checked at authoring time; the exporter remains the final OOXML/package
-# authority. Flat projects only receive the negative guard that rejects authored
-# structure metadata. Template roster/placeholder checks always run. Current
-# bundled templates opt in to complete structure validation through their
-# native_structure_mode: structured declaration. Legacy template-mode packages
-# fail closed; Create Template must author a new current-contract workspace.
-_CHECK_PPTX_STRUCTURED_PROJECT = True
-
-_BARE_HEX_VALUE_RE = re.compile(
- r"(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})"
-)
-_CANONICAL_PAINT_ALPHA_PROPERTY = {
- 'fill': 'fill-opacity',
- 'stroke': 'stroke-opacity',
- 'stop-color': 'stop-opacity',
- 'flood-color': 'flood-opacity',
-}
-SVG_NS = "http://www.w3.org/2000/svg"
-XLINK_NS = "http://www.w3.org/1999/xlink"
-_NON_VISUAL_SVG_TAGS = frozenset({
- 'defs',
- 'desc',
- 'metadata',
- 'style',
- 'title',
-})
-_BOUNDS_ATTR = 'data-pptx-bounds'
-_BOUNDS_OVERFLOW_TOLERANCE = 1.0
-_BOUNDS_OVERFLOW_ERROR_RATIO = 0.05
-_PARAGRAPH_LINE_GAP_MIN_RATIO = 0.9
-_PARAGRAPH_LINE_GAP_MAX_RATIO = 2.05
-_PARAGRAPH_LINE_X_TOLERANCE = 0.5
-_PARAGRAPH_LINE_MIN_TOTAL_CHARS = 12
-_PARAGRAPH_LINE_MIN_LONGEST_CHARS = 8
-_PARAGRAPH_LINE_TERMINATOR_RE = re.compile(r'[.!?。!?;;]["\'”’))]*$')
-_PARAGRAPH_LIST_MARKER_RE = re.compile(
- r'^\s*(?:[•·・▪◦‣]\s*|[-–—*]\s+|\d+[.)、]\s+|[((]\d+[))]\s*)\S+'
-)
-_LEGACY_PPTX_ATTRIBUTE_RENAMES = {
- 'data-pptx-module-bounds': _BOUNDS_ATTR,
- 'data-pptx-placeholder-bounds': _BOUNDS_ATTR,
- 'data-pptx-placeholder-carrier': 'data-pptx-carrier',
- 'data-pptx-placeholder-binding': 'data-pptx-binding',
- 'data-pptx-placeholder-idx': 'data-pptx-idx',
-}
-_PPTX_ROOT_STRUCTURE_ATTRS = (
- 'data-pptx-master',
- 'data-pptx-master-name',
- 'data-pptx-layout',
- 'data-pptx-layout-name',
-)
-_PPTX_ROOT_VISIBILITY_ATTRS = (
- 'data-pptx-show-master-shapes',
- 'data-pptx-show-inherited-shapes',
-)
-_PPTX_STRUCTURE_ATTRS = frozenset({
- *_PPTX_ROOT_STRUCTURE_ATTRS,
- *_PPTX_ROOT_VISIBILITY_ATTRS,
- 'data-pptx-layer',
- 'data-pptx-layout-kind',
- 'data-pptx-placeholder',
- 'data-pptx-binding',
- 'data-pptx-carrier',
- 'data-pptx-idx',
-})
-_PPTX_PLACEHOLDER_DETAIL_ATTRS = frozenset({
- 'data-pptx-binding',
- 'data-pptx-idx',
-})
-_PPTX_STRUCTURE_SECTION_RE = re.compile(
- r"(?ms)^##[ \t]+pptx_structure[ \t]*\r?\n(.*?)(?=^##[ \t]+|\Z)"
-)
-_PPTX_STRUCTURE_MODE_RE = re.compile(
- r"(?m)^-[ \t]+mode[ \t]*:[ \t]*([^\s#]+)[ \t]*(?:#.*)?$"
-)
-_SUPPORTED_INLINE_STYLE_PROPERTIES = frozenset({
- 'cx', 'cy', 'fill', 'fill-opacity', 'filter', 'flood-color',
- 'flood-opacity', 'font-family', 'font-size', 'font-style', 'font-weight',
- 'height', 'letter-spacing', 'opacity', 'r', 'rx', 'ry',
- 'shape-rendering', 'stop-color', 'stop-opacity', 'stroke',
- 'stroke-dasharray', 'stroke-linecap', 'stroke-linejoin', 'stroke-opacity',
- 'stroke-width', 'text-anchor', 'text-decoration', 'vector-effect',
- 'width', 'x', 'y',
-})
-_BAKE_REQUIRED_VISUAL_PROPERTIES = frozenset({
- 'backdrop-filter',
- 'isolation',
- 'mix-blend-mode',
-})
-_SHARED_FAIL_CLOSED_STYLE_PROPERTIES = frozenset({'mask'})
-
-
-def _compact_preset_ancestor_paint(
- root: ET.Element,
-) -> list[tuple[str, tuple[str, ...]]]:
- """Return compact presets affected by compatible ancestor paint."""
- if (
- _authored_preset_encoding is None
- or _validate_authored_preset_group is None
- ):
- return []
- parents = {
- child: parent
- for parent in root.iter()
- for child in parent
- }
- affected: list[tuple[str, tuple[str, ...]]] = []
- for group in root.iter():
- if (
- _authored_preset_encoding(group) != 'compact'
- or _validate_authored_preset_group(group)
- ):
- continue
- relevant = {'opacity'}
- if group.get('fill') != 'none' and group.get('fill-opacity') is None:
- relevant.add('fill-opacity')
- if group.get('stroke') != 'none':
- for name in (
- 'stroke-opacity',
- 'stroke-dasharray',
- 'stroke-linecap',
- 'stroke-linejoin',
- ):
- if group.get(name) is None:
- relevant.add(name)
-
- inherited: set[str] = set()
- ancestor = parents.get(group)
- while ancestor is not None:
- declarations = {
- name: ancestor.get(name) or ''
- for name in relevant
- if ancestor.get(name) is not None
- }
- for declaration in (ancestor.get('style') or '').split(';'):
- name, separator, value = declaration.partition(':')
- name = name.strip().lower()
- if separator and name in relevant:
- declarations[name] = value.strip()
- for name, value in declarations.items():
- normalized = value.strip().lower()
- if name in {'opacity', 'fill-opacity', 'stroke-opacity'}:
- try:
- if float(normalized) == 1:
- continue
- except ValueError:
- pass
- elif name == 'stroke-dasharray' and normalized == 'none':
- continue
- elif name == 'stroke-linecap' and normalized == 'butt':
- continue
- elif name == 'stroke-linejoin' and normalized == 'miter':
- continue
- inherited.add(name)
- ancestor = parents.get(ancestor)
- if inherited:
- affected.append((
- group.get('id') or '(no id)',
- tuple(sorted(inherited)),
- ))
- return affected
-
-
-def _declared_pptx_structure_mode(project_path: Path) -> str | None:
- """Return the explicitly locked SVG structure mode without a fallback."""
- lock_path = project_path / 'spec_lock.md'
- try:
- content = lock_path.read_text(encoding='utf-8')
- except OSError:
- return None
- section_match = _PPTX_STRUCTURE_SECTION_RE.search(content)
- if section_match is None:
- return None
- mode_match = _PPTX_STRUCTURE_MODE_RE.search(section_match.group(1))
- return mode_match.group(1).strip().lower() if mode_match else None
-
-
-def _generated_theme_contract_errors(project_path: Path) -> List[str]:
- """Validate the current-project theme contract required by release export."""
- if (
- _ThemeColorError is None
- or _ThemeFontError is None
- or _load_theme_color_spec is None
- or _load_master_text_style_spec is None
- or _load_theme_font_spec is None
- ):
- return [
- "PowerPoint theme contract validation is unavailable because the "
- "theme loader modules could not be imported."
- ]
- try:
- theme_font_spec = _load_theme_font_spec(project_path)
- _load_master_text_style_spec(project_path)
- theme_color_spec = _load_theme_color_spec(project_path)
- except (_ThemeFontError, _ThemeColorError) as exc:
- return [str(exc)]
-
- missing: List[str] = []
- if theme_font_spec is None:
- missing.append("typography font_family/title_family/body_family")
- if theme_color_spec is None:
- missing.append("colors")
- if not missing:
- return []
- return [
- "spec_lock.md generated PowerPoint theme contract is missing: "
- + ", ".join(missing)
- ]
-
-
-def _parse_positive_bounds(
- value: str,
-) -> Tuple[float, float, float, float]:
- """Parse one positive x/y/width/height boundary."""
- raw_values = [item for item in re.split(r"[\s,]+", value.strip()) if item]
- if len(raw_values) != 4:
- raise ValueError("must contain exactly four numbers: x y width height")
- try:
- values = tuple(float(item) for item in raw_values)
- except ValueError as exc:
- raise ValueError("must contain only numeric values") from exc
- if not all(math.isfinite(item) for item in values):
- raise ValueError("must contain only finite values")
- if values[2] <= 0 or values[3] <= 0:
- raise ValueError("must use positive width and height")
- return values
-
-
-def _placeholder_bounds_error(value: str) -> str | None:
- """Return a concise error for invalid design-zone bounds."""
- try:
- _parse_positive_bounds(value)
- except ValueError as exc:
- return str(exc)
- return None
-
-
-def _local_pptx_structure_errors(
- root: ET.Element,
- svg_path: Path,
- *,
- require_structure: bool,
-) -> List[str]:
- """Validate the authoring shape of the structured SVG contract."""
- errors: List[str] = []
- root_values = {
- attr: (root.get(attr) or '').strip()
- for attr in _PPTX_ROOT_STRUCTURE_ATTRS
- }
- has_root_structure = any(root_values.values())
- if require_structure or has_root_structure:
- missing = [attr for attr, value in root_values.items() if not value]
- if missing:
- errors.append(
- f"{svg_path.name}: structured SVG root is missing "
- + ', '.join(missing)
- )
- for attr in _PPTX_ROOT_VISIBILITY_ATTRS:
- raw = root.get(attr)
- if raw is not None and raw not in {'true', 'false'}:
- errors.append(
- f"{svg_path.name}: root {attr} must be exactly 'true' or 'false'"
- )
-
- parent_by_id = {
- id(child): parent
- for parent in root.iter()
- for child in list(parent)
- }
- for elem in root.iter():
- tag = elem.tag.rsplit('}', 1)[-1]
- element_id = elem.get('id') or f"<{tag}>"
- parent = parent_by_id.get(id(elem))
-
- if elem is not root:
- nested_root_attrs = [
- attr for attr in (
- *_PPTX_ROOT_STRUCTURE_ATTRS,
- *_PPTX_ROOT_VISIBILITY_ATTRS,
- )
- if elem.get(attr) is not None
- ]
- if nested_root_attrs:
- errors.append(
- f"{svg_path.name}: {element_id} carries root-only metadata "
- + ', '.join(nested_root_attrs)
- )
-
- if elem.get('data-pptx-layout-kind') is not None:
- errors.append(
- f"{svg_path.name}: data-pptx-layout-kind is a legacy distillation "
- "attribute; restore the page to the structured contract"
- )
-
- layer = (elem.get('data-pptx-layer') or '').strip().lower()
- placeholder = (elem.get('data-pptx-placeholder') or '').strip().lower()
- if layer in {'master', 'layout'}:
- if parent is not root:
- errors.append(
- f"{svg_path.name}: {element_id} data-pptx-layer={layer!r} "
- "must be a direct child of the root <svg>"
- )
- if tag == 'g' and not (
- _is_authored_preset_atom is not None
- and _is_authored_preset_atom(elem)
- ):
- errors.append(
- f"{svg_path.name}: {element_id} is a <g> marked as {layer}; "
- "Master/Layout fixed visuals must be root-level atomic elements"
- )
- if placeholder:
- errors.append(
- f"{svg_path.name}: {element_id} cannot be both a fixed "
- f"{layer} element and a placeholder slot"
- )
-
- detail_attrs = [
- attr for attr in _PPTX_PLACEHOLDER_DETAIL_ATTRS
- if elem.get(attr) is not None
- ]
- if detail_attrs and not placeholder:
- errors.append(
- f"{svg_path.name}: {element_id} uses placeholder detail metadata "
- "without data-pptx-placeholder"
- )
-
- if placeholder:
- if parent is not root:
- errors.append(
- f"{svg_path.name}: placeholder slot {element_id} must be a "
- "direct child of the root <svg>"
- )
- if tag != 'g':
- errors.append(
- f"{svg_path.name}: placeholder slot {element_id} must be a "
- "root-level <g>"
- )
- if not (elem.get('id') or '').strip():
- errors.append(
- f"{svg_path.name}: every placeholder slot <g> requires a stable id"
- )
- wrapper_attrs = sorted(
- attr.rsplit('}', 1)[-1]
- for attr in elem.attrib
- if attr != 'id'
- and not attr.rsplit('}', 1)[-1].startswith('data-pptx-')
- )
- if wrapper_attrs:
- errors.append(
- f"{svg_path.name}: placeholder slot {element_id} is an "
- "authoring boundary and may carry only id/data-pptx-*; remove "
- + ', '.join(wrapper_attrs)
- )
- bounds = (elem.get('data-pptx-bounds') or '').strip()
- if not bounds:
- errors.append(
- f"{svg_path.name}: placeholder slot {element_id} requires "
- "data-pptx-bounds"
- )
- else:
- bounds_error = _placeholder_bounds_error(bounds)
- if bounds_error:
- errors.append(
- f"{svg_path.name}: placeholder slot {element_id} bounds "
- + bounds_error
- )
-
- binding = (
- elem.get('data-pptx-binding') or 'carrier'
- ).strip().lower()
- if binding not in {'carrier', 'proxy'}:
- errors.append(
- f"{svg_path.name}: placeholder slot {element_id} has unknown "
- f"binding {binding!r}; use carrier or proxy"
- )
- carrier_descendants = [
- child for child in elem.iter()
- if child is not elem
- and child.get('data-pptx-carrier') is not None
- ]
- visual_children = [
- child for child in list(elem)
- if child.tag.rsplit('}', 1)[-1] not in _NON_VISUAL_SVG_TAGS
- ]
- direct_carriers = [
- child for child in visual_children
- if (child.get('data-pptx-carrier') or '').strip().lower()
- == 'true'
- ]
- nested_carriers = [
- child for child in carrier_descendants
- if parent_by_id.get(id(child)) is not elem
- ]
- if nested_carriers:
- names = ', '.join(
- child.get('id') or f"<{child.tag.rsplit('}', 1)[-1]}>"
- for child in nested_carriers
- )
- errors.append(
- f"{svg_path.name}: placeholder slot {element_id} has nested "
- f"carrier marker(s): {names}; the carrier must be a direct child"
- )
- if binding == 'carrier':
- if len(visual_children) != 1 or len(direct_carriers) != 1:
- errors.append(
- f"{svg_path.name}: placeholder slot {element_id} requires "
- "exactly one visual direct child, marked "
- "data-pptx-carrier=\"true\""
- )
- if binding == 'proxy':
- if placeholder != 'object':
- errors.append(
- f"{svg_path.name}: proxy binding is allowed only for an "
- f"object placeholder, not {placeholder!r}"
- )
- if carrier_descendants:
- errors.append(
- f"{svg_path.name}: proxy placeholder slot {element_id} must "
- "not declare a visible placeholder carrier"
- )
- if not visual_children:
- errors.append(
- f"{svg_path.name}: proxy placeholder slot {element_id} must "
- "contain visible Slide-local content"
- )
-
- carrier_value = elem.get('data-pptx-carrier')
- if carrier_value is not None:
- if carrier_value.strip().lower() != 'true':
- errors.append(
- f"{svg_path.name}: {element_id} "
- "data-pptx-carrier must equal true"
- )
- if parent is None or not (
- parent.get('data-pptx-placeholder') or ''
- ).strip():
- errors.append(
- f"{svg_path.name}: placeholder carrier {element_id} must be a "
- "direct child of a root placeholder slot"
- )
-
- if tag in _NON_VISUAL_SVG_TAGS and (layer or placeholder):
- errors.append(
- f"{svg_path.name}: non-visual {element_id} cannot carry "
- "Master/Layout/placeholder ownership"
- )
-
- return list(dict.fromkeys(errors))
-
-
-def _normalize_hex_rgb(value: str) -> str | None:
- """Normalize 3/4/6/8-digit HEX to alpha-free ``RRGGBB``."""
- if not HEX_VALUE_RE.fullmatch(value):
- return None
- color = value[1:]
- if len(color) in {3, 4}:
- color = ''.join(channel * 2 for channel in color)
- return color[:6].upper()
-
-
-# Cheap numeric envelope for font-size role enforcement. Semantic role assignment
-# is prompt-owned; Checker only verifies that a used value is close to at least
-# one declared size anchor.
-FONT_SIZE_ANCHOR_TOLERANCE_PX = 2.0
-SPARSE_UNDECLARED_FONT_SIZE_MAX_OCCURRENCES = 2
-
-# Oversampling alone does not imply distortion and is often harmless for small
-# logos. Warn about downscaling only when the source also has material on-disk
-# weight, because PPTX embeds the compressed source asset rather than raw pixels.
-IMAGE_DOWNSIZE_WARN_RATIO = 4.0
-IMAGE_DOWNSIZE_WARN_MIN_BYTES = 1024 * 1024
-
-def _design_spec_is_brand(spec_path: Path) -> bool:
- """Return True when a design_spec.md frontmatter declares ``kind: brand``.
-
- Lightweight detector that does not require PyYAML — scans only the
- frontmatter block (``---`` delimited) for a ``kind:`` line whose value
- contains ``brand``. Used by ``check_directory`` to select Brand schema
- validation instead of SVG-roster validation.
- """
- try:
- text = spec_path.read_text(encoding='utf-8')
- except OSError:
- return False
- if not text.startswith('---\n'):
- return False
- end = text.find('\n---\n', 4)
- if end == -1:
- return False
- fm_block = text[4:end]
- for line in fm_block.splitlines():
- stripped = line.strip()
- if stripped.startswith('kind:'):
- value = stripped.split(':', 1)[1].strip().strip('"\'')
- return value == 'brand'
- return False
-
-
-def _declared_template_structure_mode(target_path: Path) -> str | None:
- """Return a template directory's explicit native structure mode."""
- directory = target_path.parent if target_path.is_file() else target_path
- spec_path = directory / 'design_spec.md'
- try:
- text = spec_path.read_text(encoding='utf-8')
- except OSError:
- return None
- if not text.startswith('---\n'):
- return None
- end = text.find('\n---\n', 4)
- if end == -1:
- return None
- match = re.search(
- r'^native_structure_mode:\s*([A-Za-z0-9_-]+)\s*$',
- text[4:end],
- re.MULTILINE,
- )
- return match.group(1).lower() if match else None
-
-
-def _declared_template_canvas_viewbox(target_path: Path) -> str | None:
- """Return a template design spec's locked root-canvas value."""
- directory = target_path.parent if target_path.is_file() else target_path
- spec_path = directory / 'design_spec.md'
- try:
- text = spec_path.read_text(encoding='utf-8')
- except OSError:
- return None
- if not text.startswith('---\n'):
- return None
- end = text.find('\n---\n', 4)
- if end == -1:
- return None
- match = re.search(
- r'^canvas_viewbox:\s*["\']?([^"\'\r\n]+?)["\']?\s*$',
- text[4:end],
- re.MULTILINE,
- )
- return match.group(1).strip() if match else None
-
-
-def _template_structure_checks_enabled(target_path: Path) -> bool:
- """Return whether positive structure checks apply to this template."""
- return _declared_template_structure_mode(target_path) == 'structured'
-
-
-def _local_name(elem: ET.Element) -> str:
- """Return an XML element's namespace-free local tag name."""
- tag = elem.tag
- if not isinstance(tag, str):
- return ''
- return tag.rsplit('}', 1)[-1] if '}' in tag else tag
-
-
-def _direct_defs_index(
- root: ET.Element,
-) -> tuple[Dict[str, ET.Element], set[str]]:
- """Return direct ``<defs>`` children by id plus duplicate ids."""
- definitions: Dict[str, ET.Element] = {}
- duplicates: set[str] = set()
- for defs_elem in root.iter():
- if _local_name(defs_elem) != 'defs':
- continue
- for child in defs_elem:
- definition_id = (child.get('id') or '').strip()
- if not definition_id:
- continue
- if definition_id in definitions:
- duplicates.add(definition_id)
- definitions[definition_id] = child
- return definitions, duplicates
-
-
-def _element_label(elem: ET.Element) -> str:
- """Return a compact element label for validation messages."""
- tag = _local_name(elem)
- elem_id = (elem.get('id') or '').strip()
- return f'<{tag} id="{elem_id}">' if elem_id else f'<{tag}>'
-
-
-def _effective_presentation_value(
- elem: ET.Element,
- name: str,
- parent_by_id: Dict[int, ET.Element],
-) -> str | None:
- """Resolve one inherited presentation property for validation."""
- current: ET.Element | None = elem
- while current is not None:
- style_values = (
- _parse_inline_style(current.get('style'))
- if _parse_inline_style is not None else {}
- )
- if name in style_values:
- return style_values[name]
- direct = current.get(name)
- if direct is not None:
- return direct
- current = parent_by_id.get(id(current))
- return None
-
-
-def _parse_viewbox_values(viewbox: str) -> Tuple[float, float, float, float] | None:
- """Parse a root viewBox into four numeric values."""
- try:
- parsed = parse_project_viewbox(viewbox)
- except CanvasContractError:
- return None
- return 0.0, 0.0, float(parsed.width), float(parsed.height)
-
-
-def _parse_placeholders_fallback(block: str) -> Dict[str, Tuple[str, ...]]:
- """Tiny YAML-free reader for the documented ``placeholders:`` shape.
-
- Used only when PyYAML is unavailable. Recognized lines (indentation-aware,
- two-space indent assumed):
-
- .. code-block:: yaml
-
- placeholders:
- 01_cover: ["{{TITLE}}", "{{LOGO}}"]
- 03_content: []
- 03a_content_two_col:
- - "{{LEFT_TITLE}}"
- - "{{RIGHT_TITLE}}"
-
- Anything outside this minimal grammar is silently skipped — designers who
- rely on advanced YAML should install pyyaml.
- """
- out: Dict[str, Tuple[str, ...]] = {}
- inline_re = re.compile(
- r"^\s{2}([A-Za-z0-9_]+)\s*:\s*\[(.*)\]\s*$"
- )
- empty_re = re.compile(r"^\s{2}([A-Za-z0-9_]+)\s*:\s*\[\s*\]\s*$")
- block_header_re = re.compile(r"^\s{2}([A-Za-z0-9_]+)\s*:\s*$")
- item_re = re.compile(r'^\s{4}-\s*"?([^"]+)"?\s*$')
-
- in_section = False
- current_block_key: str | None = None
- current_items: List[str] = []
-
- def _flush_block() -> None:
- nonlocal current_block_key, current_items
- if current_block_key is not None:
- out[current_block_key] = tuple(current_items)
- current_block_key = None
- current_items = []
-
- for line in block.splitlines():
- if line.startswith("placeholders:"):
- in_section = True
- continue
- if not in_section:
- continue
-
- # End of section: dedent to a non-key line.
- if line and not line.startswith(" "):
- _flush_block()
- in_section = False
- continue
-
- if current_block_key is not None:
- m = item_re.match(line)
- if m:
- value = m.group(1).strip().strip('"').strip("'")
- if value:
- current_items.append(value)
- continue
- # Block ended.
- _flush_block()
-
- if empty_re.match(line):
- key = empty_re.match(line).group(1)
- out[key] = ()
- continue
-
- m = inline_re.match(line)
- if m:
- key, raw = m.group(1), m.group(2)
- items = [p.strip().strip('"').strip("'") for p in raw.split(",")]
- out[key] = tuple(item for item in items if item)
- continue
-
- m = block_header_re.match(line)
- if m:
- current_block_key = m.group(1)
- current_items = []
- continue
-
- _flush_block()
- return out
-
-
-class SVGQualityChecker:
- """SVG quality checker"""
-
- # Default placeholder convention per page-type prefix. This is a *hint*,
- # not a hard contract: templates may define their own placeholder vocabulary
- # via `placeholders:` in design_spec.md frontmatter (see
- # references/template-designer.md §4). Missing default placeholders surface
- # as warnings, never errors — designers may legitimately swap
- # `{{THANK_YOU}}` for `{{CLOSING_MESSAGE}}`, omit `{{DATE}}` when irrelevant,
- # or build content variants with bespoke slot vocabularies.
- #
- # Variants reuse the parent type's expectation (`03a_content_two_col.svg`
- # is matched by the same `content` rules as `03_content.svg`).
- #
- # Keys are page-type tokens, not numbered stems: template numbering is
- # presentation order within one template and shifts when the optional
- # TOC page is present (`02_chapter` in a four-page roster, `03_chapter`
- # in a five-page roster with `02_toc`), so the defaults must apply to
- # both spellings.
- DEFAULT_PLACEHOLDER_CONVENTION = {
- "cover": ("{{TITLE}}",), # only the title is universally expected
- "chapter": ("{{CHAPTER_TITLE}}",),
- "toc": (), # TOC layouts vary too widely to assert anything
- "content": ("{{PAGE_TITLE}}",),
- "ending": (), # ending pages legitimately use varied vocabularies
- }
-
- def __init__(
- self,
- *,
- template_mode: bool = False,
- quick_generate: bool = False,
- ):
- self.template_mode = template_mode
- self.quick_generate = quick_generate
- self.results = []
- self.summary = {
- 'total': 0,
- 'passed': 0,
- 'warnings': 0,
- 'errors': 0
- }
- self.issue_types = defaultdict(int)
- # spec_lock anchor comparison state (populated only when
- # _parse_spec_lock is available and a spec_lock.md is found near the SVG)
- self._lock_cache: Dict[Path, Dict] = {}
- self._anchor_value_summary: Dict[str, Dict[str, set]] = {
- 'colors': defaultdict(set),
- 'fonts': defaultdict(set),
- 'sizes': defaultdict(set),
- }
- self._undeclared_size_occurrences: Counter[str] = Counter()
- self._undeclared_size_counts_ready = False
- self._lock_seen = False # True once we locate at least one spec_lock.md
- self._source_manifest_cache: Dict[
- Path,
- Tuple[Dict, str | None],
- ] = {}
- self._source_manifest_errors_reported: set[Path] = set()
- # Template-mode aggregation (populated by check_directory when
- # template_mode=True). Each entry is (severity, kind, message) where
- # severity is 'error' or 'warning'. Printed in print_summary.
- self._template_issues: List[Tuple[str, str, str]] = []
- self._brand_template_checked = False
- self._animation_issues: List[Tuple[str, str]] = []
- self._illustration_issues: List[Tuple[str, str, str]] = []
- self._communication_trace_issues: List[Tuple[str, str]] = []
- self._pptx_structure_issues: List[Tuple[str, str]] = []
- self._has_incomplete_page_roster = False
- self._prototype_by_output: Dict[Path, Path] = {}
- self._active_prototype_path: Path | None = None
- self._active_template_reuse_scope: str | None = None
- self._prototype_root_cache: Dict[Path, ET.Element | None] = {}
- self._source_import_summary: Dict[str, object] = {
- 'warning_count': 0,
- 'by_code': {},
- }
- self._aggregate_counts_applied = False
-
- @staticmethod
- def _append_inherited_info(
- result: Dict,
- kind: str,
- message: str,
- ) -> None:
- """Record prototype-owned diagnostics outside the warning channel."""
- result['info'].setdefault('inherited', []).append({
- 'kind': kind,
- 'message': message,
- })
-
- def _active_prototype_root(self) -> ET.Element | None:
- """Parse the selected mirror prototype once for inherited checks."""
- if (
- self._active_template_reuse_scope != 'mirror'
- or self._active_prototype_path is None
- ):
- return None
- path = self._active_prototype_path.resolve()
- if path in self._prototype_root_cache:
- return self._prototype_root_cache[path]
- try:
- root = ET.parse(path).getroot()
- hydrate_native_payload_refs(root, path)
- except (OSError, ET.ParseError, NativePayloadError):
- root = None
- self._prototype_root_cache[path] = root
- return root
-
- def check_file(
- self,
- svg_file: str,
- expected_format: str = None,
- *,
- expected_viewbox: str | None = None,
- expected_viewbox_label: str = "expected canvas",
- ) -> Dict:
- """
- Check a single SVG file
-
- Args:
- svg_file: SVG file path
- expected_format: Expected canvas format (e.g., 'ppt169')
-
- Returns:
- Check result dictionary
- """
- svg_path = Path(svg_file)
-
- if not svg_path.exists():
- return {
- 'file': str(svg_file),
- 'exists': False,
- 'errors': ['File does not exist'],
- 'warnings': [],
- 'passed': False
- }
-
- result = {
- 'file': svg_path.name,
- 'path': str(svg_path),
- 'exists': True,
- 'errors': [],
- 'warnings': [],
- 'info': {},
- 'passed': True
- }
-
- try:
- source_bytes = svg_path.read_bytes()
- result['source_sha256'] = hashlib.sha256(source_bytes).hexdigest()
- content = source_bytes.decode('utf-8')
-
- # 0. Parse XML once — every other check assumes the file is valid
- # XML. Bail early on failure so the regex-based checks below don't
- # produce misleading errors on a broken document.
- root = self._parse_xml_root(content, result)
- if root is not None:
- try:
- hydrated_payloads = hydrate_native_payload_refs(root, svg_path)
- except NativePayloadError as exc:
- result['errors'].append(
- f"Invalid native payload reference: {exc}"
- )
- else:
- if hydrated_payloads:
- result['info']['native_payload_refs'] = hydrated_payloads
-
- # 1. Check viewBox
- self._check_viewbox(
- root,
- svg_path,
- result,
- expected_format,
- expected_viewbox=expected_viewbox,
- expected_viewbox_label=expected_viewbox_label,
- )
- self._check_legacy_pptx_attributes(root, svg_path, result)
-
- # 1a. Validate exact importer transport before compatible
- # inline geometry is materialized on the shared tree.
- self._check_nested_svg_crop_contract(root, result)
-
- # 2. Check forbidden elements
- self._check_forbidden_elements(content, root, result)
- self._check_mask_contract(root, result)
-
- # 2a. Validate direct geometry lengths and stroke widths.
- self._check_geometry_length_values(root, result)
-
- # 2b. Validate line-presentation grammar and mappings.
- self._check_stroke_style_values(root, result)
-
- # 2c. Validate image fit/crop grammar and mappings.
- self._check_image_contract(root, svg_path, result)
- self._check_image_aspect_ratio_values(root, result)
-
- # 2d. Validate complete path-data and point-list grammar.
- self._check_freeform_geometry_values(root, result)
-
- # 2e. Validate complete transform grammar and native mappings.
- self._check_transform_values(root, result)
-
- # 2f. Validate opacity grammar and native alpha mappings.
- self._check_opacity_values(root, result)
-
- # 2g. Validate the closed authoring-property surface and
- # conditional definition interfaces before export.
- self._check_authoring_property_contract(root, result)
- self._check_text_property_contract(root, result)
- self._check_preserved_txbody_contract(root, result)
- self._check_paint_compatibility(root, result)
- self._check_reference_spelling(root, result)
- self._check_definition_contract(root, result)
- self._check_paint_reference_contract(root, result)
- self._check_marker_contract(root, result)
- self._check_clip_path_contract(root, result)
-
- # 2h. Validate the supported shadow/glow filter interface.
- self._check_imported_effect_status(root, result)
- self._check_filter_effects(root, result)
-
- # 2i. Validate gradient definitions, stops, and coordinates.
- self._check_gradient_interfaces(root, result)
-
- # 3. Check font-size values
- self._check_font_size_values(content, result)
-
- # 4. Check fonts
- self._check_fonts(content, result)
-
- # 5. Check text wrapping methods
- self._check_text_elements(content, root, result)
-
- # 6. Check image references (file existence and resolution)
- self._check_image_references(root, svg_path, result)
-
- # 7. Check icon placeholders resolve before post-processing.
- self._check_icon_placeholders(root, svg_path, result)
-
- # 7b. Reject visual elements the native converter cannot dispatch.
- self._check_unsupported_visual_elements(root, result)
-
- # 7c. Fail closed on invalid PPTX preset/adjustment metadata.
- self._check_preset_geometry_metadata(root, result)
- self._check_preset_geometry_transforms(root, result)
-
- # 8. Check object-level animation anchor quality.
- self._check_animation_group_ids(root, svg_path, result)
-
- # 8b. Check <pattern> elements declare a PPTX preset.
- self._check_pattern_fills(root, result)
-
- # 8c. Check opt-in native table/chart markers before export.
- self._check_native_object_markers(root, result)
-
- # 8d. Validate explicit master/layout/placeholder metadata.
- if (
- _template_structure_checks_enabled(svg_path)
- if self.template_mode
- else _CHECK_PPTX_STRUCTURED_PROJECT
- ):
- self._check_pptx_structure_metadata(root, svg_path, result)
-
- # 8e. Validate rendering-neutral page/structure compiler hints.
- self._check_semantic_markers(root, svg_path, result)
-
- # 9. Compare values with spec_lock anchors. Additional colors
- # and fonts are informational. Generated-page type sizes may
- # stay sparse twice; the third occurrence is an error. Other
- # spec-backed SVG locations retain advisory review. Templates
- # do not ship a spec_lock.md, so skip in template mode.
- if not self.template_mode:
- self._check_spec_lock_alignment(
- content,
- svg_path,
- result,
- root=root,
- )
-
- # 10. Check web-sourced image attribution. Templates don't carry
- # image_sources.json; skip in template mode.
- if not self.template_mode:
- self._check_sourced_image_attribution(
- root,
- svg_path,
- result,
- )
-
- # Determine pass/fail
- result['passed'] = len(result['errors']) == 0
-
- except Exception as e:
- result['errors'].append(f"Failed to read file: {e}")
- result['passed'] = False
-
- # Update statistics
- self.summary['total'] += 1
- if result['passed']:
- if result['warnings']:
- self.summary['warnings'] += 1
- else:
- self.summary['passed'] += 1
- else:
- self.summary['errors'] += 1
-
- # Categorize issue types
- for error in result['errors']:
- self.issue_types[self._categorize_issue(error)] += 1
-
- self.results.append(result)
- return result
-
- def _parse_xml_root(self, content: str, result: Dict) -> ET.Element | None:
- """Parse the SVG content as well-formed XML.
-
- SVG is strict XML. AI-generated decks frequently produce content that
- looks fine in HTML5-tolerant previews but fails strict XML parsing —
- common causes are HTML named entities (&nbsp; &mdash; &copy;…) and
- bare XML reserved characters in text (R&D, error < 5%). Such pages
- cannot be exported to PPTX, so we surface them here as a hard error
- before any downstream check looks at them.
-
- Returns the parsed root when the document is well-formed; otherwise
- appends an error and returns None.
- """
- try:
- return ET.fromstring(content)
- except ET.ParseError as e:
- result['errors'].append(
- f"Invalid XML: {e} — SVG must be well-formed XML. "
- f"Use raw Unicode for typography (—, ©, →, NBSP); "
- f"escape XML reserved chars as &amp; &lt; &gt; &quot; &apos; "
- f"(see references/shared-standards-core.md §1)."
- )
- return None
-
- def _check_viewbox(
- self,
- root: ET.Element,
- svg_path: Path,
- result: Dict,
- expected_format: str = None,
- *,
- expected_viewbox: str | None = None,
- expected_viewbox_label: str = "expected canvas",
- ):
- """Validate the root page canvas and its project-level locks."""
- viewbox = root.get('viewBox')
- try:
- parsed = parse_project_svg_root(
- root,
- context=svg_path.name,
- )
- except CanvasContractError as exc:
- result['errors'].append(str(exc))
- return
- assert viewbox is not None
- result['info']['viewbox'] = viewbox
- if viewbox != parsed.canonical or not parsed.has_integer_dimensions:
- if parsed.has_integer_dimensions:
- recommendation = f'write viewBox="{parsed.canonical}"'
- else:
- recommendation = (
- "fractional dimensions are reserved for compatible imported "
- "custom slide sizes; new authoring uses integer pixels"
- )
- result['warnings'].append(
- f"Compatible non-canonical root viewBox {viewbox!r}; {recommendation}."
- )
-
- contracts: list[tuple[str, str]] = []
- if expected_viewbox is not None:
- contracts.append((expected_viewbox_label, expected_viewbox))
- elif not self.template_mode:
- lock = self._get_spec_lock(svg_path)
- if lock is not None and 'canvas' in lock:
- locked_viewbox = lock.get('canvas', {}).get('viewBox')
- if not locked_viewbox:
- result['errors'].append(
- "spec_lock.md canvas section must declare viewBox"
- )
- else:
- contracts.append(("spec_lock canvas", locked_viewbox))
-
- if expected_format and expected_format in CANVAS_FORMATS:
- contracts.append((
- f"canvas format {expected_format!r}",
- CANVAS_FORMATS[expected_format]['viewbox'],
- ))
- elif expected_format:
- result['errors'].append(f"Unsupported canvas format: {expected_format}")
-
- seen_contracts: set[tuple[str, str]] = set()
- for label, raw_expected in contracts:
- contract_key = (label, raw_expected)
- if contract_key in seen_contracts:
- continue
- seen_contracts.add(contract_key)
- try:
- expected = parse_project_viewbox(
- raw_expected,
- context=f"{label} viewBox",
- )
- except CanvasContractError as exc:
- result['errors'].append(str(exc))
- continue
- if parsed != expected:
- result['errors'].append(
- f"viewBox mismatch: {label} requires '{expected.canonical}', "
- f"got '{parsed.canonical}'"
- )
-
- def _check_forbidden_elements(self, content: str, root: ET.Element, result: Dict):
- """Check forbidden elements (blocklist)"""
- content_lower = content.lower()
- elems = list(root.iter())
- local_names = {_local_name(elem).lower() for elem in elems}
-
- # ============================================================
- # Forbidden elements blocklist - PPT incompatible
- # ============================================================
-
- # Style system
- if 'style' in local_names:
- result['errors'].append("Detected forbidden <style> element (use inline attributes instead)")
- if re.search(r'\bclass\s*=', content):
- result['errors'].append("Detected forbidden class attribute (use inline styles instead)")
- # id attribute: only report error when <style> also exists (id is harmful only with CSS selectors)
- # id inside <defs> for linearGradient/filter etc. is required, Inkscape also auto-adds id to elements,
- # standalone id attributes have no impact on PPT export
- if 'style' in local_names and re.search(r'\bid\s*=', content):
- result['errors'].append(
- "Detected id attribute used with <style> (CSS selectors forbidden, use inline styles instead)"
- )
- if re.search(r'<\?xml-stylesheet\b', content_lower):
- result['errors'].append("Detected forbidden xml-stylesheet (external CSS references forbidden)")
- if re.search(r'<link[^>]*rel\s*=\s*["\']stylesheet["\']', content_lower):
- result['errors'].append("Detected forbidden <link rel=\"stylesheet\"> (external CSS references forbidden)")
- if re.search(r'@import\s+', content_lower):
- result['errors'].append("Detected forbidden @import (external CSS references forbidden)")
- if _validate_inline_geometry_properties is None:
- result['warnings'].append(
- "Unable to import inline geometry validator; "
- "native export will still validate geometry styles."
- )
- else:
- geometry_errors = _validate_inline_geometry_properties(root)
- for error in geometry_errors:
- result['errors'].append(f"Invalid inline geometry property: {error}")
- if not geometry_errors:
- _materialize_inline_geometry_properties(root)
-
- # Structure / nesting
- if 'foreignobject' in local_names:
- result['errors'].append(
- "Detected forbidden <foreignObject> element (use <tspan> for manual line breaks)")
- has_generic_use = any(
- _local_name(elem).lower() == 'use' and elem.get('data-icon') is None
- for elem in elems
- )
- if has_generic_use:
- if _validate_local_use_references is None:
- result['warnings'].append(
- "Detected local <use> references, but the shared validator "
- "could not be imported; native export will still validate them."
- )
- else:
- for error in _validate_local_use_references(root):
- result['errors'].append(f"Invalid local <use> reference: {error}")
- # Text / fonts
- if 'textpath' in local_names:
- result['errors'].append("Detected forbidden <textPath> element (path text is incompatible with PPT)")
- if '@font-face' in content_lower:
- result['errors'].append("Detected forbidden @font-face (use system font stack)")
-
- # Animation / interaction
- if any(name.startswith('animate') for name in local_names):
- result['errors'].append("Detected forbidden SMIL animation element <animate*> (SVG animations are not exported)")
- if 'set' in local_names:
- result['errors'].append("Detected forbidden SMIL animation element <set> (SVG animations are not exported)")
- if 'script' in local_names:
- result['errors'].append("Detected forbidden <script> element (scripts and event handlers forbidden)")
- if re.search(r'\bon\w+\s*=', content): # onclick, onload etc.
- result['errors'].append("Detected forbidden event attributes (e.g., onclick, onload)")
-
- # Other discouraged elements
- if 'iframe' in local_names:
- result['errors'].append("Detected <iframe> element (should not appear in SVG)")
-
- def _check_paint_compatibility(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Reject unsupported paint and advise one generated-SVG spelling.
-
- The exporter parser owns compatibility. Any paint it can parse remains
- valid input; the checker only warns when that spelling differs from the
- generated-SVG default (uppercase ``#RRGGBB`` plus explicit alpha).
- """
- helpers = (
- _PAINT_PROPERTIES,
- _PERCENTAGE_OPACITY_PROPERTIES,
- _format_project_opacity,
- _is_project_paint_default_form,
- _iter_project_paints,
- _parse_inline_style,
- _parse_project_opacity,
- _parse_project_paint,
- _project_paint_errors,
- )
- if any(helper is None for helper in helpers):
- result['warnings'].append(
- "Unable to import svg_to_pptx paint parsers; skipped paint syntax check"
- )
- return
-
- result['errors'].extend(_project_paint_errors(root))
- recommendations: Counter[tuple[str, str, str]] = Counter()
- recommendation_examples: Dict[tuple[str, str, str], List[str]] = defaultdict(list)
-
- def remember_example(store: Dict, key: tuple, label: str) -> None:
- labels = store[key]
- if label not in labels and len(labels) < 3:
- labels.append(label)
-
- for elem, name, raw_value, source in _iter_project_paints(root):
- try:
- kind, normalized, color_alpha = _parse_project_paint(
- raw_value,
- name,
- )
- except ValueError:
- continue
- if _is_project_paint_default_form(raw_value, name):
- continue
-
- source_label = f'{_element_label(elem)} {source}'
- if kind == 'none':
- replacement = f'{name}="none"'
- elif kind == 'reference':
- replacement = f'{name}="url(#{normalized})"'
- elif name in {'fill', 'stroke'} and raw_value.strip().lower() == 'transparent':
- replacement = f'{name}="none"'
- else:
- replacement = f'{name}="#{normalized}"'
- alpha_name = _CANONICAL_PAINT_ALPHA_PROPERTY.get(name)
- if color_alpha < 1.0 and alpha_name is not None:
- style_values = _parse_inline_style(elem.get('style'))
- existing_alpha_raw = (
- style_values.get(alpha_name) or elem.get(alpha_name)
- )
- if existing_alpha_raw is None:
- existing_alpha = 1.0
- else:
- try:
- existing_alpha = _parse_project_opacity(
- existing_alpha_raw,
- allow_percentage=(
- alpha_name in _PERCENTAGE_OPACITY_PROPERTIES
- ),
- )
- except ValueError:
- existing_alpha = None
- effective_alpha = (
- color_alpha * existing_alpha
- if existing_alpha is not None else color_alpha
- )
- replacement += (
- f' {alpha_name}="'
- f'{_format_project_opacity(effective_alpha)}"'
- )
- elif color_alpha < 1.0:
- replacement += (
- '; put alpha on the matching pattern child fill/stroke '
- 'opacity'
- )
-
- key = (name, raw_value, replacement)
- recommendations[key] += 1
- remember_example(recommendation_examples, key, source_label)
-
- for (name, raw_value, replacement), count in sorted(recommendations.items()):
- examples = ', '.join(
- recommendation_examples[(name, raw_value, replacement)]
- )
- result['warnings'].append(
- f"Recommendation: {name}={raw_value!r} is converter-compatible "
- f"in {count} location(s) ({examples}); generated SVG should "
- f"prefer {replacement}. No change is required for export."
- )
-
- def _check_reference_spelling(self, root: ET.Element, result: Dict) -> None:
- """Recommend SVG 2 ``href`` while retaining legacy XLink input."""
- labels = []
- xlink_href = f'{{{XLINK_NS}}}href'
- for elem in root.iter():
- if _local_name(elem).lower() not in {'image', 'use'}:
- continue
- if elem.get(xlink_href) is not None:
- labels.append(_element_label(elem))
- if labels:
- examples = ', '.join(labels[:3])
- suffix = f' (+{len(labels) - 3} more)' if len(labels) > 3 else ''
- result['warnings'].append(
- f"Recommendation: legacy xlink:href is supported on {len(labels)} "
- f"reference(s) ({examples}{suffix}); generated SVG should prefer "
- "href. No change is required for export."
- )
-
- def _check_opacity_values(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Reject malformed opacity and advise generated-SVG values."""
- helpers = (
- _PERCENTAGE_OPACITY_PROPERTIES,
- _format_project_opacity,
- _is_project_opacity_default_form,
- _iter_project_opacities,
- _parse_inline_style,
- _parse_project_opacity,
- _project_opacity_errors,
- )
- if any(helper is None for helper in helpers):
- result['warnings'].append(
- "Unable to import svg_to_pptx opacity validators; native "
- "export will still validate opacity syntax."
- )
- return
-
- result['errors'].extend(_project_opacity_errors(root))
- recommendations: Counter[tuple[str, str, str]] = Counter()
- examples: Dict[tuple[str, str, str], List[str]] = defaultdict(list)
- fidelity_warnings: set[str] = set()
-
- for elem, property_name, raw, source in _iter_project_opacities(root):
- try:
- value = _parse_project_opacity(
- raw,
- allow_percentage=(
- property_name in _PERCENTAGE_OPACITY_PROPERTIES
- ),
- )
- except ValueError:
- continue
- if _is_project_opacity_default_form(raw):
- continue
- normalized = _format_project_opacity(value)
- key = (property_name, raw, normalized)
- recommendations[key] += 1
- label = f'{_element_label(elem)} {source}'
- if label not in examples[key] and len(examples[key]) < 3:
- examples[key].append(label)
-
- for elem in root.iter():
- if _local_name(elem).lower() != 'g':
- continue
- style_values = _parse_inline_style(elem.get('style'))
- raw_opacity = (
- style_values['opacity']
- if 'opacity' in style_values else elem.get('opacity')
- )
- if raw_opacity is None:
- continue
- try:
- opacity = _parse_project_opacity(raw_opacity)
- except ValueError:
- continue
- if opacity < 1.0:
- fidelity_warnings.add(
- f"Fidelity warning: {_element_label(elem)} uses group "
- f"opacity={raw_opacity!r}. The converter distributes this "
- "alpha to descendants and cannot preserve isolated group "
- "compositing; generated SVG should prefer descendant alpha. "
- "Existing input remains convertible and does not require "
- "modification."
- )
-
- for (property_name, raw, normalized), count in sorted(
- recommendations.items()
- ):
- shown_examples = ', '.join(
- examples[(property_name, raw, normalized)]
- )
- result['warnings'].append(
- f"Recommendation: {property_name}={raw!r} is "
- f"converter-compatible in {count} location(s) "
- f"({shown_examples}); generated SVG should prefer "
- f'{property_name}="{normalized}". No change is required '
- "for export."
- )
- result['warnings'].extend(sorted(fidelity_warnings))
-
- def _check_authoring_property_contract(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Validate inline CSS and attributes against the authoring surface."""
- errors: set[str] = set()
- validated_value_properties = set(_OPACITY_PROPERTIES or ())
- validated_value_properties.update(_PAINT_PROPERTIES or ())
- for elem in root.iter():
- label = _element_label(elem)
- for fragment in (elem.get('style') or '').split(';'):
- fragment = fragment.strip()
- if not fragment:
- continue
- if ':' not in fragment:
- if fragment.lower() not in validated_value_properties:
- errors.add(
- f"{label} has malformed inline style declaration "
- f"{fragment!r}"
- )
- continue
- name, value = fragment.split(':', 1)
- name = name.strip().lower()
- value = value.strip()
- if not name or not value:
- if name not in validated_value_properties:
- errors.add(
- f"{label} has malformed inline style declaration "
- f"{fragment!r}"
- )
- continue
- if name in _BAKE_REQUIRED_VISUAL_PROPERTIES:
- errors.add(
- f"{label} uses Bake-required visual property {name!r}; "
- "bake the effect or rebuild it with supported geometry"
- )
- elif (
- name not in _SUPPORTED_INLINE_STYLE_PROPERTIES
- and name not in _SHARED_FAIL_CLOSED_STYLE_PROPERTIES
- ):
- errors.add(
- f"{label} uses unsupported inline style property {name!r}; "
- "native PPTX export would ignore it"
- )
- if '!important' in value.lower():
- errors.add(
- f"{label} inline style property {name!r} cannot use !important"
- )
-
- for attr_name in elem.attrib:
- local_attr = attr_name.rsplit('}', 1)[-1]
- if local_attr in _BAKE_REQUIRED_VISUAL_PROPERTIES:
- errors.add(
- f"{label} uses Bake-required visual attribute {local_attr!r}; "
- "bake the effect or rebuild it with supported geometry"
- )
-
- result['errors'].extend(sorted(errors))
-
- def _check_text_property_contract(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Validate text property names and values with the export contract."""
- if _project_text_property_diagnostics is None:
- result['warnings'].append(
- "Unable to import the shared text-property validator; native "
- "export will still validate text properties."
- )
- return
-
- errors: set[str] = set()
- recommendations: Counter[tuple[str, str, str]] = Counter()
- examples: Dict[tuple[str, str, str], List[str]] = defaultdict(list)
- for diagnostic in _project_text_property_diagnostics(root):
- if diagnostic.severity == 'error':
- errors.add(diagnostic.message)
- continue
- if diagnostic.canonical is None:
- continue
- key = (
- diagnostic.name,
- diagnostic.raw,
- diagnostic.canonical,
- )
- recommendations[key] += 1
- if (
- diagnostic.label not in examples[key]
- and len(examples[key]) < 3
- ):
- examples[key].append(diagnostic.label)
-
- result['errors'].extend(sorted(errors))
- for (name, raw, canonical), count in sorted(recommendations.items()):
- shown_examples = ', '.join(examples[(name, raw, canonical)])
- result['warnings'].append(
- f"Recommendation: text property {name}={raw!r} is "
- f"converter-compatible in {count} location(s) "
- f"({shown_examples}); generated SVG should prefer "
- f'{name}="{canonical}". No change is required for export.'
- )
-
- def _check_definition_contract(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Require conditional definitions to be direct, uniquely identified defs."""
- if _project_definition_errors is None:
- result['warnings'].append(
- "Unable to import the shared definition validator; native "
- "export will still validate local definitions."
- )
- return
- result['errors'].extend(_project_definition_errors(root))
-
- def _check_paint_reference_contract(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Validate paint-server resolution and native target contexts."""
- if _project_paint_reference_errors is None:
- result['warnings'].append(
- "Unable to import the shared paint-reference validator; native "
- "export will still validate local paint references."
- )
- return
- result['errors'].extend(_project_paint_reference_errors(root))
-
- def _check_marker_contract(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Validate marker references against the native line-end contract."""
- if _project_marker_errors is None:
- result['warnings'].append(
- 'Unable to import the shared marker validator; native export '
- 'will still validate line-end markers.'
- )
- return
- result['errors'].extend(_project_marker_errors(root))
-
- def _check_clip_path_contract(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Validate image clip paths against the native picture geometry mapping."""
- if _project_clip_path_errors is None:
- result['errors'].append(
- 'Unable to import the clip-path validator; cannot verify '
- 'native picture geometry references'
- )
- return
- result['errors'].extend(_project_clip_path_errors(root))
-
- def _check_mask_contract(self, root: ET.Element, result: Dict) -> None:
- """Reject SVG masks through the native exporter's shared validator."""
- if _project_mask_errors is None:
- result['errors'].append(
- 'Unable to import the shared mask validator; cannot verify '
- 'that native PPTX export will preserve all visible effects'
- )
- return
- result['errors'].extend(_project_mask_errors(root))
-
- def _check_filter_effects(self, root: ET.Element, result: Dict) -> None:
- """Validate filters against the native shadow/glow approximation."""
- if _project_filter_errors is None:
- result['warnings'].append(
- "Unable to import the shared filter validator; native export "
- "will still validate shadow/glow filters."
- )
- return
- result['errors'].extend(_project_filter_errors(root))
-
- def _check_imported_effect_status(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Reject source PPTX effects that have no faithful SVG mapping."""
- if _project_effect_status_errors is None:
- if any(
- elem.get(_EFFECT_STATUS_ATTR) is not None
- or elem.get(_EFFECT_REASON_ATTR) is not None
- for elem in root.iter()
- ):
- result['errors'].append(
- 'Unable to import the PPTX effect-status validator; '
- 'cannot verify imported effect fidelity'
- )
- return
- result['errors'].extend(_project_effect_status_errors(root))
-
- def _check_gradient_interfaces(self, root: ET.Element, result: Dict) -> None:
- """Validate the normalized native gradient authoring interface."""
- if (
- _project_gradient_errors is None
- or _project_gradient_geometry_errors is None
- ):
- result['warnings'].append(
- "Unable to import the shared gradient validator; native export "
- "will still validate gradient definitions."
- )
- return
- gradient_errors = set(_project_gradient_errors(root))
- gradient_errors.update(_project_gradient_geometry_errors(root))
- if (
- _expand_local_use_references is not None
- and _UseExpansionError is not None
- ):
- expanded_root = copy.deepcopy(root)
- try:
- _expand_local_use_references(expanded_root)
- except _UseExpansionError:
- # The local-reference check owns the actionable diagnostic.
- pass
- else:
- gradient_errors.update(
- _project_gradient_geometry_errors(expanded_root)
- )
- result['errors'].extend(sorted(gradient_errors))
-
- def _check_geometry_length_values(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Reject invalid project geometry and advise the unitless spelling."""
- if (
- _format_project_geometry_length is None
- or _is_canonical_project_geometry_length is None
- or _iter_project_geometry_lengths is None
- or _parse_project_geometry_length is None
- ):
- result['warnings'].append(
- "Unable to import svg_to_pptx geometry length validators; "
- "native export will still validate project geometry."
- )
- return
-
- errors: set[str] = set()
- recommendations: Counter[tuple[str, str, str]] = Counter()
- examples: Dict[tuple[str, str, str], List[str]] = defaultdict(list)
-
- for elem, attribute, raw, source in _iter_project_geometry_lengths(root):
- label = f'{_element_label(elem)} {source}'
- try:
- value = _parse_project_geometry_length(raw, attribute)
- except ValueError as exc:
- errors.add(f"{label} {attribute}={raw!r}: {exc}")
- continue
- if _is_canonical_project_geometry_length(raw):
- continue
- normalized = _format_project_geometry_length(value)
- key = (attribute, raw, normalized)
- recommendations[key] += 1
- if label not in examples[key] and len(examples[key]) < 3:
- examples[key].append(label)
-
- result['errors'].extend(sorted(errors))
- for (attribute, raw, normalized), count in sorted(recommendations.items()):
- shown_examples = ', '.join(examples[(attribute, raw, normalized)])
- result['warnings'].append(
- f"Recommendation: project geometry {attribute}={raw!r} is "
- f"converter-compatible in {count} location(s) ({shown_examples}); "
- f"generated SVG should prefer the unitless px spelling "
- f'{attribute}="{normalized}". No change is required for export.'
- )
-
- def _check_stroke_style_values(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Reject invalid line styles and advise project-canonical spellings."""
- helpers = (
- _format_project_geometry_length,
- _is_canonical_project_geometry_length,
- _iter_project_stroke_styles,
- _noncanonical_stroke_dash_numbers,
- _parse_project_geometry_length,
- _parse_project_stroke_dasharray,
- _parse_project_stroke_enum,
- _project_stroke_style_errors,
- )
- if any(helper is None for helper in helpers):
- result['warnings'].append(
- "Unable to import svg_to_pptx line-style validators; native "
- "export will still validate line-presentation syntax."
- )
- return
-
- result['errors'].extend(_project_stroke_style_errors(root))
- recommendations: Counter[tuple[str, str, str, str]] = Counter()
- examples: Dict[tuple[str, str, str, str], List[str]] = defaultdict(list)
-
- for elem, attribute, raw, source in _iter_project_stroke_styles(root):
- label = f'{_element_label(elem)} {source}'
- normalized = None
- reason = ''
-
- if attribute == 'stroke-dasharray':
- try:
- parsed = _parse_project_stroke_dasharray(
- raw,
- allow_zero_gap=True,
- )
- noncanonical = _noncanonical_stroke_dash_numbers(raw)
- except ValueError:
- continue
- if parsed is None:
- if raw != 'none':
- normalized = 'none'
- reason = 'remove surrounding whitespace'
- else:
- preset, values = parsed
- longer_custom = preset is None and len(values) > 2
- if noncanonical or longer_custom or raw != raw.strip():
- kept_values = values[:2] if longer_custom else values
- normalized = ' '.join(
- _format_project_geometry_length(value)
- for value in kept_values
- )
- reasons = []
- if noncanonical:
- reasons.append('use ordinary decimal numbers')
- if longer_custom:
- reasons.append(
- 'make the first-pair export normalization explicit'
- )
- if raw != raw.strip():
- reasons.append('remove surrounding whitespace')
- reason = '; '.join(reasons)
- elif attribute == 'stroke-dashoffset':
- try:
- value = _parse_project_geometry_length(raw, attribute)
- except ValueError:
- continue
- if not _is_canonical_project_geometry_length(raw):
- normalized = _format_project_geometry_length(value)
- reason = 'use the unitless px spelling'
- else:
- try:
- value = _parse_project_stroke_enum(attribute, raw)
- except ValueError:
- continue
- if raw != value:
- normalized = value
- reason = 'remove surrounding whitespace'
-
- if normalized is None:
- continue
- key = (attribute, raw, normalized, reason)
- recommendations[key] += 1
- if label not in examples[key] and len(examples[key]) < 3:
- examples[key].append(label)
-
- for (attribute, raw, normalized, reason), count in sorted(
- recommendations.items()
- ):
- shown_examples = ', '.join(
- examples[(attribute, raw, normalized, reason)]
- )
- result['warnings'].append(
- f"Recommendation: line style {attribute}={raw!r} is "
- f"converter-compatible in {count} location(s) "
- f"({shown_examples}); generated SVG should prefer "
- f'{attribute}="{normalized}" to {reason}. No change is '
- "required for export."
- )
-
- def _check_image_aspect_ratio_values(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Reject ambiguous image fit/crop values and advise canonical forms."""
- helpers = (
- _format_project_image_aspect_ratio,
- _iter_project_image_aspect_ratios,
- _parse_project_image_aspect_ratio,
- _project_image_aspect_ratio_errors,
- )
- if any(helper is None for helper in helpers):
- result['warnings'].append(
- "Unable to import svg_to_pptx image aspect-ratio validators; "
- "native export will still validate image fit/crop syntax."
- )
- return
-
- result['errors'].extend(_project_image_aspect_ratio_errors(root))
- recommendations: Counter[tuple[str, str]] = Counter()
- examples: Dict[tuple[str, str], List[str]] = defaultdict(list)
-
- for elem, raw in _iter_project_image_aspect_ratios(root):
- try:
- align, mode = _parse_project_image_aspect_ratio(raw)
- except ValueError:
- continue
- normalized = _format_project_image_aspect_ratio(align, mode)
- if raw == normalized:
- continue
- key = (raw, normalized)
- recommendations[key] += 1
- label = _element_label(elem)
- if label not in examples[key] and len(examples[key]) < 3:
- examples[key].append(label)
-
- for (raw, normalized), count in sorted(recommendations.items()):
- shown_examples = ', '.join(examples[(raw, normalized)])
- result['warnings'].append(
- f"Recommendation: image preserveAspectRatio={raw!r} is "
- f"converter-compatible in {count} location(s) "
- f"({shown_examples}); generated SVG should prefer "
- f'preserveAspectRatio="{normalized}". No change is required '
- "for export."
- )
-
- def _check_nested_svg_crop_contract(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Reserve nested SVG for the imported picture-crop transport."""
- if _project_nested_svg_crop_errors is None:
- result['errors'].append(
- 'Unable to import the nested SVG crop validator; cannot '
- 'verify imported picture-crop wrappers'
- )
- return
- result['errors'].extend(_project_nested_svg_crop_errors(root))
-
- def _check_image_contract(
- self,
- root: ET.Element,
- svg_path: Path,
- result: Dict,
- ) -> None:
- """Validate picture frames, references, and bytes before export."""
- if _project_image_errors is None:
- result['errors'].append(
- 'Unable to import the image validator; cannot verify picture '
- 'frames or media'
- )
- return
- _working_root, _parent_by_id, images = self._visible_image_elements(root)
- for image in images:
- result['errors'].extend(
- _project_image_errors(
- image,
- svg_path.parent,
- allow_template_placeholders=self.template_mode,
- )
- )
-
- def _check_freeform_geometry_values(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Reject malformed path/points syntax and advise decimal spelling."""
- helpers = (
- _format_project_geometry_length,
- _iter_project_freeform_geometry,
- _noncanonical_path_numbers,
- _noncanonical_points_numbers,
- )
- if any(helper is None for helper in helpers):
- result['warnings'].append(
- "Unable to import svg_to_pptx freeform geometry validators; "
- "native export will still validate path and points syntax."
- )
- return
-
- errors: set[str] = set()
- recommendations: Counter[tuple[str, str, str]] = Counter()
- examples: Dict[tuple[str, str, str], List[str]] = defaultdict(list)
-
- for elem, attribute, raw, min_points in _iter_project_freeform_geometry(root):
- label = _element_label(elem)
- try:
- if raw is None:
- tag = _local_name(elem)
- raise ValueError(f'<{tag}> requires {attribute}')
- if attribute == 'd':
- compatible_numbers = _noncanonical_path_numbers(raw)
- else:
- required_points = min_points or 2
- compatible_numbers = _noncanonical_points_numbers(
- raw,
- min_points=required_points,
- )
- except ValueError as exc:
- errors.add(f'{label} {attribute}: {exc}')
- continue
-
- for number in compatible_numbers:
- normalized = _format_project_geometry_length(float(number))
- key = (attribute, number, normalized)
- recommendations[key] += 1
- if label not in examples[key] and len(examples[key]) < 3:
- examples[key].append(label)
-
- result['errors'].extend(sorted(errors))
- for (attribute, raw, normalized), count in sorted(recommendations.items()):
- shown_examples = ', '.join(examples[(attribute, raw, normalized)])
- result['warnings'].append(
- f"Recommendation: freeform geometry {attribute} numeric token "
- f"{raw!r} is converter-compatible in {count} occurrence(s) "
- f"({shown_examples}); generated SVG should prefer the ordinary "
- f"decimal spelling {normalized!r}. No change is required for export."
- )
-
- def _check_transform_values(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Reject invalid transforms and advise ordinary decimal spelling."""
- helpers = (
- _format_project_geometry_length,
- _iter_project_transforms,
- _noncanonical_transform_numbers,
- _project_transform_errors,
- )
- if any(helper is None for helper in helpers):
- result['warnings'].append(
- "Unable to import svg_to_pptx transform validators; "
- "native export will still validate transform syntax."
- )
- return
-
- transform_errors = set(_project_transform_errors(root))
- if (
- not transform_errors
- and _expand_local_use_references is not None
- and _UseExpansionError is not None
- ):
- expanded_root = copy.deepcopy(root)
- try:
- _expand_local_use_references(expanded_root)
- except _UseExpansionError:
- # The local-reference check owns the actionable diagnostic.
- pass
- else:
- transform_errors.update(_project_transform_errors(expanded_root))
- result['errors'].extend(
- f'Invalid SVG transform: {error}'
- for error in sorted(transform_errors)
- )
-
- recommendations: Counter[tuple[str, str]] = Counter()
- examples: Dict[tuple[str, str], List[str]] = defaultdict(list)
- for elem, raw in _iter_project_transforms(root):
- try:
- compatible_numbers = _noncanonical_transform_numbers(raw)
- except ValueError:
- continue
- for number in compatible_numbers:
- normalized = _format_project_geometry_length(float(number))
- key = (number, normalized)
- recommendations[key] += 1
- label = _element_label(elem)
- if label not in examples[key] and len(examples[key]) < 3:
- examples[key].append(label)
-
- for (raw, normalized), count in sorted(recommendations.items()):
- shown_examples = ', '.join(examples[(raw, normalized)])
- result['warnings'].append(
- f"Recommendation: transform numeric token {raw!r} is "
- f"converter-compatible in {count} occurrence(s) "
- f"({shown_examples}); generated SVG should prefer the ordinary "
- f"decimal spelling {normalized!r}. No change is required for export."
- )
-
- def _check_font_size_values(self, content: str, result: Dict):
- """Keep supported font-size units compatible and recommend unitless px."""
- canonical_re = re.compile(r'^(?:\d+(?:\.\d+)?|\.\d+)$')
- values = set()
-
- for match in re.finditer(r'\bfont-size\s*=\s*(["\'])(.*?)\1', content, re.IGNORECASE):
- values.add(match.group(2).strip())
-
- for match in re.finditer(r'\bfont-size\s*:\s*([^;"\']+)', content, re.IGNORECASE):
- values.add(match.group(1).strip())
-
- if _parse_export_length is None:
- result['warnings'].append(
- "Unable to import svg_to_pptx length parser; skipped font-size syntax check"
- )
- return
-
- unsupported = set()
- drawingml_out_of_range = set()
- compatible_noncanonical = set()
- for raw in values:
- try:
- parsed_px = _parse_export_length(raw, math.nan, font_size=16)
- except (TypeError, ValueError):
- unsupported.add(raw)
- continue
- if not math.isfinite(parsed_px) or parsed_px < 0:
- unsupported.add(raw)
- continue
- if _font_px_to_hpt is not None:
- try:
- _font_px_to_hpt(parsed_px)
- except ValueError:
- drawingml_out_of_range.add(raw)
- continue
- if not canonical_re.fullmatch(raw):
- compatible_noncanonical.add(raw)
-
- if unsupported:
- shown_values = sorted(unsupported)
- shown = ', '.join(shown_values[:5])
- more = len(shown_values) - 5
- suffix = f" (+{more} more)" if more > 0 else ""
- result['errors'].append(
- f"Unsupported font-size value(s): {shown}{suffix}. Use a finite "
- "non-negative SVG length supported by svg_to_pptx."
- )
-
- if drawingml_out_of_range:
- shown_values = sorted(drawingml_out_of_range)
- shown = ', '.join(shown_values[:5])
- more = len(shown_values) - 5
- suffix = f" (+{more} more)" if more > 0 else ""
- result['errors'].append(
- f"font-size value(s) {shown}{suffix} are outside the DrawingML "
- f"range sz={_DRAWINGML_TEXT_FONT_SIZE_MIN}.."
- f"{_DRAWINGML_TEXT_FONT_SIZE_MAX} (1..4000pt); PowerPoint would "
- "repair the exported file. Do not use tiny transparent text as "
- "a placeholder carrier: leave a text carrier blank or use the "
- "composite object proxy contract."
- )
-
- if compatible_noncanonical:
- shown_values = sorted(compatible_noncanonical)
- shown = ', '.join(shown_values[:5])
- more = len(shown_values) - 5
- suffix = f" (+{more} more)" if more > 0 else ""
- result['warnings'].append(
- f"Recommendation: font-size value(s) {shown}{suffix} are "
- "converter-compatible; generated SVG should prefer unitless px "
- "values such as font-size=\"28\". No change is required for export."
- )
-
- def _check_fonts(self, content: str, result: Dict):
- """Check font usage.
-
- PPTX stores concrete typefaces per run with no CSS fallback. The
- converter resolves each SVG font stack to exported latin / EA typefaces;
- validate those exported values rather than the visual-preview tail.
- """
- font_matches = self._font_family_values(content)
-
- if not font_matches:
- return
-
- result['info']['fonts'] = sorted(set(font_matches))
- if _unsafe_exported_font_faces is None:
- result['warnings'].append(
- "Unable to import svg_to_pptx font resolver; skipped exported-font safety check"
- )
- return
-
- for font_family in font_matches:
- unsafe = [
- f"{role}={family}"
- for role, family in _unsafe_exported_font_faces(font_family).items()
- ]
- if unsafe:
- result['warnings'].append(
- "Font stack exports non-PPT-safe typeface(s) to PPTX "
- f"({', '.join(unsafe)}): {font_family}"
- )
- break
-
- @staticmethod
- def _font_family_values(content: str) -> List[str]:
- """Extract SVG font-family values from attributes and inline styles."""
- return SVGQualityChecker._svg_property_values(content, 'font-family')
-
- @staticmethod
- def _svg_property_values(content: str, property_name: str) -> List[str]:
- """Extract a SVG property from direct attributes and inline styles."""
- values: List[str] = []
- attr_re = re.compile(
- rf'\b{re.escape(property_name)}\s*=\s*(["\'])(.*?)\1',
- re.IGNORECASE | re.DOTALL,
- )
- for match in attr_re.finditer(content):
- values.append(html.unescape(match.group(2)).strip())
-
- for match in re.finditer(r'\bstyle\s*=\s*(["\'])(.*?)\1', content, re.IGNORECASE | re.DOTALL):
- style_value = html.unescape(match.group(2))
- for part in style_value.split(';'):
- if ':' not in part:
- continue
- name, value = part.split(':', 1)
- if name.strip().lower() == property_name.lower():
- values.append(value.strip())
- return [value for value in values if value]
-
- def _check_text_elements(self, content: str, root: ET.Element, result: Dict):
- """Check text elements and wrapping methods"""
- # Count text and tspan elements
- text_count = content.count('<text')
- tspan_count = content.count('<tspan')
-
- result['info']['text_elements'] = text_count
- result['info']['tspan_elements'] = tspan_count
-
- self._check_module_bounds_contract(root, result)
- self._check_text_output_geometry(root, result)
- self._check_root_module_text_bounds(root, result)
- self._check_fragmented_paragraph_text(root, result)
- self._check_unmergeable_leading_text(root, result)
- self._check_nested_positional_tspans(root, result)
-
- def _check_nested_positional_tspans(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Reject nested baseline jumps that DrawingML runs cannot represent."""
- if _nested_positional_tspan_errors is None:
- return
- result['errors'].extend(_nested_positional_tspan_errors(root))
-
- @classmethod
- def _single_line_text_runs(
- cls,
- text_el: ET.Element,
- ) -> List[Tuple[ET.Element, str]] | None:
- """Return normalized inline runs, or ``None`` for positioned text."""
- if (
- _normalize_project_text_segments is None
- or _resolve_project_xml_space is None
- ):
- return None
- raw_runs: List[Tuple[ET.Element, str, str]] = []
-
- def append_run(owner: ET.Element, raw: str, xml_space: str) -> None:
- if raw:
- raw_runs.append((owner, xml_space, raw))
-
- def collect(container: ET.Element, inherited_xml_space: str) -> bool:
- try:
- xml_space = _resolve_project_xml_space(
- container,
- inherited_xml_space,
- )
- except ValueError:
- return False
- if container.text:
- append_run(container, container.text, xml_space)
- for child in list(container):
- if not cls._is_tspan(child):
- return False
- if any(child.get(name) is not None for name in ('x', 'y', 'dx', 'dy')):
- return False
- if any(
- name.startswith('data-paragraph-')
- for name in child.attrib
- ):
- return False
- if not collect(child, xml_space):
- return False
- if child.tail:
- append_run(container, child.tail, xml_space)
- return True
-
- if not collect(text_el, 'default'):
- return None
- normalized = _normalize_project_text_segments([
- (xml_space, raw)
- for _owner, xml_space, raw in raw_runs
- ])
- return [
- (raw_runs[index][0], text)
- for index, text in normalized
- ]
-
- @staticmethod
- def _unchanged_txbody_group_ids(
- root: ET.Element,
- ) -> set[int]:
- """Return imported shape groups whose original text body will survive."""
- if _preserved_native_text_body is None:
- return set()
- unchanged: set[int] = set()
- for group in root.iter(f'{{{SVG_NS}}}g'):
- try:
- if _preserved_native_text_body(
- group,
- trust_runtime_snapshot=False,
- ) is not None:
- unchanged.add(id(group))
- except _SvgNativeConversionError:
- # The dedicated txBody contract check owns the diagnostic.
- continue
- return unchanged
-
- @staticmethod
- def _check_preserved_txbody_contract(
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Validate imported txBody payloads independently of text geometry."""
- if _preserved_native_text_body is None:
- return
- errors: set[str] = set()
- for group in root.iter(f'{{{SVG_NS}}}g'):
- try:
- _preserved_native_text_body(
- group,
- trust_runtime_snapshot=False,
- )
- except _SvgNativeConversionError as exc:
- errors.add(
- f'{_element_label(group)} cannot preserve source '
- f'txBody: {exc}'
- )
- result['errors'].extend(sorted(errors))
-
- @staticmethod
- def _has_ancestor_id(
- elem: ET.Element,
- parent_by_id: Dict[int, ET.Element],
- ancestor_ids: set[int],
- ) -> bool:
- current = parent_by_id.get(id(elem))
- while current is not None:
- if id(current) in ancestor_ids:
- return True
- current = parent_by_id.get(id(current))
- return False
-
- @classmethod
- def _resolved_single_line_text_runs(
- cls,
- text_el: ET.Element,
- parent_by_id: Dict[int, ET.Element],
- font_sizes: Dict[int, float],
- letter_spacings: Dict[int, float],
- ) -> List[Dict] | None:
- """Resolve the same run metrics used by generated text-frame sizing."""
- source_runs = cls._single_line_text_runs(text_el)
- if source_runs is None:
- return None
- resolved: List[Dict] = []
- for owner, text in source_runs:
- raw_weight = (
- _effective_presentation_value(
- owner,
- 'font-weight',
- parent_by_id,
- )
- or 'normal'
- ).strip().lower()
- weight = _parse_project_font_weight(raw_weight).canonical
- family = (
- _effective_presentation_value(
- owner,
- 'font-family',
- parent_by_id,
- )
- or ''
- )
- opacity_chain: List[str] = []
- current: ET.Element | None = owner
- while current is not None:
- style_values = (
- _parse_inline_style(current.get('style'))
- if _parse_inline_style is not None else {}
- )
- raw_opacity = style_values.get('opacity')
- if raw_opacity is None:
- raw_opacity = current.get('opacity')
- if raw_opacity is not None:
- opacity_chain.append(raw_opacity.strip())
- current = parent_by_id.get(id(current))
- resolved.append({
- 'owner': owner,
- 'text': text,
- 'font_size': font_sizes[id(owner)],
- 'font_weight': weight,
- 'font_family': family,
- 'letter_spacing': letter_spacings[id(owner)],
- 'font_style': _effective_presentation_value(
- owner,
- 'font-style',
- parent_by_id,
- ) or 'normal',
- 'text_decoration': _effective_presentation_value(
- owner,
- 'text-decoration',
- parent_by_id,
- ) or 'none',
- 'fill_raw': _effective_presentation_value(
- owner,
- 'fill',
- parent_by_id,
- ) or '#000000',
- 'fill_opacity': _effective_presentation_value(
- owner,
- 'fill-opacity',
- parent_by_id,
- ) or '1',
- 'stroke_raw': _effective_presentation_value(
- owner,
- 'stroke',
- parent_by_id,
- ) or 'none',
- 'stroke_width': _effective_presentation_value(
- owner,
- 'stroke-width',
- parent_by_id,
- ) or '1',
- 'stroke_opacity': _effective_presentation_value(
- owner,
- 'stroke-opacity',
- parent_by_id,
- ) or '1',
- 'opacity_chain': tuple(reversed(opacity_chain)),
- })
- return cls._coalesce_checker_text_runs(resolved)
-
- @staticmethod
- def _coalesce_checker_text_runs(runs: List[Dict]) -> List[Dict]:
- """Join only runs whose resolved source styles are provably equal."""
- if _detect_text_lang is None:
- return runs
- style_keys = (
- 'font_size',
- 'font_weight',
- 'font_family',
- 'letter_spacing',
- 'font_style',
- 'text_decoration',
- 'fill_raw',
- 'fill_opacity',
- 'stroke_raw',
- 'stroke_width',
- 'stroke_opacity',
- 'opacity_chain',
- )
-
- def signature(run: Dict) -> Tuple:
- return (
- _detect_text_lang(str(run.get('text', ''))),
- *(run.get(key) for key in style_keys),
- )
-
- merged: List[Dict] = []
- previous_signature: Tuple | None = None
- for run in runs:
- current_signature = signature(run)
- if merged and current_signature == previous_signature:
- candidate = {
- **merged[-1],
- 'text': (
- str(merged[-1].get('text', ''))
- + str(run.get('text', ''))
- ),
- }
- candidate_signature = signature(candidate)
- if candidate_signature == previous_signature:
- merged[-1] = candidate
- previous_signature = candidate_signature
- continue
- merged.append(run)
- previous_signature = current_signature
- return merged
-
- def _check_text_output_geometry(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Reject measurable run advances or frames with non-positive geometry."""
- helpers = (
- _drawingml_text_frame_width_emu,
- _estimate_single_line_text_frame_width,
- _parse_project_font_weight,
- _resolve_project_font_sizes,
- _resolve_project_letter_spacings,
- _validate_single_line_text_run_advances,
- )
- if any(helper is None for helper in helpers):
- return
- try:
- font_sizes = _resolve_project_font_sizes(root)
- letter_spacings = _resolve_project_letter_spacings(root, font_sizes)
- except ValueError:
- return
-
- parent_by_id = {
- id(child): parent
- for parent in root.iter()
- for child in list(parent)
- }
- unchanged_groups = self._unchanged_txbody_group_ids(root)
- errors: List[str] = []
- for text_el in root.iter(f'{{{SVG_NS}}}text'):
- chain: List[ET.Element] = []
- current: ET.Element | None = text_el
- while current is not None:
- chain.append(current)
- current = parent_by_id.get(id(current))
- if any(
- _local_name(current) in _NON_VISUAL_SVG_TAGS
- for current in chain
- ):
- continue
- if self._has_ancestor_id(text_el, parent_by_id, unchanged_groups):
- continue
- try:
- runs = self._resolved_single_line_text_runs(
- text_el,
- parent_by_id,
- font_sizes,
- letter_spacings,
- )
- if not runs:
- continue
- if not ''.join(str(run['text']) for run in runs).strip():
- continue
- text_width = _estimate_single_line_text_frame_width(runs)
- ext_cx = _drawingml_text_frame_width_emu(
- text_width,
- font_sizes[id(text_el)],
- )
- except (KeyError, TypeError, ValueError):
- continue
- if ext_cx < 1:
- errors.append(
- f'{_element_label(text_el)} negative letter-spacing '
- 'produces a non-positive DrawingML text-frame extent '
- f'(cx={ext_cx})'
- )
- continue
- try:
- _validate_single_line_text_run_advances(runs)
- except ValueError as exc:
- errors.append(f'{_element_label(text_el)} {exc}')
- result['errors'].extend(errors)
-
- @classmethod
- def _positioned_text_lines(
- cls,
- text_el: ET.Element,
- parent_by_id: Dict[int, ET.Element],
- font_sizes: Dict[int, float],
- letter_spacings: Dict[int, float],
- ) -> List[Tuple[ET.Element, float, float, List[Dict], float]] | None:
- """Resolve direct positioned tspans into estimable visual lines."""
- if _parse_project_geometry_length is None:
- return None
- children = list(text_el)
- if not children or (text_el.text or '').strip():
- return None
- if any(
- not cls._is_tspan(child)
- or not cls._is_line_tspan(child)
- or child.get('x') is None
- or (child.tail or '').strip()
- for child in children
- ):
- return None
-
- try:
- current_y = _parse_project_geometry_length(
- text_el.get('y') or '0',
- 'y',
- )
- except ValueError:
- return None
-
- lines: List[Tuple[ET.Element, float, float, List[Dict], float]] = []
- for child in children:
- try:
- line_x = _parse_project_geometry_length(child.get('x'), 'x')
- line_y = (
- _parse_project_geometry_length(child.get('y'), 'y')
- if child.get('y') is not None
- else current_y
- )
- if child.get('dx') is not None:
- line_x += _parse_project_geometry_length(
- child.get('dx'),
- 'dx',
- )
- if child.get('dy') is not None:
- line_y += _parse_project_geometry_length(
- child.get('dy'),
- 'dy',
- )
- runs = cls._resolved_single_line_text_runs(
- child,
- parent_by_id,
- font_sizes,
- letter_spacings,
- )
- except (KeyError, TypeError, ValueError):
- return None
- current_y = line_y
- if not runs:
- continue
- try:
- font_size = max(float(run['font_size']) for run in runs)
- except (KeyError, TypeError, ValueError):
- return None
- lines.append((child, line_x, line_y, runs, font_size))
- return lines or None
-
- @classmethod
- def _estimated_text_line_bounds(
- cls,
- line_el: ET.Element,
- x: float,
- y: float,
- runs: List[Dict],
- font_size: float,
- parent_by_id: Dict[int, ET.Element],
- ) -> Tuple[float, float, float, float] | None:
- """Estimate one line's transformed visible bounds in SVG coordinates."""
- if any(helper is None for helper in (
- _estimate_single_line_text_frame_width,
- _IDENTITY_MATRIX,
- _matrix_multiply,
- _parse_project_text_anchor,
- _parse_transform_matrix,
- _transform_point,
- )):
- return None
- try:
- width = float(_estimate_single_line_text_frame_width(runs))
- raw_anchor = (
- _effective_presentation_value(
- line_el,
- 'text-anchor',
- parent_by_id,
- )
- or 'start'
- ).strip().lower()
- anchor = _parse_project_text_anchor(raw_anchor).value
- except (TypeError, ValueError):
- return None
- if not all(math.isfinite(value) for value in (x, y, width, font_size)):
- return None
- if width <= 0 or font_size <= 0:
- return None
-
- if anchor == 'middle':
- left = x - width / 2
- right = x + width / 2
- elif anchor == 'end':
- left = x - width
- right = x
- elif anchor == 'start':
- left = x
- right = x + width
- else:
- return None
- top = y - font_size * 0.85
- bottom = y + font_size * 0.35
-
- return cls._transformed_rect_bounds(
- line_el,
- (left, top, right - left, bottom - top),
- parent_by_id,
- )
-
- @classmethod
- def _estimated_text_bounds(
- cls,
- text_el: ET.Element,
- parent_by_id: Dict[int, ET.Element],
- font_sizes: Dict[int, float],
- letter_spacings: Dict[int, float],
- ) -> Tuple[float, float, float, float] | None:
- """Estimate one single- or multi-line text carrier's visual bounds."""
- lines: List[Tuple[ET.Element, float, float, List[Dict], float]] | None
- try:
- runs = cls._resolved_single_line_text_runs(
- text_el,
- parent_by_id,
- font_sizes,
- letter_spacings,
- )
- except (KeyError, TypeError, ValueError):
- return None
- if runs:
- try:
- lines = [(
- text_el,
- _parse_project_geometry_length(text_el.get('x') or '0', 'x'),
- _parse_project_geometry_length(text_el.get('y') or '0', 'y'),
- runs,
- max(float(run['font_size']) for run in runs),
- )]
- except (KeyError, TypeError, ValueError):
- return None
- else:
- lines = cls._positioned_text_lines(
- text_el,
- parent_by_id,
- font_sizes,
- letter_spacings,
- )
- if not lines:
- return None
- bounds = [
- cls._estimated_text_line_bounds(
- line_el,
- x,
- y,
- line_runs,
- font_size,
- parent_by_id,
- )
- for line_el, x, y, line_runs, font_size in lines
- ]
- resolved = [item for item in bounds if item is not None]
- if not resolved:
- return None
- return (
- min(item[0] for item in resolved),
- min(item[1] for item in resolved),
- max(item[2] for item in resolved),
- max(item[3] for item in resolved),
- )
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+ sys.path.insert(0, str(_SCRIPTS_DIR))
- @staticmethod
- def _accumulated_transform_matrix(
- element: ET.Element,
- parent_by_id: Dict[int, ET.Element],
- ):
- """Return the element-to-root transform matrix when available."""
- if any(helper is None for helper in (
- _IDENTITY_MATRIX,
- _matrix_multiply,
- _parse_transform_matrix,
- )):
- return None
- chain: List[ET.Element] = []
- current: ET.Element | None = element
- while current is not None:
- chain.append(current)
- current = parent_by_id.get(id(current))
- matrix = _IDENTITY_MATRIX
- try:
- for current in reversed(chain):
- raw_transform = current.get('transform')
- if raw_transform:
- matrix = _matrix_multiply(
- matrix,
- _parse_transform_matrix(raw_transform),
- )
- except (TypeError, ValueError):
- return None
- return matrix
-
- @classmethod
- def _transformed_rect_bounds(
- cls,
- element: ET.Element,
- bounds: Tuple[float, float, float, float],
- parent_by_id: Dict[int, ET.Element],
- ) -> Tuple[float, float, float, float] | None:
- """Transform one local rectangle into root SVG coordinates."""
- if _transform_point is None:
- return None
- matrix = cls._accumulated_transform_matrix(element, parent_by_id)
- if matrix is None:
- return None
- x, y, width, height = bounds
- try:
- corners = [
- _transform_point(matrix, corner_x, corner_y)
- for corner_x, corner_y in (
- (x, y),
- (x + width, y),
- (x + width, y + height),
- (x, y + height),
- )
- ]
- except (TypeError, ValueError):
- return None
- xs = [point[0] for point in corners]
- ys = [point[1] for point in corners]
- return min(xs), min(ys), max(xs), max(ys)
-
- @classmethod
- def _transformed_rect_edge_lengths(
- cls,
- element: ET.Element,
- bounds: Tuple[float, float, float, float],
- parent_by_id: Dict[int, ET.Element],
- ) -> Tuple[float, float] | None:
- """Return frame-axis lengths after accumulated SVG transforms."""
- if _transform_point is None:
- return None
- matrix = cls._accumulated_transform_matrix(element, parent_by_id)
- if matrix is None:
- return None
- x, y, width, height = bounds
- try:
- origin = _transform_point(matrix, x, y)
- width_end = _transform_point(matrix, x + width, y)
- height_end = _transform_point(matrix, x, y + height)
- except (TypeError, ValueError):
- return None
- rendered_w = math.hypot(
- width_end[0] - origin[0],
- width_end[1] - origin[1],
- )
- rendered_h = math.hypot(
- height_end[0] - origin[0],
- height_end[1] - origin[1],
- )
- if rendered_w <= 0 or rendered_h <= 0:
- return None
- return rendered_w, rendered_h
-
- @staticmethod
- def _resolved_root_module_bounds(
- group: ET.Element,
- ) -> Tuple[str, Tuple[float, float, float, float]] | None:
- """Return one root module's explicit boundary in root coordinates."""
- raw = group.get(_BOUNDS_ATTR)
- if raw is None:
- return None
- try:
- x, y, width, height = _parse_positive_bounds(raw)
- except ValueError:
- return None
- return _BOUNDS_ATTR, (x, y, x + width, y + height)
-
- @staticmethod
- def _bounds_overflow_metrics(
- inner: Tuple[float, float, float, float],
- outer: Tuple[float, float, float, float],
- *,
- tolerance: float = _BOUNDS_OVERFLOW_TOLERANCE,
- ) -> Tuple[str, float, float] | None:
- """Return overflow axes and ratios relative to the outer dimensions."""
- left, top, right, bottom = inner
- outer_left, outer_top, outer_right, outer_bottom = outer
- left_overflow = max(outer_left - left, 0.0)
- right_overflow = max(right - outer_right, 0.0)
- top_overflow = max(outer_top - top, 0.0)
- bottom_overflow = max(bottom - outer_bottom, 0.0)
- horizontal = (
- left_overflow > tolerance
- or right_overflow > tolerance
- )
- vertical = (
- top_overflow > tolerance
- or bottom_overflow > tolerance
- )
- if not horizontal and not vertical:
- return None
-
- outer_width = outer_right - outer_left
- outer_height = outer_bottom - outer_top
- if outer_width <= 0.0 or outer_height <= 0.0:
- return None
- horizontal_ratio = (
- max(left_overflow, right_overflow) / outer_width
- if horizontal else 0.0
- )
- vertical_ratio = (
- max(top_overflow, bottom_overflow) / outer_height
- if vertical else 0.0
- )
- if horizontal and vertical:
- axes = 'horizontal and vertical'
- elif horizontal:
- axes = 'horizontal'
- else:
- axes = 'vertical'
- return axes, horizontal_ratio, vertical_ratio
-
- @classmethod
- def _record_bounds_overflow(
- cls,
- result: Dict,
- *,
- subject: str,
- inner: Tuple[float, float, float, float],
- container: str,
- outer: Tuple[float, float, float, float],
- repair: str,
- ) -> None:
- """Record a warning through 5% overflow and an error above it."""
- metrics = cls._bounds_overflow_metrics(inner, outer)
- if metrics is None:
- return
- axes, horizontal_ratio, vertical_ratio = metrics
- overflow_ratio = max(horizontal_ratio, vertical_ratio)
- exceeds_error_ratio = (
- overflow_ratio > _BOUNDS_OVERFLOW_ERROR_RATIO
- and not math.isclose(
- overflow_ratio,
- _BOUNDS_OVERFLOW_ERROR_RATIO,
- rel_tol=0.0,
- abs_tol=1e-9,
- )
- )
- bucket = (
- result['errors']
- if exceeds_error_ratio
- else result['warnings']
- )
- left, top, right, bottom = inner
- outer_left, outer_top, outer_right, outer_bottom = outer
- bucket.append(
- f'{subject} exceeds {container} on the {axes} axis: '
- f'content ({left:.1f}, {top:.1f})-({right:.1f}, '
- f'{bottom:.1f}), container ({outer_left:.1f}, '
- f'{outer_top:.1f})-({outer_right:.1f}, '
- f'{outer_bottom:.1f}), overflow horizontal '
- f'{horizontal_ratio:.1%}, vertical {vertical_ratio:.1%}; '
- f'{repair}'
- )
-
- @staticmethod
- def _is_hidden_element(
- element: ET.Element,
- parent_by_id: Dict[int, ET.Element],
- ) -> bool:
- """Return whether inherited display or visibility hides an element."""
- current: ET.Element | None = element
- while current is not None:
- style_values = (
- _parse_inline_style(current.get('style'))
- if _parse_inline_style is not None
- else {}
- )
- display = style_values.get('display')
- if display is None:
- display = current.get('display')
- if display and display.strip().lower() == 'none':
- return True
- current = parent_by_id.get(id(current))
- visibility = (
- _effective_presentation_value(
- element,
- 'visibility',
- parent_by_id,
- )
- or ''
- ).strip().lower()
- return visibility in {'hidden', 'collapse'}
-
- @staticmethod
- def _has_zero_opacity(
- element: ET.Element,
- parent_by_id: Dict[int, ET.Element],
- ) -> bool:
- """Return whether an element or ancestor has zero effective opacity."""
- current: ET.Element | None = element
- while current is not None:
- style_values = (
- _parse_inline_style(current.get('style'))
- if _parse_inline_style is not None
- else {}
- )
- raw = style_values.get('opacity')
- if raw is None:
- raw = current.get('opacity')
- if raw is not None:
- value = raw.strip()
- try:
- opacity = (
- float(value[:-1]) / 100
- if value.endswith('%')
- else float(value)
- )
- except ValueError:
- pass
- else:
- if opacity <= 0:
- return True
- current = parent_by_id.get(id(current))
- return False
-
- @classmethod
- def _visible_image_elements(
- cls,
- root: ET.Element,
- ) -> Tuple[ET.Element, Dict[int, ET.Element], List[ET.Element]]:
- """Return rendered image instances after expanding static local uses."""
- working_root = copy.deepcopy(root)
- if (
- _expand_local_use_references is not None
- and _UseExpansionError is not None
- ):
- try:
- _expand_local_use_references(working_root)
- except _UseExpansionError:
- # The local-reference validator owns the actionable failure.
- working_root = copy.deepcopy(root)
-
- parent_by_id = {
- id(child): parent
- for parent in working_root.iter()
- for child in list(parent)
- }
- images = [
- element
- for element in working_root.iter(f'{{{SVG_NS}}}image')
- if not cls._is_hidden_element(element, parent_by_id)
- and not cls._has_non_visual_ancestor(
- element,
- working_root,
- parent_by_id,
- )
- and not cls._has_zero_opacity(element, parent_by_id)
- ]
- return working_root, parent_by_id, images
-
- @staticmethod
- def _has_non_visual_ancestor(
- element: ET.Element,
- module: ET.Element,
- parent_by_id: Dict[int, ET.Element],
- ) -> bool:
- """Return whether an element lives in a non-rendered module subtree."""
- current: ET.Element | None = element
- while current is not None and current is not module:
- if _local_name(current) in _NON_VISUAL_SVG_TAGS:
- return True
- current = parent_by_id.get(id(current))
- return False
-
- def _check_module_bounds_contract(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Validate direct root module boundaries in the SVG canvas."""
- parent_by_id = {
- id(child): parent
- for parent in root.iter()
- for child in list(parent)
- }
- viewbox = _parse_viewbox_values(root.get('viewBox') or '')
- canvas = None
- if viewbox is not None:
- x, y, width, height = viewbox
- canvas = (x, y, x + width, y + height)
-
- for element in root.iter():
- if element.get(_BOUNDS_ATTR) is None:
- continue
- if _local_name(element) != 'g':
- result['errors'].append(
- f'{_element_label(element)} {_BOUNDS_ATTR} is valid '
- 'only on <g> layout modules'
- )
-
- missing: List[str] = []
- root_groups = [
- child
- for child in list(root)
- if _local_name(child) == 'g'
- ]
- require_bounds = (
- self.template_mode
- or root.get('data-pptx-page-role') is not None
- or any(
- root.get(attribute) is not None
- for attribute in _PPTX_ROOT_STRUCTURE_ATTRS
- )
- )
- for group in root_groups:
- if self._is_hidden_element(group, parent_by_id):
- continue
- raw_bounds = group.get(_BOUNDS_ATTR)
- if raw_bounds is None:
- missing.append(_element_label(group))
- continue
- try:
- _parse_positive_bounds(raw_bounds)
- except ValueError as exc:
- result['errors'].append(
- f'{_element_label(group)} {_BOUNDS_ATTR} {exc}'
- )
- continue
-
- resolved = self._resolved_root_module_bounds(group)
- if resolved is None or canvas is None:
- continue
- attribute, bounds = resolved
- self._record_bounds_overflow(
- result,
- subject=f'{_element_label(group)} {attribute}',
- inner=bounds,
- container='canvas viewBox',
- outer=canvas,
- repair=(
- 'keep the root module subcanvas inside the SVG viewBox'
- ),
- )
-
- if missing:
- sample = '; '.join(missing[:3])
- suffix = '' if len(missing) <= 3 else f'; +{len(missing) - 3} more'
- bucket = result['errors'] if require_bounds else result['warnings']
- prefix = 'Detected' if require_bounds else 'Reference SVG: detected'
- bucket.append(
- f'{prefix} {len(missing)} visible root-level <g> '
- f'module(s) without explicit {_BOUNDS_ATTR} '
- f'({sample}{suffix}); every final-page/template root <g> declares '
- 'its root-coordinate layout subcanvas even when it also carries '
- 'data-pptx-frame or native chart/table coordinates'
- )
-
- def _check_root_module_text_bounds(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Grade visible text against its direct root module subcanvas."""
- helpers = (
- _estimate_single_line_text_frame_width,
- _parse_project_font_weight,
- _parse_project_geometry_length,
- _parse_project_text_anchor,
- _resolve_project_font_sizes,
- _resolve_project_letter_spacings,
- )
- if any(helper is None for helper in helpers):
- return
- try:
- font_sizes = _resolve_project_font_sizes(root)
- letter_spacings = _resolve_project_letter_spacings(
- root,
- font_sizes,
- )
- except ValueError:
- return
-
- parent_by_id = {
- id(child): parent
- for parent in root.iter()
- for child in list(parent)
- }
- unchanged_groups = self._unchanged_txbody_group_ids(root)
- root_groups = [
- child
- for child in list(root)
- if _local_name(child) == 'g'
- ]
- for module in root_groups:
- if self._is_hidden_element(module, parent_by_id):
- continue
- resolved_module = self._resolved_root_module_bounds(module)
- if resolved_module is None:
- continue
- boundary_attribute, boundary = resolved_module
- for text_element in module.iter(f'{{{SVG_NS}}}text'):
- if self._has_ancestor_id(
- text_element,
- parent_by_id,
- unchanged_groups,
- ):
- continue
- if self._has_non_visual_ancestor(
- text_element,
- module,
- parent_by_id,
- ):
- continue
- if self._is_hidden_element(text_element, parent_by_id):
- continue
- visible_text = ''.join(text_element.itertext())
- if (
- not visible_text.strip()
- or ('{{' in visible_text and '}}' in visible_text)
- ):
- continue
- estimated = self._estimated_text_bounds(
- text_element,
- parent_by_id,
- font_sizes,
- letter_spacings,
- )
- if estimated is None:
- continue
- self._record_bounds_overflow(
- result,
- subject=_element_label(text_element),
- inner=estimated,
- container=(
- f'{_element_label(module)} {boundary_attribute}'
- ),
- outer=boundary,
- repair=(
- 'expand the root module bounds into available '
- 'non-overlapping space; otherwise reflow the text'
- ),
- )
-
- def _check_unmergeable_leading_text(self, root: ET.Element, result: Dict) -> None:
- """Warn when leading text cannot be normalized into one PPT text frame."""
- risky = []
- for text_el in root.iter(f'{{{SVG_NS}}}text'):
- if not (text_el.text or "").strip():
- continue
- children = list(text_el)
- if not any(self._is_line_tspan(child) for child in children):
- continue
-
- reason = self._leading_text_normalizer_reject_reason(text_el)
- if reason is not None:
- risky.append(reason)
-
- if risky:
- sample = '; '.join(risky[:3])
- suffix = '' if len(risky) <= 3 else f"; +{len(risky) - 3} more"
- result['warnings'].append(
- "Detected multi-line <text> with leading direct text that cannot "
- f"be normalized into one PPT text frame ({sample}{suffix})"
- )
-
- def _check_fragmented_paragraph_text(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Warn on high-confidence prose lines split into sibling text frames."""
- helpers = (
- _parse_project_geometry_length,
- _resolve_project_font_sizes,
- )
- if any(helper is None for helper in helpers):
- return
- try:
- font_sizes = _resolve_project_font_sizes(root)
- except ValueError:
- return
-
- parent_by_id = {
- id(child): parent
- for parent in root.iter()
- for child in list(parent)
- }
- unchanged_groups = self._unchanged_txbody_group_ids(root)
- style_properties = (
- 'fill',
- 'fill-opacity',
- 'font-family',
- 'font-style',
- 'font-weight',
- 'letter-spacing',
- 'opacity',
- 'stroke',
- 'stroke-opacity',
- 'stroke-width',
- 'text-decoration',
- )
-
- def line_record(element: ET.Element) -> Dict | None:
- if (
- _local_name(element) != 'text'
- or list(element)
- or element.get('x') is None
- or element.get('y') is None
- or any(element.get(name) is not None for name in ('dx', 'dy'))
- or element.get('transform') is not None
- or self._is_hidden_element(element, parent_by_id)
- or self._has_ancestor_id(
- element,
- parent_by_id,
- unchanged_groups,
- )
- ):
- return None
- text = (element.text or '').strip()
- compact_text = re.sub(r'\s+', '', text)
- if (
- not compact_text
- or ('{{' in text and '}}' in text)
- or _PARAGRAPH_LIST_MARKER_RE.match(text)
- ):
- return None
- anchor = (
- _effective_presentation_value(
- element,
- 'text-anchor',
- parent_by_id,
- )
- or 'start'
- ).strip().lower()
- if anchor != 'start':
- return None
- try:
- x = _parse_project_geometry_length(element.get('x'), 'x')
- y = _parse_project_geometry_length(element.get('y'), 'y')
- font_size = float(font_sizes[id(element)])
- except (KeyError, TypeError, ValueError):
- return None
- if font_size <= 0:
- return None
- style = tuple(
- (
- _effective_presentation_value(
- element,
- name,
- parent_by_id,
- )
- or ''
- ).strip().lower()
- for name in style_properties
- )
- return {
- 'chars': len(compact_text),
- 'font_size': font_size,
- 'style': style,
- 'text': text,
- 'x': x,
- 'y': y,
- }
-
- suspects: List[str] = []
- for group in list(root):
- if (
- _local_name(group) != 'g'
- or self._is_hidden_element(group, parent_by_id)
- ):
- continue
- current_run: List[Dict] = []
-
- def flush_run() -> None:
- if len(current_run) < 2:
- return
- total_chars = sum(line['chars'] for line in current_run)
- longest_line = max(line['chars'] for line in current_run)
- if (
- total_chars < _PARAGRAPH_LINE_MIN_TOTAL_CHARS
- or longest_line < _PARAGRAPH_LINE_MIN_LONGEST_CHARS
- ):
- return
- first = current_run[0]
- last = current_run[-1]
- suspects.append(
- f'{_element_label(group)} x={first["x"]:.1f}, '
- f'y={first["y"]:.1f}..{last["y"]:.1f}, '
- f'{len(current_run)} lines'
- )
-
- for child in list(group):
- line = line_record(child)
- if line is None:
- flush_run()
- current_run = []
- continue
- if current_run:
- previous = current_run[-1]
- line_gap = line['y'] - previous['y']
- same_frame = (
- abs(line['x'] - previous['x'])
- <= _PARAGRAPH_LINE_X_TOLERANCE
- and line['style'] == previous['style']
- and math.isclose(
- line['font_size'],
- previous['font_size'],
- rel_tol=0.0,
- abs_tol=1e-6,
- )
- and line_gap
- >= line['font_size'] * _PARAGRAPH_LINE_GAP_MIN_RATIO
- and line_gap
- <= line['font_size'] * _PARAGRAPH_LINE_GAP_MAX_RATIO
- and not _PARAGRAPH_LINE_TERMINATOR_RE.search(
- previous['text']
- )
- )
- if not same_frame:
- flush_run()
- current_run = []
- current_run.append(line)
- flush_run()
-
- if not suspects:
- return
- sample = '; '.join(suspects[:3])
- suffix = '' if len(suspects) <= 3 else f'; +{len(suspects) - 3} more'
- result['warnings'].append(
- f'Detected {len(suspects)} paragraph-like line run(s) split '
- f'across sibling <text> elements ({sample}{suffix}). If each run '
- 'is one prose paragraph, combine it into one <text>: keep its '
- 'first line as direct text and use direct <tspan> children with '
- 'the parent x and positive relative dy values for later lines. '
- 'An all-<tspan> form may start with dy="0". Keep semantically '
- 'independent text frames separate.'
- )
-
- @staticmethod
- def _is_tspan(elem: ET.Element) -> bool:
- return elem.tag == f'{{{SVG_NS}}}tspan'
-
- @classmethod
- def _is_line_tspan(cls, elem: ET.Element) -> bool:
- if not cls._is_tspan(elem):
- return False
- if elem.get('x') is not None or elem.get('y') is not None:
- return True
- dy = elem.get('dy')
- if dy is None:
- return False
- try:
- return float(re.match(r'^[\s,]*([+-]?(?:\d+\.?\d*|\d*\.\d+))', dy).group(1)) != 0
- except (AttributeError, ValueError):
- return True
-
- @classmethod
- def _leading_text_normalizer_reject_reason(cls, text_el: ET.Element) -> str | None:
- if text_el.get('x') is None:
- return '<text> has no x anchor'
-
- for child in list(text_el):
- if not cls._is_tspan(child):
- return '<text> has non-tspan child'
- if (child.tail or "").strip():
- return '<tspan> has non-empty tail text'
-
- return None
-
- def _check_image_references(self, root: ET.Element, svg_path: Path, result: Dict):
- """Check image file existence and effective rendered resolution."""
- svg_dir = svg_path.parent
- working_root, parent_by_id, images = self._visible_image_elements(root)
-
- for image in images:
- href = image.get('href') or image.get(f'{{{XLINK_NS}}}href')
- if not href or href.startswith('data:'):
- continue
- if self.template_mode and '{{' in href and '}}' in href:
- continue
- if _resolve_external_image_reference is None:
- result['warnings'].append(
- "Detected image references, but shared image resolver could not be imported; "
- "export will still validate them."
- )
- return
-
- img_path = _resolve_external_image_reference(svg_dir, href)
- if img_path is None:
- # The shared image-source contract already reports the
- # blocking resolution failure. This pass adds quality advice
- # only for valid, resolved images.
- continue
-
- # Check resolution vs display size
- display_owner = image
- parent = parent_by_id.get(id(image))
- if (
- parent is not None
- and parent is not working_root
- and parent.tag == f'{{{SVG_NS}}}svg'
- ):
- # Imported crops use a unit-frame inner image. Quality advice
- # must compare the source against the visible outer frame.
- display_owner = parent
- display_w_str = display_owner.get('width')
- display_h_str = display_owner.get('height')
- if not display_w_str or not display_h_str:
- continue
-
- try:
- display_x = float(display_owner.get('x') or '0')
- display_y = float(display_owner.get('y') or '0')
- local_display_w = float(display_w_str)
- local_display_h = float(display_h_str)
- except (ValueError, TypeError):
- continue
- if local_display_w <= 0 or local_display_h <= 0:
- continue
- display_w = local_display_w
- display_h = local_display_h
- transformed_size = self._transformed_rect_edge_lengths(
- display_owner,
- (display_x, display_y, local_display_w, local_display_h),
- parent_by_id,
- )
- if transformed_size is not None:
- display_w, display_h = transformed_size
- axis_scale_x = display_w / local_display_w
- axis_scale_y = display_h / local_display_h
-
- try:
- from PIL import Image as PILImage, ImageOps
- with PILImage.open(img_path) as img:
- actual_w, actual_h = ImageOps.exif_transpose(img).size
- source_bytes = img_path.stat().st_size
-
- visible_w = float(actual_w)
- visible_h = float(actual_h)
- fit_owner = image
- if display_owner is not image:
- fit_owner = display_owner
- viewbox = (display_owner.get('viewBox') or '').split()
- if len(viewbox) == 4:
- try:
- viewbox_w = float(viewbox[2])
- viewbox_h = float(viewbox[3])
- except ValueError:
- pass
- else:
- if 0 < viewbox_w <= 1 and 0 < viewbox_h <= 1:
- visible_w *= viewbox_w
- visible_h *= viewbox_h
-
- raw_aspect = fit_owner.get('preserveAspectRatio')
- try:
- align, mode = (
- _parse_project_image_aspect_ratio(raw_aspect)
- if _parse_project_image_aspect_ratio is not None
- else ('xMidYMid', 'meet')
- )
- except ValueError:
- continue
-
- local_scale_x = local_display_w / visible_w
- local_scale_y = local_display_h / visible_h
- if align == 'none':
- render_scale = max(
- local_scale_x * axis_scale_x,
- local_scale_y * axis_scale_y,
- )
- fit_label = 'none'
- elif mode == 'slice':
- render_scale = (
- max(local_scale_x, local_scale_y)
- * max(axis_scale_x, axis_scale_y)
- )
- fit_label = 'slice'
- else:
- render_scale = (
- min(local_scale_x, local_scale_y)
- * max(axis_scale_x, axis_scale_y)
- )
- fit_label = 'meet'
-
- if render_scale > 1.0:
- result['warnings'].append(
- f"Image {href} is {actual_w}x{actual_h} and renders at "
- f"{render_scale:.2f}x scale in a "
- f"{int(display_w)}x{int(display_h)} {fit_label} frame "
- "— may appear blurry"
- )
- elif (
- render_scale < 1.0 / IMAGE_DOWNSIZE_WARN_RATIO
- and source_bytes >= IMAGE_DOWNSIZE_WARN_MIN_BYTES
- ):
- source_mib = source_bytes / (1024 * 1024)
- result['warnings'].append(
- f"Image {href} is {actual_w}x{actual_h} and renders at "
- f"{render_scale:.2f}x scale in a "
- f"{int(display_w)}x{int(display_h)} {fit_label} frame; "
- f"the source is {source_mib:.1f} MiB — file-size "
- "advisory only, not an aspect-ratio warning; consider "
- "a smaller source asset"
- )
- except ImportError:
- pass # PIL not available, skip resolution check
- except Exception:
- pass # Image unreadable, skip resolution check
-
- def _check_icon_placeholders(self, root: ET.Element, svg_path: Path, result: Dict) -> None:
- """Check that <use data-icon="..."> placeholders resolve."""
- placeholders = [
- elem for elem in root.iter()
- if _local_name(elem).lower() == 'use' and elem.get('data-icon') is not None
- ]
- if not placeholders:
- return
-
- if _resolve_icon_path is None:
- result['warnings'].append(
- "Detected data-icon placeholders, but icon resolver could not be imported; "
- "post-processing/export will still validate them."
- )
- return
- if _icon_search_dirs_for_svg is None:
- result['warnings'].append(
- "Detected data-icon placeholders, but shared icon search helper could not be imported; "
- "post-processing/export will still validate them."
- )
- return
-
- icons_dir, fallback_dir = _icon_search_dirs_for_svg(svg_path)
- require_project_local = self._requires_project_local_icons(svg_path)
- project_icons_dir = (
- _project_root_for_svg_path(svg_path) / 'icons'
- if _project_root_for_svg_path is not None
- else None
- )
- seen = set()
- for elem in placeholders:
- icon_name = (elem.get('data-icon') or '').strip()
- if not icon_name:
- result['errors'].append("Icon placeholder has empty data-icon value")
- continue
- if icon_name in seen:
- continue
- seen.add(icon_name)
-
- if require_project_local and project_icons_dir is not None:
- local_path, _ = _resolve_icon_path(
- icon_name,
- project_icons_dir,
- None,
- )
- if not local_path.exists():
- result['errors'].append(
- f"Icon is not prepared in the project: {icon_name} "
- f"(expected under {project_icons_dir}); return to "
- "Strategist preparation instead of using the global fallback"
- )
- continue
-
- icon_path, _ = _resolve_icon_path(icon_name, icons_dir, fallback_dir)
- if not icon_path.exists():
- fallback_msg = f", then {fallback_dir}" if fallback_dir else ""
- suggestion = (
- _suggest_icon_name(icon_name, icons_dir, fallback_dir)
- if _suggest_icon_name is not None else None
- )
- hint = (
- f"; identifiers are case-sensitive; use '{suggestion}'"
- if suggestion else ""
- )
- result['errors'].append(
- f"Icon not found: {icon_name} (searched {icons_dir}"
- f"{fallback_msg}){hint}"
- )
- continue
- try:
- icon_root = ET.parse(icon_path).getroot()
- hydrated = hydrate_native_payload_refs(icon_root, icon_path)
- except (OSError, ET.ParseError, NativePayloadError) as exc:
- result['errors'].append(
- f"Icon {icon_name} has invalid native payload metadata: {exc}"
- )
- continue
- if _project_mask_errors is not None:
- result['errors'].extend(
- f'Icon {icon_name}: {error}'
- for error in _project_mask_errors(icon_root)
- )
- if hydrated:
- result['info']['native_icon_payload_refs'] = (
- result['info'].get('native_icon_payload_refs', 0) + hydrated
- )
-
- @staticmethod
- def _requires_project_local_icons(svg_path: Path) -> bool:
- """Return whether a generated page belongs to a versioned project."""
- if svg_path.parent.name != 'svg_output' or _project_root_for_svg_path is None:
- return False
- lock_path = _project_root_for_svg_path(svg_path) / 'spec_lock.md'
- try:
- first_line = next(
- (
- line.strip()
- for line in lock_path.read_text(encoding='utf-8-sig').splitlines()
- if line.strip()
- ),
- '',
- )
- except OSError:
- return False
- return bool(
- re.fullmatch(
- r'<!--[ \t]+ppt-master-schema:[ \t]*spec-lock/v[1-9][0-9]*[ \t]+-->',
- first_line,
- re.IGNORECASE,
- )
- )
-
- def _check_unsupported_visual_elements(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Reject authored visual elements with no native converter dispatch."""
- if _collect_unsupported_visuals is None:
- result['errors'].append(
- "Unable to import native visual-element preflight; "
- "cannot verify SVG element support"
- )
- return
- if _expand_local_use_references is None or _UseExpansionError is None:
- result['errors'].append(
- "Unable to import local <use> expansion; "
- "cannot verify SVG element support"
- )
- return
-
- expanded_root = copy.deepcopy(root)
- try:
- _expand_local_use_references(expanded_root)
- except _UseExpansionError:
- # _check_forbidden_elements already reports the actionable
- # local-reference validation error.
- return
-
- unsupported = _collect_unsupported_visuals(
- expanded_root,
- allow_data_icon_use=True,
- )
- if not unsupported:
- return
-
- preview = '; '.join(unsupported[:8])
- suffix = '' if len(unsupported) <= 8 else f'; +{len(unsupported) - 8} more'
- result['errors'].append(
- f"Unsupported visual SVG element(s) for native PPTX export: "
- f"{preview}{suffix}"
- )
-
- def _check_preset_geometry_metadata(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Validate round-trip preset metadata with the exporter's parser."""
- marked = [
- elem
- for elem in root.iter()
- if (
- elem.get('data-pptx-prst') is not None
- or elem.get('data-pptx-frame') is not None
- or elem.get('data-pptx-geometry-status') is not None
- or elem.get('data-pptx-geometry-reason') is not None
- or elem.get('data-pptx-geometry-kind') is not None
- or elem.get('data-pptx-custgeom') is not None
- or elem.get('data-pptx-preview-sha256') is not None
- or elem.get('data-pptx-shape-id') is not None
- or elem.get('data-pptx-shape-scope') is not None
- or elem.get('data-pptx-shape-style') is not None
- or elem.get(_AUTHORING_ATTR) is not None
- or any(attr.startswith('data-pptx-av-') for attr in elem.attrib)
- )
- ]
- if not marked:
- return
- if _validate_preset_geometry_metadata is None:
- result['errors'].append(
- 'Unable to import PPTX preset metadata validator; '
- 'cannot verify native shape restoration'
- )
- return
-
- issues = set()
- for elem in marked:
- tag = _local_name(elem)
- elem_id = elem.get('id')
- label = f'<{tag} id="{elem_id}">' if elem_id else f'<{tag}>'
- for error in _validate_preset_geometry_metadata(elem):
- issues.add(f'{label} has invalid PPTX shape metadata: {error}')
- if _validate_authored_preset_tree is None:
- if any(
- elem.get(_AUTHORING_ATTR) is not None
- for elem in root.iter()
- ):
- issues.add(
- 'Unable to import authored PPTX preset validator'
- )
- else:
- for error in _validate_authored_preset_tree(root):
- issues.add(f'Invalid authored PPTX preset: {error}')
- if (
- _svg_preset_preview_fingerprint is None
- or _resolve_preset_preview_hash is None
- ):
- issues.add('Unable to import PPTX preset preview fingerprint validator')
- else:
- for elem in root.iter():
- if (
- _local_name(elem) != 'g'
- or elem.get('data-pptx-object') not in {'shape', 'connector'}
- or elem.get('data-pptx-prst') is None
- ):
- continue
- try:
- expected = _resolve_preset_preview_hash(elem)
- except ValueError as exc:
- elem_id = elem.get('id') or '(no id)'
- issues.add(
- f'<g id="{elem_id}"> has an invalid PPTX preset '
- f'preview contract: {exc}'
- )
- continue
- if expected is None:
- continue
- actual = _svg_preset_preview_fingerprint(elem)
- if actual != expected:
- elem_id = elem.get('id') or '(no id)'
- issues.add(
- f'<g id="{elem_id}"> has a stale PPTX preset preview; '
- 'update the native carrier or restore the generated detail paths'
- )
- result['errors'].extend(sorted(issues))
- if (
- _authored_preset_encoding is not None
- and _validate_authored_preset_group is not None
- ):
- expanded = [
- elem.get('id') or '(no id)'
- for elem in root.iter()
- if _authored_preset_encoding(elem) == 'expanded'
- and not _validate_authored_preset_group(elem)
- ]
- if expanded:
- examples = ', '.join(expanded[:3])
- suffix = '' if len(expanded) <= 3 else f', +{len(expanded) - 3} more'
- result['warnings'].append(
- 'Compatible expanded authored-preset fragment(s) detected '
- f'({len(expanded)}: {examples}{suffix}). New project-authored '
- 'pages and templates use the compact helper form; the '
- 'expanded carrier/preview form remains readable for compatibility. '
- 'No change is required while it remains ordinary Slide-local input.'
- )
- inherited_paint = _compact_preset_ancestor_paint(root)
- if inherited_paint:
- examples = ', '.join(
- f'{element_id} ({"/".join(properties)})'
- for element_id, properties in inherited_paint[:3]
- )
- suffix = (
- ''
- if len(inherited_paint) <= 3
- else f', +{len(inherited_paint) - 3} more'
- )
- result['warnings'].append(
- 'Compact authored preset(s) use compatible ancestor paint or '
- f'opacity ({examples}{suffix}). Canonical page/template authoring '
- 'keeps preset paint local and reruns the helper with channel alpha; '
- 'export remains supported.'
- )
-
- def _check_preset_geometry_transforms(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Reject preset transforms that DrawingML cannot represent exactly."""
- helpers = (
- _IDENTITY_MATRIX,
- _matrix_multiply,
- _parse_transform_matrix,
- _rect_to_dml_xfrm,
- _validate_dml_shape_matrix,
- )
- if any(helper is None for helper in helpers):
- return
-
- relevant: set[ET.Element] = set()
-
- def mark_relevant(element: ET.Element) -> bool:
- found = element.get('data-pptx-prst') is not None
- for child in element:
- found = mark_relevant(child) or found
- if found:
- relevant.add(element)
- return found
-
- mark_relevant(root)
- issues = set()
-
- def visit(element: ET.Element, parent_matrix) -> None:
- if element not in relevant:
- return
- matrix = parent_matrix
- transform = element.get('transform')
- if transform:
- try:
- local_matrix = _parse_transform_matrix(transform)
- matrix = _matrix_multiply(parent_matrix, local_matrix)
- except ValueError as exc:
- issues.add(
- f'<{_local_name(element)}> has invalid preset '
- f'transform: {exc}'
- )
- return
- if element.get('data-pptx-prst') is not None:
- try:
- raw_frame = element.get('data-pptx-frame')
- if raw_frame:
- frame = tuple(
- float(part)
- for part in re.split(r'[\s,]+', raw_frame.strip())
- )
- if len(frame) != 4:
- raise ValueError(
- 'data-pptx-frame must contain four numbers'
- )
- preset = element.get('data-pptx-prst') or ''
- _rect_to_dml_xfrm(
- frame[0],
- frame[1],
- frame[2],
- frame[3],
- matrix,
- preserve_degenerate_axes=(
- element.get('data-pptx-object') == 'connector'
- or preset in _CONNECTOR_PRESET_TYPES
- ),
- )
- else:
- _validate_dml_shape_matrix(matrix)
- except ValueError as exc:
- elem_id = element.get('id') or '(no id)'
- issues.add(
- f'<{_local_name(element)} id="{elem_id}"> has '
- f'unsupported preset transform: {exc}'
- )
- for child in element:
- visit(child, matrix)
-
- visit(root, _IDENTITY_MATRIX)
- result['errors'].extend(sorted(issues))
-
- @staticmethod
- def _is_full_canvas_root_rect(
- root: ET.Element,
- element: ET.Element,
- ) -> bool:
- """Return whether one direct rect is the ordinary full-page backdrop."""
- if (
- _local_name(element) != 'rect'
- or _parse_project_geometry_length is None
- or any(
- element.get(attribute)
- for attribute in ('transform', 'filter', 'clip-path')
- )
- ):
- return False
- viewbox = _parse_viewbox_values(root.get('viewBox') or '')
- if viewbox is None:
- return False
-
- parent_by_id = {id(element): root}
-
- def inherited(name: str, default: str) -> str:
- return _effective_presentation_value(
- element,
- name,
- parent_by_id,
- ) or default
-
- try:
- values = {
- name: _parse_project_geometry_length(
- element.get(name) or '0',
- name,
- )
- for name in ('x', 'y', 'width', 'height', 'rx', 'ry')
- }
- stroke_width = _parse_project_geometry_length(
- inherited('stroke-width', '1'),
- 'stroke-width',
- )
- stroke_opacity = (
- _parse_project_opacity(inherited('stroke-opacity', '1'))
- if _parse_project_opacity is not None else 1.0
- )
- except ValueError:
- return False
- fill = inherited('fill', '#000000').strip().lower()
- stroke = inherited('stroke', 'none').strip().lower()
- if (
- fill == 'none'
- or (
- stroke != 'none'
- and stroke_width > 0
- and stroke_opacity > 0
- )
- ):
- return False
-
- view_x, view_y, view_width, view_height = viewbox
- tolerance = 0.5
- return (
- values['rx'] == 0
- and values['ry'] == 0
- and abs(values['x'] - view_x) <= tolerance
- and abs(values['y'] - view_y) <= tolerance
- and abs(values['width'] - view_width) <= tolerance
- and abs(values['height'] - view_height) <= tolerance
- )
-
- def _check_animation_group_ids(
- self,
- root: ET.Element,
- svg_path: Path,
- result: Dict,
- ):
- """Validate top-level animation anchors without policing inner groups."""
- non_visual = {'defs', 'title', 'desc', 'metadata', 'style'}
- group_indexes: Dict[str, List[int]] = defaultdict(list)
- ungrouped: List[str] = []
- ungrouped_signatures: List[Tuple[object, ...]] = []
- visual_index = 0
-
- for child in root:
- tag = _local_name(child)
- if tag in non_visual:
- continue
- visual_index += 1
- is_first_visual = visual_index == 1
-
- if tag == 'g':
- group_id = _usable_animation_group_id(child.get('id'))
- if group_id is None:
- result['warnings'].append(
- f"Top-level visible <g> #{visual_index} has no id; "
- "object-level animation config cannot reference it"
- )
- continue
- group_indexes[group_id].append(visual_index)
- continue
-
- if svg_path.parent.name != 'svg_output':
- continue
- if child.get('data-pptx-layer') is not None:
- continue
- if (
- _is_static_page_frame is not None
- and _is_static_page_frame(
- child.get('data-pptx-role'),
- child.get('data-pptx-placeholder'),
- )
- ):
- continue
- if is_first_visual and self._is_full_canvas_root_rect(root, child):
- continue
- child_id = (child.get('id') or '').strip()
- ungrouped.append(
- f'<{tag} id="{child_id}">'
- if child_id else f'<{tag}> #{visual_index}'
- )
- ungrouped_signatures.append(
- self._prototype_element_signature(child)
- )
-
- for group_id, indexes in sorted(group_indexes.items()):
- if len(indexes) > 1:
- positions = ', '.join(str(item) for item in indexes)
- result['errors'].append(
- f'Duplicate top-level group id {group_id!r} at visible '
- f'positions {positions}; animation target ids must be unique'
- )
-
- if ungrouped:
- samples = ', '.join(ungrouped[:3])
- if len(ungrouped) > 3:
- samples += ', ...'
- message = (
- f'{len(ungrouped)} ungrouped top-level Slide-local element(s) '
- f'in svg_output ({samples}); group only logical content units '
- 'in a top-level <g id="...">. Keep genuine static page framing '
- 'as a root primitive and declare a supported data-pptx-role such '
- 'as "background" or "decoration"'
- )
- prototype_root = self._active_prototype_root()
- prototype_ungrouped = (
- self._ungrouped_slide_local_facts(prototype_root)
- if prototype_root is not None
- else ([], [])
- )
- if (
- prototype_root is not None
- and ungrouped == prototype_ungrouped[0]
- and ungrouped_signatures == prototype_ungrouped[1]
- ):
- self._append_inherited_info(
- result,
- 'animation_anchor',
- message,
- )
- else:
- result['warnings'].append(message)
-
- @staticmethod
- def _prototype_element_signature(
- element: ET.Element,
- ) -> Tuple[object, ...]:
- """Compare warning-owned topology/style while ignoring visible text."""
- return (
- _local_name(element),
- tuple(sorted(element.attrib.items())),
- tuple(
- SVGQualityChecker._prototype_element_signature(child)
- for child in element
- ),
- )
-
- def _ungrouped_slide_local_facts(
- self,
- root: ET.Element,
- ) -> Tuple[List[str], List[Tuple[object, ...]]]:
- """Describe and fingerprint top-level non-group Slide-local atoms."""
- non_visual = {'defs', 'title', 'desc', 'metadata', 'style'}
- descriptors: List[str] = []
- signatures: List[Tuple[object, ...]] = []
- visual_index = 0
- for child in root:
- tag = _local_name(child)
- if tag in non_visual:
- continue
- visual_index += 1
- if tag == 'g' or child.get('data-pptx-layer') is not None:
- continue
- if (
- _is_static_page_frame is not None
- and _is_static_page_frame(
- child.get('data-pptx-role'),
- child.get('data-pptx-placeholder'),
- )
- ):
- continue
- if visual_index == 1 and self._is_full_canvas_root_rect(root, child):
- continue
- child_id = (child.get('id') or '').strip()
- descriptors.append(
- f'<{tag} id="{child_id}">'
- if child_id else f'<{tag}> #{visual_index}'
- )
- signatures.append(self._prototype_element_signature(child))
- return descriptors, signatures
-
- # OOXML ST_PresetPatternVal enum — anything outside this set produces a
- # PPTX schema violation ("PowerPoint found a problem with the content").
- _OOXML_PATTERN_PRESETS = frozenset({
- 'pct5', 'pct10', 'pct20', 'pct25', 'pct30', 'pct40', 'pct50', 'pct60',
- 'pct70', 'pct75', 'pct80', 'pct90',
- 'horz', 'vert', 'ltHorz', 'ltVert', 'dkHorz', 'dkVert',
- 'narHorz', 'narVert', 'dashHorz', 'dashVert',
- 'cross', 'dnDiag', 'upDiag', 'ltDnDiag', 'ltUpDiag', 'dkDnDiag',
- 'dkUpDiag', 'wdDnDiag', 'wdUpDiag',
- 'dashDnDiag', 'dashUpDiag', 'diagCross',
- 'smCheck', 'lgCheck', 'smGrid', 'lgGrid', 'dotGrid', 'smConfetti',
- 'lgConfetti', 'horzBrick', 'diagBrick', 'solidDmnd', 'openDmnd',
- 'dotDmnd', 'plaid', 'sphere', 'weave', 'wave', 'trellis', 'zigZag',
- 'divot', 'shingle',
- })
-
- def _check_pattern_fills(self, root: ET.Element, result: Dict):
- """Audit <pattern> defs that drive PPTX <a:pattFill> output.
-
- svg_to_pptx maps <pattern fill> to native <a:pattFill prst="...">. The
- preset name comes from `data-pptx-pattern` (e.g. `lgGrid` / `smGrid` /
- `dkUpDiag`). Two failure modes worth catching pre-export:
-
- 1. Missing annotation → the converter compatibility fallback chooses
- `ltUpDiag` (diagonal stripes), which is not an authoring contract.
- 2. Invalid preset name → PPTX schema rejects the file; PowerPoint
- opens it with "needs to be repaired". OOXML
- `ST_PresetPatternVal` is a closed enum — only the names in
- `_OOXML_PATTERN_PRESETS` are legal. Inventing `ltGrid` (no such
- value) is the canonical mistake; the only grids are `smGrid` /
- `lgGrid` / `dotGrid`.
- """
- definitions, _duplicates = _direct_defs_index(root)
- referenced_patterns: set[str] = set()
- for elem in root.iter():
- style_values = (
- _parse_inline_style(elem.get('style'))
- if _parse_inline_style is not None else {}
- )
- fill = style_values.get('fill') or elem.get('fill')
- match = re.fullmatch(r'url\(#([^)]+)\)', (fill or '').strip())
- if match is None:
- continue
- definition = definitions.get(match.group(1))
- if definition is not None and _local_name(definition) == 'pattern':
- referenced_patterns.add(match.group(1))
-
- for pattern in (
- elem for elem in root.iter()
- if _local_name(elem) == 'pattern'
- ):
- pat_id = pattern.get('id', '<unnamed>')
- prst = pattern.get('data-pptx-pattern')
- if pat_id in referenced_patterns and not prst:
- result['warnings'].append(
- f"Fidelity warning: <pattern id=\"{pat_id}\"> has no "
- "data-pptx-pattern attribute, so the converter will use its "
- "compatible `ltUpDiag` fallback. Generated SVG should declare a valid "
- "data-pptx-pattern to make the intended preset explicit; "
- "set data-pptx-fg/data-pptx-bg or matching child paints "
- "when explicit pattern colors are required. No change is "
- "required for export."
- )
- if pat_id in referenced_patterns and pattern.get('patternTransform'):
- result['errors'].append(
- f"<pattern id=\"{pat_id}\"> cannot use patternTransform; "
- "the native preset mapping does not preserve custom tile transforms"
- )
- if prst not in self._OOXML_PATTERN_PRESETS:
- if not prst:
- continue
- result['errors'].append(
- f"<pattern id=\"{pat_id}\"> uses data-pptx-pattern=\"{prst}\" "
- "which is not in OOXML ST_PresetPatternVal — exported PPTX "
- "will fail schema validation ('needs to be repaired'). "
- "Use one of: smGrid / lgGrid / dotGrid (grids), "
- "ltUpDiag / dkUpDiag / cross / diagCross / weave / plaid / "
- "horzBrick (others); see references/native-data-interface.md §1 "
- "for the full authoring enum."
- )
-
- def _check_native_object_markers(self, root: ET.Element, result: Dict) -> None:
- """Validate opt-in native table/chart markers before PPTX export."""
- invalid_status_elements: set[ET.Element] = set()
- for elem in root.iter():
- marker_id = elem.get('id') or elem.get('data-name') or '<unnamed>'
- if elem.tag.rsplit('}', 1)[-1] == 'metadata':
- continue
- has_status = any(
- elem.get(name) is not None
- for name in (
- 'data-pptx-replace-with',
- 'data-pptx-native',
- 'data-pptx-fallback-kind',
- 'data-pptx-visual-status',
- 'data-pptx-route-status',
- 'data-pptx-replacement-status',
- 'data-pptx-native-status',
- 'data-pptx-import-source',
- 'data-pptx-native-source',
- )
- )
- if not has_status:
- continue
- if (
- _native_marker_status_errors is None
- or _native_marker_release_block_reason is None
- ):
- result['errors'].append(
- "Unable to import native-object status validator; "
- f"cannot verify PPTX graphic {marker_id}"
- )
- continue
- status_errors = _native_marker_status_errors(elem)
- for error in status_errors:
- result['errors'].append(
- f"PPTX graphic {marker_id} has invalid status metadata: {error}"
- )
- if status_errors:
- invalid_status_elements.add(elem)
- continue
- if _native_marker_legacy_warnings is not None:
- for warning in _native_marker_legacy_warnings(elem):
- result['warnings'].append(
- f"PPTX replacement marker {marker_id}: {warning}"
- )
- try:
- fallback_kind = (
- _native_fallback_kind(elem)
- if _native_fallback_kind is not None else None
- )
- replacement_kind = (
- _native_replacement_kind(elem)
- if _native_replacement_kind is not None else ''
- )
- except ValueError:
- # The shared status validator reported the alias conflict.
- continue
- if fallback_kind == 'placeholder':
- route = (
- "the native Chart/Table route may reconstruct its active marker"
- if replacement_kind
- else "default export keeps the visible placeholder"
- )
- result['warnings'].append(
- f"PPTX graphic {marker_id} is a reconstruction-only placeholder; "
- f"it has no baked preview and {route}"
- )
-
- for elem in root.iter():
- if elem.tag.rsplit('}', 1)[-1] == 'metadata':
- continue
- if _native_replacement_status is None or _native_replacement_kind is None:
- continue
- try:
- status = _native_replacement_status(elem)
- replacement_kind = _native_replacement_kind(elem)
- except ValueError:
- continue
- if not status or replacement_kind:
- continue
- marker_id = elem.get('id') or elem.get('data-name') or '<unnamed>'
- result['warnings'].append(
- f"Native PPTX object {marker_id} is fallback-only: {status}"
- )
-
- markers = [
- elem for elem in root.iter()
- if (
- _native_replacement_kind is not None
- and elem.tag.rsplit('}', 1)[-1] != 'metadata'
- and elem not in invalid_status_elements
- and _native_replacement_kind(elem)
- )
- ]
- if not markers:
- return
- if _validate_native_object_marker is None:
- result['warnings'].append(
- "Detected data-pptx-replace-with markers, but replacement validator "
- "could not be imported; export-time validation will still run."
- )
- return
-
- parent_map = {
- child: parent
- for parent in root.iter()
- for child in parent
- }
-
- def append_metadata_legacy_warnings(marker: ET.Element) -> None:
- if _native_marker_legacy_warnings is None:
- return
- marker_id = marker.get('id') or '<unnamed>'
- for child in marker:
- if child.tag.rsplit('}', 1)[-1] != 'metadata':
- continue
- for warning in _native_marker_legacy_warnings(child):
- result['warnings'].append(
- f"PPTX replacement marker {marker_id}: {warning}"
- )
-
- for marker in markers:
- marker_id = marker.get('id') or '<unnamed>'
- ancestors = []
- parent = parent_map.get(marker)
- while parent is not None and parent is not root:
- if parent.tag.rsplit('}', 1)[-1] == 'g':
- ancestors.append(parent)
- parent = parent_map.get(parent)
- ancestors_tuple = tuple(reversed(ancestors))
- if _validate_native_object_marker_with_warnings is not None:
- try:
- warnings = _validate_native_object_marker_with_warnings(
- marker,
- ancestors=ancestors_tuple,
- document_root=root,
- )
- except RuntimeError as exc:
- result['errors'].append(
- f"Invalid data-pptx-replace-with marker {marker_id}: {exc}"
- )
- continue
- for warning in warnings:
- result['warnings'].append(
- f"data-pptx-replace-with marker {marker_id}: {warning}"
- )
- append_metadata_legacy_warnings(marker)
- continue
-
- try:
- _validate_native_object_marker(marker, ancestors=ancestors_tuple)
- except RuntimeError as exc:
- result['errors'].append(
- f"Invalid data-pptx-replace-with marker {marker_id}: {exc}"
- )
- continue
- append_metadata_legacy_warnings(marker)
- if _native_object_marker_warnings is None:
- continue
- for warning in _native_object_marker_warnings(
- marker,
- ancestors=ancestors_tuple,
- document_root=root,
- ):
- result['warnings'].append(
- f"data-pptx-replace-with marker {marker_id}: {warning}"
- )
-
- def _check_pptx_structure_metadata(
- self,
- root: ET.Element,
- svg_path: Path,
- result: Dict,
- ) -> None:
- """Validate the intrinsic structured Master/Layout SVG contract."""
- if self.quick_generate:
- forbidden_attrs = sorted({
- attr
- for elem in root.iter()
- for attr in _PPTX_STRUCTURE_ATTRS
- if elem.get(attr) is not None
- })
- if forbidden_attrs:
- result['errors'].append(
- f"{svg_path.name}: Quick Generate uses flat export and "
- "forbids Master/Layout/layer/placeholder metadata; remove "
- + ', '.join(forbidden_attrs)
- )
- return
- if not self.template_mode and svg_path.parent.name == 'svg_output':
- declared_mode = _declared_pptx_structure_mode(
- self._resolve_project_path(svg_path)
- )
- if declared_mode == 'flat':
- forbidden_attrs = sorted({
- attr
- for elem in root.iter()
- for attr in _PPTX_STRUCTURE_ATTRS
- if elem.get(attr) is not None
- })
- if forbidden_attrs:
- result['errors'].append(
- f"{svg_path.name}: pptx_structure.mode: flat forbids "
- "Master/Layout/layer/placeholder metadata; remove "
- + ', '.join(forbidden_attrs)
- )
- return
- if declared_mode != 'structured':
- # The project-level gate emits one actionable migration error.
- # Avoid burying it under repeated per-page structure failures.
- return
- has_structure_metadata = any(
- elem.get(attr) is not None
- for elem in root.iter()
- for attr in _PPTX_STRUCTURE_ATTRS
- )
- require_structure = bool(
- self.template_mode
- or svg_path.parent.name == 'svg_output'
- )
- if not has_structure_metadata and not require_structure:
- return
- result['errors'].extend(_local_pptx_structure_errors(
- root,
- svg_path,
- require_structure=require_structure,
- ))
- self._check_placeholder_carrier_flattening(root, svg_path, result)
- if svg_path.parent.name == 'svg_output':
- self._append_structure_coverage_warnings(root, result)
- if _validate_template_structure_svg is None:
- result['errors'].append(
- "Structured PPTX metadata validator could not be imported; "
- "the quality gate cannot verify this SVG"
- )
- return
- result['errors'].extend(_validate_template_structure_svg(svg_path))
- result['errors'] = list(dict.fromkeys(result['errors']))
-
- @staticmethod
- def _check_placeholder_carrier_flattening(
- root: ET.Element,
- svg_path: Path,
- result: Dict,
- ) -> None:
- """Reject slot carriers that export as multiple native children.
-
- Default export flattens non-mergeable positional ``<tspan>`` lines
- before converting the surrounding slot group to DrawingML. Reuse that
- exact transform here so the quality gate fails before the later
- placeholder-unwrapping step does.
- """
- if _flatten_positional_tspans is None:
- return
-
- candidate_ids: List[str] = []
- for slot in root.iter(f'{{{SVG_NS}}}g'):
- if not (slot.get('data-pptx-placeholder') or '').strip():
- continue
- binding = (
- slot.get('data-pptx-binding') or 'carrier'
- ).strip().lower()
- if binding != 'carrier':
- continue
- visual_children = [
- child for child in list(slot)
- if _local_name(child) not in _NON_VISUAL_SVG_TAGS
- ]
- carriers = [
- child for child in visual_children
- if (child.get('data-pptx-carrier') or '')
- .strip()
- .lower()
- == 'true'
- ]
- slot_id = (slot.get('id') or '').strip()
- if not slot_id or len(visual_children) != 1 or len(carriers) != 1:
- continue
- if not any(
- _local_name(descendant) == 'tspan'
- and any(
- descendant.get(name) is not None
- for name in ('x', 'y', 'dy')
- )
- for descendant in carriers[0].iter()
- ):
- continue
- candidate_ids.append(slot_id)
-
- if not candidate_ids:
- return
-
- flattened_root = copy.deepcopy(root)
- try:
- _flatten_positional_tspans(
- ET.ElementTree(flattened_root),
- merge_paragraphs=True,
- preserve_line_breaks=True,
- )
- except ValueError:
- # The shared text check reports the unsupported nested-position
- # contract; avoid turning a quality result into a checker crash.
- return
- slots_by_id = {
- (slot.get('id') or '').strip(): slot
- for slot in flattened_root.iter(f'{{{SVG_NS}}}g')
- if (slot.get('id') or '').strip()
- }
- for slot_id in candidate_ids:
- slot = slots_by_id.get(slot_id)
- if slot is None:
- continue
- native_children = [
- child for child in list(slot)
- if _local_name(child) not in _NON_VISUAL_SVG_TAGS
- ]
- if len(native_children) == 1:
- continue
- result['errors'].append(
- f"{svg_path.name}: placeholder slot {slot_id} becomes "
- f"{len(native_children)} native children after positional "
- "<tspan> flattening; a carrier-bound slot must export as one "
- "text or picture carrier. Use one single-frame dy-stacked text "
- "frame, or move independently positioned lines outside the slot"
- )
-
- def _append_structure_coverage_warnings(
- self,
- root: ET.Element,
- result: Dict,
- ) -> None:
- """Warn on mapped pages that compile to bare Masters / empty Layouts.
-
- Zero-slot and framing-only Layouts are legal contracts, so these stay
- advisory warnings. They neither fail the workflow gate nor require a
- per-warning disposition.
- """
- messages = self._structure_coverage_messages(root)
- if not messages:
- return
- prototype_root = self._active_prototype_root()
- if (
- prototype_root is not None
- and messages == self._structure_coverage_messages(prototype_root)
- ):
- for message in messages:
- self._append_inherited_info(
- result,
- 'structure_coverage',
- message,
- )
- return
- result['warnings'].extend(messages)
-
- @staticmethod
- def _structure_coverage_messages(root: ET.Element) -> List[str]:
- """Return advisory coverage messages for one structured page."""
- if not (root.get('data-pptx-layout') or '').strip():
- return []
- messages: List[str] = []
- has_layer_mark = any(
- elem.get('data-pptx-layer') is not None
- for elem in root.iter()
- )
- has_layout_atom = any(
- child.get('data-pptx-layer') == 'layout'
- for child in list(root)
- )
- has_placeholder = any(
- elem.get('data-pptx-placeholder') is not None
- for elem in root.iter()
- )
- if not has_layer_mark:
- messages.append(
- 'Mapped page declares data-pptx-layout but no data-pptx-layer '
- 'mark; the exported Master gets no shared background/chrome '
- 'and the Layout gets no static framing. Generated templates '
- 'should mark the deck-wide '
- 'background data-pptx-layer="master" and this layout key\'s '
- 'framing data-pptx-layer="layout". No change or disposition '
- 'is required.'
- )
- if not has_placeholder and not has_layout_atom:
- messages.append(
- 'Mapped page has no placeholder slot and no '
- 'data-pptx-layer="layout" atom; its Layout exports empty. '
- 'Generated templates should declare the slots the page actually '
- 'has (title / subtitle / '
- 'body / picture / slide-number / footer) and mark the layout '
- 'key\'s static framing unless this is intentionally a fixed '
- 'zero-slot composition. No change or disposition is required.'
- )
- elif not has_placeholder:
- messages.append(
- 'Mapped Layout has static framing but no insertable '
- 'placeholder slot. Generated templates should declare the '
- 'slots the page actually has (title / subtitle / body / '
- 'picture / slide-number / footer) unless zero-slot is the '
- 'intended reusable contract. No change or disposition is required.'
- )
- return messages
-
- @staticmethod
- def _check_legacy_pptx_attributes(
- root: ET.Element,
- svg_path: Path,
- result: Dict,
- ) -> None:
- """Reject superseded long-form authoring attributes."""
- for element in root.iter():
- for legacy, canonical in _LEGACY_PPTX_ATTRIBUTE_RENAMES.items():
- if element.get(legacy) is None:
- continue
- result['errors'].append(
- f'{svg_path.name}: {_element_label(element)} uses legacy '
- f'{legacy}; rename it to {canonical}'
- )
-
- def _check_semantic_markers(
- self,
- root: ET.Element,
- svg_path: Path,
- result: Dict,
- ) -> None:
- """Validate minimal compiler hints without changing SVG rendering."""
- has_semantics = any(
- elem.get(attr) is not None
- for elem in root.iter()
- for attr in _SEMANTIC_ATTRS
- )
- require_page_role = (
- svg_path.parent.name in {'svg_output', 'svg_final'}
- and root.get('data-pptx-layout') is None
- )
- if _validate_semantic_markers is None:
- if has_semantics:
- result['warnings'].append(
- "Detected Semantic SVG markers, but their validator could "
- "not be imported."
- )
- return
- for issue in _validate_semantic_markers(
- root,
- require_page_role=require_page_role,
- ):
- if issue.severity == 'error':
- result['errors'].append(issue.message)
- else:
- result['warnings'].append(issue.message)
-
- def _get_spec_lock(self, svg_path: Path):
- """Locate and parse spec_lock.md near the SVG. Returns dict or None.
-
- Looks in svg_path.parent and svg_path.parent.parent (covers the two
- common layouts: SVG directly under <project>/ or under
- <project>/svg_output/). Results are cached per lock path.
- """
- if self.quick_generate:
- return None
- if _parse_spec_lock is None:
- return None
- for candidate in (svg_path.parent / 'spec_lock.md',
- svg_path.parent.parent / 'spec_lock.md'):
- if candidate in self._lock_cache:
- return self._lock_cache[candidate]
- if candidate.exists():
- try:
- data = _parse_spec_lock(candidate)
- except Exception:
- data = None
- self._lock_cache[candidate] = data
- if data is not None:
- self._lock_seen = True
- return data
- return None
-
- def _prototype_drift_allowances(
- self,
- ) -> Tuple[set[str], set[str], set[str]]:
- """Return color/font/size values owned by the selected mirror page."""
- prototype_root = self._active_prototype_root()
- if prototype_root is None:
- return set(), set(), set()
- try:
- content = self._active_prototype_path.read_text(encoding='utf-8')
- except (AttributeError, OSError):
- return set(), set(), set()
-
- colors: set[str] = set()
- for attribute in _PAINT_PROPERTIES or ():
- for raw_value in self._svg_property_values(content, attribute):
- normalized = raw_value.strip()
- if normalized.lower() in {'none', 'transparent'} or re.fullmatch(
- r'url\(#[^)]+\)', normalized
- ):
- continue
- if _parse_export_color is not None:
- color, _alpha = _parse_export_color(normalized)
- else:
- color = _normalize_hex_rgb(normalized)
- if color:
- colors.add(color)
- fonts = {
- self._normalize_font_stack(value)
- for value in self._font_family_values(content)
- if self._normalize_font_stack(value)
- }
- sizes = set(self._effective_text_size_counts(prototype_root))
- return colors, fonts, sizes
-
- def _declared_typography_size_anchors(
- self,
- lock: Dict,
- ) -> Tuple[Dict, set[str], List[float], List[str]]:
- """Return valid declared size anchors and malformed lock rows."""
- typography = lock.get('typography', {})
- positive_numeric_re = re.compile(
- r'^(?=.*[1-9])(?:[0-9]+(?:\.[0-9]+)?|\.[0-9]+)$'
- )
- locked_sizes: set[str] = set()
- anchor_sizes: List[float] = []
- invalid_sizes: List[str] = []
- for key, raw_value in typography.items():
- if key == 'font_family' or key.endswith('_family'):
- continue
- value = raw_value.strip()
- if positive_numeric_re.fullmatch(value) is None:
- invalid_sizes.append(f"{key}: {raw_value}")
- continue
- try:
- anchor = float(value)
- except (TypeError, ValueError):
- invalid_sizes.append(f"{key}: {raw_value}")
- continue
- if not math.isfinite(anchor) or anchor <= 0:
- invalid_sizes.append(f"{key}: {raw_value}")
- continue
- locked_sizes.add(self._canonical_font_size_key(anchor))
- anchor_sizes.append(anchor)
- return typography, locked_sizes, anchor_sizes, invalid_sizes
-
- def _count_undeclared_size_occurrences(
- self,
- root: ET.Element,
- *,
- locked_sizes: set[str],
- anchor_sizes: List[float],
- prototype_sizes: set[str],
- ) -> Counter[str]:
- """Count text objects using valid sizes outside all declared bands."""
- counts: Counter[str] = Counter()
- if not locked_sizes:
- return counts
- for value, occurrence_count in self._effective_text_size_counts(root).items():
- if value in prototype_sizes and value not in locked_sizes:
- continue
- if value in locked_sizes:
- continue
- try:
- used_px = float(value)
- except (TypeError, ValueError):
- continue
- if not math.isfinite(used_px) or used_px < 0:
- continue
- if any(
- abs(used_px - anchor_px) <= FONT_SIZE_ANCHOR_TOLERANCE_PX
- for anchor_px in anchor_sizes
- ):
- continue
- counts[value] += occurrence_count
- return counts
-
- def _effective_text_size_counts(self, root: ET.Element) -> Counter[str]:
- """Count each effective size once per non-empty SVG text object."""
- counts: Counter[str] = Counter()
- if _resolve_project_font_sizes is None:
- return counts
- working_root = root
- if (
- _expand_local_use_references is not None
- and _UseExpansionError is not None
- ):
- expanded_root = copy.deepcopy(root)
- try:
- _expand_local_use_references(expanded_root)
- except _UseExpansionError:
- pass
- else:
- working_root = expanded_root
- try:
- effective_sizes = _resolve_project_font_sizes(working_root)
- except ValueError:
- return counts
-
- def collect_text_object_sizes(element: ET.Element) -> set[str]:
- values: set[str] = set()
-
- def visit(node: ET.Element) -> None:
- if (node.text or '').strip():
- values.add(
- self._canonical_font_size_key(effective_sizes[id(node)])
- )
- for child in node:
- visit(child)
- if (child.tail or '').strip():
- values.add(
- self._canonical_font_size_key(
- effective_sizes[id(node)]
- )
- )
-
- visit(element)
- return values
-
- definition_containers = {
- 'clippath',
- 'defs',
- 'marker',
- 'mask',
- 'pattern',
- 'symbol',
- }
-
- def visit_visible(element: ET.Element) -> None:
- local_name = _local_name(element).casefold()
- if local_name in definition_containers:
- return
- if local_name == 'text':
- counts.update(collect_text_object_sizes(element))
- return
- for child in element:
- visit_visible(child)
-
- visit_visible(working_root)
- return counts
-
- @staticmethod
- def _canonical_font_size_key(value: float) -> str:
- """Canonicalize equivalent numeric spellings for deck-wide counting."""
- return format(value, '.12g')
-
- def _prepare_undeclared_size_occurrences(
- self,
- svg_files: List[Path],
- ) -> None:
- """Pre-count sparse undeclared sizes before per-file diagnostics."""
- previous_prototype = self._active_prototype_path
- try:
- for svg_path in svg_files:
- lock = self._get_spec_lock(svg_path)
- if lock is None:
- continue
- _typography, locked_sizes, anchor_sizes, _invalid = (
- self._declared_typography_size_anchors(lock)
- )
- self._active_prototype_path = self._prototype_by_output.get(
- svg_path.resolve()
- )
- _colors, _fonts, prototype_sizes = (
- self._prototype_drift_allowances()
- )
- try:
- content = svg_path.read_text(encoding='utf-8')
- except OSError:
- continue
- try:
- root = ET.fromstring(content)
- except ET.ParseError:
- continue
- self._undeclared_size_occurrences.update(
- self._count_undeclared_size_occurrences(
- root,
- locked_sizes=locked_sizes,
- anchor_sizes=anchor_sizes,
- prototype_sizes=prototype_sizes,
- )
- )
- finally:
- self._active_prototype_path = previous_prototype
- self._undeclared_size_counts_ready = True
-
- def _check_spec_lock_alignment(
- self,
- content: str,
- svg_path: Path,
- result: Dict,
- *,
- root: ET.Element,
- ):
- """Compare SVG values with reusable anchors in spec_lock.md.
-
- Covers colors (fill / stroke / stop-color / flood-color / pattern
- metadata), font-family, and font-size.
- Additional colors and font families are valid contextual authoring and
- are recorded as information. A valid undeclared display size may occur
- at most twice across generated pages; its third occurrence makes it a
- recurring role and blocks ``svg_output`` until the role is declared.
- Structural text still maps to declared role bands. Exact mirror-
- prototype values remain inherited information. Exact values are
- accumulated in self._anchor_value_summary for end-of-run aggregation.
- When spec_lock.md is missing, silently skip this local comparison; the
- Generate route's required-artifact gate owns whether execution may begin.
- """
- lock = self._get_spec_lock(svg_path)
- if lock is None:
- return
- prototype_colors, prototype_fonts, prototype_sizes = (
- self._prototype_drift_allowances()
- )
-
- # Build allow-sets from the lock
- allowed_colors = set()
- for v in lock.get('colors', {}).values():
- if _parse_export_color is not None:
- color, _alpha = _parse_export_color(v)
- if color:
- allowed_colors.add(color)
- else:
- color = _normalize_hex_rgb(v)
- if color:
- allowed_colors.add(color)
-
- # A validated compact preset may contain registry-derived darken/lighten
- # layer colors. Their base paint still comes from spec_lock; the exact
- # child HEX values are deterministic compiler evidence, not color drift.
- if (
- _authored_preset_encoding is not None
- and _validate_authored_preset_group is not None
- ):
- for group in root.iter():
- if (
- _authored_preset_encoding(group) != 'compact'
- or _validate_authored_preset_group(group)
- ):
- continue
- for child in group:
- for attribute in ('fill', 'stroke'):
- raw_value = child.get(attribute)
- if raw_value is None:
- continue
- if _parse_export_color is not None:
- color, _alpha = _parse_export_color(raw_value)
- else:
- color = _normalize_hex_rgb(raw_value)
- if color:
- allowed_colors.add(color)
- locked_colors = set(allowed_colors)
- allowed_colors.update(prototype_colors)
-
- typo, locked_sizes, anchor_sizes, invalid_lock_sizes = (
- self._declared_typography_size_anchors(lock)
- )
- if invalid_lock_sizes:
- shown = ', '.join(invalid_lock_sizes[:5])
- more = len(invalid_lock_sizes) - 5
- suffix = f" (+{more} more)" if more > 0 else ""
- result['errors'].append(
- f"spec_lock typography sizes must be positive finite unitless px values; "
- f"found {shown}{suffix}."
- )
-
- # Font families: default `font_family` plus any per-role `*_family`
- # override (title_family / body_family / emphasis_family / code_family,
- # per templates/schemas/spec_lock.schema.json). Any of these is a legitimate declared
- # value; an SVG that uses any one of them is not drifting.
- allowed_fonts = set()
- if typo:
- default_font = typo.get('font_family', '').strip()
- if default_font:
- allowed_fonts.add(self._normalize_font_stack(default_font))
- for k, v in typo.items():
- if k == 'font_family' or not k.endswith('_family'):
- continue
- v_clean = v.strip()
- # Skip placeholder text like "same as body (omit if identical)"
- if not v_clean or v_clean.lower().startswith('same as'):
- continue
- allowed_fonts.add(self._normalize_font_stack(v_clean))
- locked_fonts = set(allowed_fonts)
- allowed_fonts.update(prototype_fonts)
-
- # Sizes: declared slots are anchors. Checker cannot infer which role a
- # text node carries, so it uses the union of their ±2px bands as a cheap
- # numeric safety net; prompt rules own semantic role mapping.
- # Scan SVG for used values
- color_drifts = set()
- inherited_colors = set()
- for attr in _PAINT_PROPERTIES or ():
- for raw_value in self._svg_property_values(content, attr):
- normalized = raw_value.strip()
- if normalized.lower() in {'none', 'transparent'} or re.fullmatch(
- r'url\(#[^)]+\)', normalized
- ):
- continue
- if _BARE_HEX_VALUE_RE.fullmatch(normalized):
- continue
- if _parse_export_color is not None:
- val, _alpha = _parse_export_color(normalized)
- if val is None:
- continue
- else:
- val = _normalize_hex_rgb(normalized)
- if val is None:
- continue
- if val not in allowed_colors:
- color_drifts.add(f'#{val}')
- elif val in prototype_colors and val not in locked_colors:
- inherited_colors.add(f'#{val}')
-
- font_drifts = set()
- inherited_fonts = set()
- for val in self._font_family_values(content):
- normalized_font = self._normalize_font_stack(val)
- if allowed_fonts and normalized_font not in allowed_fonts:
- font_drifts.add(val)
- elif (
- normalized_font in prototype_fonts
- and normalized_font not in locked_fonts
- ):
- inherited_fonts.add(val)
-
- size_drift_counts = self._count_undeclared_size_occurrences(
- root,
- locked_sizes=locked_sizes,
- anchor_sizes=anchor_sizes,
- prototype_sizes=prototype_sizes,
- )
- size_drifts = set(size_drift_counts)
- inherited_sizes = set()
- for val in self._effective_text_size_counts(root):
- if val in prototype_sizes and val not in locked_sizes:
- inherited_sizes.add(val)
-
- # Record in run-wide aggregation. Colors/fonts beyond the anchor set are
- # contextual values, not release issues. Generated-page sizes enforce
- # role-anchor ownership; other spec-backed locations retain review.
- fname = svg_path.name
- for v in color_drifts:
- self._anchor_value_summary['colors'][v].add(fname)
- for v in font_drifts:
- self._anchor_value_summary['fonts'][v].add(fname)
- for v in size_drifts:
- self._anchor_value_summary['sizes'][v].add(fname)
-
- contextual_values = {}
- if color_drifts:
- contextual_values['colors'] = sorted(color_drifts)
- if font_drifts:
- contextual_values['font_families'] = sorted(font_drifts)
- if contextual_values:
- result['info']['contextual_values'] = contextual_values
-
- sparse_sizes = {}
- recurring_sizes = {}
- for value, local_count in size_drift_counts.items():
- total_count = (
- self._undeclared_size_occurrences.get(value, local_count)
- if self._undeclared_size_counts_ready
- else local_count
- )
- target = (
- sparse_sizes
- if total_count <= SPARSE_UNDECLARED_FONT_SIZE_MAX_OCCURRENCES
- else recurring_sizes
- )
- target[value] = total_count
-
- if sparse_sizes:
- result['info']['sparse_typography_sizes'] = {
- value: count for value, count in sorted(sparse_sizes.items())
- }
-
- if recurring_sizes:
- shown = ', '.join(
- f"{value} ({count} occurrences)"
- for value, count in sorted(recurring_sizes.items())
- )
- size_issue = (
- f"undeclared font-size {shown} exceeds the sparse-display limit "
- f"of {SPARSE_UNDECLARED_FONT_SIZE_MAX_OCCURRENCES} occurrences"
- )
- if svg_path.parent.name == 'svg_output':
- result['errors'].append(
- "spec_lock typography-size recurrence: "
- f"{size_issue}. Structural text must return to its declared "
- "role band; a genuinely recurring display treatment needs a "
- "justified named role in the Design Spec and spec_lock."
- )
- else:
- result['warnings'].append(
- f"spec_lock typography-size recurrence review: {size_issue}"
- )
- inherited_parts = []
- if inherited_colors:
- inherited_parts.append(f"{len(inherited_colors)} color(s)")
- if inherited_fonts:
- inherited_parts.append(f"{len(inherited_fonts)} font-family value(s)")
- if inherited_sizes:
- inherited_parts.append(f"{len(inherited_sizes)} font-size value(s)")
- if inherited_parts:
- self._append_inherited_info(
- result,
- 'spec_lock_alignment',
- f"{', '.join(inherited_parts)} come unchanged from mirror "
- "prototype and are accepted without expanding spec_lock.md",
- )
-
- def _find_image_sources_manifest(self, svg_path: Path) -> Path | None:
- """Locate image_sources.json for a project SVG.
-
- Quality checks run primarily on <project>/svg_output/*.svg, but this
- also supports SVGs checked from project root or svg_final.
- """
- bases = (svg_path.parent, svg_path.parent.parent, svg_path.parent.parent.parent)
- for base in bases:
- candidate = base / 'images' / 'image_sources.json'
- if candidate.exists():
- return candidate
- return None
-
- def _load_image_sources_manifest(
- self,
- svg_path: Path,
- ) -> Tuple[Dict, str | None, Path | None]:
- manifest_path = self._find_image_sources_manifest(svg_path)
- if manifest_path is None:
- return {}, None, None
- payload, error = self._read_image_sources_manifest(manifest_path)
- return payload, error, manifest_path
-
- def _read_image_sources_manifest(
- self,
- manifest_path: Path,
- ) -> Tuple[Dict, str | None]:
- """Read one provenance manifest without accepting damaged state."""
- if manifest_path in self._source_manifest_cache:
- return self._source_manifest_cache[manifest_path]
- try:
- payload = json.loads(manifest_path.read_text(encoding='utf-8'))
- except (OSError, json.JSONDecodeError) as exc:
- payload = {}
- error = f"cannot read {manifest_path}: {exc}"
- else:
- if not isinstance(payload, dict):
- error = f"{manifest_path} must contain a JSON object"
- payload = {}
- elif not isinstance(payload.get('items'), list):
- error = f"{manifest_path} must contain an items array"
- payload = {}
- elif any(not isinstance(item, dict) for item in payload['items']):
- error = f"{manifest_path} items must contain JSON objects"
- payload = {}
- else:
- seen_filenames: set[str] = set()
- error = None
- for index, item in enumerate(payload['items']):
- filename = item.get('filename')
- if (
- not isinstance(filename, str)
- or not filename.strip()
- or filename in {'.', '..'}
- or '/' in filename
- or '\\' in filename
- or ':' in filename
- or Path(filename).is_absolute()
- ):
- error = (
- f"{manifest_path} items[{index}].filename must be "
- "a non-empty bare filename"
- )
- break
- if filename in seen_filenames:
- error = (
- f"{manifest_path} contains duplicate filename "
- f"{filename!r}"
- )
- break
- seen_filenames.add(filename)
- if error:
- payload = {}
- self._source_manifest_cache[manifest_path] = (payload, error)
- return payload, error
-
- @staticmethod
- def _external_image_reference_basename(href: str) -> str | None:
- """Return a decoded basename for one local external image href."""
- if not href or href.startswith('data:'):
- return None
- decoded_href = html.unescape(href)
- parsed = urlsplit(decoded_href)
- if parsed.scheme and parsed.scheme != 'file':
- return None
- path_part = (
- parsed.path
- if parsed.scheme
- else decoded_href.split('?', 1)[0].split('#', 1)[0]
- )
- return Path(unquote(path_part)).name or None
-
- @classmethod
- def _referenced_image_basenames(cls, root: ET.Element) -> set[str]:
- """Return external image basenames rendered by one parsed SVG."""
- filenames = set()
- _working_root, _parent_by_id, images = cls._visible_image_elements(root)
- for elem in images:
- href = elem.get('href') or elem.get(f'{{{XLINK_NS}}}href')
- filename = cls._external_image_reference_basename(href or '')
- if filename:
- filenames.add(filename)
- return filenames
-
- def _check_sourced_image_attribution(
- self,
- root: ET.Element,
- svg_path: Path,
- result: Dict,
- ):
- """Require visible credit text for attribution-required web images.
-
- image_search.py records the legal tier in images/image_sources.json;
- Executor must render compact credit text into the SVG. This check
- binds each credit to the referenced image's author and license instead
- of accepting one generic deck-level CC token.
- """
- manifest, error, manifest_path = self._load_image_sources_manifest(svg_path)
- if error:
- if (
- manifest_path is not None
- and manifest_path not in self._source_manifest_errors_reported
- ):
- result['errors'].append(
- f"Invalid image source manifest: {error}"
- )
- self._source_manifest_errors_reported.add(manifest_path)
- return
-
- items = manifest.get('items') or []
- if not items:
- return
-
- credit_blocks = self._visible_svg_text_blocks(root)
- referenced_filenames = self._referenced_image_basenames(root)
-
- for item in items:
- if not item.get('attribution_required') and item.get('license_tier') != 'attribution-required':
- continue
-
- filename = str(item.get('filename') or '')
- if not filename or filename not in referenced_filenames:
- continue
-
- license_name = str(item.get('license_name') or '').upper()
- license_token = 'CC BY-SA' if 'BY-SA' in license_name else 'CC BY'
- author = str(item.get('author') or '').strip()
- has_credit = bool(author) and any(
- author.casefold() in block.casefold()
- and license_token in block.upper()
- for block in credit_blocks
- )
- if not has_credit:
- result['errors'].append(
- f"Missing image-specific inline attribution for sourced "
- f"image {filename} ({author or 'unknown author'}; "
- f"{license_token}). Add compact author + license credit per "
- f"references/image-searcher.md §7."
- )
-
- @classmethod
- def _visible_svg_text_blocks(cls, root: ET.Element) -> List[str]:
- """Return rendered text blocks, excluding hidden/non-visual content."""
- working_root = copy.deepcopy(root)
- if (
- _expand_local_use_references is not None
- and _UseExpansionError is not None
- ):
- try:
- _expand_local_use_references(working_root)
- except _UseExpansionError:
- working_root = copy.deepcopy(root)
- parent_by_id = {
- id(child): parent
- for parent in working_root.iter()
- for child in list(parent)
- }
-
- blocks: List[str] = []
- for element in working_root.iter(f'{{{SVG_NS}}}text'):
- if (
- cls._is_hidden_element(element, parent_by_id)
- or cls._has_non_visual_ancestor(
- element,
- working_root,
- parent_by_id,
- )
- or cls._has_zero_opacity(element, parent_by_id)
- ):
- continue
- text = re.sub(r'\s+', ' ', ' '.join(element.itertext())).strip()
- if text:
- blocks.append(text)
- return blocks
-
- @staticmethod
- def _normalize_size(value: str) -> str:
- """Normalize a font-size value for drift comparison.
-
- Unit-bearing SVG values are reported as errors before drift checking.
- The legacy `px` strip remains to avoid a duplicate drift warning after
- the hard error has already identified the unit problem.
- """
- v = value.strip().lower()
- if v.endswith('px'):
- v = v[:-2].strip()
- return v
-
- @staticmethod
- def _normalize_font_stack(stack: str) -> str:
- """Normalize a font-family stack for comparison: split on commas, strip
- quotes / whitespace, lowercase, rejoin. Collapses cosmetic differences
- (comma spacing, single vs double quotes, case) so that
- `Consolas,'Courier New',monospace` matches `Consolas, "Courier New", monospace`."""
- parts = [p.strip().strip('"\'').lower() for p in stack.split(',')]
- return ','.join(p for p in parts if p)
-
- def _categorize_issue(self, error_msg: str) -> str:
- """Categorize issue type"""
- if 'Invalid XML' in error_msg:
- return 'XML well-formedness'
- elif 'viewBox' in error_msg:
- return 'viewBox issues'
- elif 'foreignObject' in error_msg:
- return 'foreignObject'
- elif 'paint' in error_msg.lower() or 'color value' in error_msg.lower():
- return 'Paint issues'
- elif 'font' in error_msg.lower():
- return 'Font issues'
- else:
- return 'Other'
-
- def _configure_prototype_context(
- self,
- target_path: Path,
- svg_files: List[Path],
- ) -> None:
- """Map generated pages to selected prototypes for inherited diagnostics."""
- self._prototype_by_output = {}
- self._active_prototype_path = None
- self._active_template_reuse_scope = None
- self._source_import_summary = {
- 'warning_count': 0,
- 'by_code': {},
- }
- if (
- self.template_mode
- or self.quick_generate
- or _load_pptx_structure_lock is None
- ):
- return
- project_path = self._resolve_project_path(target_path)
- try:
- structure_lock = _load_pptx_structure_lock(project_path)
- except (_TemplateStructureError, OSError):
- # The project-level structure gate reports the actionable parser
- # error. Inherited classification is optional and stays silent.
- return
- if structure_lock is None:
- return
- self._active_template_reuse_scope = getattr(
- structure_lock,
- 'template_reuse_scope',
- None,
- )
- references = {
- reference.slide_num: reference.svg_path
- for reference in structure_lock.prototypes
- }
- if target_path.is_file():
- sibling_files = discover_slide_svgs(target_path.parent)
- resolved_target = target_path.resolve()
- slide_num = next(
- (
- index
- for index, sibling in enumerate(sibling_files, start=1)
- if sibling.resolve() == resolved_target
- ),
- 1,
- )
- prototype = references.get(slide_num)
- if prototype is not None:
- self._prototype_by_output[resolved_target] = prototype.resolve()
- else:
- for slide_num, svg_path in enumerate(svg_files, start=1):
- prototype = references.get(slide_num)
- if prototype is not None:
- self._prototype_by_output[svg_path.resolve()] = prototype.resolve()
-
- if self._active_template_reuse_scope not in {'mirror', 'layout'}:
- return
- manifest_path = (
- project_path / 'templates' / 'template_execution_manifest.json'
- )
- try:
- manifest = json.loads(manifest_path.read_text(encoding='utf-8'))
- except (FileNotFoundError, OSError, json.JSONDecodeError):
- return
- if manifest.get('schema') != 'ppt-master.template-execution-manifest.v1':
- return
- source_import = manifest.get('source_import')
- if isinstance(source_import, dict):
- self._source_import_summary = source_import
-
- def check_directory(self, directory: str, expected_format: str = None) -> List[Dict]:
- """
- Check all SVG files in a directory
-
- Args:
- directory: Directory path
- expected_format: Expected canvas format
-
- Returns:
- List of check results
- """
- dir_path = Path(directory)
- self._has_incomplete_page_roster = False
- self._undeclared_size_occurrences = Counter()
- self._undeclared_size_counts_ready = False
-
- if not dir_path.exists():
- print(f"[ERROR] Directory does not exist: {directory}")
- self.summary['errors'] += 1
- self.issue_types['Input issues'] += 1
- return []
-
- # Brand-only workspaces have no SVG roster. Validate their portable
- # identity schema through the same authority used by library
- # registration, while keeping project scope independent of global
- # indexes and directory names.
- if self.template_mode and dir_path.is_dir():
- nested_spec = dir_path / 'templates' / 'design_spec.md'
- spec = nested_spec if nested_spec.is_file() else dir_path / 'design_spec.md'
- if spec.exists() and _design_spec_is_brand(spec):
- self._brand_template_checked = True
- self.summary['total'] += 1
- brand_valid = True
- print(
- f"[INFO] Brand directory detected (kind: brand) — "
- f"validating design_spec.md and referenced assets."
- )
- workspace_root = (
- spec.parent.parent
- if spec.parent.name == 'templates'
- else spec.parent
- )
- try:
- from register_template import (
- SpecParseError,
- validate_brand_workspace,
- )
- validate_brand_workspace(workspace_root)
- except ImportError as exc:
- brand_valid = False
- self._template_issues.append((
- 'error',
- 'brand_contract',
- f"Brand schema validator could not be imported: {exc}",
- ))
- except (OSError, SpecParseError) as exc:
- brand_valid = False
- self._template_issues.append((
- 'error',
- 'brand_contract',
- str(exc),
- ))
- if brand_valid:
- self.summary['passed'] += 1
- return self.results
-
- # Find all SVG files
- if dir_path.is_file():
- svg_files = [dir_path]
- else:
- if self.template_mode:
- # Template directories live at templates/{layouts,decks}/<id>/.
- svg_files = discover_slide_svgs(dir_path)
- else:
- svg_output = dir_path / \
- 'svg_output' if (
- dir_path / 'svg_output').exists() else dir_path
- svg_files = discover_slide_svgs(svg_output)
-
- if not svg_files:
- print(f"[ERROR] No SVG files found in: {directory}")
- self.summary['errors'] += 1
- self.issue_types['Input issues'] += 1
- return []
-
- self._configure_prototype_context(dir_path, svg_files)
- if not self.template_mode:
- self._prepare_undeclared_size_occurrences(svg_files)
-
- directory_expected_viewbox: str | None = None
- directory_expected_label = "the first SVG canvas"
- directory_lock_has_canvas = False
- if self.template_mode:
- template_viewbox = _declared_template_canvas_viewbox(dir_path)
- if template_viewbox:
- directory_expected_viewbox = template_viewbox
- directory_expected_label = "design_spec canvas_viewbox"
- else:
- directory_expected_viewbox = ""
- directory_expected_label = "design_spec canvas_viewbox"
- if expected_format is None and directory_expected_viewbox is None:
- lock = (
- None
- if self.template_mode
- else self._get_spec_lock(svg_files[0])
- )
- if lock is not None:
- if 'canvas' in lock:
- directory_lock_has_canvas = True
- locked_viewbox = lock.get('canvas', {}).get('viewBox')
- if locked_viewbox:
- directory_expected_viewbox = locked_viewbox
- directory_expected_label = "spec_lock canvas"
- else:
- directory_expected_viewbox = ""
- directory_expected_label = "spec_lock canvas"
- if (
- directory_expected_viewbox is None
- and not directory_lock_has_canvas
- ):
- for svg_file in svg_files:
- try:
- root = ET.parse(svg_file).getroot()
- first_canvas = parse_project_viewbox(
- root.get('viewBox'),
- context=f"{svg_file.name} root viewBox",
- )
- except (OSError, ET.ParseError, CanvasContractError):
- continue
- directory_expected_viewbox = first_canvas.canonical
- directory_expected_label = f"first SVG {svg_file.name}"
- break
-
- print(f"\n[SCAN] Checking {len(svg_files)} SVG file(s)...\n")
-
- for svg_file in svg_files:
- self._active_prototype_path = self._prototype_by_output.get(
- svg_file.resolve()
- )
- result = self.check_file(
- str(svg_file),
- expected_format,
- expected_viewbox=directory_expected_viewbox,
- expected_viewbox_label=directory_expected_label,
- )
- self._print_result(result)
-
- if self.template_mode:
- check_structure = _template_structure_checks_enabled(dir_path)
- if check_structure:
- self._check_pptx_structure_contract(dir_path, svg_files)
- if dir_path.is_dir():
- self._check_template_contract(
- dir_path,
- svg_files,
- check_structure=check_structure,
- )
- elif _CHECK_PPTX_STRUCTURED_PROJECT:
- self._check_pptx_structure_contract(dir_path, svg_files)
- if (
- not self.template_mode
- and not self.quick_generate
- and dir_path.is_dir()
- ):
- self._check_animation_config_contract(dir_path)
- self._check_illustration_resource_contract(dir_path)
- if (
- not self.template_mode
- and not self.quick_generate
- and validate_communication_trace is not None
- ):
- project_path = self._resolve_project_path(dir_path)
- self._communication_trace_issues.extend(
- ('error', message)
- for message in validate_communication_trace(project_path)
- )
-
- return self.results
-
- def _check_pptx_structure_contract(
- self,
- target_path: Path,
- svg_files: List[Path],
- ) -> None:
- """Validate the all-page structured lock and reusable contracts."""
- if self.quick_generate:
- return
- project_path = self._resolve_project_path(target_path)
- standard_project = bool(
- not self.template_mode
- and (project_path / 'svg_output').is_dir()
- )
- declared_mode = (
- _declared_pptx_structure_mode(project_path)
- if standard_project
- else None
- )
- if standard_project and declared_mode in {'flat', 'structured'}:
- self._pptx_structure_issues.extend(
- ('error', message)
- for message in _generated_theme_contract_errors(project_path)
- )
- if standard_project and declared_mode == 'flat':
- if (
- _load_pptx_structure_lock is None
- or _TemplateStructureError is None
- ):
- self._pptx_structure_issues.append((
- 'error',
- 'Flat PPTX project validation is unavailable because the '
- 'template_structure module could not be imported.',
- ))
- return
- try:
- structure_lock = _load_pptx_structure_lock(project_path)
- except _TemplateStructureError as exc:
- self._pptx_structure_issues.append(('error', str(exc)))
- return
- if structure_lock is None or structure_lock.mode != 'flat':
- self._pptx_structure_issues.append((
- 'error',
- 'spec_lock.md must contain one complete '
- 'pptx_structure.mode: flat contract.',
- ))
- return
- has_metadata = False
- for svg_path in svg_files:
- try:
- root = ET.parse(svg_path).getroot()
- except (OSError, ET.ParseError):
- continue
- if any(
- elem.get(attr) is not None
- for elem in root.iter()
- for attr in _PPTX_STRUCTURE_ATTRS
- ):
- has_metadata = True
- break
-
- if not standard_project and not self.template_mode and not has_metadata:
- return
- if (
- _load_pptx_structure_lock is None
- or _parse_template_structure_slide is None
- or _parse_template_structure_slides is None
- or _structure_subtree_signature is None
- or _template_lock_errors is None
- or _TemplateStructureError is None
- ):
- self._pptx_structure_issues.append((
- 'error',
- 'Structured PPTX project validation is unavailable because the '
- 'template_structure module could not be imported.',
- ))
- return
-
- if self.template_mode:
- try:
- specs = _parse_template_structure_slides(svg_files)
- except _TemplateStructureError as exc:
- self._pptx_structure_issues.append(('error', str(exc)))
- return
- self._pptx_structure_issues.extend(
- ('error', message)
- for message in self._shared_fixed_layer_errors(specs)
- )
- self._pptx_structure_issues.extend(
- ('warning', message)
- for message in self._duplicate_layout_key_warnings(specs)
- )
- return
-
- if standard_project and declared_mode != 'structured':
- label = repr(declared_mode) if declared_mode else (
- 'missing (legacy implicit baseline)'
- )
- self._pptx_structure_issues.append((
- 'error',
- 'release SVG projects require an explicit spec_lock.md '
- 'pptx_structure.mode: flat (free design / brand-only) or '
- f'structured (deck/layout template); found {label}. New '
- 'free-design projects use mode: flat; create a new template '
- 'workspace through skills/ppt-master/workflows/create-template.md, '
- 'then generate new structured SVG pages before export. Existing '
- 'PPTX/SVG files are not upgraded in place.',
- ))
- return
-
- try:
- structure_lock = _load_pptx_structure_lock(project_path)
- except _TemplateStructureError as exc:
- self._pptx_structure_issues.append(('error', str(exc)))
- return
- if structure_lock is None or structure_lock.mode != 'structured':
- self._pptx_structure_issues.append((
- 'error',
- 'spec_lock.md must contain one complete '
- 'pptx_structure.mode: structured contract.',
- ))
- return
- complete_roster = target_path.is_dir()
- try:
- if not complete_roster and target_path.is_file():
- sibling_files = discover_slide_svgs(target_path.parent)
- resolved_target = target_path.resolve()
- slide_num = next(
- (
- index
- for index, sibling in enumerate(sibling_files, start=1)
- if sibling.resolve() == resolved_target
- ),
- 1,
- )
- specs = [
- _parse_template_structure_slide(target_path, slide_num)
- ]
- else:
- specs = _parse_template_structure_slides(svg_files)
- except _TemplateStructureError as exc:
- self._pptx_structure_issues.append(('error', str(exc)))
- return
-
- if complete_roster:
- actual_slides = {spec.slide_num for spec in specs}
- expected_slides = {
- reference.slide_num
- for reference in structure_lock.layouts
- }
- expected_slides.update(
- reference.slide_num
- for reference in structure_lock.prototypes
- )
- self._has_incomplete_page_roster = bool(
- expected_slides - actual_slides
- )
- self._pptx_structure_issues.extend(
- ('error', message)
- for message in _template_lock_errors(specs, structure_lock)
- )
- else:
- self._pptx_structure_issues.extend(
- ('error', message)
- for message in self._partial_structure_lock_errors(
- specs,
- structure_lock,
- )
- )
- if _template_prototype_errors is not None:
- self._pptx_structure_issues.extend(
- ('error', message)
- for message in _template_prototype_errors(
- specs,
- structure_lock,
- require_complete_roster=complete_roster,
- )
- )
- self._pptx_structure_issues.extend(
- ('error', message)
- for message in self._shared_fixed_layer_errors(specs)
- )
- self._pptx_structure_issues.extend(
- ('warning', message)
- for message in self._duplicate_layout_key_warnings(specs)
- )
-
- @staticmethod
- def _partial_structure_lock_errors(specs, structure_lock) -> List[str]:
- """Compare explicitly checked pages without requiring the full roster."""
- references = {
- reference.slide_num: reference
- for reference in structure_lock.layouts
- }
- master_names = {
- master.master_key: master.master_name
- for master in structure_lock.masters
- }
- definitions = {
- definition.layout_key: definition
- for definition in structure_lock.layout_definitions
- }
- errors: List[str] = []
- for spec in specs:
- page = f"P{spec.slide_num:02d}"
- reference = references.get(spec.slide_num)
- if reference is None:
- errors.append(
- f"spec_lock.md page_pptx_layouts is missing {page}"
- )
- continue
- definition = definitions.get(reference.layout_key)
- if definition is None:
- errors.append(
- f"spec_lock.md pptx_layouts is missing Layout "
- f"{reference.layout_key!r}"
- )
- continue
- if spec.master_key != definition.master_key:
- errors.append(
- f"{spec.svg_path.name}: data-pptx-master={spec.master_key!r} "
- f"does not match spec_lock Layout {reference.layout_key!r} "
- f"Master key {definition.master_key!r}"
- )
- if spec.layout_key != reference.layout_key:
- errors.append(
- f"{spec.svg_path.name}: data-pptx-layout={spec.layout_key!r} "
- f"does not match spec_lock {page} layout key "
- f"{reference.layout_key!r}"
- )
- if spec.layout_name != definition.layout_name:
- errors.append(
- f"{spec.svg_path.name}: data-pptx-layout-name="
- f"{spec.layout_name!r} does not match spec_lock Layout "
- f"{reference.layout_key!r} name {definition.layout_name!r}"
- )
- expected_master_name = master_names.get(spec.master_key)
- if expected_master_name != spec.master_name:
- errors.append(
- f"{spec.svg_path.name}: data-pptx-master-name="
- f"{spec.master_name!r} does not match spec_lock Master "
- f"{spec.master_key!r} name {expected_master_name!r}"
- )
- return errors
-
- def _duplicate_layout_key_warnings(self, specs) -> List[str]:
- """Flag distinct layout keys whose static contracts are identical.
-
- Keys split by page topic over one shared skeleton compile into
- duplicate PowerPoint Layouts; the fingerprint compares the
- id-insensitive layout-layer drawing plus the placeholder contract.
- """
- prototypes: Dict[Tuple[str, str], Path] = {}
- for spec in specs:
- prototypes.setdefault(
- (getattr(spec, 'master_key', ''), spec.layout_key),
- spec.svg_path,
- )
- if len(prototypes) < 2:
- return []
- fingerprint_keys: Dict[tuple, List[str]] = {}
- for (master_key, layout_key), svg_path in prototypes.items():
- fingerprint = self._layout_contract_fingerprint(svg_path)
- if fingerprint is None:
- continue
- fingerprint_keys.setdefault(
- (master_key, fingerprint),
- [],
- ).append(layout_key)
- messages = []
- for keys in fingerprint_keys.values():
- if len(keys) < 2:
- continue
- joined = ', '.join(sorted(keys))
- messages.append(
- f"layout keys {joined} declare identical static Layout framing "
- "and placeholder contracts; they compile to duplicate Layouts. "
- "Either merge them into one reusable key (spec_lock.md "
- "pptx_layouts + each SVG root), or — when their reusable "
- "contracts genuinely differ — assign distinct explicit default "
- "placeholder bounds and/or mark only truly stable framing as "
- 'data-pptx-layer="layout". Slide-local content geometry does not '
- "define a Layout. This recommendation is advisory; no change or "
- "disposition is required."
- )
- return messages
-
- @classmethod
- def _shared_fixed_layer_errors(cls, specs) -> List[str]:
- """Reject fixed atoms whose payload varies inside one reuse scope."""
- master_groups = defaultdict(list)
- layout_groups = defaultdict(list)
- for spec in specs:
- master_groups[spec.master_key].append(spec)
- layout_groups[(spec.master_key, spec.layout_key)].append(spec)
-
- try:
- errors = cls._fixed_layer_group_errors(master_groups, 'master')
- errors.extend(cls._fixed_layer_group_errors(layout_groups, 'layout'))
- except _TemplateStructureError as exc:
- return [str(exc)]
- return errors
-
- @classmethod
- def _fixed_layer_group_errors(cls, groups, layer: str) -> List[str]:
- """Compare fixed atom payloads across grouped slide specifications."""
- errors = []
- for scope_key, group_specs in groups.items():
- if len(group_specs) < 2:
- continue
- variants = defaultdict(lambda: defaultdict(list))
- for spec in group_specs:
- payloads = cls._fixed_layer_payloads(spec, layer)
- for element_id, payload in payloads.items():
- variants[element_id][payload].append(spec)
- for element_id, payload_specs in variants.items():
- if len(payload_specs) < 2:
- continue
- slide_names = ', '.join(
- spec.svg_path.name
- for spec in sorted(group_specs, key=lambda item: item.slide_num)
- )
- if layer == 'master':
- scope = f"Master {scope_key!r}"
- else:
- master_key, layout_key = scope_key
- scope = (
- f"Layout {layout_key!r} under Master {master_key!r}"
- )
- if element_id is None:
- subject = "fixed visual resources"
- verb = "differ"
- else:
- subject = f"fixed element {element_id!r}"
- verb = "differs"
- errors.append(
- f"{scope} {subject} {verb} across slides: "
- f"{slide_names}. Values marked data-pptx-layer={layer!r} must "
- "remain identical throughout their reuse scope; move variable "
- "text or images into a placeholder slot or keep them Slide-local."
- )
- return errors
-
- @staticmethod
- def _fixed_layer_payloads(spec, layer: str) -> Dict[object, tuple]:
- """Return resolved fixed-layer visual payloads keyed by SVG id."""
- elements = (
- spec.master_elements if layer == 'master' else spec.layout_elements
- )
- if not elements:
- return {}
- signature = _structure_subtree_signature(
- spec.svg_path,
- elements,
- include_skin=True,
- include_text=True,
- asset_identity=True,
- )
- return {
- None if element_id == '__visual_resources__' else element_id: payload
- for element_id, payload in signature
- }
-
- @staticmethod
- def _layout_contract_fingerprint(svg_path: Path):
- """Id-insensitive static contract: layout-layer XML + placeholder slots."""
- try:
- root = ET.parse(str(svg_path)).getroot()
- except (OSError, ET.ParseError):
- return None
- layout_parts = []
- placeholder_parts = []
- for child in list(root):
- if child.get('data-pptx-layer') == 'layout':
- clone = copy.deepcopy(child)
- for elem in clone.iter():
- elem.attrib.pop('id', None)
- xml = ET.tostring(clone, encoding='unicode')
- layout_parts.append(re.sub(r'\s+', ' ', xml).strip())
- placeholder = child.get('data-pptx-placeholder')
- if placeholder is not None:
- carrier_tags = tuple(
- grandchild.tag.rsplit('}', 1)[-1]
- for grandchild in list(child)
- if (
- grandchild.get('data-pptx-carrier') or ''
- ).strip().lower() == 'true'
- )
- placeholder_parts.append((
- placeholder,
- child.tag.rsplit('}', 1)[-1],
- child.get('data-pptx-bounds') or '',
- child.get('data-pptx-idx') or '',
- (
- child.get('data-pptx-binding') or 'carrier'
- ).strip().lower(),
- carrier_tags,
- ))
- return (
- tuple(layout_parts),
- tuple(sorted(placeholder_parts)),
- )
-
- def _check_illustration_resource_contract(self, dir_path: Path) -> None:
- """Project-level planned-image and illustration resource checks."""
- project_path = self._resolve_project_path(dir_path)
- spec_path = project_path / 'design_spec.md'
- if not spec_path.exists():
- return
-
- try:
- spec_text = spec_path.read_text(encoding='utf-8')
- except OSError as exc:
- self._illustration_issues.append((
- 'warning',
- 'spec_unreadable',
- f"could not read {spec_path}: {exc}",
- ))
- return
-
- current_contract = (
- '<!-- ppt-master-schema: design-spec/v1 -->' in spec_text
- )
- rows = self._extract_image_resource_rows(spec_text)
- if not rows and not current_contract:
- return
-
- lock_entries, lock_error = self._load_project_lock_image_entries(
- project_path
- )
- lock_images = set(lock_entries)
- svg_references, inline_image_counts, image_placements = (
- self._load_project_svg_image_references(project_path)
- )
- all_svg_references = (
- set().union(*(
- set(references)
- for references in svg_references.values()
- ))
- if svg_references
- else set()
- )
-
- sheet_rows = [
- row
- for row in rows
- if self._row_type(row).lower() == 'illustration sheet'
- ]
- slice_rows = [row for row in rows if self._row_acquire(row) == 'slice']
- for row in sheet_rows:
- filename = self._row_filename(row)
- if not filename:
- continue
- if filename in lock_images:
- self._illustration_issues.append((
- 'error',
- 'sheet_in_lock',
- f"{filename} is an Illustration Sheet but is listed in spec_lock.md images; "
- "only sliced element rows may be listed.",
- ))
- if filename in all_svg_references:
- self._illustration_issues.append((
- 'error',
- 'sheet_referenced',
- f"{filename} is an Illustration Sheet but is referenced by an SVG; "
- "generate it only as a slice source, never place it.",
- ))
- if (
- self._row_status(row) == 'generated'
- and not (project_path / 'images' / filename).is_file()
- ):
- self._illustration_issues.append((
- 'error',
- 'sheet_file_missing',
- f"{filename} is a Generated Illustration Sheet but "
- f"images/{filename} does not exist.",
- ))
-
- if current_contract:
- self._check_planned_image_closure(
- rows,
- project_path,
- lock_entries,
- lock_error,
- svg_references,
- inline_image_counts,
- image_placements,
- )
- else:
- for row in slice_rows:
- filename = self._row_filename(row)
- if not filename:
- continue
- if filename not in lock_images:
- self._illustration_issues.append((
- 'error',
- 'slice_missing_lock',
- f"{filename} is a slice row but is absent from spec_lock.md images.",
- ))
- if (
- self._row_status(row) == 'generated'
- and not (project_path / 'images' / filename).exists()
- ):
- self._illustration_issues.append((
- 'error',
- 'slice_file_missing',
- f"{filename} is a Generated slice row but "
- f"images/{filename} does not exist.",
- ))
-
- @staticmethod
- def _resolve_project_path(dir_path: Path) -> Path:
- """Resolve a checker target directory to its project root."""
- candidate = dir_path.parent if dir_path.is_file() else dir_path
- if (
- _project_root_for_svg_path is not None
- and candidate.name in _SVG_WORK_DIR_NAMES
- ):
- return _project_root_for_svg_path(candidate)
- if (
- (candidate / 'svg_output').exists()
- or (candidate / 'design_spec.md').exists()
- ):
- return candidate
- return candidate.parent
-
- @staticmethod
- def _split_md_table_row(line: str) -> List[str]:
- """Split a simple Markdown table row into stripped cells."""
- return [cell.strip().strip('`') for cell in line.strip().strip('|').split('|')]
-
- @classmethod
- def _extract_image_resource_rows(cls, spec_text: str) -> List[Dict[str, str]]:
- """Extract rows from design_spec.md §VIII Image Resource List."""
- section_match = re.search(
- r"^##\s+VIII\.\s+Image Resource List\b.*?(?=^##\s+|\Z)",
- spec_text,
- re.MULTILINE | re.DOTALL,
- )
- if not section_match:
- return []
-
- lines = section_match.group(0).splitlines()
- header = None
- rows: List[Dict[str, str]] = []
- in_resource_table = False
- for line in lines:
- if not line.strip().startswith('|'):
- if in_resource_table and rows:
- break
- continue
-
- cells = cls._split_md_table_row(line)
- if not cells:
- continue
- if header is None:
- if any(cell.lower() == 'filename' for cell in cells):
- header = cells
- in_resource_table = True
- continue
- if set(cell.replace('-', '').strip() for cell in cells) == {''}:
- continue
- if not in_resource_table:
- continue
- row = {header[i]: cells[i] if i < len(cells) else '' for i in range(len(header))}
- filename = row.get('Filename', '').strip()
- if (
- filename.lower() != 'filename'
- and any(value.strip() for value in row.values())
- ):
- rows.append(row)
-
- return rows
-
- @staticmethod
- def _row_filename(row: Dict[str, str]) -> str:
- return Path(row.get('Filename', '').strip()).name
-
- @staticmethod
- def _row_raw_filename(row: Dict[str, str]) -> str:
- return row.get('Filename', '').strip()
-
- @staticmethod
- def _row_type(row: Dict[str, str]) -> str:
- return row.get('Type', '').strip()
-
- @staticmethod
- def _row_acquire(row: Dict[str, str]) -> str:
- return row.get('Acquire Via', '').strip().lower()
-
- @staticmethod
- def _row_status(row: Dict[str, str]) -> str:
- return row.get('Status', '').strip().lower()
-
- @staticmethod
- def _row_layout(row: Dict[str, str]) -> str:
- return row.get('Layout pattern', '').strip()
-
- @staticmethod
- def _row_crop(row: Dict[str, str]) -> str:
- return row.get('Crop Policy', '').strip().lower()
-
- @staticmethod
- def _layout_projection_matches(left: str, right: str) -> bool:
- """Compare one Strategist recommendation without locking its wording."""
- left_ids = re.findall(r'#([0-9]+)(?![0-9])', left)
- right_ids = re.findall(r'#([0-9]+)(?![0-9])', right)
- if left_ids or right_ids:
- return left_ids == right_ids
-
- def normalize(value: str) -> str:
- return re.sub(r'\s+', ' ', value.replace('`', '')).strip()
-
- return normalize(left) == normalize(right)
-
- def _load_project_lock_image_entries(
- self,
- project_path: Path,
- ) -> Tuple[Dict[str, List[Dict[str, str]]], str | None]:
- """Return parsed image-lock rows keyed by basename."""
- lock_path = project_path / 'spec_lock.md'
- if not lock_path.exists():
- return {}, f"{lock_path} does not exist"
- if _parse_spec_lock is None:
- return {}, "spec_lock parser is unavailable"
- if _parse_spec_lock_image_value is None:
- return {}, "spec_lock image parser is unavailable"
- try:
- lock = _parse_spec_lock(lock_path)
- except Exception as exc:
- return {}, f"cannot parse {lock_path}: {exc}"
-
- entries: Dict[str, List[Dict[str, str]]] = defaultdict(list)
- legacy_metadata_keys = {
- 'image_rendering',
- 'image_rendering_references',
- 'image_rendering_behavior',
- }
- errors: List[str] = []
- for key, value in lock.get('images', {}).items():
- if str(key).strip().lower() in legacy_metadata_keys:
- continue
- try:
- parsed = _parse_spec_lock_image_value(str(key), str(value))
- except ValueError as exc:
- errors.append(f"images row {key!r} {exc}")
- continue
- path_part = parsed['path']
- filename = Path(path_part).name
- if not filename:
- continue
- entries[filename].append({
- 'key': str(key),
- 'path': path_part,
- 'source': parsed['source'],
- 'pattern': parsed['pattern'],
- 'crop': parsed['crop'],
- 'legacy': parsed['legacy'],
- })
- error = (
- f"{lock_path}: " + "; ".join(errors)
- if errors
- else None
- )
- return dict(entries), error
-
- def _load_project_lock_images(self, project_path: Path) -> set[str]:
- """Return filenames listed under spec_lock.md images."""
- entries, _error = self._load_project_lock_image_entries(project_path)
- return set(entries)
-
- @classmethod
- def _load_project_svg_image_references(
- cls,
- project_path: Path,
- ) -> Tuple[
- Dict[Path, Dict[str, set[Path]]],
- Dict[Path, int],
- Dict[str, List[Tuple[Path, str, Tuple[str, ...]]]],
- ]:
- """Parse rendered image instances, paths, and crop mechanisms."""
- svg_dir = project_path / 'svg_output'
- if not svg_dir.exists():
- return {}, {}, {}
- out: Dict[Path, Dict[str, set[Path]]] = {}
- inline_counts: Dict[Path, int] = {}
- placements: Dict[
- str,
- List[Tuple[Path, str, Tuple[str, ...]]],
- ] = defaultdict(list)
- for svg_path in discover_slide_svgs(svg_dir):
- try:
- root = ET.parse(svg_path).getroot()
- except (OSError, ET.ParseError):
- continue
- working_root, parent_by_id, images = cls._visible_image_elements(root)
- references: Dict[str, set[Path]] = defaultdict(set)
- inline_count = 0
- for element in images:
- href = (
- element.get('href')
- or element.get(f'{{{XLINK_NS}}}href')
- or ''
- )
- if href.lstrip().lower().startswith('data:'):
- inline_count += 1
- continue
- filename = cls._external_image_reference_basename(href)
- if not filename:
- continue
- references.setdefault(filename, set())
- placements[filename].append((
- svg_path,
- element.get('preserveAspectRatio') or '',
- cls._image_crop_mechanisms(
- element,
- working_root,
- parent_by_id,
- ),
- ))
- if _resolve_external_image_reference is not None:
- resolved = _resolve_external_image_reference(
- svg_path.parent,
- href,
- )
- if resolved is not None:
- references[filename].add(resolved.resolve())
- out[svg_path] = dict(references)
- if inline_count:
- inline_counts[svg_path] = inline_count
- return out, inline_counts, dict(placements)
-
- @staticmethod
- def _image_crop_mechanisms(
- image: ET.Element,
- root: ET.Element,
- parent_by_id: Dict[int, ET.Element],
- ) -> Tuple[str, ...]:
- """Return objective clipping mechanisms affecting one image instance."""
- mechanisms: List[str] = []
- current: ET.Element | None = image
- while current is not None:
- tag = _local_name(current)
- style_values = (
- _parse_inline_style(current.get('style'))
- if _parse_inline_style is not None
- else {}
- )
- for property_name in ('clip-path', 'mask'):
- value = style_values.get(property_name)
- if value is None:
- value = current.get(property_name)
- if value and value.strip().lower() != 'none':
- mechanisms.append(f"<{tag}> {property_name}")
- overflow = style_values.get('overflow')
- if overflow is None:
- overflow = current.get('overflow')
- if overflow and overflow.strip().lower() in {'hidden', 'clip'}:
- mechanisms.append(f"<{tag}> overflow={overflow.strip()!r}")
- if current is not root and tag == 'svg':
- mechanisms.append('nested <svg> viewport')
- current = parent_by_id.get(id(current))
- return tuple(dict.fromkeys(mechanisms))
-
- def _check_planned_image_closure(
- self,
- rows: List[Dict[str, str]],
- project_path: Path,
- lock_entries: Dict[str, List[Dict[str, str]]],
- lock_error: str | None,
- svg_references: Dict[Path, Dict[str, set[Path]]],
- inline_image_counts: Dict[Path, int],
- image_placements: Dict[
- str,
- List[Tuple[Path, str, Tuple[str, ...]]],
- ],
- ) -> None:
- """Close Design Spec, execution lock, files, SVGs, and provenance."""
- project_root = project_path.resolve()
- if inline_image_counts:
- total = sum(inline_image_counts.values())
- shown = ', '.join(
- f"{path.name} ({count})"
- for path, count in sorted(inline_image_counts.items())
- )
- self._illustration_issues.append((
- 'error',
- 'svg_inline_image_untracked',
- f"svg_output contains {total} inline data-URI image(s): "
- f"{shown}. Current projects must keep external project-local "
- "image hrefs so every placement closes through Design Spec "
- "§VIII and spec_lock.md.",
- ))
- valid_acquisitions = {
- 'ai',
- 'web',
- 'user',
- 'formula',
- 'placeholder',
- 'slice',
- }
- valid_statuses = {
- 'pending',
- 'failed',
- 'generated',
- 'sourced',
- 'rendered',
- 'needs-manual',
- 'existing',
- 'placeholder',
- }
- terminal_by_acquisition = {
- 'ai': {'generated', 'needs-manual'},
- 'web': {'sourced', 'needs-manual'},
- 'user': {'existing', 'needs-manual'},
- 'formula': {'rendered', 'needs-manual'},
- 'placeholder': {'placeholder'},
- 'slice': {'generated', 'needs-manual'},
- }
- current_image_contract = (
- any('Crop Policy' in row for row in rows)
- or any(
- entry.get('legacy') == 'false'
- for entries in lock_entries.values()
- for entry in entries
- )
- )
- seen_filenames: set[str] = set()
- for row in rows:
- raw_filename = self._row_raw_filename(row)
- filename = self._row_filename(row)
- acquire = self._row_acquire(row)
- status = self._row_status(row)
- layout = self._row_layout(row)
- crop = self._row_crop(row)
- filename_is_bare = bool(filename) and (
- filename not in {'.', '..'}
- and '/' not in filename
- and '\\' not in filename
- and ':' not in filename
- )
- filename_is_canonical = raw_filename in {
- filename,
- f"images/{filename}",
- }
- if not filename_is_bare or not filename_is_canonical:
- self._illustration_issues.append((
- 'error',
- 'planned_image_invalid_filename',
- f"Design Spec §VIII Filename {raw_filename!r} must be "
- "a non-empty bare filename or canonical "
- "images/<filename> path.",
- ))
- elif filename in seen_filenames:
- self._illustration_issues.append((
- 'error',
- 'planned_image_duplicate_filename',
- f"Design Spec §VIII repeats Filename {filename!r}; "
- "one resource must have one authoritative row.",
- ))
- else:
- seen_filenames.add(filename)
-
- if current_image_contract and not layout:
- self._illustration_issues.append((
- 'error',
- 'planned_image_missing_pattern',
- f"{filename or '(missing filename)'} has an empty Design "
- "Spec §VIII Layout pattern; preserve one non-empty "
- "Strategist recommendation without locking SVG geometry.",
- ))
- if current_image_contract and crop not in {'adaptive', 'no-crop'}:
- self._illustration_issues.append((
- 'error',
- 'planned_image_invalid_crop_policy',
- f"{filename or '(missing filename)'} has invalid Design "
- f"Spec §VIII Crop Policy "
- f"{row.get('Crop Policy', '').strip()!r}; use adaptive "
- "or no-crop.",
- ))
-
- if acquire not in valid_acquisitions:
- self._illustration_issues.append((
- 'error',
- 'planned_image_invalid_acquisition',
- f"{filename or '(missing filename)'} has invalid "
- f"Acquire Via {row.get('Acquire Via', '').strip()!r}.",
- ))
- continue
- if status not in valid_statuses:
- self._illustration_issues.append((
- 'error',
- 'planned_image_invalid_status',
- f"{filename or '(missing filename)'} has invalid "
- f"Status {row.get('Status', '').strip()!r}.",
- ))
- continue
- if status in {'pending', 'failed'}:
- self._illustration_issues.append((
- 'error',
- 'planned_image_not_terminal',
- f"{filename or '(missing filename)'} has non-terminal "
- f"Status {row.get('Status', '').strip()!r}; finish the "
- "owning acquisition or mark it Needs-Manual before export.",
- ))
- elif status not in terminal_by_acquisition[acquire]:
- expected = ', '.join(sorted(terminal_by_acquisition[acquire]))
- self._illustration_issues.append((
- 'error',
- 'planned_image_status_mismatch',
- f"{filename or '(missing filename)'} uses Acquire Via "
- f"{acquire!r} but Status {status!r}; terminal status must "
- f"be one of: {expected}.",
- ))
-
- if lock_error:
- self._illustration_issues.append((
- 'error',
- 'image_lock_unreadable',
- lock_error,
- ))
- return
-
- placed_rows = [
- row for row in rows
- if self._row_type(row).lower() != 'illustration sheet'
- and self._row_acquire(row)
- in {'ai', 'web', 'user', 'formula', 'placeholder', 'slice'}
- ]
- rows_by_filename = {
- self._row_filename(row): row
- for row in placed_rows
- if self._row_filename(row)
- }
- referenced_paths: Dict[str, set[Path]] = defaultdict(set)
- for references in svg_references.values():
- for filename, paths in references.items():
- referenced_paths[filename].update(paths)
- referenced = set(referenced_paths)
-
- for filename, row in rows_by_filename.items():
- if filename not in lock_entries:
- self._illustration_issues.append((
- 'error',
- 'planned_image_missing_lock',
- f"{filename} is a placed Design Spec image row but is "
- "absent from spec_lock.md images.",
- ))
- continue
- if current_image_contract and any(
- entry.get('legacy') != 'false'
- for entry in lock_entries[filename]
- ):
- self._illustration_issues.append((
- 'error',
- 'planned_image_legacy_lock_projection',
- f"{filename} uses the current Design Spec image contract "
- "but its spec_lock.md row does not provide complete "
- "source=..., pattern=..., and crop=... metadata.",
- ))
-
- for filename in sorted(referenced - set(rows_by_filename)):
- lock_note = (
- ""
- if filename in lock_entries
- else " and is absent from spec_lock.md images"
- )
- self._illustration_issues.append((
- 'error',
- 'svg_image_missing_spec',
- f"svg_output references {filename}, but it has no placed "
- f"Design Spec §VIII row{lock_note}.",
- ))
-
- for filename, entries in lock_entries.items():
- row = rows_by_filename.get(filename)
- if row is None:
- self._illustration_issues.append((
- 'error',
- 'locked_image_missing_spec',
- f"{filename} is listed in spec_lock.md images but has no "
- "placed row in Design Spec §VIII.",
- ))
- continue
-
- acquire = self._row_acquire(row)
- status = self._row_status(row)
- layout_pattern = self._row_layout(row)
- crop_policy = self._row_crop(row)
- if len(entries) > 1:
- keys = ', '.join(repr(entry.get('key', '')) for entry in entries)
- self._illustration_issues.append((
- 'error',
- 'locked_image_duplicate_entries',
- f"{filename} appears in multiple spec_lock.md image rows "
- f"({keys}); one resource must have one authoritative row.",
- ))
- for entry in entries:
- if entry.get('legacy') != 'false':
- continue
- if entry.get('source') != acquire:
- self._illustration_issues.append((
- 'error',
- 'locked_image_source_mismatch',
- f"{filename} spec_lock source={entry.get('source')!r} "
- f"does not match Design Spec §VIII Acquire Via "
- f"{acquire!r}.",
- ))
- if entry.get('crop') != crop_policy:
- self._illustration_issues.append((
- 'error',
- 'locked_image_crop_mismatch',
- f"{filename} spec_lock crop={entry.get('crop')!r} "
- f"does not match Design Spec §VIII Crop Policy "
- f"{crop_policy!r}.",
- ))
- if not self._layout_projection_matches(
- entry.get('pattern', ''),
- layout_pattern,
- ):
- self._illustration_issues.append((
- 'error',
- 'locked_image_pattern_mismatch',
- f"{filename} spec_lock pattern="
- f"{entry.get('pattern')!r} does not preserve the "
- "Design Spec §VIII Layout pattern recommendation "
- f"{layout_pattern!r}. This Design Spec-to-spec_lock "
- "projection check compares ordered catalog ids when "
- "present, otherwise normalized text; it does not "
- "compare SVG geometry or restrict the Executor's "
- "realization.",
- ))
- candidate_paths: List[Path] = []
- for entry in entries:
- raw_path = entry.get('path', '')
- if not raw_path:
- continue
- lock_path = Path(raw_path)
- legacy_bare_filename = (
- not lock_path.is_absolute()
- and raw_path not in {'.', '..'}
- and '/' not in raw_path
- and '\\' not in raw_path
- and ':' not in raw_path
- )
- if lock_path.is_absolute():
- path = lock_path
- elif legacy_bare_filename:
- path = project_path / 'images' / raw_path
- else:
- path = project_path / raw_path
- resolved_path = path.resolve()
- try:
- resolved_path.relative_to(project_root)
- except ValueError:
- self._illustration_issues.append((
- 'error',
- 'locked_image_path_outside_project',
- f"{filename} lock path {entry['path']!r} resolves "
- "outside the project workspace.",
- ))
- continue
- candidate_paths.append(resolved_path)
-
- distinct_candidate_paths = set(candidate_paths)
- if len(distinct_candidate_paths) > 1:
- shown = ', '.join(
- str(path.relative_to(project_root))
- for path in sorted(distinct_candidate_paths)
- )
- self._illustration_issues.append((
- 'error',
- 'locked_image_ambiguous_paths',
- f"{filename} resolves to multiple locked project paths: "
- f"{shown}. One resource must have one authoritative asset.",
- ))
-
- expected_paths = {
- path
- for path in distinct_candidate_paths
- if path.is_file()
- }
- asset_exists = bool(expected_paths)
- file_required = status in {
- 'existing',
- 'generated',
- 'sourced',
- 'rendered',
- }
- if not asset_exists and file_required:
- expected = entries[0].get('path') or f"images/{filename}"
- self._illustration_issues.append((
- 'error',
- 'locked_image_file_missing',
- f"{filename} is locked and has terminal Status "
- f"{row.get('Status', '').strip()!r}, but {expected} "
- "does not exist.",
- ))
-
- actual_paths = referenced_paths.get(filename, set())
- unexpected_paths = actual_paths - expected_paths
- if unexpected_paths:
- shown = ', '.join(
- str(path.relative_to(project_root))
- if path.is_relative_to(project_root)
- else str(path)
- for path in sorted(unexpected_paths)
- )
- self._illustration_issues.append((
- 'error',
- 'locked_image_reference_mismatch',
- f"{filename} is referenced from {shown}, not exclusively "
- "from its locked project path.",
- ))
-
- should_be_referenced = (
- acquire != 'placeholder'
- and asset_exists
- and status
- in {
- 'existing',
- 'generated',
- 'sourced',
- 'rendered',
- 'needs-manual',
- }
- )
- if should_be_referenced and not (actual_paths & expected_paths):
- self._illustration_issues.append((
- 'error',
- 'locked_image_unreferenced',
- f"{filename} has usable terminal content but its locked "
- "file is not referenced by any svg_output <image> element.",
- ))
-
- effective_no_crop = (
- crop_policy == 'no-crop'
- or acquire == 'formula'
- or any(entry.get('crop') == 'no-crop' for entry in entries)
- )
- if effective_no_crop:
- placements_by_svg: Dict[
- Path,
- List[Tuple[str, Tuple[str, ...]]],
- ] = defaultdict(list)
- for svg_path, raw_aspect, mechanisms in image_placements.get(
- filename,
- [],
- ):
- placements_by_svg[svg_path].append((
- raw_aspect,
- mechanisms,
- ))
-
- for svg_path, placements in placements_by_svg.items():
- parsed_placements = []
- for raw_aspect, mechanisms in placements:
- try:
- align, mode = (
- _parse_project_image_aspect_ratio(raw_aspect or None)
- if _parse_project_image_aspect_ratio is not None
- else ('', '')
- )
- except ValueError:
- # The per-SVG aspect-ratio validator owns malformed syntax.
- continue
- parsed_placements.append((
- raw_aspect,
- mechanisms,
- align,
- mode,
- ))
-
- has_complete_placement = any(
- align != 'none'
- and mode == 'meet'
- and not mechanisms
- for _raw_aspect, mechanisms, align, mode
- in parsed_placements
- )
-
- for raw_aspect, _mechanisms, align, _mode in parsed_placements:
- if align != 'none':
- continue
- actual = raw_aspect or '(implicit xMidYMid meet)'
- self._illustration_issues.append((
- 'error',
- 'no_crop_image_fit_mismatch',
- f"{svg_path.name}: {filename} is no-crop but its "
- f"rendered placement uses "
- f"preserveAspectRatio={actual!r}; stretching is not "
- "a detail crop and remains forbidden.",
- ))
-
- if has_complete_placement:
- continue
-
- for raw_aspect, mechanisms, align, mode in parsed_placements:
- if align != 'none' and mode != 'meet':
- actual = raw_aspect or '(implicit xMidYMid meet)'
- self._illustration_issues.append((
- 'error',
- 'no_crop_image_fit_mismatch',
- f"{svg_path.name}: {filename} is no-crop but "
- "this page has no complete placement and uses "
- f"preserveAspectRatio={actual!r}; keep at least "
- "one unclipped placement with a legal alignment "
- "anchor and meet.",
- ))
- if mechanisms:
- self._illustration_issues.append((
- 'error',
- 'no_crop_image_clipped',
- f"{svg_path.name}: {filename} is no-crop but "
- "this page has no complete placement; its "
- "rendered placement is affected by "
- f"{', '.join(mechanisms)}. Keep at least one "
- "unclipped meet placement so every source pixel "
- "remains visible.",
- ))
-
- self._check_sourced_image_provenance(
- rows_by_filename,
- project_path,
- )
-
- def _check_sourced_image_provenance(
- self,
- rows_by_filename: Dict[str, Dict[str, str]],
- project_path: Path,
- ) -> None:
- """Require one valid provenance item for every Sourced web row."""
- sourced = {
- filename: row
- for filename, row in rows_by_filename.items()
- if self._row_acquire(row) == 'web'
- and self._row_status(row) == 'sourced'
- }
- if not sourced:
- return
-
- manifest_path = project_path / 'images' / 'image_sources.json'
- if not manifest_path.exists():
- self._illustration_issues.append((
- 'error',
- 'image_sources_missing',
- "Sourced web images are used, but "
- "images/image_sources.json does not exist.",
- ))
- return
-
- payload, error = self._read_image_sources_manifest(manifest_path)
- if error:
- if manifest_path not in self._source_manifest_errors_reported:
- self._illustration_issues.append((
- 'error',
- 'image_sources_invalid',
- error,
- ))
- self._source_manifest_errors_reported.add(manifest_path)
- return
-
- manifest_items = {
- str(item.get('filename') or ''): item
- for item in payload['items']
- if item.get('filename')
- }
- valid_tiers = {
- 'no-attribution',
- 'attribution-required',
- 'manual',
- }
- for filename in sourced:
- item = manifest_items.get(filename)
- if item is None:
- self._illustration_issues.append((
- 'error',
- 'sourced_image_missing_provenance',
- f"{filename} is Sourced but has no matching entry in "
- "images/image_sources.json.",
- ))
- continue
-
- tier = str(item.get('license_tier') or '').strip()
- if tier not in valid_tiers:
- self._illustration_issues.append((
- 'error',
- 'sourced_image_invalid_license_tier',
- f"{filename} has invalid license_tier {tier!r} in "
- "images/image_sources.json.",
- ))
- if tier != 'manual' and not str(
- item.get('attribution_text') or ''
- ).strip():
- self._illustration_issues.append((
- 'error',
- 'sourced_image_missing_attribution_text',
- f"{filename} has license_tier {tier!r} but no "
- "attribution_text in images/image_sources.json.",
- ))
- if tier == 'attribution-required' and not str(
- item.get('author') or ''
- ).strip():
- self._illustration_issues.append((
- 'error',
- 'sourced_image_missing_author',
- f"{filename} requires attribution but has no author in "
- "images/image_sources.json.",
- ))
-
- def _check_animation_config_contract(self, dir_path: Path) -> None:
- """Project-level animations.json reference checks."""
- project_path = self._resolve_project_path(dir_path)
- config_path = project_path / 'animations.json'
- if (
- _load_animation_config is None
- or _validate_animation_config is None
- or _validate_animation_config_errors is None
- or _validate_transition_config is None
- ):
- if config_path.is_file():
- detail = _animation_config_import_error or 'unknown import error'
- self._animation_issues.append((
- 'error',
- f'animations.json validation is unavailable: {detail}',
- ))
- return
- try:
- config = _load_animation_config(project_path)
- except Exception as exc:
- self._animation_issues.append(('error', f"animations.json is invalid: {exc}"))
- return
- if not config:
- return
- fatal_errors = list(dict.fromkeys(
- _validate_transition_config(config)
- + _validate_animation_config_errors(config)
- ))
- for error in fatal_errors:
- self._animation_issues.append(('error', error))
- for message in _validate_animation_config(project_path, config):
- severity = (
- 'warning'
- if ' has no id and cannot be customized in animations.json' in message
- else 'error'
- )
- self._animation_issues.append((severity, message))
-
- def _check_template_contract(
- self,
- dir_path: Path,
- svg_files: List[Path],
- *,
- check_structure: bool,
- ) -> None:
- """Check reusable-template structure, roster, and placeholder hints.
-
- - **Roster mismatch (orphan / missing)** is reported as an *error*: a
- stale roster will produce a wrong ``layouts_index.json`` entry.
- - **Explicit structure gaps** are errors when positive structure checks
- are enabled: every current reusable SVG declares its Master and Layout
- identity. Zero-placeholder Layouts are valid. Legacy template-mode
- packages fail and must be replaced by a new create-template workspace.
- - **Placeholder gaps** are reported as *warnings*. Templates may
- legitimately omit conventional placeholders or swap them out (e.g.
- ``{{CLOSING_MESSAGE}}`` instead of ``{{THANK_YOU}}``), and a content
- variant may use a bespoke slot vocabulary. Designers can declare
- their own per-stem expectations via ``placeholders:`` frontmatter
- in ``design_spec.md`` to suppress these warnings explicitly.
-
- Issues are aggregated and printed in :py:meth:`print_summary` so the
- per-file report stays focused on intrinsic SVG validity.
- """
- spec_path = dir_path / 'design_spec.md'
- spec_text = spec_path.read_text(encoding='utf-8') if spec_path.exists() else ""
- declared_structure_mode = _declared_template_structure_mode(dir_path)
- mode_error_recorded = False
- if declared_structure_mode != 'structured':
- mode_error_recorded = True
- self._template_issues.append((
- 'error',
- 'explicit_structure_mode',
- "design_spec.md frontmatter must declare "
- "native_structure_mode: structured; legacy template-mode "
- "workspaces must be re-created through create-template",
- ))
- if check_structure:
- native_contract_path = dir_path / 'native_structure.json'
- source_template_path = dir_path / 'source_template.pptx'
- legacy_structure_detected = False
- for svg_file in svg_files:
- try:
- root = ET.parse(svg_file).getroot()
- except (OSError, ET.ParseError):
- continue
- if not root.get('data-pptx-master'):
- legacy_structure_detected = True
- self._template_issues.append((
- 'error',
- 'explicit_master_missing',
- f"{svg_file.name}: reusable templates require root "
- "data-pptx-master metadata",
- ))
- if not root.get('data-pptx-master-name'):
- legacy_structure_detected = True
- self._template_issues.append((
- 'error',
- 'explicit_master_name_missing',
- f"{svg_file.name}: reusable templates require root "
- "data-pptx-master-name metadata",
- ))
- if not root.get('data-pptx-layout'):
- self._template_issues.append((
- 'error',
- 'explicit_structure_missing',
- f"{svg_file.name}: reusable templates require root "
- "data-pptx-layout metadata",
- ))
- if not root.get('data-pptx-layout-name'):
- self._template_issues.append((
- 'error',
- 'explicit_structure_name_missing',
- f"{svg_file.name}: reusable templates require root "
- "data-pptx-layout-name metadata",
- ))
- if root.get('data-pptx-layout-kind') is not None:
- legacy_structure_detected = True
- self._template_issues.append((
- 'error',
- 'deck_instance_layout_kind',
- f"{svg_file.name}: reusable template prototypes must omit "
- "legacy data-pptx-layout-kind metadata",
- ))
- if any(
- child.get('data-pptx-placeholder') is not None
- and child.tag.rsplit('}', 1)[-1] != 'g'
- for child in list(root)
- ):
- legacy_structure_detected = True
- missing_bounds = [
- child.get('id') or child.tag.rsplit('}', 1)[-1]
- for child in list(root)
- if child.get('data-pptx-placeholder') is not None
- and child.get('data-pptx-bounds') is None
- ]
- if missing_bounds:
- legacy_structure_detected = True
- self._template_issues.append((
- 'error',
- 'placeholder_bounds_missing',
- f"{svg_file.name}: reusable templates require "
- "explicit design-zone data-pptx-bounds; missing: "
- + ', '.join(missing_bounds),
- ))
- if native_contract_path.exists() or source_template_path.exists():
- legacy_structure_detected = True
- self._template_issues.append((
- 'error',
- 'legacy_native_structure_pair',
- "legacy native_structure.json/source_template.pptx template "
- "contracts must be replaced through "
- "skills/ppt-master/workflows/create-template.md",
- ))
-
- if declared_structure_mode != 'structured':
- legacy_structure_detected = True
- if not mode_error_recorded:
- self._template_issues.append((
- 'error',
- 'explicit_structure_mode',
- "design_spec.md frontmatter must declare "
- "native_structure_mode: structured",
- ))
- if legacy_structure_detected:
- self._template_issues.append((
- 'error',
- 'legacy_structure_contract',
- "legacy template structure detected; create a new current "
- "workspace through skills/ppt-master/workflows/"
- "create-template.md before Step 3 consumption",
- ))
- spec_pages = self._extract_spec_roster(spec_text) if spec_text else []
- custom_contract = self._extract_frontmatter_placeholders(spec_text) if spec_text else {}
-
- on_disk = {p.stem for p in svg_files}
-
- if spec_pages:
- spec_set = set(spec_pages)
- orphan = sorted(on_disk - spec_set)
- missing = sorted(spec_set - on_disk)
- for page in orphan:
- self._template_issues.append((
- 'error',
- 'roster_orphan',
- f"{page}.svg exists on disk but is not listed in design_spec.md Page Roster",
- ))
- for page in missing:
- self._template_issues.append((
- 'error',
- 'roster_missing',
- f"design_spec.md Page Roster lists {page} but {page}.svg is missing on disk",
- ))
- elif spec_path.exists():
- # design_spec.md is present but the roster parser found nothing —
- # reusable template workspaces always fail closed.
- self._template_issues.append((
- 'error',
- 'roster_unknown',
- f"could not extract page roster from {spec_path.name}; "
- "skipping orphan/missing checks",
- ))
- else:
- self._template_issues.append((
- 'error',
- 'spec_missing',
- f"{spec_path.name} not found — required for every library template",
- ))
-
- # Per-file placeholder coverage. Variants reuse the parent type's set
- # (e.g. 03a_content_two_col.svg ↔ 03_content rules) unless the spec
- # frontmatter overrides that page (custom_contract takes precedence).
- for svg_file in svg_files:
- expected = self._lookup_template_contract(
- svg_file.stem, overrides=custom_contract,
- )
- if expected is None:
- continue # extension pages or stems with no convention
- try:
- content = svg_file.read_text(encoding='utf-8')
- except OSError:
- continue
- for placeholder in expected:
- if placeholder not in content:
- self._template_issues.append((
- 'warning',
- 'placeholder_hint',
- f"{svg_file.name}: missing conventional placeholder {placeholder} "
- "(declare 'placeholders:' frontmatter in design_spec.md to silence)",
- ))
-
- @staticmethod
- def _extract_frontmatter_placeholders(spec_text: str) -> Dict[str, Tuple[str, ...]]:
- """Read the optional ``placeholders:`` map from design_spec.md frontmatter.
-
- Shape:
-
- .. code-block:: yaml
-
- placeholders:
- 01_cover: ["{{TITLE}}", "{{BRAND_LOGO}}"]
- 03_content: [] # explicitly assert "no expectation"
- 03a_content_two_col: # variant-specific override
- - "{{LEFT_TITLE}}"
- - "{{RIGHT_TITLE}}"
-
- Each key is a stem (full filename without ``.svg``) or page-type prefix
- (``01_cover``). An empty list silences the default convention for that
- stem; a populated list replaces the default. Stems / prefixes not
- listed fall back to ``DEFAULT_PLACEHOLDER_CONVENTION``.
-
- We parse with PyYAML when available; otherwise we fall back to a
- minimal regex that handles the documented shape.
- """
- if not spec_text.startswith("---\n"):
- return {}
- end = spec_text.find("\n---\n", 4)
- if end == -1:
- return {}
- block = spec_text[4:end]
-
- try:
- import yaml # type: ignore
- except ImportError:
- return _parse_placeholders_fallback(block)
-
- try:
- data = yaml.safe_load(block) or {}
- except yaml.YAMLError:
- return {}
- if not isinstance(data, dict):
- return {}
- raw = data.get("placeholders")
- if not isinstance(raw, dict):
- return {}
-
- out: Dict[str, Tuple[str, ...]] = {}
- for stem, value in raw.items():
- if not isinstance(stem, str):
- continue
- if isinstance(value, list):
- out[stem] = tuple(str(v) for v in value)
- elif value is None:
- out[stem] = ()
- return out
-
- @staticmethod
- def _extract_spec_roster(spec_text: str) -> List[str]:
- """Best-effort: extract the page roster from design_spec.md.
-
- Templates do not share a uniform section index for the roster — the
- personality-only skeleton puts it at §V "Page Roster"; legacy specs use
- §VI "Page Roster" or bury filenames under §VII "Page Types" as
- ``### N. Cover Page (01_cover.svg)``. We match by title (any roman
- index), then fall back to scanning the whole document for any
- backtick-wrapped ``<stem>.svg`` reference.
-
- Returns the deduplicated stem list in document order. Empty result
- means we can't determine the roster confidently — caller should treat
- that as "skip orphan/missing checks", not as "no pages declared".
- """
- # Pass 1: explicit roster section, any roman numeral.
- sections = list(re.finditer(
- r"^##\s+[IVX]+\.\s+(?:(?:SVG\s+)?Page Roster|Page Structure|Pages|Page Types)\b.*?(?=^##\s+|\Z)",
- spec_text,
- re.MULTILINE | re.DOTALL | re.IGNORECASE,
- ))
- roster_scope = next(
- (
- section.group(0)
- for section in sections
- if re.match(
- r"^##\s+[IVX]+\.\s+(?:SVG\s+)?Page Roster\b",
- section.group(0),
- re.IGNORECASE,
- )
- ),
- None,
- )
- scope = roster_scope or next(
- (
- section.group(0)
- for section in sections
- if re.search(r"[`\(][0-9A-Za-z_]+\.svg[`\)]", section.group(0))
- ),
- sections[0].group(0) if sections else None,
- )
-
- # Pass 2: full document. We *only* trust this scan when the explicit
- # roster scan came up empty (no `<stem>.svg` references inside it) —
- # otherwise the explicit section's deliberate roster wins over loose
- # mentions elsewhere.
- explicit_scope = bool(
- scope and re.search(r"[`\(][0-9A-Za-z_]+\.svg[`\)]", scope)
- )
- if explicit_scope:
- text = scope
- else:
- text = spec_text
-
- stems: List[str] = []
- seen: set = set()
- # Accept backtick-quoted (`01_cover.svg`) and parenthesized
- # (01_cover.svg) forms — existing specs use either.
- svg_ref_re = re.compile(r"[`\(]([0-9A-Za-z_]+\.svg)[`\)]")
- for match in svg_ref_re.finditer(text):
- stem = match.group(1)[:-4]
- if stem in seen or (not explicit_scope and not re.match(r"^\d", stem)):
- continue
- seen.add(stem)
- stems.append(stem)
-
- # If the explicit §VI scan listed bare stems (without .svg), accept
- # those as fallback — but only when they were inside that section.
- if not stems and scope:
- for match in re.finditer(r"`([0-9]{2}[a-z]?_[A-Za-z0-9_]+)`", scope):
- stem = match.group(1)
- if stem in seen:
- continue
- seen.add(stem)
- stems.append(stem)
-
- return stems
-
- @classmethod
- def _lookup_template_contract(
- cls, stem: str, *,
- overrides: Dict[str, Tuple[str, ...]] | None = None,
- ) -> Tuple[str, ...] | None:
- """Resolve a SVG stem to its expected placeholder set.
-
- Resolution order, first hit wins:
- 1. ``overrides[stem]`` — frontmatter entry for the exact filename
- 2. ``overrides[<page_type_prefix>]`` — frontmatter entry for the
- variant's parent type (e.g. ``03_content`` for
- ``03a_content_two_col``)
- 3. ``DEFAULT_PLACEHOLDER_CONVENTION[<page_type>]`` — keyed by the
- type token alone, so it applies regardless of where the type
- lands in the template's presentation-order numbering
-
- Returns ``None`` for stems with no matching convention or override —
- e.g. extension pages like ``05_section_break``. ``()`` (empty tuple)
- is a valid value meaning "no expected placeholders" — used to
- explicitly silence the default convention.
- """
- overrides = overrides or {}
- if stem in overrides:
- return overrides[stem]
-
- # Variant convention: <NN><letter>?_<rest>; strip the letter to find
- # the parent type prefix, e.g. "03a_content_two_col" -> "03_content".
- match = re.match(r"^(\d{2})([a-z])?_([a-z]+)", stem)
- if not match:
- return None
- num, _letter, kind = match.groups()
- key = f"{num}_{kind}"
- if key in overrides:
- return overrides[key]
- return cls.DEFAULT_PLACEHOLDER_CONVENTION.get(kind)
-
- def _print_result(self, result: Dict):
- """Print check result for a single file"""
- if result['passed']:
- if result['warnings']:
- icon = "[WARN]"
- status = "Passed (with warnings)"
- else:
- icon = "[OK]"
- status = "Passed"
- else:
- icon = "[ERROR]"
- status = "Failed"
-
- print(f"{icon} {result['file']} - {status}")
-
- # Display basic info
- if result['info']:
- info_items = []
- if 'viewbox' in result['info']:
- info_items.append(f"viewBox: {result['info']['viewbox']}")
- if info_items:
- print(f" {' | '.join(info_items)}")
-
- # Display errors
- if result['errors']:
- for error in result['errors']:
- print(f" [ERROR] {error}")
-
- # Display the complete warning set from this run. The generation
- # workflow reviews all findings before one consolidated repair pass.
- if result['warnings']:
- for warning in result['warnings']:
- print(f" [WARN] {warning}")
-
- print()
-
- def print_summary(self):
- """Print check summary"""
- self._apply_aggregated_issue_counts()
-
- print("=" * 80)
- print("[SUMMARY] Check Summary")
- print("=" * 80)
-
- print(f"\nTotal files: {self.summary['total']}")
- print(
- f" [OK] Fully passed: {self.summary['passed']} ({self._percentage(self.summary['passed'])}%)")
- print(
- f" [WARN] With warnings: {self.summary['warnings']} ({self._percentage(self.summary['warnings'])}%)")
- print(
- f" [ERROR] With errors: {self.summary['errors']} ({self._percentage(self.summary['errors'])}%)")
-
- if self.issue_types:
- print(f"\nIssue categories:")
- for issue_type, count in sorted(self.issue_types.items(), key=lambda x: x[1], reverse=True):
- print(f" {issue_type}: {count}")
-
- # spec_lock anchor comparison (only printed when a lock was found)
- self._print_anchor_value_summary()
-
- # Template-mode aggregation (orphan/missing roster + placeholder hints)
- self._print_template_summary()
-
- # Animation config aggregation.
- self._print_animation_summary()
-
- # Illustration strategy aggregation.
- self._print_illustration_summary()
-
- # Communication contract and per-page audience movement.
- self._print_communication_trace_summary()
-
- # Explicit PowerPoint master/layout structure aggregation.
- self._print_pptx_structure_summary()
-
- # Source-owned import recovery belongs to the template, not this run.
- self._print_source_import_summary()
-
- # Fix suggestions
- if self.summary['errors'] > 0 or self.summary['warnings'] > 0:
- print(f"\n[TIP] Common fixes:")
- print(f" 1. XML well-formedness: write typography as raw Unicode (—, ©, →, NBSP); escape XML reserved chars as &amp; &lt; &gt; &quot; &apos; — never use HTML named entities like &nbsp; &mdash; &copy;")
- print(f" 2. viewBox issues: root viewBox is the canvas authority (see references/canvas-formats.md)")
- print(
- " 3. Paint recommendation: generated SVG prefers uppercase "
- "#RRGGBB plus channel-specific opacity; compatible alternatives "
- "remain non-blocking"
- )
- print(f" 4. foreignObject: Use <text> + <tspan> for manual line breaks")
- print(f" 5. Font issues: use PPT-safe exported typefaces (e.g. Microsoft YaHei / Arial / Consolas)")
-
- def _print_animation_summary(self):
- """Print animations.json validation issues if present."""
- if not self._animation_issues:
- return
-
- errors = [item for item in self._animation_issues if item[0] == 'error']
- warnings = [item for item in self._animation_issues if item[0] == 'warning']
-
- print("\n[ANIMATION] animations.json checks")
- for _severity, msg in errors:
- print(f" [ERROR] {msg}")
- for _severity, msg in warnings:
- print(f" [WARN] {msg}")
-
- def _print_illustration_summary(self):
- """Print project-level illustration strategy issues if present."""
- if not self._illustration_issues:
- return
-
- errors = [item for item in self._illustration_issues if item[0] == 'error']
- warnings = [item for item in self._illustration_issues if item[0] == 'warning']
-
- print("\n[IMAGES] Image resource checks")
- if errors:
- print(f" Errors ({len(errors)}):")
- for _severity, kind, msg in errors:
- print(f" [{kind}] {msg}")
- if warnings:
- print(f" Warnings ({len(warnings)}):")
- for _severity, kind, msg in warnings:
- print(f" [{kind}] {msg}")
-
- def _print_pptx_structure_summary(self):
- """Print project-level PowerPoint structure contract issues."""
- if not self._pptx_structure_issues:
- return
- print("\n[PPTX STRUCTURE] Master/layout contract checks")
- for severity, message in self._pptx_structure_issues:
- print(f" [{severity.upper()}] {message}")
-
- def _print_communication_trace_summary(self):
- """Print project-level communication trace issues."""
- if not self._communication_trace_issues:
- return
- print("\n[COMMUNICATION TRACE] Contract and Audience move checks")
- for severity, message in self._communication_trace_issues:
- print(f" [{severity.upper()}] {message}")
-
- def _print_source_import_summary(self):
- """Print source-owned tolerant-import diagnostics as information."""
- warning_count = _source_import_warning_count(
- self._source_import_summary
- )
- if warning_count <= 0:
- return
- print("\n[SOURCE IMPORT] Template-owned compatibility diagnostics")
- print(
- f" [INFO] {warning_count} source-import warning(s); unchanged "
- "template recovery is not attributed to generated content."
- )
- by_code = self._source_import_summary.get('by_code')
- if isinstance(by_code, dict):
- for code, count in sorted(by_code.items()):
- print(f" {code}: {count}")
-
- def _print_template_summary(self):
- """Aggregate template-mode roster / placeholder issues at the bottom.
-
- Errors land under the ``errors`` summary count (so the exit signal
- from ``main`` agrees), warnings under ``warnings``. Both are listed
- per file so the user can act on them directly.
- """
- if not self._template_issues and not self._brand_template_checked:
- return
-
- errors = [item for item in self._template_issues if item[0] == 'error']
- warnings = [item for item in self._template_issues if item[0] == 'warning']
-
- print("\n[TEMPLATE] Template mode checks")
- if errors:
- print(f" Errors ({len(errors)}):")
- for _sev, kind, msg in errors:
- print(f" [{kind}] {msg}")
- if warnings:
- print(f" Warnings ({len(warnings)}):")
- for _sev, kind, msg in warnings:
- print(f" [{kind}] {msg}")
- if self._brand_template_checked and not errors:
- print(" Brand design_spec.md schema and asset references passed.")
- if not errors:
- if not self._brand_template_checked:
- print(" No structural roster issues.")
- print(" Conventional placeholder-name hints may be declared through "
- "'placeholders:' frontmatter. Placeholder bounds are mandatory "
- "design-zone metadata.")
-
- def _apply_aggregated_issue_counts(self):
- """Mirror project-level aggregate issues into summary counters once."""
- if self._aggregate_counts_applied:
- return
- self._aggregate_counts_applied = True
-
- animation_errors = [item for item in self._animation_issues if item[0] == 'error']
- animation_warnings = [item for item in self._animation_issues if item[0] == 'warning']
- self.summary['errors'] += len(animation_errors)
- self.summary['warnings'] += len(animation_warnings)
- for severity, _msg in self._animation_issues:
- self.issue_types[f'animation_config_{severity}'] += 1
-
- template_errors = [item for item in self._template_issues if item[0] == 'error']
- template_warnings = [item for item in self._template_issues if item[0] == 'warning']
- self.summary['errors'] += len(template_errors)
- self.summary['warnings'] += len(template_warnings)
- for severity, kind, _msg in self._template_issues:
- self.issue_types[f'template_{kind}_{severity}'] += 1
-
- illustration_errors = [item for item in self._illustration_issues if item[0] == 'error']
- illustration_warnings = [item for item in self._illustration_issues if item[0] == 'warning']
- self.summary['errors'] += len(illustration_errors)
- self.summary['warnings'] += len(illustration_warnings)
- for severity, kind, _msg in self._illustration_issues:
- self.issue_types[f'illustration_{kind}_{severity}'] += 1
-
- communication_errors = [
- item for item in self._communication_trace_issues
- if item[0] == 'error'
- ]
- communication_warnings = [
- item for item in self._communication_trace_issues
- if item[0] == 'warning'
- ]
- self.summary['errors'] += len(communication_errors)
- self.summary['warnings'] += len(communication_warnings)
- for severity, _msg in self._communication_trace_issues:
- self.issue_types[f'communication_trace_{severity}'] += 1
-
- structure_errors = [item for item in self._pptx_structure_issues if item[0] == 'error']
- structure_warnings = [item for item in self._pptx_structure_issues if item[0] == 'warning']
- self.summary['errors'] += len(structure_errors)
- self.summary['warnings'] += len(structure_warnings)
- for severity, _msg in self._pptx_structure_issues:
- self.issue_types[f'pptx_structure_{severity}'] += 1
-
- def _print_anchor_value_summary(self):
- """Print anchor comparisons without treating contextual paint/type as drift."""
- if not self._lock_seen:
- return
- has_contextual = any(
- self._anchor_value_summary[category]
- for category in ('colors', 'fonts')
- )
- has_undeclared_sizes = bool(self._anchor_value_summary['sizes'])
- if not has_contextual and not has_undeclared_sizes:
- print(
- "\n[OK] spec_lock anchor comparison: no additional contextual "
- "colors/fonts or out-of-band font sizes"
- )
- return
-
- if has_contextual:
- print("\nContextual values beyond spec_lock anchors (informational):")
- for category, label in (
- ('colors', 'Colors'),
- ('fonts', 'Font families'),
- ):
- items = self._anchor_value_summary.get(category, {})
- if not items:
- continue
- entries = sorted(
- items.items(), key=lambda item: (-len(item[1]), item[0])
- )
- print(f" {label}:")
- for val, files in entries:
- count = len(files)
- suffix = "file" if count == 1 else "files"
- print(f" {val} ({count} {suffix})")
- print(
- "Note: contextual page paint, gradient/effect colors, and "
- "export-safe typefaces are allowed.\n"
- " Add a spec_lock row only when a value becomes a "
- "recurring named semantic role."
- )
-
- if has_undeclared_sizes:
- print(
- "\nTypography sizes outside every declared role anchor ±2px "
- "(up to 2 occurrences are sparse; the 3rd is recurring):"
- )
- entries = sorted(
- self._anchor_value_summary['sizes'].items(),
- key=lambda item: (-len(item[1]), item[0]),
- )
- for val, files in entries:
- occurrences = self._undeclared_size_occurrences.get(
- val,
- len(files),
- )
- file_count = len(files)
- file_suffix = "file" if file_count == 1 else "files"
- policy = (
- "sparse"
- if occurrences <= SPARSE_UNDECLARED_FONT_SIZE_MAX_OCCURRENCES
- else "recurring — declare a role"
- )
- print(
- f" {val} ({occurrences} occurrences in {file_count} "
- f"{file_suffix}; {policy})"
- )
-
- def _percentage(self, count: int) -> int:
- """Calculate percentage"""
- if self.summary['total'] == 0:
- return 0
- return min(100, int(count / self.summary['total'] * 100))
-
- def export_report(self, output_file: str = 'svg_quality_report.txt'):
- """Export check report"""
- with open(output_file, 'w', encoding='utf-8') as f:
- f.write("PPT Master SVG Quality Check Report\n")
- f.write("=" * 80 + "\n\n")
-
- for result in self.results:
- status = "[OK] Passed" if result['passed'] else "[ERROR] Failed"
- f.write(f"{status} - {result['file']}\n")
- f.write(f"Path: {result.get('path', 'N/A')}\n")
-
- if result['info']:
- f.write(f"Info: {result['info']}\n")
-
- if result['errors']:
- f.write(f"\nErrors:\n")
- for error in result['errors']:
- f.write(f" - {error}\n")
-
- if result['warnings']:
- f.write(f"\nWarnings:\n")
- for warning in result['warnings']:
- f.write(f" - {warning}\n")
-
- f.write("\n" + "-" * 80 + "\n\n")
-
- # Write summary
- f.write("\n" + "=" * 80 + "\n")
- f.write("Check Summary\n")
- f.write("=" * 80 + "\n\n")
- f.write(f"Total files: {self.summary['total']}\n")
- f.write(f"Fully passed: {self.summary['passed']}\n")
- f.write(f"With warnings: {self.summary['warnings']}\n")
- f.write(f"With errors: {self.summary['errors']}\n")
-
- print(f"\n[REPORT] Check report exported: {output_file}")
-
- def export_json_report(
- self,
- output_file: str,
- *,
- target: str,
- stage: str,
- ) -> None:
- """Write a machine-readable quality report with provenance classes."""
- self._apply_aggregated_issue_counts()
- introduced: List[Dict[str, str]] = []
- blocking: List[Dict[str, str]] = []
- inherited: List[Dict[str, str]] = []
- for result in self.results:
- filename = str(result.get('file') or '')
- introduced.extend({
- 'file': filename,
- 'message': warning,
- } for warning in result.get('warnings', []))
- blocking.extend({
- 'file': filename,
- 'message': error,
- } for error in result.get('errors', []))
- info = result.get('info') or {}
- for item in info.get('inherited', []):
- if isinstance(item, dict):
- inherited.append({
- 'file': filename,
- 'kind': str(item.get('kind') or 'prototype'),
- 'message': str(item.get('message') or ''),
- })
-
- project_issues = {
- 'template': [
- {'severity': severity, 'kind': kind, 'message': message}
- for severity, kind, message in self._template_issues
- ],
- 'animation': [
- {'severity': severity, 'message': message}
- for severity, message in self._animation_issues
- ],
- 'illustration': [
- {'severity': severity, 'kind': kind, 'message': message}
- for severity, kind, message in self._illustration_issues
- ],
- 'communication_trace': [
- {'severity': severity, 'message': message}
- for severity, message in self._communication_trace_issues
- ],
- 'pptx_structure': [
- {'severity': severity, 'message': message}
- for severity, message in self._pptx_structure_issues
- ],
- }
- for group, issues in project_issues.items():
- for issue in issues:
- item = {
- 'scope': group,
- 'message': issue['message'],
- }
- if issue['severity'] == 'error':
- blocking.append(item)
- else:
- introduced.append(item)
-
- # Keep the legacy `drift` JSON field for report compatibility. Its
- # colors/fonts entries are informational anchor comparisons; sparse
- # size entries are informational until their third occurrence.
- drift = {
- category: {
- value: sorted(files)
- for value, files in sorted(values.items())
- }
- for category, values in self._anchor_value_summary.items()
- }
- source_import = dict(self._source_import_summary)
- payload = {
- 'schema': 'ppt-master.svg-quality-report.v1',
- 'stage': stage,
- 'target': str(Path(target).resolve()),
- 'source_fingerprint': _quality_source_fingerprint(self.results),
- 'summary': dict(self.summary),
- 'issue_types': dict(sorted(self.issue_types.items())),
- 'categories': {
- 'blocking': {
- 'count': len(blocking),
- 'issues': blocking,
- },
- 'introduced': {
- 'count': len(introduced),
- 'issues': introduced,
- },
- 'inherited': {
- 'count': len(inherited),
- 'issues': inherited,
- },
- 'source-import': {
- 'count': _source_import_warning_count(source_import),
- 'summary': source_import,
- },
- },
- 'drift': drift,
- 'project_issues': project_issues,
- 'files': self.results,
- }
- report_path = Path(output_file)
- report_path.parent.mkdir(parents=True, exist_ok=True)
- report_path.write_text(
- json.dumps(payload, ensure_ascii=False, indent=2) + '\n',
- encoding='utf-8',
- )
- print(f"\n[REPORT] JSON quality report exported: {report_path}")
-
-
-def _source_import_warning_count(summary: Dict[str, object]) -> int:
- """Return only a schema-compatible non-negative warning count."""
- value = summary.get('warning_count')
- if isinstance(value, bool) or not isinstance(value, int) or value < 0:
- return 0
- return value
-
-
-def _quality_source_fingerprint(results: List[Dict]) -> Dict[str, object]:
- """Bind a quality report to the exact SVG bytes that were checked."""
- files: List[Dict[str, object]] = []
- aggregate = hashlib.sha256()
- candidates = sorted(
- (
- result
- for result in results
- if result.get('exists') and result.get('path')
- ),
- key=lambda result: Path(str(result['path'])).name,
- )
- for result in candidates:
- path = Path(str(result['path']))
- file_sha256 = result.get('source_sha256')
- if not isinstance(file_sha256, str):
- files.append({
- 'file': path.name,
- 'sha256': None,
- 'error': 'source bytes were not available during validation',
- })
- file_sha256 = 'unreadable'
- else:
- files.append({'file': path.name, 'sha256': file_sha256})
- aggregate.update(path.name.encode('utf-8'))
- aggregate.update(b'\0')
- aggregate.update(file_sha256.encode('ascii'))
- aggregate.update(b'\n')
- return {
- 'algorithm': 'sha256',
- 'digest': aggregate.hexdigest(),
- 'file_count': len(files),
- 'files': files,
- }
-
-
-def _first_page_target(target: str) -> str:
- """Resolve a project/directory target to its first authored SVG page."""
- path = Path(target)
- if path.is_file():
- return str(path)
- svg_root = path / 'svg_output' if (path / 'svg_output').is_dir() else path
- svg_files = discover_slide_svgs(svg_root) if svg_root.is_dir() else []
- return str(svg_files[0]) if svg_files else target
-
-
-def _default_json_report_path(
- checker: SVGQualityChecker,
- target: str,
- stage: str,
-) -> Path:
- """Choose a stage-specific report path without overwriting the final gate."""
- target_path = Path(target)
- project_path = checker._resolve_project_path(target_path)
- report_name = (
- 'svg_quality_report.json'
- if stage == 'final'
- else 'svg_quality_first_page_report.json'
- )
- if (
- (project_path / 'svg_output').is_dir()
- or (project_path / 'design_spec.md').is_file()
- ):
- return project_path / 'validation' / report_name
- base = target_path if target_path.is_dir() else target_path.parent
- return base / report_name
-
-
-def print_usage() -> None:
- """Print CLI usage information."""
- print("PPT Master - SVG Quality Check Tool\n")
- print("Usage:")
- print(" python3 scripts/svg_quality_checker.py <svg_file>")
- print(" python3 scripts/svg_quality_checker.py <directory>")
- print(" python3 scripts/svg_quality_checker.py <workspace>/templates --template-mode")
- print(" python3 scripts/svg_quality_checker.py --all examples")
- print("\nExamples:")
- print(" python3 scripts/svg_quality_checker.py examples/project/svg_output/slide_01.svg")
- print(" python3 scripts/svg_quality_checker.py examples/project/svg_output")
- print(" python3 scripts/svg_quality_checker.py examples/project")
- print(" python3 scripts/svg_quality_checker.py templates/layouts/presentation_core/templates --template-mode")
- print(" python3 scripts/svg_quality_checker.py templates/decks/中国电信/templates --template-mode")
- print("\nOptions:")
- print(" --format <ppt169|ppt43|...> Expected canvas format")
- print(" --stage <first-page|final> first-page checks only the first authored SVG")
- print(" with a partial structure roster; final (default)")
- print(" requires the complete declared page roster.")
- print(" --json Write a machine-readable quality report")
- print(" --json-output <path> Override the JSON report path")
- print(" --quick-generate Validate lockless flat Quick Generate SVGs;")
- print(" ignore design_spec.md and spec_lock.md.")
- print(" --template-mode Validate a template workspace's templates/ directory:")
- print(" Brand validates design_spec.md and referenced assets;")
- print(" Layout/Deck glob *.svg directly, skip spec_lock checks,")
- print(" enforce roster consistency, and emit placeholder hints.")
- print(" native_structure_mode: structured also enables complete")
- print(" per-file and cross-page structure validation. Legacy")
- print(" native_structure_mode: template fails and must be")
- print(" re-created through create-template before validation.")
- print(" Warnings are advisory: they require no modification and do not affect exit status;")
- print(" only errors make the command exit with status 1.")
-
-
-def main() -> None:
- """Run the CLI entry point."""
- if len(sys.argv) < 2:
- print_usage()
- sys.exit(0)
-
- if sys.argv[1] in {"-h", "--help", "help"}:
- print_usage()
- sys.exit(0)
-
- if sys.argv[1].startswith("--") and sys.argv[1] not in {"--all"}:
- print(f"[ERROR] Missing target before option: {sys.argv[1]}")
- print_usage()
- sys.exit(1)
-
- template_mode = '--template-mode' in sys.argv
- quick_generate = '--quick-generate' in sys.argv
- if template_mode and quick_generate:
- print("[ERROR] --template-mode cannot be combined with --quick-generate")
- sys.exit(1)
- checker = SVGQualityChecker(
- template_mode=template_mode,
- quick_generate=quick_generate,
- )
-
- # Parse arguments
- target = sys.argv[1]
- expected_format = None
- stage = 'final'
-
- if '--format' in sys.argv:
- idx = sys.argv.index('--format')
- if idx + 1 < len(sys.argv):
- expected_format = sys.argv[idx + 1]
- if '--stage' in sys.argv:
- idx = sys.argv.index('--stage')
- if idx + 1 >= len(sys.argv):
- print("[ERROR] --stage requires first-page or final")
- sys.exit(1)
- stage = sys.argv[idx + 1]
- if stage not in {'first-page', 'final'}:
- print(f"[ERROR] Unsupported quality-check stage: {stage}")
- sys.exit(1)
-
- # Execute check
- if target == '--all':
- if quick_generate:
- print("[ERROR] --quick-generate does not support --all")
- sys.exit(1)
- if stage != 'final':
- print("[ERROR] --stage first-page does not support --all")
- sys.exit(1)
- # Check all example projects
- base_dir = sys.argv[2] if len(sys.argv) > 2 else 'examples'
- from project_utils import find_all_projects
- projects = find_all_projects(base_dir)
-
- for project in projects:
- print(f"\n{'=' * 80}")
- print(f"Checking project: {project.name}")
- print('=' * 80)
- checker.check_directory(str(project))
- else:
- check_target = _first_page_target(target) if stage == 'first-page' else target
- checker.check_directory(check_target, expected_format)
-
- if stage == 'final' and Path(target).is_dir():
- if checker._has_incomplete_page_roster:
- print(
- "[TIP] This final-stage run found an incomplete page roster. "
- "During serial authoring, use --stage first-page for the first-page "
- "gate; keep --stage final for the complete deck."
- )
-
- # Print summary
- checker.print_summary()
-
- # Export report (if specified)
- if '--export' in sys.argv:
- output_file = 'svg_quality_report.txt'
- if '--output' in sys.argv:
- idx = sys.argv.index('--output')
- if idx + 1 < len(sys.argv):
- output_file = sys.argv[idx + 1]
- checker.export_report(output_file)
-
- if '--json' in sys.argv or '--json-output' in sys.argv:
- if '--json-output' in sys.argv:
- idx = sys.argv.index('--json-output')
- if idx + 1 >= len(sys.argv):
- print("[ERROR] --json-output requires a path")
- sys.exit(1)
- json_output = Path(sys.argv[idx + 1])
- else:
- json_output = _default_json_report_path(checker, target, stage)
- checker.export_json_report(
- str(json_output),
- target=target,
- stage=stage,
- )
-
- # Return exit code
- if checker.summary['errors'] > 0:
- sys.exit(1)
- else:
- sys.exit(0)
+from console_encoding import configure_utf8_stdio # noqa: E402
+configure_utf8_stdio()
-if __name__ == '__main__':
+from svg_quality.checker import ( # noqa: E402
+ CANVAS_FORMATS,
+ FONT_SIZE_ANCHOR_TOLERANCE_PX,
+ HEX_VALUE_RE,
+ IMAGE_DOWNSIZE_WARN_MIN_BYTES,
+ IMAGE_DOWNSIZE_WARN_RATIO,
+ SPARSE_UNDECLARED_FONT_SIZE_MAX_OCCURRENCES,
+ SVG_NS,
+ XLINK_NS,
+ SVGQualityChecker,
+)
+from svg_quality.cli import main, print_usage # noqa: E402
+
+__all__ = [
+ "CANVAS_FORMATS",
+ "FONT_SIZE_ANCHOR_TOLERANCE_PX",
+ "HEX_VALUE_RE",
+ "IMAGE_DOWNSIZE_WARN_MIN_BYTES",
+ "IMAGE_DOWNSIZE_WARN_RATIO",
+ "SPARSE_UNDECLARED_FONT_SIZE_MAX_OCCURRENCES",
+ "SVG_NS",
+ "SVGQualityChecker",
+ "XLINK_NS",
+ "main",
+ "print_usage",
+]
+
+
+if __name__ == "__main__":
main()