shiny-plotly 0.2.0__tar.gz → 0.3.0__tar.gz

{shiny_plotly-0.2.0 → shiny_plotly-0.3.0}/.gitignore

@@ -1,5 +1,6 @@
 .venv/
 .wheel-venv/
+.floor-venv/
 dist/
 __pycache__/
 *.pyc

{shiny_plotly-0.2.0 → shiny_plotly-0.3.0}/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0](https://github.com/rvben/shiny-plotly/compare/v0.2.0...v0.3.0) - 2026-08-20
+
+### Added
+
+- `@render_plotly(events=...)` forwards plotly events to Shiny inputs: any of `click`, `hover`, `selected` and `relayout` arrive as `input.<id>_<event>` (namespaced inside a module), carrying plotly's event data cut to what serializes (`points` with each point's scalar fields plus `customdata`, `bbox`, `pointNumbers`; `range` or `lassoPoints` for selections; relayout data as is). A click fires on every click; hover is debounced and becomes `None` when the pointer leaves; a deselect sets `selected` to `None`. Handlers attach once per graph div and survive re-renders. `max_event_points` (default 10 000) caps the points one event carries: above it the value arrives with `"points": None` and `point_count` set, its `range` or `lassoPoints` intact, because a point is about 100 bytes of JSON and a box over a dense trace would otherwise build a message of many megabytes, or one above uvicorn's default 16 MB websocket limit, which closes the session (`make bench-events` measures it; 200 000 selected points are 20.9 MB).
+- `extend_traces(id, data, indices=None, *, max_points=None)`, `restyle(id, update, indices=None)` and `relayout(id, update)`: in-place updates to the figure an output holds, sent as Shiny custom messages and applied in the browser with `Plotly.extendTraces`, `Plotly.restyle` and `Plotly.relayout`. Values go through plotly's encoder; the id is namespaced inside a module; an update sent while the output has no figure drawn is held and applied after its next draw; a re-render replaces the figure, updates included.
+- `enable_compressed_plotly_js(app)` is public: a Core app can serve plotly.js compressed and immutable from its very first request instead of from its first session on.
+
+### Fixed
+
+- `output_plotly()` now carries the htmltools fill CSS itself. On a page that did not load it otherwise (`ui.page_fluid` without a card), a fixed-height output (`output_plotly(id, height="200px")`) with a bare `@render_plotly` drew a 400px graph that overflowed the output and whatever sat below it.
+- `output_plotly(id)` (and the Express auto output) did not namespace its id inside a Shiny module, so a `@render_plotly` in a module never found its output.
+- The declared dependency floor was wrong: `plotly>=5.0` and `htmltools>=0.5` could not work (`fig_to_ui` needs `to_html(div_id=...)`, which plotly 5.5 introduced; shiny 1.0 itself needs htmltools 0.5.2). The bounds are now `plotly>=5.5`, `htmltools>=0.5.2`, and CI installs exactly that floor (with shiny 1.0) and runs the whole suite against it, browser tests included (`make check-floor`).
+
 ## [0.2.0](https://github.com/rvben/shiny-plotly/compare/v0.1.0...v0.2.0) - 2026-08-19
 
 ### Changed

