feat: run blocking pygame loops and render plots for the console

pygame:
- Ordinary blocking game loops now use SDL mode: with JSPI, the calls a
  game loop makes (display.flip/update, Clock.tick, time.wait/delay,
  event.wait) pause via run_sync so the browser can draw and Acode stays
  responsive (python/acode_pygame.py)
- Check JSPI inside a task before running a blocking loop; without it,
  fall back with an explanation instead of freezing Acode
- Stop blocking loops through a flag checked at those pauses, since
  they never reach an await; stopped runs no longer print into the next
  console
- Explain the worker's "dummy not available" error

Images:
- Default matplotlib figure size to the console width (via the
  matplotlibrc read on first import), so text stays readable on phones
- Render at the device pixel ratio and display at true size, so plots
  are sharp on HiDPI screens

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: bajrangCoder

README.md

@@ -29,29 +29,26 @@ await micropip.install("snowballstemmer")
 
 ### Plots and images
 
-`matplotlib` figures are shown in the console when you call `plt.show()`, and any figures left open are shown when the program ends. Pillow's `Image.show()` works too.
+`matplotlib` figures are shown in the console when you call `plt.show()`, and any figures left open are shown when the program ends. Figures default to the width of the console and are rendered at the screen's pixel density. Pillow's `Image.show()` works too.
 
 ### pygame (experimental)
 
-pygame programs can draw to a canvas in the console using Pyodide's [SDL support](https://pyodide.org/en/stable/usage/sdl.html). The game loop must be async so the app stays responsive:
+pygame programs can draw to a canvas in the console using Pyodide's [SDL support](https://pyodide.org/en/stable/usage/sdl.html). Ordinary game loops work as written:
 
 ```python
-import asyncio
 import pygame
 
 pygame.init()
-screen = pygame.display.set_mode((320, 240))
+screen = pygame.display.set_mode((1280, 720))
+clock = pygame.time.Clock()
 
-async def main():
-    while True:
-        screen.fill((30, 30, 60))
-        pygame.display.flip()
-        await asyncio.sleep(1 / 60)
-
-await main()
+while True:
+    screen.fill("purple")
+    pygame.display.flip()
+    clock.tick(60)
 ```
 
-If SDL cannot start, the program runs without a display. Running again or closing the console stops the game.
+This needs a WebView with JSPI support (Android System WebView 137+), which lets the loop pause at `display.flip()` / `Clock.tick()` so the app stays responsive. On older WebViews, use an async loop (`await asyncio.sleep(0)` each frame) instead. If SDL cannot start, the program runs without a display. Running again or closing the console stops the game.
 
 ## Development
 

changelog.md

@@ -8,8 +8,8 @@
 - Console output can now be selected and copied
 - Header button to toggle line wrap in the console (remembered between sessions)
 - Thin progress line under the console header while Python loads or code is running
-- matplotlib plots are shown in the console (`plt.show()`, or automatically at the end of a run), as are Pillow `Image.show()` images
-- Experimental SDL support: pygame programs with an async game loop draw to a canvas in the console, falling back to running without a display if SDL cannot start
+- matplotlib plots are shown in the console (`plt.show()`, or automatically at the end of a run), as are Pillow `Image.show()` images. Plots are sized to the console and rendered sharp on high-density screens
+- Experimental SDL support: pygame programs draw to a canvas in the console, including ordinary blocking game loops on WebViews with JSPI. Falls back to running without a display if SDL cannot start
 - Python crashes no longer leave the console stuck; Python restarts on the next run
 - Fixed Python failing to load (or staying on "loading...") on some devices
 - Clear error message when Python fails to load, with automatic retry on the next run

plugin.zip

@@ -6,10 +6,8 @@ const WRAP_KEY = `${plugin.id}.wrap`;
 const WRAP_ICON =
 	'<svg viewBox="0 0 24 24" width="1em" height="1em" fill="currentColor" aria-hidden="true"><path d="M4 19h6v-2H4v2zM20 5H4v2h16V5zm-3 6H4v2h13.25c1.1 0 2 .9 2 2s-.9 2-2 2H15v-2l-3 3 3 3v-2h2c2.21 0 4-1.79 4-4s-1.79-4-4-4z"/></svg>';
 
-// pygame programs use the experimental SDL runtime on the main thread, which
-// is only safe when their game loop yields with `await`
+// pygame programs use the experimental SDL runtime on the main thread
 const PYGAME_IMPORT = /^\s*(?:import|from)\s+pygame\b/m;
