Record why the raster payload omits the density overlay

[Alek99]

Follow-up to #284, addressing its review.

The finding

#284 made the raster exporters skip the density point-sample overlay, because
_raster._emit_grid never reads density["sample"]. But it dropped that
representation without recording anything, which contradicts a stated invariant:

Every decimation/tier decision is recorded in the spec, never silent (§28).

The neighbouring branch already honours this — it sets
density["overlay_omitted"] = "rows_exceed_u32" when row ids exceed u32. The new
raster case had no equivalent, so a raster payload dump showed an absent sample
with no explanation.

What changed

density["overlay_omitted"] = "static_raster" on the raster path, guarded with
if "overlay_omitted" not in density so it cannot mask the more fundamental
rows_exceed_u32 reason when a trace hits both.

Tests pin both halves: the field is present on the raster payload, and absent
from build_payload, so the raster-only flag can never leak to the client.

Also tightens the import guard added in #284:

• the module set is sampled after NumPy, so nothing NumPy pulls in is attributed to xy
• xml.sax.saxutils joins the forbidden set directly, rather than the guard relying
  on the urllib/ssl/email tree that import happens to drag in today — a future
  slimmer saxutils would otherwise let the removed import creep back without
  failing the test named for it

Verification

overlay_omitted is written only into the private raster spec, which no renderer
reads, so this is observably inert:

• all 72 artifact hashes unchanged — PNG at scale 1 and 2, SVG, HTML, wire blob
  and wire spec, across 12 figure configurations (density, direct, f32, clipped,
  continuous colour, NaN-injected, log axes, categorical at 2.2M, line, and one
  with & < > " ' plus non-BMP characters in the title)
• full suite 2283 passed, 4 skipped
• ruff check and ruff format --check clean

Spec updated in spec/api/export.md alongside the code.

Summary by CodeRabbit

• Bug Fixes

  • Static raster density payloads now consistently indicate when the point overlay is omitted.
  • Omission reasons are reported clearly, with oversized row IDs taking precedence when applicable.
  • Wire payloads continue to exclude overlay metadata when it is not shipped.

• Documentation

  • Updated static raster export documentation to describe overlay omission reporting and reason precedence.

• Tests

  • Added regression coverage for payload omission markers and SVG export behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

Raster density payloads now record why overlays are omitted, with tests and documentation covering raster versus wire behavior. The SVG import regression test now checks only modules newly imported by xy and includes xml.sax.saxutils among forbidden modules.

Changes

Density overlay omission contract

Layer / File(s)	Summary
Record raster overlay omission python/xy/_payload.py, tests/test_raster_density_overlay.py, spec/api/export.md	Raster payloads record overlay_omitted = "static_raster" when applicable, while wire payloads omit the marker; documentation describes precedence for rows_exceed_u32.

SVG import isolation guard

Layer / File(s)	Summary
Track newly imported forbidden modules tests/test_svg_escape.py	The subprocess test snapshots modules before importing xy, then checks newly added forbidden modules including xml.sax.saxutils.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• reflex-dev/xy#284: Modifies raster-density payload construction and overlay omission behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the main change: recording why raster payloads omit the density overlay.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch alek/raster-overlay-omission-reason

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

tests/test_raster_density_overlay.py (1)

44-50: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Add coverage for rows_exceed_u32 precedence.

The new test covers normal raster exports, but not the documented case where both conditions apply. Add a regression case confirming that overlay_omitted remains "rows_exceed_u32" rather than being overwritten with "static_raster".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/test_raster_density_overlay.py` around lines 44 - 50, Add a regression
test alongside test_raster_payload_omits_the_overlay that configures a raster
payload with both rows exceeding u32 and a static raster overlay, then assert
density["overlay_omitted"] is "rows_exceed_u32". Preserve the existing
normal-overlay omission assertion.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/test_raster_density_overlay.py`:
- Around line 44-50: Add a regression test alongside
test_raster_payload_omits_the_overlay that configures a raster payload with both
rows exceeding u32 and a static raster overlay, then assert
density["overlay_omitted"] is "rows_exceed_u32". Preserve the existing
normal-overlay omission assertion.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e68a7b9e-801f-444a-96d7-4689117394b8

📥 Commits

Reviewing files that changed from the base of the PR and between a7239b9 and 7520e37.

📒 Files selected for processing (4)

• python/xy/_payload.py
• spec/api/export.md
• tests/test_raster_density_overlay.py
• tests/test_svg_escape.py

[codspeed-hq]

Merging this PR will not alter performance

✅ 102 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing alek/raster-overlay-omission-reason (7520e37) with main (a7239b9)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