{shiny_plotly-0.2.0 → shiny_plotly-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shiny-plotly
-Version: 0.2.0
+Version: 0.3.0
 Summary: Render plotly figures in Shiny for Python with plain plotly.js, without the shinywidgets layer.
 Project-URL: Homepage, https://github.com/rvben/shiny-plotly
 Project-URL: Repository, https://github.com/rvben/shiny-plotly
@@ -21,8 +21,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: htmltools>=0.5
-Requires-Dist: plotly>=5.0
+Requires-Dist: htmltools>=0.5.2
+Requires-Dist: plotly>=5.5
 Requires-Dist: shiny>=1.0
 Provides-Extra: brotli
 Requires-Dist: brotli>=1.1; extra == 'brotli'
@@ -73,7 +73,7 @@ Measured on the same app (a slider and one fillable card with a line chart; `ben
 | Websocket bytes per re-render | 5.4 MB | 10 kB |
 | Re-render round trip, median of 50 | 1.1 to 1.4 s | 11 to 14 ms |
 
-Both need plotly.js in the browser. shiny-plotly serves `plotly.min.js` compressed (4.9 MB raw) with `Cache-Control: immutable`, so a browser fetches it once per plotly version; shinywidgets sends plotly's widget bundle as part of the `FigureWidget` state over the websocket, and a re-render creates a new `FigureWidget`, so that cost is paid on every visit and every re-render. The round-trip numbers come from a loaded laptop and are a range across runs, not a constant. shinywidgets does things this package does not (in-place `FigureWidget` updates, any ipywidget), which the table does not measure. `make bench` reproduces it; `bench/results.json` holds the raw numbers.
+Both need plotly.js in the browser. shiny-plotly serves `plotly.min.js` compressed (4.9 MB raw) with `Cache-Control: immutable`, so a browser fetches it once per plotly version; shinywidgets sends plotly's widget bundle as part of the `FigureWidget` state over the websocket, and a re-render creates a new `FigureWidget`, so that cost is paid on every visit and every re-render. The round-trip numbers come from a loaded laptop and are a range across runs, not a constant. shinywidgets does things this package does not (arbitrary in-place `FigureWidget` mutation, any ipywidget), which the table does not measure; the common in-place updates, appending points and changing trace or layout attributes, are covered by `extend_traces`, `restyle` and `relayout` below. `make bench` reproduces it; `bench/results.json` holds the raw numbers.
 
 ## Install
 
@@ -156,7 +156,9 @@ The decorator creates its own output placeholder in Express, just like `@render_
     width="100%",
     figurewidget_margins=True,  # the l16/t32/r16/b16 margins shinywidgets applies
     config={"displaylogo": False},
-    post_script=CLICK_TO_INPUT,  # JavaScript run once, when the graph is first drawn
+    events=("click", "selected"),  # arrive as input.sales_click, input.sales_selected
+    max_event_points=10_000,  # above it an event carries the count and range, not the points
+    post_script=MORE_JS,  # JavaScript run once, when the graph is first drawn
 )
 def sales(): ...
 ```
@@ -165,7 +167,7 @@ def sales(): ...
 
 ### Re-renders, zoom and pan
 
-Each `output_plotly` holds one plotly graph div. The first figure is drawn with `Plotly.newPlot`; every later one goes through `Plotly.react`, which diffs the new figure into the graph that is already there. So the DOM node, the handlers `post_script` attached and plotly's per-graph state all survive a re-render.
+Each `output_plotly` holds one plotly graph div. The first figure is drawn with `Plotly.newPlot`; every later one goes through `Plotly.react`, which diffs the new figure into the graph that is already there. So the DOM node, the event handlers (from `events=` or `post_script`) and plotly's per-graph state all survive a re-render.
 
 Whether the user's zoom and pan survive is plotly's `uirevision` rule, the same one shinywidgets users rely on for in-place updates: set `layout.uirevision` to any value and keep it the same across renders to preserve the view, change it to reset the view, leave it unset to reset on every render.
 
@@ -200,32 +202,137 @@ The rules mirror `output_widget`:
 
 Plotly alone re-measures a graph only on window resize. `shiny-plotly` ships a small helper script (`shiny-plotly.js`, loaded with every output) that observes each graph's container with a `ResizeObserver`, so a card that changes size without a window resize, for example when a sibling output renders below it, or when a sidebar collapses, re-lays the graph out. The same helper purges a graph once it leaves the document, which releases the window listener and layout state plotly would otherwise keep.
 
-### Events back to Shiny
+### Dark mode
 
-`post_script` runs once, after the first figure is drawn; `{plot_id}` is replaced with the graph div's id. Re-renders go through `Plotly.react` into the same graph div, so the handlers stay attached and are never stacked.
+Plotly does not follow Bootstrap's color mode by itself. Give the dark mode switch an id, read it in the render function to pick the template, and make the figure's backgrounds transparent so the card's own background shows through in both modes:
 
 ```python
-CLICK_TO_INPUT = """
-document.getElementById('{plot_id}').on('plotly_click', function (ev) {
-    var p = ev.points[0];
-    Shiny.setInputValue('clicked', {x: p.x, y: p.y}, {priority: 'event'});
-});
-"""
+app_ui = ui.page_fillable(
+    ui.input_dark_mode(id="mode"),
+    ui.card(output_plotly("sales")),
+)
 
 
-@render_plotly(post_script=CLICK_TO_INPUT)
+@render_plotly
+def sales():
+    template = "plotly_dark" if input.mode() == "dark" else "plotly"
+    fig = px.bar(df, x="month", y="total", template=template)
+    return fig.update_layout(paper_bgcolor="rgba(0,0,0,0)", plot_bgcolor="rgba(0,0,0,0)")
+```
+
+Flipping the switch re-renders the figure through `Plotly.react`, the same as any other re-render. `input.mode()` is `"light"` or `"dark"` and follows the user's system preference when the switch is not given an initial `mode`.
+
+### Events back to Shiny
+
+`events=` names the plotly events to forward; each arrives as `input.<id>_<event>`, namespaced like the output inside a module. Four are available: `click`, `hover`, `selected` and `relayout`.
+
+```python
+@render_plotly(events=("click", "selected"))
 def scatter(): ...
 
 
 @render.text
 def click_info():
-    if not input.clicked.is_set():
+    if not input.scatter_click.is_set():
         return "Click a point."
-    pt = input.clicked()
-    return f"x={pt['x']}, y={pt['y']}"
+    pt = input.scatter_click()["points"][0]
+    return f"trace {pt['curveNumber']}, point {pt['pointNumber']}: x={pt['x']}, y={pt['y']}"
+```
+
+What arrives is plotly's own event data, cut to what serializes, the same way Dash cuts it:
+
+| event | value of `input.<id>_<event>()` |
+| --- | --- |
+| `click` | `{"points": [...]}`; fires on every click, a repeated one too |
+| `hover` | `{"points": [...]}` while over a point, `None` once the pointer leaves; debounced (100 ms) |
+| `selected` | `{"points": [...], "range": {"x": [..], "y": [..]}}` for a box, `lassoPoints` for a lasso; `None` after a double-click deselect; above `max_event_points` the points give way to `point_count` (below) |
+| `relayout` | plotly's relayout data as is: `{"xaxis.range[0]": ..., "xaxis.range[1]": ...}` after a zoom or pan, `{"xaxis.autorange": True, ...}` after a reset, `{"dragmode": "pan"}` from the mode bar, `{"autosize": True}` after a resize |
+
+Each point carries plotly's scalar fields for that trace type (`curveNumber`, `pointNumber`, `pointIndex`, `x`, `y`, `z`, `text`, `label`, `value`, `lat`, `lon`, ...) plus `customdata` (as a plain list, also when it was a numpy array), `bbox` and `pointNumbers` when present. `input.<id>_<event>()` raises a silent exception until the event has fired once, so check `is_set()` when the output should show something before that.
+
+#### Dense traces
+
+A point is about 100 bytes of JSON, so a box over a dense trace builds a large message, and a large enough one ends the session: uvicorn closes a websocket on a message above 16 MB by default. `max_event_points` (default 10 000) is the most points one event carries. Above it the points stay in the browser and the value says so, with the selection's geometry intact:
+
+```python
+@render_plotly(events="selected")
+def scatter(): ...
+
+
+@render.text
+def picked():
+    sel = input.scatter_selected()
+    if sel is None:
+        return "Nothing selected."
+    if sel["points"] is not None:
+        return f"{len(sel['points'])} points"
+    # More than max_event_points: {"points": None, "point_count": 120000, "range": {...}}.
+    # The data is here, so membership is a filter on the box the user dragged.
+    (x0, x1), (y0, y1) = sel["range"]["x"], sel["range"]["y"]
+    inside = df[df.x.between(x0, x1) & df.y.between(y0, y1)]
+    return f"{sel['point_count']} points, {len(inside)} rows"
 ```
 
-`input.clicked()` raises a silent exception while the input has never been set, so check `is_set()` first when the output should show something before the first click.
+The value is never silently cut: `points` is a full list or `None`, and `point_count` is there when it is `None`. A lasso carries `lassoPoints` (the polygon's `x` and `y` lists) instead of `range`. `max_event_points=None` lifts the cap. Measured with `make bench-events` (one `Scattergl` trace, every point box-selected with a real mouse, headless Chromium and the server on the same laptop, 2026-08-19):
+
+| points | `max_event_points` | event JSON | mouse up to server |
+| --- | --- | --- | --- |
+| 1 000 | 10 000 | 99 kB | 83 ms |
+| 10 000 | 10 000 | 1.01 MB | 149 ms |
+| 100 000 | 10 000 | 136 B | 24 ms |
+| 100 000 | none | 10.33 MB | 1017 ms |
+| 200 000 | 10 000 | 135 B | 108 ms |
+| 200 000 | none | 20.89 MB | disconnected |
+
+`click` and `hover` carry one point per trace under the pointer, so the cap matters for `selected`; hover is also debounced (100 ms), so a pointer sweeping across a dense trace sends one event when it rests, not one per point.
+
+For anything else, `post_script` runs once, after the first figure is drawn, with `{plot_id}` replaced by the graph div's id. Re-renders go through `Plotly.react` into the same graph div, so handlers attached either way stay attached and are never stacked.
+
+```python
+LEGEND_TO_INPUT = """
+document.getElementById('{plot_id}').on('plotly_legendclick', function (ev) {
+    Shiny.setInputValue('legend', ev.curveNumber, {priority: 'event'});
+    return true;  // let plotly toggle the trace as usual
+});
+"""
+
+
+@render_plotly(post_script=LEGEND_TO_INPUT)
+def scatter(): ...
+```
+
+### Live updates without a re-render
+
+A re-render sends the whole figure. For a stream of points, a colour change or a new title, send just the change: `extend_traces`, `restyle` and `relayout` call the plotly.js functions of the same names on the graph an output holds. All three are coroutines, so the effect that calls them is `async def`.
+
+```python
+from shiny_plotly import extend_traces, relayout, restyle
+
+
+@render_plotly
+def prices():
+    return go.Figure(go.Scatter(x=[], y=[], mode="lines"))  # the seed; the stream fills it
+
+
+@reactive.effect
+async def _stream():
+    reactive.invalidate_later(1)
+    t, v = latest_sample()
+    await extend_traces("prices", {"x": [[t]], "y": [[v]]}, max_points=500)
+
+
+@reactive.effect
+@reactive.event(input.highlight)
+async def _highlight():
+    await restyle("prices", {"line.color": "crimson"}, indices=0)
+    await relayout("prices", {"title.text": "highlighted"})
+```
+
+- `extend_traces(id, data, indices=None, *, max_points=None)`: `data` maps an array attribute to one sequence of new values per trace, in the order of `indices` (`{"x": [[t]], "y": [[v]]}` appends one point to one trace; `{"y": [[1], [2]]}` with `indices=[0, 1]` one point to each of two). `indices` (an int or a list) defaults to every trace; `max_points` drops the oldest points past that many, for a rolling window.
+- `restyle(id, update, indices=None)`: `update` maps attribute paths to values; `{"marker.color": "red"}` applies to every trace in `indices`, a list value applies per trace (`{"opacity": [0.5, 1]}` with `indices=[0, 1]`).
+- `relayout(id, update)`: layout attribute paths, `{"title.text": "Live"}`, `{"xaxis.range": [0, 10]}`, `{"xaxis.autorange": True}`. With `events="relayout"` on the output, the result comes back as `input.<id>_relayout`, the same as a user's zoom.
+
+The values go through plotly's encoder, so numpy arrays, pandas columns and datetimes work. The id is namespaced inside a module, like the output. An update reaches the figure that is drawn at that moment; one sent while the output has no figure (its first render is still running, it sits in a hidden tab, it shows an error or was emptied by `None`) is held and applied, in order, right after the output's next draw. A re-render replaces the figure, updates included, with what the render function returns: the server stays the source of truth, and a figure that should keep its streamed points across a re-render builds them in from server-side state.
 
 ### Lower level
 
@@ -233,6 +340,8 @@ def click_info():
 - `plotly_js()` is the `HTMLDependency` for plotly.js, served from the installed `plotly` wheel at `/lib/plotly-<version>/plotly.min.js`. Every `output_plotly` and every `fig_to_ui` fragment carries it, so it is optional; add it to the page UI when the first figure is inserted later (`ui.insert_ui`, a `@render.ui` that starts empty) and the bundle should load with the page.
 - `shiny_plotly_js()` is the helper's dependency. Every output and fragment carries it too.
 - `FIGUREWIDGET_MARGINS` is the `{"l": 16, "t": 32, "r": 16, "b": 16}` mapping.
+- `enable_compressed_plotly_js(app)` turns on compressed, immutable serving of plotly.js for a `shiny.App` before its first session (see below).
+- `extend_traces`, `restyle` and `relayout` take an optional `session=` when called outside the current session's context.
 
 `render_plotly` needs `output_plotly`; it is an output binding, not a `render.ui`, so `ui.output_ui(id)` does not draw it.
 
@@ -244,7 +353,16 @@ Shiny serves HTML dependencies from a plain static mount: no compression, no `Ca
 uv add "shiny-plotly[brotli]"  # optional: brotli instead of gzip
 ```
 
-Two things to know. The page load that starts the very first session of a process has already asked for the bundle before the route exists, so that one visitor gets the raw file from Shiny's mount; everyone after gets the compressed one. And if a reverse proxy in front of the app does its own compression and caching, or you want Shiny's static serving untouched for any reason, set `SHINY_PLOTLY_NO_COMPRESS=1` in the app's environment.
+Two things to know. The page load that starts the very first session of a process has already asked for the bundle before the route exists, so that one visitor gets the raw file from Shiny's mount; everyone after gets the compressed one. A Core app can close that gap by enabling the route as soon as the `App` exists:
+
+```python
+from shiny_plotly import enable_compressed_plotly_js
+
+app = App(app_ui, server)
+enable_compressed_plotly_js(app)
+```
+
+And if a reverse proxy in front of the app does its own compression and caching, or you want Shiny's static serving untouched for any reason, set `SHINY_PLOTLY_NO_COMPRESS=1` in the app's environment; `enable_compressed_plotly_js` then returns `False` and adds nothing.
 
 ## Examples
 
@@ -258,11 +376,12 @@ uv run --with shiny-plotly shiny run examples/express_app.py
 ```sh
 make sync        # uv sync --all-groups
 make browsers    # playwright install chromium, once
-make check       # lint, typecheck, unit + e2e tests, browser tests, wheel check
+make check       # lint, typecheck, unit + e2e tests, browser tests, wheel check, floor check
 make bench       # the shinywidgets comparison above, on this machine
+make bench-events  # what a selection over a dense trace costs, capped and uncapped
 ```
 
-`make test` runs the unit tests and the in-process Shiny end-to-end tests over a real websocket, including the compressed bundle route. `make test-browser` drives the package in headless Chromium: fill sizing, resize without a window event, the graph div surviving a re-render, `uirevision` keeping a dragged zoom, purge once an output leaves the page, full screen, `post_script` click wiring (once, not stacked), error and `None` rendering, on-demand loading of plotly.js and the compressed, cached bundle as a fresh visitor sees it. `make check-wheel` installs the built wheel into a throwaway venv and runs the suite against it, so the published artifact is what was tested.
+`make test` runs the unit tests and the in-process Shiny end-to-end tests over a real websocket, including the compressed bundle route. `make test-browser` drives the package in headless Chromium: fill sizing, resize without a window event, the graph div surviving a re-render, `uirevision` keeping a dragged zoom, purge once an output leaves the page, full screen, `events=` click, hover, selection and relayout inputs (attached once, also inside a module, a selection above `max_event_points` arriving as count and range), `extend_traces`, `restyle` and `relayout` applied in place (rolling window, one trace or all, held until the first draw, reset by a re-render, inside a module, dropped with a warning for an unknown output), `post_script` click wiring (once, not stacked), the dark mode recipe, error and `None` rendering, on-demand loading of plotly.js and the compressed, cached bundle as a fresh visitor sees it. `make check-wheel` installs the built wheel into a throwaway venv and runs the suite against it, so the published artifact is what was tested. `make check-floor` installs the package with plotly, shiny and htmltools at the oldest versions `pyproject.toml` allows and runs the whole suite again, browser tests included, so the declared lower bounds are tested on every push rather than assumed.
 
 ## License
 

{shiny_plotly-0.2.0 → shiny_plotly-0.3.0}/README.md

@@ -43,7 +43,7 @@ Measured on the same app (a slider and one fillable card with a line chart; `ben
 | Websocket bytes per re-render | 5.4 MB | 10 kB |
 | Re-render round trip, median of 50 | 1.1 to 1.4 s | 11 to 14 ms |
 
-Both need plotly.js in the browser. shiny-plotly serves `plotly.min.js` compressed (4.9 MB raw) with `Cache-Control: immutable`, so a browser fetches it once per plotly version; shinywidgets sends plotly's widget bundle as part of the `FigureWidget` state over the websocket, and a re-render creates a new `FigureWidget`, so that cost is paid on every visit and every re-render. The round-trip numbers come from a loaded laptop and are a range across runs, not a constant. shinywidgets does things this package does not (in-place `FigureWidget` updates, any ipywidget), which the table does not measure. `make bench` reproduces it; `bench/results.json` holds the raw numbers.
+Both need plotly.js in the browser. shiny-plotly serves `plotly.min.js` compressed (4.9 MB raw) with `Cache-Control: immutable`, so a browser fetches it once per plotly version; shinywidgets sends plotly's widget bundle as part of the `FigureWidget` state over the websocket, and a re-render creates a new `FigureWidget`, so that cost is paid on every visit and every re-render. The round-trip numbers come from a loaded laptop and are a range across runs, not a constant. shinywidgets does things this package does not (arbitrary in-place `FigureWidget` mutation, any ipywidget), which the table does not measure; the common in-place updates, appending points and changing trace or layout attributes, are covered by `extend_traces`, `restyle` and `relayout` below. `make bench` reproduces it; `bench/results.json` holds the raw numbers.
 
 ## Install
 
@@ -126,7 +126,9 @@ The decorator creates its own output placeholder in Express, just like `@render_
     width="100%",
     figurewidget_margins=True,  # the l16/t32/r16/b16 margins shinywidgets applies
     config={"displaylogo": False},
-    post_script=CLICK_TO_INPUT,  # JavaScript run once, when the graph is first drawn
+    events=("click", "selected"),  # arrive as input.sales_click, input.sales_selected
+    max_event_points=10_000,  # above it an event carries the count and range, not the points
+    post_script=MORE_JS,  # JavaScript run once, when the graph is first drawn
 )
 def sales(): ...
 ```
@@ -135,7 +137,7 @@ def sales(): ...
 
 ### Re-renders, zoom and pan
 
-Each `output_plotly` holds one plotly graph div. The first figure is drawn with `Plotly.newPlot`; every later one goes through `Plotly.react`, which diffs the new figure into the graph that is already there. So the DOM node, the handlers `post_script` attached and plotly's per-graph state all survive a re-render.
+Each `output_plotly` holds one plotly graph div. The first figure is drawn with `Plotly.newPlot`; every later one goes through `Plotly.react`, which diffs the new figure into the graph that is already there. So the DOM node, the event handlers (from `events=` or `post_script`) and plotly's per-graph state all survive a re-render.
 
 Whether the user's zoom and pan survive is plotly's `uirevision` rule, the same one shinywidgets users rely on for in-place updates: set `layout.uirevision` to any value and keep it the same across renders to preserve the view, change it to reset the view, leave it unset to reset on every render.
 
@@ -170,32 +172,137 @@ The rules mirror `output_widget`:
 
 Plotly alone re-measures a graph only on window resize. `shiny-plotly` ships a small helper script (`shiny-plotly.js`, loaded with every output) that observes each graph's container with a `ResizeObserver`, so a card that changes size without a window resize, for example when a sibling output renders below it, or when a sidebar collapses, re-lays the graph out. The same helper purges a graph once it leaves the document, which releases the window listener and layout state plotly would otherwise keep.
 
-### Events back to Shiny
+### Dark mode
 
-`post_script` runs once, after the first figure is drawn; `{plot_id}` is replaced with the graph div's id. Re-renders go through `Plotly.react` into the same graph div, so the handlers stay attached and are never stacked.
+Plotly does not follow Bootstrap's color mode by itself. Give the dark mode switch an id, read it in the render function to pick the template, and make the figure's backgrounds transparent so the card's own background shows through in both modes:
 
 ```python
-CLICK_TO_INPUT = """
-document.getElementById('{plot_id}').on('plotly_click', function (ev) {
-    var p = ev.points[0];
-    Shiny.setInputValue('clicked', {x: p.x, y: p.y}, {priority: 'event'});
-});
-"""
+app_ui = ui.page_fillable(
+    ui.input_dark_mode(id="mode"),
+    ui.card(output_plotly("sales")),
+)
 
 
-@render_plotly(post_script=CLICK_TO_INPUT)
+@render_plotly
+def sales():
+    template = "plotly_dark" if input.mode() == "dark" else "plotly"
+    fig = px.bar(df, x="month", y="total", template=template)
+    return fig.update_layout(paper_bgcolor="rgba(0,0,0,0)", plot_bgcolor="rgba(0,0,0,0)")
+```
+
+Flipping the switch re-renders the figure through `Plotly.react`, the same as any other re-render. `input.mode()` is `"light"` or `"dark"` and follows the user's system preference when the switch is not given an initial `mode`.
+
+### Events back to Shiny
+
+`events=` names the plotly events to forward; each arrives as `input.<id>_<event>`, namespaced like the output inside a module. Four are available: `click`, `hover`, `selected` and `relayout`.
+
+```python
+@render_plotly(events=("click", "selected"))
 def scatter(): ...
 
 
 @render.text
 def click_info():
-    if not input.clicked.is_set():
+    if not input.scatter_click.is_set():
         return "Click a point."
-    pt = input.clicked()
-    return f"x={pt['x']}, y={pt['y']}"
+    pt = input.scatter_click()["points"][0]
+    return f"trace {pt['curveNumber']}, point {pt['pointNumber']}: x={pt['x']}, y={pt['y']}"
+```
+
+What arrives is plotly's own event data, cut to what serializes, the same way Dash cuts it:
+
+| event | value of `input.<id>_<event>()` |
+| --- | --- |
+| `click` | `{"points": [...]}`; fires on every click, a repeated one too |
+| `hover` | `{"points": [...]}` while over a point, `None` once the pointer leaves; debounced (100 ms) |
+| `selected` | `{"points": [...], "range": {"x": [..], "y": [..]}}` for a box, `lassoPoints` for a lasso; `None` after a double-click deselect; above `max_event_points` the points give way to `point_count` (below) |
+| `relayout` | plotly's relayout data as is: `{"xaxis.range[0]": ..., "xaxis.range[1]": ...}` after a zoom or pan, `{"xaxis.autorange": True, ...}` after a reset, `{"dragmode": "pan"}` from the mode bar, `{"autosize": True}` after a resize |
+
+Each point carries plotly's scalar fields for that trace type (`curveNumber`, `pointNumber`, `pointIndex`, `x`, `y`, `z`, `text`, `label`, `value`, `lat`, `lon`, ...) plus `customdata` (as a plain list, also when it was a numpy array), `bbox` and `pointNumbers` when present. `input.<id>_<event>()` raises a silent exception until the event has fired once, so check `is_set()` when the output should show something before that.
+
+#### Dense traces
+
+A point is about 100 bytes of JSON, so a box over a dense trace builds a large message, and a large enough one ends the session: uvicorn closes a websocket on a message above 16 MB by default. `max_event_points` (default 10 000) is the most points one event carries. Above it the points stay in the browser and the value says so, with the selection's geometry intact:
+
+```python
+@render_plotly(events="selected")
+def scatter(): ...
+
+
+@render.text
+def picked():
+    sel = input.scatter_selected()
+    if sel is None:
+        return "Nothing selected."
+    if sel["points"] is not None:
+        return f"{len(sel['points'])} points"
+    # More than max_event_points: {"points": None, "point_count": 120000, "range": {...}}.
+    # The data is here, so membership is a filter on the box the user dragged.
+    (x0, x1), (y0, y1) = sel["range"]["x"], sel["range"]["y"]
+    inside = df[df.x.between(x0, x1) & df.y.between(y0, y1)]
+    return f"{sel['point_count']} points, {len(inside)} rows"
 ```
 
-`input.clicked()` raises a silent exception while the input has never been set, so check `is_set()` first when the output should show something before the first click.
+The value is never silently cut: `points` is a full list or `None`, and `point_count` is there when it is `None`. A lasso carries `lassoPoints` (the polygon's `x` and `y` lists) instead of `range`. `max_event_points=None` lifts the cap. Measured with `make bench-events` (one `Scattergl` trace, every point box-selected with a real mouse, headless Chromium and the server on the same laptop, 2026-08-19):
+
+| points | `max_event_points` | event JSON | mouse up to server |
+| --- | --- | --- | --- |
+| 1 000 | 10 000 | 99 kB | 83 ms |
+| 10 000 | 10 000 | 1.01 MB | 149 ms |
+| 100 000 | 10 000 | 136 B | 24 ms |
+| 100 000 | none | 10.33 MB | 1017 ms |
+| 200 000 | 10 000 | 135 B | 108 ms |
+| 200 000 | none | 20.89 MB | disconnected |
+
+`click` and `hover` carry one point per trace under the pointer, so the cap matters for `selected`; hover is also debounced (100 ms), so a pointer sweeping across a dense trace sends one event when it rests, not one per point.
+
+For anything else, `post_script` runs once, after the first figure is drawn, with `{plot_id}` replaced by the graph div's id. Re-renders go through `Plotly.react` into the same graph div, so handlers attached either way stay attached and are never stacked.
+
+```python
+LEGEND_TO_INPUT = """
+document.getElementById('{plot_id}').on('plotly_legendclick', function (ev) {
+    Shiny.setInputValue('legend', ev.curveNumber, {priority: 'event'});
+    return true;  // let plotly toggle the trace as usual
+});
+"""
+
+
+@render_plotly(post_script=LEGEND_TO_INPUT)
+def scatter(): ...
+```
+
+### Live updates without a re-render
+
+A re-render sends the whole figure. For a stream of points, a colour change or a new title, send just the change: `extend_traces`, `restyle` and `relayout` call the plotly.js functions of the same names on the graph an output holds. All three are coroutines, so the effect that calls them is `async def`.
+
+```python
+from shiny_plotly import extend_traces, relayout, restyle
+
+
+@render_plotly
+def prices():
+    return go.Figure(go.Scatter(x=[], y=[], mode="lines"))  # the seed; the stream fills it
+
+
+@reactive.effect
+async def _stream():
+    reactive.invalidate_later(1)
+    t, v = latest_sample()
+    await extend_traces("prices", {"x": [[t]], "y": [[v]]}, max_points=500)
+
+
+@reactive.effect
+@reactive.event(input.highlight)
+async def _highlight():
+    await restyle("prices", {"line.color": "crimson"}, indices=0)
+    await relayout("prices", {"title.text": "highlighted"})
+```
+
+- `extend_traces(id, data, indices=None, *, max_points=None)`: `data` maps an array attribute to one sequence of new values per trace, in the order of `indices` (`{"x": [[t]], "y": [[v]]}` appends one point to one trace; `{"y": [[1], [2]]}` with `indices=[0, 1]` one point to each of two). `indices` (an int or a list) defaults to every trace; `max_points` drops the oldest points past that many, for a rolling window.
+- `restyle(id, update, indices=None)`: `update` maps attribute paths to values; `{"marker.color": "red"}` applies to every trace in `indices`, a list value applies per trace (`{"opacity": [0.5, 1]}` with `indices=[0, 1]`).
+- `relayout(id, update)`: layout attribute paths, `{"title.text": "Live"}`, `{"xaxis.range": [0, 10]}`, `{"xaxis.autorange": True}`. With `events="relayout"` on the output, the result comes back as `input.<id>_relayout`, the same as a user's zoom.
+
+The values go through plotly's encoder, so numpy arrays, pandas columns and datetimes work. The id is namespaced inside a module, like the output. An update reaches the figure that is drawn at that moment; one sent while the output has no figure (its first render is still running, it sits in a hidden tab, it shows an error or was emptied by `None`) is held and applied, in order, right after the output's next draw. A re-render replaces the figure, updates included, with what the render function returns: the server stays the source of truth, and a figure that should keep its streamed points across a re-render builds them in from server-side state.
 
 ### Lower level
 
@@ -203,6 +310,8 @@ def click_info():
 - `plotly_js()` is the `HTMLDependency` for plotly.js, served from the installed `plotly` wheel at `/lib/plotly-<version>/plotly.min.js`. Every `output_plotly` and every `fig_to_ui` fragment carries it, so it is optional; add it to the page UI when the first figure is inserted later (`ui.insert_ui`, a `@render.ui` that starts empty) and the bundle should load with the page.
 - `shiny_plotly_js()` is the helper's dependency. Every output and fragment carries it too.
 - `FIGUREWIDGET_MARGINS` is the `{"l": 16, "t": 32, "r": 16, "b": 16}` mapping.
+- `enable_compressed_plotly_js(app)` turns on compressed, immutable serving of plotly.js for a `shiny.App` before its first session (see below).
+- `extend_traces`, `restyle` and `relayout` take an optional `session=` when called outside the current session's context.
 
 `render_plotly` needs `output_plotly`; it is an output binding, not a `render.ui`, so `ui.output_ui(id)` does not draw it.
 
@@ -214,7 +323,16 @@ Shiny serves HTML dependencies from a plain static mount: no compression, no `Ca
 uv add "shiny-plotly[brotli]"  # optional: brotli instead of gzip
 ```
 
-Two things to know. The page load that starts the very first session of a process has already asked for the bundle before the route exists, so that one visitor gets the raw file from Shiny's mount; everyone after gets the compressed one. And if a reverse proxy in front of the app does its own compression and caching, or you want Shiny's static serving untouched for any reason, set `SHINY_PLOTLY_NO_COMPRESS=1` in the app's environment.
+Two things to know. The page load that starts the very first session of a process has already asked for the bundle before the route exists, so that one visitor gets the raw file from Shiny's mount; everyone after gets the compressed one. A Core app can close that gap by enabling the route as soon as the `App` exists:
+
+```python
+from shiny_plotly import enable_compressed_plotly_js
+
+app = App(app_ui, server)
+enable_compressed_plotly_js(app)
+```
+
+And if a reverse proxy in front of the app does its own compression and caching, or you want Shiny's static serving untouched for any reason, set `SHINY_PLOTLY_NO_COMPRESS=1` in the app's environment; `enable_compressed_plotly_js` then returns `False` and adds nothing.
 
 ## Examples
 
@@ -228,11 +346,12 @@ uv run --with shiny-plotly shiny run examples/express_app.py
 ```sh
 make sync        # uv sync --all-groups
 make browsers    # playwright install chromium, once
-make check       # lint, typecheck, unit + e2e tests, browser tests, wheel check
+make check       # lint, typecheck, unit + e2e tests, browser tests, wheel check, floor check
 make bench       # the shinywidgets comparison above, on this machine
+make bench-events  # what a selection over a dense trace costs, capped and uncapped
 ```
 
-`make test` runs the unit tests and the in-process Shiny end-to-end tests over a real websocket, including the compressed bundle route. `make test-browser` drives the package in headless Chromium: fill sizing, resize without a window event, the graph div surviving a re-render, `uirevision` keeping a dragged zoom, purge once an output leaves the page, full screen, `post_script` click wiring (once, not stacked), error and `None` rendering, on-demand loading of plotly.js and the compressed, cached bundle as a fresh visitor sees it. `make check-wheel` installs the built wheel into a throwaway venv and runs the suite against it, so the published artifact is what was tested.
+`make test` runs the unit tests and the in-process Shiny end-to-end tests over a real websocket, including the compressed bundle route. `make test-browser` drives the package in headless Chromium: fill sizing, resize without a window event, the graph div surviving a re-render, `uirevision` keeping a dragged zoom, purge once an output leaves the page, full screen, `events=` click, hover, selection and relayout inputs (attached once, also inside a module, a selection above `max_event_points` arriving as count and range), `extend_traces`, `restyle` and `relayout` applied in place (rolling window, one trace or all, held until the first draw, reset by a re-render, inside a module, dropped with a warning for an unknown output), `post_script` click wiring (once, not stacked), the dark mode recipe, error and `None` rendering, on-demand loading of plotly.js and the compressed, cached bundle as a fresh visitor sees it. `make check-wheel` installs the built wheel into a throwaway venv and runs the suite against it, so the published artifact is what was tested. `make check-floor` installs the package with plotly, shiny and htmltools at the oldest versions `pyproject.toml` allows and runs the whole suite again, browser tests included, so the declared lower bounds are tested on every push rather than assumed.
 
 ## License
 

{shiny_plotly-0.2.0 → shiny_plotly-0.3.0}/examples/core_app.py

@@ -1,4 +1,4 @@
-"""Shiny Core example: three plotly charts rendered without shinywidgets.
+"""Shiny Core example: four plotly charts rendered without shinywidgets, one of them live.
 
 Run with:  uv run --with shiny-plotly shiny run examples/core_app.py
 """
@@ -9,15 +9,7 @@ from itertools import accumulate
 import plotly.graph_objects as go
 from shiny import App, Inputs, Outputs, Session, reactive, render, ui
 
-from shiny_plotly import output_plotly, render_plotly
-
-# Forwards plotly click events to a Shiny input. {plot_id} is the graph div's id.
-CLICK_TO_INPUT = """
-document.getElementById('{plot_id}').on('plotly_click', function (ev) {
-    var p = ev.points[0];
-    Shiny.setInputValue('clicked', {x: p.x, y: p.y}, {priority: 'event'});
-});
-"""
+from shiny_plotly import enable_compressed_plotly_js, extend_traces, output_plotly, render_plotly
 
 app_ui = ui.page_sidebar(
     ui.sidebar(
@@ -37,9 +29,15 @@ app_ui = ui.page_sidebar(
             full_screen=True,
         ),
     ),
-    ui.card(
-        ui.card_header("Fixed height, click a point"),
-        output_plotly("fixed_plot"),
+    ui.layout_columns(
+        ui.card(
+            ui.card_header("Fixed height, click a point"),
+            output_plotly("fixed_plot"),
+        ),
+        ui.card(
+            ui.card_header("Live: a point a second, no re-render"),
+            output_plotly("live_plot"),
+        ),
     ),
     title="shiny-plotly",
     fillable=True,
@@ -68,17 +66,39 @@ def server(input: Inputs, output: Outputs, session: Session):
         x, y = data()
         return go.Figure(go.Scatter(x=x, y=[abs(v) for v in y], fill="tozeroy"))
 
-    @render_plotly(height="260px", post_script=CLICK_TO_INPUT, config={"displaylogo": False})
+    # Clicks arrive as input.fixed_plot_click (the output id plus the event name).
+    @render_plotly(height="260px", events="click", config={"displaylogo": False})
     def fixed_plot():
         x, y = data()
         return go.Figure(go.Scatter(x=x, y=y, mode="markers"))
 
+    # The render function draws the seed once; every second an effect appends one point
+    # to the graph in the browser, keeping the last 60, and nothing is re-rendered.
+    @render_plotly(height="260px")
+    def live_plot():
+        return go.Figure(go.Scatter(x=[], y=[], mode="lines")).update_layout(
+            xaxis_title="tick", yaxis_title="value"
+        )
+
+    tick = 0
+
+    @reactive.effect
+    async def _stream():
+        nonlocal tick
+        reactive.invalidate_later(1)
+        tick += 1
+        point = {"x": [[tick]], "y": [[random.gauss(0, 1)]]}
+        await extend_traces("live_plot", point, max_points=60)
+
     @render.text
     def click_info():
-        if not input.clicked.is_set():
+        if not input.fixed_plot_click.is_set():
             return "Click a point in the bottom chart."
-        pt = input.clicked()
+        pt = input.fixed_plot_click()["points"][0]
         return f"Clicked x={pt['x']}, y={pt['y']:.2f}"
 
 
 app = App(app_ui, server)
+# Optional: serve plotly.js compressed from the very first request instead of from the
+# first session on (see README, "plotly.js on the wire").
+enable_compressed_plotly_js(app)

{shiny_plotly-0.2.0 → shiny_plotly-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shiny-plotly"
-version = "0.2.0"
+version = "0.3.0"
 description = "Render plotly figures in Shiny for Python with plain plotly.js, without the shinywidgets layer."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -25,10 +25,13 @@ classifiers = [
   "Topic :: Scientific/Engineering :: Visualization",
   "Typing :: Typed",
 ]
+# The floor is what `make check-floor` installs and tests: plotly 5.5 is the first with
+# to_html(div_id=...), shiny 1.0 is the oldest release the suite runs against, and
+# htmltools 0.5.2 is what shiny 1.0 itself requires.
 dependencies = [
   "shiny>=1.0",
-  "plotly>=5.0",
-  "htmltools>=0.5",
+  "plotly>=5.5",
+  "htmltools>=0.5.2",
 ]
 
 [project.optional-dependencies]
@@ -48,7 +51,6 @@ bench = [
 ]
 dev = [
   "pytest>=8",
-  "pytest-asyncio>=0.24",
   "ruff>=0.6",
   "pyright>=1.1.380",
   "httpx2>=2.12.0",
@@ -65,8 +67,6 @@ include = ["src/shiny_plotly", "tests", "examples", "README.md", "CHANGELOG.md",
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-asyncio_mode = "auto"
-asyncio_default_fixture_loop_scope = "function"
 filterwarnings = ["error"]
 markers = ["browser: drives the package in a real Chromium through playwright"]