q5 1.9.21 → 1.9.46

package/README.md

@@ -1,12 +1,12 @@
 # <img src="q5js_logo.webp" height="64"> <img src="q5js_brand.webp" height="64">
 
-**q5.js** implements all of [p5][]'s 2D drawing, math, and user input functionality.
+The sequel to p5.js is here!
 
-It's a drop-in replacement that's performance optimized and 23x smaller than p5. q5 even has a few exclusive features: top-level global mode, HDR color support, namespace mode, and text image caching.
+**q5.js** implements all of [p5][]'s 2D drawing, math, and user input functionality.
 
-But q5 doesn't include any friendly error messages, so its mainly for people who are already familiar with p5.js or JS programming in general. If you're a beginner, stick with p5 while developing a sketch, then use q5 to share your work.
+It's a drop-in replacement that's performance optimized and ~20x smaller than p5, while packing exclusive new features: HDR color support, modular use, top-level global mode, namespace mode, and text image caching.
 
-## Usage
+## Typical Use
 
 q5 should work with your existing p5.js sketches, no modifications required! If you have any problems though, please [make an issue report][].
 
@@ -37,22 +37,53 @@ q5.js is compatible with popular p5 addons and projects that use p5, such as [p5
 To use addons, simply load them after q5.js:
 
 ```html
-<script src="q5.js"></script>
+<script src="https://q5js.org/q5.js"></script>
 <!-- load p5 addons after q5 -->
 <script src="https://p5play.org/v3/planck.min.js"></script>
 <script src="https://p5play.org/v3/p5play.js"></script>
 ```
 
-## New Features: Top-Level Global Mode
+## Exclusive Features
+
+q5 includes some exclusive features that aren't available in p5.
+
+## Ask AI ✨
+
+Why doesn't this code work? `text('Hello!');`
+
+JavaScript quietly avoids errors if possible (for example by giving undefined variables default values) and its error messages can be confusing for beginners.
+
+p5's error messages are friendlier but often too vague, leaving beginners searching for help. 🙋
+
+```
+🌸 p5.js says: [test.js, line 19] text() was expecting at least 3 arguments, but received only 1.
+```
+
+q5 creates error reports that can be sent to an AI just by clicking a link! Users can also run the `askAI()` function before a line of code that isn't working as expected. 🤖
+
+```js
+function draw() {
+	askAI();
+	text('Hello!');
+}
+```
 
-> q5.js includes some exclusive features that aren't available in p5.js. Using them is optional!
+Optionally `askAI` can take a question as input, the default question is "What's wrong with this line? short answer".
+
+ChatGPT 4o excels at identifying the most common errors that beginners make: typos, missing syntax, incorrect arguments, and more.
+
+This feature can be disabled by setting `Q5.disableFriendlyErrors = true;`, though unlike in p5 this doesn't provide a performance boost from disabling argument validation because q5 mostly doesn't have any already.
+
+q5 can catch errors in q5 function like `draw` and continue looping if you set `Q5.errorTolerant = true;`.
+
+## Top-Level Global Mode
 
 In **p5**, functions like `rect` can't be used on the file level. They must be called from within p5 functions like `setup` and `draw`.
 
 In **q5**, existing p5 2D sketches don't require any modification. But if you initialize Q5 at the top of your sketch, the `preload` and `setup` functions become optional.
 
 ```js
-new Q5();
+Q5();
 
 noStroke();
 let c = color(0, 126, 255, 102);
@@ -63,7 +94,7 @@ rect(15, 15, 35, 70);
 This is great because you don't have to declare variables on the file level and then define them in `preload` or `setup`. You can declare and define them at the same time!
 
 ```js
-new Q5();
+Q5();
 
 let cow = loadImage('cow.png');
 
@@ -76,7 +107,7 @@ function setup() {
 
 Note that if you use `loadImage` on the file level, q5 will wait to run `setup` and `draw` until the image loads. Optionally if you forgo defining `preload`, you can run it to signify that the sketch can start once loading is complete. Otherwise q5 will auto-start the sketch after 32ms of delay, this ensures code after `new Q5()` is run before the sketch starts.
 
-## New Features: HDR Color Support
+## HDR Color Support
 
 Most modern devices support the "display-p3" HDR color space. If a device doesn't support it, q5 will fall back to "srgb".
 
@@ -103,7 +134,7 @@ Support for the HSV color format was removed in q5 v1.9.3 because color experts
 
 https://en.wikipedia.org/wiki/HSL_and_HSV#Disadvantages
 
-## New Features: Customize Canvas Context Attributes
+## Customize Canvas Context Attributes
 
 In **p5**, you're stuck with the default [canvas context attributes][], which can't be changed. So the canvas must have an alpha layer, even if you don't need one. HDR color space and [desynchronized rendering][] are not supported.
 
@@ -127,7 +158,7 @@ createCanvas(400, 400, '2d', {
 });
 ```
 
-## New Features: Namespace Mode
+## Namespace Mode
 
 **p5**'s [instance mode][] enables multiple sketches to run on one page. To avoid needing to preface every p5 function with `p.` you can use a JS [with statement][].
 
@@ -177,11 +208,17 @@ q5 will automatically load and configure `canvas` and `jsdom` if they are instal
 
 In node.js, q5's automatic global mode is disabled. To use global mode you need to assign q5 user defined functions like `draw` and `setup` to the `global` object then call `new Q5()`. q5 will add q5 variables and functions to the `global` object, just like it adds them to the `window` object in the browser.
 
+## Modular Use
+
+**p5.js** is nearly 5MB in size. This is mainly [due to the inclusion of the webgl render and the dependencies corejs and opentype](https://github.com/processing/p5.js/issues/6776#issuecomment-1918238317). If 2d rendering is all a sketch needs, p5 wastes user bandwidth and is slower to load, parse, and run.
+
+**q5.js** (the default bundle) is 20x smaller than p5, which is already great for typical use. For extremely lightweight use you can load a subset of scripts from the `src` folder, just be sure to load `src/q5-core.js` first.
+
 ## Motivation: Part 1
 
-> This section was written by @LingDong-, co-creator of q5.
+> This section was written by @LingDong-
 
-After having used many graphics libraries across many different languages, I have found that the Processing/p5.js/Openframeworks system has one huge advantage over others:
+After having used many graphics libraries across many different languages, I have found that the Processing system has one huge advantage over others:
 
 It gets stuff drawn onto the screen quick and easy!
 
@@ -195,7 +232,7 @@ In fact, its not uncommon for successful software systems to have multiple imple
 
 ## Motivation: Part 2
 
-> This section was written by @quinton-ashley, co-creator of q5.
+> This section was written by @quinton-ashley
 
 I thought @LingDong-'s work on q5 and the idea itself had great potential, so I decided to implement more of the p5.js API. My main goal was to make it work with [p5play](https://p5play.org)!
 
@@ -203,14 +240,19 @@ An increase in performance of even a few frames per second can make a significan
 
 I was also interested in working on q5 because for a lot of p5.js users, the library itself is a black box. Even as an expert JS programmer and someone who teaches CS for a living, I still find myself scratching my head when I look at the p5.js source code. p5 was initially released 10 years ago and bad design choices were made due to JS limitations at the time. It's also become an absolutely massive library, with literally over 100,000 lines of code and documentation!
 
-I think it'd be better if the canvas mode, webgl mode, Friendly Error System, and accessibility features of p5 were offered in separate files. Yet, the powers that be at the Processing Foundation have made it clear that they don't want to do that. Instead they insist on adding more accessibility features to the base library, which the majority of people just don't need. So q5 is a good alternative that trims out the fat.
+I think it'd be better if the canvas mode, webgl mode, Friendly Error System, and accessibility features of p5 were offered in separate files. Yet, the powers that be at the Processing Foundation have made it clear that they don't want to do that. So q5 is a good alternative that trims out the fat.
 
 Thanks in large part to @LingDong-'s design, q5 is well organized, concise, and utilizes many modern JS features! I think even without inline documentation, the source code is easier for experienced JS programmers to comprehend.
 
 ## More exclusive features
 
+Features added by @Tezumie:
+
+- `point()`: more efficient point drawing.
+
 Features added by @quinton-ashley:
 
+- `image.trim()`: removes transparent pixels from the edges of an image.
 - `opacity(globalAlpha)`: set the opacity multiplier for anything subsequently drawn to the canvas in a range between 0 (transparent) and 1 (opaque).
 - `textCache(enabled)`: Text image caching is enabled by default. Rotated text is only rendered once, and then cached as an image. This can result in ridiculously high 90x performance boosts for text-heavy sketches. Users don't need to change their code, the `text` function can be used as normal, q5 takes care of everything behind the scenes.
 - `createImage`, `loadImage`, and `createGraphics`: as a last parameter to these functions, `opt` (options) object, users can specify canvas context attributes for an image or graphic. `opt.alpha` is set to true by default.
@@ -225,21 +267,21 @@ Features added by @LingDong-:
 
 ## Limitations
 
-- `color` function only accepts numeric input, hex, and simple named colors. It doesn't parse strings like `color('hsl(160, 100%, 50%)')`. This was done to keep the codebase small and easier to understand.
+- `color` function only accepts numeric input, hex, and simple named colors. It doesn't parse strings like `color('hsl(160, 100%, 50%)')`. q5 supports oklch which is a superior color format so use it instead. The `fill`, `stroke`, and `background` functions can accept any css color string though.
 
 ## Size Comparison
 
 Unminified:
 
-- p5.js **4300kb** ⚠️
+- p5.js **4958kb** ⚠️
 - p5.sound.js 488kb
-- q5.js 66kb
+- q5.js 71kb
 
 Minified:
 
-- p5.min.js 1000kb
+- p5.min.js 1033kb ⚠️
 - p5.sound.min.js 200kb
-- q5.min.js **42kb** 🎉
+- q5.min.js **45kb** 🎉
 
 ## Benchmarks
 
@@ -278,17 +320,29 @@ Higher FPS (frames per second) is better.
 
 <sub>\* Only for browsers that support CanvasRenderingContext2D.filter ([75% of all](https://caniuse.com/#feat=mdn-api_canvasrenderingcontext2d_filter) as of Aug 2020, including Chrome, Firefox and Edge). For those that don't, performance is similar to p5.js, as identical implementations are usually used as fallbacks.</sub>
 
-## Contributing
+## Contributor Code of Conduct
+
+We aim to make contributing to the q5 project more approachable for non-experts by using modern JavaScript without any complicated build tools or frameworks.
+
+All contributors are required to check their ego at the door and be open to feedback. Critique of code is not a critique of the person who wrote it. We're all here to learn and work with others to collectively write the best code possible.
+
+Code is a language art that can be subjectively judged by its effectiveness at communicating its functionality to humans. Code can also be objectively measured by its performance. Since JavaScript is served over a network, size is a factor as well. Therefore, the q5 team strives to balance code readability with brevity and performance.
+
+Check out the q5 project planning board:
+
+https://github.com/users/quinton-ashley/projects/4/views/1
+
+## Organization
 
-Speed is a goal for q5.js, and we would very much like to see the above list grow. If you know how to make something faster, advice/pull requests are very welcome!
+If the q5 project is successful, all contributing developers will be paid for their work. The project will be run as a [worker co-op](https://en.wikipedia.org/wiki/Worker_cooperative).
 
 ## Licensing
 
-q5.js is not affiliated with the Processing Foundation. p5.js is licensed under the LGPLv2, the two small sections of p5.js' code were directly copied into q5.js are credited below. The rest of q5 is a new implementation of part of the p5.js API. APIs are not copyrightable in the United States, as decided by the Supreme Court in the Google v Oracle case.
+q5.js was created by the q5 team and is licensed under the LGPLv3. q5 is not affiliated with The Processing Foundation.
 
-@LingDong- created the original q5xjs library and licensed it under the MIT license.
+@LingDong- created the original q5xjs library which is MIT licensed.
 
-@quinton-ashley created q5.js (this project) which contains many bug fixes, additional p5.js API implementations, and several exclusive features. q5.js is licensed under the LGPLv3.
+p5.js is licensed under the LGPLv2, the two small sections of p5' code directly copied into q5 are credited below. The rest of q5 is a new implementation of part of the p5 API. APIs are not copyrightable in the United States, as decided by the Supreme Court in the Google v Oracle case.
 
 ## Credits
 

package/package.json

@@ -1,12 +1,19 @@
 {
-	"author": "quinton-ashley",
 	"name": "q5",
-	"version": "1.9.21",
-	"description": "An implementation of the p5.js 2D API that's smaller and faster",
+	"version": "1.9.46",
+	"description": "The sequel to p5.js that's smaller and faster",
+	"author": "quinton-ashley",
+	"contributors": [
+		"Tezumie",
+		"LingDong-"
+	],
+	"license": "LGPL-3.0",
+	"homepage": "https://q5js.org/home",
 	"main": "q5-server.js",
 	"scripts": {
+		"bundle": "cat src/q5-core.js src/q5-2d-canvas.js src/q5-2d-drawing.js src/q5-2d-image.js src/q5-2d-text.js src/q5-ai.js src/q5-color.js src/q5-display.js src/q5-input.js src/q5-math.js src/q5-sound.js src/q5-util.js src/q5-vector.js > q5.js",
 		"min": "terser q5.js --compress ecma=2024 --mangle > q5.min.js",
-		"dist": "cp q5.js ../../web/p5play-web/v3/q5.js && bun min && cp q5.min.js ../../web/p5play-web/v3/q5.min.js",
+		"dist": "bun bundle && cp q5.js ../../web/p5play-web/v3/q5.js && bun min && cp q5.min.js ../../web/p5play-web/v3/q5.min.js",
 		"v": "npm version patch --force",
 		"V": "npm version minor --force",
 		"version": "git add -A",
@@ -14,7 +21,10 @@
 	},
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/quinton-ashley/q5.js.git"
+		"url": "git+https://github.com/q5js/q5.js.git"
+	},
+	"bugs": {
+		"url": "https://github.com/q5js/q5.js/issues"
 	},
 	"keywords": [
 		"p5",
@@ -25,9 +35,9 @@
 		"q5.js",
 		"q5js"
 	],
-	"license": "LGPL-3.0",
-	"bugs": {
-		"url": "https://github.com/quinton-ashley/q5.js/issues"
-	},
-	"homepage": "https://github.com/quinton-ashley/q5.js#readme"
+	"devDependencies": {
+		"canvas": "^2.11.2",
+		"jsdom": "^24.1.0",
+		"@types/p5": "^1.7.6"
+	}
 }

package/q5-server.js

@@ -8,7 +8,8 @@ try {
 	global.CairoCanvas ??= require('canvas');
 	global.JSDOM ??= require('jsdom').JSDOM;
 } catch (e) {
-	module.exports = require('./q5.js');
+	require('./q5.js');
+	module.exports = Q5;
 	return;
 }
 
@@ -24,7 +25,7 @@ global.window = new JSDOM('', { url: 'http://localhost' }).window;
 	global.Event = window.Event;
 }
 
-const Q5 = require('./q5.js');
+require('./q5.js');
 
 Q5._createNodeJSCanvas = function () {
 	let cairoCanvas = CairoCanvas.createCanvas(...arguments);

package/q5.js

@@ -91,7 +91,7 @@ function Q5(scope, parent) {
 	}
 
 	$.createCanvas = function (width, height, renderer, options) {
-		if (renderer == 'webgl') throw `webgl renderer is not supported in q5, use '2d'`;
+		if (renderer == 'webgl') throw Error(`webgl renderer is not supported in q5, use '2d'`);
 		if (typeof renderer == 'object') options = renderer;
 		$.width = $.canvas.width = width || window.innerWidth;
 		$.height = $.canvas.height = height || window.innerHeight;
@@ -924,6 +924,7 @@ function Q5(scope, parent) {
 		blue: [0, 0, 255],
 		brown: [165, 42, 42],
 		crimson: [220, 20, 60],
+		cyan: [0, 255, 255],
 		darkviolet: [148, 0, 211],
 		gold: [255, 215, 0],
 		green: [0, 128, 0],
@@ -1026,6 +1027,7 @@ function Q5(scope, parent) {
 		$._doStroke = true;
 		$._strokeSet = true;
 		if (!c._q5Color && typeof c != 'string') c = $.color(...arguments);
+		else if (basicColors[c]) c = $.color(...basicColors[c]);
 		if (c.a <= 0) return ($._doStroke = false);
 		ctx.strokeStyle = c.toString();
 	};
@@ -1034,6 +1036,7 @@ function Q5(scope, parent) {
 		$._doFill = true;
 		$._fillSet = true;
 		if (!c._q5Color && typeof c != 'string') c = $.color(...arguments);
+		else if (basicColors[c]) c = $.color(...basicColors[c]);
 		if (c.a <= 0) return ($._doFill = false);
 		ctx.fillStyle = c.toString();
 	};
@@ -1059,7 +1062,8 @@ function Q5(scope, parent) {
 		if (c._q5) return $.image(c, 0, 0, $.width, $.height);
 		ctx.save();
 		ctx.resetTransform();
-		if (!c._q5color && typeof c != 'string') c = $.color(...arguments);
+		if (!c._q5Color && typeof c != 'string') c = $.color(...arguments);
+		else if (basicColors[c]) c = $.color(...basicColors[c]);
 		ctx.fillStyle = c.toString();
 		ctx.fillRect(0, 0, $.canvas.width, $.canvas.height);
 		ctx.restore();
@@ -2018,11 +2022,7 @@ function Q5(scope, parent) {
 		clearBuff();
 		firstVertex = true;
 		if (ctx) ctx.save();
-		try {
-			$.draw();
-		} catch (e) {
-			console.error(e);
-		}
+		$.draw();
 		for (let m of Q5.prototype._methods.post) m.call($);
 		if (ctx) {
 			ctx.restore();
@@ -2311,6 +2311,72 @@ function Q5(scope, parent) {
 		return $.audioContext.resume();
 	};
 
+	// AI
+
+	$.askAI = (q = '') => {
+		throw Error('Ask AI ✨ ' + q);
+	};
+
+	async function aiErrorAssistance(e) {
+		let askAI = e.message.includes('Ask AI ✨');
+		if (!askAI) console.error(e);
+		if (Q5.disableFriendlyErrors) return;
+		if (askAI || !Q5.errorTolerant) noLoop();
+		let stackLines = e.stack.split('\n');
+		if (stackLines.length <= 1) return;
+
+		let idx = 1;
+		let sep = '(';
+		if (navigator.userAgent.indexOf('Chrome') == -1) {
+			idx = 0;
+			sep = '@';
+		}
+		while (stackLines[idx].indexOf('q5.js:') >= 0) idx++;
+
+		let parts = stackLines[idx].split(sep).at(-1);
+		parts = parts.split(':');
+		let lineNum = parseInt(parts.at(-2));
+		if (askAI) lineNum++;
+		let fileUrl = parts.slice(0, -2).join(':');
+		let fileBase = fileUrl.split('/').at(-1);
+
+		try {
+			let res = await (await fetch(fileUrl)).text();
+			let lines = res.split('\n');
+			let errLine = lines[lineNum - 1].trim();
+
+			let context = '';
+			let i = 1;
+			while (context.length < 1600) {
+				if (lineNum - i >= 0) {
+					context = lines[lineNum - i].trim() + '\n' + context;
+				}
+				if (lineNum + i < lines.length) {
+					context += lines[lineNum + i].trim() + '\n';
+				}
+				i++;
+			}
+
+			let question =
+				askAI && e.message.length > 10 ? e.message.slice(10) : 'Whats+wrong+with+this+line%3F+short+answer';
+
+			let url =
+				'https://chatgpt.com/?q=q5.js+' +
+				question +
+				(askAI ? '' : '%0A%0A' + encodeURIComponent(e.name + ': ' + e.message)) +
+				'%0A%0ALine%3A+' +
+				encodeURIComponent(errLine) +
+				'%0A%0AExcerpt+for+context%3A%0A%0A' +
+				encodeURIComponent(context);
+
+			if (!askAI) console.log('Error in ' + fileBase + ' on line ' + lineNum + ':\n\n' + errLine);
+
+			console.warn('Ask AI ✨ ' + url);
+
+			if (askAI) window.open(url, '_blank');
+		} catch (err) {}
+	}
+
 	// INIT
 
 	if (scope == 'global') {
@@ -2354,7 +2420,7 @@ function Q5(scope, parent) {
 
 	let t = scope == 'global' ? (!Q5._nodejs ? window : global) : $;
 	let preloadDefined = t.preload;
-	let eventNames = [
+	let userFns = [
 		'setup',
 		'draw',
 		'preload',
@@ -2371,9 +2437,17 @@ function Q5(scope, parent) {
 		'touchEnded',
 		'windowResized'
 	];
-	for (let k of eventNames) {
+	for (let k of userFns) {
 		if (!t[k]) $[k] = () => {};
-		else if ($._isGlobal) $[k] = t[k];
+		else if ($._isGlobal) {
+			$[k] = () => {
+				try {
+					t[k]();
+				} catch (e) {
+					aiErrorAssistance(e);
+				}
+			};
+		}
 	}
 
 	$._isTouchAware = $.touchStarted || $.touchMoved || $.mouseReleased;
@@ -2382,7 +2456,10 @@ function Q5(scope, parent) {
 		window.addEventListener('mousemove', (e) => $._onmousemove(e), false);
 		window.addEventListener('keydown', (e) => $._onkeydown(e), false);
 		window.addEventListener('keyup', (e) => $._onkeyup(e), false);
-		window.addEventListener('resize', () => ($._shouldResize = true));
+		window.addEventListener('resize', () => {
+			$._shouldResize = true;
+			if (!$._loop) $.redraw();
+		});
 	}
 
 	if (!($.setup || $.draw)) return;
@@ -2765,7 +2842,7 @@ if (!window.matchMedia || !matchMedia('(dynamic-range: high) and (color-gamut: p
 
 Q5._instanceCount = 0;
 Q5._friendlyError = (msg, func) => {
-	throw func + ': ' + msg;
+	throw Error(func + ': ' + msg);
 };
 Q5._validateParameters = () => true;