[cpsievert]

Stacked on #324 (@render_pythreejs), on top of #356 (shared, process-global widgets; replacement for the auto-merged #351), #346 (browser-created widget comms), and #343 (generic AMD-externals resolution). This PR adds the ipyvolume renderer; its dependency machinery lives in #343 and its shared-widget handling in #356. Merge order: #343 → #346 → #356 → #324 → this PR. Part of #278.

Add @render_ipyvolume for ipyvolume 3D plots

ipyvolume is the classic Jupyter 3D plotting package (scatter, quiver, volume rendering). With this PR, Shiny apps can render ipyvolume figures reactively — the WebGL canvas fills (and resizes with) its container, and camera state and selections round-trip to Python:

import ipyvolume as ipv
import numpy as np
from shiny import App, ui
from shinywidgets import output_widget, render_ipyvolume

app_ui = ui.page_fillable(output_widget("plot"))

def server(input, output, session):
    @render_ipyvolume
    def plot():
        x, y, z = np.random.normal(size=(3, 1000))
        ipv.quickscatter(x, y, z, size=1, marker="sphere")
        return ipv.gcf()

app = App(app_ui, server)

Requires pip install 'shinywidgets[ipyvolume]' (the extra also installs ipython_genutils, which ipyvolume 0.6.3 — the latest release, from 2023 — imports but doesn't declare).

Both ways of building a figure work, including in outputs that re-render:

• The pylab API: ipv.quickscatter(...), or ipv.figure() plus drawing calls — return ipv.gcf() (or the object quickscatter()/gcc() returns, which is unwrapped to its figure).
• Direct construction: ipv.Figure() with ipv.widgets.Scatter and friends added to fig.scatters. Set size_selected/color_selected explicitly on scatters (their trait defaults are 0-d numpy arrays, which don't JSON-serialize; pylab sets them for you) and set fig.xlim/ylim/zlim (directly constructed figures default to a [0, 1]³ axis box with no auto-fit).

Interaction state round-trips to Python: orbit/zoom camera state via reactive_read(), and rectangle/lasso selections via fig.on_selection(fn) (selections arrive as custom messages, not trait changes, and the payload is a pixel/device region, not selected indices).

Sizing

A figure's width/height traits are its WebGL canvas size in pixels, with no built-in fit-to-container behavior, so a WIDGET_BEHAVIORS entry (js) drives the canvas from the container through those traits (throttled ResizeObservers on the output and the widget view, minus toolbar height; the measured size round-trips to Python). Explicit sizes are always respected:

• The two "default" sizes (the 500x400 trait default and the 400x500 ipv.figure() always passes) are treated as unset, as is a size matching the last browser sync (so redisplaying a cached figure still fills).
• An explicit ipv.figure(width=..., height=...) keeps its pixel size, even inside an output_widget(height=...).
• output_widget(height=...) sizes the canvas to the output.
• A widget Layout(height=...) — including viewport-relative values like "50vh" — sizes the canvas to the widget view.

Implementation notes

• Shared ipyvue/ipyvuetify widgets come from feat: share process-global widgets across sessions and re-renders (#348) #351. import ipyvolume constructs module-level singleton widgets (ipyvue's force_load_instance, ipyvuetify's theme), and pylab's never-rendered Container uses ipyvue Template widgets that are shared across the whole process. feat: share process-global widgets across sessions and re-renders (#348) #351 treats these as process-global widgets (tolerated at import time, mirrored into every session, never closed by render cleanup), so this PR needs no ipyvolume-specific workaround: apps can import ipyvolume at module level, and pylab figures re-render cleanly across re-renders and sessions.
• require.js externals (from feat: resolve widget bundles' AMD externals generically #343). ipyvolume's and pythreejs's AMD bundles each declare an external three but ship incompatible three.js builds, and an ipyvolume figure needs both (its scene/camera are pythreejs widgets); jupyter-vuetify's bundle similarly externalizes jupyter-vue. The generic resolution in feat: resolve widget bundles' AMD externals generically #343 parses the bundles' define([...]) headers at render time and maps/shims those externals per-module — without it, require.js requests /three.js at the app root (404) and the figure never renders.
• ipywidgets 8. ipyvolume 0.6.3 works with the repo's ipywidgets 8.1+ floor and the bundled @jupyter-widgets/html-manager 1.0.

Caveats

• ipyvolume's FigureView.remove() never calls renderer.dispose(), so WebGL contexts leak per re-render (upstream; unmaintained since 2023) — the same theme as k3d/ipysigma in docs/widget-reports/.
• Rough benchmark (base64 buffer transport, page load → first composited frame, headless Chromium): ~10k float32 points ~1.6 s; ~100k points ~8.5 s. Transport isn't the bottleneck at 10k but dominates at 100k. (Measured with direct construction.)

Verification

• make check-format and make pyright (0 errors) on this head
• js/src and the committed shinywidgets/static/output.js are byte-identical to the previously verified head of this PR (where cd js && yarn build reproduced the bundle)
• Unit tests and the Playwright suites (tests/playwright/render_ipyvolume: rendering, fill, explicit sizing, selection + camera round trips; tests/playwright/render_ipyvolume_rerender: re-render lifecycle over the pylab API, old models closed) are left to CI on this head

Testing notes for future widget work: WebGL renders fine in headless Chromium (SwiftShader), and tests assert composited screenshot pixels since WebGL canvases can't be read back; clicks that land while the main thread is busy with WebGL setup can sit in the renderer's event queue for a long time, so tests wait for the first frame before interacting.

[Copilot]

🔵 Needs a closer look

Auto-height widget layouts can bypass explicit output sizing and leave the canvas clipped.

2 open issues

• Resize canvas when explicit view layout dimensions change
• Preserve explicit figure dimensions with CSS output height

1 previously missed issue

In code that hasn't changed since last review

Exclude auto layout height from intrinsic view measurement

js/​src/​ipyvolume.ts:47

With output_widget(height="250px") and Layout(height="auto"), this treats the auto-height view as explicitly sized and measures its intrinsic height instead of the 250px output. The canvas therefore retains its default height and overflows or is clipped, even though set_layout_defaults() treats "auto" as unset. Exclude intrinsic sizing keywords when deciding whether to measure the view, add a regression case combining an explicit output height with an auto Layout height, and regenerate shinywidgets/static/output.js.

1 resolved since last review

• Guard jupyter-vue mapping in CDN-only mode

_{Review effort: Balanced}