code-playpad 0.2.0 → 0.3.0

package/README.md

@@ -3,37 +3,134 @@
 [![npm](https://img.shields.io/npm/v/code-playpad)](https://www.npmjs.com/package/code-playpad) [![license](https://img.shields.io/npm/l/code-playpad)](./LICENSE)
 
 Runnable code in any web page. A CodeMirror editor that **executes what it
-shows** — Python, JavaScript and TypeScript — entirely in the reader's browser.
-No backend, no iframe, no sign-up.
+shows** — Python, JavaScript, TypeScript and a documented subset of Java —
+entirely in the reader's browser. No backend, no iframe, no sign-up.
 
 **[Live demo →](https://code-playpad.swengr.com)**
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/code-playpad@0.2.0"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/code-playpad@0.3.0"></script>
 
-<code-playpad height="180">
+<code-playpad height="auto">
   print("hello from a static page")
 </code-playpad>
 ```
 
+**Contents** — [Languages](#languages) · [Install](#install) · [Attributes](#attributes)
+· [Sizing](#sizing) · [Several files](#several-files) · [Input](#input)
+· [Controlling it from JavaScript](#controlling-it-from-javascript)
+· [Events and grading](#events-and-grading) · [Saving work](#saving-work)
+· [Light and dark](#light-and-dark) · [Styling](#styling) · [Framework recipes](#framework-recipes)
+· [Production](#production) · [Worth knowing](#worth-knowing)
+
 ## Languages
 
 | `language` | Runtime | Downloaded at runtime |
 | --- | --- | --- |
-| `python` (default) | Python 3.14 via Pyodide — full standard library, `input()`, real tracebacks, `numpy` on demand | ~11 MB, once, cached |
+| `python` (default) | Python 3.14 via Pyodide — full standard library, `input()`, real tracebacks, `numpy` on demand | ~6 MB (13.5 MB unpacked), once, cached |
 | `javascript` | The browser's own engine, in a Worker | nothing |
-| `typescript` | Same engine, types stripped before running | ~50 KB, once, cached |
+| `typescript` | Same engine, types stripped before running | ~70 KB, once, cached |
+| `java` | A documented subset of Java 25, compiled and interpreted in a Worker by an engine built for this package — see [Java](#java) | nothing: the engine is a ~27 KB (gzipped) chunk of this package, loaded with the first Java widget |
+
+```html
+<code-playpad height="auto">print("python is the default")</code-playpad>
+
+<code-playpad language="javascript" height="auto">
+  const doubled = [1, 2, 3].map((n) => n * 2);
+  console.log(doubled);
+  doubled.reduce((a, b) => a + b, 0)
+</code-playpad>
 
-Each language loads **only on pages that use it**. A Python-only page never
-downloads a byte of the JavaScript runtime; a JavaScript-only page never touches
-Pyodide's 11 MB.
+<code-playpad language="typescript" height="auto">
+  type Point = { x: number; y: number };
+  const dist = (p: Point): number => Math.hypot(p.x, p.y);
+  dist({ x: 3, y: 4 })
+</code-playpad>
+```
+
+A trailing expression prints its value, like a REPL. Each language loads **only
+on pages that use it**: a Python-only page never downloads a byte of the
+JavaScript runtime, and a JavaScript-only page never touches Pyodide's ~6 MB.
 
 TypeScript here erases types, it does not check them — a type error will not
 stop your code running. This is a playground, not `tsc`.
 
+### Java
+
+```html
+<code-playpad language="java" height="auto">
+  int visits = 0;
+
+  void main() {
+      greet("Ada");
+      IO.println("greeted " + visits + " people");
+  }
+
+  void greet(String name) {
+      visits++;
+      IO.println("Hello, " + name + "!");
+  }
+</code-playpad>
+```
+
+Java runs on an engine written for code-playpad, not on a JVM. It covers a
+documented subset of Java 25 and checks its behaviour against a real JDK 25:
+
+- Java 25 **compact source files** and instance `main`, or a classic
+  `public class Main` with `public static void main(String[] args)`
+- `int`, `char`, `boolean`, `String`; one-dimensional arrays; static and
+  instance methods with overloading and recursion; fields; `if`/`while`/`for`,
+  `break`/`continue`/`return`; `String.length()`/`charAt()`/`equals()`;
+  `System.out`/`System.err` and `IO.print`/`IO.println`
+- **Errors read like the JDK's**: compile errors in javac's format, exceptions
+  with Java stack traces and the JDK's NullPointerException messages
+
+Anything outside the subset — `long`/`double`, `?:`, `switch`, objects and
+constructors, collections, `Scanner`, imports — is reported as *not supported in
+this version* rather than run with a different meaning. The file is `Main.java`
+unless `entry` says otherwise. The engine stops runaway programs after 200
+million steps and explains why.
+
+## Download size
+
+What a page downloads once a reader presses Run, with the CDN build. Measured by
+loading one-widget pages in a browser and gzipping each file the page fetched;
+CDN downloads are what the CDN actually sent.
+
+| Page uses | code-playpad (gzip) | Also fetched from a CDN at run time | 0.2.1 (gzip) |
+| --- | --- | --- | --- |
+| Python | **165.8 KB** | Pyodide, about **6.0 MB** (a 3.3 MB wasm file and a 2.4 MB standard library) | 165.2 KB |
+| JavaScript | **179.9 KB** | nothing | 180.5 KB |
+| TypeScript | **179.9 KB** | Sucrase, 72 KB (≈ 252 KB in total) | ≈ 252.6 KB |
+| Java | **189.7 KB** | nothing | n/a |
+| All four | 247.2 KB | Pyodide and Sucrase | n/a |
+
+- **A shared base of 144 KB is in every row:** the editor (CodeMirror) and the
+  widget, the same as 0.2.1 within 0.6 KB.
+- **Each language adds:** Python 21.7 KB; JavaScript/TypeScript 35.8 KB; Java
+  45.6 KB, which is the 26.5 KB engine plus 19 KB of Java syntax highlighting.
+- **Languages load lazily.** A Java page never fetches the Python or JavaScript
+  runtimes, and Python and JavaScript pages never fetch Java, so adding Java left
+  Python-only and JavaScript-only pages the same size as in 0.2.1.
+- **Java is the lightest to run:** it is self-contained, while Python's first run
+  is dominated by the roughly 6 MB Pyodide download (cached after that).
+- **With npm and a bundler** you already ship CodeMirror yourself. code-playpad's
+  own code then costs about 9 KB, plus the runtime chunk for each language used;
+  Java's is 27 KB, plus `@codemirror/lang-java` if you install it.
+
 ## Install
 
-The CDN snippet above needs nothing installed. For a bundler:
+### From a CDN — nothing to install
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/code-playpad@0.3.0"></script>
+```
+
+This is the `standalone` build: CodeMirror is bundled in, so a static blog post
+or a Markdown-rendered page needs only that one tag. Pin the version — an
+unpinned URL follows `latest` and will change under your readers.
+
+### From npm, with a bundler
 
 ```bash
 npm install code-playpad @codemirror/state @codemirror/view @codemirror/commands \
@@ -41,59 +138,72 @@ npm install code-playpad @codemirror/state @codemirror/view @codemirror/commands
 ```
 
 CodeMirror is a peer dependency so you never end up with two copies of
-`@codemirror/state`. Language grammars (`@codemirror/lang-python`,
-`lang-javascript`, `lang-json`) are **optional** — install only the ones you
-use; a missing one degrades to plain text.
+`@codemirror/state`. Language grammars are **optional** — install only what you
+use (`@codemirror/lang-python`, `@codemirror/lang-javascript`,
+`@codemirror/lang-json`, `@codemirror/lang-java`); a missing one degrades to
+plain text rather than throwing.
 
 ```js
 import 'code-playpad/element';        // registers <code-playpad>
 ```
 
-Importing for the side effect is enough. If your bundler is configured to drop
-side-effect-only imports, register explicitly instead:
+If your bundler is configured to drop side-effect-only imports, register
+explicitly instead:
 
 ```js
 import { defineCodePlayPad } from 'code-playpad/element';
 defineCodePlayPad();
 ```
 
-From React:
+### Entry points
 
-```jsx
-import { CodePlayPad } from 'code-playpad/react';
-
-<CodePlayPad
-  language="python"
-  code={'print("hi")'}
-  height={180}
-  onOutput={(r) => setPassed(r.stdout.includes('hi'))}
-/>
-```
+| Import | You get |
+| --- | --- |
+| `code-playpad/element` | registers `<code-playpad>`; smallest thing that works |
+| `code-playpad` | the same, plus every helper below |
+| `code-playpad/react` | the `<CodePlayPad>` React component |
+| `code-playpad/standalone` | CodeMirror bundled in — what the CDN serves |
 
-Importing on a server is safe — the element degrades to a no-op without a DOM,
-so Next.js, Astro and SvelteKit need no dynamic import.
+Importing on a server is safe: without a DOM the element degrades to a no-op, so
+Next.js, Astro and SvelteKit need no dynamic import or `client:only` guard.
 
-## API
+## Attributes
 
 | | |
 | --- | --- |
-| **attributes** | `language`, `height`, `min-height`, `max-height`, `theme` (`light` \| `dark` \| `auto`), `readonly`, `autorun`, `stdin`, `persist`, `entry` |
-| **properties** | `code`, `files`, `entry`, `stdin`, `language` |
-| **methods** | `run()`, `stop()`, `reset()`, `getCode()`, `getFiles()`, `openFile(name)`, `prewarm()` |
-| **events** | `py-ready`, `py-run`, `py-output`, `py-error` |
+| `language` | `python` (default), `javascript`, `typescript`, `java` |
+| `height` | number (px), any CSS length, or `auto` |
+| `min-height` / `max-height` | bounds for `auto` |
+| `theme` | `light`, `dark`, or `auto` (default — follows the OS) |
+| `readonly` | editor cannot be typed into; Run still works |
+| `autorun` | runs once, on its own, when scrolled into view |
+| `stdin` | shows the standard-input box up front |
+| `persist` | key under which edits are saved (see [Saving work](#saving-work)) |
+| `entry` | which file Run executes, for multi-file widgets |
+
+```html
+<!-- a worked example nobody should edit -->
+<code-playpad height="auto" readonly>
+  print("read this, don't change it")
+</code-playpad>
 
-Events bubble and cross the shadow boundary, so answer-checking lives outside
-the widget:
+<!-- output visible before the reader does anything -->
+<code-playpad height="auto" autorun>
+  print("this already ran")
+</code-playpad>
 
-```js
-document.addEventListener('py-output', (e) => {
-  // e.detail: { stdout, stderr?, value?, table?, durationMs, language }
-  grade(e.target.id, e.detail.stdout);
-});
+<!-- always dark, regardless of the reader's OS setting -->
+<code-playpad height="auto" theme="dark">
+  print("always dark")
+</code-playpad>
 ```
 
-Note `language`, not `lang` — `lang` is a standard HTML attribute for the
-*human* language of an element's text.
+`readonly` blocks typing but not execution, and the code can still be replaced
+from JavaScript — useful for "show the answer" buttons.
+
+Note it is `language`, not `lang`: `lang` is a standard HTML attribute for the
+*human* language of an element's text, and putting `python` there confuses
+screen readers.
 
 ## Sizing
 
@@ -125,11 +235,11 @@ length (`40vh`, `30em`).
 
 ## Several files
 
-A widget can hold a small project. Relative imports, packages, and data files
-all work, and tracebacks name the real file and line.
+A widget can hold a small project. Relative imports, packages and data files all
+work, and tracebacks name the real file and line.
 
 ```html
-<code-playpad entry="main.py" height="260">
+<code-playpad entry="main.py" height="auto" max-height="420">
   <playpad-file name="main.py">
     from geometry import Circle
     print(Circle(1).area())
@@ -149,9 +259,34 @@ all work, and tracebacks name the real file and line.
 </code-playpad>
 ```
 
+JavaScript and TypeScript work the same way, including `.json` imported as data:
+
+```html
+<code-playpad language="javascript" entry="main.js" height="auto">
+  <playpad-file name="main.js">
+    import { total } from "./cart.js";
+    import items from "./items.json";
+
+    console.log(total(items));
+  </playpad-file>
+
+  <playpad-file name="cart.js">
+    export const total = (items) =>
+      items.reduce((sum, item) => sum + item.price, 0);
+  </playpad-file>
+
+  <playpad-file name="items.json">
+    [{ "price": 12 }, { "price": 30 }]
+  </playpad-file>
+</code-playpad>
+```
+
+A tab bar appears once there is more than one file, with `▸` marking the entry
+point, and each file keeps its own undo history. Editing a module takes effect
+on the next run — the import cache is cleared between runs.
+
 Highlighting follows the **file**, not the runtime: a `.json` beside your
 JavaScript is highlighted as JSON, a `.csv` beside your Python is plain text.
-`.json` files are importable as data, the same as in Node.
 
 ## Input
 
@@ -165,10 +300,299 @@ age? 36
 hello Ada, next year you turn 37
 ```
 
-`Enter` sends a line; **EOF** (or `Ctrl-D`) ends input. In JavaScript and
-TypeScript, `input()` is a global returning a promise, so `await` works at the
-top level. Echoed input is display-only — `Result.stdout` stays exactly what the
-program printed, so graders are unaffected.
+`Enter` sends a line; **EOF** (or `Ctrl-D`) ends input, which is how you finish
+a `while True:` loop.
+
+In JavaScript and TypeScript, `input()` is a global returning a promise, so
+`await` works at the top level:
+
+```html
+<code-playpad language="javascript" height="auto">
+  const name = await input("your name? ");
+  console.log(`hello ${name}`);
+</code-playpad>
+```
+
+To script the answers instead of typing them — useful for a worked example —
+pre-fill the box. Those lines are used before the reader is asked:
+
+```html
+<code-playpad height="auto" stdin>
+  name = input("name? ")
+  print("hi", name)
+</code-playpad>
+```
+
+```js
+document.querySelector('code-playpad').stdin = 'Ada\n36';
+```
+
+Echoed input is display-only: `stdout` stays exactly what the program printed,
+so graders are unaffected.
+
+Java does not read input yet; `Scanner` over the input box is planned.
+
+## Controlling it from JavaScript
+
+```js
+const pad = document.querySelector('code-playpad');
+
+pad.code = 'print("set from outside")';   // replace the visible file
+const source = pad.getCode();             // read it back
+const result = await pad.run();           // { stdout, stderr?, value?, durationMs }
+pad.reset();                              // back to the snippet the page shipped
+pad.stop();                               // stop this widget's run, queued or running
+await pad.prewarm();                      // boot the runtime before the reader runs anything
+```
+
+Multi-file widgets add:
+
+```js
+pad.files = {                             // replace the whole project
+  'main.py': 'from util import shout\nprint(shout("hi"))',
+  'util.py': 'def shout(s): return s.upper() + "!"'
+};
+pad.entry = 'main.py';                    // which file Run executes
+pad.openFile('util.py');                  // bring a tab on screen
+const everything = pad.getFiles();        // { name: contents }
+```
+
+`prewarm()` is worth calling when you know the reader is about to run something
+— on a lesson page, for instance — so the ~6 MB Python download starts before
+they press Run rather than after.
+
+## Events and grading
+
+Four events bubble and cross the shadow boundary, so answer-checking lives
+outside the widget rather than inside it:
+
+| event | `event.detail` |
+| --- | --- |
+| `py-ready` | `{ language, label }` — runtime booted |
+| `py-run` | `{ code, entry, files, language }` — a run started |
+| `py-output` | `{ stdout, stderr?, value?, table?, durationMs, language }` |
+| `py-error` | `{ message, hint?, language }` |
+
+A complete exercise check:
+
+```html
+<code-playpad id="ex1" height="auto" min-height="150" persist="ex1">
+  # Print the numbers 1 to 5, one per line.
+</code-playpad>
+<p id="ex1-result"></p>
+```
+
+```js
+const expected = '1\n2\n3\n4\n5\n';
+
+document.addEventListener('py-output', (event) => {
+  if (event.target.id !== 'ex1') return;
+
+  const el = document.getElementById('ex1-result');
+  if (event.detail.stderr) {
+    el.textContent = 'Your code raised an error — read the message above.';
+  } else if (event.detail.stdout === expected) {
+    el.textContent = '✅ Correct';
+  } else {
+    el.textContent = `❌ Expected ${JSON.stringify(expected)}, got ${JSON.stringify(event.detail.stdout)}`;
+  }
+});
+```
+
+`py-error` also carries a `hint` when the runtime can explain the failure in
+plain language — for example when a program calls `input()` more times than the
+standard-input box has lines.
+
+## Saving work
+
+`persist` stores the whole file map in IndexedDB, so a reader's edits survive
+navigation *and* a full reload:
+
+```html
+<code-playpad height="auto" persist="lesson-3-exercise-1">
+  # Your code here
+</code-playpad>
+```
+
+The page's file list stays authoritative: edits come back, but files you add or
+remove later follow the page, not the old snapshot.
+
+For a course you usually also want completion state, which the package exports:
+
+```js
+import { setProgress, getProgress, allProgress, loadSnippet, clearSnippet } from 'code-playpad';
+
+// mark a lesson done when its exercise passes
+document.addEventListener('py-output', async (event) => {
+  if (event.detail.stdout === expected) {
+    await setProgress('lesson-3', { completed: true, score: 100 });
+  }
+});
+
+await getProgress('lesson-3');   // { id, completed, score, updatedAt }
+await allProgress();             // every record, for a progress bar
+await loadSnippet('lesson-3-exercise-1');   // what the reader last wrote
+await clearSnippet('lesson-3-exercise-1');  // a "start over" button
+```
+
+All of it is per-browser: nothing leaves the reader's machine.
+
+## Light and dark
+
+`theme` takes `light`, `dark`, or `auto` (the default).
+
+```html
+<code-playpad theme="dark" height="auto">print("always dark")</code-playpad>
+<code-playpad theme="light" height="auto">print("always light")</code-playpad>
+<code-playpad height="auto">print("follows the page, then the OS")</code-playpad>
+```
+
+**`auto` follows your site first, the operating system second.** If your page
+has its own light/dark switch, the widget follows it as long as the switch sets
+`color-scheme` on the root element — which is how most themes are written:
+
+```css
+:root { color-scheme: light; }
+:root[data-theme="dark"] { color-scheme: dark; }
+```
+
+Flip `data-theme` (or a class, or an inline style) and every widget on the page
+re-themes itself. Nothing else to wire up. With no `color-scheme` on the page,
+`auto` falls back to the reader's OS setting via `prefers-color-scheme`.
+
+If your theme switch does *not* set `color-scheme`, drive the widgets directly:
+
+```js
+function setTheme(mode) {            // mode: 'light' | 'dark'
+  document.documentElement.dataset.theme = mode;
+  for (const pad of document.querySelectorAll('code-playpad')) {
+    pad.setAttribute('theme', mode);
+  }
+}
+```
+
+An explicit `theme` attribute always wins over the page, so a deliberately dark
+snippet stays dark on a light page.
+
+## Styling
+
+The widget lives in a shadow root, so page CSS cannot leak in — and its own
+styles cannot leak out. Two supported ways to restyle it.
+
+**Custom properties** inherit through the shadow boundary:
+
+```css
+code-playpad {
+  --cp-accent: #b5179e;     /* buttons, focus, the caret */
+  --cp-radius: 14px;
+  --cp-font-mono: "JetBrains Mono", monospace;
+}
+```
+
+| | |
+| --- | --- |
+| colours | `--cp-bg`, `--cp-fg`, `--cp-muted`, `--cp-border`, `--cp-surface` |
+| accents | `--cp-accent`, `--cp-accent-fg`, `--cp-danger`, `--cp-ok` |
+| shape and type | `--cp-radius`, `--cp-font-mono`, `--cp-font-ui` |
+
+**Parts** expose the pieces worth targeting:
+
+```css
+code-playpad::part(run-button) { border-radius: 999px; }
+code-playpad::part(stop-button) { font-weight: 700; }
+code-playpad::part(output) { background: #fff7fb; }
+code-playpad::part(tabs) { border-bottom-width: 2px; }
+```
+
+Both work from an ordinary stylesheet, no `::shadow` hacks. For dark mode, the
+`theme` attribute already follows the reader's OS by default.
+
+## Framework recipes
+
+**Astro** — put the import in a page or layout script; the element does the rest.
+
+```astro
+---
+// src/layouts/Lesson.astro
+---
+<script>
+  import 'code-playpad/element';
+</script>
+
+<code-playpad height="auto" persist={Astro.props.id}>
+  {Astro.props.code}
+</code-playpad>
+```
+
+**React** — the wrapper assigns props through a ref, so React 18 behaves like 19.
+
+```jsx
+import { useState } from 'react';
+import { CodePlayPad } from 'code-playpad/react';
+
+export function Exercise() {
+  const [passed, setPassed] = useState(false);
+
+  return (
+    <>
+      <CodePlayPad
+        language="python"
+        code={'# Your code here'}
+        height="auto"
+        minHeight={150}
+        persist="exercise-1"
+        onOutput={(r) => setPassed(r.stdout.trim() === '42')}
+      />
+      {passed && <p>✅ Correct</p>}
+    </>
+  );
+}
+```
+
+Props: `code`, `files`, `entry`, `language`, `height`, `stdin`, `theme`,
+`readOnly`, `autoRun`, `persist`, `className`, `style`, and the callbacks
+`onReady`, `onRun`, `onOutput`, `onError`.
+
+**Next.js** — the element is SSR-safe, so a plain import works in a client
+component:
+
+```jsx
+'use client';
+import 'code-playpad/element';
+
+export default function Lesson() {
+  return <code-playpad height="auto">{'print("hi")'}</code-playpad>;
+}
+```
+
+**Vue** — tell the compiler the tag is a custom element, then use it directly:
+
+```js
+// vite.config.js
+export default {
+  plugins: [vue({ template: { compilerOptions: { isCustomElement: (tag) => tag === 'code-playpad' } } })]
+};
+```
+
+**Plain HTML / Markdown** — the CDN tag plus the element. Because the code lives
+in the element's text content, the snippet is still readable if JavaScript never
+loads.
+
+## Production
+
+Serve Pyodide from your own origin so you control its cache headers, rather than
+depending on a public CDN:
+
+```js
+import { configurePython, pyodideAssetUrls } from 'code-playpad';
+
+configurePython({ indexURL: '/pyodide/' });   // before the first run
+pyodideAssetUrls();                            // the files worth <link rel=preload>-ing
+```
+
+`configureTypeScript({ sucraseURL })` does the same for the TypeScript
+transform. Give those files a long `Cache-Control`: one page's download then
+warms every other page on the site.
 
 ## Worth knowing
 
@@ -177,15 +601,93 @@ program printed, so graders are unaffected.
   single-threaded, so a second widget waits for the first.
 - **Runaway code cannot freeze the page.** Code runs in a Worker; **Stop**
   terminates and reboots it. Runs queued behind the stopped one survive.
+  Stopping a widget that is still `Queued…` just takes it out of the queue —
+  whatever is running keeps running.
 - **A program waiting on `input()` holds the shared runtime.** Other widgets
   show `Queued…` until it finishes or is stopped.
 - **Nothing boots on page load.** An IntersectionObserver starts a runtime as a
-  widget nears the viewport; touching the editor also wakes it.
+  widget nears the viewport; touching the editor also wakes it. Use `prewarm()`
+  to start earlier on purpose.
 - **Python in the browser has limits**: no threads, no `multiprocessing`, no
   sockets, no `subprocess`. `requests` works but goes through browser `fetch`,
   so CORS applies.
-- **Serve Pyodide from your own origin in production** so you control its cache
-  headers: `configurePython({ indexURL: '/pyodide/' })` before the first run.
+- **If CodeMirror fails to load**, the widget falls back to a plain textarea that
+  still runs code, rather than showing nothing.
+
+## Version history
+
+No breaking changes so far: markup and API written against 0.1.3 still work on
+0.3.0.
+
+### 0.3.0
+
+- **`language="java"`**: a documented subset of Java 25 — see [Java](#java).
+  The engine is a ~27 KB (gzipped) chunk loaded only by pages with a Java
+  widget; Python and JavaScript pages download the same as in 0.2.1 (see
+  [Download size](#download-size)). `@codemirror/lang-java` is a new optional
+  peer dependency for its highlighting.
+- **Fixed:** in JavaScript, a top-level `await` inside an expression
+  (`Number(await input())`) failed with `SyntaxError: missing ) after argument
+  list`; it only worked when the first `await` started a statement.
+- A hint about something other than input (a runaway loop, say) no longer opens
+  the standard-input box; only "input() asked for a line…" does.
+
+0.2.2 was never published; its fixes ship in 0.3.0:
+
+- **Fixed:** pressing **Stop** on a widget still showing `Queued…` stopped a
+  *different* widget — whichever one was running — and the queued run then
+  went ahead anyway. Stop now cancels only the widget's own run: a queued run is
+  dropped without touching the worker, and only a run that is actually
+  executing kills and reboots it. `pad.stop()` on an idle widget no longer
+  affects anyone else.
+- **Fixed:** stopping a run while the runtime was rebooting from an earlier
+  Stop could wedge the queue — every later run sat at `Queued…` forever.
+- `Runtime.stop()` takes an optional argument: the promise `run()` returned,
+  to stop just that run. With no argument it behaves as before.
+- **Fixed:** a line printed just before an infinite loop (`print("started")`
+  then `while True: pass`) never appeared — output batching held it back, and
+  the loop never let the worker send it. The first lines of any burst are now
+  sent immediately, in Python and JavaScript; large outputs are still batched.
+- The JavaScript/TypeScript worker is now minified in `dist/` like the Python
+  one; it previously shipped as readable source, comments included. The
+  `javascript` chunk drops from about 12KB to about 7KB.
+
+### 0.2.1
+
+- `theme="auto"` now follows the **page** before the operating system: if your
+  site's light/dark switch sets `color-scheme` on the root, widgets re-theme
+  with it. Previously a page could go dark while every widget stayed light.
+- `minHeight` and `maxHeight` props on the React wrapper — 0.2.0 added them as
+  attributes but missed the wrapper.
+- README expanded into full usage documentation: entry points, an example per
+  attribute, programmatic control, a complete grading example, the progress
+  store, styling, and framework recipes.
+
+### 0.2.0
+
+- `height="auto"` is a supported content-fitting mode. It previously worked by
+  accident and could have broken silently.
+- New `min-height` and `max-height` attributes. `max-height` scrolls rather than
+  clipping; `min-height` grows the editor itself, so the empty space below a
+  short snippet is still clickable — what an exercise answer box needs.
+
+### 0.1.4
+
+- **Fixed:** a `<pre>` or other wrapper on its own line leaked its indentation
+  into the program, so two-line snippets failed with `IndentationError` while
+  single-line ones looked fine.
+- **Fixed:** `sideEffects` named the re-export shims rather than the chunk that
+  registers the element, so a bundler could legitimately drop it and
+  `<code-playpad>` would never register in a production build.
+- No runtime dependencies (an analytics package used only by the demo had crept
+  into `dependencies`).
+
+### 0.1.3
+
+- Relicensed **MIT**. Earlier versions were published as `UNLICENSED`, which
+  granted nobody the right to use them.
+
+Versions 0.1.0 to 0.1.2 were withdrawn and are not installable.
 
 ## Licence
 
@@ -196,3 +698,8 @@ it, modify it. Bundled third-party components (CodeMirror 6, Lezer) remain under
 their own MIT licences, reproduced in full in `dist/THIRD-PARTY-NOTICES.txt`.
 Pyodide (MPL-2.0) is fetched from a CDN at runtime and is not redistributed by
 this package.
+
+The Java engine is original code under the same MIT licence. Java is a trademark
+of Oracle and/or its affiliates; code-playpad is not affiliated with, endorsed
+by, or certified by Oracle, and its Java support is a documented subset, not a
+Java implementation.