hyperbook 0.91.1 → 0.93.0

package/dist/assets/directive-pyide/client.js

@@ -45,6 +45,10 @@ hyperbook.python = (function () {
    * @type {Map<string, Set<string>>}
    */
   const installedMicropipPackages = new Map();
+  /**
+   * @type {Map<string, any>}
+   */
+  const turtleModules = new Map();
 
   /**
    * @type {Map<string, { running: boolean, stopping: boolean, stopRequested: boolean, type: "run" | "test" | null }>}
@@ -74,7 +78,12 @@ hyperbook.python = (function () {
     const loadPyodide = await pyodideReadyPromise;
     const pyodide = await loadPyodide();
     if (typeof pyodide.registerJsModule === "function") {
+      const turtleModule = createTurtleJsFFI(id);
+      turtleModule.__setPyodide(pyodide);
+      pyodide.registerJsModule("turtle", turtleModule);
+      pyodide.registerJsModule("jturtle", turtleModule);
       pyodide.registerJsModule("pytamaro_js_ffi", createPytamaroJsFFI());
+      turtleModules.set(id, turtleModule);
     }
     if (
       typeof SharedArrayBuffer !== "undefined" &&
@@ -95,16 +104,58 @@ hyperbook.python = (function () {
    * @type {Map<string, string>}
    */
   const pytamaroStdoutCarry = new Map();
+  const pytamaroCanvasTargets = new Set();
 
   const getOutput = (id) => {
     return document.getElementById(id)?.getElementsByClassName("output")[0];
   };
 
+  const getCanvas = (id) => {
+    return document.getElementById(id)?.getElementsByClassName("canvas")[0];
+  };
+
+  const setPytamaroCanvasTarget = (id, enabled) => {
+    if (enabled) {
+      pytamaroCanvasTargets.add(id);
+    } else {
+      pytamaroCanvasTargets.delete(id);
+    }
+  };
+
+  const renderPytamaroDataUri = (id, container, dataUri) => {
+    if (id && pytamaroCanvasTargets.has(id)) {
+      const canvas = getCanvas(id);
+      const context = canvas?.getContext?.("2d");
+      if (canvas && context) {
+        const img = new Image();
+        img.onload = () => {
+          const width = Math.max(1, img.naturalWidth || img.width);
+          const height = Math.max(1, img.naturalHeight || img.height);
+          canvas.width = width;
+          canvas.height = height;
+          context.clearRect(0, 0, width, height);
+          context.drawImage(img, 0, 0, width, height);
+        };
+        img.onerror = () => {
+          appendOutputErrorLine(id, "Failed to render pytamaro graphic.");
+        };
+        img.src = dataUri;
+        return;
+      }
+    }
+
+    const img = document.createElement("img");
+    img.src = dataUri;
+    img.style.maxWidth = "100%";
+    img.style.display = "block";
+    container.appendChild(img);
+  };
+
   /**
    * Renders a message that may contain pytamaro data URI image markers into
    * the given container, creating <img> elements for each embedded image.
    */
-  const renderOutputSegments = (container, message) => {
+  const renderOutputSegments = (container, message, id = null) => {
     let remaining = String(message);
     while (remaining.length > 0) {
       const beginIdx = remaining.indexOf(PYTAMARO_URI_BEGIN);
@@ -122,15 +173,15 @@ hyperbook.python = (function () {
         break;
       }
       const dataUri = afterBegin.slice(0, endIdx);
-      const img = document.createElement("img");
-      img.src = dataUri;
-      img.style.maxWidth = "100%";
-      img.style.display = "block";
-      container.appendChild(img);
+      renderPytamaroDataUri(id, container, dataUri);
       remaining = afterBegin.slice(endIdx + PYTAMARO_URI_END.length);
     }
   };
 
+  const scriptLooksLikeTurtle = (script) => {
+    return /\bfrom\s+turtle\s+import\b|\bimport\s+turtle\b/.test(String(script || ""));
+  };
+
   const getTrailingPrefixLength = (text, marker) => {
     const max = Math.min(text.length, marker.length - 1);
     for (let len = max; len > 0; len -= 1) {
@@ -189,11 +240,7 @@ hyperbook.python = (function () {
       }
 
       const dataUri = afterBegin.slice(0, endIdx);
-      const img = document.createElement("img");
-      img.src = dataUri;
-      img.style.maxWidth = "100%";
-      img.style.display = "block";
-      output.appendChild(img);
+      renderPytamaroDataUri(id, output, dataUri);
       combined = afterBegin.slice(endIdx + PYTAMARO_URI_END.length);
     }
   };
@@ -207,7 +254,7 @@ hyperbook.python = (function () {
     output.appendChild(line);
   };
 
-  const appendOutput = (output, message, isError = false) => {
+  const appendOutput = (output, message, isError = false, id = null) => {
     if (!output || message === undefined || message === null) return;
     if (isError) {
       const line = document.createElement("span");
@@ -218,7 +265,7 @@ hyperbook.python = (function () {
     }
     const msg = String(message);
     if (msg.includes(PYTAMARO_URI_BEGIN)) {
-      renderOutputSegments(output, msg);
+      renderOutputSegments(output, msg, id);
       return;
     }
     output.appendChild(document.createTextNode(msg));
@@ -226,6 +273,7 @@ hyperbook.python = (function () {
 
   const clearPytamaroStdoutCarry = (id) => {
     pytamaroStdoutCarry.delete(id);
+    pytamaroCanvasTargets.delete(id);
   };
 
   const updateFullscreenButtonState = (elem, button) => {
@@ -268,6 +316,954 @@ hyperbook.python = (function () {
     context?.clearRect(0, 0, canvas.width, canvas.height);
   };
 
+  const createTurtleJsFFI = (id) => {
+    const DEFAULT_LINE_WIDTH = 1;
+    const DEFAULT_FONT_SIZE = 8;
+    const TK_TEXT_X_OFFSET = -1;
+    const DEFAULT_TURTLE_SCREEN_WIDTH = 400;
+    const TURTLE_SIZE = 20;
+
+    let pyodide = null;
+    let canvas = null;
+    let context = null;
+    let cssWidth = 0;
+    let cssHeight = 0;
+    let dpr = 1;
+    let active = false;
+
+    let x = 0;
+    let y = 0;
+    let heading = 0;
+    let renderedX = 0;
+    let renderedY = 0;
+    let renderedHeading = 0;
+    let penDown = true;
+    let turtleVisible = true;
+    let renderedTurtleVisible = true;
+    let strokeColor = "#000000";
+    let fillColor = "#000000";
+    let backgroundColor = "#ffffff";
+    let backgroundImage = null;
+    let fontSize = DEFAULT_FONT_SIZE;
+    let currentFontFamily = "Arial";
+    let currentFontStyle = "normal";
+    let colorMode = 1.0;
+    let delayMs = 80;
+    let turtleSpeed = 3;
+    let screenWidth = null;
+    let screenHeight = null;
+    let filling = false;
+    let fillPath = null;
+    let currentPath = null;
+    /** @type {Array<any>} */
+    let paths = [];
+    let operationQueue = [];
+    let queueGeneration = 0;
+    let queueRunning = false;
+    const textMeasureCanvas = document.createElement("canvas");
+    const textMeasureContext = textMeasureCanvas.getContext("2d");
+
+    const normalizeAngle = (angle) => {
+      const value = Number(angle) || 0;
+      return ((value % 360) + 360) % 360;
+    };
+
+    const toRadians = (angle) => (Number(angle) * Math.PI) / 180;
+    const toCanvasX = (value) => cssWidth / 2 + value;
+    const toCanvasY = (value) => cssHeight / 2 - value;
+    const toPlainNumber = (value, fallback = Number.NaN) => {
+      if (value === null || value === undefined) return fallback;
+      if (typeof value === "number") return Number.isFinite(value) ? value : fallback;
+      if (typeof value === "bigint") return Number(value);
+      if (typeof value.toJs === "function") {
+        return toPlainNumber(value.toJs({ pyproxies: [] }), fallback);
+      }
+      const numeric = Number(value);
+      return Number.isFinite(numeric) ? numeric : fallback;
+    };
+    const fontSizeToCanvasUnits = (value) => {
+      const numeric = toPlainNumber(value, Number.NaN);
+      if (!Number.isFinite(numeric) || numeric === 0) {
+        const fallback = DEFAULT_FONT_SIZE;
+        return { size: `${fallback}pt`, pxApprox: (fallback * 96) / 72 };
+      }
+      if (numeric < 0) {
+        return { size: `${Math.abs(numeric)}px`, pxApprox: Math.abs(numeric) };
+      }
+      return { size: `${numeric}pt`, pxApprox: (numeric * 96) / 72 };
+    };
+    const toPlainString = (value, fallback = "") => {
+      if (value === null || value === undefined) return fallback;
+      if (typeof value === "string") return value;
+      if (typeof value.toJs === "function") {
+        return toPlainString(value.toJs({ pyproxies: [] }), fallback);
+      }
+      return String(value);
+    };
+    const toSequence = (value) => {
+      if (value === null || value === undefined) return null;
+      if (Array.isArray(value)) return value;
+      if (typeof value === "string") return [value];
+      if (typeof value.toJs === "function") {
+        return toSequence(value.toJs({ pyproxies: [] }));
+      }
+      if (typeof value[Symbol.iterator] === "function") {
+        try {
+          return Array.from(value);
+        } catch {}
+      }
+      if (typeof value === "object" && "length" in value) {
+        try {
+          return Array.from(value);
+        } catch {}
+      }
+      return null;
+    };
+    const toPlainObject = (value) => {
+      if (value === null || value === undefined) return null;
+      if (typeof value.toJs === "function") {
+        try {
+          return toPlainObject(value.toJs({ pyproxies: [], dict_converter: Object.fromEntries }));
+        } catch {
+          return toPlainObject(value.toJs({ pyproxies: [] }));
+        }
+      }
+      if (typeof value !== "object" || Array.isArray(value)) return null;
+      return value;
+    };
+    const hasOwn = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+    const isWriteKwargsObject = (value) => {
+      const obj = toPlainObject(value);
+      if (!obj) return false;
+      return (
+        hasOwn(obj, "arg") ||
+        hasOwn(obj, "text") ||
+        hasOwn(obj, "move") ||
+        hasOwn(obj, "align") ||
+        hasOwn(obj, "font")
+      );
+    };
+    const normalizeFontStyle = (value) => {
+      const style = toPlainString(value, "normal").trim().toLowerCase();
+      if (!style || style === "normal") return "";
+      const parts = style.split(/\s+/).filter(Boolean);
+      const hasItalic = parts.includes("italic");
+      const hasBold = parts.includes("bold");
+      if (hasItalic && hasBold) return "italic bold";
+      if (hasBold) return "bold";
+      if (hasItalic) return "italic";
+      return style;
+    };
+    const normalizeTextAlign = (value) => {
+      const align = toPlainString(value, "left").trim().toLowerCase();
+      if (align === "center" || align === "right") return align;
+      return "left";
+    };
+    const buildCanvasFont = (family, size, style) => {
+      const { size: canvasSize } = fontSizeToCanvasUnits(size);
+      const stylePart = normalizeFontStyle(style);
+      return `${stylePart ? `${stylePart} ` : ""}${canvasSize} ${toPlainString(family, "Arial")}`;
+    };
+    const measureTurtleText = (text, family, size, style) => {
+      const font = buildCanvasFont(family, size, style);
+      const { pxApprox } = fontSizeToCanvasUnits(size);
+      const ctx = textMeasureContext || context;
+      if (!ctx) {
+        return {
+          font,
+          width: String(text || "").length * pxApprox * 0.6,
+          descent: pxApprox * 0.2,
+        };
+      }
+      ctx.font = font;
+      ctx.textAlign = "left";
+      const metrics = ctx.measureText(String(text || ""));
+      return {
+        font,
+        width: metrics.width,
+        left: metrics.actualBoundingBoxLeft || 0,
+        right: metrics.actualBoundingBoxRight || metrics.width,
+        ascent:
+          metrics.fontBoundingBoxAscent ||
+          metrics.actualBoundingBoxAscent ||
+          pxApprox * 0.8,
+        descent:
+          metrics.fontBoundingBoxDescent ||
+          metrics.actualBoundingBoxDescent ||
+          pxApprox * 0.2,
+      };
+    };
+    const sleep = (ms) => new Promise((resolve) => window.setTimeout(resolve, ms));
+    const clearQueue = () => {
+      queueGeneration += 1;
+      operationQueue = [];
+      queueRunning = false;
+    };
+    const enqueueOperation = (fn) => {
+      if (delayMs <= 0) {
+        fn();
+        return;
+      }
+      const generation = queueGeneration;
+      operationQueue.push({ fn, generation });
+      if (queueRunning) return;
+      queueRunning = true;
+      void (async () => {
+        try {
+          while (operationQueue.length > 0) {
+            const operation = operationQueue.shift();
+            if (!operation || operation.generation !== queueGeneration) {
+              continue;
+            }
+            operation.fn();
+            if (delayMs > 0) {
+              await sleep(delayMs);
+            }
+          }
+        } finally {
+          queueRunning = false;
+        }
+      })();
+    };
+
+    const ensureContext = () => {
+      if (!canvas) {
+        canvas = getCanvas(id);
+      }
+      if (!canvas) return false;
+      if (!context) {
+        context = canvas.getContext("2d");
+      }
+      return !!context;
+    };
+
+    const setupCanvasResolution = () => {
+      if (!ensureContext()) return false;
+      dpr = window.devicePixelRatio || 1;
+      const wrapperRect = canvas.parentElement?.getBoundingClientRect?.();
+      const panelWidth =
+        wrapperRect?.width || canvas.parentElement?.clientWidth || canvas.clientWidth || canvas.width || 800;
+      const panelHeight =
+        wrapperRect?.height || canvas.parentElement?.clientHeight || canvas.clientHeight || canvas.height || 400;
+      const width = Math.max(
+        1,
+        Math.floor(screenWidth !== null ? screenWidth : panelWidth),
+      );
+      const height = Math.max(
+        1,
+        Math.floor(screenHeight !== null ? screenHeight : panelHeight),
+      );
+      cssWidth = width;
+      cssHeight = height;
+      canvas.style.width = `${width}px`;
+      canvas.style.height = `${height}px`;
+      canvas.width = Math.max(1, Math.floor(cssWidth * dpr));
+      canvas.height = Math.max(1, Math.floor(cssHeight * dpr));
+      context.setTransform(dpr, 0, 0, dpr, 0, 0);
+      return true;
+    };
+
+    const makePath = (overrides = {}) => ({
+      down: penDown,
+      stroke: strokeColor,
+      lineWidth: DEFAULT_LINE_WIDTH,
+      fontsize: fontSize,
+      fontfamily: currentFontFamily,
+      fontstyle: currentFontStyle,
+      fill: false,
+      fillstyle: fillColor,
+      points: [{ x, y }],
+      ...overrides,
+    });
+
+    const beginCurrentPath = () => {
+      currentPath = makePath();
+      paths.push(currentPath);
+      return currentPath;
+    };
+
+    const commitStyleToNewPath = () => {
+      currentPath = makePath({
+        down: penDown,
+        lineWidth: currentPath?.lineWidth ?? DEFAULT_LINE_WIDTH,
+      });
+      paths.push(currentPath);
+      return currentPath;
+    };
+
+    const ensurePath = () => {
+      if (!currentPath) {
+        beginCurrentPath();
+      }
+      return currentPath;
+    };
+
+    const drawBackground = () => {
+      context.save();
+      context.setTransform(dpr, 0, 0, dpr, 0, 0);
+      context.fillStyle = backgroundColor;
+      context.fillRect(0, 0, cssWidth, cssHeight);
+      if (backgroundImage?.complete && backgroundImage.naturalWidth > 0) {
+        context.drawImage(backgroundImage, 0, 0, cssWidth, cssHeight);
+      }
+      context.restore();
+    };
+
+    const drawPathSegment = (path) => {
+      if (!path?.points?.length) return;
+
+      if (path.fill) {
+        context.beginPath();
+        path.points.forEach((point, index) => {
+          const px = toCanvasX(point.x);
+          const py = toCanvasY(point.y);
+          if (index === 0) {
+            context.moveTo(px, py);
+          } else {
+            context.lineTo(px, py);
+          }
+        });
+        context.closePath();
+        context.fillStyle = path.fillstyle;
+        context.fill();
+        return;
+      }
+
+      let startedLine = false;
+      context.beginPath();
+      for (const point of path.points) {
+        const px = toCanvasX(point.x);
+        const py = toCanvasY(point.y);
+        if (point.text !== undefined) {
+          const family = point.fontfamily || path.fontfamily || "Arial";
+          const style = point.fontstyle || path.fontstyle || "normal";
+          const size = point.fontsize ?? path.fontsize ?? DEFAULT_FONT_SIZE;
+          const text = String(point.text);
+          const metrics = measureTurtleText(text, family, size, style);
+          const align = normalizeTextAlign(point.align);
+          const left = metrics.left || 0;
+          const right = metrics.right || metrics.width || 0;
+          const descent = metrics.descent || 0;
+          const anchorX = px + TK_TEXT_X_OFFSET;
+          let drawX = anchorX + left;
+          if (align === "center") {
+            drawX = anchorX + (left - right) / 2;
+          } else if (align === "right") {
+            drawX = anchorX - right;
+          }
+          const drawY = py - descent;
+          context.font = metrics.font;
+          context.fillStyle = point.color || path.stroke;
+          context.textAlign = "left";
+          context.textBaseline = "alphabetic";
+          context.fillText(text, drawX, drawY);
+          continue;
+        }
+        if (point.dotRadius) {
+          context.beginPath();
+          context.arc(px, py, point.dotRadius, 0, 2 * Math.PI);
+          context.fillStyle = point.color || path.fillstyle || path.stroke;
+          context.fill();
+          context.beginPath();
+          startedLine = false;
+          continue;
+        }
+        if (!startedLine || point.move || !path.down) {
+          context.moveTo(px, py);
+          startedLine = true;
+          continue;
+        }
+        context.lineTo(px, py);
+      }
+
+      if (path.down) {
+        context.strokeStyle = path.stroke;
+        context.lineWidth = path.lineWidth || DEFAULT_LINE_WIDTH;
+        context.stroke();
+      }
+    };
+
+    const drawTurtle = () => {
+      if (!renderedTurtleVisible) return;
+      context.save();
+      context.translate(toCanvasX(renderedX), toCanvasY(renderedY));
+      context.rotate(-toRadians(renderedHeading));
+      context.beginPath();
+      context.moveTo(TURTLE_SIZE / 2, 0);
+      context.lineTo(-TURTLE_SIZE / 2, TURTLE_SIZE / 3);
+      context.lineTo(-TURTLE_SIZE / 4, 0);
+      context.lineTo(-TURTLE_SIZE / 2, -TURTLE_SIZE / 3);
+      context.closePath();
+      context.fillStyle = "#2f9e44";
+      context.strokeStyle = "#1b5e20";
+      context.lineWidth = 1;
+      context.fill();
+      context.stroke();
+      context.restore();
+    };
+
+    const draw = () => {
+      if (!active) return;
+      if (!setupCanvasResolution()) return;
+      drawBackground();
+      paths.forEach(drawPathSegment);
+      drawTurtle();
+    };
+
+    const resetState = () => {
+      paths = [];
+      currentPath = null;
+      fillPath = null;
+      x = 0;
+      y = 0;
+      heading = 0;
+      renderedX = 0;
+      renderedY = 0;
+      renderedHeading = 0;
+      penDown = true;
+      turtleVisible = true;
+      renderedTurtleVisible = true;
+      strokeColor = "#000000";
+      fillColor = "#000000";
+      backgroundColor = "#ffffff";
+      backgroundImage = null;
+      fontSize = DEFAULT_FONT_SIZE;
+      currentFontFamily = "Arial";
+      currentFontStyle = "normal";
+      colorMode = 1.0;
+      screenWidth = null;
+      screenHeight = null;
+      filling = false;
+      active = true;
+      clearQueue();
+      beginCurrentPath();
+      draw();
+    };
+
+    const deactivate = () => {
+      active = false;
+      clearQueue();
+      paths = [];
+      currentPath = null;
+      fillPath = null;
+      turtleVisible = false;
+      renderedTurtleVisible = false;
+    };
+
+    const bindCanvas = (nextCanvas) => {
+      canvas = nextCanvas || getCanvas(id);
+      context = canvas?.getContext?.("2d") || null;
+      if (canvas) {
+        canvas.tabIndex = 0;
+      }
+      if (!currentPath) {
+        beginCurrentPath();
+      }
+      draw();
+    };
+
+    const toColorString = (value) => {
+      if (typeof value === "string") {
+        return value;
+      }
+      if (value && typeof value.toJs === "function") {
+        return toColorString(value.toJs({ pyproxies: [] }));
+      }
+      if (Array.isArray(value) || (value && typeof value === "object" && "length" in value)) {
+        const parts = Array.from(value).slice(0, 3).map((part) => Number(part));
+        if (parts.length !== 3 || parts.some((part) => !Number.isFinite(part))) {
+          throw new Error(`bad color sequence: ${String(value)}`);
+        }
+        if (colorMode === 1.0) {
+          if (parts.some((part) => part < 0 || part > 1)) {
+            throw new Error(`bad color sequence: ${String(value)}`);
+          }
+          const [r, g, b] = parts.map((part) => Math.round(part * 255));
+          return `rgb(${r}, ${g}, ${b})`;
+        }
+        if (colorMode === 255) {
+          if (parts.some((part) => part < 0 || part > 255)) {
+            throw new Error(`bad color sequence: ${String(value)}`);
+          }
+          const [r, g, b] = parts.map((part) => Math.round(part));
+          return `rgb(${r}, ${g}, ${b})`;
+        }
+        throw new Error(`bad color sequence: ${String(value)}`);
+      }
+      return "#000000";
+    };
+
+    const getPenState = () => ({
+      pendown: penDown,
+      pencolor: strokeColor,
+      fillcolor: fillColor,
+      pensize: currentPath?.lineWidth ?? DEFAULT_LINE_WIDTH,
+      speed: turtleSpeed,
+      shown: turtleVisible,
+    });
+
+    const forward = (distance) => {
+      if (!ensureContext()) return;
+      const path = ensurePath();
+      const fill = filling ? fillPath : null;
+      const length = Number(distance) || 0;
+      const nextX = x + length * Math.cos(toRadians(heading));
+      const nextY = y + length * Math.sin(toRadians(heading));
+      x = nextX;
+      y = nextY;
+      const point = { x, y, move: !penDown };
+      enqueueOperation(() => {
+        renderedX = point.x;
+        renderedY = point.y;
+        path.points.push(point);
+        if (fill) {
+          fill.points.push({ x, y });
+        }
+        draw();
+      });
+    };
+
+    const backward = (distance) => forward(-Number(distance || 0));
+    const right = (angle) => {
+      heading = normalizeAngle(heading - Number(angle || 0));
+      const nextHeading = heading;
+      enqueueOperation(() => {
+        renderedHeading = nextHeading;
+        draw();
+      });
+    };
+    const left = (angle) => {
+      heading = normalizeAngle(heading + Number(angle || 0));
+      const nextHeading = heading;
+      enqueueOperation(() => {
+        renderedHeading = nextHeading;
+        draw();
+      });
+    };
+    const penup = () => {
+      penDown = false;
+      commitStyleToNewPath();
+      draw();
+    };
+    const pendownFn = () => {
+      penDown = true;
+      commitStyleToNewPath();
+      draw();
+    };
+    const goto_ = (a, b) => {
+      if (!ensureContext()) return;
+      let nextX = Number(a);
+      let nextY = Number(b);
+      if (b === undefined && (Array.isArray(a) || (a && typeof a === "object"))) {
+        const source =
+          a && typeof a.toJs === "function" ? a.toJs({ pyproxies: [] }) : a;
+        nextX = Number(source?.[0] ?? source?.x ?? 0);
+        nextY = Number(source?.[1] ?? source?.y ?? 0);
+      }
+      x = Number.isFinite(nextX) ? nextX : 0;
+      y = Number.isFinite(nextY) ? nextY : 0;
+      const path = ensurePath();
+      const fill = filling ? fillPath : null;
+      const point = { x, y, move: !penDown };
+      enqueueOperation(() => {
+        renderedX = point.x;
+        renderedY = point.y;
+        path.points.push(point);
+        if (fill) {
+          fill.points.push({ x, y });
+        }
+        draw();
+      });
+    };
+    const setx = (value) => goto_(Number(value), y);
+    const sety = (value) => goto_(x, Number(value));
+    const position = () => [x, y];
+    const xcor = () => x;
+    const ycor = () => y;
+    const heading_ = () => heading;
+    const setheading = (angle) => {
+      heading = normalizeAngle(angle);
+      const nextHeading = heading;
+      enqueueOperation(() => {
+        renderedHeading = nextHeading;
+        draw();
+      });
+    };
+    const home = () => {
+      goto_(0, 0);
+      setheading(0);
+    };
+    const towards = (tx, ty) => {
+      const dx = Number(tx) - x;
+      const dy = Number(ty) - y;
+      if (!Number.isFinite(dx) || !Number.isFinite(dy)) return 0;
+      return normalizeAngle((Math.atan2(dy, dx) * 180) / Math.PI);
+    };
+    const speed = (value = 0) => {
+      const numeric = Number(value);
+      turtleSpeed = Number.isFinite(numeric) ? numeric : 0;
+      delayMs = turtleSpeed <= 0 ? 0 : Math.max(0, Math.round(300 / turtleSpeed));
+      return delayMs;
+    };
+    const colormode = (mode = undefined) => {
+      if (mode === undefined) return colorMode;
+      const numeric = Number(mode);
+      if (numeric !== 1 && numeric !== 255) {
+        throw new Error("colormode must be 1.0 or 255");
+      }
+      colorMode = numeric;
+      return colorMode;
+    };
+    const screensize = (canvwidth = undefined, canvheight = undefined, bg = undefined) => {
+      if (canvwidth === undefined && canvheight === undefined && bg === undefined) {
+        return [screenWidth || cssWidth || 0, screenHeight || cssHeight || 0];
+      }
+      if (canvwidth !== undefined && canvwidth !== null) {
+        const width = Math.floor(Number(canvwidth));
+        if (Number.isFinite(width) && width > 0) {
+          screenWidth = width;
+        }
+      }
+      if (canvheight !== undefined && canvheight !== null) {
+        const height = Math.floor(Number(canvheight));
+        if (Number.isFinite(height) && height > 0) {
+          screenHeight = height;
+        }
+      }
+      if (bg !== undefined && bg !== null) {
+        backgroundColor = toColorString(bg);
+      }
+      draw();
+      if (canvas?.parentElement) {
+        const wrapper = canvas.parentElement;
+        wrapper.scrollLeft = Math.max(0, (cssWidth - wrapper.clientWidth) / 2);
+        wrapper.scrollTop = Math.max(0, (cssHeight - wrapper.clientHeight) / 2);
+      }
+      return [screenWidth || cssWidth || 0, screenHeight || cssHeight || 0];
+    };
+    const color = (...args) => {
+      const stroke = toColorString(args[0]);
+      const fill = args.length > 1 ? toColorString(args[1]) : stroke;
+      strokeColor = stroke;
+      fillColor = fill;
+      commitStyleToNewPath();
+      if (filling && fillPath) {
+        fillPath.fillstyle = fillColor;
+      }
+      draw();
+    };
+    const pencolor = (value) => {
+      strokeColor = toColorString(value);
+      commitStyleToNewPath();
+      draw();
+    };
+    const fillcolor = (value) => {
+      fillColor = toColorString(value);
+      if (filling && fillPath) {
+        fillPath.fillstyle = fillColor;
+      }
+      commitStyleToNewPath();
+      draw();
+    };
+    const pensize = (value) => {
+      ensurePath().lineWidth = Math.max(1, Number(value) || DEFAULT_LINE_WIDTH);
+      commitStyleToNewPath();
+      draw();
+    };
+    const width = (value) => pensize(value);
+    const begin_fill = () => {
+      if (filling) return;
+      filling = true;
+      fillPath = makePath({
+        down: false,
+        fill: true,
+        stroke: "transparent",
+        lineWidth: 1,
+        fillstyle: fillColor,
+      });
+      paths.push(fillPath);
+      draw();
+    };
+    const end_fill = () => {
+      filling = false;
+      fillPath = null;
+      commitStyleToNewPath();
+      draw();
+    };
+    const dot = (size = 5, colorValue = null) => {
+      const segment = makePath({
+        down: false,
+        fill: false,
+        stroke: colorValue ? toColorString(colorValue) : strokeColor,
+        fillstyle: colorValue ? toColorString(colorValue) : strokeColor,
+        points: [
+          {
+            x,
+            y,
+            dotRadius: Math.max(0.5, Number(size) || 5) / 2,
+            color: colorValue ? toColorString(colorValue) : strokeColor,
+          },
+        ],
+      });
+      enqueueOperation(() => {
+        paths.push(segment);
+        draw();
+      });
+    };
+    const circle = (radius, steps = 120) => {
+      const numericRadius = Number(radius) || 0;
+      const stepCount = Math.max(8, Number(steps) | 0);
+      const circumference = 2 * Math.PI * Math.abs(numericRadius);
+      const stepLength = circumference / stepCount;
+      const stepTurn = (360 / stepCount) * (numericRadius >= 0 ? 1 : -1);
+      for (let index = 0; index < stepCount; index += 1) {
+        forward(stepLength);
+        left(stepTurn);
+      }
+    };
+    const write = (text, move = false, align = "left", font = null) => {
+      let writeText = text;
+      let writeMove = move;
+      let writeAlign = align;
+      let writeFont = font;
+
+      if (isWriteKwargsObject(writeAlign)) {
+        const kwargs = toPlainObject(writeAlign);
+        if (kwargs) {
+          if (hasOwn(kwargs, "arg")) writeText = kwargs.arg;
+          else if (hasOwn(kwargs, "text")) writeText = kwargs.text;
+          if (hasOwn(kwargs, "move")) writeMove = kwargs.move;
+          if (hasOwn(kwargs, "align")) writeAlign = kwargs.align;
+          if (hasOwn(kwargs, "font")) writeFont = kwargs.font;
+        }
+      }
+      if (isWriteKwargsObject(writeFont)) {
+        const kwargs = toPlainObject(writeFont);
+        if (kwargs) {
+          if (hasOwn(kwargs, "arg")) writeText = kwargs.arg;
+          else if (hasOwn(kwargs, "text")) writeText = kwargs.text;
+          if (hasOwn(kwargs, "move")) writeMove = kwargs.move;
+          if (hasOwn(kwargs, "align")) writeAlign = kwargs.align;
+          if (hasOwn(kwargs, "font")) writeFont = kwargs.font;
+        }
+        writeFont = null;
+      }
+
+      let family = currentFontFamily;
+      let size = fontSize;
+      let style = currentFontStyle;
+      try {
+        const source = toSequence(writeFont);
+        if (source?.length) {
+          if (source[0]) family = toPlainString(source[0], family);
+          if (source[1] !== undefined && source[1] !== null) {
+            size = toPlainNumber(source[1], size);
+          }
+          if (source[2]) style = toPlainString(source[2], style);
+        }
+      } catch {}
+      const normalizedAlign = normalizeTextAlign(writeAlign);
+      const segment = makePath({
+        down: false,
+        fill: false,
+        stroke: strokeColor,
+        points: [
+          {
+            x,
+            y,
+            text: String(writeText),
+            align: normalizedAlign,
+            fontsize: size,
+            fontfamily: family,
+            fontstyle: style,
+            color: strokeColor,
+          },
+        ],
+      });
+      if (Boolean(writeMove)) {
+        const metrics = measureTurtleText(String(writeText), family, size, style);
+        const left = metrics.left || 0;
+        const right = metrics.right || metrics.width || 0;
+        const align = normalizeTextAlign(normalizedAlign);
+        const textWidth = left + right;
+        if (align === "left") {
+          x += TK_TEXT_X_OFFSET + textWidth;
+        } else if (align === "center") {
+          x += TK_TEXT_X_OFFSET + right;
+        } else {
+          x += TK_TEXT_X_OFFSET;
+        }
+        commitStyleToNewPath();
+      }
+      enqueueOperation(() => {
+        paths.push(segment);
+        draw();
+      });
+    };
+    const setfontsize = (value) => {
+      const nextSize = toPlainNumber(value, DEFAULT_FONT_SIZE);
+      fontSize = Math.max(1, Number.isFinite(nextSize) ? nextSize : DEFAULT_FONT_SIZE);
+      commitStyleToNewPath();
+      draw();
+    };
+    const bgcolor = (value) => {
+      backgroundColor = toColorString(value);
+      draw();
+    };
+    const bgpic = (filename = "") => {
+      const name = String(filename || "").trim();
+      if (!name) {
+        backgroundImage = null;
+        draw();
+        return;
+      }
+      const fs = pyodide?.FS;
+      if (!fs) return;
+      const candidates = [
+        name,
+        `/home/pyodide/${name}`,
+        `/home/pyodide/files/${name}`,
+        `/home/pyodide/uploads/${name}`,
+      ];
+      for (const candidate of candidates) {
+        try {
+          const data = fs.readFile(candidate);
+          const blob = new Blob([data], { type: "image/*" });
+          const url = URL.createObjectURL(blob);
+          const image = new Image();
+          image.onload = () => {
+            backgroundImage = image;
+            draw();
+            URL.revokeObjectURL(url);
+          };
+          image.onerror = () => URL.revokeObjectURL(url);
+          image.src = url;
+          return;
+        } catch {}
+      }
+    };
+    const clear = () => {
+      clearQueue();
+      paths = [];
+      currentPath = null;
+      fillPath = null;
+      beginCurrentPath();
+      draw();
+    };
+    const reset = () => {
+      resetState();
+    };
+    const showturtle = () => {
+      turtleVisible = true;
+      enqueueOperation(() => {
+        renderedTurtleVisible = true;
+        draw();
+      });
+    };
+    const hideturtle = () => {
+      turtleVisible = false;
+      enqueueOperation(() => {
+        renderedTurtleVisible = false;
+        draw();
+      });
+    };
+    const isvisible = () => turtleVisible;
+    const pen = (options = undefined) => {
+      if (options === undefined) {
+        return getPenState();
+      }
+      const source =
+        options && typeof options.toJs === "function"
+          ? options.toJs({ pyproxies: [], dict_converter: Object.fromEntries })
+          : options;
+      if (!source || typeof source !== "object") return getPenState();
+      if ("pendown" in source) {
+        penDown = !!source.pendown;
+      }
+      if ("pencolor" in source) {
+        strokeColor = toColorString(source.pencolor);
+      }
+      if ("fillcolor" in source) {
+        fillColor = toColorString(source.fillcolor);
+      }
+      if ("pensize" in source) {
+        ensurePath().lineWidth = Math.max(1, Number(source.pensize) || DEFAULT_LINE_WIDTH);
+      }
+      if ("shown" in source) {
+        turtleVisible = !!source.shown;
+        renderedTurtleVisible = turtleVisible;
+      }
+      commitStyleToNewPath();
+      draw();
+      return getPenState();
+    };
+
+    const api = {
+      __bindCanvas: bindCanvas,
+      __deactivate: deactivate,
+      __redraw: draw,
+      __resetState: resetState,
+      __setPyodide: (runtime) => {
+        pyodide = runtime;
+      },
+      forward,
+      fd: forward,
+      backward,
+      bk: backward,
+      back: backward,
+      right,
+      rt: right,
+      left,
+      lt: left,
+      goto: (...args) => goto_(...args),
+      setpos: (...args) => goto_(...args),
+      setposition: (...args) => goto_(...args),
+      setx,
+      sety,
+      setheading,
+      seth: setheading,
+      home,
+      circle,
+      dot,
+      position,
+      pos: position,
+      xcor,
+      ycor,
+      heading: heading_,
+      towards,
+      pendown: pendownFn,
+      pd: pendownFn,
+      down: pendownFn,
+      penup,
+      pu: penup,
+      up: penup,
+      pensize,
+      width,
+      pen,
+      write,
+      setfontsize,
+      color,
+      pencolor,
+      fillcolor,
+      begin_fill,
+      end_fill,
+      bgcolor,
+      bgpic,
+      reset,
+      clear,
+      speed,
+      colormode,
+      screensize,
+      showturtle,
+      st: showturtle,
+      hideturtle,
+      ht: hideturtle,
+      isvisible,
+    };
+
+    return api;
+  };
+
   const createPytamaroJsFFI = () => {
     const floatBuffer = new ArrayBuffer(4);
     const floatView = new DataView(floatBuffer);
@@ -596,6 +1592,142 @@ hyperbook.python = (function () {
     };
   };
 
+  // Browser/Pyodide needs periodic yielding for top-level pygame loops.
+  const hasExplicitMain = (code) => {
+    const text = String(code || "");
+    return (
+      /^(\s*)(?:async\s+def|def)\s+main\s*\(/m.test(text) ||
+      /__name__\s*==\s*["']__main__["']/.test(text)
+    );
+  };
+
+  const looksLikeTopLevelGameLoop = (code) => {
+    const text = String(code || "");
+    const hasPygame =
+      /(?:^|\W)(?:import\s+pygame\b|from\s+pygame\b\s+import\b)/m.test(text);
+    const hasSasPygame =
+      /(?:^|\W)(?:import\s+sas_pygame\b|from\s+sas_pygame\b\s+import\b)/m.test(text);
+    const hasAnyWhile = /^\s*while\s+.+:\s*$/m.test(text);
+    if (!hasAnyWhile) return false;
+    return (hasPygame || hasSasPygame) && hasAnyWhile;
+  };
+
+  const indentBlock = (source, spaces) => {
+    const pad = " ".repeat(spaces);
+    return String(source || "")
+      .split(/\r\n|\r|\n/)
+      .map((line) => (line.length ? pad + line : line))
+      .join("\n");
+  };
+
+  const wrapTopLevelIntoAsyncMain = (userCode) => {
+    const code = String(userCode || "").replace(/\r\n/g, "\n");
+
+    if (hasExplicitMain(code)) return code;
+
+    const lines = code.split("\n");
+    const keep = [];
+    const body = [];
+
+    let index = 0;
+    while (index < lines.length) {
+      const line = lines[index];
+      if (/^\s*$/.test(line)) {
+        keep.push(line);
+        index += 1;
+        continue;
+      }
+      if (/^\s*#/.test(line)) {
+        keep.push(line);
+        index += 1;
+        continue;
+      }
+      if (/^\s*(?:from\s+\S+\s+import\b|import\s+\S+)/.test(line)) {
+        keep.push(line);
+        index += 1;
+        continue;
+      }
+
+      if (/^\s*(?:def|async\s+def|class)\s+/.test(line)) {
+        keep.push(line);
+        index += 1;
+        while (index < lines.length) {
+          const nextLine = lines[index];
+          if (/^\s*$/.test(nextLine)) {
+            keep.push(nextLine);
+            index += 1;
+            continue;
+          }
+          if (
+            /^\S/.test(nextLine) &&
+            !/^\s*#/.test(nextLine) &&
+            !/^\s*(?:from\s+\S+\s+import\b|import\s+\S+)/.test(nextLine) &&
+            !/^\s*(?:def|async\s+def|class)\s+/.test(nextLine)
+          ) {
+            break;
+          }
+          keep.push(nextLine);
+          index += 1;
+        }
+        continue;
+      }
+      break;
+    }
+
+    for (; index < lines.length; index += 1) {
+      body.push(lines[index]);
+    }
+
+    let bodyText = body.join("\n");
+    bodyText = bodyText.replace(/^([ \t]*\n)+/, "");
+    bodyText = bodyText.replace(/(\n[ \t]*)+$/, "");
+    bodyText = bodyText.replace(/\t/g, "    ");
+    if (!bodyText.replace(/[\s\n]+/g, "").length) return code;
+
+    const injected = bodyText
+      .replace(
+        /^(\s*)(\w+\s*\.\s*tick\s*\([^\)]*\)\s*)$/gm,
+        "$1$2\n$1await asyncio.sleep(0)",
+      )
+      .replace(
+        /^(\s*)(pygame\s*\.\s*display\s*\.\s*flip\s*\(\s*\)\s*)$/gm,
+        "$1$2\n$1await asyncio.sleep(0)",
+      )
+      .replace(
+        /^([\t ]*)([A-Za-z_][\w]*(?:\s*\.\s*[A-Za-z_][\w]*)*\s*\.\s*step\s*\([^\)]*\)\s*)(#.*)?$/gm,
+        "$1$2$3\n$1await asyncio.sleep(0)",
+      );
+
+    const prelude = [
+      "# --- auto-wrapped by IDE for browser pygame compatibility ---",
+      "import asyncio",
+      "import pygame",
+      "",
+      "async def main():",
+      indentBlock(injected, 4),
+      "",
+      "await main()",
+      "# --- end auto-wrapped ---",
+      "",
+    ].join("\n");
+
+    let keepText = keep.join("\n");
+    if (keepText && !keepText.endsWith("\n")) keepText += "\n";
+    if (keepText && !/\n\s*\n$/.test(keepText)) keepText += "\n";
+
+    return keepText + prelude;
+  };
+
+  const maybeAutoWrapPygame = (code) => {
+    try {
+      const text = String(code || "");
+      if (!looksLikeTopLevelGameLoop(text)) return text;
+      return wrapTopLevelIntoAsyncMain(text);
+    } catch {
+      return String(code || "");
+    }
+  };
+
   const ensureMicropipPackages = async (id, pyodide, packages = []) => {
     if (packages.length === 0) return;
     if (!installedMicropipPackages.has(id)) {
@@ -623,10 +1755,20 @@ hyperbook.python = (function () {
       const pyodide = await getRuntime(id);
       const { canvas, ...globalsContext } = context;
       const decoder = new TextDecoder("utf-8");
+      const executableScript = maybeAutoWrapPygame(script);
 
       if (canvas) {
         try {
           resetCanvas(canvas);
+          const usesTurtle = scriptLooksLikeTurtle(executableScript);
+          if (usesTurtle) {
+            turtleModules.get(id)?.__bindCanvas(canvas);
+            turtleModules.get(id)?.__resetState();
+          } else {
+            turtleModules.get(id)?.__deactivate?.();
+            canvas.style.width = "";
+            canvas.style.height = "";
+          }
           pyodide.canvas.setCanvas2D(canvas);
         } catch (error) {
           appendOutputErrorLine(id, `Canvas setup failed: ${error.message}`);
@@ -658,14 +1800,14 @@ hyperbook.python = (function () {
       });
 
       await ensureMicropipPackages(id, pyodide, packages);
-      await pyodide.loadPackagesFromImports(script);
+      await pyodide.loadPackagesFromImports(executableScript);
       const dict = pyodide.globals.get("dict");
       const globals = dict();
       try {
         for (const [key, value] of Object.entries(globalsContext)) {
           globals.set(key, value);
         }
-        const results = await pyodide.runPythonAsync(script, {
+        const results = await pyodide.runPythonAsync(executableScript, {
           globals,
           locals: globals,
           filename,
@@ -1122,6 +2264,7 @@ if _pg:
         output.classList.add("hidden");
         if (canvasWrapper) canvasWrapper.classList.remove("hidden");
         canvasOutputSplitter?.classList.add("hidden");
+        turtleModules.get(id)?.__redraw?.();
       };
 
       const applyStoredCanvasOutputSplit = setupCanvasOutputSplitter(
@@ -1152,6 +2295,7 @@ if _pg:
             canvasBtn.disabled = true;
           }
           applyStoredCanvasOutputSplit?.();
+          turtleModules.get(id)?.__redraw?.();
           return;
         }
 
@@ -1238,7 +2382,10 @@ if _pg:
         void restoreEditorState();
       }
 
-      window.addEventListener("resize", applyCanvasOutputLayout);
+      window.addEventListener("resize", () => {
+        applyCanvasOutputLayout();
+        turtleModules.get(id)?.__redraw?.();
+      });
       applyCanvasOutputLayout();
 
       editor.addEventListener("input", () => {
@@ -1303,8 +2450,9 @@ if _pg:
 
       run?.addEventListener("click", async () => {
         const script = getEditorValue();
-        const useOutputForPytamaro = hasPytamaroPackage || scriptLooksLikePytamaro(script);
-        if (hasCanvas && !useOutputForPytamaro) {
+        const usesPytamaro = hasPytamaroPackage || scriptLooksLikePytamaro(script);
+        const renderPytamaroToCanvas = hasCanvas && canvas && usesPytamaro;
+        if (hasCanvas) {
           showCanvas();
         } else {
           showOutput();
@@ -1322,15 +2470,16 @@ if _pg:
         output.innerHTML = "";
         clearPytamaroStdoutCarry(id);
         try {
+          setPytamaroCanvasTarget(id, renderPytamaroToCanvas);
           const { results, error } = await executeScript(id, script, {
-            ...(hasCanvas && canvas && !useOutputForPytamaro ? { canvas } : {}),
+            ...(hasCanvas && canvas ? { canvas } : {}),
           }, additionalPackages);
           if (!state.stopRequested) {
             if (results) {
-              appendOutput(output, results);
+              appendOutput(output, results, false, id);
             } else if (error) {
               showOutput();
-              appendOutput(output, error, true);
+              appendOutput(output, error, true, id);
             }
           } else {
             appendOutputLine(id, "Execution stopped.");
@@ -1338,7 +2487,7 @@ if _pg:
         } catch (e) {
           showOutput();
           output.innerHTML = "";
-          appendOutput(output, `Error: ${e}`, true);
+          appendOutput(output, `Error: ${e}`, true, id);
           console.log(e);
         } finally {
           clearPytamaroStdoutCarry(id);