Skip to content

The animation engine for agents: blazingly fast math and 3D videos with Manim's Python API, on a Rust GPU core.

Python

Package browser engine and player

Sina Atalayf888ec2fee2d
diff --git a/browser/.prettierrc.json b/browser/.prettierrc.json
new file mode 100644
index 00000000..de753c53
--- /dev/null
+++ b/browser/.prettierrc.json
@@ -0,0 +1,3 @@
+{
+ "printWidth": 100
+}
diff --git a/browser/README.md b/browser/README.md
new file mode 100644
index 00000000..e796ae20
--- /dev/null
+++ b/browser/README.md
@@ -0,0 +1,55 @@
+# manimgx
+
+[manimgx](https://manimgx.academa.ai/) in the browser: a scene written in Python, with Manim
+Community Edition's API, made and played in the page by manimgx's own player, drawn with
+WebGPU.
+
+```sh
+npm install manimgx
+```
+
+```html
+<script type="module">
+ import "manimgx";
+</script>
+
+<manimgx-player autoplay>
+ <script type="text/python">
+ import manimgx as m
+
+ class Euler(m.Scene):
+ def construct(self):
+ circle = m.Circle(color=m.BLUE, fill_opacity=0.5)
+ self.play(m.Create(circle), m.Write(m.MathTex(r"e^{i\pi} + 1 = 0").next_to(circle, m.DOWN)))
+ </script>
+</manimgx-player>
+```
+
+Or from JavaScript:
+
+```js
+import "manimgx";
+
+const player = document.createElement("manimgx-player");
+player.source = code; // a Python module; set it again, and the film is made again, the time kept
+document.body.append(player);
+```
+
+- **Python, in the page.** [Pyodide](https://pyodide.org) runs the scene in a Web Worker, with
+ manimgx installed from PyPI (the same version as this package). Nothing runs on a server.
+- **manimgx's own player**, the one `manimgx preview` plays a file in: the engine compiled to
+ WebAssembly draws the film with WebGPU, and its face over it: the controls, the time, the
+ timeline in the scene's plays (each named by its line of code), captions, the scene's error
+ and the keys (`?` lists them), all in manimgx's fonts. A click, a tap and a key do the same.
+- **Any frame, at once**: the film is recorded as it is made (a *take*: each shape once, then
+ each frame), and any moment of it is drawn at once, so it plays before the scene has
+ finished and seeks instantly. Each frame is drawn at the size the page shows it, in the
+ screen's own pixels: sharp at any size, full screen too.
+- **For scripts**: `play()`, `pause()`, `paused`, `currentTime`, `duration`, and `scene`.
+
+The first film downloads Python (Pyodide, about 6 MB) and manimgx (about 20 MB); the browser
+keeps both. It needs WebGPU: Chrome and Edge 113+, Safari 26, Firefox 141+ on Windows (not yet
+with the float32 blending manimgx's renderer uses).
+
+One file, no dependencies, any bundler. On the command line, `manimgx preview scene.py` plays a
+scene file in a window of its own: the same player.
diff --git a/browser/build.ts b/browser/build.ts
new file mode 100644
index 00000000..d3ab6c4b
--- /dev/null
+++ b/browser/build.ts
@@ -0,0 +1,35 @@
+import { rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(fileURLToPath(import.meta.url));
+const output = join(root, "dist");
+const { version } = (await Bun.file(join(root, "package.json")).json()) as {
+ version: string;
+};
+
+// Compile the worker before putting its source in the player's single-file bundle.
+const director = await Bun.build({
+ entrypoints: [join(root, "src/director.ts")],
+ target: "browser",
+ format: "esm",
+ minify: true,
+});
+if (!director.success) throw new AggregateError(director.logs, "Could not build the director");
+const worker = director.outputs[0];
+if (!worker) throw new Error("The director build produced no JavaScript");
+
+await rm(output, { recursive: true, force: true });
+const player = await Bun.build({
+ entrypoints: [join(root, "src/index.ts")],
+ target: "browser",
+ format: "esm",
+ minify: true,
+ outdir: output,
+ naming: "manimgx.js",
+ define: {
+ VERSION: JSON.stringify(version),
+ DIRECTOR: JSON.stringify(await worker.text()),
+ },
+});
+if (!player.success) throw new AggregateError(player.logs, "Could not build the player");
diff --git a/browser/bun.lock b/browser/bun.lock
new file mode 100644
index 00000000..31689333
--- /dev/null
+++ b/browser/bun.lock
@@ -0,0 +1,67 @@
+{
+ "lockfileVersion": 1,
+ "configVersion": 1,
+ "workspaces": {
+ "": {
+ "name": "manimgx",
+ "devDependencies": {
+ "@types/bun": "1.4.2",
+ "prettier": "3.9.9",
+ "typescript": "7.0.2",
+ },
+ },
+ },
+ "packages": {
+ "@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.4.2" } }, "sha512-GimotNn7+ZV0uVArItBbriZsR1oNf0+WTzPkdcFrzShI7k2norL0uzEaJT8T33dWr7O/c9ZDuAFQrctKCi72oQ=="],
+
+ "@types/node": ["@types/[email protected]", "", { "dependencies": { "undici-types": "~8.9.0" } }, "sha512-ldVPDCzj7fsaGZrLB0NuHuTvJcsNasysBAqMolr/cgxrLd1xbqxIr3XJiPnHHJUCxj5sNF1vnRj9aWnrVh5Jcg=="],
+
+ "@typescript/typescript-aix-ppc64": ["@typescript/[email protected]", "", { "os": "aix", "cpu": "ppc64" }, "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ=="],
+
+ "@typescript/typescript-darwin-arm64": ["@typescript/[email protected]", "", { "os": "darwin", "cpu": "arm64" }, "sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA=="],
+
+ "@typescript/typescript-darwin-x64": ["@typescript/[email protected]", "", { "os": "darwin", "cpu": "x64" }, "sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA=="],
+
+ "@typescript/typescript-freebsd-arm64": ["@typescript/[email protected]", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ=="],
+
+ "@typescript/typescript-freebsd-x64": ["@typescript/[email protected]", "", { "os": "freebsd", "cpu": "x64" }, "sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw=="],
+
+ "@typescript/typescript-linux-arm": ["@typescript/[email protected]", "", { "os": "linux", "cpu": "arm" }, "sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ=="],
+
+ "@typescript/typescript-linux-arm64": ["@typescript/[email protected]", "", { "os": "linux", "cpu": "arm64" }, "sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ=="],
+
+ "@typescript/typescript-linux-loong64": ["@typescript/[email protected]", "", { "os": "linux", "cpu": "none" }, "sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ=="],
+
+ "@typescript/typescript-linux-mips64el": ["@typescript/[email protected]", "", { "os": "linux", "cpu": "none" }, "sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA=="],
+
+ "@typescript/typescript-linux-ppc64": ["@typescript/[email protected]", "", { "os": "linux", "cpu": "ppc64" }, "sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA=="],
+
+ "@typescript/typescript-linux-riscv64": ["@typescript/[email protected]", "", { "os": "linux", "cpu": "none" }, "sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ=="],
+
+ "@typescript/typescript-linux-s390x": ["@typescript/[email protected]", "", { "os": "linux", "cpu": "s390x" }, "sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw=="],
+
+ "@typescript/typescript-linux-x64": ["@typescript/[email protected]", "", { "os": "linux", "cpu": "x64" }, "sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A=="],
+
+ "@typescript/typescript-netbsd-arm64": ["@typescript/[email protected]", "", { "os": "none", "cpu": "arm64" }, "sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA=="],
+
+ "@typescript/typescript-netbsd-x64": ["@typescript/[email protected]", "", { "os": "none", "cpu": "x64" }, "sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA=="],
+
+ "@typescript/typescript-openbsd-arm64": ["@typescript/[email protected]", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ=="],
+
+ "@typescript/typescript-openbsd-x64": ["@typescript/[email protected]", "", { "os": "openbsd", "cpu": "x64" }, "sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg=="],
+
+ "@typescript/typescript-sunos-x64": ["@typescript/[email protected]", "", { "os": "sunos", "cpu": "x64" }, "sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g=="],
+
+ "@typescript/typescript-win32-arm64": ["@typescript/[email protected]", "", { "os": "win32", "cpu": "arm64" }, "sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ=="],
+
+ "@typescript/typescript-win32-x64": ["@typescript/[email protected]", "", { "os": "win32", "cpu": "x64" }, "sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g=="],
+
+ "bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-bxV1FgK7yBIzjRe5zBozIM4Bem11ZJcCXSrjWRG3YWLt8yFDePu4cLjpebO8OvPeIE9trbyPF4fuj3Cia4Fj3w=="],
+
+ "prettier": ["[email protected]", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-Z/CJHIkdujO/OtN7nXUii0Rf3VT5SRuhjBA82Xvu2XhBUgX3nhP67T0LHceBdQLex7OOFGTox+Q5Yg8Jk2Qivg=="],
+
+ "typescript": ["[email protected]", "", { "optionalDependencies": { "@typescript/typescript-aix-ppc64": "7.0.2", "@typescript/typescript-darwin-arm64": "7.0.2", "@typescript/typescript-darwin-x64": "7.0.2", "@typescript/typescript-freebsd-arm64": "7.0.2", "@typescript/typescript-freebsd-x64": "7.0.2", "@typescript/typescript-linux-arm": "7.0.2", "@typescript/typescript-linux-arm64": "7.0.2", "@typescript/typescript-linux-loong64": "7.0.2", "@typescript/typescript-linux-mips64el": "7.0.2", "@typescript/typescript-linux-ppc64": "7.0.2", "@typescript/typescript-linux-riscv64": "7.0.2", "@typescript/typescript-linux-s390x": "7.0.2", "@typescript/typescript-linux-x64": "7.0.2", "@typescript/typescript-netbsd-arm64": "7.0.2", "@typescript/typescript-netbsd-x64": "7.0.2", "@typescript/typescript-openbsd-arm64": "7.0.2", "@typescript/typescript-openbsd-x64": "7.0.2", "@typescript/typescript-sunos-x64": "7.0.2", "@typescript/typescript-win32-arm64": "7.0.2", "@typescript/typescript-win32-x64": "7.0.2" }, "bin": { "tsc": "bin/tsc" } }, "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA=="],
+
+ "undici-types": ["[email protected]", "", {}, "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg=="],
+ }
+}
diff --git a/browser/package.json b/browser/package.json
new file mode 100644
index 00000000..3cbb35cb
--- /dev/null
+++ b/browser/package.json
@@ -0,0 +1,53 @@
+{
+ "name": "manimgx",
+ "version": "0.0.0",
+ "description": "The animation engine for agents, in the browser: blazingly fast math and 3D videos with Manim's Python API, run by Pyodide in a Web Worker, on a Rust GPU core with WebGPU.",
+ "type": "module",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "default": "./dist/manimgx.js"
+ },
+ "./package.json": "./package.json"
+ },
+ "types": "./dist/index.d.ts",
+ "files": [
+ "dist"
+ ],
+ "scripts": {
+ "check": "bun run format:check && tsc --project tsconfig.json && tsc --project tsconfig.worker.json && tsc --project tsconfig.build.json",
+ "format": "prettier --write src tests build.ts '*.json'",
+ "format:check": "prettier --check src tests build.ts '*.json'",
+ "build": "bun run check && bun run build.ts && tsc --project tsconfig.json --noEmit false --declaration --emitDeclarationOnly --outDir dist",
+ "test": "bun run build && bun test tests && bun run test:types",
+ "test:types": "tsc --project tests/tsconfig.json"
+ },
+ "devDependencies": {
+ "@types/bun": "1.4.2",
+ "prettier": "3.9.9",
+ "typescript": "7.0.2"
+ },
+ "license": "MIT",
+ "author": "Academa, Inc.",
+ "contributors": [
+ "Sina Atalay <[email protected]>",
+ "Abdullah Geduk <[email protected]>"
+ ],
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/academa-labs/manimgx.git",
+ "directory": "browser"
+ },
+ "homepage": "https://manimgx.academa.ai/",
+ "keywords": [
+ "manim",
+ "manimgx",
+ "animation",
+ "math",
+ "python",
+ "pyodide",
+ "webgpu",
+ "video",
+ "player"
+ ]
+}
diff --git a/browser/src/index.ts b/browser/src/index.ts
new file mode 100644
index 00000000..bb933df3
--- /dev/null
+++ b/browser/src/index.ts
@@ -0,0 +1,14 @@
+// manimgx in the browser: <manimgx-player>, a scene written in Python, run by Pyodide and played by
+// manimgx's own player, drawn with WebGPU. manimgx itself comes from PyPI, the version of this
+// package. This file is all of it: its worker is inside it, so any bundler (or none) can take it.
+
+import { define, runtime, settings } from "./player.js";
+
+declare const VERSION: string;
+declare const DIRECTOR: string;
+
+runtime.worker = () => URL.createObjectURL(new Blob([DIRECTOR], { type: "text/javascript" }));
+settings.manimgx = `manimgx==${VERSION}`;
+define();
+
+export { ManimgxPlayer, settings } from "./player.js";
diff --git a/browser/src/player.ts b/browser/src/player.ts
new file mode 100644
index 00000000..60edef74
--- /dev/null
+++ b/browser/src/player.ts
@@ -0,0 +1,387 @@
+// <manimgx-player>: manimgx's player in the page. The engine's own player, the one `manimgx
+// preview`'s window is, compiled to WebAssembly: it draws the film and its face (the controls, the
+// time, the plays, captions, the scene's error, the keys) onto a canvas with WebGPU, and keeps the
+// clock and the sound. The element only hands it what its viewer does, in the web's own words,
+// draws it when it is due, and does what it asks (another scene, full screen). Its scene is
+// Python, run in the browser by Pyodide (see director.ts).
+//
+// <manimgx-player><script type="text/python"> …a scene… </script></manimgx-player>
+// player.source = code (the film made again, time kept)
+
+import type { Engine, Player } from "./engine.js";
+import { message } from "./protocol.js";
+import type { FromDirector, ToDirector } from "./protocol.js";
+
+const PYODIDE = "https://cdn.jsdelivr.net/pyodide/v314.0.7/full/";
+const MAC = /Mac|iPhone|iPad/.test(navigator.platform);
+
+/** Where Pyodide and manimgx come from (set before the first film starts). */
+export const settings = {
+ /** Pyodide's files (its `indexURL`). */
+ pyodide: PYODIDE,
+ /** What micropip installs: `manimgx==<this version>` from PyPI, or a wheel's URL. */
+ manimgx: "manimgx",
+};
+
+/** The entry point supplies the bundled director's script. */
+export const runtime = {
+ worker: (): string | URL => new URL("./director.js", import.meta.url),
+};
+
+interface PagePlayer {
+ wait(): void;
+ feed(bytes: ArrayBuffer): void;
+}
+
+interface Page {
+ director: Worker;
+ players: Map<number, PagePlayer>;
+ engine: Promise<Engine>;
+ status: string;
+}
+
+let page: Page | undefined; // the page's director, its engine (once it is up), and its players
+
+function send(director: Worker, data: ToDirector): void {
+ director.postMessage(data);
+}
+
+/** The page's director (Pyodide, in a worker) and engine, begun once. */
+function begin(): Page {
+ if (page) return page;
+ const director = new Worker(runtime.worker(), { type: "module" });
+ const players = new Map<number, PagePlayer>();
+ let up: (engine: Engine) => void = () => {};
+ const current: Page = {
+ director,
+ players,
+ engine: new Promise((resolve) => (up = resolve)),
+ status: "Loading Python…",
+ };
+ page = current;
+ director.onmessage = async ({ data }: MessageEvent<FromDirector>) => {
+ if ("status" in data) {
+ current.status = data.status;
+ for (const player of players.values()) player.wait();
+ }
+ if ("engine" in data) {
+ // the player, from the manimgx the director installed: its JS, its WebAssembly, the fonts
+ // its face is set in
+ const { js, wasm, fonts } = data.engine;
+ try {
+ const engine = (await import(
+ URL.createObjectURL(new Blob([js], { type: "text/javascript" }))
+ )) as Engine;
+ await engine.default({ module_or_path: wasm });
+ await engine.init(fonts);
+ up(engine);
+ } catch (error) {
+ current.status = `manimgx can't draw here: ${message(error)}`;
+ for (const player of players.values()) player.wait();
+ }
+ }
+ if ("film" in data) players.get(data.film)?.feed(data.feed);
+ };
+ send(director, { boot: { pyodide: settings.pyodide, manimgx: settings.manimgx } });
+ return page;
+}
+
+let films = 0;
+
+/** A scene written in Python, made in the page and played on a canvas by manimgx's engine,
+ * with the engine's own controls. */
+export class ManimgxPlayer extends HTMLElement {
+ static observedAttributes = ["scene"];
+
+ #film = ++films;
+ #canvas: HTMLCanvasElement;
+ #said: HTMLParagraphElement;
+ #source: string | null = null;
+ #backlog: ArrayBuffer[] = []; // the director's bytes that came before the player
+ #wants: { time: number; playing: boolean | null } = { time: 0, playing: null };
+ #begun = false;
+ #failed = false;
+ #player: Player | null = null;
+ #timer: number | undefined;
+ #frame = 0;
+ #root: ShadowRoot;
+
+ constructor() {
+ super();
+ this.#root = this.attachShadow({ mode: "open" });
+ this.#root.innerHTML = `<style>
+ :host { display: block; position: relative; aspect-ratio: var(--film, 16 / 9); background: #000; outline: none; contain: content; }
+ canvas { position: absolute; inset: 0; width: 100%; height: 100%; touch-action: pan-y; }
+ p { position: absolute; inset: 0; margin: auto; height: 1.5em; text-align: center; color: #fffb; font: 15px system-ui, sans-serif; }
+ </style><canvas></canvas><p></p>`;
+ const canvas = this.#root.querySelector("canvas");
+ const said = this.#root.querySelector("p");
+ if (!canvas || !said) throw new Error("The player's canvas and status are missing");
+ this.#canvas = canvas;
+ this.#said = said; // what it waits for, until the engine is up
+ }
+
+ connectedCallback(): void {
+ if (!this.hasAttribute("tabindex")) this.tabIndex = 0; // it takes keys
+ // begun a task later: a page can still set `settings` after importing this
+ if (!this.#begun) setTimeout(() => this.isConnected && !this.#begun && this.#begin());
+ }
+
+ disconnectedCallback(): void {
+ if (this.#player) this.pause();
+ }
+
+ attributeChangedCallback(): void {
+ if (this.#begun && this.#source !== null) this.#run();
+ }
+
+ /** The scene's Python source: set it, and the film is made again (the time kept). */
+ get source(): string | null {
+ return this.#source;
+ }
+ set source(code: string | null) {
+ this.#source = code == null ? null : String(code);
+ if (this.#begun && this.#source !== null) this.#run();
+ }
+
+ /** The scene shown (a file may define several; N and P go through them). Another scene starts
+ * at its beginning. */
+ get scene(): string | null {
+ return this.#player?.scene ?? this.getAttribute("scene");
+ }
+ set scene(name: string | null) {
+ this.currentTime = 0;
+ if (name == null) this.removeAttribute("scene");
+ else this.setAttribute("scene", name);
+ }
+
+ /** Seconds. */
+ get currentTime(): number {
+ return this.#player?.time ?? this.#wants.time;
+ }
+ set currentTime(t: number) {
+ if (!Number.isFinite(Number(t))) return;
+ if (this.#player) this.#player.time = Number(t);
+ else this.#wants.time = Number(t);
+ this.#after();
+ }
+ /** Seconds made so far; NaN before the film's first frame. */
+ get duration(): number {
+ return this.#player?.film ? this.#player.duration : NaN;
+ }
+ get paused(): boolean {
+ return this.#player
+ ? !this.#player.playing
+ : !(this.#wants.playing ?? this.hasAttribute("autoplay"));
+ }
+ play(): void {
+ if (this.#player) this.#player.play();
+ else this.#wants.playing = true;
+ this.#after();
+ }
+ pause(): void {
+ if (this.#player) this.#player.pause();
+ else this.#wants.playing = false;
+ this.#after();
+ }
+
+ // ── the player ─────────────────────────────────────────────────────────────────────────
+
+ async #begin(): Promise<void> {
+ this.#begun = true;
+ const script = this.querySelector('script[type="text/python"]');
+ if (script && this.#source === null) this.#source = dedent(script.textContent);
+ const { players, engine } = begin();
+ players.set(this.#film, { wait: () => this.#wait(), feed: (bytes) => this.#feed(bytes) });
+ this.#wait();
+ if (this.#source !== null) this.#run();
+ const canvas = this.#canvas;
+ const box = canvas.getBoundingClientRect();
+ [canvas.width, canvas.height] = [
+ Math.max(1, Math.round(box.width * devicePixelRatio)),
+ Math.max(1, Math.round(box.height * devicePixelRatio)),
+ ];
+ const made = await engine;
+ if (this.#failed) return;
+ try {
+ const { time, playing } = this.#wants;
+ this.#player = new made.Player(canvas, time, playing ?? this.hasAttribute("autoplay"), MAC);
+ this.#player.resize(canvas.width, canvas.height, devicePixelRatio);
+ } catch (error) {
+ return this.#fail(error);
+ }
+ this.#said.remove();
+ this.#wire();
+ for (const bytes of this.#backlog.splice(0)) this.#feed(bytes);
+ this.#after();
+ }
+
+ #wait(): void {
+ if (!this.#player && !this.#failed) this.#said.textContent = begin().status;
+ }
+
+ #fail(error: unknown): void {
+ this.#player = null;
+ this.#failed = true;
+ this.#backlog = [];
+ this.#said.textContent = message(error);
+ this.#root.append(this.#said);
+ }
+
+ #run(): void {
+ if (this.#source === null) return;
+ send(begin().director, {
+ film: this.#film,
+ run: { source: this.#source, scene: this.getAttribute("scene") },
+ });
+ }
+
+ #feed(bytes: ArrayBuffer): void {
+ if (this.#failed) return;
+ if (!this.#player) {
+ this.#backlog.push(bytes);
+ return;
+ }
+ try {
+ this.#player.feed(new Uint8Array(bytes));
+ } catch (error) {
+ return this.#fail(error);
+ }
+ // the film's own proportions (unless the page sizes the player itself)
+ const film = this.#player.film;
+ if (film) this.style.setProperty("--film", `${film[0]} / ${film[1]}`);
+ this.#after();
+ }
+
+ /** What the viewer does, handed on as the web has it; what the player takes, the page doesn't. */
+ #wire(): void {
+ const p = this.#player,
+ canvas = this.#canvas;
+ if (!p) return;
+ const at = (e: PointerEvent): [number, number] => {
+ const box = canvas.getBoundingClientRect();
+ return [
+ (e.clientX - box.left) * (canvas.width / box.width),
+ (e.clientY - box.top) * (canvas.height / box.height),
+ ];
+ };
+ // an event handed on (while this player is the element's: not after it failed), the default
+ // action prevented if the player took it
+ const on = <K extends keyof HTMLElementEventMap>(
+ target: Pick<HTMLElement, "addEventListener">,
+ type: K,
+ hand: (event: HTMLElementEventMap[K]) => boolean | void,
+ options?: AddEventListenerOptions,
+ ): void =>
+ target.addEventListener(
+ type,
+ (e) => {
+ if (this.#player !== p) return;
+ if (hand(e)) e.preventDefault();
+ this.#after();
+ },
+ options,
+ );
+ let pressed: number | null = null; // the pointer that pressed: one at a time, its primary button or finger
+ on(this, "keydown", (e) => p.key(e.key, e.ctrlKey, e.altKey, e.metaKey));
+ on(canvas, "pointermove", (e) => p.pointer(...at(e)));
+ on(canvas, "pointerdown", (e) => {
+ if (pressed !== null || e.button !== 0 || !e.isPrimary) return false;
+ pressed = e.pointerId;
+ this.focus({ preventScroll: true });
+ canvas.setPointerCapture(e.pointerId);
+ return p.press(...at(e), e.pointerType === "touch");
+ });
+ const end = (e: PointerEvent, ended: () => boolean | void): boolean | void => {
+ if (e.pointerId !== pressed) return false;
+ pressed = null;
+ return ended();
+ };
+ on(canvas, "pointerup", (e) => end(e, () => p.release()));
+ on(canvas, "pointercancel", (e) => end(e, () => p.cancel()));
+ on(canvas, "pointerleave", () => p.leave());
+ on(
+ canvas,
+ "wheel",
+ (e) => {
+ const unit = [1, 20, canvas.clientHeight][e.deltaMode] ?? 1; // pixels, lines (as a window's), pages
+ return p.wheel(e.deltaX * unit, e.deltaY * unit);
+ },
+ { passive: false },
+ );
+ on(document, "fullscreenchange", () => p.fullscreen(document.fullscreenElement === this));
+ // drawn at the size the page shows it, in the screen's own pixels: sharp at any size
+ new ResizeObserver(([entry]) => {
+ if (!entry) return;
+ const box = entry.devicePixelContentBoxSize?.[0];
+ const css = entry.contentBoxSize[0];
+ if (!css) return;
+ const w = box ? box.inlineSize : Math.round(css.inlineSize * devicePixelRatio);
+ const h = box ? box.blockSize : Math.round(css.blockSize * devicePixelRatio);
+ if (this.#player !== p) return;
+ p.resize(w, h, w / css.inlineSize);
+ this.#after();
+ }).observe(canvas);
+ // out of sight, it draws nothing (its clock and sound go on)
+ new IntersectionObserver(([entry]) => {
+ if (!entry) return;
+ if (this.#player !== p) return;
+ p.hide(!entry.isIntersecting);
+ this.#after();
+ }).observe(this);
+ }
+
+ /** What the player asks (its director to run another scene, full screen), its cursor, and its
+ * next picture, when it is due. */
+ #after(): void {
+ const p = this.#player;
+ if (!p) return;
+ for (const [ask, value] of p.asks()) {
+ if (ask === "scene") {
+ this.setAttribute("scene", value);
+ } else if (ask === "fullscreen") {
+ if (value)
+ this.requestFullscreen?.().catch(() => {}); // refused: not full screen
+ else if (document.fullscreenElement === this) document.exitFullscreen();
+ }
+ }
+ this.#canvas.style.cursor = p.cursor;
+ clearTimeout(this.#timer);
+ let wake;
+ try {
+ wake = p.wake();
+ } catch (error) {
+ return this.#fail(error);
+ }
+ if (wake === 0) this.#frame ||= requestAnimationFrame(() => this.#draw());
+ else if (wake > 0) this.#timer = setTimeout(() => this.#after(), wake);
+ }
+
+ #draw(): void {
+ this.#frame = 0;
+ try {
+ this.#player?.draw();
+ } catch (error) {
+ return this.#fail(error);
+ }
+ this.#after();
+ }
+}
+
+/** Python written indented in HTML, as the file it is. */
+function dedent(text: string): string {
+ const lines = text.replace(/^\n+|\s+$/g, "").split("\n");
+ const indent = Math.min(...lines.filter((l) => l.trim()).map((l) => l.search(/\S/)));
+ return lines.map((l) => l.slice(indent)).join("\n") + "\n";
+}
+
+/** Define <manimgx-player> (once `settings` are as they should be). */
+export function define(): void {
+ customElements.get("manimgx-player") ?? customElements.define("manimgx-player", ManimgxPlayer);
+}
+
+declare global {
+ interface HTMLElementTagNameMap {
+ "manimgx-player": ManimgxPlayer;
+ }
+}
diff --git a/browser/tests/api.ts b/browser/tests/api.ts
new file mode 100644
index 00000000..6e560879
--- /dev/null
+++ b/browser/tests/api.ts
@@ -0,0 +1,30 @@
+// Compile this like a consumer of the published declarations, without the package's source.
+import { ManimgxPlayer, settings } from "manimgx";
+
+const player: ManimgxPlayer = document.createElement("manimgx-player");
+player.source = "class Demo(Scene): pass";
+player.source = null;
+player.scene = "Demo";
+player.scene = null;
+player.currentTime = 1.5;
+player.play();
+player.pause();
+const duration: number = player.duration;
+const paused: boolean = player.paused;
+const source: string | null = player.source;
+const scene: string | null = player.scene;
+settings.pyodide = "https://example.test/pyodide/";
+settings.manimgx = "https://example.test/manimgx.whl";
+
+// @ts-expect-error Python source must be text.
+player.source = 1;
+// @ts-expect-error Playback positions use seconds as numbers.
+player.currentTime = "1.5";
+// @ts-expect-error Duration is reported by the engine and is read-only.
+player.duration = 10;
+// @ts-expect-error Call play() or pause() to change playback.
+player.paused = true;
+// @ts-expect-error Package requirements and wheel URLs are strings.
+settings.manimgx = 1;
+
+void [duration, paused, source, scene];
diff --git a/browser/tests/browser.test.ts b/browser/tests/browser.test.ts
new file mode 100644
index 00000000..9257b51b
--- /dev/null
+++ b/browser/tests/browser.test.ts
@@ -0,0 +1,308 @@
+import { describe, expect, test } from "bun:test";
+import { readFile } from "node:fs/promises";
+import { createContext, SourceTextModule, SyntheticModule } from "node:vm";
+import type * as BrowserAPI from "../dist/index.js";
+
+const bundle = await readFile(new URL("../dist/manimgx.js", import.meta.url), "utf8");
+const packageJSON = (await Bun.file(new URL("../package.json", import.meta.url)).json()) as {
+ version: string;
+};
+
+// Each page gets its own globals and module, just as separate browser tabs do. Loading the
+// emitted file also catches packaging mistakes that importing the TypeScript source misses.
+async function page(script: string | null = null) {
+ const tasks: (() => void)[] = [];
+ const blobs: Blob[] = [];
+ const elements = new Map<string, unknown>();
+ const workers: Director[] = [];
+ const waiting = { textContent: "", remove() {} };
+ const canvas = {
+ width: 0,
+ height: 0,
+ getBoundingClientRect: () => ({ width: 320, height: 180 }),
+ };
+
+ class Element extends EventTarget {
+ isConnected = true;
+ tabIndex = -1;
+ attributes = new Map<string, string>();
+ shadowRoot = {
+ innerHTML: "",
+ querySelector: (selector: string) => (selector === "canvas" ? canvas : waiting),
+ append() {},
+ };
+ attachShadow() {
+ return this.shadowRoot;
+ }
+ querySelector() {
+ return script === null ? null : { textContent: script };
+ }
+ hasAttribute(name: string) {
+ return this.attributes.has(name);
+ }
+ getAttribute(name: string) {
+ return this.attributes.get(name) ?? null;
+ }
+ setAttribute(name: string, value: string) {
+ this.attributes.set(name, value);
+ this.attributeChangedCallback();
+ }
+ removeAttribute(name: string) {
+ this.attributes.delete(name);
+ this.attributeChangedCallback();
+ }
+ attributeChangedCallback() {}
+ }
+
+ class Director {
+ sent: unknown[] = [];
+ onmessage: ((event: { data: unknown }) => Promise<void>) | null = null;
+ constructor(
+ readonly url: string,
+ readonly options: WorkerOptions,
+ ) {
+ workers.push(this);
+ }
+ postMessage(data: unknown) {
+ this.sent.push(data);
+ }
+ }
+
+ const context = createContext({
+ HTMLElement: Element,
+ navigator: { platform: "Linux" },
+ customElements: {
+ get: (name: string) => elements.get(name),
+ define: (name: string, value: unknown) => elements.set(name, value),
+ },
+ Worker: Director,
+ Blob,
+ URL: class extends URL {
+ static override createObjectURL(blob: Blob) {
+ blobs.push(blob);
+ return `blob:test/${blobs.length}`;
+ }
+ },
+ devicePixelRatio: 2,
+ setTimeout: (callback: () => void) => tasks.push(callback),
+ });
+ const module = new SourceTextModule(bundle, { context });
+ await module.link(() => {
+ throw new Error("The published player must be one self-contained module");
+ });
+ await module.evaluate();
+ const api = module.namespace as typeof BrowserAPI;
+ return {
+ api,
+ blobs,
+ elements,
+ workers,
+ waiting,
+ canvas,
+ flush: () => tasks.splice(0).forEach((task) => task()),
+ };
+}
+
+async function settle() {
+ // Boot, micropip installation and queued runs all yield to promises. The worker's explicit
+ // task boundary stays under the test's control, so these checks don't depend on wall time.
+ for (let i = 0; i < 30; i++) await Promise.resolve();
+}
+
+describe("published browser module", () => {
+ test("registers the public element and pins the Python package to its own version", async () => {
+ const { api, elements, workers } = await page();
+ expect(elements.get("manimgx-player")).toBe(api.ManimgxPlayer);
+ expect(api.settings.manimgx).toBe(`manimgx==${packageJSON.version}`);
+ expect(workers).toHaveLength(0);
+ });
+
+ test("keeps playback requests made before the engine arrives", async () => {
+ const { api } = await page();
+ const player = new api.ManimgxPlayer();
+ expect(player.source).toBeNull();
+ expect(player.scene).toBeNull();
+ expect(player.duration).toBeNaN();
+ expect(player.paused).toBe(true);
+ player.setAttribute("autoplay", "");
+ expect(player.paused).toBe(false);
+ player.pause();
+ expect(player.paused).toBe(true);
+ player.play();
+ expect(player.paused).toBe(false);
+ player.currentTime = 2.5;
+ player.currentTime = NaN;
+ player.currentTime = Infinity;
+ expect(player.currentTime).toBe(2.5);
+ player.scene = "SecondScene";
+ expect(player.scene).toBe("SecondScene");
+ expect(player.currentTime).toBe(0);
+ player.source = "class SecondScene(Scene): pass";
+ expect(player.source).toBe("class SecondScene(Scene): pass");
+ player.source = null;
+ player.scene = null;
+ expect(player.source).toBeNull();
+ expect(player.scene).toBeNull();
+ });
+
+ test("boots once after settings are set and sends dedented scenes and subsequent edits", async () => {
+ const state = await page("\n class Demo(Scene):\n pass\n ");
+ const player = new state.api.ManimgxPlayer();
+ player.connectedCallback();
+ state.api.settings.pyodide = "https://example.test/python/";
+ state.api.settings.manimgx = "https://example.test/manimgx.whl";
+ expect(state.workers).toHaveLength(0);
+ state.flush();
+ const director = state.workers[0]!;
+ expect(director.options).toEqual({ type: "module" });
+ expect(director.sent).toEqual([
+ {
+ boot: {
+ pyodide: "https://example.test/python/",
+ manimgx: "https://example.test/manimgx.whl",
+ },
+ },
+ { film: 1, run: { source: "class Demo(Scene):\n pass\n", scene: null } },
+ ]);
+ expect(state.canvas).toMatchObject({ width: 640, height: 360 });
+ expect(player.tabIndex).toBe(0);
+ await director.onmessage!({ data: { status: "Installing manimgx…" } });
+ expect(state.waiting.textContent).toBe("Installing manimgx…");
+ player.source = "class Changed(Scene): pass";
+ expect(director.sent.at(-1)).toEqual({ film: 1, run: { source: player.source, scene: null } });
+ player.scene = "Changed";
+ expect(director.sent.at(-1)).toEqual({
+ film: 1,
+ run: { source: player.source, scene: "Changed" },
+ });
+ player.disconnectedCallback();
+ player.connectedCallback();
+ state.flush();
+ expect(state.workers).toHaveLength(1);
+ expect(director.sent).toHaveLength(4);
+ });
+
+ test("the embedded worker is executable JavaScript and coalesces pending scene edits", async () => {
+ const state = await page();
+ new state.api.ManimgxPlayer().connectedCallback();
+ state.flush();
+ const source = await state.blobs[0]!.text();
+ const messages: { data: unknown; transfer: unknown[] }[] = [];
+ const imports: string[] = [];
+ const installs: string[] = [];
+ const runs: { film: number; source: string; scene: string | null; tried: string[] }[] = [];
+ const tasks: (() => void)[] = [];
+ let destroyed = false;
+ let allowBoot!: () => void;
+ const bootGate = new Promise<void>((resolve) => {
+ allowBoot = resolve;
+ });
+ const wasm = new Uint8Array([0, 97, 115, 109]);
+ const fonts = [new Uint8Array([1, 2])];
+ const runner = (
+ film: number,
+ source: string,
+ scene: string | null,
+ send: (bytes: Uint8Array) => void,
+ tried: string[],
+ ) => {
+ runs.push({ film, source, scene, tried: [...tried] });
+ if (source === "latest" && !tried.includes("networkx")) return "networkx";
+ send(new Uint8Array([film]));
+ return null;
+ };
+ const pyodide = {
+ loadPackage: async (name: string) => {
+ expect(name).toBe("micropip");
+ },
+ pyimport: (name: string) => {
+ expect(name).toBe("micropip");
+ return {
+ install: async (requirement: string) => {
+ installs.push(requirement);
+ },
+ };
+ },
+ runPython: (source: string) =>
+ source.includes("def run(")
+ ? runner
+ : {
+ toJs: () => ["engine source", wasm, fonts],
+ destroy: () => {
+ destroyed = true;
+ },
+ },
+ loadPackagesFromImports: async (source: string) => {
+ imports.push(source);
+ },
+ };
+ const global = {
+ onmessage: null as ((event: { data: unknown }) => void) | null,
+ postMessage: (data: unknown, transfer: unknown[] = []) => {
+ messages.push({ data, transfer });
+ },
+ setTimeout: (callback: () => void) => tasks.push(callback),
+ };
+ const context = createContext(global);
+ const pythonModule = new SyntheticModule(
+ ["loadPyodide"],
+ function () {
+ this.setExport("loadPyodide", async (options: { indexURL: string }) => {
+ expect(options.indexURL).toBe("https://example.test/python/");
+ await bootGate;
+ return pyodide;
+ });
+ },
+ { context },
+ );
+ await pythonModule.link(() => {
+ throw new Error("Unexpected dependency");
+ });
+ await pythonModule.evaluate();
+ const worker = new SourceTextModule(source, {
+ context,
+ importModuleDynamically: (specifier) => {
+ expect(specifier).toBe("https://example.test/python/pyodide.mjs");
+ return pythonModule;
+ },
+ });
+ await worker.link(() => {
+ throw new Error("The embedded director must be self-contained");
+ });
+ await worker.evaluate();
+ const send = (data: unknown) => global.onmessage!({ data });
+ send({ boot: { pyodide: "https://example.test/python/", manimgx: "manimgx==test" } });
+ send({ film: 1, run: { source: "stale", scene: null } });
+ send({ film: 1, run: { source: "latest", scene: "Demo" } });
+ send({ film: 2, run: { source: "other", scene: null } });
+ allowBoot();
+ await settle();
+ expect(installs).toEqual(["manimgx==test", "networkx"]);
+ expect(destroyed).toBe(true);
+ expect(messages.slice(0, 3)).toEqual([
+ { data: { status: "Loading Python…" }, transfer: [] },
+ { data: { status: "Installing manimgx…" }, transfer: [] },
+ {
+ data: { engine: { js: "engine source", wasm, fonts } },
+ transfer: [wasm.buffer, fonts[0]!.buffer],
+ },
+ ]);
+ expect(runs).toEqual([
+ { film: 1, source: "latest", scene: "Demo", tried: [] },
+ { film: 1, source: "latest", scene: "Demo", tried: ["networkx"] },
+ ]);
+ tasks.splice(0).forEach((task) => task());
+ await settle();
+ expect(imports).toEqual(["latest", "other"]);
+ expect(runs.at(-1)).toEqual({ film: 2, source: "other", scene: null, tried: [] });
+ const feeds = messages.slice(3) as {
+ data: { film: number; feed: ArrayBuffer };
+ transfer: unknown[];
+ }[];
+ expect(feeds.map(({ data }) => [data.film, ...new Uint8Array(data.feed)])).toEqual([
+ [1, 1],
+ [2, 2],
+ ]);
+ for (const { data, transfer } of feeds) expect(transfer).toEqual([data.feed]);
+ });
+});
diff --git a/browser/tests/tsconfig.json b/browser/tests/tsconfig.json
new file mode 100644
index 00000000..73142f2d
--- /dev/null
+++ b/browser/tests/tsconfig.json
@@ -0,0 +1,11 @@
+{
+ "extends": "../tsconfig.json",
+ "compilerOptions": {
+ "types": ["bun"],
+ "noEmit": true,
+ "declaration": false,
+ "emitDeclarationOnly": false,
+ "rootDir": ".."
+ },
+ "include": ["./**/*.ts"]
+}
diff --git a/browser/tsconfig.base.json b/browser/tsconfig.base.json
new file mode 100644
index 00000000..f016e3c9
--- /dev/null
+++ b/browser/tsconfig.base.json
@@ -0,0 +1,15 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "strict": true,
+ "noUncheckedIndexedAccess": true,
+ "exactOptionalPropertyTypes": true,
+ "noUnusedLocals": true,
+ "noUnusedParameters": true,
+ "verbatimModuleSyntax": true,
+ "noEmit": true,
+ "types": []
+ }
+}
diff --git a/browser/tsconfig.build.json b/browser/tsconfig.build.json
new file mode 100644
index 00000000..47ee5cb4
--- /dev/null
+++ b/browser/tsconfig.build.json
@@ -0,0 +1,8 @@
+{
+ "extends": "./tsconfig.base.json",
+ "compilerOptions": {
+ "lib": ["ES2022"],
+ "types": ["bun"]
+ },
+ "include": ["build.ts"]
+}
diff --git a/browser/tsconfig.json b/browser/tsconfig.json
new file mode 100644
index 00000000..218c2023
--- /dev/null
+++ b/browser/tsconfig.json
@@ -0,0 +1,8 @@
+{
+ "extends": "./tsconfig.base.json",
+ "compilerOptions": {
+ "lib": ["ES2022", "DOM", "DOM.Iterable"],
+ "rootDir": "src"
+ },
+ "include": ["src/index.ts", "src/player.ts", "src/engine.ts", "src/protocol.ts"]
+}
diff --git a/browser/tsconfig.worker.json b/browser/tsconfig.worker.json
new file mode 100644
index 00000000..a8808c80
--- /dev/null
+++ b/browser/tsconfig.worker.json
@@ -0,0 +1,8 @@
+{
+ "extends": "./tsconfig.base.json",
+ "compilerOptions": {
+ "lib": ["ES2022", "WebWorker"],
+ "rootDir": "src"
+ },
+ "include": ["src/director.ts", "src/protocol.ts"]
+}
diff --git a/rust/engine/src/chrome.rs b/rust/engine/src/chrome.rs
index 2c56226d..5607579e 100644
--- a/rust/engine/src/chrome.rs
+++ b/rust/engine/src/chrome.rs
@@ -6,7 +6,7 @@
use std::collections::{HashMap, HashSet};
use std::rc::Rc;
-use crate::render::{Frame, Gpu, Mat34, Player, Record, VIEW_FLOATS};
+use crate::render::{Frame, Gpu, Mat34, Player, Record, VIEW_LENGTH};
use crate::text::{Family, Fonts, Line};
/// The shapes every control is made of, uploaded once: a unit square, a unit disk, a triangle.
@@ -483,7 +483,7 @@ impl Chrome {
let (w, h) = (size.0 as f32, size.1 as f32);
// pixels, y up: x ∈ [0, w] → [−1, 1], y ∈ [0, h] → [−1, 1] (WGSL: column-major); a
// clear background
- let mut view = vec![0.0f32; VIEW_FLOATS + 4];
+ let mut view = vec![0.0f32; VIEW_LENGTH];
let projection = [[2.0 / w, 0.0, 0.0, -1.0], [0.0, 2.0 / h, 0.0, -1.0], [0.0, 0.0, 0.0, 0.5], [0.0, 0.0, 0.0, 1.0]];
for (r, row) in projection.iter().enumerate() {
for (c, value) in row.iter().enumerate() {