pptx-render-review

name	pptx-render-review
description	Use when reviewing PPTX renderer visual fidelity, triaging failed or needs-review oracle cases, inspecting PDF/PNG versus HTML screenshots, checking renderer bugfix side effects, planning regression coverage, or saving manual support verdicts in this repository.

PPTX Render Review

Overview

Use renderer screenshots, diff images, and oracle metrics to make fast visual fidelity judgments. Start from side-by-side review, then use diff-first as a diagnostic lens; stay read-only unless the user asks for a fix.

Required Context

From the repository root:

pwd
git status --short
find test/e2e/reports/oracle-failures -maxdepth 1 -type f -name '*.json' -print0 | xargs -0 ls -lt | head

For current quality, compare generated_at values and prefer the newest report matching the requested corpus.

Review Sources

Source order:

Need	Source
Interactive visual review	http://127.0.0.1:5173/test/pages/e2e-compare.html
Single native slide	/test/pages/render-slide.html?file=testdata/cases/{case}/source.pptx&slide=N
Metrics	test/e2e/reports/oracle-failures/*live*.json or requested report
Diff and screenshots	test/e2e/reports/{case}_slide{N}_{pdf,html,diff}.png
Manual verdict store	test/e2e/reports/oracle-failures/manual-review.json
Support catalog	test/e2e/reports/oracle-failures/support-catalog.json

Workflow

1. Confirm report freshness:

jq '{generated_at,total_cases,
  passed:(.results|map(select(.passed==true))|length),
  failed:(.results|map(select(.passed==false))|length),
  needs_review:(.results|map(select(.needs_review==true))|length)}' test/e2e/reports/oracle-failures/<report>.json

If it is not the newest matching corpus, call it stale.

2. Confirm dev servers only when browser/API review is needed:

pnpm dev:e2e

If servers already run, reuse them.

3. Pick a review set for the changed rendering area:

Area	Prefer samples
Shape geometry	target shape id, related presets, adjustment variants
Fill/stroke	gradient, scheme color, alpha, connector, multi-path
Chart	axis, legend, marker, combo, stock, doughnut, data labels
Text/table	pypptx text, table alignment, composite cases
SmartArt	layout family, generated PNG ground truth, edge-heavy

4. For renderer fixes, build a small interaction matrix before changing code or declaring the fix complete. Include the user-visible positive case, the inverse/opt-out case, and the parent container or browser behavior that could expose a side effect. For text layout changes, inspect a:bodyPr and cover relevant combinations of wrap, horzOverflow, vertOverflow, spAutoFit, normAutofit, noAutofit, insets, vertical text, bullets, multi-paragraph text, and adjacent runs. A leaf TextRenderer test is insufficient when the visible behavior depends on the ShapeRenderer text container.

5. Prioritize:

Priority	Meaning
P0	large diff in changed rendering area
P1	passed=false or semantic mismatch
P2	passed=true, needs_review=true
P3	representative supported sample for baseline

6. Inspect selected cases in side-by-side view first. Use diff-first to locate suspicious regions, then confirm in ground-truth/rendered side-by-side before making a verdict. Prefer PNG ground truth; use PDF only when PNG is unavailable or requested.

Default to decision metrics first: auto gate (PASS, REVIEW, FAIL), SSIM, color correlation, and needs_review. Open Diagnostics only when locating a mismatch or explaining why a case needs review; diagnostic metrics include foreground IoU, chamfer, MAE, text coverage, word counts, and shape count.

7. Save verdicts only after per-slide visual inspection:

curl -sS -X POST http://127.0.0.1:8080/api/manual-review \
  -H 'Content-Type: application/json' \
  -d '{"test_file":"CASE","slide_idx":0,"verdict":"supported","note":"short reason"}'

Use supported, unsupported, or unsure. Notes name visible mismatch, not guessed code cause.

Red Flags

• Bulk-marking from metrics alone.
• Treating diagnostic metrics as top-level verdict gates.
• needs_review=true without expanding from diff into side-by-side inspection.
• Old generated_at or wrong corpus/source.
• Notes guess code cause instead of visible mismatch.
• Text/layout fixes tested only at the run/span layer without the shape text container.
• Missing inverse coverage for explicit opt-outs such as horzOverflow="overflow".

Reporting Back

Report the report path, generated_at, selected review set, auto gate summary, diff observations, saved verdicts, and stale/missing data. Keep diagnostic metrics secondary unless they explain a visible issue.

Common Mistakes

• Do not use windows-all-eval.json or all-shapes-eval.json blindly.
• Do not mark a case supported from metrics alone when needs_review=true.
• Do not bulk-save manual verdicts; save only case/slide verdicts you inspected.
• Do not chase fg_iou as a pass/fail gate; it is diagnostic only.
• Do not modify renderer code during review unless the user asks for a fix.