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

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

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0](https://github.com/rvben/shiny-plotly/compare/v0.1.0...v0.2.0) - 2026-08-19
+
+### Changed
+
+- `@render_plotly` is now a Shiny output binding instead of a `render.ui`: the figure travels as plotly JSON and `shiny-plotly.js` draws it with `Plotly.newPlot` the first time and `Plotly.react` on every re-render, into one graph div it keeps. Handlers attached by `post_script` stay attached (it runs once, not on every render), a figure with `layout.uirevision` keeps the user's zoom and pan across re-renders, a render error shows in place and `None` empties the output. Trace data is serialized by plotly's encoder, so numpy arrays, pandas columns and datetimes work as they do in `fig.to_json()`.
+- `output_plotly()` carries the plotly.js and helper dependencies itself, so a page-level `plotly_js()` call is no longer needed for it.
+- **Breaking:** `@render_plotly` requires `output_plotly(id)`; `ui.output_ui(id)` no longer draws it. `fig_to_ui` is unchanged and remains the path for `@render.ui`.
+
+### Added
+
+- `plotly.min.js` is served pre-compressed (brotli with the optional `brotli` extra, gzip otherwise) with `Cache-Control: public, max-age=31536000, immutable`, `Vary: Accept-Encoding` and an `ETag` per encoding, through a route added in front of Shiny's static mount when the first session renders a figure. Compression runs once per process in a background thread. `SHINY_PLOTLY_NO_COMPRESS=1` turns the route off.
+- `shiny-plotly[brotli]` extra.
+- Bench: one warm-up visit per server before measuring, HTTP accounting from the browser's Resource Timing (cache hits count as zero bytes), and rows for plotly.js on the wire and requests that left the cache on a repeat visit.
+
 ## [0.1.0] - 2026-08-19
 
 ### Added
@@ -19,6 +33,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `figurewidget_margins=True` fills in unset margin sides with the values shinywidgets applies to a `FigureWidget` (l16/t32/r16/b16), for pixel-identical migrations.
 - `config` (merged over `{"responsive": True}`) and `post_script` (with `{plot_id}` substitution) options for forwarding plotly events to Shiny inputs.
 - Test suite: unit tests, in-process Shiny end-to-end tests over a real websocket, and a headless Chromium suite covering sizing, resize tracking, purge on re-render, full screen and `post_script` wiring.
-
-[Unreleased]: https://github.com/rvben/shiny-plotly/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/rvben/shiny-plotly/releases/tag/v0.1.0

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: shiny-plotly
-Version: 0.1.0
-Summary: Render plotly figures in Shiny for Python as plain HTML, without the shinywidgets layer.
+Version: 0.2.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
 Project-URL: Changelog, https://github.com/rvben/shiny-plotly/blob/main/CHANGELOG.md
@@ -24,11 +24,13 @@ Requires-Python: >=3.10
 Requires-Dist: htmltools>=0.5
 Requires-Dist: plotly>=5.0
 Requires-Dist: shiny>=1.0
+Provides-Extra: brotli
+Requires-Dist: brotli>=1.1; extra == 'brotli'
 Description-Content-Type: text/markdown
 
 # shiny-plotly
 
-Render [plotly](https://plotly.com/python/) figures in [Shiny for Python](https://shiny.posit.co/py/) as plain HTML, without the shinywidgets layer.
+Render [plotly](https://plotly.com/python/) figures in [Shiny for Python](https://shiny.posit.co/py/) with plain plotly.js, without the shinywidgets layer.
 
 *An independent project, not affiliated with or endorsed by Posit or Plotly.*
 
@@ -48,7 +50,7 @@ def sales():
     return go.Figure(go.Bar(x=months, y=totals))
 ```
 
-That is the whole API surface for the common case. The figure is serialized with plotly's own `to_html`, sent to the browser as a UI fragment, and drawn with `Plotly.newPlot`. No ipywidgets, no kernel comm, no anywidget. Every render replaces the figure, which is how most dashboards already use `@render_widget`.
+That is the whole API surface for the common case. The figure travels as plotly's own JSON over Shiny's websocket; a small output binding draws it with `Plotly.newPlot` the first time and `Plotly.react` on every re-render, into one graph div it keeps. No ipywidgets, no kernel comm, no anywidget. Every render replaces the figure, which is how most dashboards already use `@render_widget`; zoom and pan survive it when the figure sets `layout.uirevision`.
 
 ## Why
 
@@ -58,7 +60,20 @@ That is the whole API surface for the common case. The figure is serialized with
 - a second rendering path next to Shiny's own, with its own quirks around sizing and full screen;
 - figures held as widget state on the server for the life of the session.
 
-`shiny-plotly` renders the figure the way plotly itself does, as HTML plus `Plotly.newPlot`, and uses Shiny's `render.ui` for delivery. The plotly.js bundle is served straight from the installed `plotly` wheel, keyed by its version, so nothing is copied or vendored.
+`shiny-plotly` sends the figure as plotly JSON and draws it with plotly.js directly, through a Shiny output binding. The plotly.js bundle is served straight from the installed `plotly` wheel, keyed by its version, pre-compressed and with an immutable cache lifetime, so nothing is copied or vendored and a browser fetches it once.
+
+Measured on the same app (a slider and one fillable card with a line chart; `bench/`), shiny 1.7.0, plotly 6.9.0, shinywidgets 0.8.1, shiny-plotly 0.2.0, headless Chromium, 2026-08-19:
+
+| | shinywidgets | shiny-plotly |
+| --- | --- | --- |
+| Packages added on top of `shiny` + `plotly` | 24 (38 MB) | 1 (38 kB) |
+| First visit, bytes to the first figure | 10.7 MB (5.3 MB HTTP + 5.4 MB websocket) | 2.6 MB (2.6 MB HTTP + 9 kB websocket) |
+| of which plotly.js over HTTP | 0 (in the websocket) | 1.2 MB (brotli; 1.5 MB gzip) |
+| Repeat visit (warm browser cache) | 5.4 MB, nearly all websocket | 13 kB |
+| 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.
 
 ## Install
 
@@ -81,7 +96,7 @@ from itertools import accumulate
 import plotly.graph_objects as go
 from shiny import App, ui
 
-from shiny_plotly import output_plotly, plotly_js, render_plotly
+from shiny_plotly import output_plotly, render_plotly
 
 app_ui = ui.page_fillable(
     ui.input_slider("n", "Points", 10, 500, 100),
@@ -90,7 +105,6 @@ app_ui = ui.page_fillable(
         output_plotly("walk"),
         full_screen=True,
     ),
-    plotly_js(),  # optional: load plotly.js with the page instead of with the first figure
 )
 
 
@@ -142,12 +156,24 @@ 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 after the plot is drawn
+    post_script=CLICK_TO_INPUT,  # JavaScript run once, when the graph is first drawn
 )
 def sales(): ...
 ```
 
-`None` from the render function renders nothing. The function may be sync or async. It may also return `fig.to_dict()` instead of a `Figure`.
+`None` from the render function empties the output. The function may be sync or async. It may also return `fig.to_dict()` instead of a `Figure`. Anything plotly's own encoder serializes is fine as trace data: numpy arrays, pandas columns, datetimes.
+
+### 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.
+
+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.
+
+```python
+@render_plotly
+def prices():
+    return px.line(frame(), x="date", y="close").update_layout(uirevision="prices")
+```
 
 ### Migrating from shinywidgets
 
@@ -159,10 +185,11 @@ def sales(): ...
 | `@render_widget` | `@render_plotly` |
 | (FigureWidget margins, applied implicitly) | `@render_plotly(figurewidget_margins=True)` |
 
-Two things change on purpose:
+Three things change on purpose:
 
 - **Margins.** shinywidgets sets tight margins (`l=16, t=32, r=16, b=16`) on every FigureWidget; plotly's own defaults are `80/100/80/80`. `shiny-plotly` uses plotly's defaults unless you pass `figurewidget_margins=True`, which fills in only the sides your figure leaves unset. Set margins explicitly on the figure if you want something else.
 - **In-place mutation.** A `FigureWidget` you keep on the server and mutate (`fig.data[0].y = ...`, `fig.add_trace(...)` after render) is exactly what shinywidgets is for. `shiny-plotly` has no channel for that; return a new figure from the render function and let Shiny re-render. If your app depends on in-place widget updates, stay on shinywidgets for those outputs. Both packages can coexist in one app.
+- **Zoom across re-renders.** A mutated `FigureWidget` keeps the user's zoom because nothing replaces the figure. Here a re-render is a new figure, so plotly's `uirevision` decides: set `layout.uirevision` (see above) to keep the view.
 
 ### Sizing
 
@@ -171,11 +198,11 @@ The rules mirror `output_widget`:
 - `height=None` (default): the plot fills its container. Inside `ui.card(full_screen=True)`, a fillable page or a sidebar layout it grows and shrinks with the card, from a 400px basis. Outside a fill layout it is 400px tall.
 - `height="300px"` (on the decorator or on `output_plotly`): the plot is exactly that tall and opts out of filling.
 
-Plotly alone re-measures a graph only on window resize. `shiny-plotly` ships a small helper script (`shiny-plotly.js`, loaded with every figure) 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 Shiny has replaced the output holding it, which releases the window listener and layout state plotly would otherwise keep for every render.
+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
 
-`post_script` runs after `Plotly.newPlot` resolves; `{plot_id}` is replaced with the graph div's id.
+`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.
 
 ```python
 CLICK_TO_INPUT = """
@@ -202,11 +229,23 @@ def click_info():
 
 ### Lower level
 
-- `fig_to_ui(fig, div_id=None, *, height, width, figurewidget_margins, config, post_script)` returns the `TagList` a render produces: the plotly.js dependency, the helper dependency and the `<div class="shiny-plotly">` holding the figure. Use it from a plain `@render.ui` that composes several things, or from any htmltools context.
-- `plotly_js()` is the `HTMLDependency` for plotly.js, served from the installed `plotly` wheel at `/lib/plotly-<version>/plotly.min.js`. Every figure carries it, so it is optional; add it to the page UI to load the bundle up front instead of with the first figure.
-- `shiny_plotly_js()` is the helper's dependency. Every figure carries it too.
+- `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`.
+- `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.
 
+`render_plotly` needs `output_plotly`; it is an output binding, not a `render.ui`, so `ui.output_ui(id)` does not draw it.
+
+### plotly.js on the wire
+
+Shiny serves HTML dependencies from a plain static mount: no compression, no `Cache-Control`. `plotly.min.js` is 4.9 MB, so once the first session of a process has rendered a figure, `shiny-plotly` adds a route in front of that mount for the bundle's exact path (`/lib/plotly-<version>/plotly.min.js`) that serves it pre-compressed (brotli when the `brotli` package is installed, gzip otherwise; 1.2 MB or 1.5 MB on the wire) with `Cache-Control: public, max-age=31536000, immutable`, `Vary: Accept-Encoding` and an `ETag` per encoding. The URL is keyed by the plotly version, so a browser fetches each version once. Compression runs once per process, in a background thread; until it has finished the route serves the raw file with the same headers.
+
+```sh
+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.
+
 ## Examples
 
 ```sh
@@ -220,9 +259,10 @@ uv run --with shiny-plotly shiny run examples/express_app.py
 make sync        # uv sync --all-groups
 make browsers    # playwright install chromium, once
 make check       # lint, typecheck, unit + e2e tests, browser tests, wheel check
+make bench       # the shinywidgets comparison above, on this machine
 ```
 
-`make test` runs the unit tests and the in-process Shiny end-to-end tests over a real websocket. `make test-browser` drives the package in headless Chromium: fill sizing, resize without a window event, purge on re-render, full screen, `post_script` click wiring and on-demand loading of plotly.js. `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, `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.
 
 ## License
 

shiny_plotly-0.2.0/README.md

@@ -0,0 +1,239 @@
+# shiny-plotly
+
+Render [plotly](https://plotly.com/python/) figures in [Shiny for Python](https://shiny.posit.co/py/) with plain plotly.js, without the shinywidgets layer.
+
+*An independent project, not affiliated with or endorsed by Posit or Plotly.*
+
+[![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)
+
+```python
+from shiny_plotly import output_plotly, render_plotly
+
+# UI
+output_plotly("sales")
+
+
+# server
+@render_plotly
+def sales():
+    return go.Figure(go.Bar(x=months, y=totals))
+```
+
+That is the whole API surface for the common case. The figure travels as plotly's own JSON over Shiny's websocket; a small output binding draws it with `Plotly.newPlot` the first time and `Plotly.react` on every re-render, into one graph div it keeps. No ipywidgets, no kernel comm, no anywidget. Every render replaces the figure, which is how most dashboards already use `@render_widget`; zoom and pan survive it when the figure sets `layout.uirevision`.
+
+## Why
+
+`shinywidgets` renders a plotly figure by wrapping it in a `FigureWidget` and shipping it through the ipywidgets comm protocol. That machinery earns its keep when the app mutates a figure in place (`fig.data[0].y = ...`) and wants the browser to patch it. Most Shiny apps do not do that; they rebuild the figure inside a reactive function and let Shiny re-render the output. For those apps the widget layer is overhead:
+
+- extra dependencies (`ipywidgets`, `anywidget`, `shinywidgets`) and their JavaScript bundles on every page;
+- a second rendering path next to Shiny's own, with its own quirks around sizing and full screen;
+- figures held as widget state on the server for the life of the session.
+
+`shiny-plotly` sends the figure as plotly JSON and draws it with plotly.js directly, through a Shiny output binding. The plotly.js bundle is served straight from the installed `plotly` wheel, keyed by its version, pre-compressed and with an immutable cache lifetime, so nothing is copied or vendored and a browser fetches it once.
+
+Measured on the same app (a slider and one fillable card with a line chart; `bench/`), shiny 1.7.0, plotly 6.9.0, shinywidgets 0.8.1, shiny-plotly 0.2.0, headless Chromium, 2026-08-19:
+
+| | shinywidgets | shiny-plotly |
+| --- | --- | --- |
+| Packages added on top of `shiny` + `plotly` | 24 (38 MB) | 1 (38 kB) |
+| First visit, bytes to the first figure | 10.7 MB (5.3 MB HTTP + 5.4 MB websocket) | 2.6 MB (2.6 MB HTTP + 9 kB websocket) |
+| of which plotly.js over HTTP | 0 (in the websocket) | 1.2 MB (brotli; 1.5 MB gzip) |
+| Repeat visit (warm browser cache) | 5.4 MB, nearly all websocket | 13 kB |
+| 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.
+
+## Install
+
+```sh
+uv add shiny-plotly
+# or
+pip install shiny-plotly
+```
+
+Requires Python 3.10+, `shiny>=1.0`, `plotly>=5.0`.
+
+## Use
+
+### Core
+
+```python
+import random
+from itertools import accumulate
+
+import plotly.graph_objects as go
+from shiny import App, ui
+
+from shiny_plotly import output_plotly, render_plotly
+
+app_ui = ui.page_fillable(
+    ui.input_slider("n", "Points", 10, 500, 100),
+    ui.card(
+        ui.card_header("Fills the card; try full screen"),
+        output_plotly("walk"),
+        full_screen=True,
+    ),
+)
+
+
+def server(input, output, session):
+    @render_plotly
+    def walk():
+        rng = random.Random(input.n())
+        y = list(accumulate(rng.gauss(0, 1) for _ in range(input.n())))
+        return go.Figure(go.Scatter(y=y, mode="lines"))
+
+
+app = App(app_ui, server)
+```
+
+Anything that is a `plotly.graph_objects.Figure` works, including what `plotly.express` builds (install `plotly[express]` for that).
+
+### Express
+
+```python
+import random
+from itertools import accumulate
+
+import plotly.graph_objects as go
+from shiny.express import input, ui
+
+from shiny_plotly import render_plotly
+
+ui.page_opts(fillable=True)
+
+with ui.sidebar():
+    ui.input_slider("n", "Points", 10, 500, 100)
+
+with ui.card(full_screen=True):
+
+    @render_plotly
+    def walk():
+        rng = random.Random(input.n())
+        y = list(accumulate(rng.gauss(0, 1) for _ in range(input.n())))
+        return go.Figure(go.Scatter(y=y, mode="lines"))
+```
+
+The decorator creates its own output placeholder in Express, just like `@render_widget` does.
+
+### Options
+
+```python
+@render_plotly(
+    height="300px",  # fixed height; default None fills the container
+    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
+)
+def sales(): ...
+```
+
+`None` from the render function empties the output. The function may be sync or async. It may also return `fig.to_dict()` instead of a `Figure`. Anything plotly's own encoder serializes is fine as trace data: numpy arrays, pandas columns, datetimes.
+
+### 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.
+
+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.
+
+```python
+@render_plotly
+def prices():
+    return px.line(frame(), x="date", y="close").update_layout(uirevision="prices")
+```
+
+### Migrating from shinywidgets
+
+| shinywidgets | shiny-plotly |
+| --- | --- |
+| `from shinywidgets import output_widget, render_widget` | `from shiny_plotly import output_plotly, render_plotly` |
+| `output_widget("id")` | `output_plotly("id")` |
+| `output_widget("id", height="300px")` | `output_plotly("id", height="300px")` |
+| `@render_widget` | `@render_plotly` |
+| (FigureWidget margins, applied implicitly) | `@render_plotly(figurewidget_margins=True)` |
+
+Three things change on purpose:
+
+- **Margins.** shinywidgets sets tight margins (`l=16, t=32, r=16, b=16`) on every FigureWidget; plotly's own defaults are `80/100/80/80`. `shiny-plotly` uses plotly's defaults unless you pass `figurewidget_margins=True`, which fills in only the sides your figure leaves unset. Set margins explicitly on the figure if you want something else.
+- **In-place mutation.** A `FigureWidget` you keep on the server and mutate (`fig.data[0].y = ...`, `fig.add_trace(...)` after render) is exactly what shinywidgets is for. `shiny-plotly` has no channel for that; return a new figure from the render function and let Shiny re-render. If your app depends on in-place widget updates, stay on shinywidgets for those outputs. Both packages can coexist in one app.
+- **Zoom across re-renders.** A mutated `FigureWidget` keeps the user's zoom because nothing replaces the figure. Here a re-render is a new figure, so plotly's `uirevision` decides: set `layout.uirevision` (see above) to keep the view.
+
+### Sizing
+
+The rules mirror `output_widget`:
+
+- `height=None` (default): the plot fills its container. Inside `ui.card(full_screen=True)`, a fillable page or a sidebar layout it grows and shrinks with the card, from a 400px basis. Outside a fill layout it is 400px tall.
+- `height="300px"` (on the decorator or on `output_plotly`): the plot is exactly that tall and opts out of filling.
+
+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
+
+`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.
+
+```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'});
+});
+"""
+
+
+@render_plotly(post_script=CLICK_TO_INPUT)
+def scatter(): ...
+
+
+@render.text
+def click_info():
+    if not input.clicked.is_set():
+        return "Click a point."
+    pt = input.clicked()
+    return f"x={pt['x']}, y={pt['y']}"
+```
+
+`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.
+
+### 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`.
+- `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.
+
+`render_plotly` needs `output_plotly`; it is an output binding, not a `render.ui`, so `ui.output_ui(id)` does not draw it.
+
+### plotly.js on the wire
+
+Shiny serves HTML dependencies from a plain static mount: no compression, no `Cache-Control`. `plotly.min.js` is 4.9 MB, so once the first session of a process has rendered a figure, `shiny-plotly` adds a route in front of that mount for the bundle's exact path (`/lib/plotly-<version>/plotly.min.js`) that serves it pre-compressed (brotli when the `brotli` package is installed, gzip otherwise; 1.2 MB or 1.5 MB on the wire) with `Cache-Control: public, max-age=31536000, immutable`, `Vary: Accept-Encoding` and an `ETag` per encoding. The URL is keyed by the plotly version, so a browser fetches each version once. Compression runs once per process, in a background thread; until it has finished the route serves the raw file with the same headers.
+
+```sh
+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.
+
+## Examples
+
+```sh
+uv run --with shiny-plotly shiny run examples/core_app.py
+uv run --with shiny-plotly shiny run examples/express_app.py
+```
+
+## Development
+
+```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 bench       # the shinywidgets comparison above, on this machine
+```
+
+`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.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

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

@@ -9,7 +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, plotly_js, render_plotly
+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 = """
@@ -41,7 +41,6 @@ app_ui = ui.page_sidebar(
         ui.card_header("Fixed height, click a point"),
         output_plotly("fixed_plot"),
     ),
-    plotly_js(),
     title="shiny-plotly",
     fillable=True,
 )
@@ -61,7 +60,8 @@ def server(input: Inputs, output: Outputs, session: Session):
             trace = go.Scatter(x=x, y=y, mode="lines")
         else:
             trace = go.Bar(x=x, y=y)
-        return go.Figure(trace).update_layout(title=f"{input.n()} points")
+        # uirevision keeps the zoom the user dragged across re-renders of the same kind.
+        return go.Figure(trace).update_layout(title=f"{input.n()} points", uirevision=input.kind())
 
     @render_plotly(figurewidget_margins=True)
     def compact_plot():

{shiny_plotly-0.1.0 → shiny_plotly-0.2.0}/examples/express_app.py

@@ -9,10 +9,9 @@ from itertools import accumulate
 import plotly.graph_objects as go
 from shiny.express import input, ui
 
-from shiny_plotly import plotly_js, render_plotly
+from shiny_plotly import render_plotly
 
 ui.page_opts(title="shiny-plotly (Express)", fillable=True)
-plotly_js()
 
 with ui.sidebar():
     ui.input_slider("n", "Points", min=10, max=500, value=100)

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

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shiny-plotly"
-version = "0.1.0"
-description = "Render plotly figures in Shiny for Python as plain HTML, without the shinywidgets layer."
+version = "0.2.0"
+description = "Render plotly figures in Shiny for Python with plain plotly.js, without the shinywidgets layer."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
@@ -31,6 +31,10 @@ dependencies = [
   "htmltools>=0.5",
 ]
 
+[project.optional-dependencies]
+# plotly.min.js is served brotli-compressed (about 15% smaller than gzip) when present.
+brotli = ["brotli>=1.1"]
+
 [project.urls]
 Homepage   = "https://github.com/rvben/shiny-plotly"
 Repository = "https://github.com/rvben/shiny-plotly"
@@ -38,6 +42,10 @@ Changelog  = "https://github.com/rvben/shiny-plotly/blob/main/CHANGELOG.md"
 Issues     = "https://github.com/rvben/shiny-plotly/issues"
 
 [dependency-groups]
+bench = [
+    "anywidget>=0.11.0",
+    "shinywidgets>=0.8.1",
+]
 dev = [
   "pytest>=8",
   "pytest-asyncio>=0.24",
@@ -45,6 +53,8 @@ dev = [
   "pyright>=1.1.380",
   "httpx2>=2.12.0",
   "pytest-playwright>=0.9.0",
+  "numpy>=1.26",
+  "brotli>=1.1",
 ]
 
 [tool.hatch.build.targets.wheel]
@@ -68,7 +78,7 @@ target-version = "py310"
 select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
 
 [tool.pyright]
-include = ["src", "tests", "examples"]
+include = ["src", "tests", "examples", "bench"]
 pythonVersion = "3.10"
 typeCheckingMode = "standard"
 

{shiny_plotly-0.1.0 → shiny_plotly-0.2.0}/src/shiny_plotly/_deps.py

@@ -19,9 +19,14 @@ def plotly_js() -> HTMLDependency:
     copied or written: the dependency points at ``plotly/package_data/plotly.min.js``,
     the exact bundle ``plotly.offline.get_plotlyjs()`` would inline.
 
-    Add it once to the page UI so the bundle loads with the page. Every figure rendered by
-    :func:`~shiny_plotly.render_plotly` or :func:`~shiny_plotly.fig_to_ui` also carries it,
-    so an output still works without the page-level call; htmltools de-duplicates.
+    Every :func:`~shiny_plotly.output_plotly` and every :func:`~shiny_plotly.fig_to_ui`
+    fragment carries it, so nothing needs to be added to the page for it; htmltools
+    de-duplicates. Add it to the page UI yourself only when the first figure is inserted
+    later (``ui.insert_ui``, a ``@render.ui`` that starts empty) and the bundle should load
+    with the page instead.
+
+    Once a session has rendered a figure, the bundle is served pre-compressed with an
+    immutable cache lifetime; see :mod:`shiny_plotly._serve`.
     """
     return HTMLDependency(
         name="plotly",
@@ -33,11 +38,12 @@ def plotly_js() -> HTMLDependency:
 
 def shiny_plotly_js() -> HTMLDependency:
     """
-    The small browser helper every rendered figure depends on.
+    The small browser helper every output and fragment depends on.
 
-    It keeps each graph sized to its container (plotly alone only reacts to window
-    resizes) and purges a graph once Shiny has replaced the output holding it, so
-    re-rendering outputs do not accumulate plotly state. It rides along with every
+    It holds the output binding for :func:`~shiny_plotly.output_plotly` (``Plotly.newPlot``
+    once, ``Plotly.react`` on every re-render), keeps each graph sized to its container
+    (plotly alone only reacts to window resizes) and purges a graph once it leaves the
+    document, so nothing accumulates plotly state. It rides along with every output and
     fragment; there is no need to add it to the page yourself.
     """
     return HTMLDependency(