ENG-10441: Complete Reflex events and cross-filtering

[FarhanAliRaza]

Closes the P0 interaction loop for reflex_xy: browser interaction → semantic event → Reflex handler → State update → dependent @reflex_xy.figure recompute → republish behind stable tokens, with no remount and no feedback loops.

What changed

Event envelopes (v1). on_point_hover, on_point_click, on_select_end, and on_view_change now deliver versioned, JSON-bounded envelopes carrying the stable figure token, trace identity, the canonical row id (never a shipped/decimated buffer index), data/datum, and — for clicks — canvas-relative screen coords and keyboard modifiers.

Bounded selections + complete data (ENG-10461). Selection replies opt into include_rows (sent only when on_select_end is wired) and carry kind/mode/bounds/polygon/canonical_row_ids/rows/truncated, capped at SELECTION_EVENT_ROW_LIMIT = 1000 rows / SELECTION_EVENT_ID_LIMIT = 10000 ids with total_count always exact. New Selection.rows() gives a deterministic, JSON-safe canonical projection (pick-result shape); new reflex_xy.resolve_selection(event) re-resolves the geometry server-side against canonical f64 columns for the complete, unbounded selection — large selections never ride the browser as JSON.

Event enablement, throttling, loop hygiene. The JSX wrapper injects click/view_change interaction flags only when those handler props are wired (zero overhead otherwise), throttles hover dispatch (120 ms latest-wins), debounces view changes (200 ms trailing) and suppresses non-user sources. On a stable-token republish the wrapper preserves the user's viewport and re-issues the active selection without redispatching handlers, so cross-filter refreshes can't loop or reset zoom.

Stale-event rejection. Clients echo the last payload version (v) on every kernel message; XYNamespace.on_msg drops messages minted against a replaced figure version (same pattern as drill_seq staleness). Clients that omit v remain compatible.

Input parity. Keyboard Enter/Space on a focused datum emits the same click contract (screen + modifiers) as pointer activation; render-client bundles regenerated via node js/build.mjs.

Docs & demo. docs/engineering/design/reflex-integration.md §5.1 documents the envelopes, limits, truncation fallback, static-src caveats, and shared-handler/viewport-sync patterns; the demo app cross-filters by selection rows and demonstrates resolve_selection.

Verification

• uv run pytest — 1949 passed, 65 skipped (includes new unit + socket-E2E coverage: enriched selection round-trip, stale-version drop, resolve_selection, keyboard-activation contract, payload-bound tests)
• uv run ruff check . / ruff format --check . / uv run ty check — clean
• node js/build.mjs — bundles fresh
• uv run --with pre-commit pre-commit run --all-files — all hooks pass

Not covered: the browser smoke (scripts/reflex_ws_smoke.py) needs a running demo app + headless Chromium; worth a manual pass before release.

[linear-code]

ENG-10441

[codspeed-hq]

Merging this PR will not alter performance

✅ 97 untouched benchmarks
⏩ 1 skipped benchmark¹

---

_{Comparing farhan/eng-10441-complete-reflex-events-and-cross-filtering-in-xy (6317ef5) with main (09b5873)}

Footnotes

1. 1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩

[masenf]

it would be nice to have TypedDict declarations for the event payloads handled on the reflex side

[greptile-apps]

Greptile Summary

This PR completes semantic chart events and cross-filtering for reflex_xy. The main changes are:

• Versioned, bounded envelopes for hover, click, selection, and view events.
• Canonical selection rows with server-side resolution for truncated results.
• Stable-token republishing that preserves viewport and selection state.
• Request identities and payload versions for stale-reply rejection.
• Keyboard click parity, updated clients, tests, docs, and demo behavior.

Confidence Score: 5/5

This looks safe to merge.

Selection restore replies use request-specific identities, and version checks prevent messages for replaced figures from reaching kernel handling.

No blocking issue remains in the reviewed interaction paths.

T-Rex Logs

What T-Rex did

• T-Rex produced proof for the posted P1 finding in review comment 0.
• T-Rex produced proof for the posted P1 finding in review comment 1.
• T-Rex performed general-contract-validation-proof analysis, capturing the baseline showcase, smoke setup, viewport issue, drill, and separate Playwright run observations.
• T-Rex linked and inspected 11 artifacts from the Playwright run to assess drill effects and hover behavior.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
python/reflex-xy/reflex_xy/assets/XYChart.jsx	Adds semantic event envelopes, throttling, republish restoration, and request-specific click and selection reply tracking.
python/reflex-xy/reflex_xy/namespace.py	Rejects versioned client messages when their figure payload has been replaced.
python/xy/channel.py	Returns bounded selection details and preserves selection request identities in replies.
python/reflex-xy/reflex_xy/selections.py	Adds server-side resolution of complete selections from event geometry.
js/src/53_interaction.js	Adds keyboard activation details and retains selection geometry across drill changes.

Comments Outside Diff (2)

1. General comment

   Browser smoke sends drill input outside Chromium's viewport

   • Bug
     • The documented scripts/reflex_ws_smoke.py flow consistently times out at density drill even though the rendered chart and socket transport are healthy. Headless Chromium reports a 780×437 viewport, while the cloud center used for wheel input is y=517. CDP input at that off-screen coordinate does not reach the chart. Scrolling the cloud into view immediately allows the same 16-wheel sequence to drill.
   • Cause
     • The smoke deliberately removed device-metrics emulation but computes viewport-relative getBoundingClientRect() coordinates without ensuring #cloud is visible before dispatching input.
   • Fix
     • Call probe.scroll_to("cloud") before obtaining its rect and dispatching drill/hover input, or otherwise clamp/scroll the target into the active viewport. Retain the no-emulation workaround if pointer movement requires it.

   _{Ran code and verified through T-Rex}

2. General comment

   Hovering a rendered drilled point does not close the Reflex state loop

   • Bug
     • After scrolling the real cloud into view, the density tier drills successfully, but the smoke’s hover traversal never produces the expected x=… state readout. A separate Playwright execution scanned the rendered pick framebuffer, found a valid drilled point (pickable=true, 195 points), moved to that exact rendered coordinate, and still observed no Reflex readout. This contradicts the claimed hover → kernel pick → Reflex event → state delta path.
   • Cause
     • The failure is downstream of rendering and drill: valid drilled pick pixels exist, but pointer hover does not result in the expected Reflex DOM state update. The precise break between browser hover dispatch, socket pick response, wrapper event conversion, and state handler requires further tracing.
   • Fix
     • Trace the hover/pick frames and browser event callbacks for a known pick-buffer coordinate. Verify XYChart.jsx emits the v1 hover envelope, the namespace resolves the drilled subset using drill_seq, and Demo.on_hover receives and publishes the state delta. Add the exact rendered-point traversal as a deterministic smoke assertion.

   _{Ran code and verified through T-Rex}

_{Reviews (4): Last reviewed commit: "test(smoke): isolate stale-mask gate fro..." | Re-trigger Greptile}