Data-bound chart components 6/8: compile probe for figure builders

[FarhanAliRaza]

Stacked on #465. Base is stack/5-chart-factories.

Why

With the data-bound tier validating structure at page evaluation, @reflex_xy.figure is the last place chart-building code defers to hydrate — where a typo'd mark name or a bad kwarg shows up as a blank mount and an err frame, in a browser, after a round trip.

Change

XYPlugin.post_compile walks the state tree and runs each figure builder once against a default state instance:

• probe="build" (sync default) — run the body;
• probe="figure" — also compile the result;
• probe=False — opt out, and the default for async def builders, because awaiting a data source at compile is exactly what the "no data ingestion at compile" constraint forbids. An async builder can still opt in explicitly.

Failures raise FigureProbeError naming the state class, var, and source location, wrapping the original exception.

One deliberate softening

A builder whose source reads self.router is session-dependent by declaration, and only a live session can validate it — so its probe failure degrades to a RuntimeWarning rather than failing the compile. The heuristic is source text, which is why it can only ever downgrade an error, never invent one.

Spec

reflex-integration.md §3.1 (compile probe).

Test plan

• uv run pytest tests/reflex_adapter tests/test_validation_timing.py — 240 passed
• pre-commit run --all-files, ruff check, ruff format --check, ty check — clean

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: cdd619c2-4973-46fa-921f-5eca0e821f6f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[greptile-apps]

Greptile Summary

Adds compile-time validation for @reflex_xy.figure builders so chart-construction errors can surface during backend startup rather than hydration.

• Adds configurable build, figure, and disabled probe levels, with asynchronous builders disabled by default.
• Walks figure variables during plugin compilation and reports failures with state, variable, and source-location context.
• Documents the compile-probe contract and adds focused adapter tests.

Confidence Score: 5/5

This follow-up appears safe to merge.

No blocking failure remains within the eligible follow-up scope.

Important Files Changed

Filename	Overview
python/reflex_xy/app.py	Implements state-tree traversal, builder execution, result validation, session-dependent warning behavior, and plugin integration for compile probes.
python/reflex_xy/vars.py	Adds the public probe option, validates its accepted values, and records the effective probe level on each figure getter.
python/reflex_xy/tokens.py	Defines the function attribute used to preserve probe configuration through Reflex computed-variable copies.
spec/design/reflex-integration.md	Specifies compile-probe levels, asynchronous behavior, strict option validation, and the session-dependent escape valve.
tests/reflex_adapter/test_figure_probe.py	Covers successful probes, opt-outs, asynchronous opt-in, builder and figure failures, session warnings, invalid returns, and strict level validation.

_{Reviews (3): Last reviewed commit: "fix(reflex): identity-strict probe level..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will not alter performance

✅ 109 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing stack/6-compile-probe (b3ebb05) with stack/5-chart-factories (c30f0e7)}

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

[cubic-dev-ai]

All reported issues were addressed across 5 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[FarhanAliRaza]

Review addressed in 4845359:

• probe= validation is identity-strict: 0/0.0 (== False) and 1/True are refused at decoration instead of silently opting the builder out.
• The default "build" level now also type-checks the builder's return: a non-chart value (e.g. a dict) fails reflex run with the builder's location instead of reaching hydrate. probe="figure" remains the full-compile level; async stays opt-in (recorded decision: never await user data sources at compile).

Spec §3.1 updated; pinned by test_figure_probe.py::test_non_chart_return_fails_the_default_probe_level and ::test_probe_levels_are_identity_strict.

[greptile-apps]

Greptile has paused reviews on this repository — it used its 100 free open-source review credits for this billing period. Reviews resume automatically on September 3. To continue before then, an organization admin can keep reviews running past the free credits — those bill as normal usage.