Ship animation identity planes only when the client can key-match

[Alek99]

The remaining item from the #319 review's perf-audit residual — but a different, more tractable half of it than the one I originally recorded.

What was wrong

match defaults to "index". So key= combined with a bare xy.animation(...), with enabled=False, or with no animation spec at all was putting two u32 identity columns into the payload that no client code reads.

chart spec	keys shipped before	ever read
animation(match="key")	yes	yes
animation(match="index")	yes	no
animation(duration=250) — match defaulted	yes	no
animation(enabled=False)	yes	no
no animation(...) at all	yes	no

At 50k rows the payload was half dead key columns: 800,000 → 400,000 bytes, plus 400 KB retained for the widget lifetime.

What this does not change

Encoding still runs in every case. Duplicate-key and row-count errors are construction contract, not animation policy, and _encode_transition_keys materializes as part of validating — so the saving is retention and transport, not CPU. Tests assert both error classes still fire in all three now-skipped shapes.

Payloads that key-match are byte-identical. Verified by hashing spec and blob across the merge base and this branch:

match=key     spec 0d46cee54989e43a   blob 2e3a2ed38bad6748    <- both branches
match=index   blob 800000 -> 400000 bytes, retained 400000 -> 0

It surfaced a worse bug — filed as #329

Animation.to_spec() emits every field, and both the Python merge and the client's {...spec.animation, ...trace.animation} are plain dict spreads. So a mark-level xy.animation(duration=90) resets match, easing, enter, update, and interpolate to defaults:

xy.scatter_chart(
    xy.scatter(x=x, y=y, key=keys, animation=xy.animation(duration=90)),
    xy.animation(match="key", easing="linear"),
)
# resolved: match="index", easing="ease-out"

That silently turns off chart-level match="key", and suppresses the match='key' requires key= guard entirely. It was invisible before this change because keys shipped whether or not the resolved spec could use them.

test_aggregate_tier_records_key_matching_fallback was written in exactly that shape and passed for that reason; it now restates match="key" to express its intent, with a pointer to #329. test_mark_animation_spec_clobbers_chart_level_fields pins the buggy behavior so a fix is deliberate rather than silent.

The two compose safely. key_matching reads the same effective dict #329 would correct, so fixing the merge automatically restores plane shipping wherever key matching starts working again.

Verification

• pytest tests/ — 2574 passed, 4 skipped
• ruff@0.15.8 check / format --check clean
• Payload spec+blob hash comparison across five animation configurations, before and after
• Browser smoke assertions on animation_fallback all operate on match="key" payloads, so they are untouched

Not done, deliberately

The other half of the perf-audit residual — keys encoded for rows discarded above MAX_ANIMATION_MATCH_ROWS — stays open. Finite-row filtering means n_points > 200k does not guarantee the shipped count exceeds the limit, so it genuinely cannot be decided at attach time. Parallelizing the kernel would optimize exactly that discarded work, so it should wait on this being resolved.

Summary by CodeRabbit

• Bug Fixes

  • Removed unused animation identity data from payloads when key-based matching is unavailable.
  • Preserved key validation and existing payload output for animations that support key matching.
  • Prevented unnecessary sorting and row reordering when identity keys are not used.

• Documentation

  • Clarified when animation identity data is retained and transmitted.
  • Documented default matching behavior and key-based animation scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7d23dd1a-dbcc-44b9-9553-b16545e94f5c

📥 Commits

Reviewing files that changed from the base of the PR and between 7c377ce and 25c3005.

📒 Files selected for processing (4)

• CHANGELOG.md
• python/xy/components.py
• spec/design/animation.md
• tests/test_animation.py

---

📝 Walkthrough

Walkthrough

Key identity planes are now retained and transmitted only when the resolved animation performs key matching. Key validation remains active, while line-like key sorting is skipped for non-key-matching animations. Tests and documentation cover the updated behavior.

Changes

Animation key-plane retention

Layer / File(s)	Summary
Effective key-matching transition metadata python/xy/components.py	Transition-key sorting and trace attachment now depend on effective enabled and match settings, while encoded key length validation remains active.
Key-plane behavior validation and documentation tests/test_animation.py, spec/design/animation.md, CHANGELOG.md	Tests cover conditional transmission, validation preservation, matching payload consistency, and aggregation fallback; documentation records the updated stable-identity contract.

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

Possibly related issues

• Mark-level xy.animation(...) silently resets every chart-level animation field, including match="key" #329 — Related animation key-matching resolution around mark-level animation specifications.
• Animation identity keys ship 8 B/row even when animation is disabled #172 — Directly concerns preventing dead key-plane transmission when effective matching is unavailable.

Possibly related PRs

• reflex-dev/xy#321 — Touches the transition-key encoding pipeline in python/xy/components.py.

Suggested reviewers: carlosabadia

🚥 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 clearly and accurately summarizes the main change: only shipping animation identity planes when key matching is possible.
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/skip-unmatched-key-planes

---

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

[codspeed-hq]

Merging this PR will not alter performance

✅ 103 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing alek/skip-unmatched-key-planes (25c3005) with main (7c377ce)}

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. ↩