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: ad3994a4-aa0f-4cf7-a647-6b5a46ec2892

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 (4845359) with stack/5-chart-factories (5f15a49)}

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]

1 issue found across 5 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="tests/reflex_adapter/test_figure_probe.py">

<violation number="1" location="tests/reflex_adapter/test_figure_probe.py:74">
P2: These tests probe the whole rx.State tree rather than scoping to ProbeDemo. That ties their outcome to every other probe-enabled figure builder registered anywhere in the pytest session: any unrelated module's builder that isn't a no-op under default state (or that the process-wide walk reaches) would fail or downgrade these tests. Scope the probe to the test state, e.g. probe_figure_builders(ProbeDemo), so each test is self-contained and isolation is explicit.</violation>
</file>

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

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

[cubic-dev-ai]

P2: These tests probe the whole rx.State tree rather than scoping to ProbeDemo. That ties their outcome to every other probe-enabled figure builder registered anywhere in the pytest session: any unrelated module's builder that isn't a no-op under default state (or that the process-wide walk reaches) would fail or downgrade these tests. Scope the probe to the test state, e.g. probe_figure_builders(ProbeDemo), so each test is self-contained and isolation is explicit.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At tests/reflex_adapter/test_figure_probe.py, line 74:

<comment>These tests probe the whole rx.State tree rather than scoping to ProbeDemo. That ties their outcome to every other probe-enabled figure builder registered anywhere in the pytest session: any unrelated module's builder that isn't a no-op under default state (or that the process-wide walk reaches) would fail or downgrade these tests. Scope the probe to the test state, e.g. probe_figure_builders(ProbeDemo), so each test is self-contained and isolation is explicit.</comment>

<file context>
@@ -0,0 +1,113 @@
+
+
+def test_probe_runs_sync_builders_and_skips_optouts():
+    probed = probe_figure_builders()
+    names = {name.rsplit(".", 1)[-1] for name in probed if "probe_demo" in name}
+    assert "healthy" in names
</file context>

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