q5 4.4.5 → 4.5.3

package/deno.json

@@ -1,6 +1,6 @@
 {
 	"name": "@q5/q5",
-	"version": "4.4.5",
+	"version": "4.5.3",
 	"license": "LGPL-3.0-only",
 	"description": "Beginner friendly graphics powered by WebGPU, optimized for interactive art!",
 	"author": "quinton-ashley",
@@ -24,6 +24,7 @@
 			"home",
 			"lang",
 			"learn",
+			"teach",
 			"test",
 			".npmignore",
 			".prettierignore",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "q5",
-	"version": "4.4.5",
+	"version": "4.5.3",
 	"description": "Beginner friendly graphics powered by WebGPU, optimized for interactive art!",
 	"author": "quinton-ashley",
 	"contributors": [
@@ -12,8 +12,27 @@
 	],
 	"license": "LGPL-3.0-only",
 	"homepage": "https://q5js.org/home",
-	"main": "q5-server.js",
 	"types": "q5.d.ts",
+	"browser": {
+		".": "./q5.js",
+		"node:process": false
+	},
+	"exports": {
+		".": {
+			"types": "./q5.d.ts",
+			"browser": "./q5.js",
+			"deno": "./q5-deno-server.js",
+			"node": "./q5-server.js",
+			"default": "./q5.js"
+		},
+		"./q5.min.js": "./q5.min.js",
+		"./q5.js": "./q5.js",
+		"./q5-server.js": {
+			"browser": null,
+			"deno": "./q5-deno-server.js",
+			"default": "./q5-server.js"
+		}
+	},
 	"funding": [
 		{
 			"type": "patreon",
@@ -29,8 +48,8 @@
 		}
 	],
 	"scripts": {
-		"bundle": "cat src/q5-core.js src/q5-canvas.js src/q5-c2d-canvas.js src/q5-c2d-shapes.js src/q5-c2d-image.js src/q5-c2d-soft-filters.js src/q5-c2d-text.js src/q5-color.js src/q5-display.js src/q5-dom.js src/q5-fes.js src/q5-input.js src/q5-math.js src/q5-record.js src/q5-sound.js src/q5-util.js src/q5-vector.js src/q5-webgpu.js src/q5-lang.js > q5.js",
-		"min": "terser q5.js --compress ecma=2025 --mangle > q5.min.js",
+		"bundle": "cat src/q5-core.js src/q5-canvas.js src/q5-c2d-canvas.js src/q5-c2d-shapes.js src/q5-c2d-image.js src/q5-c2d-soft-filters.js src/q5-c2d-text.js src/q5-color.js src/q5-display.js src/q5-dom.js src/q5-fes.js src/q5-input.js src/q5-math.js src/q5-record.js src/q5-sound.js src/q5-util.js src/q5-vector.js src/q5-webgpu.js src/q5-lang.js src/q5-python.js > q5.js",
+		"min": "terser q5.js --compress ecma=2026 --mangle --output q5.min.js --source-map url=q5.min.js.map",
 		"dist": "bun bundle && bun min",
 		"tests": "jest test",
 		"bld": "node lang/build.js",
@@ -61,6 +80,10 @@
 		"jest-cli": "^29.7.0",
 		"jsdom": "^25.0.1",
 		"json2csv": "^6.0.0-alpha.2",
-		"skia-canvas": "^1.0.2"
-	}
+		"skia-canvas": "^1.0.2",
+		"terser": "^5.46.1"
+	},
+	"trustedDependencies": [
+		"skia-canvas"
+	]
 }

package/q5.d.ts

