q5 2.16.0 → 2.17.0

package/q5.d.ts

@@ -80,7 +80,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 +95,7 @@ function mousePressed() {
 	/** ⭐️
 	 * Starts the draw loop again if it was stopped.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 noLoop();
 
 function draw() {
@@ -248,7 +248,7 @@ function draw() {
 	var deltaTime: number;
 
 	/** ⭐️
-	 * q5 uses the same preload system as Java Processing and p5.js v1
+	 * q5 uses the same preload system as p5.js v1
 	 * to load assets asynchronously, before the setup and draw
 	 * functions are run. It makes it very easy for users to
 	 * load many images, sounds, and other assets at the same time.
@@ -257,7 +257,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 +281,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 +332,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
@@ -355,91 +356,89 @@ 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"
 	 */
 	var canvas: HTMLCanvasElement;
 
-	/** ⬜️
-	 * The width of the canvas.
-	 * Can also be accessed via `canvas.w`/`canvas.width`.
-	 */
-	var width: number;
-
-	/** ⬜️
-	 * The height of the canvas.
-	 * Can also be accessed via `canvas.h`/`canvas.height`.
-	 */
-	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;
 
@@ -447,15 +446,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;
 
@@ -463,15 +460,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;
 
@@ -481,19 +477,20 @@ 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.
+	 * @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() {
@@ -507,15 +504,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;
 
@@ -527,27 +523,36 @@ 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);
+background(200);
+noStroke();
+shadow('red');
 
-	shadowBox(-20, -8, 50);
-	circle(100, 100, 80, 80);
-}
+shadowBox(-20, -8, 50);
+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
@@ -649,35 +654,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;
 
