AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
fix(image-pipeline): close fidelity and transaction gaps
hugohe3f438ff6c5f8d
diff --git a/skills/ppt-master/scripts/finalize_svg.py b/skills/ppt-master/scripts/finalize_svg.pyindex 9e3fd38d..ffc88d45 100644--- a/skills/ppt-master/scripts/finalize_svg.py+++ b/skills/ppt-master/scripts/finalize_svg.py@@ -39,6 +39,7 @@ import sysimport shutilimport argparsefrom pathlib import Path+from typing import TextIOfrom xml.etree import ElementTree as ETfrom console_encoding import configure_utf8_stdio@@ -63,10 +64,11 @@ from svg_to_pptx.use_expander import ()-def safe_print(text: str) -> None:+def safe_print(text: str, *, file: TextIO | None = None) -> None:"""Print text while tolerating Windows terminal encoding limits."""+ stream = file or sys.stdouttry:- print(text)+ print(text, file=stream)except UnicodeEncodeError:replacements = {chr(0x23F3): "[..]",@@ -79,7 +81,7 @@ def safe_print(text: str) -> None:}for source, target in replacements.items():text = text.replace(source, target)- print(text)+ print(text, file=stream)def process_flatten_text(svg_file: Path, verbose: bool = False) -> bool:@@ -236,11 +238,17 @@ def finalize_project()img_count += countimg_errors += errs+ if img_errors:+ safe_print(+ f"[ERROR] Image alignment/embedding failed for "+ f"{img_errors} image(s); svg_final was not published",+ file=sys.stderr,+ )+ shutil.rmtree(svg_final, ignore_errors=True)+ return Falseif not quiet:if img_count > 0:msg = f" {img_count} image(s) aligned + embedded"- if img_errors:- msg += f" ({img_errors} error(s))"safe_print(msg)if office_vector_count:safe_print(diff --git a/skills/ppt-master/scripts/image_gen.py b/skills/ppt-master/scripts/image_gen.pyindex 00558d47..ce01a34f 100644--- a/skills/ppt-master/scripts/image_gen.py+++ b/skills/ppt-master/scripts/image_gen.py@@ -464,6 +464,34 @@ VALID_IMAGE_TYPES = ()+def _validate_bare_output_name(+ value: str,+ *,+ field_name: str,+ require_extension: bool = False,+ reject_parent_marker: bool = False,+) -> Path:+ """Require one cross-platform-safe basename, optionally with an extension."""+ value_path = Path(value)+ if (+ not value.strip()+ or value in {".", ".."}+ or reject_parent_marker and ".." in value+ or "/" in value+ or "\\" in value+ or ":" in value+ or value_path.is_absolute()+ or value_path.name != value+ ):+ raise ValueError(+ f"{field_name} must be a bare filename without path components, "+ f"got {value!r}"+ )+ if require_extension and not value_path.suffix:+ raise ValueError(f"{field_name} must include an extension, got {value!r}")+ return value_path++def load_manifest(path: str) -> dict:"""Load and validate an `image_prompts.json` manifest.@@ -531,7 +559,7 @@ def load_manifest(path: str) -> dict:if not isinstance(items, list) or not items:raise ValueError(f"{path}: 'items' must be a non-empty array")- seen_filenames: set[str] = set()+ claimed_outputs: dict[str, str] = {}seen_stems: set[str] = set()missing_page_role = 0missing_text_policy = 0@@ -614,6 +642,7 @@ def load_manifest(path: str) -> dict:raise ValueError(f"{prefix} field 'last_error' must be a string")has_slice_grid = "slice_grid" in itemhas_slice_names = "slice_names" in item+ slice_outputs: list[str] = []if has_slice_grid != has_slice_names:raise ValueError(f"{prefix} fields 'slice_grid' and 'slice_names' must appear together"@@ -647,20 +676,11 @@ def load_manifest(path: str) -> dict:)normalized_outputs: set[str] = set()for name in names:- name_path = Path(name)- if (- name in {".", ".."}- or ".." in name- or "/" in name- or "\\" in name- or ":" in name- or name_path.is_absolute()- or name_path.name != name- ):- raise ValueError(- f"{prefix} slice output name {name!r} must be a safe "- "bare filename"- )+ name_path = _validate_bare_output_name(+ name,+ field_name=f"{prefix} slice output name",+ reject_parent_marker=True,+ )if name_path.suffix and name_path.suffix.lower() != ".png":raise ValueError(f"{prefix} slice output name {name!r} must omit its "@@ -675,33 +695,40 @@ def load_manifest(path: str) -> dict:f"{output_name!r}")normalized_outputs.add(output_name)+ slice_outputs.append(output_name)fname = item["filename"]- filename_path = Path(fname)- if (- filename_path.is_absolute()- or filename_path.name != fname- or "/" in fname- or "\\" in fname- or fname in {".", ".."}- ):- raise ValueError(- f"{prefix} field 'filename' must be one basename, got '{fname}'"- )- if not filename_path.suffix:+ filename_path = _validate_bare_output_name(+ fname,+ field_name=f"{prefix} field 'filename'",+ require_extension=True,+ )+ normalized_filename = fname.casefold()+ if normalized_filename in claimed_outputs:raise ValueError(- f"{prefix} field 'filename' must include an extension, got '{fname}'"+ f"{prefix} output filename {fname!r} conflicts with "+ f"{claimed_outputs[normalized_filename]} (case-insensitive)")- if fname in seen_filenames:- raise ValueError(f"{prefix} duplicate filename '{fname}'")- seen_filenames.add(fname)- stem = filename_path.stem+ claimed_outputs[normalized_filename] = f"manifest output {fname!r}"++ stem = filename_path.stem.casefold()if stem in seen_stems:raise ValueError(- f"{prefix} duplicate filename stem '{stem}' would reuse backend output"+ f"{prefix} duplicate filename stem '{filename_path.stem}' "+ "would reuse backend output")seen_stems.add(stem)+ for output_name in slice_outputs:+ if output_name in claimed_outputs:+ raise ValueError(+ f"{prefix} slice output {output_name!r} conflicts with "+ f"{claimed_outputs[output_name]} (case-insensitive)"+ )+ claimed_outputs[output_name] = (+ f"slice output {output_name!r} from items[{i}]"+ )+legacy_parts = []if missing_page_role:legacy_parts.append(@@ -791,6 +818,14 @@ def _run_manifest(manifest: dict, manifest_path: str, backend_module, *,Returns (ok_count, failed_count, skipped_count)."""+ manifest_output_dir = Path(manifest_path).resolve().parent+ if Path(output_dir).resolve() != manifest_output_dir:+ raise ValueError(+ "Manifest outputs must stay beside image_prompts.json: "+ f"expected {manifest_output_dir}, got {Path(output_dir).resolve()}"+ )+ output_dir = str(manifest_output_dir)+from image_backends.backend_common import (is_rate_limit_error,validate_image_file,@@ -1144,6 +1179,15 @@ def main() -> None:args = parser.parse_args()+ if args.filename is not None:+ try:+ _validate_bare_output_name(+ args.filename,+ field_name="--filename",+ )+ except ValueError as exc:+ parser.error(str(exc))+if args.reference_image is not None:# Reference editing is a single-image-only enhancement; keep it out of# the manifest / sidecar / list surfaces entirely.@@ -1185,8 +1229,25 @@ def main() -> None:print(f"Rendered Markdown sidecar: {md_path}")return+ manifest = None+ manifest_output_dir = Noneif args.manifest:+ if not os.path.isfile(args.manifest):+ print(f"Error: manifest file not found: {args.manifest}")+ sys.exit(1)_guard_confirmed_non_api_path(args.manifest)+ try:+ manifest = load_manifest(args.manifest)+ except ValueError as e:+ print(f"Error: {e}")+ sys.exit(1)+ manifest_output_dir = Path(args.manifest).resolve().parent+ if args.output and Path(args.output).resolve() != manifest_output_dir:+ print(+ "Error: --output cannot redirect manifest items outside the "+ f"manifest directory ({manifest_output_dir})"+ )+ sys.exit(1)try:_load_image_env_file()@@ -1203,22 +1264,13 @@ def main() -> None:print(f"Using backend: {backend_name}\n")if args.manifest:- if not os.path.isfile(args.manifest):- print(f"Error: manifest file not found: {args.manifest}")- sys.exit(1)- try:- manifest = load_manifest(args.manifest)- except ValueError as e:- print(f"Error: {e}")- sys.exit(1)-concurrency = _resolve_concurrency(args.concurrency)try:_, failed, _ = _run_manifest(manifest, args.manifest, backend,initial_concurrency=concurrency,image_size=args.image_size,- output_dir=args.output or str(Path(args.manifest).parent),+ output_dir=str(manifest_output_dir),model=args.model,)except KeyboardInterrupt:diff --git a/skills/ppt-master/scripts/image_search.py b/skills/ppt-master/scripts/image_search.pyindex 0eb7bc57..0dac009f 100644--- a/skills/ppt-master/scripts/image_search.py+++ b/skills/ppt-master/scripts/image_search.py@@ -46,9 +46,10 @@ import osimport sysimport tempfileimport threading+from dataclasses import dataclassfrom datetime import datetime, timezonefrom pathlib import Path-from typing import Optional+from typing import Callable, Optionalimport requests@@ -113,6 +114,8 @@ SEARCH_VALID_STATUSES = {# (see image-searcher.md §8); only Pending/Failed rows are retried on re-run.SEARCH_RETRYABLE_STATUSES = {SEARCH_STATUS_PENDING, SEARCH_STATUS_FAILED}SEARCH_REQUIRED_ITEM_FIELDS = ("filename", "query", "status")+SEARCH_FAILURE_NO_MATCH = "no-match"+SEARCH_FAILURE_RETRYABLE = "retryable"_WEAK_REQUIRED_TERM_PARTS = frozenset({"ancient town",@@ -232,48 +235,103 @@ def _is_keyed_provider_unconfigured(provider_name: str, exc: Exception) -> bool:return "API_KEY" in str(exc)+@dataclass+class SearchDownloadResult:+ """Carry one search result without collapsing no-match and retryable failures."""++ candidate: Optional[AssetCandidate] = None+ provider_name: Optional[str] = None+ stage: Optional[str] = None+ actual_dimensions: Optional[tuple[int, int]] = None+ staged_path: Optional[Path] = None+ output_path: Optional[Path] = None+ failure_kind: Optional[str] = None+ error: Optional[str] = None+++class DownloadQualityError(ValueError):+ """Signal a readable candidate that fails the requested image contract."""+++def _is_pillow_decompression_error(exc: BaseException) -> bool:+ """Recognize Pillow's safety exception without making Pillow a hard import."""+ cls = type(exc)+ return (+ cls.__name__ == "DecompressionBombError"+ and cls.__module__.startswith("PIL.")+ )+++def _is_recoverable_image_error(exc: BaseException) -> bool:+ """Return whether a provider/download/image failure can be reported cleanly."""+ return isinstance(+ exc,+ (+ requests.RequestException,+ OSError,+ RuntimeError,+ SyntaxError,+ ValueError,+ ),+ ) or _is_pillow_decompression_error(exc)++def _try_provider(name: str,request: ImageSearchRequest,license_tier_filter: str,-) -> Optional[list[AssetCandidate]]:- """Run one provider; print and swallow recoverable errors, return None- so the dispatcher can try the next provider."""+) -> tuple[Optional[list[AssetCandidate]], Optional[str]]:+ """Run one provider while preserving whether it errored or returned no rows."""try:module = _load_provider(name)- return module.search(request, license_tier_filter=license_tier_filter)+ return module.search(request, license_tier_filter=license_tier_filter), Noneexcept RuntimeError as exc:if _is_keyed_provider_unconfigured(name, exc):print(f" [{name}] skipped: {exc}",file=sys.stderr,)+ return None, Noneelse:print(f" [{name}] error: {exc}", file=sys.stderr)- return None- except (requests.RequestException, ValueError) as exc:+ return None, f"{name}: {exc}"+ except (requests.RequestException, OSError, ValueError) as exc:print(f" [{name}] error: {exc}", file=sys.stderr)- return None+ return None, f"{name}: {exc}"+ except ImportError as exc:+ print(f" [{name}] error: {exc}", file=sys.stderr)+ return None, f"{name}: provider import failed: {exc}"# ---------------------------------------------------------------------------# Post-download quality validation# ----------------------------------------------------------------------------_MIN_DOWNLOAD_PIXELS = 800 * 600 # reject anything below ~480K px+_MIN_DOWNLOAD_PIXELS = 800 * 600 # preserve the existing absolute thumbnail floor-def _validate_downloaded_quality(path: Path) -> bool:- """Reject images that are too small after download.+def _validate_downloaded_quality(+ path: Path,+ *,+ min_width: int = 0,+ min_height: int = 0,+ enforce_thumbnail_floor: bool = True,+) -> bool:+ """Reject unreadable images and actual EXIF-oriented dimensions below contract.Upstream metadata can be inaccurate (e.g. Openverse aggregates rawpixelwhich only exposes a preview). This function checks what was actually- written to disk and rejects thumbnails / previews.+ written to disk. Automated paths also reject thumbnails/previews; explicit+ manual paths may disable that absolute floor while retaining their own+ requested dimensions."""try:from PIL import Image, ImageOps # type: ignore- except ImportError:- return True # can't check without Pillow; assume OK+ except ImportError as exc:+ raise RuntimeError(+ "Pillow is required to validate downloaded image dimensions. "+ "Install it with: pip install Pillow"+ ) from exctry:with Image.open(path) as im:oriented = ImageOps.exif_transpose(im)@@ -281,7 +339,14 @@ def _validate_downloaded_quality(path: Path) -> bool:w, h = oriented.sizeif oriented is not im:oriented.close()- if w * h < _MIN_DOWNLOAD_PIXELS:+ if w < min_width or h < min_height:+ print(+ f" rejected: downloaded image dimensions {w}x{h} are below "+ f"the requested minimum {min_width}x{min_height}",+ file=sys.stderr,+ )+ return False+ if enforce_thumbnail_floor and w * h < _MIN_DOWNLOAD_PIXELS:print(f" rejected: downloaded image too small "f"({w}x{h} = {w*h:,} px < {_MIN_DOWNLOAD_PIXELS:,} px minimum)",@@ -289,7 +354,9 @@ def _validate_downloaded_quality(path: Path) -> bool:)return Falsereturn True- except (OSError, SyntaxError, ValueError) as exc:+ except Exception as exc:+ if not _is_recoverable_image_error(exc):+ raiseprint(f" rejected: downloaded file is not a readable image ({exc})",file=sys.stderr,@@ -297,6 +364,118 @@ def _validate_downloaded_quality(path: Path) -> bool:return False+def _stage_validated_image(+ url: str,+ output_path: Path,+ *,+ min_width: int,+ min_height: int,+ enforce_thumbnail_floor: bool = True,+) -> tuple[Path, tuple[int, int]]:+ """Download and validate beside the target without changing the canonical."""+ output_path.parent.mkdir(parents=True, exist_ok=True)+ fd, temp_name = tempfile.mkstemp(+ prefix=f".{output_path.stem}.",+ suffix=output_path.suffix,+ dir=str(output_path.parent),+ )+ os.close(fd)+ temp_path = Path(temp_name)+ keep_temp = False+ try:+ download_image(+ url,+ str(temp_path),+ headers={"User-Agent": USER_AGENT},+ )+ if not _validate_downloaded_quality(+ temp_path,+ min_width=min_width,+ min_height=min_height,+ enforce_thumbnail_floor=enforce_thumbnail_floor,+ ):+ raise DownloadQualityError(+ "downloaded image did not satisfy the requested dimensions/readability"+ )+ actual_dimensions = _measure_actual_image(temp_path)+ if actual_dimensions is None:+ raise DownloadQualityError(+ "downloaded image dimensions could not be measured"+ )+ keep_temp = True+ return temp_path, actual_dimensions+ finally:+ if not keep_temp:+ try:+ temp_path.unlink(missing_ok=True)+ except OSError:+ pass+++def _commit_staged_image(+ staged_path: Path,+ target_path: Path,+ manifest_writer: Callable[[], Path],+) -> Path:+ """Install a staged image and roll it back if provenance cannot be written."""+ target_path.parent.mkdir(parents=True, exist_ok=True)+ backup_path: Optional[Path] = None+ installed = False++ try:+ if target_path.exists():+ if not target_path.is_file():+ raise RuntimeError(+ f"image target exists but is not a regular file: {target_path}"+ )+ fd, backup_name = tempfile.mkstemp(+ prefix=f".{target_path.stem}.backup.",+ suffix=target_path.suffix,+ dir=str(target_path.parent),+ )+ os.close(fd)+ reserved_backup_path = Path(backup_name)+ reserved_backup_path.unlink()+ os.replace(target_path, reserved_backup_path)+ backup_path = reserved_backup_path++ os.replace(staged_path, target_path)+ installed = True+ written = manifest_writer()+ except Exception as exc:+ rollback_errors: list[str] = []+ if installed:+ try:+ target_path.unlink(missing_ok=True)+ except OSError as rollback_exc:+ rollback_errors.append(f"cannot remove new target: {rollback_exc}")+ if backup_path is not None and backup_path.exists():+ try:+ os.replace(backup_path, target_path)+ except OSError as rollback_exc:+ rollback_errors.append(f"cannot restore prior target: {rollback_exc}")+ if rollback_errors:+ raise RuntimeError(+ f"{exc}; image rollback also failed: {'; '.join(rollback_errors)}"+ ) from exc+ raise+ else:+ if backup_path is not None:+ try:+ backup_path.unlink(missing_ok=True)+ except OSError as exc:+ print(+ f" warning: could not remove image backup {backup_path}: {exc}",+ file=sys.stderr,+ )+ return written+ finally:+ try:+ staged_path.unlink(missing_ok=True)+ except OSError:+ pass++def _write_review_copy(src: Path, dest_dir: Path, name: str, max_side: int = 1024) -> Optional[Path]:@@ -311,6 +490,7 @@ def _write_review_copy(from PIL import Image, ImageOps # type: ignoreexcept ImportError:return None+ review_path: Optional[Path] = Nonetry:dest_dir.mkdir(parents=True, exist_ok=True)review_path = dest_dir / f"{Path(name).stem}.jpg"@@ -323,7 +503,14 @@ def _write_review_copy(if oriented is not im:oriented.close()return review_path- except (OSError, ValueError):+ except Exception as exc:+ if not _is_recoverable_image_error(exc):+ raise+ if review_path is not None:+ try:+ review_path.unlink(missing_ok=True)+ except OSError:+ passreturn None@@ -332,6 +519,8 @@ def _save_candidates_pool(output_dir: Path,stem: str,selected_filename: str,+ min_width: int,+ min_height: int,max_candidates: int = 4,) -> None:"""Download top-N candidates into ``candidates/<stem>/`` and write@@ -347,38 +536,60 @@ def _save_candidates_pool(suffix = Path(candidate.download_url.split("?")[0]).suffix or ".jpg"cand_filename = f"candidate_{idx + 1:02d}{suffix}"cand_path = cand_dir / cand_filename+ keep_candidate = Falsetry:download_image(candidate.download_url,str(cand_path),headers={"User-Agent": USER_AGENT},)- if not _validate_downloaded_quality(cand_path):- cand_path.unlink(missing_ok=True)+ if not _validate_downloaded_quality(+ cand_path,+ min_width=min_width,+ min_height=min_height,+ ):continue- except (requests.RequestException, OSError, RuntimeError, ValueError):+ actual_dim = _measure_actual_image(cand_path)+ review_path = _write_review_copy(+ cand_path,+ cand_dir / "review",+ cand_filename,+ )+ idx += 1+ pool.append({+ "rank": idx,+ "score": round(score, 2),+ "filename": cand_filename,+ "review": f"review/{review_path.name}" if review_path else None,+ "provider": provider_name,+ "title": candidate.title,+ "author": candidate.author,+ "source_page_url": candidate.source_page_url,+ "download_url": candidate.download_url,+ "license_name": candidate.license_name,+ "license_url": candidate.license_url,+ "license_tier": candidate.license_tier,+ "attribution_required": (+ candidate.license_tier == "attribution-required"+ ),+ "attribution_text": build_attribution_text(+ selected_filename,+ candidate,+ ),+ "width": actual_dim[0] if actual_dim else candidate.width,+ "height": actual_dim[1] if actual_dim else candidate.height,+ })+ keep_candidate = True+ except Exception as exc:+ if not _is_recoverable_image_error(exc):+ raisecontinue- idx += 1- actual_dim = _measure_actual_image(cand_path)- review_path = _write_review_copy(cand_path, cand_dir / "review", cand_filename)- pool.append({- "rank": idx,- "score": round(score, 2),- "filename": cand_filename,- "review": f"review/{review_path.name}" if review_path else None,- "provider": provider_name,- "title": candidate.title,- "author": candidate.author,- "source_page_url": candidate.source_page_url,- "download_url": candidate.download_url,- "license_name": candidate.license_name,- "license_url": candidate.license_url,- "license_tier": candidate.license_tier,- "attribution_required": candidate.license_tier == "attribution-required",- "attribution_text": build_attribution_text(selected_filename, candidate),- "width": actual_dim[0] if actual_dim else candidate.width,- "height": actual_dim[1] if actual_dim else candidate.height,- })+ finally:+ if not keep_candidate:+ try:+ cand_path.unlink(missing_ok=True)+ except OSError:+ passif pool:meta = {@@ -388,10 +599,7 @@ def _save_candidates_pool("candidates": pool,}meta_path = cand_dir / "candidates.json"- meta_path.write_text(- json.dumps(meta, indent=2, ensure_ascii=False) + "\n",- encoding="utf-8",- )+ _write_json_atomic(meta_path, meta)print(f" candidates: {cand_dir}/ ({len(pool)} saved)", file=sys.stderr)@@ -403,7 +611,7 @@ def search_and_download(strict_no_attribution: bool,save_candidates: bool = False,max_candidates: int = 4,-) -> tuple[Optional[AssetCandidate], Optional[str], Optional[str]]:+) -> SearchDownloadResult:"""Find a candidate AND successfully download it.By default only the best match is downloaded. When ``save_candidates``@@ -411,19 +619,24 @@ def search_and_download(``candidates/<stem>/`` so the agent can review and ``--promote`` abetter fit when the best match does not pass visual confirmation.- Returns ``(candidate, provider_name, stage)`` for the successfully- downloaded image, or ``(None, None, None)`` if every combination- failed.+ Returns a structured result so batch mode can keep transient/provider+ failures retryable while treating a complete no-match as terminal."""license_filters: list[str] = (["no-attribution-only"] if strict_no_attribution else ["all"])+ provider_errors: list[str] = []+ download_errors: list[str] = []+ quality_rejections = 0+for stage in license_filters:ranked: list[tuple[float, str, AssetCandidate]] = []for provider_name in providers:print(f" -> trying {provider_name} ({stage}) ...", file=sys.stderr)- candidates = _try_provider(provider_name, request, stage)+ candidates, provider_error = _try_provider(provider_name, request, stage)+ if provider_error:+ provider_errors.append(provider_error)if not candidates:continue@@ -449,10 +662,23 @@ def search_and_download(# --- Save candidate pool (before picking the winner) ---if save_candidates and sorted_ranked:stem = Path(output_path).stem- _save_candidates_pool(- sorted_ranked, output_path.parent, stem, output_path.name,- max_candidates=max_candidates,- )+ try:+ _save_candidates_pool(+ sorted_ranked,+ output_path.parent,+ stem,+ output_path.name,+ request.min_width,+ request.min_height,+ max_candidates=max_candidates,+ )+ except Exception as exc:+ if not _is_recoverable_image_error(exc):+ raise+ print(+ f" warning: candidate pool could not be saved: {exc}",+ file=sys.stderr,+ )# --- Pick the best downloadable candidate ---for _score, provider_name, candidate in sorted_ranked:@@ -460,28 +686,47 @@ def search_and_download(# exist in the candidates dir — but we still need the# primary copy at output_path.try:- download_image(+ staged_path, actual_dimensions = _stage_validated_image(candidate.download_url,- str(output_path),- headers={"User-Agent": USER_AGENT},+ output_path,+ min_width=request.min_width,+ min_height=request.min_height,)- if not _validate_downloaded_quality(output_path):- output_path.unlink(missing_ok=True)- continue- review = _write_review_copy(- output_path, output_path.parent / ".review", output_path.name+ return SearchDownloadResult(+ candidate=candidate,+ provider_name=provider_name,+ stage=stage,+ actual_dimensions=actual_dimensions,+ staged_path=staged_path,+ output_path=output_path,)- if review is not None:- print(f" review copy: {review}", file=sys.stderr)- return candidate, provider_name, stage- except (requests.RequestException, OSError, RuntimeError, ValueError) as exc:+ except DownloadQualityError:+ quality_rejections += 1+ continue+ except Exception as exc:+ if not _is_recoverable_image_error(exc):+ raiseprint(f" download failed for {candidate.title!r}: {exc}",file=sys.stderr,)+ download_errors.append(f"{provider_name}/{candidate.title}: {exc}")continue- return None, None, None+ retryable_errors = provider_errors + download_errors+ if retryable_errors:+ return SearchDownloadResult(+ failure_kind=SEARCH_FAILURE_RETRYABLE,+ error="; ".join(retryable_errors)[:500],+ )++ detail = "no acceptable candidate across all providers/stages"+ if quality_rejections:+ detail += f" ({quality_rejections} candidate(s) failed actual-size/readability gates)"+ return SearchDownloadResult(+ failure_kind=SEARCH_FAILURE_NO_MATCH,+ error=detail,+ )# ---------------------------------------------------------------------------@@ -533,7 +778,9 @@ def _measure_actual_image(path: Path) -> Optional[tuple[int, int]]:finally:if oriented is not im:oriented.close()- except (OSError, ValueError):+ except Exception as exc:+ if not _is_recoverable_image_error(exc):+ raisereturn None@@ -624,7 +871,7 @@ def _read_existing_manifest(path: Path) -> dict:raise RuntimeError(f"existing image sources manifest contains a non-object item: {path}")- seen_filenames: set[str] = set()+ seen_filenames: dict[str, str] = {}for index, item in enumerate(items):filename = item.get("filename")if not isinstance(filename, str):@@ -638,12 +885,14 @@ def _read_existing_manifest(path: Path) -> dict:raise RuntimeError(f"existing image sources manifest items[{index}]: {exc}: {path}") from exc- if filename in seen_filenames:+ normalized_filename = filename.casefold()+ if normalized_filename in seen_filenames:raise RuntimeError(- f"existing image sources manifest contains duplicate filename "- f"{filename!r}: {path}"+ f"existing image sources manifest filename {filename!r} conflicts "+ f"with {seen_filenames[normalized_filename]!r} "+ f"(case-insensitive): {path}")- seen_filenames.add(filename)+ seen_filenames[normalized_filename] = filenamereturn payload@@ -672,9 +921,37 @@ def write_sources_manifest(path: Path, item: dict) -> Path:entry that targets the same filename."""manifest_path = Path(path)payload = _read_existing_manifest(manifest_path)+ filename = item.get("filename")+ if not isinstance(filename, str):+ raise RuntimeError("new image source item requires a string filename")+ try:+ _validate_bare_filename(filename)+ except ValueError as exc:+ raise RuntimeError(f"new image source item: {exc}") from excitems: list[dict] = list(payload.get("items") or [])- items = [i for i in items if i.get("filename") != item["filename"]]+ normalized_filename = filename.casefold()+ differently_cased = next(+ (+ existing["filename"]+ for existing in items+ if isinstance(existing.get("filename"), str)+ and existing["filename"].casefold() == normalized_filename+ and existing["filename"] != filename+ ),+ None,+ )+ if differently_cased is not None:+ raise RuntimeError(+ f"new image source filename {filename!r} conflicts with existing "+ f"{differently_cased!r} (case-insensitive)"+ )+ items = [+ i+ for i in items+ if not isinstance(i.get("filename"), str)+ or i["filename"].casefold() != normalized_filename+ ]items.append(item)payload["items"] = items@@ -701,9 +978,9 @@ def promote_candidate("""Replace the primary image with a candidate from the pool.Steps:- 1. Copy ``candidates/<stem>/<candidate_filename>`` → ``<target_filename>``- 2. Update ``candidates.json`` selected field- 3. Update ``image_sources.json`` with the candidate's metadata+ 1. Stage and validate ``candidates/<stem>/<candidate_filename>``+ 2. Replace the canonical image and its provenance as one rollback unit+ 3. Advance ``candidates.json`` only after provenance succeeds"""import shutil@@ -724,16 +1001,38 @@ def promote_candidate(cand_dir = output_dir / "candidates" / stemcand_meta_path = cand_dir / "candidates.json"- if not cand_meta_path.exists():+ if not cand_meta_path.is_file():print(f"Error: {cand_meta_path} not found.", file=sys.stderr)return 1- meta = json.loads(cand_meta_path.read_text(encoding="utf-8"))+ try:+ meta = json.loads(cand_meta_path.read_text(encoding="utf-8"))+ except (OSError, json.JSONDecodeError) as exc:+ print(f"Error: cannot read {cand_meta_path}: {exc}", file=sys.stderr)+ return 1+ if not isinstance(meta, dict) or not isinstance(meta.get("candidates"), list):+ print(+ f"Error: {cand_meta_path} must contain a candidates array.",+ file=sys.stderr,+ )+ return 1candidates = meta.get("candidates", [])- entry = next((c for c in candidates if c["filename"] == candidate_filename), None)+ entry = next(+ (+ candidate+ for candidate in candidates+ if isinstance(candidate, dict)+ and candidate.get("filename") == candidate_filename+ ),+ None,+ )if entry is None:- names = [c["filename"] for c in candidates]+ names = [+ str(candidate.get("filename"))+ for candidate in candidates+ if isinstance(candidate, dict) and candidate.get("filename")+ ]print(f"Error: '{candidate_filename}' not found. Available: {', '.join(names)}",file=sys.stderr,@@ -742,63 +1041,135 @@ def promote_candidate(src_path = cand_dir / candidate_filenamedst_path = output_dir / target_filename- if not src_path.exists():+ if not src_path.is_file():print(f"Error: {src_path} does not exist on disk.", file=sys.stderr)return 1- shutil.copy2(str(src_path), str(dst_path))- print(f" promoted: {candidate_filename} → {target_filename}", file=sys.stderr)- review = _write_review_copy(dst_path, output_dir / ".review", target_filename)- if review is not None:- print(f" review copy: {review}", file=sys.stderr)-- # Update candidates.json- meta["selected"] = candidate_filename- _write_json_atomic(cand_meta_path, meta)-- # Update image_sources.json- actual_dim = _measure_actual_image(dst_path)- w = actual_dim[0] if actual_dim else entry.get("width", 0)- h = actual_dim[1] if actual_dim else entry.get("height", 0)-items: list[dict] = list(manifest.get("items") or [])+ target_item: Optional[dict] = Nonefor item in items:- if item.get("filename") == target_filename:- item["provider"] = entry["provider"]- item["title"] = entry["title"]- item["author"] = entry["author"]- item["source_page_url"] = entry["source_page_url"]- item["download_url"] = entry["download_url"]- item["license_name"] = entry["license_name"]- item["license_url"] = entry.get("license_url", "")- item["license_tier"] = entry["license_tier"]- item["attribution_required"] = entry.get("attribution_required", False)- # Recompute the credit from the promoted candidate — never carry the- # replaced image's attribution_text (wrong author/title/source).- item["attribution_text"] = build_attribution_text(- target_filename,- AssetCandidate(- provider=entry.get("provider", ""),- title=entry.get("title", ""),- source_page_url=entry.get("source_page_url", ""),- license_name=entry.get("license_name", ""),- license_url=entry.get("license_url", ""),- license_tier=entry.get("license_tier", ""),- width=w,- height=h,- download_url=entry.get("download_url", ""),- author=entry.get("author", ""),- ),- )- item["width"] = w- item["height"] = h- item.pop("metadata_dimensions", None)- item["status"] = "promoted"+ filename = item.get("filename")+ if (+ isinstance(filename, str)+ and filename.casefold() == target_filename.casefold()+ ):+ target_item = itembreak- manifest["items"] = items- manifest["generated_at"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")- _write_json_atomic(mpath, manifest)+ if target_item is None:+ print(+ f"Error: {mpath} has no provenance entry for {target_filename!r}.",+ file=sys.stderr,+ )+ return 1+ if target_item["filename"] != target_filename:+ print(+ f"Error: target filename casing {target_filename!r} conflicts with "+ f"provenance filename {target_item['filename']!r}.",+ file=sys.stderr,+ )+ return 1++ output_dir.mkdir(parents=True, exist_ok=True)+ fd, staged_name = tempfile.mkstemp(+ prefix=f".{dst_path.stem}.promote.",+ suffix=dst_path.suffix,+ dir=str(dst_path.parent),+ )+ os.close(fd)+ staged_path = Path(staged_name)+ try:+ shutil.copy2(src_path, staged_path)+ if not _validate_downloaded_quality(+ staged_path,+ enforce_thumbnail_floor=False,+ ):+ raise DownloadQualityError(+ "candidate image did not satisfy the readability/size gate"+ )+ actual_dim = _measure_actual_image(staged_path)+ if actual_dim is None:+ raise DownloadQualityError("candidate dimensions could not be measured")+ w, h = actual_dim+ if w < 1 or h < 1:+ raise DownloadQualityError("candidate dimensions must be positive")+ if w * h < _MIN_DOWNLOAD_PIXELS:+ print(+ f" warning: explicitly promoted image is low resolution ({w}x{h})",+ file=sys.stderr,+ )++ target_item["provider"] = entry.get("provider", "")+ target_item["title"] = entry.get("title", "")+ target_item["author"] = entry.get("author", "")+ target_item["source_page_url"] = entry.get("source_page_url", "")+ target_item["download_url"] = entry.get("download_url", "")+ target_item["license_name"] = entry.get("license_name", "")+ target_item["license_url"] = entry.get("license_url", "")+ target_item["license_tier"] = entry.get("license_tier", "")+ target_item["attribution_required"] = entry.get(+ "attribution_required",+ False,+ )+ # Recompute the credit from the promoted candidate — never carry the+ # replaced image's attribution_text (wrong author/title/source).+ target_item["attribution_text"] = build_attribution_text(+ target_filename,+ AssetCandidate(+ provider=entry.get("provider", ""),+ title=entry.get("title", ""),+ source_page_url=entry.get("source_page_url", ""),+ license_name=entry.get("license_name", ""),+ license_url=entry.get("license_url", ""),+ license_tier=entry.get("license_tier", ""),+ width=w,+ height=h,+ download_url=entry.get("download_url", ""),+ author=entry.get("author", ""),+ ),+ )+ target_item["width"] = w+ target_item["height"] = h+ target_item.pop("metadata_dimensions", None)+ target_item["status"] = "promoted"+ manifest["items"] = items+ manifest["generated_at"] = (+ datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")+ )++ _commit_staged_image(+ staged_path,+ dst_path,+ lambda: _write_json_atomic(mpath, manifest),+ )+ except Exception as exc:+ if not _is_recoverable_image_error(exc):+ raise+ print(f"Error: candidate promotion failed: {exc}", file=sys.stderr)+ return 1+ finally:+ try:+ staged_path.unlink(missing_ok=True)+ except OSError:+ pass++ print(f" promoted: {candidate_filename} → {target_filename}", file=sys.stderr)print(f" manifest updated: {mpath}", file=sys.stderr)++ # The selection marker must never move ahead of canonical provenance.+ meta["selected"] = candidate_filename+ try:+ _write_json_atomic(cand_meta_path, meta)+ except OSError as exc:+ print(+ f"Error: image was promoted, but {cand_meta_path} could not be updated: "+ f"{exc}",+ file=sys.stderr,+ )+ return 1++ review = _write_review_copy(dst_path, output_dir / ".review", target_filename)+ if review is not None:+ print(f" review copy: {review}", file=sys.stderr)return 0@@ -818,6 +1189,8 @@ def fetch_url_replace(search_query: str = "",orientation: str = "",required_terms: tuple[str, ...] = (),+ min_width: int = 1200,+ min_height: int = 800,) -> int:"""Download a user-supplied image URL into the target and record it.@@ -840,28 +1213,50 @@ def fetch_url_replace((itemfor item in existing_manifest.get("items", [])- if item.get("filename") == target_filename+ if isinstance(item.get("filename"), str)+ and item["filename"].casefold() == target_filename.casefold()),{},)+ if prior and prior["filename"] != target_filename:+ print(+ f"Error: target filename casing {target_filename!r} conflicts with "+ f"provenance filename {prior['filename']!r}.",+ file=sys.stderr,+ )+ return 1+ try:+ inherited_required_terms = _parse_required_terms(+ prior.get("required_terms")+ )+ except ValueError as exc:+ print(+ f"Error: existing provenance has invalid required_terms: {exc}",+ file=sys.stderr,+ )+ return 1+ final_required_terms = inherited_required_terms or required_termsoutput_dir.mkdir(parents=True, exist_ok=True)dst_path = output_dir / target_filenametry:- download_image(url, str(dst_path), headers={"User-Agent": USER_AGENT})- except (requests.RequestException, OSError, RuntimeError, ValueError) as exc:+ staged_path, actual_dim = _stage_validated_image(+ url,+ dst_path,+ min_width=min_width,+ min_height=min_height,+ enforce_thumbnail_floor=False,+ )+ except (+ DownloadQualityError,+ requests.RequestException,+ OSError,+ RuntimeError,+ ValueError,+ ) as exc:print(f"Error: failed to download {url}: {exc}", file=sys.stderr)return 1- if not dst_path.exists():- print(f"Error: download produced no file at {dst_path}", file=sys.stderr)- return 1-- print(f" fetched: {url} -> {target_filename}", file=sys.stderr)- review = _write_review_copy(dst_path, output_dir / ".review", target_filename)- if review is not None:- print(f" review copy: {review}", file=sys.stderr)- actual_dim = _measure_actual_image(dst_path)# Inherit page context (which slide / purpose / query this image serves)# from the entry being replaced; override only source / license / size /# status so the audit trail survives a manual swap.@@ -880,18 +1275,45 @@ def fetch_url_replace("license_url": "","license_tier": "manual","attribution_required": False,- "width": actual_dim[0] if actual_dim else 0,- "height": actual_dim[1] if actual_dim else 0,+ "width": actual_dim[0],+ "height": actual_dim[1],"attribution_text": "","status": "manual",- "note": "Manually supplied image URL; verifying usage rights is the user's responsibility.",+ "note": (+ "Manually supplied image URL; verifying usage rights is the user's "+ "responsibility."+ ),}- inherited_required_terms = _parse_required_terms(prior.get("required_terms"))- final_required_terms = inherited_required_terms or required_termsif final_required_terms:item["required_terms"] = list(final_required_terms)- written = write_sources_manifest(mpath, item)++ try:+ written = _commit_staged_image(+ staged_path,+ dst_path,+ lambda: write_sources_manifest(mpath, item),+ )+ except (+ OSError,+ RuntimeError,+ ValueError,+ ) as exc:+ print(+ f"Error: failed to replace {target_filename} and record provenance: {exc}",+ file=sys.stderr,+ )+ return 1+ finally:+ try:+ staged_path.unlink(missing_ok=True)+ except OSError:+ pass++ print(f" fetched: {url} -> {target_filename}", file=sys.stderr)print(f" manifest updated: {written}", file=sys.stderr)+ review = _write_review_copy(dst_path, output_dir / ".review", target_filename)+ if review is not None:+ print(f" review copy: {review}", file=sys.stderr)return 0@@ -910,6 +1332,8 @@ def load_search_manifest(path: str) -> dict:"""try:data = json.loads(Path(path).read_text(encoding="utf-8"))+ except OSError as exc:+ raise ValueError(f"Cannot read {path}: {exc}") from excexcept json.JSONDecodeError as exc:raise ValueError(f"Invalid JSON in {path}: {exc.msg} "@@ -925,7 +1349,7 @@ def load_search_manifest(path: str) -> dict:if not isinstance(items, list) or not items:raise ValueError(f"{path}: 'items' must be a non-empty array")- seen_filenames: set[str] = set()+ seen_filenames: dict[str, str] = {}for i, item in enumerate(items):prefix = f"{path}: items[{i}]"if not isinstance(item, dict):@@ -947,21 +1371,42 @@ def load_search_manifest(path: str) -> dict:_parse_required_terms(item["required_terms"])except ValueError as exc:raise ValueError(f"{prefix} {exc}") from exc+ for dimension_field in ("min_width", "min_height"):+ if dimension_field not in item:+ continue+ value = item[dimension_field]+ if (+ not isinstance(value, int)+ or isinstance(value, bool)+ or value < 1+ ):+ raise ValueError(+ f"{prefix} field '{dimension_field}' must be a positive integer"+ )fname = item["filename"]try:_validate_bare_filename(fname)except ValueError as exc:raise ValueError(f"{prefix} {exc}") from exc- if fname in seen_filenames:- raise ValueError(f"{prefix} duplicate filename '{fname}'")- seen_filenames.add(fname)+ normalized_filename = fname.casefold()+ if normalized_filename in seen_filenames:+ raise ValueError(+ f"{prefix} filename {fname!r} conflicts with "+ f"{seen_filenames[normalized_filename]!r} (case-insensitive)"+ )+ seen_filenames[normalized_filename] = fnamereturn datadef save_search_manifest(path: str, data: dict) -> None:"""Atomically write the batch manifest back (tmp file + rename)."""- _write_json_atomic(path, data)+ try:+ _write_json_atomic(path, data)+ except OSError as exc:+ raise RuntimeError(+ f"cannot update image query manifest {path}: {exc}"+ ) from excdef _resolve_search_concurrency(cli_value: Optional[int]) -> int:@@ -984,11 +1429,18 @@ def _search_one_item(default_strict: bool,default_min_width: int,default_min_height: int,-) -> tuple[Optional[dict], Optional[str]]:+) -> tuple[+ Optional[dict],+ Optional[str],+ bool,+ Optional[Path],+ Optional[Path],+]:"""Run the full search + download for one batch item (thread worker).- Returns ``(manifest_item, error)``. Only the network/disk work happens- here; all manifest writes are serialized by the caller.+ Returns ``(manifest_item, error, retryable, staged_path, output_path)``.+ Only network and staged-file work happens here; canonical replacement and+ all manifest writes are serialized by the caller."""filename = _validate_bare_filename(item["filename"])orientation = item.get("orientation", "any") or "any"@@ -1010,7 +1462,7 @@ def _search_one_item(providers = [pinned] if pinned else _default_provider_chain()output_path = output_dir / filename- candidate, provider_name, stage = search_and_download(+ result = search_and_download(providers,request,output_path=output_path,@@ -1018,26 +1470,53 @@ def _search_one_item(save_candidates=save_candidates,max_candidates=max_candidates,)- if candidate is None:- return None, "no acceptable candidate across all providers/stages"+ if result.candidate is None:+ return (+ None,+ result.error or "search failed",+ result.failure_kind == SEARCH_FAILURE_RETRYABLE,+ None,+ None,+ )+ if result.staged_path is None or result.output_path is None:+ return (+ None,+ "search succeeded without a staged output",+ True,+ None,+ None,+ )- actual_dimensions = _measure_actual_image(output_path)- item_args = argparse.Namespace(- filename=filename,- slide=item.get("slide", ""),- purpose=item.get("purpose", ""),- query=item["query"],- orientation=orientation,- required_terms=request.required_terms,- )- manifest_item = _candidate_to_manifest_item(- candidate,- item_args,- provider_name=provider_name,- stage=stage,- actual_dimensions=actual_dimensions,- )- return manifest_item, None+ try:+ item_args = argparse.Namespace(+ filename=filename,+ slide=item.get("slide", ""),+ purpose=item.get("purpose", ""),+ query=item["query"],+ orientation=orientation,+ required_terms=request.required_terms,+ )+ manifest_item = _candidate_to_manifest_item(+ result.candidate,+ item_args,+ provider_name=result.provider_name or "",+ stage=result.stage or "",+ actual_dimensions=result.actual_dimensions,+ )+ return (+ manifest_item,+ None,+ False,+ result.staged_path,+ result.output_path,+ )+ except Exception:+ if result.staged_path is not None:+ try:+ result.staged_path.unlink(missing_ok=True)+ except OSError:+ pass+ raisedef run_search_manifest(@@ -1053,17 +1532,66 @@ def run_search_manifest(default_strict: bool,default_min_width: int,default_min_height: int,-) -> tuple[int, int, int]:+) -> tuple[int, int, int, int]:"""Process all Pending/Failed rows concurrently with a bounded pool.On success the rich provenance entry is appended to ``image_sources.json``(the credit source of truth) and the row's status flips to ``Sourced``.A row that exhausts the provider/stage chain becomes ``Needs-Manual``(terminal). Status is written back after each completion, so an interrupt- preserves finished rows. Returns ``(sourced, needs_manual, skipped)``.+ preserves finished rows. Returns ``(sourced, needs_manual, failed, skipped)``."""- _read_existing_manifest(sources_manifest_path)+ sources_manifest = _read_existing_manifest(sources_manifest_path)items = manifest["items"]++ provenance_filenames = {+ item["filename"].casefold(): item["filename"]+ for item in sources_manifest.get("items", [])+ if isinstance(item.get("filename"), str)+ }+ repaired_sourced = False+ for item in items:+ if item["status"] != SEARCH_STATUS_SOURCED:+ continue+ filename = item["filename"]+ target_path = output_dir / filename+ reasons: list[str] = []+ provenance_filename = provenance_filenames.get(filename.casefold())+ if provenance_filename is None:+ reasons.append("image_sources.json has no matching provenance entry")+ elif provenance_filename != filename:+ reasons.append(+ "image_sources.json filename casing does not match "+ f"({provenance_filename!r} vs {filename!r})"+ )+ if not target_path.is_file():+ reasons.append("target file is missing")+ else:+ min_width = int(item.get("min_width", default_min_width))+ min_height = int(item.get("min_height", default_min_height))+ try:+ target_is_valid = _validate_downloaded_quality(+ target_path,+ min_width=min_width,+ min_height=min_height,+ )+ except RuntimeError as exc:+ reasons.append(f"target validation unavailable: {exc}")+ else:+ if not target_is_valid:+ reasons.append(+ "target file is unreadable or below requested dimensions"+ )+ if reasons:+ item["status"] = SEARCH_STATUS_FAILED+ item["last_error"] = (+ "Sourced state validation failed: " + "; ".join(reasons)+ )[:500]+ repaired_sourced = True+ print(f" [RETRY] {filename} — {item['last_error']}")+ if repaired_sourced:+ save_search_manifest(manifest_path, manifest)+pending_idx = [i for i, it in enumerate(items)if it["status"] in SEARCH_RETRYABLE_STATUSES@@ -1076,7 +1604,7 @@ def run_search_manifest(f"[Batch] Nothing to do — all {len(items)} row(s) already in a ""terminal state (Sourced / Needs-Manual).")- return 0, 0, skipped+ return 0, 0, 0, skippedprint(f"\n[Batch] {total} row(s) to search, {skipped} already done. "@@ -1085,50 +1613,137 @@ def run_search_manifest(sourced_count = 0needs_manual_count = 0+ failed_count = 0write_lock = threading.Lock()def _one(idx: int):try:- manifest_item, error = _search_one_item(- items[idx],- output_dir=output_dir,- save_candidates=save_candidates,- max_candidates=max_candidates,- default_provider=default_provider,- default_strict=default_strict,- default_min_width=default_min_width,- default_min_height=default_min_height,+ manifest_item, error, retryable, staged_path, target_path = (+ _search_one_item(+ items[idx],+ output_dir=output_dir,+ save_candidates=save_candidates,+ max_candidates=max_candidates,+ default_provider=default_provider,+ default_strict=default_strict,+ default_min_width=default_min_width,+ default_min_height=default_min_height,+ )+ )+ return (+ idx,+ manifest_item,+ error,+ retryable,+ staged_path,+ target_path,)- return idx, manifest_item, errorexcept Exception as exc: # noqa: BLE001 — provider code raises freely- return idx, None, str(exc)[:500]-- with concurrent.futures.ThreadPoolExecutor(max_workers=concurrency) as ex:- futures = [ex.submit(_one, i) for i in pending_idx]- for fut in concurrent.futures.as_completed(futures):- idx, manifest_item, error = fut.result()- item = items[idx]- with write_lock:- if manifest_item is not None:- write_sources_manifest(sources_manifest_path, manifest_item)- item["status"] = SEARCH_STATUS_SOURCED- item["provider"] = manifest_item.get("provider", "")- item["license_tier"] = manifest_item.get("license_tier", "")- item.pop("last_error", None)- sourced_count += 1- print(f" [OK] {item['filename']} ({item['provider']})")- else:- item["status"] = SEARCH_STATUS_NEEDS_MANUAL- item["last_error"] = error or "search failed"- needs_manual_count += 1- print(f" [MANUAL] {item['filename']} — {item['last_error']}")- save_search_manifest(manifest_path, manifest)+ return idx, None, str(exc)[:500], True, None, None++ futures: list[concurrent.futures.Future] = []+ try:+ with concurrent.futures.ThreadPoolExecutor(max_workers=concurrency) as ex:+ futures = [ex.submit(_one, i) for i in pending_idx]+ for fut in concurrent.futures.as_completed(futures):+ (+ idx,+ manifest_item,+ error,+ retryable,+ staged_path,+ target_path,+ ) = fut.result()+ item = items[idx]+ with write_lock:+ if (+ manifest_item is not None+ and staged_path is not None+ and target_path is not None+ ):+ try:+ _commit_staged_image(+ staged_path,+ target_path,+ lambda: write_sources_manifest(+ sources_manifest_path,+ manifest_item,+ ),+ )+ except Exception as exc:+ if not _is_recoverable_image_error(exc):+ raise+ item["status"] = SEARCH_STATUS_FAILED+ item["last_error"] = (+ f"canonical/provenance commit failed: {exc}"+ )[:500]+ failed_count += 1+ print(+ f" [FAIL] {item['filename']} — "+ f"{item['last_error']}"+ )+ else:+ item["status"] = SEARCH_STATUS_SOURCED+ item["provider"] = manifest_item.get("provider", "")+ item["license_tier"] = manifest_item.get(+ "license_tier",+ "",+ )+ item.pop("last_error", None)+ sourced_count += 1+ review = _write_review_copy(+ target_path,+ output_dir / ".review",+ target_path.name,+ )+ if review is not None:+ print(+ f" review copy: {review}",+ file=sys.stderr,+ )+ print(+ f" [OK] {item['filename']} "+ f"({item['provider']})"+ )+ elif retryable:+ item["status"] = SEARCH_STATUS_FAILED+ item["last_error"] = error or "provider/download failure"+ failed_count += 1+ print(+ f" [FAIL] {item['filename']} — {item['last_error']}"+ )+ else:+ item["status"] = SEARCH_STATUS_NEEDS_MANUAL+ item["last_error"] = error or "search failed"+ needs_manual_count += 1+ print(+ f" [MANUAL] {item['filename']} — "+ f"{item['last_error']}"+ )+ save_search_manifest(manifest_path, manifest)+ finally:+ # Workers only stage files. Any result not committed because of an+ # interrupt or a later manifest error must not leave candidate residue.+ for future in futures:+ if not future.done():+ continue+ try:+ outcome = future.result()+ except BaseException:+ continue+ staged_path = outcome[4]+ if staged_path is not None:+ try:+ staged_path.unlink(missing_ok=True)+ except OSError:+ passprint(- f"\n[Batch] Done: {sourced_count} sourced / {needs_manual_count} "- f"needs-manual ({skipped} pre-skipped). Manifest: {manifest_path}"+ f"\n[Batch] Done: {sourced_count} sourced / {failed_count} failed / "+ f"{needs_manual_count} needs-manual ({skipped} pre-skipped). "+ f"Manifest: {manifest_path}")- return sourced_count, needs_manual_count, skipped+ return sourced_count, needs_manual_count, failed_count, skipped# ---------------------------------------------------------------------------@@ -1313,6 +1928,8 @@ def main(argv: Optional[list[str]] = None) -> int:)except ValueError as exc:parser.error(str(exc))+ if args.min_width < 1 or args.min_height < 1:+ parser.error("--min-width and --min-height must both be positive integers")output_dir = Path(args.output)@@ -1341,6 +1958,8 @@ def main(argv: Optional[list[str]] = None) -> int:search_query=args.query or "",orientation="" if args.orientation == "any" else args.orientation,required_terms=_parse_required_terms(args.require_terms),+ min_width=args.min_width,+ min_height=args.min_height,)# --- Batch mode ---@@ -1362,7 +1981,7 @@ def main(argv: Optional[list[str]] = None) -> int:else default_manifest_path(str(batch_output_dir)))try:- _, needs_manual, _ = run_search_manifest(+ _, needs_manual, failed, _ = run_search_manifest(manifest,args.batch,output_dir=batch_output_dir,@@ -1381,10 +2000,9 @@ def main(argv: Optional[list[str]] = None) -> int:except RuntimeError as exc:print(f"Error: {exc}", file=sys.stderr)return 1- # Mirror image_gen.py: a non-zero code flags rows that need manual- # attention. It is a signal, not a halt — the workflow (image-base.md- # §6) surfaces Needs-Manual rows and continues regardless.- return 1 if needs_manual else 0+ # Mirror image_gen.py: any unresolved retryable or manual row keeps the+ # command non-zero. It is a gate signal, not a request to hide progress.+ return 1 if needs_manual or failed else 0# --- Single-query search mode ---if not args.query:@@ -1419,7 +2037,7 @@ def main(argv: Optional[list[str]] = None) -> int:output_path = output_dir / args.filenameprint(f"Searching providers: {', '.join(providers)}", file=sys.stderr)- candidate, provider_name, stage = search_and_download(+ result = search_and_download(providers,request,output_path=output_path,@@ -1428,57 +2046,81 @@ def main(argv: Optional[list[str]] = None) -> int:max_candidates=args.max_candidates,)- if candidate is None:+ if result.candidate is None:print(- "No acceptable candidates could be downloaded across all "- "providers/filters. Try a shorter query, use default attribution "- "mode if strict mode is enabled, or set an API key for a keyed provider.",+ f"{result.error or 'Image search failed'}. "+ "Try a shorter query, use default attribution mode if strict mode "+ "is enabled, or set an API key for a keyed provider.",file=sys.stderr,)return 1print(- f" picked: {candidate.title!r} from {provider_name} "- f"({candidate.license_name or 'no license string'}, "- f"{candidate.license_tier})",+ f" picked: {result.candidate.title!r} from {result.provider_name} "+ f"({result.candidate.license_name or 'no license string'}, "+ f"{result.candidate.license_tier})",file=sys.stderr,)- # Measure what was actually written to disk; upstream metadata can be+ # The staged file has already been measured; upstream metadata can still be# off (e.g. Openverse aggregates rawpixel which only exposes previews).- actual_dimensions = _measure_actual_image(output_path)+ actual_dimensions = result.actual_dimensionsif (actual_dimensions is not None- and candidate.width- and candidate.height+ and result.candidate.width+ and result.candidate.heightand actual_dimensions[0] * actual_dimensions[1]- < 0.5 * candidate.width * candidate.height+ < 0.5 * result.candidate.width * result.candidate.height):print(f"\n[!] Downloaded image is much smaller than upstream metadata "f"({actual_dimensions[0]}x{actual_dimensions[1]} vs "- f"{candidate.width}x{candidate.height}). The provider likely "- f"only exposes a preview here. Layout based on the manifest's "+ f"{result.candidate.width}x{result.candidate.height}). The provider "+ f"likely only exposes a preview here. Layout based on the manifest's "f"width/height will be accurate; the metadata_dimensions field "f"is preserved for reference.",file=sys.stderr,)- item = _candidate_to_manifest_item(- candidate,- args,- provider_name=provider_name,- stage=stage,- actual_dimensions=actual_dimensions,- )+ if result.staged_path is None or result.output_path is None:+ print("Error: image search returned no staged output.", file=sys.stderr)+ if result.staged_path is not None:+ try:+ result.staged_path.unlink(missing_ok=True)+ except OSError:+ pass+ return 1try:- write_sources_manifest(manifest_path, item)- except RuntimeError as exc:+ item = _candidate_to_manifest_item(+ result.candidate,+ args,+ provider_name=result.provider_name or "",+ stage=result.stage or "",+ actual_dimensions=actual_dimensions,+ )+ written = _commit_staged_image(+ result.staged_path,+ result.output_path,+ lambda: write_sources_manifest(manifest_path, item),+ )+ except (OSError, RuntimeError, ValueError) as exc:print(f"Error: {exc}", file=sys.stderr)return 1- print(f" manifest: {manifest_path}", file=sys.stderr)+ finally:+ try:+ result.staged_path.unlink(missing_ok=True)+ except OSError:+ pass+ print(f" manifest: {written}", file=sys.stderr)+ review = _write_review_copy(+ result.output_path,+ result.output_path.parent / ".review",+ result.output_path.name,+ )+ if review is not None:+ print(f" review copy: {review}", file=sys.stderr)- if candidate.license_tier == "attribution-required":+ if result.candidate.license_tier == "attribution-required":print("\n[!] This image requires on-slide attribution. ""Executor should add a small credit element to the slide using "diff --git a/skills/ppt-master/scripts/project_manager.py b/skills/ppt-master/scripts/project_manager.pyindex 231eb1d8..57638a65 100644--- a/skills/ppt-master/scripts/project_manager.py+++ b/skills/ppt-master/scripts/project_manager.py@@ -22,6 +22,7 @@ import reimport shutilimport subprocessimport sys+import tempfilefrom datetime import datetimefrom pathlib import Pathfrom urllib.parse import urlparse@@ -86,6 +87,82 @@ IMAGE_ASSET_SUFFIXES = BITMAP_IMAGE_SUFFIXES | {configure_utf8_stdio()+def _validate_image_manifest(+ payload: object,+ path: Path,+) -> list[dict]:+ """Require a safe, case-insensitively unique image manifest payload."""+ if not isinstance(payload, list):+ raise RuntimeError(+ f"Image manifest must be a JSON array: {path}"+ )++ seen_filenames: dict[str, str] = {}+ for index, item in enumerate(payload):+ if not isinstance(item, dict):+ raise RuntimeError(+ f"Existing image manifest item {index} must be an object: {path}"+ )+ 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()+ or Path(filename).name != filename+ ):+ raise RuntimeError(+ f"Image manifest item {index} has no safe bare filename: {path}"+ )+ normalized_filename = filename.casefold()+ if normalized_filename in seen_filenames:+ raise RuntimeError(+ f"Image manifest filename {filename!r} conflicts with "+ f"{seen_filenames[normalized_filename]!r} (case-insensitive): {path}"+ )+ seen_filenames[normalized_filename] = filename+ return payload+++def _read_existing_image_manifest(path: Path) -> list[dict]:+ """Load an existing project image manifest or fail closed on corruption."""+ if not path.exists():+ return []+ if not path.is_file():+ raise RuntimeError(f"Existing image manifest is not a regular file: {path}")+ try:+ payload = json.loads(path.read_text(encoding="utf-8"))+ except (OSError, json.JSONDecodeError) as exc:+ raise RuntimeError(+ f"Existing image manifest is unreadable: {path} ({exc}); "+ "repair or restore it before importing more assets"+ ) from exc+ return _validate_image_manifest(payload, path)+++def _write_json_atomic(path: Path, payload: object) -> None:+ """Write JSON through a same-directory temporary file and atomic rename."""+ fd, temp_name = tempfile.mkstemp(+ prefix=f"{path.stem}.",+ suffix=".tmp",+ dir=str(path.parent),+ )+ try:+ with os.fdopen(fd, "w", encoding="utf-8") as handle:+ json.dump(payload, handle, ensure_ascii=False, indent=2)+ handle.write("\n")+ os.replace(temp_name, path)+ except Exception:+ try:+ os.unlink(temp_name)+ except OSError:+ pass+ raise++def is_url(value: str) -> bool:"""Return whether a string looks like an HTTP(S) URL."""parsed = urlparse(value)@@ -407,16 +484,8 @@ class ProjectManager:def _merge_image_manifest(self, source_items: list[dict], destination_manifest: Path) -> None:"""Merge per-source manifest items into the project-level manifest, keyed by filename."""- existing_data: list[object] = []- if destination_manifest.is_file():- try:- loaded = json.loads(destination_manifest.read_text(encoding="utf-8"))- if isinstance(loaded, list):- existing_data = loaded- else:- print(f"[WARN] Replacing non-list image manifest: {destination_manifest}")- except (OSError, json.JSONDecodeError) as exc:- print(f"[WARN] Replacing unreadable image manifest {destination_manifest}: {exc}")+ _validate_image_manifest(source_items, destination_manifest)+ existing_data = _read_existing_image_manifest(destination_manifest)new_by_filename: dict[str, dict] = {}new_order: list[str] = []@@ -424,9 +493,10 @@ class ProjectManager:filename = item.get("filename")if not isinstance(filename, str):continue- if filename not in new_by_filename:- new_order.append(filename)- new_by_filename[filename] = item+ normalized_filename = filename.casefold()+ if normalized_filename not in new_by_filename:+ new_order.append(normalized_filename)+ new_by_filename[normalized_filename] = itemmerged: list[dict] = []seen: set[str] = set()@@ -436,20 +506,19 @@ class ProjectManager:filename = item.get("filename")if not isinstance(filename, str):continue- if filename in new_by_filename:- merged.append(new_by_filename[filename])+ normalized_filename = filename.casefold()+ if normalized_filename in new_by_filename:+ merged.append(new_by_filename[normalized_filename])else:merged.append(item)- seen.add(filename)+ seen.add(normalized_filename)- for filename in new_order:- if filename not in seen:- merged.append(new_by_filename[filename])+ for normalized_filename in new_order:+ if normalized_filename not in seen:+ merged.append(new_by_filename[normalized_filename])- destination_manifest.write_text(- json.dumps(merged, ensure_ascii=False, indent=2) + "\n",- encoding="utf-8",- )+ _validate_image_manifest(merged, destination_manifest)+ _write_json_atomic(destination_manifest, merged)@staticmethoddef _namespace_from_asset_dir(asset_dir: Path) -> str:@@ -464,10 +533,11 @@ class ProjectManager:source_file: Path,namespace: str,existing_manifest: dict[str, dict],+ occupied_names: set[str],) -> str:"""Return a short unique image filename for the runtime image pool."""candidate = images_dir / source_file.name- if not candidate.exists():+ if candidate.name.casefold() not in occupied_names:return source_file.nametry:meta = existing_manifest.get(candidate.name, {})@@ -485,7 +555,7 @@ class ProjectManager:counter = 2while True:candidate = images_dir / f"{stem}_{counter}{suffix}"- if not candidate.exists():+ if candidate.name.casefold() not in occupied_names:return candidate.nametry:meta = existing_manifest.get(candidate.name, {})@@ -511,31 +581,31 @@ class ProjectManager:returntry:- source_data = json.loads(manifest_path.read_text(encoding="utf-8"))+ source_payload = json.loads(manifest_path.read_text(encoding="utf-8"))except (OSError, json.JSONDecodeError) as exc:print(f"[WARN] Cannot read image manifest {manifest_path}: {exc}")return- if not isinstance(source_data, list):- print(f"[WARN] Ignoring non-list image manifest: {manifest_path}")+ try:+ source_data = _validate_image_manifest(source_payload, manifest_path)+ except RuntimeError as exc:+ print(f"[WARN] {exc}")returnimages_dir = project_dir / "images"- images_dir.mkdir(parents=True, exist_ok=True)-namespace = self._namespace_from_asset_dir(asset_dir)- existing_manifest: dict[str, dict] = {}destination_manifest = images_dir / "image_manifest.json"- if destination_manifest.is_file():- try:- data = json.loads(destination_manifest.read_text(encoding="utf-8"))- if isinstance(data, list):- existing_manifest = {- item["filename"]: item- for item in data- if isinstance(item, dict) and isinstance(item.get("filename"), str)- }- except (OSError, json.JSONDecodeError):- existing_manifest = {}+ existing_data = _read_existing_image_manifest(destination_manifest)+ images_dir.mkdir(parents=True, exist_ok=True)++ existing_manifest = {+ item["filename"]: item+ for item in existing_data+ }+ occupied_names = {+ path.name.casefold()+ for path in images_dir.iterdir()+ if path.is_file()+ }rename_map: dict[str, str] = {}copied_count = 0@@ -549,10 +619,12 @@ class ProjectManager:source_file,namespace,existing_manifest,+ occupied_names,)destination = images_dir / new_nameif source_file.resolve() != destination.resolve():shutil.copy2(source_file, destination)+ occupied_names.add(new_name.casefold())rename_map[source_file.name] = new_namecopied_count += 1diff --git a/skills/ppt-master/scripts/project_specs.py b/skills/ppt-master/scripts/project_specs.pyindex 3bfa521c..9f6f1d60 100644--- a/skills/ppt-master/scripts/project_specs.py+++ b/skills/ppt-master/scripts/project_specs.py@@ -71,7 +71,30 @@ _MARKDOWN_DATA_LINE_RE = re.compile(re.MULTILINE,)_IMAGE_PATH_SUFFIXES = frozenset(- {".bmp", ".gif", ".jpeg", ".jpg", ".png", ".svg", ".tif", ".tiff", ".webp"}+ {+ ".bmp",+ ".emf",+ ".gif",+ ".jpeg",+ ".jpg",+ ".png",+ ".svg",+ ".tif",+ ".tiff",+ ".webp",+ ".wmf",+ }+)+_IMAGE_ACQUISITION_SOURCES = frozenset(+ {"ai", "web", "user", "formula", "placeholder", "slice"}+)+_IMAGE_CROP_POLICIES = frozenset({"adaptive", "no-crop"})+_LEGACY_IMAGE_METADATA_KEYS = frozenset(+ {+ "image_rendering",+ "image_rendering_behavior",+ "image_rendering_references",+ })_LEGACY_SPEC_LOCK_FORBIDDEN = frozenset({"Mixing icon libraries"})_SCAFFOLD_TOKEN_RE = re.compile(r"\{\{[A-Z_]+\}\}")@@ -176,6 +199,109 @@ def _looks_like_image_path(raw: str) -> bool:return bool(token) and Path(token).suffix.casefold() in _IMAGE_PATH_SUFFIXES+def parse_spec_lock_image_value(key: str, value: str) -> dict[str, str]:+ """Parse one image-lock row while preserving supported legacy rows.++ Current rows use ``<path> | source=... | pattern=... | crop=...``. Legacy+ rows remain readable, but any row that starts using named metadata must+ provide the complete current contract.+ """+ normalized_key = str(key).strip()+ normalized_value = str(value).strip()+ parts = [part.strip() for part in normalized_value.split("|")]+ path_part = parts[0] if parts else ""++ if _looks_like_image_path(normalized_key) and not _looks_like_image_path(path_part):+ parts.insert(0, normalized_key)+ path_part = normalized_key+ elif (+ len(parts) >= 2+ and parts[0].casefold() in _IMAGE_ACQUISITION_SOURCES+ and _looks_like_image_path(parts[1])+ ):+ path_part = parts[1]++ metadata_parts = [part for part in parts[1:] if "=" in part]+ if not metadata_parts:+ legacy_crop = (+ "no-crop"+ if any(+ re.search(r"(?<![a-z])no-crop(?![a-z])", part, re.IGNORECASE)+ for part in parts[1:]+ )+ else ""+ )+ return {+ "path": path_part,+ "source": "",+ "pattern": "",+ "crop": legacy_crop,+ "legacy": "true",+ }++ metadata: dict[str, str] = {}+ unsupported_parts: list[str] = []+ for part in parts[1:]:+ field, separator, raw = part.partition("=")+ if not separator:+ unsupported_parts.append(part)+ continue+ field = field.strip().casefold()+ if field in metadata:+ raise ValueError(f"repeats metadata field {field!r}")+ metadata[field] = raw.strip()++ expected_fields = {"source", "pattern", "crop"}+ unknown_fields = sorted(set(metadata) - expected_fields)+ missing_fields = sorted(expected_fields - set(metadata))+ if unsupported_parts:+ shown = ", ".join(repr(part) for part in unsupported_parts)+ raise ValueError(f"has unsupported metadata token(s) {shown}")+ if unknown_fields:+ raise ValueError(+ f"has unknown metadata field(s) {', '.join(unknown_fields)}"+ )+ if missing_fields:+ raise ValueError(+ f"misses metadata field(s) {', '.join(missing_fields)}"+ )+ if not _looks_like_image_path(path_part):+ raise ValueError(f"has invalid image path {path_part!r}")++ normalized_path = path_part.replace("\\", "/")+ path = Path(normalized_path)+ if (+ path.is_absolute()+ or len(path.parts) != 2+ or path.parts[0] != "images"+ or path.name in {"", ".", ".."}+ or ":" in path.name+ or normalized_path != f"images/{path.name}"+ ):+ raise ValueError(+ f"must use canonical project path images/<filename>, got {path_part!r}"+ )++ source = metadata["source"].casefold()+ if source not in _IMAGE_ACQUISITION_SOURCES:+ allowed = ", ".join(sorted(_IMAGE_ACQUISITION_SOURCES))+ raise ValueError(f"source must be one of {allowed}, got {metadata['source']!r}")+ if not metadata["pattern"]:+ raise ValueError("pattern must be non-empty")+ crop = metadata["crop"].casefold()+ if crop not in _IMAGE_CROP_POLICIES:+ allowed = ", ".join(sorted(_IMAGE_CROP_POLICIES))+ raise ValueError(f"crop must be one of {allowed}, got {metadata['crop']!r}")++ return {+ "path": normalized_path,+ "source": source,+ "pattern": metadata["pattern"],+ "crop": crop,+ "legacy": "false",+ }++def parse_spec_lock_artifact(lock_path: Path,*,@@ -873,6 +999,16 @@ def _validate_spec_lock_relations(f"unknown catalog id '{reference}'")+ for key, value in fields("images").items():+ if key.strip().casefold() in _LEGACY_IMAGE_METADATA_KEYS:+ continue+ try:+ parse_spec_lock_image_value(key, value)+ except ValueError as exc:+ errors.append(+ f"{markdown_name} schema: images row {key!r} {exc}"+ )+rhythm = fields("page_rhythm")layouts = fields("pptx_layouts")page_pptx_layouts = fields("page_pptx_layouts")diff --git a/skills/ppt-master/scripts/resource_paths.py b/skills/ppt-master/scripts/resource_paths.pyindex 1d6f3e29..fa81c898 100644--- a/skills/ppt-master/scripts/resource_paths.py+++ b/skills/ppt-master/scripts/resource_paths.py@@ -1,15 +1,16 @@#!/usr/bin/env python3"""-PPT Master - Shared SVG Resource Path Helpers+PPT Master - Shared SVG Resource Helpers-Centralizes project-relative SVG resource lookup used by the checker,-finalizer, and SVG-to-PPTX exporter.+Centralizes project-relative resource lookup and nested-SVG closure validation+used by the checker, finalizer, and SVG-to-PPTX exporter.Usage:Imported by scripts; not intended as a standalone CLI.Examples:from resource_paths import resolve_external_image_reference+ from resource_paths import svg_image_payload_errorDependencies:None@@ -17,13 +18,45 @@ Dependencies:from __future__ import annotations+import base64+import binascii+import refrom pathlib import Path-from urllib.parse import unquote, urlsplit+from urllib.parse import unquote, unquote_to_bytes, urlsplit+from xml.etree import ElementTree as ETSVG_WORK_DIR_NAMES = frozenset({'svg_output', 'svg_final', 'svg-flat', 'svg_flat'})TEMPLATE_SOURCE_DIR_NAME = 'templates'TEMPLATE_SPEC_FILENAME = 'design_spec.md'+_SVG_NAMESPACE = 'http://www.w3.org/2000/svg'+_SVG_URL_REFERENCE_RE = re.compile(r'url\(\s*([^)]+?)\s*\)', re.IGNORECASE)+_SVG_CSS_URL_ATTRIBUTES = frozenset({+ 'background',+ 'background-image',+ 'clip-path',+ 'color-profile',+ 'cursor',+ 'fill',+ 'filter',+ 'marker',+ 'marker-end',+ 'marker-mid',+ 'marker-start',+ 'mask',+ 'stroke',+ 'style',+})+_SVG_DIRECT_RESOURCE_ATTRIBUTES = frozenset({'poster', 'src'})+_SVG_DATA_URI_DEPTH_LIMIT = 8+_SVG_EXTERNAL_DOCTYPE_RE = re.compile(+ br'<!DOCTYPE\b[^>]*\b(?:PUBLIC|SYSTEM)\b',+ re.IGNORECASE | re.DOTALL,+)+_XML_STYLESHEET_HREF_RE = re.compile(+ r'\bhref\s*=\s*([\'"])(.*?)\1',+ re.IGNORECASE | re.DOTALL,+)def project_root_for_svg_path(svg_path: Path) -> Path:@@ -59,6 +92,146 @@ def icon_search_dirs_for_svg(svg_path: Path) -> tuple[Path, Path | None]:return icon_search_dirs_for_project(project_root_for_svg_path(svg_path))+def _decode_svg_data_uri(raw: str) -> tuple[bytes | None, str | None]:+ """Decode an SVG data URI; return ``(None, None)`` for other media."""+ value = raw.strip().strip('\'"')+ if not value.lower().startswith('data:'):+ return None, None+ header, separator, payload = value.partition(',')+ media_type = header[5:].split(';', 1)[0].strip().lower()+ if media_type != 'image/svg+xml':+ return None, None+ if not separator:+ return None, 'invalid embedded SVG data URI'+ is_base64 = any(+ token.strip().lower() == 'base64'+ for token in header.split(';')[1:]+ )+ try:+ decoded = (+ base64.b64decode(payload, validate=True)+ if is_base64+ else unquote_to_bytes(payload)+ )+ except (ValueError, binascii.Error):+ return None, 'invalid embedded SVG data URI'+ return decoded, None+++def _svg_reference_error(raw: str, depth: int) -> str | None:+ """Return an external or recursively embedded SVG resource error."""+ value = raw.strip().strip('\'"')+ if not value:+ return 'empty resource reference'+ if value.startswith('#'):+ return None+ if not value.lower().startswith('data:'):+ return f'unpackaged external resource {value!r}'++ nested_svg, decode_error = _decode_svg_data_uri(value)+ if decode_error is not None:+ return decode_error+ if nested_svg is None:+ return None+ if depth >= _SVG_DATA_URI_DEPTH_LIMIT:+ return 'embedded SVG resource nesting exceeds the safety limit'+ nested_error = _svg_image_payload_error(nested_svg, depth + 1)+ if nested_error is None:+ return None+ return f'embedded SVG resource is not closed: {nested_error}'+++def _xml_stylesheet_error(raw_bytes: bytes, depth: int) -> str | None:+ """Return an external XML stylesheet processing-instruction error."""+ parser = ET.XMLPullParser(events=('pi',))+ try:+ parser.feed(raw_bytes)+ parser.close()+ except ET.ParseError:+ return None+ for _event, instruction in parser.read_events():+ text = (instruction.text or '').strip()+ if not text.lower().startswith('xml-stylesheet'):+ continue+ match = _XML_STYLESHEET_HREF_RE.search(text)+ if match is None:+ return 'XML stylesheet processing instruction lacks href'+ reference_error = _svg_reference_error(match.group(2), depth)+ if reference_error is not None:+ return f'XML stylesheet is not closed: {reference_error}'+ return None+++def _svg_image_payload_error(raw_bytes: bytes, depth: int) -> str | None:+ """Return why one SVG image payload is not a closed packaged resource."""+ if _SVG_EXTERNAL_DOCTYPE_RE.search(raw_bytes):+ return 'unpackaged external XML doctype'+ try:+ root = ET.fromstring(raw_bytes)+ except ET.ParseError as exc:+ return f'invalid SVG XML: {exc}'+ if root.tag != f'{{{_SVG_NAMESPACE}}}svg':+ return 'root must use the SVG namespace'++ stylesheet_error = _xml_stylesheet_error(raw_bytes, depth)+ if stylesheet_error is not None:+ return stylesheet_error+ for elem in root.iter():+ tag = str(elem.tag).rsplit('}', 1)[-1]+ for raw_name, raw_value in elem.attrib.items():+ name = raw_name.rsplit('}', 1)[-1]+ if name == 'href' and tag != 'a':+ reference_error = _svg_reference_error(raw_value, depth)+ if reference_error is not None:+ return reference_error+ elif name in _SVG_DIRECT_RESOURCE_ATTRIBUTES:+ reference_error = _svg_reference_error(raw_value, depth)+ if reference_error is not None:+ return reference_error+ elif name == 'data' and tag == 'object':+ reference_error = _svg_reference_error(raw_value, depth)+ if reference_error is not None:+ return reference_error+ elif name == 'srcset' and raw_value.strip():+ return 'srcset resource lists are not closed SVG resources'++ if name not in _SVG_CSS_URL_ATTRIBUTES:+ continue+ for match in _SVG_URL_REFERENCE_RE.finditer(raw_value):+ reference_error = _svg_reference_error(match.group(1), depth)+ if reference_error is not None:+ return f'url() resource is not closed: {reference_error}'++ if tag != 'style':+ continue+ style_text = ''.join(elem.itertext())+ if re.search(r'@import\b', style_text, flags=re.IGNORECASE):+ return 'unpackaged CSS import'+ for match in _SVG_URL_REFERENCE_RE.finditer(style_text):+ reference_error = _svg_reference_error(match.group(1), depth)+ if reference_error is not None:+ return f'url() resource is not closed: {reference_error}'+ return None+++def svg_image_payload_error(raw_bytes: bytes) -> str | None:+ """Return why a nested SVG image is not a closed packaged resource."""+ return _svg_image_payload_error(raw_bytes, 0)+++def svg_data_uri_payload_error(raw: str) -> str | None:+ """Return why an inline SVG image data URI is not a closed resource."""+ nested_svg, decode_error = _decode_svg_data_uri(raw)+ if decode_error is not None:+ return decode_error+ if nested_svg is None:+ return None+ nested_error = _svg_image_payload_error(nested_svg, 0)+ if nested_error is None:+ return None+ return f'inline SVG data URI is not closed: {nested_error}'++def external_image_reference_candidates(svg_dir: Path, href: str) -> list[Path]:"""Return candidate paths for a non-data-URI SVG image href."""parsed = urlsplit(href)diff --git a/skills/ppt-master/scripts/slice_images.py b/skills/ppt-master/scripts/slice_images.pyindex eed4ff07..2bfe79c7 100644--- a/skills/ppt-master/scripts/slice_images.py+++ b/skills/ppt-master/scripts/slice_images.py@@ -175,6 +175,17 @@ def slice_sheet(f"{total_cells} cells; provide exactly one name per cell")safe_names = [_safe_basename(n) for n in names] if names else None+ if safe_names:+ seen_outputs: set[str] = set()+ for name in safe_names:+ output_name = name if Path(name).suffix else f"{name}.png"+ normalized_output = output_name.casefold()+ if normalized_output in seen_outputs:+ raise ValueError(+ f"--names repeats output filename {output_name!r} "+ "(case-insensitive)"+ )+ seen_outputs.add(normalized_output)if alpha and safe_names:for name in safe_names:suffix = Path(name).suffix.lower()diff --git a/skills/ppt-master/scripts/svg_finalize/align_embed_images.py b/skills/ppt-master/scripts/svg_finalize/align_embed_images.pyindex 4190251d..d30ed99d 100644--- a/skills/ppt-master/scripts/svg_finalize/align_embed_images.py+++ b/skills/ppt-master/scripts/svg_finalize/align_embed_images.py@@ -46,6 +46,7 @@ from __future__ import annotationsimport base64import io+import mathimport osimport reimport sys@@ -58,7 +59,11 @@ if str(_SCRIPTS_DIR) not in sys.path:sys.path.insert(0, str(_SCRIPTS_DIR))from console_encoding import configure_utf8_stdio # noqa: E402-from resource_paths import resolve_external_image_reference # noqa: E402+from resource_paths import ( # noqa: E402+ resolve_external_image_reference,+ svg_data_uri_payload_error,+ svg_image_payload_error,+)configure_utf8_stdio()@@ -223,6 +228,8 @@ def _target_size(def _downscale_to_target(img: 'PILImage', target_w: int, target_h: int) -> tuple['PILImage', bool]:"""Downscale without upsampling."""width, height = img.size+ if width <= 0 or height <= 0:+ return img, Falseratio = min(target_w / width, target_h / height, 1.0)if ratio >= 1.0:return img, False@@ -327,7 +334,10 @@ def _process_one_image(href = _get_href(image)if not href:return False, None- if href.startswith('data:'):+ if href.lower().startswith('data:'):+ payload_error = svg_data_uri_payload_error(href)+ if payload_error is not None:+ return False, payload_errorreturn False, None # already inlineimg_path = _resolve_image_path(href, svg_dir)@@ -346,6 +356,9 @@ def _process_one_image(return False, Noneif _is_svg_image(img_path, raw_bytes):+ payload_error = svg_image_payload_error(raw_bytes)+ if payload_error is not None:+ return False, f'{img_path.name}: {payload_error}'_embed_raw_image(image, img_path, raw_bytes)if verbose:print(f' [OK] {img_path.name} (svg, embedded as-is)')@@ -379,7 +392,12 @@ def _process_one_image(box_y = _parse_float(image.get('y'))box_w = _parse_float(image.get('width'))box_h = _parse_float(image.get('height'))- if box_w <= 0 or box_h <= 0:+ if (+ not math.isfinite(box_w)+ or not math.isfinite(box_h)+ or box_w <= 0+ or box_h <= 0+ ):return False, 'zero-sized box'par_attr = image.get('preserveAspectRatio') or ''@@ -392,6 +410,8 @@ def _process_one_image(new_x, new_y, new_w, new_h = box_x, box_y, box_w, box_htransformed = geometry_normalizedtarget_box_w, target_box_h = box_w, box_h+ preserve_stretch = False+ preserve_slice = Falseif not par_attr:# No preserveAspectRatio at all. The previous pipeline's fix-aspect@@ -403,14 +423,20 @@ def _process_one_image(align, mode = parse_preserve_aspect_ratio(par_attr)if align == 'none':# Author wants stretch-to-box; preserve geometry, embed bytes.- pass+ preserve_stretch = Trueelif mode == 'slice':x_anchor, y_anchor = get_crop_anchor(align)cropped_img = crop_image_to_size(- img, int(box_w), int(box_h), x_anchor, y_anchor+ img, box_w, box_h, x_anchor, y_anchor)final_img = cropped_imgtransformed = True+ preserve_slice = not math.isclose(+ cropped_img.size[0] / cropped_img.size[1],+ box_w / box_h,+ rel_tol=1e-6,+ abs_tol=1e-9,+ )else: # meet (or any other mode → treat as meet)new_w_calc, new_h_calc, off_x, off_y = calculate_fitted_dimensions(img.size[0], img.size[1], box_w, box_h, mode='meet',@@ -449,7 +475,11 @@ def _process_one_image(image.set('y', _format_number(new_y))image.set('width', _format_number(new_w))image.set('height', _format_number(new_h))- if 'preserveAspectRatio' in image.attrib:+ if preserve_stretch:+ image.set('preserveAspectRatio', 'none')+ elif preserve_slice:+ image.set('preserveAspectRatio', par_attr)+ elif 'preserveAspectRatio' in image.attrib:del image.attrib['preserveAspectRatio']if verbose:@@ -505,8 +535,10 @@ def align_and_embed_images_in_svg(try:tree = ET.parse(svg_path)except ET.ParseError as exc:- if verbose:- print(f' [ERROR] {svg_path.name}: parse failed ({exc})')+ print(+ f' [ERROR] {svg_path.name}: parse failed ({exc})',+ file=sys.stderr,+ )return (0, 1)root = tree.getroot()@@ -535,10 +567,9 @@ def align_and_embed_images_in_svg(processed += 1elif err:errors += 1- if verbose:- print(f' [WARN] {svg_path.name}: {err}')+ print(f' [ERROR] {svg_path.name}: {err}', file=sys.stderr)- if processed > 0 and not dry_run:+ if processed > 0 and errors == 0 and not dry_run:tree.write(svg_path, encoding='utf-8', xml_declaration=False)return (processed, errors)diff --git a/skills/ppt-master/scripts/svg_finalize/crop_images.py b/skills/ppt-master/scripts/svg_finalize/crop_images.pyindex 09b1f7f3..028bc319 100644--- a/skills/ppt-master/scripts/svg_finalize/crop_images.py+++ b/skills/ppt-master/scripts/svg_finalize/crop_images.py@@ -86,8 +86,8 @@ def get_crop_anchor(align: str) -> tuple[float, float]:def crop_image_to_size(img: Image.Image,- target_width: int,- target_height: int,+ target_width: float,+ target_height: float,x_anchor: float = 0.5,y_anchor: float = 0.5,) -> Image.Image:@@ -108,6 +108,10 @@ def crop_image_to_size(Cropped PIL Image object (preserving original resolution)"""img_width, img_height = img.size+ if img_width <= 0 or img_height <= 0:+ raise ValueError('source image dimensions must be positive')+ if target_width <= 0 or target_height <= 0:+ raise ValueError('target image dimensions must be positive')# Calculate target aspect ratiotarget_ratio = target_width / target_height@@ -117,11 +121,11 @@ def crop_image_to_size(if img_ratio > target_ratio:# Original image is wider; crop left and right sidescrop_height = img_height- crop_width = int(img_height * target_ratio)+ crop_width = max(1, min(img_width, int(round(img_height * target_ratio))))else:# Original image is taller; crop top and bottom sidescrop_width = img_width- crop_height = int(img_width / target_ratio)+ crop_height = max(1, min(img_height, int(round(img_width / target_ratio))))# Calculate crop position based on anchor pointextra_width = img_width - crop_widthdiff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.pyindex 784d3b61..34228bb2 100644--- a/skills/ppt-master/scripts/svg_quality_checker.py+++ b/skills/ppt-master/scripts/svg_quality_checker.py@@ -53,9 +53,13 @@ from svg_to_pptx.canvas_contract import ()try:- from project_specs import parse_spec_lock as _parse_spec_lock+ from 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 = Nonetry:from svg_to_pptx.animation_config import (@@ -2248,13 +2252,15 @@ class SVGQualityChecker:'frames or media')return- result['errors'].extend(- _project_image_errors(- root,- svg_path.parent,- allow_template_placeholders=self.template_mode,+ _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,@@ -3227,23 +3233,95 @@ class SVGQualityChecker:parent_by_id: Dict[int, ET.Element],) -> bool:"""Return whether inherited display or visibility hides an element."""- display = (+ 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,- 'display',+ 'visibility',parent_by_id,)or '').strip().lower()- visibility = (- _effective_presentation_value(+ 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,- 'visibility',+ working_root,parent_by_id,)- or ''- ).strip().lower()- return display == 'none' or visibility in {'hidden', 'collapse'}+ and not cls._has_zero_opacity(element, parent_by_id)+ ]+ return working_root, parent_by_id, images@staticmethoddef _has_non_visual_ancestor(@@ -3657,16 +3735,9 @@ class SVGQualityChecker: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- parent_by_id = {- id(child): parent- for parent in root.iter()- for child in list(parent)- }-- for image in root.iter():- if image.tag != f'{{{SVG_NS}}}image':- continue+ 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@@ -3691,7 +3762,7 @@ class SVGQualityChecker:parent = parent_by_id.get(id(image))if (parent is not None- and parent is not root+ and parent is not working_rootand parent.tag == f'{{{SVG_NS}}}svg'):# Imported crops use a unit-frame inner image. Quality advice@@ -5427,11 +5498,10 @@ class SVGQualityChecker:@classmethoddef _referenced_image_basenames(cls, root: ET.Element) -> set[str]:- """Return external image basenames referenced by one parsed SVG."""+ """Return external image basenames rendered by one parsed SVG."""filenames = set()- for elem in root.iter():- if elem.tag != f'{{{SVG_NS}}}image':- continue+ _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:@@ -5497,45 +5567,31 @@ class SVGQualityChecker:@classmethoddef _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 root.iter()+ for parent in working_root.iter()for child in list(parent)}- def has_zero_opacity(element: ET.Element) -> bool:- 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-blocks: List[str] = []- for element in root.iter(f'{{{SVG_NS}}}text'):+ 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, root, parent_by_id)- or has_zero_opacity(element)+ or cls._has_non_visual_ancestor(+ element,+ working_root,+ parent_by_id,+ )+ or cls._has_zero_opacity(element, parent_by_id)):continuetext = re.sub(r'\s+', ' ', ' '.join(element.itertext())).strip()@@ -6248,7 +6304,7 @@ class SVGQualityChecker:)lock_images = set(lock_entries)svg_texts = self._load_project_svg_texts(project_path)- svg_references, inline_image_counts = (+ svg_references, inline_image_counts, image_placements = (self._load_project_svg_image_references(project_path))all_svg_references = (@@ -6309,6 +6365,7 @@ class SVGQualityChecker:lock_error,svg_references,inline_image_counts,+ image_placements,)else:for row in slice_rows:@@ -6423,6 +6480,23 @@ class SVGQualityChecker: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,@@ -6433,6 +6507,8 @@ class SVGQualityChecker: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:@@ -6444,42 +6520,33 @@ class SVGQualityChecker:'image_rendering_references','image_rendering_behavior',}- acquisition_sources = {- 'ai',- 'web',- 'user',- 'formula',- 'placeholder',- 'slice',- }+ errors: List[str] = []for key, value in lock.get('images', {}).items():if str(key).strip().lower() in legacy_metadata_keys:continue- parts = [part.strip() for part in value.split('|')]- path_part = parts[0] if parts else ''- if (- len(parts) >= 2- and parts[0].lower() in acquisition_sources- and parts[1]- and not urlsplit(parts[1]).scheme- ):- # Legacy key-first rows spell `<source> | <path> | ...`.- path_part = parts[1]+ 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).nameif not filename:continue- metadata = {- field: raw- for part in parts[1:]- if '=' in part- for field, raw in [part.split('=', 1)]- }entries[filename].append({'key': str(key),'path': path_part,- **metadata,+ 'source': parsed['source'],+ 'pattern': parsed['pattern'],+ 'crop': parsed['crop'],+ 'legacy': parsed['legacy'],})- return dict(entries), None+ error = (+ f"{lock_path}: " + "; ".join(errors)+ if errors+ else None+ )+ return dict(entries), errordef _load_project_lock_images(self, project_path: Path) -> set[str]:"""Return filenames listed under spec_lock.md images."""@@ -6504,21 +6571,30 @@ class SVGQualityChecker:def _load_project_svg_image_references(cls,project_path: Path,- ) -> Tuple[Dict[Path, Dict[str, set[Path]]], Dict[Path, int]]:- """Parse external image paths and count inline images in generated SVGs."""+ ) -> 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 {}, {}+ 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 sorted(svg_dir.glob('*.svg')):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 root.iter(f'{{{SVG_NS}}}image'):+ for element in images:href = (element.get('href')or element.get(f'{{{XLINK_NS}}}href')@@ -6531,6 +6607,15 @@ class SVGQualityChecker:if not filename:continuereferences.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,@@ -6541,7 +6626,39 @@ class SVGQualityChecker:out[svg_path] = dict(references)if inline_count:inline_counts[svg_path] = inline_count- return out, inline_counts+ 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,@@ -6551,6 +6668,10 @@ class SVGQualityChecker: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()@@ -6594,12 +6715,22 @@ class SVGQualityChecker:'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@@ -6628,6 +6759,24 @@ class SVGQualityChecker: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',@@ -6695,6 +6844,18 @@ class SVGQualityChecker: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 = (@@ -6722,6 +6883,51 @@ class SVGQualityChecker: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', '')@@ -6825,6 +7031,44 @@ class SVGQualityChecker:"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:+ for svg_path, raw_aspect, mechanisms in image_placements.get(+ filename,+ [],+ ):+ 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+ if align != 'xMidYMid' or 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 its "+ f"rendered placement uses "+ f"preserveAspectRatio={actual!r}; use xMidYMid meet.",+ ))+ if mechanisms:+ self._illustration_issues.append((+ 'error',+ 'no_crop_image_clipped',+ f"{svg_path.name}: {filename} is no-crop but its "+ "rendered placement is affected by "+ f"{', '.join(mechanisms)}; remove clipping so every "+ "source pixel remains visible.",+ ))+self._check_sourced_image_provenance(rows_by_filename,project_path,diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml/elements.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml/elements.pyindex 23832376..2c262709 100644--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml/elements.py+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml/elements.py@@ -25,7 +25,10 @@ from pptx_shapes import ()from pptx_effects import EFFECT_REASON_ATTR, EFFECT_STATUS_ATTRfrom pptx_to_svg.preset_authoring import AUTHORING_ATTR, AUTHORING_VALUE-from resource_paths import resolve_external_image_reference+from resource_paths import (+ resolve_external_image_reference,+ svg_image_payload_error,+)from .context import ConvertContext, ShapeResultfrom .theme_colors import color_node_xml@@ -259,11 +262,7 @@ def _valid_project_image_payload(img_format: str, img_data: bytes) -> bool:if not img_data:return Falseif img_format == 'svg':- try:- root = ET.fromstring(img_data)- except ET.ParseError:- return False- return root.tag == f'{{{SVG_NS}}}svg'+ return svg_image_payload_error(img_data) is Noneif img_format == 'emf':return _valid_emf_payload(img_data)if img_format == 'wmf':@@ -3494,16 +3493,94 @@ def _picture_xfrm_from_svg_rect(return _picture_xfrm_from_rect(ctx, resolved_x, resolved_y, resolved_w, resolved_h)-def _read_image_size(data: bytes) -> tuple[int | None, int | None]:+def _picture_rendered_frame_size(+ ctx: ConvertContext,+ raw_x: float,+ raw_y: float,+ raw_w: float,+ raw_h: float,+ resolved_x: float,+ resolved_y: float,+ resolved_w: float,+ resolved_h: float,+ transform: str | None,+) -> tuple[float, float]:+ """Return final DrawingML picture-axis lengths in rendered SVG pixels."""+ _attr, _x, _y, ext_cx, ext_cy, _bounds = _picture_xfrm_from_svg_rect(+ ctx,+ raw_x,+ raw_y,+ raw_w,+ raw_h,+ resolved_x,+ resolved_y,+ resolved_w,+ resolved_h,+ transform,+ )+ emu_per_px = px_to_emu(1.0)+ return ext_cx / emu_per_px, ext_cy / emu_per_px+++def _read_svg_image_size(data: bytes) -> tuple[float, float] | None:+ """Read an SVG image's viewport ratio from root dimensions or viewBox."""+ try:+ root = ET.fromstring(data)+ except ET.ParseError:+ return None+ if root.tag != f'{{{SVG_NS}}}svg':+ return None++ try:+ width = parse_svg_length(root.get('width'))+ height = parse_svg_length(root.get('height'))+ except ValueError:+ width = 0.0+ height = 0.0+ if (+ width > 0+ and height > 0+ and math.isfinite(width)+ and math.isfinite(height)+ ):+ return width, height++ view_box = root.get('viewBox')+ if view_box:+ parts = [+ part for part in re.split(r'[\s,]+', view_box.strip())+ if part+ ]+ try:+ values = [float(part) for part in parts]+ except ValueError:+ values = []+ if (+ len(values) == 4+ and all(math.isfinite(value) for value in values)+ and values[2] > 0+ and values[3] > 0+ ):+ return values[2], values[3]+ return None+++def _read_image_size(data: bytes) -> tuple[float | None, float | None]:"""Read intrinsic image dimensions (width, height) from raw bytes.Used by ``convert_image`` to translate SVG ``preserveAspectRatio`` intoDrawingML ``<a:srcRect>`` so the original image is preserved and remainscroppable inside PowerPoint.- Returns ``(None, None)`` on any failure — callers fall back to the- legacy stretch behaviour.+ SVG images use valid root ``width`` / ``height`` as the viewport ratio and+ fall back to ``viewBox`` when either dimension is unavailable. Raster+ images use EXIF-normalized pixel dimensions. Returns ``(None, None)`` on+ any failure."""+ svg_size = _read_svg_image_size(data)+ if svg_size is not None:+ return svg_size+try:from PIL import Image, ImageOps, UnidentifiedImageError # type: ignoreexcept ImportError:@@ -3578,58 +3655,119 @@ def _image_target_size(return target_w, target_h+def _visible_source_scale_floor(+ img_w: int,+ img_h: int,+ display_w: float,+ display_h: float,+ visible_source_fraction: tuple[float, float],+) -> float:+ """Keep each rendered axis at or below its visible source pixels."""+ fraction_w, fraction_h = visible_source_fraction+ visible_w = img_w * fraction_w+ visible_h = img_h * fraction_h+ if visible_w <= 0 or visible_h <= 0:+ return 1.0+ return min(1.0, max(display_w / visible_w, display_h / visible_h))++def _fit_full_image_target(img_w: int,img_h: int,- box_w: float,- box_h: float,- align: str,- mode: str,+ display_w: float,+ display_h: float,*,sizing: str,max_dimension: int | None,scale: float,+ visible_source_fraction: tuple[float, float] | None = None,) -> tuple[int, int]:"""Size the full source image; never crop pixels.- ``cap`` mode only limits oversized source images by maximum dimension.- ``display`` mode sizes to the rendered SVG box budget.+ ``cap`` mode limits oversized sources unless that would leave a cropped+ or stretched picture with fewer visible source pixels than its final+ rendered frame. ``display`` mode targets the configured rendered-frame+ scale while retaining the same one-source-pixel-per-display-pixel floor."""if img_w <= 0 or img_h <= 0:return (1, 1)+ enforce_visible_floor = visible_source_fraction is not None+ if enforce_visible_floor and (+ any(+ not math.isfinite(fraction) or fraction <= 0+ for fraction in visible_source_fraction+ )+ ):+ return (img_w, img_h)+if sizing == 'cap':- target_w, target_h = img_w, img_h- if max_dimension and max(target_w, target_h) > max_dimension:- ratio = max_dimension / max(target_w, target_h)- target_w = max(1, int(round(target_w * ratio)))- target_h = max(1, int(round(target_h * ratio)))+ ratio = 1.0+ if max_dimension and max(img_w, img_h) > max_dimension:+ ratio = max_dimension / max(img_w, img_h)+ if enforce_visible_floor:+ ratio = max(+ ratio,+ _visible_source_scale_floor(+ img_w,+ img_h,+ display_w,+ display_h,+ visible_source_fraction,+ ),+ )+ ratio = min(1.0, ratio)+ target_w = max(1, int(math.ceil(img_w * ratio)))+ target_h = max(1, int(math.ceil(img_h * ratio)))return target_w, target_h- target_box_w, target_box_h = _image_target_size(- box_w,- box_h,+ target_display_w, target_display_h = _image_target_size(+ display_w,+ display_h,max_dimension=None,scale=scale,)- img_ratio = img_w / img_h- box_ratio = box_w / box_h if box_h else img_ratio- if align != 'none' and mode == 'slice':- if box_ratio >= img_ratio:- target_w = target_box_w- target_h = int(round(target_w / img_ratio))- else:- target_h = target_box_h- target_w = int(round(target_h * img_ratio))+ if enforce_visible_floor:+ fraction_w, fraction_h = visible_source_fraction+ preferred_scale = min(+ 1.0,+ max(+ target_display_w / (img_w * fraction_w),+ target_display_h / (img_h * fraction_h),+ ),+ )+ visible_floor = _visible_source_scale_floor(+ img_w,+ img_h,+ display_w,+ display_h,+ visible_source_fraction,+ )+ resize_scale = preferred_scale+ if max_dimension and max(img_w, img_h) * resize_scale > max_dimension:+ resize_scale = max(+ visible_floor,+ max_dimension / max(img_w, img_h),+ )+ target_w = int(math.ceil(img_w * resize_scale))+ target_h = int(math.ceil(img_h * resize_scale))else:- ratio = min(target_box_w / img_w, target_box_h / img_h, 1.0)+ ratio = min(+ target_display_w / img_w,+ target_display_h / img_h,+ 1.0,+ )target_w = int(round(img_w * ratio))target_h = int(round(img_h * ratio))target_w = max(1, target_w)target_h = max(1, target_h)- if max_dimension and max(target_w, target_h) > max_dimension:+ if (+ not enforce_visible_floor+ and max_dimension+ and max(target_w, target_h) > max_dimension+ ):ratio = max_dimension / max(target_w, target_h)target_w = max(1, int(round(target_w * ratio)))target_h = max(1, int(round(target_h * ratio)))@@ -3648,7 +3786,10 @@ def _resize_for_target(img: Any, target_w: int, target_h: int) -> Any:from PIL import Image # type: ignoreexcept ImportError:return img- new_size = (max(1, int(round(width * ratio))), max(1, int(round(height * ratio))))+ new_size = (+ max(1, int(math.ceil(width * ratio))),+ max(1, int(math.ceil(height * ratio))),+ )return img.resize(new_size, Image.Resampling.LANCZOS)@@ -3672,12 +3813,13 @@ def _encode_optimized_image(img: Any, *, prefer_jpeg: bool, quality: int) -> tupdef _optimize_image_for_pptx(- elem: ET.Element,ctx: ConvertContext,img_data: bytes,img_format: str,- box_w: float,- box_h: float,+ display_w: float,+ display_h: float,+ *,+ visible_source_fraction: tuple[float, float] | None = None,) -> tuple[bytes, str]:"""Optimize full raster image bytes for native PPTX embedding."""if not ctx.image_optimize:@@ -3706,19 +3848,15 @@ def _optimize_image_for_pptx(geometry_normalized = _has_exif_geometry_transform(img)img = _prepare_raster_for_geometry(img)- align, mode = parse_project_image_aspect_ratio(- elem.get('preserveAspectRatio')- )target_w, target_h = _fit_full_image_target(img.size[0],img.size[1],- box_w,- box_h,- align,- mode,+ display_w,+ display_h,sizing=ctx.image_sizing,max_dimension=ctx.image_max_dimension,scale=ctx.image_scale,+ visible_source_fraction=visible_source_fraction,)original_size = img.size@@ -3766,35 +3904,37 @@ def _compute_slice_src_rect(visible_w = box_w / scale # ≤ img_wvisible_h = box_h / scale # ≤ img_h- if abs(visible_w - img_w) < 0.5 and abs(visible_h - img_h) < 0.5:+ if (+ math.isclose(visible_w, img_w, rel_tol=1e-9, abs_tol=1e-9)+ and math.isclose(visible_h, img_h, rel_tol=1e-9, abs_tol=1e-9)+ ):return None # No crop needed- crop_w_total = max(0.0, img_w - visible_w)- crop_h_total = max(0.0, img_h - visible_h)-x_anchor, y_anchor = PROJECT_IMAGE_ASPECT_RATIO_ANCHORS[align]-- crop_l = crop_w_total * x_anchor- crop_r = crop_w_total - crop_l- crop_t = crop_h_total * y_anchor- crop_b = crop_h_total - crop_t-- l = max(0, min(100000, int(round(crop_l / img_w * 100000))))- t = max(0, min(100000, int(round(crop_t / img_h * 100000))))- r = max(0, min(100000, int(round(crop_r / img_w * 100000))))- b = max(0, min(100000, int(round(crop_b / img_h * 100000))))+ crop_w_total = max(+ 0,+ min(99999, int(round((1.0 - visible_w / img_w) * 100000))),+ )+ crop_h_total = max(+ 0,+ min(99999, int(round((1.0 - visible_h / img_h) * 100000))),+ )+ l = max(0, min(crop_w_total, int(round(crop_w_total * x_anchor))))+ t = max(0, min(crop_h_total, int(round(crop_h_total * y_anchor))))+ r = crop_w_total - l+ b = crop_h_total - t+ if not any((l, t, r, b)):+ return Nonereturn (l, t, r, b)-def _resolve_image_src_rect(+def _resolve_image_src_rect_values(elem: ET.Element,img_data: bytes,box_w: float, box_h: float,-) -> str:- """Build ``<a:srcRect .../>`` XML for an SVG <image> based on its- preserveAspectRatio. Returns an empty string when no srcRect is needed- (meet mode, none mode, or already-aligned content).+) -> tuple[int, int, int, int] | None:+ """Resolve DrawingML source-crop values for an SVG slice image.Slice mode is resolved into a srcRect so the original image is embeddedintact and PowerPoint's crop tool / "Reset Picture" continue to work.@@ -3807,16 +3947,25 @@ def _resolve_image_src_rect()if align == 'none' or mode != 'slice':- return '' # meet handled by frame fit; none → stretch is correct per SVG spec+ return Noneimg_w, img_h = _read_image_size(img_data)if img_w is None or img_h is None:- return ''+ return None- rect = _compute_slice_src_rect(float(img_w), float(img_h), box_w, box_h, align)+ return _compute_slice_src_rect(+ float(img_w),+ float(img_h),+ box_w,+ box_h,+ align,+ )+++def _src_rect_xml(rect: tuple[int, int, int, int] | None) -> str:+ """Serialize an optional DrawingML source crop."""if rect is None:return ''-l, t, r, b = rectreturn f'<a:srcRect l="{l}" t="{t}" r="{r}" b="{b}"/>'@@ -3914,8 +4063,47 @@ def convert_image(elem: ET.Element, ctx: ConvertContext) -> ShapeResult | None:img_format = source.img_formatimg_data = source.img_data+ transform = elem.get('transform')+ rendered_w, rendered_h = _picture_rendered_frame_size(+ ctx,+ raw_x,+ raw_y,+ raw_w,+ raw_h,+ x,+ y,+ w,+ h,+ transform,+ )+ align, mode = parse_project_image_aspect_ratio(+ elem.get('preserveAspectRatio')+ )+ src_rect = _resolve_image_src_rect_values(+ elem,+ img_data,+ raw_w,+ raw_h,+ )+ visible_source_fraction = None+ if align == 'none':+ visible_source_fraction = (1.0, 1.0)+ elif mode == 'slice':+ if src_rect is None:+ visible_source_fraction = (1.0, 1.0)+ else:+ src_l, src_t, src_r, src_b = src_rect+ visible_source_fraction = (+ 1.0 - (src_l + src_r) / 100000.0,+ 1.0 - (src_t + src_b) / 100000.0,+ )img_data, img_format = _optimize_image_for_pptx(- elem, ctx, img_data, img_format, w, h,+ ctx,+ img_data,+ img_format,+ rendered_w,+ rendered_h,+ visible_source_fraction=visible_source_fraction,)img_idx = len(ctx.media_files) + 1@@ -3929,15 +4117,13 @@ def convert_image(elem: ET.Element, ctx: ConvertContext) -> ShapeResult | None:'target': f'../media/{img_filename}',})- transform = elem.get('transform')-# Resolve clip-path → DrawingML geometryclip_geom = _resolve_clip_geometry(elem, ctx, raw_x, raw_y, raw_w, raw_h)# Resolve preserveAspectRatio="<align> slice" as DrawingML crop metadata.# Image optimization only downscales the full source image; it never crops# pixels out of the embedded media.- src_rect_xml = _resolve_image_src_rect(elem, img_data, w, h)+ src_rect_xml = _src_rect_xml(src_rect)blip_xml = _build_image_blip_xml(r_id, get_element_opacity(elem, ctx))# Resolve preserveAspectRatio="<align> meet" by shrinking the picture@@ -4403,8 +4589,29 @@ def convert_nested_svg(elem: ET.Element, ctx: ConvertContext) -> ShapeResult:img_format = source.img_formatimg_data = source.img_data+ transform = elem.get('transform')+ rendered_w, rendered_h = _picture_rendered_frame_size(+ ctx,+ svg_x,+ svg_y,+ svg_w,+ svg_h,+ x,+ y,+ w,+ h,+ transform,+ )img_data, img_format = _optimize_image_for_pptx(- image_elem, ctx, img_data, img_format, w, h,+ ctx,+ img_data,+ img_format,+ rendered_w,+ rendered_h,+ visible_source_fraction=(+ 1.0 - (crop.src_l + crop.src_r) / 100000.0,+ 1.0 - (crop.src_t + crop.src_b) / 100000.0,+ ),)img_idx = len(ctx.media_files) + 1@@ -4418,8 +4625,6 @@ def convert_nested_svg(elem: ET.Element, ctx: ConvertContext) -> ShapeResult:'target': f'../media/{img_filename}',})- transform = elem.get('transform')-shape_id = _claim_element_shape_id(elem, ctx)xfrm_attr, off_x, off_y, ext_cx, ext_cy, bounds_emu = _picture_xfrm_from_svg_rect(ctx,diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.pyindex dcb1674f..1c07a6fa 100644--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py@@ -857,9 +857,11 @@ Recorded narration:parser.add_argument('--no-image-optimize', action='store_true',help='Disable native PPTX raster image optimization; embeds original image bytes.')parser.add_argument('--image-max-dimension', type=int, default=2560,- help='Maximum optimized raster image dimension in pixels (default: 2560).')+ help='Preferred optimized raster cap in pixels; cap mode may retain more '+ 'for cropped/stretched effective resolution (default: 2560).')parser.add_argument('--image-sizing', choices=['cap', 'display'], default='cap',- help='Raster sizing mode: cap only limits source dimensions; '+ help='Raster sizing mode: cap limits source dimensions without '+ 'undersupplying cropped/stretched visible pixels; ''display sizes from the SVG rendered box (default: cap).')parser.add_argument('--image-scale', type=float, default=2.0,help='Target optimized image pixels per SVG display pixel '