-const AWAIT = /\bawait\b/;
 
 class Python {
 	#worker;
@@ -163,16 +161,7 @@ class Python {
 		await this.#cacheFile.writeFile("");
 
 		const code = editorManager.editor.getValue();
-		if (PYGAME_IMPORT.test(code)) {
-			if (!AWAIT.test(code)) {
-				this.print(
-					"Tip: pygame needs an async game loop (await asyncio.sleep(0) each frame) to show its window with the experimental SDL support.",
-					"info",
-				);
-			} else if (await this.#runWithSdl(code)) {
-				return;
-			}
-		}
+		if (PYGAME_IMPORT.test(code) && (await this.#runWithSdl(code))) return;
 		await this.runCode(code);
 	}
 
@@ -194,7 +183,8 @@ class Python {
 				canvas: $canvas,
 				stdout: (text) => this.print(text),
 				stderr: (text) => this.print(text, "error"),
-				showImage: (data) => this.#printImage(data),
+				showImage: (data, scale) => this.#printImage(data, scale),
+				...this.#displaySize(),
 			});
 			if (error) this.print(error, "error");
 			return true;
@@ -239,6 +229,7 @@ class Python {
 			this.#worker.postMessage({
 				action: "run",
 				code,
+				...this.#displaySize(),
 			});
 			const res = await new Promise((resolve, error) => {
 				this.#onRunSuccess = resolve;
@@ -306,9 +297,30 @@ class Python {
 		this.#append($output, this.$input);
 	}
 
-	#printImage(data) {
+	/** Console width (CSS px) and pixel ratio, so figures fit and stay sharp */
+	#displaySize() {
+		const $main = this.$page.get(".main");
+		const style = $main && getComputedStyle($main);
+		const padding = style
+			? Number.parseFloat(style.paddingLeft) +
+				Number.parseFloat(style.paddingRight)
+			: 0;
+		return {
+			width: Math.max(0, ($main?.clientWidth ?? 0) - padding),
+			pixelRatio: window.devicePixelRatio || 1,
+		};
+	}
+
+	/**
+	 * Shows a PNG rendered at `scale` times its display size at its true
+	 * size, so it is sharp on HiDPI screens instead of upscaled.
+	 */
+	#printImage(data, scale = 1) {
 		if (!this.$page.isConnected) return;
 		const $img = tag("img", { src: `data:image/png;base64,${data}` });
+		$img.onload = () => {
+			$img.style.width = `${$img.naturalWidth / scale}px`;
+		};
 		this.#append(
 			tag("div", { className: "py-media", children: [$img] }),
 			this.$input,
@@ -368,7 +380,7 @@ class Python {
 				break;
 
 			case "image":
-				this.#printImage(e.data.data);
+				this.#printImage(e.data.data, e.data.scale);
 				break;
 
 			case "fatal":

src/main.js

@@ -1,30 +1,63 @@
 """Shows images from Python code in the Acode console.
 
 Installed into site-packages by the plugin. ``show_image`` is provided by the
-plugin as the ``_acode`` JS module and receives base64 encoded PNG data.
+plugin as the ``_acode`` JS module and receives base64 encoded PNG data plus
+the scale it was rendered at.
 """
 
 import base64
 import io
+import os
 import sys
 
 from _acode import show_image
 
 _pil_ready = False
 
+# device pixel ratio of the console, figures are rendered at this scale
+scale = 1.0
 
-def show_png(data):
-    show_image(base64.b64encode(data).decode("ascii"))
 
+def show_png(data, image_scale=1.0):
+    show_image(base64.b64encode(data).decode("ascii"), image_scale)
 
-def prepare(code):
-    """Called before running ``code``, after its packages are loaded."""
+
+def prepare(code, width=0, pixel_ratio=1):
+    """Called before running ``code``, after its packages are loaded.
+
+    ``width`` is the console width in CSS pixels, ``pixel_ratio`` the
+    device pixel ratio.
+    """
     from pyodide.code import find_imports
 
+    global scale
+    scale = max(1.0, min(float(pixel_ratio or 1), 3.0))
+    if width:
+        _fit_figures(width)
+
     if "PIL" in find_imports(code):
         setup_pil()
 
 
+def _fit_figures(width):
+    """Default matplotlib figures to the console width, so their text stays
+    readable on a phone instead of a 6.4in figure being shrunk to fit.
+
+    Written as the matplotlibrc read when matplotlib is first imported (also
+    when imported indirectly, e.g. by pandas), so settings changed later by
+    the program are left alone.
+    """
+    if "matplotlib" in sys.modules:
+        return
+    rc_file = os.environ.get("MATPLOTLIBRC")
+    if not rc_file:
+        return
+    inches = max(3.0, min(width / 100, 6.4))
+    with open(rc_file, "w") as rc:
+        rc.write(f"figure.figsize: {inches:.2f}, {inches * 0.75:.2f}\n")
+        rc.write("figure.dpi: 100\n")
+
+
 def setup_pil():
     """Make ``Image.show()`` display the image in the console."""
     global _pil_ready

src/python/acode_display.py

@@ -7,14 +7,19 @@
 from matplotlib._pylab_helpers import Gcf
 from matplotlib.backends.backend_agg import FigureCanvasAgg as FigureCanvas
 
-from acode_display import show_png
+import acode_display
 
 __all__ = ["FigureCanvas", "show"]
 
 
 def show(*args, **kwargs):
+    scale = acode_display.scale
     for manager in Gcf.get_all_fig_managers():
+        figure = manager.canvas.figure
         buffer = io.BytesIO()
-        manager.canvas.figure.savefig(buffer, format="png", bbox_inches="tight")
-        show_png(buffer.getvalue())
+        # render at the device pixel ratio so plots stay sharp on HiDPI screens
+        figure.savefig(
+            buffer, format="png", bbox_inches="tight", dpi=figure.dpi * scale
+        )
+        acode_display.show_png(buffer.getvalue(), scale)
     Gcf.destroy_all()

src/python/acode_mpl_backend.py

@@ -0,0 +1,110 @@
+"""Lets ordinary blocking pygame loops run on the browser's main thread.
+
+A ``while running: ... clock.tick(60)`` loop never returns control to the
+browser, so nothing would be drawn and Acode would freeze. With JavaScript
+Promise Integration (JSPI) Python can pause on an awaitable, so the calls every
+game loop makes (display.flip/update, Clock.tick, time.wait/delay, event.wait)
+pause briefly and let the browser draw. Those pauses are also where a running
+game is stopped, since a blocking loop never reaches an ``await``.
+"""
+
+import asyncio
+import time
+
+import pygame
+from pyodide.ffi import can_run_sync, run_sync
+
+_installed = False
+_stop_requested = False
+
+
+class StopProgram(BaseException):
+    """Raised inside the game loop when the console stops the program."""
+
+
+def reset():
+    global _stop_requested
+    _stop_requested = False
+
+
+def request_stop():
+    global _stop_requested
+    _stop_requested = True
+
+
+def _pause(seconds=0):
+    if _stop_requested:
+        raise StopProgram
+    if can_run_sync():
+        run_sync(asyncio.sleep(seconds))
+    if _stop_requested:
+        raise StopProgram
+
+
+def install():
+    global _installed
+    if _installed:
+        return
+    _installed = True
+
+    display = pygame.display
+    original_flip = display.flip
+    original_update = display.update
+
+    def flip():
+        original_flip()
+        _pause()
+
+    def update(*args, **kwargs):
+        original_update(*args, **kwargs)
+        _pause()
+
+    display.flip = flip
+    display.update = update
+
+    original_clock = pygame.time.Clock
+
+    class Clock:
+        """pygame.time.Clock whose tick() waits without blocking the page."""
+
+        def __init__(self):
+            self._clock = original_clock()
+            self._last = time.perf_counter()
+
+        def tick(self, framerate=0):
+            if framerate:
+                delay = 1 / framerate - (time.perf_counter() - self._last)
+                _pause(max(delay, 0))
+            self._last = time.perf_counter()
+            return self._clock.tick()
+
+        tick_busy_loop = tick
+
+        def __getattr__(self, name):
+            return getattr(self._clock, name)
+
+    pygame.time.Clock = Clock
+    if hasattr(pygame, "Clock"):
+        pygame.Clock = Clock
+
+    def wait(milliseconds):
+        start = time.perf_counter()
+        _pause(milliseconds / 1000)
+        return int((time.perf_counter() - start) * 1000)
+
+    pygame.time.wait = wait
+    pygame.time.delay = wait
+
+    original_poll = pygame.event.poll
+
+    def event_wait(timeout=0):
+        start = time.perf_counter()
+        while True:
+            event = original_poll()
+            if event.type != pygame.NOEVENT:
+                return event
+            if timeout and (time.perf_counter() - start) * 1000 >= timeout:
+                return event
+            _pause(0.01)
+
+    pygame.event.wait = event_wait