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

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

@@ -7,3 +7,4 @@ __pycache__/
 .pytest_cache/
 .ruff_cache/
 tmp/
+site/

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

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.2](https://github.com/rvben/shiny-plotly/compare/v0.3.1...v0.3.2) - 2026-08-20
+
+### Added
+
+- Three more forwardable events: `doubleclick` arrives as a running count of plot-area double-clicks (plotly hands the event no data; the count's change invalidates the input); `legendclick` and `legenddoubleclick` arrive as the clicked trace's `curve_number`, `expanded_index`, `name` and pre-toggle `visible`, plus `label` for trace types whose legend items are labels. The default toggle and isolate behaviors still happen.
+- `examples/streaming_app.py`: a live rolling window fed by `extend_traces`, with a pause switch and a window slider; a browser test drives the example file itself and proves the stream flows and pauses.
+- A live demo at https://rvben.github.io/shiny-plotly/: `examples/shinylive/app.py` grew into a two-tab showcase (a streaming figure, click and box-select events, a dark mode toggle), deployed to GitHub Pages by a workflow that builds the site from the checkout's own wheel (`make site`) and gates the deploy on a headless Chromium watching both tabs render (`make site-check`). The committed example still installs from PyPI, so `uvx shinylive export examples/shinylive site` keeps working as documented.
+
+## [0.3.1](https://github.com/rvben/shiny-plotly/compare/v0.3.0...v0.3.1) - 2026-08-20
+
+### Added
+
+- `@render_plotly(theme="auto")`: the figure follows the page's color mode in the browser, with no server round-trip. `"auto"` pairs plotly's `"plotly"` and `"plotly_dark"` templates; a `(light, dark)` tuple picks others, each a registered name, a `Template` object or a template dict. Both templates travel with the figure with transparent backgrounds so the page shows through; the browser applies the mode's template before the first draw and switches it with `Plotly.relayout` when `data-bs-theme` (what `ui.input_dark_mode()` sets) or the OS `prefers-color-scheme` flips. Unknown template names raise at decoration time.
+- The in-place update family is complete: `add_traces`, `delete_traces`, `prepend_traces` and `update` (a restyle and a relayout in one redraw) join `extend_traces`, `restyle` and `relayout`. Same contract as the first three: values through plotly's encoder, ids namespaced inside a module, updates held and applied in order while the output has no figure drawn.
+- Examples for dark mode (`examples/dark_app.py`), dense-trace selections (`examples/events_app.py`) and a ready-to-export shinylive app (`examples/shinylive/`); a test keeps every example building.
+
+### Fixed
+
+- Shinylive: under pyodide the compressed plotly.js route is skipped instead of crashing the session. Pyodide cannot start threads, so the compression thread raised `RuntimeError: can't start new thread` from the first `@render_plotly` of every session and no figure ever rendered; there is also nothing to serve there, as the browser loads assets from the shinylive bundle. Verified against a real `shinylive export`: 0.3.0 crashes, this version renders.
+
 ## [0.3.0](https://github.com/rvben/shiny-plotly/compare/v0.2.0...v0.3.0) - 2026-08-20
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shiny-plotly
-Version: 0.3.0
+Version: 0.3.2
 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
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
@@ -37,6 +38,8 @@ Render [plotly](https://plotly.com/python/) figures in [Shiny for Python](https:
 [![PyPI](https://img.shields.io/pypi/v/shiny-plotly)](https://pypi.org/project/shiny-plotly/)
 [![CI](https://github.com/rvben/shiny-plotly/actions/workflows/ci.yml/badge.svg)](https://github.com/rvben/shiny-plotly/actions/workflows/ci.yml)
 
+**[Try the live demo](https://rvben.github.io/shiny-plotly/)**: a streaming figure and forwarded plotly events, running entirely in your browser through shinylive.
+
 ```python
 from shiny_plotly import output_plotly, render_plotly
 
@@ -83,7 +86,7 @@ uv add shiny-plotly
 pip install shiny-plotly
 ```
 
-Requires Python 3.10+, `shiny>=1.0`, `plotly>=5.0`.
+Requires Python 3.10+, `shiny>=1.0`, `plotly>=5.5`.
 
 ## Use
 
@@ -158,6 +161,7 @@ The decorator creates its own output placeholder in Express, just like `@render_
     config={"displaylogo": False},
     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
+    theme="auto",  # follow the page's color mode in the browser; also takes (light, dark)
     post_script=MORE_JS,  # JavaScript run once, when the graph is first drawn
 )
 def sales(): ...
@@ -204,7 +208,30 @@ Plotly alone re-measures a graph only on window resize. `shiny-plotly` ships a s
 
 ### Dark mode
 
-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:
+Plotly does not follow Bootstrap's color mode by itself. `theme="auto"` makes the figure follow it in the browser, with no server round-trip:
+
+```python
+app_ui = ui.page_fillable(
+    ui.input_dark_mode(),
+    ui.card(output_plotly("sales")),
+)
+
+
+@render_plotly(theme="auto")
+def sales():
+    return px.bar(df, x="month", y="total")
+```
+
+`"auto"` pairs plotly's own templates: `"plotly"` in light mode, `"plotly_dark"` in dark. A `(light, dark)` tuple picks different ones, each a registered name, a plotly `Template` object or a template dict:
+
+```python
+@render_plotly(theme=("seaborn", "plotly_dark"))
+def sales(): ...
+```
+
+How it works: both templates travel with the figure, their `paper_bgcolor` and `plot_bgcolor` made transparent so the card's own background shows through in both modes (backgrounds set on the figure's layout still win). The browser applies the mode's template before the first draw and switches it with `Plotly.relayout` when the mode flips, so the switch is instant and works even while the server is busy. The mode is `data-bs-theme` on `<html>`, which is what `ui.input_dark_mode()` maintains, or the OS `prefers-color-scheme` on a page without that attribute. A template the figure baked in through `layout.template` is dropped for themed outputs; use `theme=None` (the default) where the figure's own template should stand.
+
+The manual alternative, picking the template on the server, still works and is the way to vary anything beyond the template per mode. Give the dark mode switch an id and read it in the render function; flipping the switch then re-renders the figure through `Plotly.react`:
 
 ```python
 app_ui = ui.page_fillable(
@@ -220,11 +247,9 @@ def sales():
     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`.
+`events=` names the plotly events to forward; each arrives as `input.<id>_<event>`, namespaced like the output inside a module. Seven are available: `click`, `doubleclick`, `hover`, `selected`, `relayout`, `legendclick` and `legenddoubleclick`.
 
 ```python
 @render_plotly(events=("click", "selected"))
@@ -247,6 +272,9 @@ What arrives is plotly's own event data, cut to what serializes, the same way Da
 | `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 |
+| `doubleclick` | a running count of double-clicks on the plot area (the gesture that resets the axes); plotly hands the event no data, and the count's change is what invalidates the input |
+| `legendclick` | `{"curve_number": 1, "expanded_index": 1, "name": "beta", "visible": True}` for the trace whose legend item was clicked, `visible` as it stood before the click's toggle (`True` or `"legendonly"`); trace types whose legend items are labels (pie, funnelarea) add `label`; fires on every click, and the default toggle still happens |
+| `legenddoubleclick` | same value as `legendclick`; the default isolate-this-trace behavior still happens |
 
 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.
 
@@ -289,21 +317,20 @@ The value is never silently cut: `points` is a full list or `None`, and `point_c
 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
+ANNOTATION_TO_INPUT = """
+document.getElementById('{plot_id}').on('plotly_clickannotation', function (ev) {
+    Shiny.setInputValue('annotation', ev.index, {priority: 'event'});
 });
 """
 
 
-@render_plotly(post_script=LEGEND_TO_INPUT)
+@render_plotly(post_script=ANNOTATION_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`.
+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`, `prepend_traces`, `add_traces`, `delete_traces`, `restyle`, `relayout` and `update` call the plotly.js functions of the same names on the graph an output holds. All of them are coroutines, so the effect that calls them is `async def`.
 
 ```python
 from shiny_plotly import extend_traces, relayout, restyle
@@ -331,9 +358,15 @@ async def _highlight():
 - `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.
+- `update(id, restyle=None, relayout=None, indices=None)`: a restyle and a relayout in one redraw, where separate calls would draw twice. At least one of the two is required; `indices` scopes the trace part.
+- `prepend_traces(id, data, indices=None, *, max_points=None)`: the mirror of `extend_traces`; the new values go in front, and `max_points` drops points from the far end.
+- `add_traces(id, traces, indices=None)`: whole new traces, each a graph object (`go.Scatter(y=[1, 2])`) or a dict (`{"y": [1], "type": "bar"}`); `indices` says where they land in the trace order, appended without it.
+- `delete_traces(id, indices)`: removes the traces at `indices`; the rest renumber, as a Python list does on `del`.
 
 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.
 
+A runnable version of the streaming pattern, with a pause switch and a window slider, is `examples/streaming_app.py`.
+
 ### Lower level
 
 - `fig_to_ui(fig, div_id=None, *, height, width, figurewidget_margins, config, post_script)` returns a `TagList` holding the plotly.js dependency, the helper dependency and a `<div class="shiny-plotly">` that draws the figure with `Plotly.newPlot` (plotly's own `to_html` fragment). Use it from a plain `@render.ui` that composes a figure with other UI, or from any htmltools context. Each render draws a fresh graph; an output that is only a figure is better served by `render_plotly`.
@@ -364,11 +397,19 @@ 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.
 
+### Shinylive
+
+Apps using `shiny-plotly` run under [Shinylive](https://shiny.posit.co/py/get-started/shinylive.html) (pyodide in the browser) as well; list `shiny-plotly` in the app's `requirements.txt` next to `plotly`. There is no HTTP server in the browser and pyodide cannot start threads, so the compression route above stands down under pyodide (`enable_compressed_plotly_js` returns `False`); everything else, rendering, events, in-place updates and themes, is browser-side already. Verified against a real `shinylive export`; `examples/shinylive/` is a ready-to-export app, and its deployed copy is the [live demo](https://rvben.github.io/shiny-plotly/). The Pages workflow builds that demo from the current checkout's wheel (`make site`) and deploys only after a headless Chromium has watched both tabs render (`make site-check`).
+
 ## Examples
 
 ```sh
-uv run --with shiny-plotly shiny run examples/core_app.py
-uv run --with shiny-plotly shiny run examples/express_app.py
+uv run --with shiny-plotly shiny run examples/core_app.py     # fill, margins, a click input, a live stream
+uv run --with shiny-plotly shiny run examples/express_app.py  # the Express flavor
+uv run --with shiny-plotly shiny run examples/dark_app.py     # theme="auto" and a custom (light, dark) pair
+uv run --with shiny-plotly shiny run examples/events_app.py   # box selections over a 50k-point trace
+uv run --with shiny-plotly shiny run examples/streaming_app.py # a rolling window fed by extend_traces
+uvx shinylive export examples/shinylive site                  # the same package, running in the browser
 ```
 
 ## Development

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

@@ -7,6 +7,8 @@ Render [plotly](https://plotly.com/python/) figures in [Shiny for Python](https:
 [![PyPI](https://img.shields.io/pypi/v/shiny-plotly)](https://pypi.org/project/shiny-plotly/)
 [![CI](https://github.com/rvben/shiny-plotly/actions/workflows/ci.yml/badge.svg)](https://github.com/rvben/shiny-plotly/actions/workflows/ci.yml)
 
+**[Try the live demo](https://rvben.github.io/shiny-plotly/)**: a streaming figure and forwarded plotly events, running entirely in your browser through shinylive.
+
 ```python
 from shiny_plotly import output_plotly, render_plotly
 
@@ -53,7 +55,7 @@ uv add shiny-plotly
 pip install shiny-plotly
 ```
 
-Requires Python 3.10+, `shiny>=1.0`, `plotly>=5.0`.
+Requires Python 3.10+, `shiny>=1.0`, `plotly>=5.5`.
 
 ## Use
 
@@ -128,6 +130,7 @@ The decorator creates its own output placeholder in Express, just like `@render_
     config={"displaylogo": False},
     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
+    theme="auto",  # follow the page's color mode in the browser; also takes (light, dark)
     post_script=MORE_JS,  # JavaScript run once, when the graph is first drawn
 )
 def sales(): ...
@@ -174,7 +177,30 @@ Plotly alone re-measures a graph only on window resize. `shiny-plotly` ships a s
 
 ### Dark mode
 
-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:
+Plotly does not follow Bootstrap's color mode by itself. `theme="auto"` makes the figure follow it in the browser, with no server round-trip:
+
+```python
+app_ui = ui.page_fillable(
+    ui.input_dark_mode(),
+    ui.card(output_plotly("sales")),
+)
+
+
+@render_plotly(theme="auto")
+def sales():
+    return px.bar(df, x="month", y="total")
+```
+
+`"auto"` pairs plotly's own templates: `"plotly"` in light mode, `"plotly_dark"` in dark. A `(light, dark)` tuple picks different ones, each a registered name, a plotly `Template` object or a template dict:
+
+```python
+@render_plotly(theme=("seaborn", "plotly_dark"))
+def sales(): ...
+```
+
+How it works: both templates travel with the figure, their `paper_bgcolor` and `plot_bgcolor` made transparent so the card's own background shows through in both modes (backgrounds set on the figure's layout still win). The browser applies the mode's template before the first draw and switches it with `Plotly.relayout` when the mode flips, so the switch is instant and works even while the server is busy. The mode is `data-bs-theme` on `<html>`, which is what `ui.input_dark_mode()` maintains, or the OS `prefers-color-scheme` on a page without that attribute. A template the figure baked in through `layout.template` is dropped for themed outputs; use `theme=None` (the default) where the figure's own template should stand.
+
+The manual alternative, picking the template on the server, still works and is the way to vary anything beyond the template per mode. Give the dark mode switch an id and read it in the render function; flipping the switch then re-renders the figure through `Plotly.react`:
 
 ```python
 app_ui = ui.page_fillable(
@@ -190,11 +216,9 @@ def sales():
     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`.
+`events=` names the plotly events to forward; each arrives as `input.<id>_<event>`, namespaced like the output inside a module. Seven are available: `click`, `doubleclick`, `hover`, `selected`, `relayout`, `legendclick` and `legenddoubleclick`.
 
 ```python
 @render_plotly(events=("click", "selected"))
@@ -217,6 +241,9 @@ What arrives is plotly's own event data, cut to what serializes, the same way Da
 | `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 |
+| `doubleclick` | a running count of double-clicks on the plot area (the gesture that resets the axes); plotly hands the event no data, and the count's change is what invalidates the input |
+| `legendclick` | `{"curve_number": 1, "expanded_index": 1, "name": "beta", "visible": True}` for the trace whose legend item was clicked, `visible` as it stood before the click's toggle (`True` or `"legendonly"`); trace types whose legend items are labels (pie, funnelarea) add `label`; fires on every click, and the default toggle still happens |
+| `legenddoubleclick` | same value as `legendclick`; the default isolate-this-trace behavior still happens |
 
 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.
 
@@ -259,21 +286,20 @@ The value is never silently cut: `points` is a full list or `None`, and `point_c
 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
+ANNOTATION_TO_INPUT = """
+document.getElementById('{plot_id}').on('plotly_clickannotation', function (ev) {
+    Shiny.setInputValue('annotation', ev.index, {priority: 'event'});
 });
 """
 
 
-@render_plotly(post_script=LEGEND_TO_INPUT)
+@render_plotly(post_script=ANNOTATION_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`.
+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`, `prepend_traces`, `add_traces`, `delete_traces`, `restyle`, `relayout` and `update` call the plotly.js functions of the same names on the graph an output holds. All of them are coroutines, so the effect that calls them is `async def`.
 
 ```python
 from shiny_plotly import extend_traces, relayout, restyle
@@ -301,9 +327,15 @@ async def _highlight():
 - `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.
+- `update(id, restyle=None, relayout=None, indices=None)`: a restyle and a relayout in one redraw, where separate calls would draw twice. At least one of the two is required; `indices` scopes the trace part.
+- `prepend_traces(id, data, indices=None, *, max_points=None)`: the mirror of `extend_traces`; the new values go in front, and `max_points` drops points from the far end.
+- `add_traces(id, traces, indices=None)`: whole new traces, each a graph object (`go.Scatter(y=[1, 2])`) or a dict (`{"y": [1], "type": "bar"}`); `indices` says where they land in the trace order, appended without it.
+- `delete_traces(id, indices)`: removes the traces at `indices`; the rest renumber, as a Python list does on `del`.
 
 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.
 
+A runnable version of the streaming pattern, with a pause switch and a window slider, is `examples/streaming_app.py`.
+
 ### Lower level
 
 - `fig_to_ui(fig, div_id=None, *, height, width, figurewidget_margins, config, post_script)` returns a `TagList` holding the plotly.js dependency, the helper dependency and a `<div class="shiny-plotly">` that draws the figure with `Plotly.newPlot` (plotly's own `to_html` fragment). Use it from a plain `@render.ui` that composes a figure with other UI, or from any htmltools context. Each render draws a fresh graph; an output that is only a figure is better served by `render_plotly`.
@@ -334,11 +366,19 @@ 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.
 
+### Shinylive
+
+Apps using `shiny-plotly` run under [Shinylive](https://shiny.posit.co/py/get-started/shinylive.html) (pyodide in the browser) as well; list `shiny-plotly` in the app's `requirements.txt` next to `plotly`. There is no HTTP server in the browser and pyodide cannot start threads, so the compression route above stands down under pyodide (`enable_compressed_plotly_js` returns `False`); everything else, rendering, events, in-place updates and themes, is browser-side already. Verified against a real `shinylive export`; `examples/shinylive/` is a ready-to-export app, and its deployed copy is the [live demo](https://rvben.github.io/shiny-plotly/). The Pages workflow builds that demo from the current checkout's wheel (`make site`) and deploys only after a headless Chromium has watched both tabs render (`make site-check`).
+
 ## Examples
 
 ```sh
-uv run --with shiny-plotly shiny run examples/core_app.py
-uv run --with shiny-plotly shiny run examples/express_app.py
+uv run --with shiny-plotly shiny run examples/core_app.py     # fill, margins, a click input, a live stream
+uv run --with shiny-plotly shiny run examples/express_app.py  # the Express flavor
+uv run --with shiny-plotly shiny run examples/dark_app.py     # theme="auto" and a custom (light, dark) pair
+uv run --with shiny-plotly shiny run examples/events_app.py   # box selections over a 50k-point trace
+uv run --with shiny-plotly shiny run examples/streaming_app.py # a rolling window fed by extend_traces
+uvx shinylive export examples/shinylive site                  # the same package, running in the browser
 ```
 
 ## Development

shiny_plotly-0.3.2/examples/dark_app.py

@@ -0,0 +1,53 @@
+"""Dark mode example: theme="auto" follows the page's color mode in the browser.
+
+Run with:  uv run --with shiny-plotly shiny run examples/dark_app.py
+"""
+
+import plotly.graph_objects as go
+from shiny import App, Inputs, Outputs, Session, ui
+
+from shiny_plotly import output_plotly, render_plotly
+
+MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
+TOTALS = [12, 17, 9, 20, 14, 23]
+
+app_ui = ui.page_fillable(
+    ui.input_dark_mode(),
+    ui.layout_columns(
+        ui.card(
+            ui.card_header("theme='auto': plotly in light, plotly_dark in dark"),
+            output_plotly("auto_themed"),
+            full_screen=True,
+        ),
+        ui.card(
+            ui.card_header("A custom (light, dark) pair"),
+            output_plotly("pair_themed"),
+            full_screen=True,
+        ),
+    ),
+    title="shiny-plotly dark mode",
+)
+
+# Any registered template name, plotly Template object or template dict works in the pair.
+DARK_TEMPLATE = {
+    "layout": {
+        "font": {"color": "#f2f5fa"},
+        "colorway": ["#66c2a5", "#fc8d62", "#8da0cb"],
+    }
+}
+
+
+def server(input: Inputs, output: Outputs, session: Session):
+    # The flip happens in the browser with Plotly.relayout: no server round-trip, and it
+    # works even while the server is busy. Both templates travel with the figure, their
+    # backgrounds made transparent so the card shows through in both modes.
+    @render_plotly(theme="auto")
+    def auto_themed():
+        return go.Figure(go.Bar(x=MONTHS, y=TOTALS))
+
+    @render_plotly(theme=("seaborn", DARK_TEMPLATE))
+    def pair_themed():
+        return go.Figure(go.Scatter(x=MONTHS, y=TOTALS, mode="lines+markers"))
+
+
+app = App(app_ui, server)

shiny_plotly-0.3.2/examples/events_app.py

@@ -0,0 +1,64 @@
+"""Events example: clicks and box selections arrive as Shiny inputs.
+
+The trace holds 50 000 points, above the default max_event_points of 10 000, so a big
+selection arrives as a count plus the box's geometry and the server recounts membership
+from its own data, the pattern the README describes for dense traces.
+
+Run with:  uv run --with shiny-plotly shiny run examples/events_app.py
+"""
+
+import random
+
+import plotly.graph_objects as go
+from shiny import App, Inputs, Outputs, Session, render, ui
+
+from shiny_plotly import output_plotly, render_plotly
+
+rng = random.Random(7)
+N = 50_000
+X = [rng.gauss(0, 1) for _ in range(N)]
+Y = [rng.gauss(0, 1) for _ in range(N)]
+
+app_ui = ui.page_fillable(
+    ui.card(
+        ui.card_header("Drag a box; click a point"),
+        output_plotly("cloud"),
+        full_screen=True,
+    ),
+    ui.output_text("selection_info"),
+    ui.output_text("click_info"),
+    title="shiny-plotly events",
+)
+
+
+def server(input: Inputs, output: Outputs, session: Session):
+    @render_plotly(events=("click", "selected"))
+    def cloud():
+        fig = go.Figure(go.Scattergl(x=X, y=Y, mode="markers", marker={"size": 3}))
+        return fig.update_layout(dragmode="select")
+
+    @render.text
+    def selection_info():
+        if not input.cloud_selected.is_set():
+            return "Selection: none yet."
+        sel = input.cloud_selected()
+        if sel is None:
+            return "Selection: cleared."
+        if sel["points"] is not None:
+            return f"Selection: {len(sel['points'])} points arrived with the event."
+        # Above max_event_points the geometry arrives instead of the points; the data
+        # lives here, so membership is a filter on the box the user dragged.
+        x0, x1 = sorted(sel["range"]["x"])
+        y0, y1 = sorted(sel["range"]["y"])
+        inside = sum(1 for x, y in zip(X, Y, strict=True) if x0 <= x <= x1 and y0 <= y <= y1)
+        return f"Selection: {sel['point_count']} points; recounted {inside} on the server."
+
+    @render.text
+    def click_info():
+        if not input.cloud_click.is_set():
+            return "Click: none yet."
+        pt = input.cloud_click()["points"][0]
+        return f"Click: point {pt['pointNumber']} at x={pt['x']:.2f}, y={pt['y']:.2f}."
+
+
+app = App(app_ui, server)

shiny_plotly-0.3.2/examples/shinylive/app.py

@@ -0,0 +1,114 @@
+"""The live demo behind https://rvben.github.io/shiny-plotly/, running in the browser.
+
+The whole app runs in the browser via pyodide: no server. Two tabs show the package's
+two sides. Stream draws one empty figure and feeds it through ``extend_traces``, one
+small message per tick, no re-render. Explore forwards plotly's click and box-select
+events to Shiny inputs. Both figures follow the page's color mode via ``theme="auto"``
+and the toggle in the corner.
+
+Export this directory to a static site and serve it:
+
+    uvx shinylive export examples/shinylive site
+    python -m http.server 8000 -d site
+
+That installs the released package from PyPI (requirements.txt); the deployed demo is
+built by ``make site``, which installs the wheel from the current checkout instead.
+"""
+
+import random
+from datetime import datetime
+
+import plotly.graph_objects as go
+from shiny import App, Inputs, Outputs, Session, reactive, render, ui
+
+from shiny_plotly import extend_traces, output_plotly, render_plotly
+
+TICK_SECONDS = 0.5
+CLUSTERS = {"alpha": (0.0, 0.0), "beta": (3.0, 2.0), "gamma": (1.0, 4.0)}
+
+app_ui = ui.page_fillable(
+    ui.div(
+        ui.tags.b("shiny-plotly"),
+        ui.span("plotly figures in Shiny for Python, without shinywidgets", class_="text-muted"),
+        ui.div(ui.input_dark_mode(), class_="ms-auto"),
+        class_="d-flex align-items-center gap-3",
+    ),
+    ui.navset_card_underline(
+        ui.nav_panel(
+            "Stream",
+            ui.layout_columns(
+                ui.input_switch("run", "Stream", value=True),
+                ui.input_slider("window", "Window (points)", min=50, max=500, value=200, step=50),
+                col_widths=(3, 9),
+            ),
+            output_plotly("stream"),
+        ),
+        ui.nav_panel(
+            "Explore",
+            output_plotly("explore"),
+            ui.layout_columns(ui.output_text("clicked"), ui.output_text("picked")),
+        ),
+    ),
+    title="shiny-plotly demo",
+)
+
+
+def server(input: Inputs, output: Outputs, session: Session):
+    # Per-session: each visitor gets their own stream.
+    state = {"a": 20.0, "b": 50.0}
+
+    @render_plotly(theme="auto")
+    def stream():
+        fig = go.Figure(
+            [
+                go.Scatter(x=[], y=[], mode="lines", name="sensor a"),
+                go.Scatter(x=[], y=[], mode="lines", name="sensor b"),
+            ]
+        )
+        return fig.update_layout(uirevision="keep")
+
+    @reactive.effect
+    async def _tick():
+        reactive.invalidate_later(TICK_SECONDS)
+        if not input.run():
+            return
+        now = datetime.now()
+        state["a"] += random.uniform(-1.0, 1.0)
+        state["b"] += random.uniform(-2.0, 2.0)
+        # One column of new values per trace; max_points keeps the rolling window.
+        await extend_traces(
+            "stream",
+            {"x": [[now], [now]], "y": [[state["a"]], [state["b"]]]},
+            max_points=input.window(),
+        )
+
+    @render_plotly(theme="auto", events=("click", "selected"))
+    def explore():
+        rng = random.Random(7)
+        fig = go.Figure()
+        for name, (cx, cy) in CLUSTERS.items():
+            fig.add_scatter(
+                x=[cx + rng.gauss(0, 0.8) for _ in range(40)],
+                y=[cy + rng.gauss(0, 0.8) for _ in range(40)],
+                mode="markers",
+                name=name,
+            )
+        # Select mode from the start, so a plain drag is a box selection.
+        return fig.update_layout(dragmode="select")
+
+    @render.text
+    def clicked():
+        if not input.explore_click.is_set():
+            return "Click a point."
+        point = input.explore_click()["points"][0]
+        name = list(CLUSTERS)[point["curveNumber"]]
+        return f"Clicked {name} at ({point['x']:.2f}, {point['y']:.2f})."
+
+    @render.text
+    def picked():
+        if not input.explore_selected.is_set() or input.explore_selected() is None:
+            return "Drag a box to select points."
+        return f"{len(input.explore_selected()['points'])} points selected."
+
+
+app = App(app_ui, server)

shiny_plotly-0.3.2/examples/shinylive/requirements.txt

@@ -0,0 +1,3 @@
+# 0.3.0 started a thread at session start, which pyodide cannot do; newer versions skip it.
+shiny-plotly>0.3.0
+plotly