@@ -708,7 +720,7 @@ function draw() {
 	/** ⬜️
 	 * Saves the current drawing style settings and transformations.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 push();
 fill('blue');
@@ -757,7 +769,7 @@ square(0, 0, 50);
 	 * on the unit provided to this function.
 	 * @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);
@@ -790,12 +802,17 @@ rect(20, 20, 60, 60);
 	 * @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
-	 *   - "maxed": canvas will fill the parent element, same as fullscreen for a canvas inside a `main` element
-	 *   - "fullscreen": canvas will fill the screen with letterboxing if necessary to preserve its aspect ratio
+	 *   - "maxed": canvas will fill the parent element, with letterboxing if necessary to preserve its aspect ratio
 	 * @param {string} renderQuality
 	 *   - "smooth": (default) no change to the default render quality
 	 *   - "pixelated": runs `pixelDensity(1)` and `noSmooth()` then sets the canvas CSS styles `image-rendering: pixelated` and `font-smooth: never`
 	 * @param {number} scale can also be given as a string (for example "x2")
+	 * @example
+createCanvas(50, 25);
+
+displayMode('centered', 'pixelated', 4);
+
+circle(25, 12.5, 16);
 	 */
 	function displayMode(mode: string, renderQuality: string, scale: string | number): void;
 
@@ -803,32 +820,58 @@ rect(20, 20, 60, 60);
 
 	/** 🧑‍🎨
 	 * 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);
+	circle(mouseX, mouseY, 20);
+}
 	 */
-	function background(color: string | number): void;
+	function background(filler: Color | Image): void;
 
 	/** 🧑‍🎨
-	 * Draws a rectangle.
+	 * Draws a rectangle or a rounded rectangle.
 	 * @param {number} x x-coordinate
 	 * @param {number} y y-coordinate
 	 * @param {number} w width of the rectangle
 	 * @param {number} [h] height of the rectangle
-	 * @param {number} [tl] top-left radius for rounded corners
-	 * @param {number} [tr] top-right radius for rounded corners
-	 * @param {number} [br] bottom-right radius for rounded corners
-	 * @param {number} [bl] bottom-left radius for rounded corners
+	 * @param {number} [tl] top-left radius
+	 * @param {number} [tr] top-right radius
+	 * @param {number} [br] bottom-right radius
+	 * @param {number} [bl] bottom-left radius
+	 * @example
+createCanvas(200);
+background(200);
+
+rect(30, 20, 40, 60);
+rect(80, 70, 40, 60, 10);
+rect(130, 120, 40, 60, 30, 2, 8, 20);
 	 */
 	function rect(x: number, y: number, w: number, h?: number, tl?: number, tr?: number, br?: number, bl?: number): void;
 
 	/** 🧑‍🎨
-	 * Draws a square.
+	 * Draws a square or a rounded square.
 	 * @param {number} x x-coordinate
 	 * @param {number} y y-coordinate
 	 * @param {number} size size of the sides of the square
-	 * @param {number} [tl] top-left radius for rounded corners
-	 * @param {number} [tr] top-right radius for rounded corners
-	 * @param {number} [br] bottom-right radius for rounded corners
-	 * @param {number} [bl] bottom-left radius for rounded corners
+	 * @param {number} [tl] top-left radius
+	 * @param {number} [tr] top-right radius
+	 * @param {number} [br] bottom-right radius
+	 * @param {number} [bl] bottom-left radius
+	 * @example
+createCanvas(200);
+background(200);
+
+square(30, 30, 40);
+square(80, 80, 40, 10);
+square(130, 130, 40, 30, 2, 8, 20);
 	 */
 	function square(x: number, y: number, size: number, tl?: number, tr?: number, br?: number, bl?: number): void;
 
@@ -837,6 +880,9 @@ rect(20, 20, 60, 60);
 	 * @param {number} x x-coordinate
 	 * @param {number} y y-coordinate
 	 * @param {number} diameter diameter of the circle
+	 * @example
+createCanvas(200, 100);
+circle(100, 50, 80);
 	 */
 	function circle(x: number, y: number, diameter: number): void;
 
@@ -846,6 +892,9 @@ rect(20, 20, 60, 60);
 	 * @param {number} y y-coordinate
 	 * @param {number} width width of the ellipse
 	 * @param {number} [height] height of the ellipse
+	 * @example
+createCanvas(200, 100);
+ellipse(100, 50, 160, 80);
 	 */
 	function ellipse(x: number, y: number, width: number, height?: number): void;
 
@@ -861,14 +910,13 @@ rect(20, 20, 60, 60);
 	 * @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
-function draw() {
-	background(200);
+createCanvas(200);
+background(200);
 
-	arc(40, 40, 40, 40, 0.8, -0.8);
-  arc(80, 80, 40, 40, 0.8, -0.8, PIE);
-  arc(120, 120, 40, 40, 0.8, -0.8, CHORD_OPEN);
-  arc(160, 160, 40, 40, 0.8, -0.8, CHORD);
-}
+arc(40, 40, 40, 40, 0.8, -0.8);
+arc(80, 80, 40, 40, 0.8, -0.8, PIE);
+arc(120, 120, 40, 40, 0.8, -0.8, CHORD_OPEN);
+arc(160, 160, 40, 40, 0.8, -0.8, CHORD);
 	 */
 	function arc(x: number, y: number, w: number, h: number, start: number, stop: number, mode?: number): void;
 
@@ -878,6 +926,10 @@ function draw() {
 	 * @param {number} y1 y-coordinate of the first point
 	 * @param {number} x2 x-coordinate of the second point
 	 * @param {number} y2 y-coordinate of the second point
+	 * @example
+createCanvas(200, 100);
+stroke('lime');
+line(20, 20, 180, 80);
 	 */
 	function line(x1: number, y1: number, x2: number, y2: number): void;
 
@@ -885,6 +937,13 @@ function draw() {
 	 * Draws a point on the canvas.
 	 * @param {number} x x-coordinate
 	 * @param {number} y y-coordinate
+	 * @example
+createCanvas(200, 100);
+stroke('white');
+point(75, 50);
+
+strokeWeight(10);
+point(125, 50);
 	 */
 	function point(x: number, y: number): void;
 
@@ -1029,6 +1088,8 @@ function draw() {
 
 	/** 🧑‍🎨
 	 * Checks if a given point is within the current path's fill area.
+	 * 
+	 * Not available in q5 WebGPU.
 	 * @param {number} x x-coordinate of the point
 	 * @param {number} y y-coordinate of the point
 	 * @returns {boolean} true if the point is within the fill area, false otherwise
@@ -1037,12 +1098,240 @@ function draw() {
 
 	/** 🧑‍🎨
 	 * Checks if a given point is within the current path's stroke.
+	 * 
+	 * Not available in q5 WebGPU.
 	 * @param {number} x x-coordinate of the point
 	 * @param {number} y y-coordinate of the point
 	 * @returns {boolean} true if the point is within the stroke, false otherwise
 	 */
 	function inStroke(x: number, y: number): boolean;
 
+	// 📑 dom
+
+	/** 📑
+	 * Creates a new HTML element.
+	 * 
+	 * q5 adds functions like `position` and `size` to the element
+	 * that make it easy to position elements above the canvas.
+	 * 
+	 * Modify the element's CSS [`style`](https://developer.mozilla.org/docs/Web/API/HTMLElement/style) to change its appearance.
+	 * 
+	 * `createEl` is an alias for this function.
+	 * @param {string} tag tag name of the element
+	 * @param {string} [content] content of the element
+	 * @returns {HTMLElement} created DOM element
+	 * @example
+createCanvas(200);
+
+let el = createEl('div', '*');
+el.position(0, 0);
+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, 100);
+
+let link = createA('https://q5js.org', 'q5.js');
+link.position(0, 0);
+link.style.fontSize = '80px';
+	 */
+	function createA(href: string, text?: string): HTMLAnchorElement;
+
+	/** 📑
+	 * Creates a button element.
+	 * 
+	 * Use [`addEventListener`](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener) to respond to button click events.
+	 * @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('change', () => {
+	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 img 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.
+	 * 
+	 * Use the `selected` property to get the selected option or options.
+	 * @param {boolean} [placeholder] optional placeholder text that appears when no 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);
+
+// let vid = createVideo('/assets/q5js_video.mp4');
+// vid.controls = true;
+// vid.loop = true;
+	 */
+	function createVideo(src: string): HTMLVideoElement;
+
 	// 🌆 image
 
 	/** 🌆
@@ -1051,7 +1340,7 @@ function draw() {
 	 * @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');
 
@@ -1073,7 +1362,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');
 
@@ -1090,7 +1379,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');
 
@@ -1121,7 +1410,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');
 
@@ -1143,7 +1432,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');
 
@@ -1156,7 +1445,7 @@ function setup() {
 	/** 🌆
 	 * Disables smooth image rendering for a pixelated look.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 let icon = loadImage('/q5js_icon.png');
 
@@ -1187,7 +1476,7 @@ function setup() {
 	 * each copy separately.
 	 * @param {string | number} color tint color
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 let logo = loadImage('/q5js_logo.webp');
 
@@ -1226,7 +1515,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');
 
@@ -1248,7 +1537,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() {
@@ -1276,7 +1565,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');
 
@@ -1295,7 +1584,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() {
@@ -1310,7 +1599,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) {
@@ -1338,7 +1627,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() {
@@ -1401,29 +1690,29 @@ function setup() {
 
 	/** ✍️
 	 * Renders text to the screen. Text can be positioned with the x and y
-	 * parameters and can optionally be constrained by a character limit
-	 * per line and a line limit.
+	 * parameters and can optionally be constrained.
 	 * @param {string} str string of text to display
 	 * @param {number} x x-coordinate of the text's position
 	 * @param {number} y y-coordinate of the text's position
-	 * @param {number} [w] character limit per line
-	 * @param {number} [h] line limit
+	 * @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, w?: number, h?: number): void;
+	function text(str: string, x: number, y: number, wrapWidth?: number, lineLimit?: number): void;
 
 	/** ✍️
 	 * Loads a font from a URL and optionally runs a callback function
@@ -1444,7 +1733,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');
 
@@ -1467,7 +1756,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');
@@ -1510,7 +1799,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);
@@ -1525,7 +1814,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);
@@ -1570,7 +1859,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);
 
@@ -1580,15 +1869,13 @@ createCanvas(200, 200);
 	function textDescent(str: string): number;
 
 	/** ✍️
-	 * Creates an image from a string of text. Width and height
-	 * will not be the width and height of the text image, but of
-	 * the bounding box that the text will be constrained within.
+	 * Creates an image from a string of text.
 	 * @param {string} str string of text
-	 * @param {number} w width of the bounding box
-	 * @param {number} h height of the bounding box
+	 * @param {number} [wrapWidth] maximum line width in characters
+	 * @param {number} [lineLimit] maximum number of lines
 	 * @returns {Q5.Image} an image object representing the rendered text
 	 */
-	function createTextImage(str: string, w: number, h: number): Q5.Image;
+	function createTextImage(str: string, wrapWidth: number, lineLimit: number): Q5.Image;
 
 	/** ✍️
 	 * Renders an image generated from text onto the canvas. The
@@ -1672,27 +1959,49 @@ 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:
+	 * 
+	 * `r`/`red`, `g`/`green`, `b`/`blue`, and `a`/`alpha`.
+	 * 
+	 * The default color format is integer, so set color components
+	 * to values between 0 and 255.
 	 * 
-	 * 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.
+	 * In q5 WebGPU, the default color mode is RGB in float format, so
+	 * set color components to values between 0 and 1.
 	 * 
-	 * `fill`, `stroke`, and `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 [`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);
+//                (gray, alpha)
+let darkGray = color(55, 100);
+background(darkGray);
+//	                  (r, g,   b,  a)
+let blueBottle = color(0, 0, 200, 20);
+fill(blueBottle);
+circle(100, 50, 50);
+	 * @example
+createCanvas(200);
 
-let c = color(128);
+let c = color('gray');
 
 function draw() {
 	background(c);
@@ -1712,7 +2021,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);
@@ -1722,7 +2031,7 @@ rect(66, 0, 67, 200);
 fill(0, 0, 1);
 rect(133, 0, 67, 200);
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 
 colorMode(OKLCH);
 
@@ -1743,7 +2052,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);
@@ -1758,7 +2067,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);
 
@@ -1792,7 +2101,7 @@ function setup() {
 	 * 
 	 * Note how seamless the hue transitions are in the following example.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 colorMode(OKLCH);
 
 function draw() {
@@ -1851,7 +2160,7 @@ function draw() {
 	 * True if the mouse is currently pressed, false otherwise.
 	 * @example
 function draw() {
-	if (mouseIsPressed) background(0);
+	if (mouseIsPressed) background(100);
 	else background(200);
 }
 	 */
@@ -1872,7 +2181,7 @@ function draw() {
 	 * True if a key is currently pressed, false otherwise.
 	 * @example
 function draw() {
-	if (keyIsPressed) background(0);
+	if (keyIsPressed) background(100);
 	else background(200);
 }
 	 */
@@ -1894,13 +2203,8 @@ function draw() {
 	function keyIsDown(key: string): boolean;
 
 	/** 🖲️
-	 * The keyCode of the last key pressed.
-	 * @deprecated
-	 */
-	let keyCode: number;
-
-	/** 🖲️
-	 * Array of current touches, each touch being an object with x, y, id, etc.
+	 * Array of current touches, each touch being an object with
+	 * id, x, and y properties.
 	 */
 	let touches: any[];
 
@@ -1917,7 +2221,7 @@ function draw() {
 	/** 🖲️
 	 * Hides the cursor within the bounds of the canvas.
 	 * @example
-createCanvas(200, 200);
+createCanvas(200);
 noCursor();
 	 */
 	function noCursor(): void;
@@ -2123,7 +2427,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;
@@ -2144,7 +2448,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;
@@ -2170,10 +2474,63 @@ function mousePressed() {
 	class Sound {
 		/** 🔊
 		 * Creates a new `Q5.Sound` object.
-		 * 
-		 * See the `loadSound` documentation for more info.
 		 */
 		constructor();
+
+		/** 🔊
+		 * Set the sound's volume to a value between
+		 * 0 (silent) and 1 (full volume).
+		 */
+		volume: number;
+
+		/** 🔊
+		 * Set the sound's stereo position between -1 (left) and 1 (right).
+		 */
+		pan: number;
+
+		/** 🔊
+		 * Set to true to make the sound loop continuously.
+		 */
+		loop: boolean;
+
+		/** 🔊
+		 * True if the sound data has finished loading.
+		 */
+		loaded: boolean;
+
+		/** 🔊
+		 * True if the sound is currently paused.
+		 */
+		paused: boolean;
+
+		/** 🔊
+		 * True if the sound has finished playing.
+		 */
+		ended: boolean;
+
+		/** 🔊
+		 * Plays the sound.
+		 * 
+		 * If this function is run when the sound is already playing,
+		 * a new playback will start, causing a layering effect.
+		 * 
+		 * If this function is run when the sound is paused,
+		 * all playback instances will be resumed.
+		 */
+		play(): void;
+
+		/** 🔊
+		 * Pauses the sound, allowing it to be resumed.
+		 */
+		pause(): void;
+
+		/** 🔊
+		 * Stops the sound, resetting its playback position
+		 * to the beginning.
+		 * 
+		 * Removes all playback instances.
+		 */
+		stop(): void;
 	}
 
 	// 🛠️ utilities
@@ -2200,7 +2557,7 @@ function draw() {
 }
 	 * @example
 new Q5();
-createCanvas(200, 200);
+createCanvas(200);
 
 // use with top level await in a module
 await load('/assets/Robotica.ttf');
@@ -2209,7 +2566,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'