Preserve diagram geometry and PDF-native form appearance

[sayantandey]

Summary

• Preserve unfilled, unconnected constellations of labeled outline panels as one deterministic SVG instead of flattening their labels into prose.
• Keep the detector conservative with independent form-column, table-lattice, image-overlap, text-containment, size, row, and axis vetoes.
• Carry native diagram labels into alternative text and retain page, glyph, region, and PDF-object provenance.
• Resolve page-only outline destinations to unique page headings without inventing #None anchors.
• Recover AcroForm appearance evidence from /DA, /MK, /AP, /Q, and /Rect, with the normal appearance stream authoritative over declarations.
• Render only evidenced widget size, text color, background, border, and alignment in safe documentary HTML; never emit active controls or map opaque PDF font resource names to invented browser fonts.
• Recompute uniform appearance after page-range widget filtering so styles cannot leak between pages.
• Regenerate the committed first-party corpus and strengthen both semantic and visual assertions.
• Give same-repository PRs an immutable head-commit HTML preview; stable repository links are explicitly labeled main, and untrusted fork HTML is not one-click rendered.

Why the earlier tests passed

The old scope gate proved only that the five outlined panels were not hallucinated as form controls. It did not positively require their strokes, spatial grouping, labels, asset reference, accessibility text, or provenance to survive. The full conversion had only a generic non-empty/schema-valid contract, so dropping the rectangles and flattening their labels still passed.

The blue-gray Beta field had a different issue: the earlier micro-PDF encoded a widget rectangle and value but no deterministic appearance. Chrome synthesized viewer UI that CocoaPDF correctly could not treat as PDF content. The fixture now contains an explicit standards-based normal appearance plus matching appearance declarations, and CocoaPDF preserves that evidence. Appearance-less widgets remain deliberately plain.

The new checks are two-sided but not pixel-locked: they require one native vector figure with all five labels and strokes, no flattened false prose, correct references and provenance, a valid finance table, valid outline anchors, one evidenced SecondField presentation, no style on the appearance-less field, and no OCR or active form controls.

Visual review

• Rendered full output at this exact commit
• Rendered page-2 output at this exact commit
• Source PDF at this exact commit

The generated HTML was rendered locally in a real browser. Beta is visibly large, dark blue-gray, and placed on the encoded pale blue-gray field background; FirstField remains plain.

Fixture architecture

The corpus remains one review experience but three diagnostic PDFs. StructTreeRoot/ParentTree, AcroForm, and Outlines are document-catalog object graphs, not page-local decorations. Concatenating ordinary pages would either discard those semantics or create a misleading partially tagged hybrid and couple unrelated failures. The rationale is now visible in the README, review page, and machine-readable manifest.

A repository README also cannot dynamically infer the GitHub ref from which an external URL was clicked. Therefore stable public preview links are explicitly labeled main, while CI injects an immutable SHA-pinned preview into each same-repository PR. Fork PRs retain the generated artifact but intentionally do not receive a direct rendering of contributor-controlled HTML.

Verification

• python -m unittest discover -s tests -v — 250 passed
• python scripts/refresh_examples.py --check — 37 committed files across 3 first-party cases verified
• python scripts/check_repository_invariants.py — passed
• python -m compileall -q src tests tools scripts validation — passed
• PR visual validation — passed for head 6151fe1ef224f90b65c349242bd76ec27385375a
• Browser rendering — inspected
• git diff --check — clean

PR visual-validation artifact

The temporary review artifact was deleted automatically after this PR was merged; no stale download link is retained.

• Reviewed head commit: 6151fe1ef224f90b65c349242bd76ec27385375a
• Review workflow close/cleanup run
• Browse the permanent capability demo

Reopening the PR generates a fresh artifact and restores a live download link.