pygfx · Vipitis · Sep 16, 2025 · Sep 16, 2025 · Sep 17, 2025 · Sep 17, 2025
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -40,6 +40,7 @@ jobs:
 
   docs:
     name: Docs
+    needs: [release]
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -48,11 +49,21 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: 3.12
+        python-version: 3.12    
     - name: Install dev dependencies
       run: |
         python -m pip install --upgrade pip
         pip install -U -e .[docs]
+    - name: Download assets
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist
+    - name: move wheel into static
+      run: |
+        mkdir -p docs/static
+        mv dist/* docs/static
+        ls -la docs/static
     - name: Build docs
       run: |
         cd docs

diff --git a/docs/backends.rst b/docs/backends.rst
@@ -46,7 +46,12 @@ The table below gives an overview of the names in the different ``rendercanvas``
           | ``loop``
         - | Create a standalone canvas using wx, or
           | integrate a render canvas in a wx application.
-
+    *   - ``html``
+        - | ``HTMLRenderCanvas`` (toplevel)
+          | ``RenderCanvas`` (alias)
+          | ``loop`` (an ``AsyncioLoop``)
+        - | A canvas that runs in a web browser, using Pyodide.
+
 
 There are also three loop-backends. These are mainly intended for use with the glfw backend:
 
@@ -168,7 +173,7 @@ Alternatively, you can select the specific qt library to use, making it easy to
     loop.run()  # calls app.exec_()
 
 
-It is technically possible to e.g. use a ``glfw`` canvas with the Qt loop. However, this is not recommended because Qt gets confused in the precense of other windows and may hang or segfault.
+It is technically possible to e.g. use a ``glfw`` canvas with the Qt loop. However, this is not recommended because Qt gets confused in the presence of other windows and may hang or segfault.
 But the other way around, running a Qt canvas in e.g. the trio loop, works fine:
 
 .. code-block:: py
@@ -264,6 +269,47 @@ subclass implementing a remote frame-buffer. There are also some `wgpu examples
 
     canvas  # Use as cell output
 
+Support for HTMLCanvas in Pyodide
+---------------------------------
+When RenderCanvas runs in the browser using Pyodide the auto backend selects ``rendercanvas.html.HTMLRenderCanvas`` class.
+It expects a HTMLCanvasElement to be present in the DOM. It requires no additional dependencies, as rendercanvas can be installed from micropip.
+
+.. code-block:: html
+
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <script src="https://cdn.jsdelivr.net/pyodide/v0.28.2/full/pyodide.js"></script>
+    </head>
+    <body>
+    ...
+    <canvas id="canvas" width="640" height="480"></canvas>
+    <script type="text/javascript">
+        async function main(){
+            pythonCode = `
+                # Use python script as normally
+                from rendercanvas.auto import RenderCanvas, loop
+                canvas = RenderCanvas(title="Example")
-                canvas = RenderCanvas(title="Example")
+                canvas_el = document.getElementById("canvas")
+                canvas = RenderCanvas(canvas_el, title="Example")
-                canvas = RenderCanvas(title="Example")
+                canvas_el = document.getElementById("canvas")
+                canvas = RenderCanvas(canvas_el, title="Example")
+                context = canvas.get_context("bitmap")
+                bitmap = memoryview(b"HTMLRenderCanvas"[::-1]).cast("B", shape=(2, 2, 4))
+                context.set_bitmap(bitmap)
+                canvas.force_draw()
+            `
+        // load Pyodide and install Rendercanvas
+        let pyodide = await loadPyodide();
+        await pyodide.loadPackage("micropip");
+        const micropip = pyodide.pyimport("micropip");
+        await micropip.install("rendercanvas");
+        // have to call as runPythonAsync
+        pyodide.runPythonAsync(pythonCode);
+        }
+    main();
+    </script>
+    </body>
+    </html>
+
+
+Currently only presenting a bitmap is supported, as shown in the examples :doc:`noise.py <gallery/noise>` and :doc:`snake.py <gallery/snake>`.
 
 
 .. _env_vars:

diff --git a/docs/conf.py b/docs/conf.py
@@ -22,8 +22,8 @@
 
 # Load wglibu so autodoc can query docstrings
 import rendercanvas  # noqa: E402
-import rendercanvas.stub  # noqa: E402 - we use the stub backend to generate doccs
-import rendercanvas._context  # noqa: E402 - we use the ContexInterface to generate doccs
+import rendercanvas.stub  # noqa: E402 - we use the stub backend to generate docs
+import rendercanvas._context  # noqa: E402 - we use the ContextInterface to generate docs
 import rendercanvas.utils.bitmappresentadapter  # noqa: E402
 
 # -- Project information -----------------------------------------------------

diff --git a/docs/contextapi.rst b/docs/contextapi.rst
@@ -24,7 +24,7 @@ then present the result to the screen. For this, the canvas provides one or more
                 └─────────┘               └────────┘
 
 This means that for the context to be able to present to any canvas, it must
-support *both* the 'image' and 'screen' present-methods. If the context prefers
+support *both* the 'bitmap' and 'screen' present-methods. If the context prefers
 presenting to the screen, and the canvas supports that, all is well. Similarly,
 if the context has a bitmap to present, and the canvas supports the
 bitmap-method, there's no problem.
@@ -44,7 +44,7 @@ on the CPU. All GPU API's have ways to do this.
                          download from gpu to cpu
 
 If the context has a bitmap to present, and the canvas only supports presenting
-to screen, you can usse a small utility: the ``BitmapPresentAdapter`` takes a
+to screen, you can use a small utility: the ``BitmapPresentAdapter`` takes a
 bitmap and presents it to the screen.
 
 .. code-block::
@@ -58,7 +58,7 @@ bitmap and presents it to the screen.
 
 This way, contexts can be made to work with all canvas backens.
 
-Canvases may also provide additionaly present-methods. If a context knows how to
+Canvases may also provide additionally present-methods. If a context knows how to
 use that present-method, it can make use of it. Examples could be presenting
 diff images or video streams.
 

diff --git a/docs/start.rst b/docs/start.rst
@@ -79,12 +79,12 @@ Async
 A render canvas can be used in a fully async setting using e.g. Asyncio or Trio, or in an event-drived framework like Qt.
 If you like callbacks, ``loop.call_later()`` always works. If you like async, use ``loop.add_task()``. Event handlers can always be async.
 
-If you make use of async functions (co-routines), and want to keep your code portable accross
+If you make use of async functions (co-routines), and want to keep your code portable across
 different canvas backends, restrict your use of async features to ``sleep``  and ``Event``;
-these are the only features currently implemened in our async adapter utility.
+these are the only features currently implemented in our async adapter utility.
 We recommend importing these from :doc:`rendercanvas.utils.asyncs <utils_asyncs>` or use ``sniffio`` to detect the library that they can be imported from.
 
-On the other hand, if you know your code always runs on the asyncio loop, you can fully make use of ``asyncio``. Dito for Trio.
+On the other hand, if you know your code always runs on the asyncio loop, you can fully make use of ``asyncio``. Ditto for Trio.
 
 If you use Qt and get nervous from async code, no worries, when running on Qt, ``asyncio`` is not even imported. You can regard most async functions
 as syntactic sugar for pieces of code chained with ``call_later``. That's more or less how our async adapter works :)

diff --git a/docs/static/_pyodide_iframe.html b/docs/static/_pyodide_iframe.html
@@ -0,0 +1,35 @@
+<!doctype html>
+<html>
+<head>
+    <!-- Interactive HTMLRenderCanvas via Pyodide:<br> -->
+    <script src="https://cdn.jsdelivr.net/pyodide/v0.28.2/full/pyodide.js"></script>
+</head>
+<body>
+<canvas id="canvas" width="640" height="480" style="background-color: red;"></canvas><br>
+<!-- TODO: redirect stdout prints into something visible without console? -->
+<script type="text/javascript">
+    async function main(){
+        let example_name = window.parent.location.href.split("/").slice(-1)[0].split("#").splice(0)[0].replace(".html", "");
+        // TODO: get the script from docs dir? docs/gallery/script.py or the .zip?
+        // for now get the example from main because the local example is hidden behind a hash in _downloads/hash/example_name.py (but it still exists)
+        pythonCode = await (await fetch(`https://raw.githubusercontent.com/pygfx/rendercanvas/refs/heads/main/examples/${example_name}.py`)).text();
+        let pyodide = await loadPyodide();
+        await pyodide.loadPackage("micropip");
+        const micropip = pyodide.pyimport("micropip");
+        await micropip.install('numpy'); // can we figure out if we need it, or do we always get it?
+
+        // TODO: learn js to implement the other options...
+        // so we should get the rendercanvas wheel from three locations:
+        // 1) local wheel from ../dist/*whl? (for local development)
+        // 2) from the CI artefacts (moves into _static in the job) (for PR branch)
+        // 3) latest from pypi, when the artefacts are gone - for like stable/main?
+        // await micropip.install('rendercanvas');
+        await micropip.install('rendercanvas-2.2.1-py3-none-any.whl'); // from html/_static/ dir like a PR branch doc build...
+
+        // Run the Python code async because some calls are async it seems.
+        pyodide.runPythonAsync(pythonCode);
+    }
+    main();
+</script>
+</body>
+</html>
diff --git a/docs/static/custom.css b/docs/static/custom.css
@@ -1,4 +1,9 @@
 div.sphx-glr-download,
 div.sphx-glr-download-link-note {
     display: none;
+}
+div.document iframe {
+    width: 100%;
+    height: 500px; 
+    border: none;
 }
diff --git a/examples/events.py b/examples/events.py
@@ -19,3 +19,16 @@ def process_event(event):
 
 if __name__ == "__main__":
     loop.run()
+
+# %%
+#
+# .. only:: html
+#
+#     Interactive example
+#     ===================
+#     There is no visible canvas, but events will get printed to your browsers console.
+#
+#     .. raw:: html
+#
+#         <iframe src="../_static/_pyodide_iframe.html"></iframe>
+#
diff --git a/examples/local_browser.html b/examples/local_browser.html
@@ -0,0 +1,80 @@
+<!-- adapted from: https://traineq.org/imgui_bundle_online/projects/min_bundle_pyodide_app/demo_heart.source.txt -->
+<!doctype html>
+<html>
+<head>
+    RenderCanvas HTML canvas via Pyodide:<br>
+    <script src="https://cdn.jsdelivr.net/pyodide/v0.28.2/full/pyodide.js"></script>
+ <style>
+        /* so the demo page can have interactive resizing */
+        #canvas {
+            position: absolute;
+            width: 90%;
+            height: 90%;
+        }
+    </style>
+</head>
+<body>
+<!-- WIP: make it more of a "Playground"? -->
+<select id="example-select">
+    <option value="events.py">events.py</option>
+    <option value="noise.py">noise.py</option>
+    <option value="snake.py">snake.py</option>
+</select>
+<!-- maybe something like add example (to test spawning more canvases and also closing them?) -->
+<button id="reload-example">Reload example</button>
+<button id="reload-page" style="background-color: orange;"onclick="location.reload();">Reload page</button>
+<select id="lib-path">
+    <option value="../dist/rendercanvas-2.2.1-py3-none-any.whl" selected>local ./dist/</option>
+    <option value="rendercanvas">latest PyPI</option>
+</select>
+<input type="checkbox" id="load-wgpu">Load WebGPU (experimental)</input>
+<br>
+<!-- maybe wrap in a div so content after it still shows? -->
+<canvas id="canvas" style="background-color: lightgrey;"></canvas><br>
+some text below the canvas!
+<!-- TODO: redirect the Python stdout/stderr to some kind of text box at the bottom -->
+<script type="text/javascript">
+
+    async function loadPythonExample(example_path){
+        let response = await fetch(example_path);
+        let pythonCode = await response.text();
+        return pythonCode;
+    }
+
+    async function main(){
+
+        // fetch the file locally for easier scripting
+        // start chrome --allow-file-access-from-files %cd%\examples\local_browser.html or local webserver
+        // TODO: replace the actual code here (unless you have the module)
+        let example_select = document.getElementById("example-select");
+        let reload_example_button = document.getElementById("reload-example");
+        pythonCode = await (await fetch(example_select.value)).text();
+
+        // Load Pyodide
+        let pyodide = await loadPyodide();
+
+        await pyodide.loadPackage("micropip");
+        const micropip = pyodide.pyimport("micropip");
+        await micropip.install('numpy');
+        // await micropip.install('rendercanvas');
+        await micropip.install('../dist/rendercanvas-2.2.1-py3-none-any.whl'); // local wheel for auto testing
+
+        // Run the Python code async because some calls are async it seems.
+        pyodide.runPythonAsync(pythonCode);
+
+        // on click, we reload the example (or a difference one)
+        reload_example_button.onclick = async function() {
+            // interrupt existing code?
+            // sounds complex: https://pyodide.org/en/stable/usage/keyboard-interrupts.html
+            pyodide.setInterruptBuffer([2]);
+            pyodide.setInterruptBuffer([2]);
+
+            let example_file = example_select.value;
+            pythonCode = await (await fetch(example_file)).text();
+            pyodide.runPythonAsync(pythonCode);
+        };
+    }
+    main();
+</script>
+</body>
+</html>