Initiative: Report rendering parity and PDF stylesheet strategy

[techmore]

Summary

Track the remaining work to bring browser HTML reports and exported PDF reports into a coherent, intentional, maintainable rendering system.

The codex/runtime-contract-fixes branch already cleaned up a large portion of the report pipeline wiring:

• explicit web vs PDF stylesheet routing
• shared saved-scan PDF generation flow
• cleaner reporting module boundaries
• regression coverage around report workflow contracts

What remains is no longer basic runtime wiring. It is the product/design/maintainability work around rendering quality, parity, and long-term stylesheet ownership.

Goals

• improve HTML and PDF visual parity
• decide the long-term stylesheet strategy for PDF generation
• reduce drift between interactive web output and printable/exported output
• validate representative reports for readability, spacing, and print quality

Scope

1. Rendering Quality Audit

• typography hierarchy
• spacing and section rhythm
• card/table readability
• vulnerability and asset-list presentation
• PDF page-break behavior and print-safe layout

2. Stylesheet Strategy

• decide whether PDF should use:
  • a dedicated print-first XSL
  • a thin print override layer on top of the web stylesheet
  • or a mostly unified stylesheet with minimal divergence

3. Parity Validation

• compare representative HTML/PDF outputs side by side
• reduce renderer-specific drift
• document known intentional differences if full parity is not desired

4. Regression Protection

• keep tests around stylesheet routing and report workflow boundaries
• add sample-based or fixture-based regression checks where feasible

Why This Should Be One Initiative

The existing issues around report formatting, PDF styling, and HTML/PDF parity overlap heavily. Treating them separately makes it harder to tell whether a change is solving rendering quality, stylesheet ownership, or runtime wiring. Those wiring concerns are now mostly resolved; the remaining work is best tracked as one rendering initiative.

Suggested Follow-Up Tasks

• capture 2-3 representative HTML/PDF samples for comparison
• choose PDF stylesheet direction
• fix highest-visibility formatting defects first
• add regression checks for the chosen rendering model

[techmore]

Tracked as priority 2 in #108. This initiative follows the scan-history indexing work and covers the remaining report-rendering/parity decisions.

[techmore]

Implemented the next report-rendering cleanup on .

What landed:

• removed DataTables/browser-only CSS and JS dependencies from \
• removed the inline interactive table/search/collapse script block from the PDF stylesheet
• added a runtime contract test that keeps the PDF stylesheet print-first while the web stylesheet remains interactive

Verification:

• ..................................... [100%]
  37 passed in 0.12s -> 37 passed
• ........................................................................ [ 53%]
  .............................................................. [100%]
  134 passed in 0.29s -> 134 passed

Commit: 86e404f \

[techmore]

Implemented the next report-rendering cleanup on codex/runtime-contract-fixes.

What landed:

• removed DataTables/browser-only CSS and JS dependencies from nmap-pdf-olive-legacy.xsl
• removed the inline interactive table/search/collapse script block from the PDF stylesheet
• added a runtime contract test that keeps the PDF stylesheet print-first while the web stylesheet remains interactive

Verification:

• ./.venv/bin/python -m pytest -q /Users/techmore/projects/NmapUI/tests/test_runtime_contract.py -> 37 passed
• ./.venv/bin/python -m pytest -q -> 134 passed

Commit: 86e404f Make PDF stylesheet print first

[techmore]

Added the next #106 increment on codex/runtime-contract-fixes.

What landed:

• switched Playwright PDF generation from screen media to print media in nmapui/reporting.py
• extended the runtime contract test so the browser renderer stays aligned with the print-first PDF stylesheet

Verification:

• ./.venv/bin/python -m pytest -q /Users/techmore/projects/NmapUI/tests/test_runtime_contract.py -> 37 passed
• ./.venv/bin/python -m pytest -q -> 134 passed

Commit: 3655176 Use print media for PDF rendering

[techmore]

Added another #106 fix on codex/runtime-contract-fixes.

This one corrects a live runtime bug in app.py:

• report generation was still wiring pdf_stylesheet to XSL_STYLESHEET instead of XSL_STYLESHEET_PDF
• both the main report-generation path and the saved-PDF path now pass the dedicated PDF stylesheet through to the shared workflow/reporting code
• runtime contract coverage now asserts that the app wires the web and PDF stylesheet slots distinctly

Verification:

• ./.venv/bin/python -m pytest -q /Users/techmore/projects/NmapUI/tests/test_runtime_contract.py -> 37 passed
• ./.venv/bin/python -m pytest -q -> 134 passed

Commit: bcf3261 Use PDF stylesheet for report jobs

[techmore]

Added a concrete #106 increment in 73f6928 (Add report stylesheet regression coverage).

What landed:

• added docs/guides/REPORT_STYLESHEET_STRATEGY.md to document the current design choice: shared visual language, interactive web stylesheet, and print-first PDF stylesheet
• added a representative render regression in tests/test_reporting_modules.py that runs both XSLs through xsltproc on sample scan XML and verifies shared landmarks/content plus intentional asset differences
• updated tests/test_runtime_contract.py to pin the strategy doc and stylesheet expectations

Verification:

• ./.venv/bin/python -m pytest -q /Users/techmore/projects/NmapUI/tests/test_reporting_modules.py -k representative_report_fixture
• ./.venv/bin/python -m pytest -q /Users/techmore/projects/NmapUI/tests/test_runtime_contract.py
• ./.venv/bin/python -m pytest -q
• result: 188 passed, 6 skipped

Keeping #106 open because this addresses regression protection and strategy definition, not the full rendering-quality audit/parity cleanup.