PPTX authoring and editing

Reading is not in scope. To read an existing .pptx, use the harness read tool (markitdown extracts slide text). This skill is for writing and editing.

Quick reference

Generation modalities

HTML/CSS via PptxGenJS (preferred for visual fidelity):

node scripts/generate_pptxgenjs.js deck.json out.pptx

deck.json describes slides as a JSON tree; the script invokes PptxGenJS (and html2pptx for HTML inputs) to produce a fully-editable .pptx. Best for branded decks with gradients, custom fonts, complex shapes.

Markdown via Marp:

bash scripts/generate_marp.sh deck.md out.pptx

Best for content-heavy decks (lectures, reports) where markdown is more natural than JSON.

Programmatic via python-pptx: Best when shapes are computed (e.g., one slide per data row). Requires manual EMU positioning.

Editing existing decks

Three-step pattern, like docx:

python scripts/unpack.py input.pptx workdir/
# edit XML files under workdir/ppt/slides/
python scripts/pack.py workdir/ output.pptx
python scripts/validate.py output.pptx

For surgical shape edits without unpacking, use edit_shape.py:

python scripts/edit_shape.py input.pptx \
  --slide 2 --shape "Title 1" --op set_text --value "New title"

JSON patch ops: set_text, set_position (EMU), set_size, recolor, delete.

OOXML gotchas specific to pptx

• Use defusedxml.minidom, NOT xml.etree.ElementTree. ElementTree corrupts presentation namespaces during round-tripping. unpack.py and pack.py use minidom; if you write your own XML manipulation, do the same.
• EMU units everywhere. 1 inch = 914400 EMU. Slide positions, sizes, font sizes (in pt × 100) all use derived EMU values.
• Placeholders vs free shapes. Placeholders inherit from slide masters; free shapes don't. Editing a placeholder's text is <a:t> content; editing its layout requires master-slide changes.
• Don't pretty-print pptx XML on pack. Whitespace-significant runs (<a:r>) break if reformatted. pack.py preserves the original whitespace.
• Slide cloning is more than a file copy. Use unpack + pack — manual file copies miss the rIds in _rels/ and the Content_Types.xml registration.

Deterministic QA loop

After every generation, run:

python scripts/thumbnail.py deck.pptx thumbs/   # PDF + JPEGs per slide
python scripts/deterministic_qa.py deck.pptx > qa.json

deterministic_qa.py checks:

• Shape bounding boxes don't extend past slide edges
• No two shapes overlap with > 50% area intersection
• Font sizes ≥ 11pt for body text, ≥ 18pt for titles
• All placeholders are filled (no Click to add title defaults)
• Bullet lists don't exceed 7 items per slide

Output is JSON listing each violation with slide number and shape id. Fix violations and re-render.

(A vision-model QA pass is intentionally out of scope for v1. Add --use-vision later if deterministic checks miss layout issues.)

Validation gate

Always run validate.py before declaring done. Schema-validates against ECMA-376 PresentationML XSDs, checks rId consistency, content-type registration.

Out of scope

• Reading: use the read tool.
• SmartArt creation (limited python-pptx support).
• Complex embedded charts beyond what python-pptx exposes.
• Slide transitions / animations (rarely matter for legal output).
• Vision-model layout review (deferred to v2).