@@ -2500,6 +2500,8 @@ declare global {
 	 * - If one numerical input is provided, returns a number between 0 and the provided value.
 	 * - If two numerical inputs are provided, returns a number between the two values.
 	 * - If an array is provided, returns a random element from the array.
+	 * 
+	 * Return value can be the lower bound but can never exactly be the upper bound.
 	 * @param {number | any[]} [low] lower bound (inclusive) or an array
 	 * @param {number} [high] upper bound (exclusive)
 	 * @returns {number | any} a random number or element
@@ -4035,7 +4037,7 @@ declare global {
 	 * 
 	 * q5.draw = function () {
 	 * 	shader(stripes);
-	 * 	background(0);
+	 * 	plane(0, 0, width, height);
 	 * 
 	 * 	resetShader();
 	 * 	triangle(-50, -50, 0, 50, 50, -50);

package/q5.js

@@ -1,6 +1,6 @@
 /**
  * q5.js
- * @version 4.4
+ * @version 4.5
  * @author quinton-ashley
  * @contributors evanalulu, Tezumie, ormaq, Dukemz, LingDong-
  * @license LGPL-3.0
@@ -298,6 +298,7 @@ function Q5(scope, parent, renderer) {
 			if (Q5[name]) $[name] = Q5[name];
 			else {
 				Object.defineProperty(Q5, name, {
+					configurable: true,
 					get: () => $[name],
 					set: (fn) => ($[name] = fn)
 				});
@@ -307,9 +308,9 @@ function Q5(scope, parent, renderer) {
 
 	function wrapWithFES(name) {
 		const fn = t[name] || $[name];
-		$[name] = (event) => {
+		$[name] = function (...args) {
 			try {
-				return fn(event);
+				return fn.apply(this, args);
 			} catch (e) {
 				if ($._fes) $._fes(e);
 				throw e;
@@ -321,6 +322,7 @@ function Q5(scope, parent, renderer) {
 		await runHooks('presetup');
 
 		readyResolve();
+		if ($._removed) return;
 
 		if (t.preload || $.preload) {
 			wrapWithFES('preload');
@@ -352,9 +354,9 @@ function Q5(scope, parent, renderer) {
 			})
 		]);
 
-		if (!$._disablePreload) {
-			await $.loadAll();
-		}
+		if ($._removed) return;
+		if (!$._disablePreload) await $.loadAll();
+		if ($._removed) return;
 
 		$.setup ??= t.setup || (() => {});
 		wrapWithFES('setup');
@@ -366,10 +368,12 @@ function Q5(scope, parent, renderer) {
 		millisStart = performance.now();
 		await $.setup();
 		$._setupDone = true;
+
+		if ($._removed) return;
 		if ($.ctx === null) $.createCanvas(200, 200);
 		await runHooks('postsetup');
 
-		if ($.frameCount) return;
+		if ($.frameCount || $._removed) return;
 
 		$._lastFrameTime = performance.now() - 15;
 		raf(_draw);
@@ -449,7 +453,7 @@ Q5.preloadMethods = {};
 Q5.prototype.registerPreloadMethod = (n, fn) => (Q5.preloadMethods[n] = fn[n]);
 
 function Canvas(w, h, opt) {
-	if (Q5._hasGlobal) return;
+	if (Q5._hasGlobal) return Promise.resolve(Q5.instances[0].canvas);
 
 	let useC2D = w == 'c2d' || h == 'c2d' || opt == 'c2d' || opt?.renderer == 'c2d' || !Q5._esm;
 
@@ -491,7 +495,7 @@ if (typeof window == 'object') {
 	window.addEventListener('pagehide', cleanup);
 } else global.window = 0;
 
-Q5.version = Q5.VERSION = '4.4';
+Q5.version = Q5.VERSION = '4.5';
 
 if (typeof document == 'object') {
 	document.addEventListener('DOMContentLoaded', () => {
@@ -583,7 +587,7 @@ Q5.modules.canvas = ($, q) => {
 				if (!el) {
 					// reattach canvas to the DOM
 					document.getElementById(c.id)?.remove();
-					addCanvas();
+					$._addCanvas();
 				}
 
 				if (window.IntersectionObserver) {
@@ -714,7 +718,7 @@ Q5.modules.canvas = ($, q) => {
 			}
 		};
 
-		function addCanvas() {
+		$._addCanvas = () => {
 			let el = $._parent;
 			el ??= document.getElementsByTagName('main')[0];
 			if (!el) {
@@ -729,8 +733,8 @@ Q5.modules.canvas = ($, q) => {
 					if (document.body) document.body.appendChild(el);
 				});
 			}
-		}
-		addCanvas();
+		};
+		$._addCanvas();
 	}
 
 	$.resizeCanvas = (w, h) => {
@@ -3455,16 +3459,12 @@ Q5.modules.fes = ($) => {
 		try {
 			let res = await (await fetch(fileUrl)).text(),
 				lines = res.split('\n'),
-				errLine = lines[lineNum - 1]?.trim() ?? '',
-				bug = ['🐛', '🐞', '🐜', '🦗', '🦋', '🪲'][Math.floor(Math.random() * 6)],
-				inIframe = window.self !== window.top,
-				prefix = `q5.js ${bug}`,
-				errorMsg = ` Error in ${fileBase} on line ${lineNum}:\n\n${errLine}`;
+				errLine = lines[lineNum - 1]?.trim();
 
-			if (inIframe) $.log(prefix + errorMsg);
-			else {
-				$.log(`%c${prefix}%c${errorMsg}`, 'background: #b7ebff; color: #000;', '');
-			}
+			let type = '';
+			if (e instanceof SyntaxError || e.name === 'SyntaxError') type = 'syntax';
+
+			Q5.friendlyError(fileBase, lineNum, errLine, type);
 		} catch (err) {}
 	};
 
@@ -3477,7 +3477,7 @@ Q5.modules.fes = ($) => {
 			let match = line.match(/(https?:\/\/[^\s)]+\.js|\b\/[^\s)]+\.js)/);
 			if (match) {
 				let file = match[1];
-				if (!/q5|p5play/i.test(file)) {
+				if (!/q5|p5play|q5play|brython/i.test(file)) {
 					$._sketchFile = file;
 					break;
 				}
@@ -3516,6 +3516,19 @@ Q5.modules.fes = ($) => {
 		checkLatestVersion();
 	}
 };
+
+Q5.friendlyError = (file, lineNum, detail) => {
+	let bug = ['🐛', '🐞', '🐜', '🦗', '🦋', '🪲'][Math.floor(Math.random() * 6)],
+		inIframe = window.self !== window.top,
+		prefix = `q5 ${bug}`,
+		msg = `Error in ${file} on line ${lineNum}`;
+
+	if (detail) msg += ':\n\n' + detail;
+
+	if (inIframe) return console.log(prefix + msg);
+
+	console.log(`%c${prefix}%c ${msg}`, 'background: #b7ebff; color: #000;', '');
+};
 Q5.modules.input = ($, q) => {
 	if ($._isGraphics) return;
 
@@ -9348,17 +9361,17 @@ const userLangs = `
 update -> es:actualizar
 draw -> es:dibujar
 postProcess -> es:postProcesar
-mousePressed -> es:alPresionarRatón
-mouseReleased -> es:alSoltarRatón
-mouseMoved -> es:alMoverRatón
-mouseDragged -> es:alArrastrarRatón
+mousePressed -> es:alPresionarRaton
+mouseReleased -> es:alSoltarRaton
+mouseMoved -> es:alMoverRaton
+mouseDragged -> es:alArrastrarRaton
 doubleClicked -> es:dobleClic
 keyPressed -> es:alPresionarTecla
 keyReleased -> es:alSoltarTecla
 touchStarted -> es:alEmpezarToque
 touchEnded -> es:alTerminarToque
 touchMoved -> es:alMoverToque
-mouseWheel -> es:ruedaRatón
+mouseWheel -> es:ruedaRaton
 `;
 
 const classLangs = {
@@ -9439,20 +9452,19 @@ Object.defineProperty(Q5, 'lang', {
 
 		for (let className in classLangs) {
 			let target = className == 'Q5' ? Q5 : Q5[className] ? Q5[className].prototype : null;
-			if (target) {
-				let map = parseLangs(classLangs[className], val);
-				for (let name in map) {
-					let translatedName = map[name];
-					if (target.hasOwnProperty(translatedName)) continue;
-					Object.defineProperty(target, translatedName, {
-						get: function () {
-							return this[name];
-						},
-						set: function (v) {
-							this[name] = v;
-						}
-					});
-				}
+			if (!target) continue;
+			let map = parseLangs(classLangs[className], val);
+			for (let name in map) {
+				let translatedName = map[name];
+				if (target.hasOwnProperty(translatedName)) continue;
+				Object.defineProperty(target, translatedName, {
+					get: function () {
+						return this[name];
+					},
+					set: function (v) {
+						this[name] = v;
+					}
+				});
 			}
 		}
 
@@ -9511,6 +9523,13 @@ Q5.addHook('init', (q) => {
 	for (let name in m) {
 		let translatedName = m[name];
 		q[translatedName] = q[name];
+
+		if (Q5._lang == 'es') {
+			let unaccentedName = translatedName.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+			if (unaccentedName != translatedName) {
+				q[unaccentedName] = q[name];
+			}
+		}
 	}
 });
 
@@ -9523,6 +9542,8 @@ Q5.addHook('predraw', (q) => {
 		'frameCount',
 		'mouseX',
 		'mouseY',
+		'pmouseX',
+		'pmouseY',
 		'movedX',
 		'movedY',
 		'mouseIsPressed',
@@ -9535,6 +9556,152 @@ Q5.addHook('predraw', (q) => {
 
 	// sync properties
 	for (let p of props) {
-		if (m[p]) q[m[p]] = q[p];
+		if (!m[p]) continue;
+		q[m[p]] = q[p];
+		if (Q5._lang == 'es') {
+			let unaccentedName = m[p].normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+			if (unaccentedName != m[p]) {
+				q[unaccentedName] = q[p];
+			}
+		}
 	}
 });
+const runPython = async function () {
+	let scripts = [...document.getElementsByTagName('script')];
+	scripts = scripts.filter((s) => s.type == 'q5-python' || s.type == 'text/q5-python');
+	if (!scripts.length) return;
+
+	if (!window.brython) {
+		const loadScript = (src) =>
+			new Promise((resolve, reject) => {
+				const script = document.createElement('script');
+				script.src = src;
+				script.onload = resolve;
+				script.onerror = reject;
+				document.head.appendChild(script);
+			});
+
+		await loadScript('https://cdn.jsdelivr.net/npm/brython@3.14.0/brython.min.js');
+		await loadScript('https://cdn.jsdelivr.net/npm/brython@3.14.0/brython_stdlib.min.js');
+	}
+
+	let code = '';
+	for (const script of scripts) {
+		code += script.src ? await (await fetch(script.src)).text() : script.innerText;
+	}
+
+	const useWebGPU = !code.slice(0, code.indexOf('\n')).includes('C2D'),
+		q5py = useWebGPU ? await Q5.WebGPU() : new Q5();
+
+	// `window.Canvas` returns a promise that resolves when Q5 is ready
+	// but `q5py.Canvas` returns the renderer synchronously
+	// so to make Brython happy with `await Canvas()` we need to make it async
+	const Canvas = q5py.Canvas;
+	q5py.Canvas = async (...a) => Canvas(...a);
+
+	code = code.replaceAll('\n', '\n\t');
+
+	code = `
+async def __run():
+	${code}
+
+	_q5_state_vars = ["mouseX", "mouseY", "pmouseX", "pmouseY", "width", "height", "frameCount", "deltaTime", "mouseIsPressed", "mouseButton", "keyIsPressed", "key", "keyCode", "touches", "movedX", "movedY"]
+
+	def _sync_and_call(fn):
+		def _wrapper(*args):
+			try:
+				for var in _q5_state_vars:
+					if hasattr(q5py, var):
+						ns[var] = getattr(q5py, var)
+				return fn(*args)
+			except Exception as e:
+				window._pyErr(_err())
+				raise e
+		return _wrapper
+
+	for fn_name in ["update", "draw", "mousePressed", "mouseReleased", "mouseMoved", "mouseDragged", "mouseClicked", "doubleClicked", "mouseWheel", "keyPressed", "keyReleased", "keyTyped", "touchStarted", "touchMoved", "touchEnded", "windowResized"]:
+		if fn_name in locals():
+			setattr(window, fn_name, _sync_and_call(locals()[fn_name]))
+`;
+
+	window._pyErr = (err, lineNum) => {
+		if (typeof err === 'string' && err.includes('Traceback')) {
+			let lines = err.split('\n');
+			for (let i = 0; i < lines.length; i++) {
+				const match = lines[i].match(/File "<string>", line (\d+)/);
+				if (match) {
+					lineNum = parseInt(match[1]);
+					lines = lines.slice(i + 1);
+					// de-indent the first two lines based on the first line's indentation
+					const indentMatch = lines[0].match(/^\s+/);
+					if (indentMatch) {
+						const indent = indentMatch[0];
+						for (let j = 0; j < Math.min(2, lines.length); j++) {
+							lines[j] = lines[j].slice(indent.length);
+						}
+					}
+					err = lines.join('\n');
+					break;
+				}
+			}
+		}
+
+		let file = scripts[0].src.split('/').at(-1);
+		lineNum -= 2; // adjust for the wrapper code lines
+		if (Q5.friendlyError) Q5.friendlyError(file, lineNum, err);
+		else console.error(`Error in ${file} on line ${lineNum}:\n\n${err}`);
+	};
+
+	brython();
+
+	// hide brython's internal logs by temporarily overriding console.log
+	let log = console.log;
+	console.log = function () {};
+
+	__BRYTHON__.runPythonSource(`
+from browser import window, aio
+import traceback
+import io
+
+def _err():
+	f = io.StringIO()
+	traceback.print_exc(file=f)
+	return f.getvalue()
+
+async def _run_py(q5py, code):
+	ns = globals().copy()
+	ns['ns'] = ns
+	ns['q5py'] = q5py
+
+	for attr in dir(q5py):
+		if not attr.startswith('_'):
+			try:
+				ns[attr] = getattr(q5py, attr)
+			except Exception:
+				pass
+
+	try:
+		exec(code, ns)
+	except SyntaxError as e:
+		return window._pyErr(_err(), e.lineno)
+	except Exception as e:
+		return window._pyErr(_err())
+	
+	try:
+		await ns["__run"]()
+	except Exception as e:
+		window._pyErr(_err())
+
+window._runPy = _run_py
+`);
+
+	console.log = log;
+
+	await window._runPy(q5py, code);
+};
+
+if (typeof document == 'object') {
+	if (document.readyState == 'loading') {
+		document.addEventListener('DOMContentLoaded', runPython);
+	} else runPython();
+}