feat: show matplotlib/Pillow images and add experimental SDL support

- Move Pyodide setup into src/runtime.js, shared by the worker and the
  new SDL runtime; Python helpers live in src/python and are installed
  into site-packages
- matplotlib: custom Agg backend (MPLBACKEND) posts figures as PNG to
  the console on plt.show(); unshown figures are shown when a run ends
- Pillow: Image.show() displays in the console
- Experimental SDL (pygame): programs with an async game loop run in a
  main-thread Pyodide drawing to a <canvas id="canvas"> in the console.
  SDL setup is checked with pygame.display.init() and any failure falls
  back to the worker. Keyboard input is limited to the canvas, Acode's
  document title is restored, and re-running or closing the console
  cancels the game
- Worker runs pygame headless (SDL_VIDEODRIVER=dummy): without a canvas
  Emscripten's SDL video crashed Pyodide fatally
- Handle Pyodide fatal errors: report them and restart Python on the
  next run instead of leaving the console stuck
- Hide "already loaded" package messages on every run

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

Author: bajrangCoder

README.md

@@ -27,6 +27,32 @@ import micropip
 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.
+
+### 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:
+
+```python
+import asyncio
+import pygame
+
+pygame.init()
+screen = pygame.display.set_mode((320, 240))
+
+async def main():
+    while True:
+        screen.fill((30, 30, 60))
+        pygame.display.flip()
+        await asyncio.sleep(1 / 60)
+
+await main()
+```
+
+If SDL cannot start, the program runs without a display. Running again or closing the console stops the game.
+
 ## Development
 
 ```sh

changelog.md

@@ -8,6 +8,9 @@
 - 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
+- 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
 - Smaller plugin size (removed stale Pyodide files)

esbuild.config.mjs

@@ -95,6 +95,8 @@ const buildConfig = {
 	entryPoints: {
 		main: "src/main.js",
 		worker: "src/worker.js",
+		// experimental SDL runtime, loaded on demand by main.js
+		sdl: "src/sdl.js",
 	},
 	bundle: true,
 	minify: true,
@@ -106,6 +108,8 @@ const buildConfig = {
 	outdir: "dist",
 	// Node-only imports inside Pyodide, never reached in the browser
 	external: ["node:*", "ws"],
+	// Python helpers installed into Pyodide's site-packages
+	loader: { ".py": "text" },
 	define: {
 		PYODIDE_VERSION: JSON.stringify(pyodideVersion),
 	},

plugin.zip

@@ -6,6 +6,11 @@ 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`
+const PYGAME_IMPORT = /^\s*(?:import|from)\s+pygame\b/m;
+const AWAIT = /\bawait\b/;
+
 class Python {
 	#worker;
 	#onInitError;
@@ -28,6 +33,7 @@ class Python {
 	#initPromise = Promise.resolve(false);
 	/** number of code runs still waiting for the worker */
 	#running = 0;
+	#sdlPromise = null;
 
 	INITIALIZING = 1;
 	INITIALIZED = 2;
@@ -47,6 +53,7 @@ class Python {
 
 		const onhide = $page.onhide;
 		$page.onhide = () => {
+			window.acodePythonSdl?.stop();
 			this.#state = this.NOT_INTIALIZED;
 			this.#worker?.terminate();
 			// runs on the terminated worker never reply
@@ -149,11 +156,75 @@ class Python {
 	}
 
 	async run() {
+		window.acodePythonSdl?.stop();
 		this.#showPage();
 		this.#inputCount = 0;
 		this.#append(this.$input);
 		await this.#cacheFile.writeFile("");
-		await this.runCode(editorManager.editor.getValue());
+
+		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;
+			}
+		}
+		await this.runCode(code);
+	}
+
+	/**
+	 * Runs a pygame program with the experimental SDL runtime.
+	 * @returns {Promise<boolean>} false if SDL is unavailable and the caller
+	 * should fall back to the worker
+	 */
+	async #runWithSdl(code) {
+		const $canvas = tag("canvas");
+		const $media = tag("div", { className: "py-media", children: [$canvas] });
+		this.#append($media, this.$input);
+		this.#running += 1;
+		this.#updateStatus();
+		try {
+			const sdl = await this.#loadSdl();
+			const error = await sdl.run(code, {
+				baseUrl: this.baseUrl,
+				canvas: $canvas,
+				stdout: (text) => this.print(text),
+				stderr: (text) => this.print(text, "error"),
+				showImage: (data) => this.#printImage(data),
+			});
+			if (error) this.print(error, "error");
+			return true;
+		} catch (error) {
+			$media.remove();
+			this.print(
+				`Experimental SDL support is unavailable (${error?.message ?? error}). Running without it, so pygame windows cannot be shown.`,
+				"info",
+			);
+			return false;
+		} finally {
+			this.#running = Math.max(0, this.#running - 1);
+			this.#updateStatus();
+		}
+	}
+
+	#loadSdl() {
+		this.#sdlPromise ??= new Promise((resolve, reject) => {
+			const $script = tag("script", { src: `${this.baseUrl}sdl.js` });
+			$script.onload = () => {
+				if (window.acodePythonSdl) resolve(window.acodePythonSdl);
+				else reject(new Error("sdl.js did not initialize"));
+			};
+			$script.onerror = () => reject(new Error("failed to load sdl.js"));
+			document.head.append($script);
+		}).catch((error) => {
+			this.#sdlPromise = null;
+			throw error;
+		});
+		return this.#sdlPromise;
 	}
 
 	async terminal() {
@@ -199,6 +270,7 @@ class Python {
 
 		this.$wrapBtn?.remove();
 		this.$status?.remove();
+		window.acodePythonSdl?.stop();
 		this.#worker?.terminate();
 		editorManager.off("switch-file", this.checkRunnable.bind(this));
 		editorManager.off("rename-file", this.checkRunnable.bind(this));
@@ -234,6 +306,15 @@ class Python {
 		this.#append($output, this.$input);
 	}
 
+	#printImage(data) {
+		if (!this.$page.isConnected) return;
+		const $img = tag("img", { src: `data:image/png;base64,${data}` });
+		this.#append(
+			tag("div", { className: "py-media", children: [$img] }),
+			this.$input,
+		);
+	}
+
 	#showPage() {
 		const $main = this.$page.get(".main");
 		if (!this.$page.isConnected) {
@@ -286,6 +367,20 @@ class Python {
 				this.print(text);
 				break;
 
+			case "image":
+				this.#printImage(e.data.data);
+				break;
+
+			case "fatal":
+				// Python cannot recover; restart it on the next run
+				this.#worker?.terminate();
+				this.#state = this.NOT_INTIALIZED;
+				this.#isInput = false;
+				this.#onRunError?.(
+					`Python crashed (${error}). It will restart on the next run.`,
+				);
+				break;
+
 			case "stderr":
 				this.print(text, "error");
 				break;

src/main.js

@@ -0,0 +1,53 @@
+"""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.
+"""
+
+import base64
+import io
+import sys
+
+from _acode import show_image
+
+_pil_ready = False
+
+
+def show_png(data):
+    show_image(base64.b64encode(data).decode("ascii"))
+
+
+def prepare(code):
+    """Called before running ``code``, after its packages are loaded."""
+    from pyodide.code import find_imports
+
+    if "PIL" in find_imports(code):
+        setup_pil()
+
+
+def setup_pil():
+    """Make ``Image.show()`` display the image in the console."""
+    global _pil_ready
+    if _pil_ready:
+        return
+
+    from PIL import ImageShow
+
+    class AcodeViewer(ImageShow.Viewer):
+        format = "PNG"
+
+        def show_image(self, image, **options):
+            buffer = io.BytesIO()
+            image.save(buffer, format="PNG")
+            show_png(buffer.getvalue())
+            return 1
+
+    ImageShow.register(AcodeViewer(), 0)
+    _pil_ready = True
+
+
+def flush_figures():
+    """Show matplotlib figures the code created but never showed."""
+    pyplot = sys.modules.get("matplotlib.pyplot")
+    if pyplot is not None and pyplot.get_fignums():
+        pyplot.show()

src/python/acode_display.py

@@ -0,0 +1,20 @@
+"""Matplotlib backend that renders figures with Agg and shows them as PNG
+images in the Acode console. Selected with MPLBACKEND=module://acode_mpl_backend.
+"""
+
+import io
+
+from matplotlib._pylab_helpers import Gcf
+from matplotlib.backends.backend_agg import FigureCanvasAgg as FigureCanvas
+
+from acode_display import show_png
+
+__all__ = ["FigureCanvas", "show"]
+
+
+def show(*args, **kwargs):
+    for manager in Gcf.get_all_fig_managers():
+        buffer = io.BytesIO()
+        manager.canvas.figure.savefig(buffer, format="png", bbox_inches="tight")
+        show_png(buffer.getvalue())
+    Gcf.destroy_all()