q5 2.16.4 → 2.18.1

package/q5.d.ts

@@ -7,6 +7,20 @@
 declare global {
 	// ⭐️ core
 
+	/** ⭐️
+	 * Welcome to q5's documentation! ☺️
+	 * 
+	 * First time coding? Check out the [q5 Beginner's Guide to JavaScript](https://github.com/q5js/q5.js/wiki/q5-Beginner's-Guide-to-JavaScript).
+	 * 
+	 * On these Learn pages you'll find concise descriptions for
+	 * q5's functions and variables. Scroll through entire topics without
+	 * needing to click between separate pages.
+	 * 
+	 * Experiment with editing the code in the interactive mini examples,
+	 * which are often only 8 lines of code or less. They automatically
+	 * update as you type, so you can see results right away.
+	 */
+
 	/** ⭐️
 	 * The draw function is run 60 times per second by default.
 	 * @example
@@ -80,7 +94,7 @@ function draw() {
 	 * it calls the draw function once.
 	 * @param {number} [n] number of times to redraw the canvas, default is 1
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 noLoop();
 
 function draw() {
@@ -95,7 +109,7 @@ function mousePressed() {
 	/** ⭐️
 	 * Starts the draw loop again if it was stopped.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 noLoop();
 
 function draw() {
@@ -257,7 +271,7 @@ function draw() {
 	 * favor of having load* functions, such as `loadImage`,
 	 * return promises.
 	 * 
-	 * In q5 the `load` function can be used to load a file or
+	 * In q5 the [`load`](https://q5js.org/learn/#load) function can be used to load a file or
 	 * multiple files, and it returns a promise that resolves
 	 * when the file(s) are loaded.
 	 * 
@@ -281,7 +295,7 @@ function draw() {
 		 *
 		 * Running `new Q5()` enables the use of q5 functions and variables
 		 * anywhere in your code. You can also start Q5 in global mode by 
-		 * running [`createCanvas`](https://q5js.org/learn/#canvas-createCanvas).
+		 * running [`createCanvas`](https://q5js.org/learn/#createCanvas).
 		 * 
 		 * By default q5 uses the CanvasRenderingContext2D based c2d renderer.
 		 * 
@@ -332,10 +346,11 @@ circle(100, 50, 80);
 	 * Start using q5 by running this function!
 	 *
 	 * If this function is not run by the user, a 200x200 canvas will be
-	 * created automatically before the draw loop starts. Although in q5 
-	 * WebGPU, this function must be run before running other q5 functions.
-	 * @param {number} [w] width of the canvas, default is windowWidth
-	 * @param {number} [h] height of the canvas, default is windowHeight
+	 * created automatically before the draw loop starts.
+	 * 
+	 * In q5 WebGPU, this function must be run before running other q5 functions.
+	 * @param {number} [w] width or size of the canvas
+	 * @param {number} [h] height of the canvas
 	 * @param {Object} [opt] options for the canvas
 	 * @param {boolean} [opt.alpha] whether the canvas should have an alpha channel that allows it to be seen through, default is false
 	 * @param {string} [opt.colorSpace] color space of the canvas, either "srgb" or "display-p3", default is "display-p3" for devices that support HDR colors
@@ -356,96 +371,88 @@ function draw() {
 	/** ⬜️
 	 * The canvas element associated with the Q5 instance.
 	 * 
-	 * @prop {Number} w
-	 * @prop {Number} width
-	 * @prop {Number} h
-	 * @prop {Number} height
-	 * @prop {Number} hw half the width
-	 * @prop {Number} hh half the height
-	 * @prop {String} renderer either "c2d" (Canvas2D) or "webgpu"
+	 * @prop {number} w
+	 * @prop {number} width
+	 * @prop {number} h
+	 * @prop {number} height
+	 * @prop {number} hw half the width
+	 * @prop {number} hh half the height
+	 * @prop {string} renderer either "c2d" (Canvas2D) or "webgpu"
 	 */
 	var canvas: HTMLCanvasElement;
 
-	/** ⬜️
-	 * The width of the canvas.
-	 */
-	var width: number;
-
-	/** ⬜️
-	 * The height of the canvas.
-	 */
-	var height: number;
-
 	/** ⬜️
 	 * Clears the canvas, making every pixel completely transparent.
 	 *
-	 * The canvas can only be seen through if it has an alpha channel though.
+	 * Note that the canvas can only be seen through if it has an alpha channel.
 	 */
 	function clear(): void;
 
 	/** ⬜️
 	 * Sets the fill color for shapes. The default is white.
 	 * 
-	 * Like the [`color`](https://q5js.org/learn/#color) function, this function can accept colors in a wide range of formats: CSS color string, hex string, grayscale value, and color component values.
-	 * @param {string | Color} color fill color
+	 * Like the [`color`](https://q5js.org/learn/#color) function, this function
+	 * can accept colors in a wide range of formats: as a CSS color string,
+	 * a `Color` object, grayscale value, or color component values.
+	 * @param {Color} color fill color
 	 * @example
-function draw() {
-	background(200);
+createCanvas(200);
+background(200);
 
-  fill('red');
-  circle(80, 80, 80);
+fill('red');
+circle(80, 80, 80);
 
-	fill('lime');
-  square(80, 80, 80);
-}
+fill('lime');
+square(80, 80, 80);
 	 */
-	function fill(color: string | Color): void;
+	function fill(color: Color): void;
 
 	/** ⬜️
 	 * Sets the stroke (outline) color for shapes. The default is black.
 	 * 
-	 * Like the [`color`](https://q5js.org/learn/#color) function, this function can accept colors in a wide range of formats: CSS color string, hex string, grayscale value, and color component values.
-	 * @param {string | Color} color stroke color
+	 * Like the [`color`](https://q5js.org/learn/#color) function, this function
+	 * can accept colors in a wide range of formats: as a CSS color string,
+	 * a `Color` object, grayscale value, or color component values.
+	 * @param {Color} color stroke color
 	 * @example
-function draw() {
-  background(200);
-	fill(36);
+createCanvas(200);
+background(200);
+fill(36);
 
-  stroke('red');
-  circle(80, 80, 80);
-	stroke('lime');
-  square(80, 80, 80);
-}
+stroke('red');
+circle(80, 80, 80);
+
+stroke('lime');
+square(80, 80, 80);
 	 */
-	function stroke(color: string | Color): void;
+	function stroke(color: Color): void;
 
 	/** ⬜️
 	 * After calling this function, shapes will not be filled.
 	 * @example
-function draw() {
-  background(200);
+createCanvas(200);
+background(200);
 
-	noFill();
-  stroke('red');
-  circle(80, 80, 80);
-	stroke('lime');
-  square(80, 80, 80);
-}
+noFill();
+
+stroke('red');
+circle(80, 80, 80);
+stroke('lime');
+square(80, 80, 80);
 	 */
 	function noFill(): void;
 
 	/** ⬜️
 	 * After calling this function, shapes will not have a stroke (outline).
 	 * @example
-function draw() {
-  background(200);
-  fill(36);
-  stroke('red');
-  circle(80, 80, 80);
+createCanvas(200);
+background(200);
+fill(36);
+stroke('red');
+circle(80, 80, 80);
 
-	noStroke();
-  square(80, 80, 80);
-}
+noStroke();
+square(80, 80, 80);
 	 */
 	function noStroke(): void;
 
@@ -453,15 +460,13 @@ function draw() {
 	 * Sets the size of the stroke used for lines and the border around shapes.
 	 * @param {number} weight size of the stroke in pixels
 	 * @example
-function setup() {
-	createCanvas(200, 200);
-	background(200);
-	stroke('red');
-  circle(50, 100, 80);
+createCanvas(200);
+background(200);
+stroke('red');
+circle(50, 100, 80);
 
-  strokeWeight(20);
-  circle(150, 100, 80)
-}
+strokeWeight(20);
+circle(150, 100, 80);
 	 */
 	function strokeWeight(weight: number): void;
 
@@ -469,15 +474,14 @@ function setup() {
 	 * Sets the global opacity, which affects all subsequent drawing operations, except `background`. Default is 1, fully opaque.
 	 * @param {number} alpha opacity level, ranging from 0 to 1
 	 * @example
-function draw() {
-	background(200);
-	
-	opacity(1);
-	circle(80, 80, 80);
+createCanvas(200);
+background(200);
 
-	opacity(0.2);
-	square(80, 80, 80);
-}
+opacity(1);
+circle(80, 80, 80);
+
+opacity(0.2);
+square(80, 80, 80);
 	 */
 	function opacity(alpha: number): void;
 
@@ -487,19 +491,22 @@ function draw() {
 	 * Shadows apply to anything drawn to the canvas, including filled
 	 * shapes, strokes, text, and images.
 	 * 
-	 * Like the [`color`](https://q5js.org/learn/#color) function, this function can accept colors in a wide range of formats: CSS color string, hex string, grayscale value, and color component values.
-	 * @param {string | Color} color shadow color
+	 * Like the [`color`](https://q5js.org/learn/#color) function, this function
+	 * can accept colors in a wide range of formats: as a CSS color string,
+	 * a `Color` object, grayscale value, or color component values.
+	 * 
+	 * Not available in q5 WebGPU.
+	 * @param {Color} color shadow color
 	 * @example
-function draw() {
-  background(200);
-	
-	noFill();
-	shadow('black');
-	rect(64, 60, 80, 80);
-	text('q5', 100, 100);
-}
+createCanvas(200);
+background(200);
+
+noFill();
+shadow('black');
+rect(64, 60, 80, 80);
+text('q5', 100, 100);
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 let logo = loadImage('/assets/p5play_logo.webp');
 
 function setup() {
@@ -513,15 +520,14 @@ function setup() {
 	/** ⬜️
 	 * Disables the shadow effect.
 	 * @example
-function draw() {
-  background(200);
-	noStroke();
-	shadow('black');
-	rect(14, 14, 80, 80);
+createCanvas(200);
+background(200);
+noStroke();
+shadow('black');
+rect(14, 14, 80, 80);
 
-	noShadow();
-	rect(104, 104, 80, 80);
-}
+noShadow();
+rect(104, 104, 80, 80);
 	 */
 	function noShadow(): void;
 
@@ -533,27 +539,38 @@ function draw() {
 	 * @param {number} offsetY vertical offset of the shadow, defaults to be the same as offsetX
 	 * @param {number} blur blur radius of the shadow, defaults to 0
 	 * @example
-function draw() {
-	background(200);
-	noStroke();
-	shadow('red');
+createCanvas(200);
+noStroke();
+shadow(50);
 
-	shadowBox(-20, -8, 50);
+function draw() {
+  background(200);
+	shadowBox(-20, mouseY, 10);
 	circle(100, 100, 80, 80);
 }
 	 * @example
-function draw() {
-	background(200);
-	noStroke();
-	shadow('aqua');
-	shadowBox(20);
-	rect(50, 50, 100, 100);
-  textSize(64);
-  text('q5', 60, 115);
-}
+createCanvas(200);
+background(200);
+noStroke();
+
+shadow('aqua');
+shadowBox(20);
+rect(50, 50, 100, 100);
+textSize(64);
+text('q5', 60, 115);
 	 */
 	function shadowBox(offsetX: number, offsetY: number, blur: number): void;
 
+	/** ⬜️
+	 * The width of the canvas.
+	 */
+	var width: number;
+
+	/** ⬜️
+	 * The height of the canvas.
+	 */
+	var height: number;
+
 	/** ⬜️
 	 * Translates the origin of the drawing context.
 	 * @param {number} x translation along the x-axis
@@ -655,35 +672,42 @@ function draw() {
 	 * q5 runs this function before every time the `draw` function is run,
 	 * so that transformations don't carry over to the next frame.
 	 * @example
-function draw() {
-	background(200);
+createCanvas(200);
+background(200);
 
-	translate(100, 100);
-	circle(0, 0, 80);
+translate(100, 100);
+circle(0, 0, 80);
 
-	resetMatrix();
-	square(0, 0, 50);
-}
+resetMatrix();
+square(0, 0, 50);
 	 */
 	function resetMatrix(): void;
 
 	/** ⬜️
 	 * Saves the current transformation matrix.
 	 * @example
-function draw() {
-	background(200);
-	translate(100, 100);
-	pushMatrix();
-	rotate(QUARTER_PI);
-	ellipse(0, 0, 120, 40);
-	popMatrix();
-	ellipse(0, 0, 120, 40);
-}
+createCanvas(200);
+background(200);
+translate(100, 100);
+pushMatrix();
+rotate(QUARTER_PI);
+ellipse(0, 0, 120, 40);
+popMatrix();
+ellipse(0, 0, 120, 40);
 	 */
 	function pushMatrix(): void;
 
 	/** ⬜️
 	 * Restores the previously saved transformation matrix.
+	 * @example
+createCanvas(200);
+background(200);
+translate(100, 100);
+pushMatrix();
+rotate(QUARTER_PI);
+ellipse(0, 0, 120, 40);
+popMatrix();
+ellipse(0, 0, 120, 40);
 	 */
 	function popMatrix(): void;
 
@@ -714,7 +738,7 @@ function draw() {
 	/** ⬜️
 	 * Saves the current drawing style settings and transformations.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 push();
 fill('blue');
@@ -761,9 +785,11 @@ square(0, 0, 50);
 	/** ⬜️
 	 * Any position coordinates or dimensions you use will be scaled based
 	 * on the unit provided to this function.
+	 * 
+	 * Not available in q5 WebGPU.
 	 * @param {number} unit unit to scale by
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 flexibleCanvas(100);
 // rect will appear in the middle of the canvas
 rect(20, 20, 60, 60);
@@ -772,6 +798,8 @@ rect(20, 20, 60, 60);
 
 	/** ⬜️
 	 * Creates a graphics buffer.
+	 * 
+	 * Not available in q5 WebGPU.
 	 * @param {number} w width
 	 * @param {number} h height
 	 * @param {Object} [opt] options
@@ -780,7 +808,8 @@ rect(20, 20, 60, 60);
 	function createGraphics(w: number, h: number, opt?: any): Q5;
 
 	/** ⬜️
-	 * The 2D rendering context for the canvas.
+	 * The 2D rendering context for the canvas, if using the Canvas2D
+	 * renderer.
 	 */
 	var ctx: CanvasRenderingContext2D;
 
@@ -792,7 +821,7 @@ rect(20, 20, 60, 60);
 	// 💻 display
 
 	/** 💻
-	 * The `displayMode` function lets you customize how your canvas is presented.
+	 * Customize how your canvas is presented.
 	 * @param {string} mode
 	 *   - "normal": (default) no styling to canvas or its parent element
 	 *   - "centered": canvas will be centered horizontally and vertically within its parent and if the window is smaller than the canvas, the canvas will be resized to avoid clipping
@@ -814,17 +843,21 @@ circle(25, 12.5, 16);
 
 	/** 🧑‍🎨
 	 * Draws over the entire canvas with a color or image.
-	 * @param {string | number} color color or image to draw
+	 * 
+	 * Like the [`color`](https://q5js.org/learn/#color) function,
+	 * this function can accept colors in a wide range of formats:
+	 * CSS color string, grayscale value, and color component values.
+	 * @param {Color | Image} filler a color or image to draw
 	 * @example
 createCanvas(200, 100);
 background('crimson');
 	 * @example
 function draw() {
-	background(128, 20);
+	background(128, 100);
 	circle(mouseX, mouseY, 20);
 }
 	 */
-	function background(color: string | number): void;
+	function background(filler: Color | Image): void;
 
 	/** 🧑‍🎨
 	 * Draws a rectangle or a rounded rectangle.
@@ -837,7 +870,7 @@ function draw() {
 	 * @param {number} [br] bottom-right radius
 	 * @param {number} [bl] bottom-left radius
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 background(200);
 
 rect(30, 20, 40, 60);
@@ -856,7 +889,7 @@ rect(130, 120, 40, 60, 30, 2, 8, 20);
 	 * @param {number} [br] bottom-right radius
 	 * @param {number} [bl] bottom-left radius
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 background(200);
 
 square(30, 30, 40);
@@ -900,7 +933,7 @@ ellipse(100, 50, 160, 80);
 	 * @param {number} stop angle to stop the arc
 	 * @param {number} [mode] shape and stroke style setting, default is `PIE_OPEN` for a pie shape with an unclosed stroke, can be `PIE`, `CHORD`, or `CHORD_OPEN`
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 background(200);
 
 arc(40, 40, 40, 40, 0.8, -0.8);
@@ -1096,6 +1129,263 @@ point(125, 50);
 	 */
 	function inStroke(x: number, y: number): boolean;
 
+	// 📑 dom
+
+	/** 📑
+	 * Creates a new HTML element and adds it to the page. `createEl` is
+	 * an alias.
+	 * 
+	 * The element is part of the DOM (Document Object Model), an interface for
+	 * creating and editing web pages with JavaScript.
+	 * 
+	 * Modify the element's CSS [`style`](https://developer.mozilla.org/docs/Web/API/HTMLElement/style) to change its appearance.
+	 * 
+	 * Use [`addEventListener`](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener) to respond to events such as:
+	 * - "click": when the element is clicked
+	 * - "mouseover": when the mouse hovers over the element
+	 * - "mouseout": when the mouse stops hovering over the element
+	 * - "input": when a form element's value changes
+	 * 
+	 * q5 adds some extra functionality to the elements it creates:
+	 * 
+	 * - the `position` function makes it easy to place the element
+	 * relative to the canvas
+	 * - the `size` function sets the width and height of the element
+	 * - alternatively, use the element's `x`, `y`, `width`, and `height` properties
+	 * @param {string} tag tag name of the element
+	 * @param {string} [content] content of the element
+	 * @returns {HTMLElement} element
+	 * @example
+createCanvas(200);
+
+let el = createEl('div', '*');
+el.position(50, 50);
+el.size(100, 100);
+el.style.fontSize = '136px';
+el.style.textAlign = 'center';
+el.style.backgroundColor = 'blue';
+el.style.color = 'white';
+	 */
+	function createElement(tag: string, content?: string): HTMLElement;
+
+	/** 📑
+	 * Creates a link element.
+	 * @param {string} href url
+	 * @param {string} [text] text content
+	 * @param {boolean} [newTab] whether to open the link in a new tab
+	 * @example
+createCanvas(200);
+
+let link = createA('https://q5js.org', 'q5.js');
+link.position(16, 42);
+link.style.fontSize = '80px';
+
+link.addEventListener('mouseover', () => {
+	background('blue');
+});
+	 */
+	function createA(href: string, text?: string): HTMLAnchorElement;
+
+	/** 📑
+	 * Creates a button element.
+	 * @param {string} [content] text content
+	 * @example
+createCanvas(200, 100);
+
+let btn = createButton('Click me!');
+
+btn.addEventListener('click', () => {
+	background(random(100, 255));
+});
+	 */
+	function createButton(content?: string): HTMLButtonElement;
+
+	/** 📑
+	 * Creates a checkbox element.
+	 * 
+	 * Use the `checked` property to get or set the checkbox's state.
+	 * 
+	 * The `label` property is the text label element next to the checkbox.
+	 * @param {string} [label] text label placed next to the checkbox
+	 * @param {boolean} [checked] initial state
+	 * @example
+createCanvas(200, 100);
+
+let box = createCheckbox('Check me!');
+box.label.style.color = 'lime';
+
+box.addEventListener('input', () => {
+	if (box.checked) background('lime');
+	else background('black');
+});
+	 */
+	function createCheckbox(label?: string, checked?: boolean): HTMLInputElement;
+
+	/** 📑
+	 * Creates a color input element.
+	 * 
+	 * Use the `value` property to get or set the color value.
+	 * @param {string} [value] initial color value
+	 * @example
+createCanvas(200, 100);
+
+let picker = createColorPicker();
+picker.value = '#fd7575';
+
+function draw() {
+	background(picker.value);
+}
+	 */
+	function createColorPicker(value?: string): HTMLInputElement;
+
+	/** 📑
+	 * Creates an image element.
+	 * @param {string} src url of the image
+	 * @example
+createCanvas(200, 100);
+
+let img = createImg('/assets/p5play_logo.webp')
+	.position(0, 0)
+	.size(100, 100);
+	 */
+	function createImg(src: string): HTMLImageElement;
+
+	/** 📑
+	 * Creates an input element.
+	 * 
+	 * Use the `value` property to get or set the input's value.
+	 * 
+	 * See MDN's [input documentation](https://developer.mozilla.org/docs/Web/HTML/Element/input#input_types) for the full list of input types.
+	 * @param {string} [value] initial value
+	 * @param {string} [type] text input type, can be 'text', 'password', 'email', 'number', 'range', 'search', 'tel', 'url'
+	 * @example
+createCanvas(200, 100);
+textSize(64);
+
+let input = createInput();
+input.placeholder = 'Type here!';
+input.size(200, 32);
+
+input.addEventListener('input', () => {
+	background('orange');
+	text(input.value, 10, 70);
+});
+	 */
+	function createInput(value?: string, type?: string): HTMLInputElement;
+
+	/** 📑
+	 * Creates a paragraph element.
+	 * @param {string} [content] text content
+	 * @example
+createCanvas(200, 50);
+background('coral');
+
+let p = createP('Hello, world!');
+p.style.color = 'pink';
+	 */
+	function createP(content?: string): HTMLParagraphElement;
+
+	/** 📑
+	 * Creates a radio button group.
+	 * 
+	 * Use the `option(label, value)` function to add new radio buttons
+	 * to the group.
+	 * 
+	 * Use the `value` property to get or set the value of the selected radio button.
+	 * @param {string} [groupName]
+	 * @example
+createCanvas(200, 100);
+
+let radio = createRadio()
+	.option('square', '1')
+	.option('circle', '2');
+radio.style.color = 'aqua';
+
+function draw() {
+	background(200);
+	if (radio.value == '1') square(75, 25, 50);
+	if (radio.value == '2') circle(100, 50, 50);
+}
+	 */
+	function createRadio(groupName): HTMLDivElement;
+
+	/** 📑
+	 * Creates a select element.
+	 * 
+	 * Use the `option(label, value)` function to add new options to
+	 * the select element.
+	 * 
+	 * Set `multiple` to `true` to allow multiple options to be selected.
+	 * 
+	 * Use the `value` property to get or set the selected option value.
+	 * 
+	 * Use the `selected` property get the labels of the selected 
+	 * options or set the selected options by label. Can be a single 
+	 * string or an array of strings.
+	 * @param {string} [placeholder] optional placeholder text that appears before an option is selected
+	 * @example
+createCanvas(200, 100);
+
+let sel = createSelect('Select a color')
+	.option('Red', '#f55')
+	.option('Green', '#5f5');
+
+sel.addEventListener('change', () => {
+	background(sel.value);
+});
+	 */
+	function createSelect(placeholder): HTMLSelectElement;
+
+	/** 📑
+	 * Creates a slider element.
+	 * 
+	 * Use the `value` property to get or set the slider's value.
+	 * 
+	 * Use the `val` function to get the slider's value as a number.
+	 * @param {number} min minimum value
+	 * @param {number} max maximum value
+	 * @param {number} [value] initial value
+	 * @param {number} [step] step size
+	 * @example
+createCanvas(200);
+
+let slider = createSlider(0, 255)
+	.position(10, 10)
+	.size(180);
+
+function draw() {
+	background(slider.val());
+}
+	 */
+	function createSlider(min: number, max: number, value?: number, step?: number): HTMLInputElement;
+
+	/** 📑
+	 * Creates a video element.
+	 * @param {string} src url of the video
+	 * @example
+createCanvas(200, 100);
+
+// example coming soon
+// let vid = createVideo('/assets/q5js_video.mp4');
+// vid.controls = true;
+// vid.loop = true;
+	 */
+	function createVideo(src: string): HTMLVideoElement;
+
+	/** 📑
+	 * Finds the first element in the DOM that matches the given [CSS selector](https://developer.mozilla.org/docs/Learn_web_development/Core/Styling_basics/Basic_selectors).
+	 * @param {string} selector
+	 * @returns {HTMLElement} element
+	 */
+	function findElement(selector: string): HTMLElement;
+
+	/** 📑
+	 * Finds all elements in the DOM that match the given [CSS selector](https://developer.mozilla.org/docs/Learn_web_development/Core/Styling_basics/Basic_selectors).
+	 * @param {string} selector
+	 * @returns {HTMLElement[]} elements
+	 */
+	function findElements(selector: string): HTMLElement[];
+
 	// 🌆 image
 
 	/** 🌆
@@ -1104,7 +1394,7 @@ point(125, 50);
 	 * @param {(img: any) => void} [cb] callback function after the image is loaded
 	 * @param {any} [opt] optional parameters for loading the image
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 let logo = loadImage('/q5js_logo.webp');
 
@@ -1126,7 +1416,7 @@ function draw() {
 	 * @param {number} [sw] width of the subsection of the source image
 	 * @param {number} [sh] height of the subsection of the source image
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 let logo = loadImage('/q5js_logo.webp');
 
@@ -1143,7 +1433,7 @@ function draw() {
 	 * `CENTER`: images will be drawn centered at (dx, dy)
 	 * @param {string} mode
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 let logo = loadImage('/q5js_logo.webp');
 
@@ -1174,7 +1464,7 @@ function draw() {
 	 * @param {number} w new width
 	 * @param {number} h new height
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 let logo = loadImage('/q5js_logo.webp');
 
@@ -1196,7 +1486,7 @@ function setup() {
 	 * their actual size. This is the default setting, so running this
 	 * function only has an effect if `noSmooth` has been called.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 let icon = loadImage('/q5js_icon.png');
 
@@ -1209,7 +1499,7 @@ function setup() {
 	/** 🌆
 	 * Disables smooth image rendering for a pixelated look.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 let icon = loadImage('/q5js_icon.png');
 
@@ -1240,7 +1530,7 @@ function setup() {
 	 * each copy separately.
 	 * @param {string | number} color tint color
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 let logo = loadImage('/q5js_logo.webp');
 
@@ -1279,7 +1569,7 @@ function setup() {
 	 * @param {number} [h] height of the area
 	 * @returns {Image | number[]}
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 let logo = loadImage('/q5js_logo.webp');
 
@@ -1301,7 +1591,7 @@ function setup() {
 	 * @param {number} y
 	 * @param {any} c color, canvas, or image
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 let c = color('lime');
 
 function draw() {
@@ -1329,7 +1619,7 @@ function draw() {
 	 * @param {number} dw width of the destination region
 	 * @param {number} dh height of the destination region
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 let logo = loadImage('/q5js_logo.webp');
 
@@ -1348,7 +1638,7 @@ function setup() {
 	/** 🌆
 	 * Loads pixel data into the canvas' or image's `pixels` array.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 let icon = loadImage('/q5js_icon.png');
 
 function setup() {
@@ -1363,7 +1653,7 @@ function setup() {
 	/** 🌆
 	 * Applies changes in the `pixels` array to the canvas or image.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 function setup() {
 	for (let x = 0; x < 200; x += 5) {
 		for (let y = 0; y < 200; y += 5) {
@@ -1391,7 +1681,7 @@ function setup() {
 	 * @param {string} type filter type or a CSS filter string
 	 * @param {number} [value] optional value, depends on filter type
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 let logo = loadImage('/q5js_logo.webp');
 
 function setup() {
@@ -1443,8 +1733,8 @@ function setup() {
 
 	/** 🌆
 	 * Creates a new image.
-	 * @param {number} [w] character limit per line
-	 * @param {number} [h] line limit
+	 * @param {number} w width
+	 * @param {number} h height
 	 * @param {any} [opt] optional settings for the image
 	 * @returns {Image}
 	 */
@@ -1461,19 +1751,20 @@ function setup() {
 	 * @param {number} [wrapWidth] maximum line width in characters
 	 * @param {number} [lineLimit] maximum number of lines
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 background('silver');
 
 textSize(32);
 text('Hello, world!', 12, 106);
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 background(200);
 textSize(20);
 
 let info = "q5.js is a JavaScript library for creative coding. It's a sequel to p5.js that's optimized for interactive art.";
 
 text(info, 12, 30, 20, 6);
+//
 //
 	 */
 	function text(str: string, x: number, y: number, wrapWidth?: number, lineLimit?: number): void;
@@ -1497,7 +1788,7 @@ text(info, 12, 30, 20, 6);
 	 * @param {(font: FontFace) => void} [cb] optional callback function that receives the font name as an argument once the font is loaded
 	 * @returns {FontFace} font
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 loadFont('/assets/Robotica.ttf');
 
@@ -1520,7 +1811,7 @@ function setup() {
 	 * https://developer.mozilla.org/docs/Web/CSS/font-family
 	 * @param {string} fontName name of the font family or a FontFace object
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 background(200);
 
 textFont('serif');
@@ -1563,7 +1854,7 @@ function draw() {
 	 * Sets the current text style.
 	 * @param {'normal' | 'italic' | 'bold' | 'bolditalic'} style font style
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 background(200);
 
 textStyle(ITALIC);
@@ -1578,7 +1869,7 @@ text('Hello, world!', 12, 106);
 	 * @param {'left' | 'center' | 'right'} horiz horizontal alignment
 	 * @param {'top' | 'middle' | 'bottom' | 'alphabetic'} [vert] vertical alignment
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 background(200);
 
 textAlign(CENTER, MIDDLE);
@@ -1623,7 +1914,7 @@ function draw() {
 	 * @param {string} str string to measure
 	 * @returns {number} descent of the text in pixels
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 	background(200);
 	textSize(64);
 
@@ -1723,30 +2014,54 @@ createCanvas(200, 200);
 	// 🎨 color
 
 	/** 🎨
-	 * Creates a new `Color` object. This function can parse different
-	 * color representations depending on the current color mode.
+	 * Creates a new `Color` object, which is primarily useful for storing
+	 * a color that your sketch will reuse or modify later.
 	 * 
-	 * RGB colors have components `r`/`red`, `g`/`green`, `b`/`blue`,
-	 * and `a`/`alpha`.
+	 * With the default RGB color mode, colors have these components:
 	 * 
-	 * When only one numeric input is provided, it'll be interpreted
-	 * as a grayscale value. If only two numeric inputs are provided, 
-	 * they will be used as grayscale and alpha values.
+	 * `r`/`red`, `g`/`green`, `b`/`blue`, and `a`/`alpha`.
 	 * 
-	 * [`fill`](https://q5js.org/learn/#fill), [`stroke`](https://q5js.org/learn/#stroke), and [`background`](https://q5js.org/learn/#background) functions can accept the same
-	 * wide range of inputs as this function.
-	 * @param {string | number | Color | number[]} c0 first color component, a CSS color string, a `Color` object (to make copy), or an array of components
+	 * The default color format is integer, so set color components
+	 * to values between 0 and 255.
+	 * 
+	 * In q5 WebGPU, the default color mode is RGB in float format, so
+	 * set color components to values between 0 and 1.
+	 * 
+	 * The [`fill`](https://q5js.org/learn/#fill), [`stroke`](https://q5js.org/learn/#stroke), and [`background`](https://q5js.org/learn/#background) functions
+	 * accept the same wide range of color representations as this function.
+	 * 
+	 * Here are some examples of valid use:
+	 * 
+	 * - `color(255)` (grayscale)
+	 * - `color(255, 200)` (grayscale, alpha)
+	 * - `color(255, 0, 0)` (r, g, b)
+	 * - `color(255, 0, 0, 10)` (r, g, b, a)
+	 * - `color('red')` (colorName)
+	 * - `color('#ff0000')` (hexColor)
+	 * - `color([255, 0, 0])` (colorComponents)
+	 * @param {string | number | Color | number[]} c0 color or first color component
 	 * @param {number} [c1] second color component
 	 * @param {number} [c2] third color component
 	 * @param {number} [c3] fourth color component (alpha)
 	 * @returns {Color} a new `Color` object
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
+rect(0, 0, 100, 200);
 
-let c = color('gray');
+//                ( r,   g,   b,   a)
+let bottle = color(90, 100, 255, 100);
+fill(bottle);
+stroke(bottle);
+strokeWeight(30);
+circle(100, 100, 155);
+	 * @example
+createCanvas(200);
+//          (gray, alpha)
+let c = color(200, 50);
 
 function draw() {
 	background(c);
+	circle(mouseX, mouseY, 50);
 	c.g = (c.g + 1) % 255;
 }
 	 */
@@ -1763,7 +2078,7 @@ function draw() {
 	 * @param {'rgb' | 'srgb' | 'oklch'} mode color mode
 	 * @param {1 | 255} format color format (1 for float, 255 for integer)
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 colorMode(RGB, 1);
 fill(1, 0, 0);
@@ -1773,12 +2088,13 @@ rect(66, 0, 67, 200);
 fill(0, 0, 1);
 rect(133, 0, 67, 200);
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 colorMode(OKLCH);
 
 fill(0.25, 0.15, 0);
 rect(0, 0, 100, 200);
+
 fill(0.75, 0.15, 0)
 rect(100, 0, 100, 200);
 	 */
@@ -1794,7 +2110,7 @@ rect(100, 0, 100, 200);
 	 * rgb colors are mapped to the full P3 gamut, even when they use the
 	 * legacy integer format.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 function setup() {
 	background(255, 0, 0);
@@ -1809,7 +2125,7 @@ function setup() {
 	 * example, note that full red appears less saturated, as it would
 	 * on an SDR display.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 colorMode(SRGB, 255);
 
@@ -1843,7 +2159,7 @@ function setup() {
 	 * 
 	 * Note how seamless the hue transitions are in the following example.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 colorMode(OKLCH);
 
 function draw() {
@@ -1963,7 +2279,7 @@ function draw() {
 	/** 🖲️
 	 * Hides the cursor within the bounds of the canvas.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 noCursor();
 	 */
 	function noCursor(): void;
@@ -2147,6 +2463,75 @@ noCursor();
 	 */
 	const TAU: number;
 
+	// 🎞️ record
+
+	/** 🎞️
+	 * Creates a recorder. Simply hit record to start recording!
+	 * 
+	 * Recording large canvases is an intensive process, so your
+	 * computer may not be able to do it in real time. That's okay,
+	 * the resulting video will playback at your sketch's target 
+	 * frame rate.
+	 * 
+	 * In cases where real time interaction is a priority, consider 
+	 * reducing the canvas' size, frame rate, and/or recording
+	 * quality.
+	 * 
+	 * `format` and `quality` properties are set 
+	 * automatically based on the height of the canvas. They can be
+	 * changed via the UI or programmatically.
+	 * 
+	 * The recorder uses the [`MediaRecorder`](https://developer.mozilla.org/docs/Web/API/MediaRecorder/MediaRecorder) API, which 
+	 * unfortunately can't encode HDR video.
+	 * @returns {HTMLElement} a recorder, q5 DOM element
+	 * @example
+createCanvas(200);
+
+createRecorder();
+
+function draw() {
+	circle(mouseX, random(canvas.h), 10);
+}
+	 */
+	function createRecorder(): HTMLElement;
+
+	/** 🎞️
+	 * Starts recording the canvas or resumes recording if it was paused.
+	 * 
+	 * If no recorder exists, one is created but not displayed.
+	 */
+	function record(): void;
+
+	/** 🎞️
+	 * Pauses the canvas recording, if one is in progress.
+	 */
+	function pauseRecording(): void;
+
+	/** 🎞️
+	 * Discards the current recording.
+	 */
+	function deleteRecording(): void;
+
+	/** 🎞️
+	 * Saves the current recording as a video file.
+	 * @param {string} fileName
+	 * @example
+function draw() {
+	square(mouseX, random(canvas.h), 10);
+}
+
+function mousePressed() {
+	if (!recording) record();
+	else saveRecording('squares');
+}
+	 */
+	function saveRecording(fileName): void;
+
+	/** 🎞️
+	 * True if the canvas is currently being recorded.
+	 */
+	var recording: boolean;
+
 	// 🔊 sound
 
 	/** 🔊
@@ -2169,7 +2554,7 @@ noCursor();
 	 * @param {string} url sound file
 	 * @returns {Sound} a new `Sound` object
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 let sound = loadSound('/assets/jump.wav');
 sound.volume = 0.3;
@@ -2190,7 +2575,7 @@ function mousePressed() {
 	 * @param url audio file
 	 * @returns {HTMLAudioElement} an HTMLAudioElement
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 let audio = loadAudio('/assets/retro.flac');
 audio.volume = 0.4;
@@ -2299,7 +2684,7 @@ function draw() {
 }
 	 * @example
 new Q5();
-createCanvas(200, 200);
+createCanvas(200);
 
 // use with top level await in a module
 await load('/assets/Robotica.ttf');
@@ -2308,7 +2693,7 @@ background(255);
 text('Hello, world!', 20, 100);
 	 * @example
 let q = new Q5();
-createCanvas(200, 200);
+createCanvas(200);
 
 let [jump, retro] = await load(
 		'/assets/jump.wav', '/assets/retro.flac'