feat(cli): export standalone HTML and strengthen layout checks

Merged
VI
23d ago
+1454-3699

Summary

Add standalone HTML reports for calculation development and repair the overflow preflight described in #61.

captured execution → prepared document → shared HTML
                                        ├─ standalone export, optional browser checks
                                        └─ mandatory browser checks → PDF

cso html source.cso.py --function calculate --out report.html works without Chromium. --check-layout adds screen and print inspection. Formula descendant bounds produce source-linked overflow diagnostics, and failed checks preserve existing output. Agent guidance now uses HTML during development and reserves page-by-page PDF inspection for relevant print work and delivery.

Closes #61.

Evidence

  • Before: MathML descendants could overflow while the outer math element passed the PDF preflight. No standalone HTML export was available.
  • After: Browser regressions reject overflowing fractions, conditionals and qualified symbols in HTML and PDF, preserve prior output, and report overflow coordinates. A separate regression proves that non-math title text fitting the viewport but exceeding the printable sheet is rejected by both HTML and PDF.
  • Merged #65 to concentrate the suite on core workflows. Its final CI passed 562 TypeScript tests and 107 Python tests (669 total), lint, typechecking, package isolation and installed-package consumers. Fresh checks on this PR’s merge commit 916bdb3 also passed all 669 tests, lint, typechecking, package isolation, installed-package consumers and CodeQL. Installed consumers exercise unavailable Chromium and a missing packaged stylesheet.
  • Package isolation, library archive consumers and demo build passed. Standalone HTML and both pages of a representative PDF were visually inspected.

The overflow regressions intentionally fail before PDF publication. They assert structured diagnostics and preservation of previous output, so no successful overflow PDF exists to inspect. The representative successful artifact inspection is a separate check.

Cubic review fixes

All 11 findings from the initial review are addressed in cff5bd8.

  • Non-math text and elements use printable-sheet bounds, with a browser regression for the viewport false negative.
  • Layout diagnostics validate derived overflow values against their coordinates.
  • Document success, output and write-failure checks share one policy helper.
  • The packaged stylesheet owns standalone preview rules and the shared print-width token.
  • HTML build errors remain document-preparation failures; rendering stays not applicable before browser work.
  • Installed consumer tests strip external module paths and assert unavailable-browser failure causes. A real missing-stylesheet test covers HTML build failure.
  • Both consumer layers use one canonical overflow fixture.
  • The review workflow links to execution-evidence, which permits document-level diagnostics when no source placement exists.
  • Asset documentation distinguishes capture checks from source-binding validation.

Validation before consolidation included the full suite, lint, typechecking, 12 focused browser tests and freshly installed archives/wheel outside the repository. The updated two-panel HTML preview was visually inspected.

The three follow-up maintainability findings are addressed in 5d0f049: both layout scans share diagnostic recording, fixture replacements require exactly one match, and browser/rejection test setup is shared. All 12 focused HTML/PDF tests, root and CLI typechecking, and lint passed after this refactor.

Concentrated test suite

#65 retains end-to-end calculation/report workflows, independent numeric references and failure recovery while removing repeated and lower-priority edge cases. Review follow-up preserves ordinary pi parameters, ambiguous metadata rejection without replacing bindings, and malformed Python-export calls. The title-overflow regression uses an explicit wider viewport so Ubuntu font metrics do not invalidate its viewport precondition; both sheet-overflow and no-viewport-overflow assertions remain.

This intentionally reduces distinct edge-case coverage; passing the smaller suite does not establish equivalent regression detection.

Merge Danger

Door: two-way

No migration or new dependency. Reverting restores the previous CLI behavior.

Blast Radius: rendering

HTML and PDF share document preparation, evidence publication and browser inspection. Stricter checks inspect text and element bounds against the printable sheet and can reject previously accepted overflowing PDFs; they do not reflow oversized formulas. Unchecked HTML explicitly reports rendering as not applicable and visual inspection as pending.