Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

feat(authoring): expose carrier use and batch native presets

hugohe30a040a3045f6
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 2e093bf2..1f1e95a3 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -175,6 +175,16 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`
2. **Quality Check Gate**: only after every planned SVG exists, run `python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final --json` directly on `svg_output/` without `tail` / `head` / `grep` filtering. One run already reports all pages. Review its complete issue set, fix every `error` plus any selected advisory warnings in one consolidated edit pass, then perform one verification rerun. If it still fails, its complete output begins the next batch cycle; never use checker calls to discover or fix one next issue at a time. Every `warning` is advisory: it never sends the page back for required modification, never authorizes automatic rewriting of compatible user syntax, and needs no acknowledgement/disposition line. Recommendation warnings describe the generated-SVG default; fidelity/quality warnings may be surfaced when material, while the existing input remains releasable. Prototype-identical diagnostics are recorded as `inherited`, source conversion losses as `source-import`, changed/new advisories as `introduced`, and release failures as `blocking` in `validation/svg_quality_report.json`. If release truly depends on a condition, it belongs in `errors`. On success, use the exit status and terminal summary; do not open or `cat` the complete JSON into model context. If terminal output is truncated on failure, read only the relevant issue arrays from the report written by that same run. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.
3. **Logic Construction Phase (conditional)**: after SVGs pass the quality check, batch-generate speaker notes for narrative continuity only when the effective Speaker Notes outcome is enabled.
+**Mandatory — final carrier-receipt review**: The final checker prints one
+factual `[CARRIERS]` summary and stores per-page detail under
+`files[].info.carrier_receipt`. Compare the summary with the retained page jobs,
+chosen resource roles, and running geometry signatures before export. Counts
+and diversity never create a quota or prove quality; zero use remains valid.
+When the facts contradict an active decision—such as an adopted preset absent
+from output, a primary image reduced to a minor frame, or unrelated jobs
+collapsing to one neutral construction—read only the affected receipt rows,
+repair those pages in one consolidated pass, and rerun the final checker.
+
### 3.0 Native Shape Selection
**Hard rule — contour before encoding**: choose the page-fit contour from the
diff --git a/skills/ppt-master/references/native-shape-authoring.md b/skills/ppt-master/references/native-shape-authoring.md
index 1ef07486..2c33258d 100644
--- a/skills/ppt-master/references/native-shape-authoring.md
+++ b/skills/ppt-master/references/native-shape-authoring.md
@@ -42,8 +42,11 @@ or contrast. Independently resolve page-field / carrier fit from ownership,
focal hierarchy, boundary strength, and the active deck's edge / opening
language; `Structure=no` removes only relationship topology. Choose a plain
primitive, uniform grid, or no drawn carrier only when that lack of inflection
-gives the reader a concrete benefit or avoids a false inference; retain that
-effect in active context. Quick speed, restrained style, readability, equal
+gives the reader a concrete benefit or avoids a false inference. Retain that
+reader effect through authoring. Before that neutral result wins, name the
+strongest fitting native / compound alternative and retain why its inflection
+would add no reader benefit, create a false inference, weaken hierarchy, or
+conflict with the page job. Quick speed, restrained style, readability, equal
importance, precedent, and shorter syntax alone do not qualify.
**Hard rule — style does not narrow capability**: the active visual system may
@@ -72,6 +75,10 @@ hand-author a freeform merely because an SVG path is convenient.
`data-pptx-authoring="preset"`. Never add `data-pptx-prst`, frame, adjustment,
or registry path data by hand. Insert the helper's complete compact `<g>` and
rerun the helper whenever its geometry, paint, or filter reference changes.
+After selecting two or more objects for one current page or template
+construction, use `render-batch --input -` to validate and emit their
+independent fragments in one stdout round; the batch never chooses those
+objects or their composition.
---
@@ -197,8 +204,8 @@ siblings whenever one-object contour semantics are unnecessary.
## 3. Fragment Generation
-One helper invocation owns one selected object; multiple chosen objects may
-render in one tool round as separate outputs.
+`render` emits one selected object. `render-batch` atomically emits multiple
+already-selected objects for one current page or template construction.
Generated project pages choose each object's solid paint from the current page
context, using `spec_lock.md` roles as reusable anchors rather than an exhaustive
palette; `create-template` takes colors from the confirmed brief and template
@@ -234,11 +241,13 @@ Every connector-family preset requires `--object-kind connector`, `--fill none`,
and a visible stroke. It exports as an unconnected `p:cxnSp`; a connector
preset can never be authored as an ordinary `shape`.
-**Hard rule — stdout-only exception**: the helper prints one deterministic
-`<g>` fragment. Read that output and insert it with the normal page/template
-`apply_patch` edit. Do not redirect it into `svg_output/`, drive it from a batch
-manifest, loop over pages/templates, or let it choose layout. The main Agent
-still authors each complete SVG page and reusable template explicitly.
+**Hard rule — stdout-only exception**: the helper prints one or more
+deterministic `<g>` fragments. Read that output and insert it with the normal
+page/template `apply_patch` edit. A batch JSON array is transient input for
+already-selected objects in the current construction, never a project resource
+or multi-page plan. Do not redirect output into `svg_output/`, loop over
+pages/templates, or let the helper choose layout. The main Agent still authors
+each complete SVG page and reusable template explicitly.
---
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 2a905176..5ce345bb 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -194,12 +194,18 @@ python3 scripts/native_enhance_pptx.py apply <project_path>
python3 scripts/pptx_delivery_check.py <finished.pptx>
```
-Native preset shape authoring (one registry-backed fragment on stdout):
+Native preset shape authoring (one or more registry-backed fragments on stdout):
```bash
python3 scripts/preset_shape_svg.py list --search arrow
python3 scripts/preset_shape_svg.py describe rightArrow
python3 scripts/preset_shape_svg.py render rightArrow --id process-arrow --frame 120 180 240 96 --fill '#2563EB'
+python3 scripts/preset_shape_svg.py render-batch --input - <<'JSON'
+[
+ {"preset":"chevron","id":"step-1","frame":[120,180,220,96],"fill":"#2563EB","stroke":"none"},
+ {"preset":"leftBrace","id":"group-brace","frame":[380,170,48,240],"fill":"none","stroke":"#111827","stroke_width":3}
+]
+JSON
```
The helper never writes a page or project file. Select one exact semantic
@@ -209,7 +215,11 @@ is one compact atomic `<g>` with direct registry-generated visible paths. When
one effect is justified, optional `--filter-id softShadow` references one
existing direct page-level filter under the shared shadow/glow contract and
applies it once to a shape preset. Connector presets do not accept that option.
-The helper does not create the filter definition.
+The helper does not create the filter definition. `render-batch` accepts a
+non-empty JSON array using the snake_case forms of the single-render options;
+it validates every item and duplicate id before printing, so one invalid item
+produces no partial fragment output. The batch remains fragment-only input for
+one current construction, not a page generator or project manifest.
Quality check and export rerender the registry instead of relying on a hidden
carrier, preview wrapper, or stored preview fingerprint. PPTX import and
round-trip SVGs deliberately keep their expanded carrier/preview evidence and
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index aab7c049..73def5c1 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -650,6 +650,7 @@ Behavior:
- Native export writes to a temporary file first and publishes the requested PPTX only after conversion succeeds. A failed conversion does not replace the main output file.
- `--conversion-trace` without a path writes `validation/<output_stem>.trace.json`. `--conversion-trace <path>` respects the explicit destination; relative paths are resolved from the project root, so `exports/<name>.trace.json` remains available when intentionally requested.
- Formal default and `--quick-generate` release export compute the exact SVG source fingerprint and refuse a missing, unreadable, unsupported, non-final, blocking, stale, or unverifiable final quality report before PPTX creation. A project without `validation/svg_quality_report.json` exits nonzero with the `not-provided` gate status; run the final checker against its current `svg_output/` first. An explicit non-`output` `--source` remains a diagnostic override and bypasses this release gate; postflight still records any verifiable report linkage.
+- The final quality report carries an informational `carrier_receipt` aggregate plus each page's `files[].info.carrier_receipt`: actual text/image/icon counts, SVG geometry, native preset names, marker use, native Chart/Table/Formula markers, and largest image-frame share. The terminal prints only the compact aggregate. These facts never affect exit status, create coverage quotas, or score design; the active Generate profile compares them with its retained page decisions before export.
- After publication, native export writes `validation/<output_stem>.report.json`. The report distinguishes authored Slides from internal Layout definitions, reruns ZIP integrity and published Slide-count checks, records slide/layout/master/notes part counts, labels relationship/structured/transition/animation validation as enforced at build time, links the final SVG quality report only when its SHA-256 source fingerprint matches the exact export inputs, and surfaces stale/unverified gates, unresolved template tokens, generic-only font stacks, and external image references. A matching final quality report with introduced warnings yields `passed-with-warnings` and a `quality_introduced_warnings=<N>` receipt instead of a clean `passed` claim.
- By default, a successful command also prints a compact receipt instead of requiring a report read: `[POSTFLIGHT] status=<...> quality_gate=<...> slides=<N> warning_categories=<N>`, followed by one compact line per warning category and the `[PPTX]` / `[REPORT]` paths. Resource-warning lines carry counts; a non-passing quality gate carries its status. Routine agents use this receipt and do not load either complete validation JSON into model context. Full reports remain cold audit artifacts; failure investigation and explicit audits extract only the required fields. `--quiet` keeps suppressing successful-run output.
- Before publishing structured template output, export reopens the temporary PPTX and validates the Slide → Layout → Master graph and registrations, Layout identity, placeholder identity, reusable bounds, and prompt/level-one sizes. A mismatch aborts publication. Flat release instead validates its single referenced Master/Layout shell and exact date/footer/slide-number hook roster before packaging.
diff --git a/skills/ppt-master/scripts/preset_shape_svg.py b/skills/ppt-master/scripts/preset_shape_svg.py
index 8ef40480..3bd574fa 100644
--- a/skills/ppt-master/scripts/preset_shape_svg.py
+++ b/skills/ppt-master/scripts/preset_shape_svg.py
@@ -2,19 +2,21 @@
"""
PPT Master - Preset Shape SVG Fragment Tool
-List DrawingML presets or print one compact canonical native-preset SVG group to
+List DrawingML presets or print compact canonical native-preset SVG groups to
stdout for manual insertion into a hand-authored page or template.
Usage:
python3 scripts/preset_shape_svg.py list [--search QUERY]
python3 scripts/preset_shape_svg.py describe PRESET
python3 scripts/preset_shape_svg.py render PRESET --id ID --frame X Y W H
+ python3 scripts/preset_shape_svg.py render-batch --input FILE_OR_DASH
Examples:
python3 scripts/preset_shape_svg.py list --search arrow
python3 scripts/preset_shape_svg.py describe rightArrow
python3 scripts/preset_shape_svg.py render rightArrow --id next-step \
--frame 160 210 320 112 --fill "#2563EB" --stroke none
+ python3 scripts/preset_shape_svg.py render-batch --input shapes.json
Dependencies:
None (only uses standard library and local PPT Master modules)
@@ -25,6 +27,7 @@ from __future__ import annotations
import argparse
import json
import sys
+from pathlib import Path
from typing import Sequence
from console_encoding import configure_utf8_stdio
@@ -35,6 +38,24 @@ from pptx_to_svg.preset_authoring import render_preset_shape_fragment
configure_utf8_stdio()
+_BATCH_ITEM_FIELDS = frozenset({
+ "preset",
+ "id",
+ "frame",
+ "object_kind",
+ "name",
+ "fill",
+ "fill_opacity",
+ "stroke",
+ "stroke_width",
+ "stroke_opacity",
+ "stroke_linecap",
+ "stroke_linejoin",
+ "filter_id",
+ "adjustments",
+})
+
+
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
description=(
@@ -140,6 +161,20 @@ def build_parser() -> argparse.ArgumentParser:
"for example --adjust 'adj1=val 50000'."
),
)
+
+ batch_parser = subparsers.add_parser(
+ "render-batch",
+ help="Print multiple canonical authored-preset fragments atomically.",
+ )
+ batch_parser.add_argument(
+ "--input",
+ required=True,
+ metavar="FILE_OR_DASH",
+ help=(
+ "UTF-8 JSON array of shape objects; use - to read stdin. "
+ "The command prints no fragments when any item is invalid."
+ ),
+ )
return parser
@@ -179,6 +214,16 @@ def main(argv: Sequence[str] | None = None) -> int:
print(json.dumps(payload, ensure_ascii=False, indent=2))
return 0
+ if args.command == "render-batch":
+ try:
+ items = _read_batch_items(args.input)
+ fragments = _render_batch_items(items)
+ except ValueError as exc:
+ print(f"Error: {exc}", file=sys.stderr)
+ return 1
+ print("\n".join(fragments))
+ return 0
+
try:
adjustments = _parse_adjustments(args.adjust)
style = _style_from_args(args)
@@ -216,26 +261,133 @@ def _parse_adjustments(values: Sequence[str]) -> dict[str, str]:
def _style_from_args(args: argparse.Namespace) -> dict[str, str]:
+ return _style_from_values(
+ fill=args.fill,
+ fill_opacity=args.fill_opacity,
+ stroke=args.stroke,
+ stroke_width=args.stroke_width,
+ stroke_opacity=args.stroke_opacity,
+ stroke_linecap=args.stroke_linecap,
+ stroke_linejoin=args.stroke_linejoin,
+ )
+
+
+def _style_from_values(
+ *,
+ fill: object = "none",
+ fill_opacity: object | None = None,
+ stroke: object = "none",
+ stroke_width: object | None = None,
+ stroke_opacity: object | None = None,
+ stroke_linecap: object | None = None,
+ stroke_linejoin: object | None = None,
+) -> dict[str, str]:
+ fill_text = str(fill)
+ stroke_text = str(stroke)
style = {
- "fill": args.fill,
- "stroke": args.stroke,
+ "fill": fill_text,
+ "stroke": stroke_text,
}
- if args.fill_opacity is not None:
- style["fill-opacity"] = str(args.fill_opacity)
- if args.stroke != "none":
+ if fill_opacity is not None:
+ style["fill-opacity"] = str(fill_opacity)
+ if stroke_text != "none":
style["stroke-width"] = str(
- 1.0 if args.stroke_width is None else args.stroke_width
+ 1.0 if stroke_width is None else stroke_width
)
- elif args.stroke_width is not None:
+ elif stroke_width is not None:
raise ValueError("--stroke-width requires a non-none --stroke")
- if args.stroke_opacity is not None:
- style["stroke-opacity"] = str(args.stroke_opacity)
- if args.stroke_linecap is not None:
- style["stroke-linecap"] = args.stroke_linecap
- if args.stroke_linejoin is not None:
- style["stroke-linejoin"] = args.stroke_linejoin
+ if stroke_opacity is not None:
+ style["stroke-opacity"] = str(stroke_opacity)
+ if stroke_linecap is not None:
+ style["stroke-linecap"] = str(stroke_linecap)
+ if stroke_linejoin is not None:
+ style["stroke-linejoin"] = str(stroke_linejoin)
return style
+def _read_batch_items(input_path: str) -> list[object]:
+ """Read one JSON array from a path or stdin."""
+ try:
+ raw = (
+ sys.stdin.read()
+ if input_path == "-"
+ else Path(input_path).read_text(encoding="utf-8")
+ )
+ except OSError as exc:
+ raise ValueError(f"Cannot read batch input {input_path!r}: {exc}") from exc
+ try:
+ payload = json.loads(raw)
+ except json.JSONDecodeError as exc:
+ raise ValueError(
+ f"Invalid batch JSON at line {exc.lineno}, column {exc.colno}: {exc.msg}"
+ ) from exc
+ if not isinstance(payload, list) or not payload:
+ raise ValueError("Batch input must be a non-empty JSON array")
+ return payload
+
+
+def _render_batch_items(items: Sequence[object]) -> list[str]:
+ """Validate every batch item, then return all fragments together."""
+ fragments: list[str] = []
+ element_ids = set()
+ for index, raw_item in enumerate(items):
+ label = f"items[{index}]"
+ if not isinstance(raw_item, dict):
+ raise ValueError(f"{label} must be a JSON object")
+ unknown = sorted(set(raw_item) - _BATCH_ITEM_FIELDS)
+ if unknown:
+ raise ValueError(f"{label} has unsupported fields: {', '.join(unknown)}")
+ missing = [
+ name for name in ("preset", "id", "frame")
+ if name not in raw_item
+ ]
+ if missing:
+ raise ValueError(f"{label} is missing: {', '.join(missing)}")
+
+ element_id = str(raw_item["id"])
+ if element_id in element_ids:
+ raise ValueError(f"{label} duplicates SVG element id {element_id!r}")
+ element_ids.add(element_id)
+ frame = raw_item["frame"]
+ if not isinstance(frame, list) or len(frame) != 4:
+ raise ValueError(f"{label}.frame must be a four-number JSON array")
+ adjustments = raw_item.get("adjustments", {})
+ if not isinstance(adjustments, dict):
+ raise ValueError(f"{label}.adjustments must be a JSON object")
+
+ try:
+ style = _style_from_values(
+ fill=raw_item.get("fill", "none"),
+ fill_opacity=raw_item.get("fill_opacity"),
+ stroke=raw_item.get("stroke", "none"),
+ stroke_width=raw_item.get("stroke_width"),
+ stroke_opacity=raw_item.get("stroke_opacity"),
+ stroke_linecap=raw_item.get("stroke_linecap"),
+ stroke_linejoin=raw_item.get("stroke_linejoin"),
+ )
+ fragment = render_preset_shape_fragment(
+ str(raw_item["preset"]),
+ tuple(frame),
+ adjustments=adjustments,
+ object_kind=str(raw_item.get("object_kind", "shape")),
+ element_id=element_id,
+ name=(
+ str(raw_item["name"])
+ if raw_item.get("name") is not None
+ else None
+ ),
+ style=style,
+ filter_id=(
+ str(raw_item["filter_id"])
+ if raw_item.get("filter_id") is not None
+ else None
+ ),
+ )
+ except (TypeError, ValueError) as exc:
+ raise ValueError(f"{label}: {exc}") from exc
+ fragments.append(fragment)
+ return fragments
+
+
if __name__ == "__main__":
raise SystemExit(main())
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index 92a098e0..668c80b3 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -345,14 +345,14 @@
"max_tokens": 125000
},
"route.generate.quick-generate.hyperlink": {
- "description": "Quick Generate with direct PowerPoint-native external and same-deck hyperlink authoring.",
+ "description": "Quick Generate with direct PowerPoint-native external and same-deck hyperlink authoring. Ceiling raised after BUDGET_LOAD_SET reported 110212 tokens.",
"scope": "cumulative",
"include": [
"route.generate.quick-generate",
"stage.generate.executor.hyperlink"
],
"files": [],
- "max_tokens": 110000
+ "max_tokens": 125000
},
"route.generate.quick-generate.ai-two-types": {
"description": "Quick Generate with AI resource preparation, representative rendering inputs, and two local image types. Ceiling raised after BUDGET_LOAD_SET reported 140175 tokens.",
@@ -976,12 +976,12 @@
"max_tokens": 1000
},
"stage.create-template.authored-preset": {
- "description": "Conditional native preset and Boolean shape authoring reference for Create Layout/Create Deck.",
+ "description": "Conditional native preset and Boolean shape authoring reference for Create Layout/Create Deck. Ceiling raised after BUDGET_LOAD_SET reported 6618 tokens.",
"scope": "incremental",
"files": [
"skills/ppt-master/references/native-shape-authoring.md"
],
- "max_tokens": 6500
+ "max_tokens": 7500
},
"route.generate.planning-template": {
"description": "Generate-PPTX planning context after an explicit template workspace is installed. Ceiling raised after BUDGET_LOAD_SET reported 119170 tokens.",
@@ -1090,12 +1090,12 @@
"max_tokens": 1000
},
"stage.generate.executor.native-shape": {
- "description": "Stock PowerPoint shape selection and Boolean materialization authority, always included in Generate Executor contexts.",
+ "description": "Stock PowerPoint shape selection and Boolean materialization authority, always included in Generate Executor contexts. Ceiling raised after BUDGET_LOAD_SET reported 6618 tokens.",
"scope": "incremental",
"files": [
"skills/ppt-master/references/native-shape-authoring.md"
],
- "max_tokens": 6500
+ "max_tokens": 7500
},
"stage.shared.svg-effects": {
"description": "Advanced SVG paint, effects, transforms, and geometry authority, always included in Generate Executor contexts and conditionally loaded by other SVG-authoring routes.",
diff --git a/skills/ppt-master/scripts/svg_quality/checker.py b/skills/ppt-master/scripts/svg_quality/checker.py
index 30cd95fb..9c2e9f3f 100644
--- a/skills/ppt-master/scripts/svg_quality/checker.py
+++ b/skills/ppt-master/scripts/svg_quality/checker.py
@@ -1177,6 +1177,7 @@ class SVGQualityChecker:
expected_viewbox_label=expected_viewbox_label,
)
self._check_legacy_pptx_attributes(root, svg_path, result)
+ self._record_carrier_receipt(root, result)
# 1a. Validate exact importer transport before compatible
# inline geometry is materialized on the shared tree.
@@ -1438,6 +1439,208 @@ class SVGQualityChecker:
)
)
+ def _record_carrier_receipt(
+ self,
+ root: ET.Element,
+ result: Dict,
+ ) -> None:
+ """Record factual visible-carrier use without grading the design."""
+ parent_by_id = {
+ id(child): parent
+ for parent in root.iter()
+ for child in list(parent)
+ }
+ geometry_tags = (
+ 'rect',
+ 'circle',
+ 'ellipse',
+ 'line',
+ 'polyline',
+ 'polygon',
+ 'path',
+ )
+ geometry_counts = Counter({tag: 0 for tag in geometry_tags})
+ preset_names: Counter[str] = Counter()
+ native_objects = Counter({
+ 'chart': 0,
+ 'table': 0,
+ 'formula_block': 0,
+ 'formula_inline': 0,
+ 'other': 0,
+ })
+ marker_counts = Counter({'start': 0, 'mid': 0, 'end': 0})
+ text_count = 0
+ icon_count = 0
+ page_frame_geometry = 0
+
+ for element in root.iter():
+ if (
+ element is root
+ or self._is_hidden_element(element, parent_by_id)
+ or self._has_non_visual_ancestor(element, root, parent_by_id)
+ or self._has_zero_opacity(element, parent_by_id)
+ ):
+ continue
+
+ tag = _local_name(element)
+ if tag == 'text':
+ text_count += 1
+ elif tag == 'use' and element.get('data-icon') is not None:
+ icon_count += 1
+
+ if element.get(_INLINE_FORMULA_ATTR) is not None:
+ native_objects['formula_inline'] += 1
+ replacement_kind = self._carrier_native_replacement_kind(element)
+ if replacement_kind:
+ key = (
+ 'formula_block'
+ if replacement_kind == 'formula'
+ else replacement_kind
+ )
+ native_objects[key if key in native_objects else 'other'] += 1
+
+ preset = (element.get('data-pptx-prst') or '').strip()
+ if preset:
+ preset_names[preset] += 1
+ if self._carrier_page_frame_role(element, root, parent_by_id):
+ page_frame_geometry += 1
+ continue
+ if tag not in geometry_counts or self._has_preset_ancestor(
+ element,
+ root,
+ parent_by_id,
+ ):
+ continue
+
+ geometry_counts[tag] += 1
+ if self._carrier_page_frame_role(element, root, parent_by_id):
+ page_frame_geometry += 1
+ style_values = (
+ _parse_inline_style(element.get('style'))
+ if _parse_inline_style is not None
+ else {}
+ )
+ for position in ('start', 'mid', 'end'):
+ raw_marker = (
+ style_values.get(f'marker-{position}')
+ or element.get(f'marker-{position}')
+ or ''
+ ).strip().lower()
+ if raw_marker and raw_marker != 'none':
+ marker_counts[position] += 1
+
+ image_receipt = self._carrier_image_receipt(root)
+ result['info']['carrier_receipt'] = {
+ 'text_elements': text_count,
+ 'images': image_receipt,
+ 'icons': icon_count,
+ 'geometry': {
+ 'svg_elements': dict(geometry_counts),
+ 'preset_shapes': sum(preset_names.values()),
+ 'preset_names': dict(sorted(preset_names.items())),
+ 'page_frame_elements': page_frame_geometry,
+ 'marker_uses': dict(marker_counts),
+ },
+ 'native_objects': dict(native_objects),
+ }
+
+ @staticmethod
+ def _carrier_native_replacement_kind(element: ET.Element) -> str:
+ """Return one native replacement kind without turning bad data into a check."""
+ if _native_replacement_kind is not None:
+ try:
+ return (_native_replacement_kind(element) or '').strip().lower()
+ except ValueError:
+ pass
+ return (
+ element.get('data-pptx-replace-with')
+ or element.get('data-pptx-native')
+ or ''
+ ).strip().lower()
+
+ @staticmethod
+ def _has_preset_ancestor(
+ element: ET.Element,
+ root: ET.Element,
+ parent_by_id: Dict[int, ET.Element],
+ ) -> bool:
+ """Return whether geometry is only the visible detail of a preset atom."""
+ current = parent_by_id.get(id(element))
+ while current is not None and current is not root:
+ if (current.get('data-pptx-prst') or '').strip():
+ return True
+ current = parent_by_id.get(id(current))
+ return False
+
+ @staticmethod
+ def _carrier_page_frame_role(
+ element: ET.Element,
+ root: ET.Element,
+ parent_by_id: Dict[int, ET.Element],
+ ) -> bool:
+ """Return whether an element belongs to declared page framing."""
+ current: ET.Element | None = element
+ while current is not None:
+ role = (current.get('data-pptx-role') or '').strip().lower()
+ if role in {'background', 'decoration'}:
+ return True
+ if current is root:
+ break
+ current = parent_by_id.get(id(current))
+ return False
+
+ def _carrier_image_receipt(self, root: ET.Element) -> Dict:
+ """Summarize visible image placements and their frame share."""
+ working_root, parent_by_id, images = self._visible_image_elements(root)
+ viewbox = _parse_viewbox_values(working_root.get('viewBox') or '')
+ canvas_area = (
+ abs(viewbox[2] * viewbox[3])
+ if viewbox is not None and viewbox[2] and viewbox[3]
+ else 0.0
+ )
+ frame_shares: List[float] = []
+ filenames = set()
+
+ for image in images:
+ href = image.get('href') or image.get(f'{{{XLINK_NS}}}href') or ''
+ if href.startswith('data:'):
+ filenames.add('(embedded)')
+ elif href:
+ path_name = Path(unquote(urlsplit(href).path)).name
+ filenames.add(path_name or href[:80])
+
+ display_owner = image
+ parent = parent_by_id.get(id(image))
+ if (
+ parent is not None
+ and parent is not working_root
+ and _local_name(parent) == 'svg'
+ ):
+ display_owner = parent
+ try:
+ x = float(display_owner.get('x') or '0')
+ y = float(display_owner.get('y') or '0')
+ width = float(display_owner.get('width') or '0')
+ height = float(display_owner.get('height') or '0')
+ except (TypeError, ValueError):
+ continue
+ if width <= 0 or height <= 0 or canvas_area <= 0:
+ continue
+ transformed = self._transformed_rect_edge_lengths(
+ display_owner,
+ (x, y, width, height),
+ parent_by_id,
+ )
+ if transformed is not None:
+ width, height = transformed
+ frame_shares.append(abs(width * height) / canvas_area)
+
+ return {
+ 'placements': len(images),
+ 'files': sorted(filenames),
+ 'max_frame_share': round(max(frame_shares), 4) if frame_shares else 0.0,
+ }
+
def _check_fonts(self, content: str, result: Dict):
"""Check font usage.
@@ -6941,6 +7144,7 @@ class SVGQualityChecker:
f" [ERROR] With errors: {self.summary['errors']} ({self._percentage(self.summary['errors'])}%)")
self._print_provenance_category_summary()
+ self._print_carrier_receipt_summary()
if self.issue_types:
print(f"\nIssue categories:")
@@ -6981,6 +7185,119 @@ class SVGQualityChecker:
print(f" 4. foreignObject: Use <text> + <tspan> for manual line breaks")
print(f" 5. Font issues: use PPT-safe exported typefaces (e.g. Microsoft YaHei / Arial / Consolas)")
+ def _carrier_receipt_summary(self) -> Dict:
+ """Aggregate factual per-page carrier receipts for compact review."""
+ receipts = [
+ result.get('info', {}).get('carrier_receipt')
+ for result in self.results
+ if result.get('info', {}).get('carrier_receipt')
+ ]
+ totals = Counter({
+ 'text_elements': 0,
+ 'image_placements': 0,
+ 'icons': 0,
+ 'svg_geometry_elements': 0,
+ 'preset_shapes': 0,
+ 'page_frame_elements': 0,
+ 'marker_uses': 0,
+ })
+ pages_with = Counter({
+ 'images': 0,
+ 'icons': 0,
+ 'presets': 0,
+ 'charts': 0,
+ 'tables': 0,
+ 'formulas': 0,
+ })
+ geometry_counts: Counter[str] = Counter()
+ preset_names: Counter[str] = Counter()
+ native_objects: Counter[str] = Counter()
+ image_frame_shares: List[float] = []
+
+ for receipt in receipts:
+ images = receipt['images']
+ geometry = receipt['geometry']
+ native = receipt['native_objects']
+ totals['text_elements'] += receipt['text_elements']
+ totals['image_placements'] += images['placements']
+ totals['icons'] += receipt['icons']
+ totals['preset_shapes'] += geometry['preset_shapes']
+ totals['page_frame_elements'] += geometry['page_frame_elements']
+ totals['marker_uses'] += sum(geometry['marker_uses'].values())
+ geometry_counts.update(geometry['svg_elements'])
+ preset_names.update(geometry['preset_names'])
+ native_objects.update(native)
+
+ if images['placements']:
+ pages_with['images'] += 1
+ image_frame_shares.append(images['max_frame_share'])
+ if receipt['icons']:
+ pages_with['icons'] += 1
+ if geometry['preset_shapes']:
+ pages_with['presets'] += 1
+ if native.get('chart'):
+ pages_with['charts'] += 1
+ if native.get('table'):
+ pages_with['tables'] += 1
+ if native.get('formula_block') or native.get('formula_inline'):
+ pages_with['formulas'] += 1
+
+ totals['svg_geometry_elements'] = sum(geometry_counts.values())
+ frame_share_range = (
+ [round(min(image_frame_shares), 4), round(max(image_frame_shares), 4)]
+ if image_frame_shares
+ else []
+ )
+ return {
+ 'scope': 'informational-not-a-quota',
+ 'pages': len(receipts),
+ 'totals': dict(totals),
+ 'pages_with': dict(pages_with),
+ 'geometry_elements': dict(sorted(geometry_counts.items())),
+ 'preset_names': dict(sorted(preset_names.items())),
+ 'native_objects': dict(sorted(native_objects.items())),
+ 'image_page_max_frame_share_range': frame_share_range,
+ }
+
+ def _print_carrier_receipt_summary(self) -> None:
+ """Print a compact actual-use receipt without a score or threshold."""
+ if self.template_mode:
+ return
+ receipt = self._carrier_receipt_summary()
+ if not receipt['pages']:
+ return
+ totals = receipt['totals']
+ native = receipt['native_objects']
+ print("\n[CARRIERS] Actual-use receipt (informational; not a quota)")
+ print(
+ f" Pages: {receipt['pages']} | text: {totals['text_elements']} | "
+ f"images: {totals['image_placements']} | icons: {totals['icons']}"
+ )
+ print(
+ f" Geometry: SVG elements {totals['svg_geometry_elements']} | "
+ f"native presets {totals['preset_shapes']} | "
+ f"page-frame elements {totals['page_frame_elements']} | "
+ f"marker uses {totals['marker_uses']}"
+ )
+ print(
+ f" Native objects: charts {native.get('chart', 0)} | "
+ f"tables {native.get('table', 0)} | formulas "
+ f"{native.get('formula_block', 0) + native.get('formula_inline', 0)}"
+ )
+ presets = receipt['preset_names']
+ preset_text = (
+ ', '.join(f'{name} x{count}' for name, count in presets.items())
+ if presets
+ else '(none)'
+ )
+ print(f" Presets: {preset_text}")
+ image_range = receipt['image_page_max_frame_share_range']
+ if image_range:
+ print(
+ " Largest image-frame share on image pages: "
+ f"{image_range[0] * 100:.1f}%–{image_range[1] * 100:.1f}%"
+ )
+
def _print_provenance_category_summary(self):
"""Print compact JSON-equivalent counts for token-safe gate handling."""
categories = self._provenance_categories()
@@ -7386,6 +7703,7 @@ class SVGQualityChecker:
},
},
'drift': drift,
+ 'carrier_receipt': self._carrier_receipt_summary(),
'project_issues': project_issues,
'files': self.results,
}
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index 7e94b669..cde903a4 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -863,6 +863,7 @@ Before creating the PPTX, the exporter independently requires the current matchi
## ✅ Generate PPTX Complete
- [x] Image readiness gate passed
+- [x] The final carrier receipt was compared with the retained page decisions, and any factual contradiction was repaired without treating counts as quotas
- [x] Notes split completed when enabled; disabled exports used `--no-notes`
- [x] `svg_final/` preview completed
- [x] Native PPTX published and postflight report written
diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.md
index 3b2666dc..7a6d3a1c 100644
--- a/skills/ppt-master/workflows/profiles/quick-generate.md
+++ b/skills/ppt-master/workflows/profiles/quick-generate.md
@@ -647,7 +647,16 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> \
--quick-generate --stage final --json
```
-Fix every blocking error and rerun the same command. Then export:
+Fix every blocking error and rerun the same command.
+
+**Mandatory — final carrier-receipt review**: Review the factual
+`[CARRIERS]` summary against the retained page jobs, resource roles, and running
+geometry signatures before export. Counts and diversity are not quotas, and
+zero use is valid. When the summary contradicts an active decision, read only
+the affected `files[].info.carrier_receipt` rows from the current report, repair
+those pages in one consolidated pass, and rerun the same final checker.
+
+Then export:
When Speaker Notes is enabled, load
[`executor-notes.md`](../../references/executor-notes.md) after the passing final
@@ -726,6 +735,7 @@ or lock.
- [x] Resolved SVG pages and their project-local references exist
- [x] Every role declared by an installed template spec is locatable in the finished pages, or its non-use is deliberate — checked per installed spec, not from memory
- [x] Every triggered capability-specific preparation and pre-checker verification completed
+- [x] The current final report's carrier receipt was compared with the retained page jobs and any factual contradiction was repaired before export, without treating counts as quotas
- [x] The lockless final SVG quality report passes and matches the current SVGs
- [x] Enabled notes were validated/generated and split; enabled custom motion ran through its owning stage
- [x] One native PPTX exists under `exports/` or the explicit output path