q5 4.5.0 → 4.5.4

package/README.md

@@ -47,7 +47,9 @@ p5.js is licensed under the LGPLv2, small sections of p5' code directly copied i
 
 q5 was inspired by the incredible work of [Ben Fry](https://benfry.com) and [Casey Reas](https://x.com/REAS) on Java [Processing](https://processingfoundation.org/) from 2001 to 2023, [Lauren McCarthy](http://lauren-mccarthy.com)'s work on [p5.js](https://p5js.org) from 2013 to 2019, and all contributors to these projects.
 
-## Code Excerpt Sources
+Huge thanks to all the [q5 contributors](https://github.com/q5js/q5.js/graphs/contributors)!
+
+@evanalulu, @Tezumie, @keturn, @ormaq, @bertubi, @RedWilly, @Dukemz, @LingDong-
 
 WebGPU MSDF text rendering:
 https://webgpu.github.io/webgpu-samples/?sample=textRenderingMsdf

package/deno.json

@@ -1,6 +1,6 @@
 {
 	"name": "@q5/q5",
-	"version": "4.5.0",
+	"version": "4.5.4",
 	"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.5.0",
+	"version": "4.5.4",
 	"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",
@@ -30,7 +49,7 @@
 	],
 	"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 src/q5-python.js > q5.js",
-		"min": "terser q5.js --compress ecma=2025 --mangle > q5.min.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

@@ -308,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;
@@ -322,6 +322,7 @@ function Q5(scope, parent, renderer) {
 		await runHooks('presetup');
 
 		readyResolve();
+		if ($._removed) return;
 
 		if (t.preload || $.preload) {
 			wrapWithFES('preload');
@@ -353,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');
@@ -367,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);
@@ -390,6 +393,7 @@ Q5._esm = this === undefined;
 
 Q5._instanceCount = 0;
 Q5.instances = [];
+Q5.errorTolerant = false;
 Q5._friendlyError = (msg, func) => {
 	if (!Q5.disableFriendlyErrors) console.error(func + ': ' + msg);
 };
@@ -450,7 +454,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;
 
@@ -584,7 +588,7 @@ Q5.modules.canvas = ($, q) => {
 				if (!el) {
 					// reattach canvas to the DOM
 					document.getElementById(c.id)?.remove();
-					addCanvas();
+					$._addCanvas();
 				}
 
 				if (window.IntersectionObserver) {
@@ -715,7 +719,7 @@ Q5.modules.canvas = ($, q) => {
 			}
 		};
 
-		function addCanvas() {
+		$._addCanvas = () => {
 			let el = $._parent;
 			el ??= document.getElementsByTagName('main')[0];
 			if (!el) {
@@ -730,8 +734,8 @@ Q5.modules.canvas = ($, q) => {
 					if (document.body) document.body.appendChild(el);
 				});
 			}
-		}
-		addCanvas();
+		};
+		$._addCanvas();
 	}
 
 	$.resizeCanvas = (w, h) => {
@@ -3456,16 +3460,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) {}
 	};
 
@@ -3478,7 +3478,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;
 				}
@@ -3517,6 +3517,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;
 
@@ -9349,17 +9362,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 = {
@@ -9440,20 +9453,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;
+					}
+				});
 			}
 		}
 
@@ -9512,6 +9524,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];
+			}
+		}
 	}
 });
 
@@ -9524,6 +9543,8 @@ Q5.addHook('predraw', (q) => {
 		'frameCount',
 		'mouseX',
 		'mouseY',
+		'pmouseX',
+		'pmouseY',
 		'movedX',
 		'movedY',
 		'mouseIsPressed',
@@ -9536,7 +9557,14 @@ 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 () {
@@ -9554,67 +9582,135 @@ const runPython = async function () {
 				document.head.appendChild(script);
 			});
 
-		await loadScript('https://cdn.jsdelivr.net/npm/brython@3.12.0/brython.js');
-		await loadScript('https://cdn.jsdelivr.net/npm/brython@3.12.0/brython_stdlib.min.js');
+		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');
 	}
 
-	brython();
-
-	__BRYTHON__.runPythonSource(`
-from browser import window, aio
-
-async def runQ5PY(code, q5py):
-	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
-
-	exec(code, ns)
-	
-	if "__run_code" in ns:
-	  await ns["__run_code"]()
-
-window._runQ5PY = runQ5PY
-`);
-
 	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();
+		q = useWebGPU ? await Q5.WebGPU() : new Q5();
 
-	code = code.replaceAll('\n', '\n\t');
+	// `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 = q.Canvas;
+	q.Canvas = async (...a) => Canvas(...a);
 
-	code = `
-async def __run_code():
-	pass
+	// add a tab before each line of code to nest it inside the __run function
+	// but not within triple-quoted strings
+	code = code
+		.split(/(\"\"\"[\s\S]*?\"\"\"|\'\'\'[\s\S]*?\'\'\')/g)
+		.map((part, i) => (i % 2 === 0 ? part.replaceAll('\n', '\n\t') : part))
+		.join('');
 
+	code = `
+async def __run(q):
 	${code}
 
-	q5_state_vars = ["mouseX", "mouseY", "pmouseX", "pmouseY", "width", "height", "frameCount", "deltaTime", "mouseIsPressed", "mouseButton", "keyIsPressed", "key", "keyCode", "touches", "movedX", "movedY"]
+	_state_vars = ["mouseX", "mouseY", "pmouseX", "pmouseY", "width", "height", "frameCount", "deltaTime", "mouseIsPressed", "mouseButton", "keyIsPressed", "key", "keyCode", "touches", "movedX", "movedY"]
+
+	_usr_fns = ["update", "draw", "postProcess", "mousePressed", "mouseReleased", "mouseMoved", "mouseDragged", "mouseClicked", "doubleClicked", "mouseWheel", "keyPressed", "keyReleased", "keyTyped", "touchStarted", "touchMoved", "touchEnded", "windowResized"]
 
 	def _sync_and_call(fn):
 		def _wrapper(*args):
-			for _var in q5_state_vars:
-				if hasattr(q5py, _var):
-					ns[_var] = getattr(q5py, _var)
-			return fn(*args)
+			try:
+				for var in _state_vars:
+					if hasattr(q, var):
+						ns[var] = getattr(q, var)
+				return fn(*args)
+			except Exception as e:
+				window._pyErr(_err())
+				if not window.Q5.errorTolerant: noLoop()
 		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]))
+	for fn_name in _usr_fns:
+		if fn_name in locals():
+			setattr(window, fn_name, _sync_and_call(locals()[fn_name]))
 `;
 
-	await window._runQ5PY(code, q5py);
+	window._pyErr = (err, lineNum) => {
+		if (typeof err === 'string' && err.includes('Traceback')) {
+			let lines = err.split('\n');
+			for (let i = lines.length - 1; i > 0; 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);
+						}
+					} else {
+						let line = code.split('\n')[lineNum - 1].trim();
+						lines.unshift(line, '');
+					}
+					err = lines.join('\n');
+					break;
+				}
+			}
+		}
+
+		let file = scripts[0].src || scripts[0]['data-filename'] || 'sketch.py';
+		file = file.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(q, code):
+	ns = globals().copy()
+	ns['ns'] = ns
+	ns['Q5'] = window.Q5
+
+	for attr in dir(q):
+		if not attr.startswith('_'):
+			try:
+				ns[attr] = getattr(q, 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"](q)
+	except Exception as e:
+		window._pyErr(_err())
+
+window._runPy = _run_py
+`);
+
+	console.log = log;
+
+	await window._runPy(q, code);
 };
 
 if (typeof document == 'object') {