kei-lisp-plugin-graphics 1.1.0 → 3.0.0

package/dist/index.js

@@ -1,25 +1,127 @@
 import { Cons, InterpretedSymbol } from "kei-lisp";
 //#region src/GraphicsPlugin/index.ts
+const LINE_CAPS = /* @__PURE__ */ new Set([
+	"butt",
+	"round",
+	"square"
+]);
+const LINE_JOINS = /* @__PURE__ */ new Set([
+	"miter",
+	"round",
+	"bevel"
+]);
+const TEXT_ALIGNS = /* @__PURE__ */ new Set([
+	"left",
+	"right",
+	"center",
+	"start",
+	"end"
+]);
+const TEXT_BASELINES = /* @__PURE__ */ new Set([
+	"top",
+	"hanging",
+	"middle",
+	"alphabetic",
+	"ideographic",
+	"bottom"
+]);
+const TEXT_DIRECTIONS = /* @__PURE__ */ new Set([
+	"ltr",
+	"rtl",
+	"inherit"
+]);
+const FONT_KERNINGS = /* @__PURE__ */ new Set([
+	"auto",
+	"normal",
+	"none"
+]);
+const FONT_STRETCHES = /* @__PURE__ */ new Set([
+	"ultra-condensed",
+	"extra-condensed",
+	"condensed",
+	"semi-condensed",
+	"normal",
+	"semi-expanded",
+	"expanded",
+	"extra-expanded",
+	"ultra-expanded"
+]);
+const FONT_VARIANTS = /* @__PURE__ */ new Set([
+	"normal",
+	"small-caps",
+	"all-small-caps",
+	"petite-caps",
+	"all-petite-caps",
+	"unicase",
+	"titling-caps"
+]);
+const TEXT_RENDERINGS = /* @__PURE__ */ new Set([
+	"auto",
+	"optimizeSpeed",
+	"optimizeLegibility",
+	"geometricPrecision"
+]);
+const PATTERN_REPETITIONS = /* @__PURE__ */ new Set([
+	"repeat",
+	"repeat-x",
+	"repeat-y",
+	"no-repeat"
+]);
+const COMPOSITE_OPERATIONS = /* @__PURE__ */ new Set([
+	"source-over",
+	"source-in",
+	"source-out",
+	"source-atop",
+	"destination-over",
+	"destination-in",
+	"destination-out",
+	"destination-atop",
+	"lighter",
+	"copy",
+	"xor",
+	"multiply",
+	"screen",
+	"overlay",
+	"darken",
+	"lighten",
+	"color-dodge",
+	"color-burn",
+	"hard-light",
+	"soft-light",
+	"difference",
+	"exclusion",
+	"hue",
+	"saturation",
+	"color",
+	"luminosity"
+]);
 /**
 * @class
 * @classdesc Canvas2D drawing plugin for the kei-lisp interpreter. Implements
 *            the `KeiLispPlugin` contract (`name` / `has` / `apply`) and
-*            exposes 45 `g…` Lisp functions that proxy to a 2D rendering
+*            exposes 75 `g…` Lisp functions that proxy to a 2D rendering
 *            context.
 * @author Keisuke Ikeda
-* @this {GraphicsPlugin}
 */
-var GraphicsPlugin = class GraphicsPlugin extends Object {
+var GraphicsPlugin = class GraphicsPlugin {
 	/**
 	* Dispatch map from a Lisp function name (InterpretedSymbol) to the name of
-	* the GraphicsPlugin method that implements it.
+	* the GraphicsPlugin method that implements it. Private so hosts cannot
+	* mutate the registered function set.
 	*/
-	static buildInFunctions = GraphicsPlugin.setup();
+	static #builtInFunctions = GraphicsPlugin.#setup();
+	/**
+	* Lists every Lisp function name this plugin registers.
+	* @return the sorted `g…` function names
+	*/
+	static functionNames() {
+		return [...GraphicsPlugin.#builtInFunctions.keys()].map(String).sort((a, b) => a.localeCompare(b));
+	}
 	/**
 	* Builds the dispatch table.
 	* @return the dispatch table
 	*/
-	static setup() {
+	static #setup() {
 		const aTable = /* @__PURE__ */ new Map();
 		aTable.set(InterpretedSymbol.of("galpha"), "gAlpha");
 		aTable.set(InterpretedSymbol.of("garc"), "gArc");
@@ -58,17 +160,55 @@ var GraphicsPlugin = class GraphicsPlugin extends Object {
 		aTable.set(InterpretedSymbol.of("gstroke-text"), "gStrokeText");
 		aTable.set(InterpretedSymbol.of("gstroke-tri"), "gStrokeTri");
 		aTable.set(InterpretedSymbol.of("gtext-align"), "gTextAlign");
-		aTable.set(InterpretedSymbol.of("gtext-dire"), "gTextDirection");
+		aTable.set(InterpretedSymbol.of("gtext-direction"), "gTextDirection");
 		aTable.set(InterpretedSymbol.of("gtext-font"), "gTextFont");
+		aTable.set(InterpretedSymbol.of("gtext-baseline"), "gTextBaseline");
+		aTable.set(InterpretedSymbol.of("gtext-dire"), "gTextDirection");
 		aTable.set(InterpretedSymbol.of("gtext-line"), "gTextBaseline");
 		aTable.set(InterpretedSymbol.of("gtranslate"), "gTranslate");
 		aTable.set(InterpretedSymbol.of("grect"), "gRect");
 		aTable.set(InterpretedSymbol.of("grotate"), "gRotate");
 		aTable.set(InterpretedSymbol.of("gsave"), "gSave");
 		aTable.set(InterpretedSymbol.of("grestore"), "gRestore");
+		aTable.set(InterpretedSymbol.of("gellipse"), "gEllipse");
+		aTable.set(InterpretedSymbol.of("ground-rect"), "gRoundRect");
+		aTable.set(InterpretedSymbol.of("gline-dash"), "gLineDash");
+		aTable.set(InterpretedSymbol.of("gline-dash-offset"), "gLineDashOffset");
+		aTable.set(InterpretedSymbol.of("gmiter-limit"), "gMiterLimit");
+		aTable.set(InterpretedSymbol.of("gclip"), "gClip");
+		aTable.set(InterpretedSymbol.of("gis-point-in-path"), "gIsPointInPath");
+		aTable.set(InterpretedSymbol.of("gis-point-in-stroke"), "gIsPointInStroke");
+		aTable.set(InterpretedSymbol.of("gtransform"), "gTransform");
+		aTable.set(InterpretedSymbol.of("gset-transform"), "gSetTransform");
+		aTable.set(InterpretedSymbol.of("greset-transform"), "gResetTransform");
+		aTable.set(InterpretedSymbol.of("gcomposite"), "gComposite");
+		aTable.set(InterpretedSymbol.of("gfilter"), "gFilter");
+		aTable.set(InterpretedSymbol.of("gimage-smoothing"), "gImageSmoothing");
+		aTable.set(InterpretedSymbol.of("gmeasure-text"), "gMeasureText");
+		aTable.set(InterpretedSymbol.of("gletter-spacing"), "gLetterSpacing");
+		aTable.set(InterpretedSymbol.of("gword-spacing"), "gWordSpacing");
+		aTable.set(InterpretedSymbol.of("gfont-kerning"), "gFontKerning");
+		aTable.set(InterpretedSymbol.of("gfont-stretch"), "gFontStretch");
+		aTable.set(InterpretedSymbol.of("gfont-variant"), "gFontVariant");
+		aTable.set(InterpretedSymbol.of("gtext-rendering"), "gTextRendering");
+		aTable.set(InterpretedSymbol.of("gclear-rect"), "gClearRect");
+		aTable.set(InterpretedSymbol.of("greset"), "gReset");
+		aTable.set(InterpretedSymbol.of("gwidth"), "gWidth");
+		aTable.set(InterpretedSymbol.of("gheight"), "gHeight");
+		aTable.set(InterpretedSymbol.of("gpixel"), "gPixel");
+		aTable.set(InterpretedSymbol.of("gset-pixel"), "gSetPixel");
+		aTable.set(InterpretedSymbol.of("glinear-gradient"), "gLinearGradient");
+		aTable.set(InterpretedSymbol.of("gradial-gradient"), "gRadialGradient");
+		aTable.set(InterpretedSymbol.of("gconic-gradient"), "gConicGradient");
 		return aTable;
 	}
 	/**
+	* Loaded-image cache shared by `gimage` and `gpattern`. Repeated draws of
+	* the same `src` reuse the loaded element and run synchronously, so they
+	* keep their place in the drawing order instead of racing the load.
+	*/
+	#imageCache = /* @__PURE__ */ new Map();
+	/**
 	* Plugin identifier, used for diagnostics.
 	*/
 	name = "graphics";
@@ -81,22 +221,221 @@ var GraphicsPlugin = class GraphicsPlugin extends Object {
 	* @param canvas - the canvas to draw to
 	*/
 	constructor(canvas) {
-		super();
 		this.canvas = canvas;
 		this.ctx = canvas.getContext("2d");
 		this.isOpen = false;
 	}
 	/**
-	* Writes a diagnostic line directly to `process.stderr`, matching the
-	* convention used by kei-lisp itself (`Applier.format` writes to
-	* `process.stdout`). In a Node runtime this hits the real stderr; in a
-	* browser kei-lisp host (e.g. kei-lisp-web) the host typically swaps
-	* `process.stderr.write` for a sink that routes to the REPL output panel,
-	* so the same call reaches the user via the host's normal output channel.
+	* Writes a diagnostic line to `process.stderr`, matching the convention
+	* used by kei-lisp itself (`Applier.format` writes to `process.stdout`).
+	* In a Node runtime this hits the real stderr; in a browser kei-lisp host
+	* (e.g. kei-lisp-web) the host typically swaps `process.stderr.write` for
+	* a sink that routes to the REPL output panel. In a plain browser with no
+	* `process` shim at all, the line falls back to `console.error` instead of
+	* throwing.
 	* @param line - the line to write
 	*/
 	#print(line) {
-		process.stderr.write(line + "\n");
+		const stderr = globalThis.process?.stderr;
+		if (typeof stderr?.write === "function") {
+			stderr.write(line + "\n");
+			return;
+		}
+		console.error(line);
+	}
+	/**
+	* Resolves an image for the given source and runs `draw` with it —
+	* synchronously when the image is already loaded, on its `load` event
+	* otherwise. A load failure prints a diagnostic once.
+	* @param source - the image URL / data URI
+	* @param draw - the drawing action to run once the image is available
+	*/
+	#withImage(source, draw) {
+		const cached = this.#imageCache.get(source);
+		const image = cached ?? new Image();
+		if (cached === void 0) {
+			image.src = source;
+			this.#imageCache.set(source, image);
+			image.addEventListener("error", () => {
+				this.#print(`Can not load image: ${source}`);
+			});
+		}
+		if (image.complete) {
+			draw(image);
+			return;
+		}
+		image.addEventListener("load", () => {
+			draw(image);
+		});
+	}
+	/**
+	* Shared guard-and-dispatch skeleton for the newer `g…` methods: checks the
+	* context and the open flag, runs `body`, and converts both a `null` return
+	* and a thrown exception into `failureMessage` + `Cons.nil`.
+	* @param failureMessage - the diagnostic printed when `body` fails
+	* @param body - the drawing action; returns the Lisp result, or `null` on
+	*               bad arguments
+	* @return the body's result, or `Cons.nil` on failure
+	*/
+	#execute(failureMessage, body) {
+		if (!this.checkSupport()) return Cons.nil;
+		if (!this.isOpen) {
+			this.#print("The canvas is closed and cannot be executed.");
+			return Cons.nil;
+		}
+		try {
+			const result = body(this.ctx);
+			if (result !== null) return result;
+		} catch {}
+		this.#print(failureMessage);
+		return Cons.nil;
+	}
+	/**
+	* Reads a single string argument and validates it against an allowlist.
+	* @param arguments_ - the evaluated argument list
+	* @param allowed - the accepted values
+	* @return the validated string, or `null` on wrong arity, a non-string
+	*         argument, or a value outside the allowlist
+	*/
+	#enumString(arguments_, allowed) {
+		if (arguments_.length() !== 1 || !Cons.isString(arguments_.car)) return null;
+		return allowed.has(arguments_.car) ? arguments_.car : null;
+	}
+	/**
+	* Reads exactly `count` numbers from the argument list.
+	* @param arguments_ - the evaluated argument list
+	* @param count - the expected argument count
+	* @return the numbers, or `null` on wrong arity or a non-number argument
+	*/
+	#numbers(arguments_, count) {
+		if (arguments_.length() !== count) return null;
+		const values = [];
+		let rest = arguments_;
+		for (let index = 0; index < count; index++) {
+			if (!Cons.isNumber(rest.car)) return null;
+			values.push(rest.car);
+			rest = rest.cdr;
+		}
+		return values;
+	}
+	/**
+	* Flattens the argument list into a JS array.
+	* @param arguments_ - the evaluated argument list
+	* @return the argument values in order
+	*/
+	#listValues(arguments_) {
+		const values = [];
+		let rest = arguments_;
+		for (let index = arguments_.length(); index > 0; index--) {
+			values.push(rest.car);
+			rest = rest.cdr;
+		}
+		return values;
+	}
+	/**
+	* Builds a Lisp list (Cons chain) from JS values.
+	* @param values - the values, at least one
+	* @return the list head
+	*/
+	#toList(values) {
+		const head = new Cons(values[0]);
+		let tail = head;
+		for (let index = 1; index < values.length; index++) {
+			tail.cdr = new Cons(values[index]);
+			tail = tail.cdr;
+		}
+		return head;
+	}
+	/**
+	* Applies `(offset color)` pairs to a gradient.
+	* @param gradient - the gradient to add stops to
+	* @param stops - alternating numeric offsets (0–1) and CSS color strings
+	* @return true when every pair was valid and at least one was applied
+	*/
+	#applyGradientStops(gradient, stops) {
+		if (stops.length === 0 || stops.length % 2 !== 0) return false;
+		for (let index = 0; index < stops.length; index += 2) {
+			const offset = stops[index];
+			const color = stops[index + 1];
+			if (!Cons.isNumber(offset) || !Cons.isString(color)) return false;
+			gradient.addColorStop(offset, color);
+		}
+		return true;
+	}
+	/**
+	* Sets both `fillStyle` and `strokeStyle` to the given gradient after
+	* applying its stops, mirroring how `gcolor` sets both styles at once.
+	* @param context - the 2D context
+	* @param gradient - the gradient to install
+	* @param stops - alternating offsets and colors (see #applyGradientStops)
+	* @return `t` on success, `null` on invalid stops
+	*/
+	#installGradient(context, gradient, stops) {
+		if (!this.#applyGradientStops(gradient, stops)) return null;
+		context.fillStyle = gradient;
+		context.strokeStyle = gradient;
+		return InterpretedSymbol.of("t");
+	}
+	/**
+	* Encodes the canvas via `toDataURL` and triggers a browser download through
+	* a temporary `<a download>` element. Requires a DOM (`document`) and an
+	* `HTMLCanvasElement`; `OffscreenCanvas` has no `toDataURL`, and Node.js has
+	* no `document` — those callers must pass a file path instead.
+	* @param mimeType - the image MIME type to encode
+	* @param label - the format name used in diagnostics ("jpeg" / "png")
+	* @return `t` on success, `Cons.nil` otherwise
+	*/
+	#downloadCanvas(mimeType, label) {
+		if (typeof document === "undefined" || !("toDataURL" in this.canvas)) {
+			this.#print(`Can not save ${label}. Browser download needs a DOM and an HTMLCanvasElement; pass a file path to save on Node.js.`);
+			return Cons.nil;
+		}
+		try {
+			const link = document.createElement("a");
+			link.href = this.canvas.toDataURL(mimeType);
+			link.download = "canvas";
+			document.body.append(link);
+			link.click();
+			link.remove();
+			return InterpretedSymbol.of("t");
+		} catch {
+			this.#print(`Can not save ${label}. If you are using an image in the canvas, you can't save ${label}.`);
+			return Cons.nil;
+		}
+	}
+	/**
+	* Writes the encoded canvas image to a file path on Node.js, using
+	* `process.getBuiltinModule('node:fs')` so browser bundles never see a
+	* `node:fs` import. `HTMLCanvasElement` (and node-canvas) encode
+	* synchronously via `toDataURL`; `OffscreenCanvas` only offers the async
+	* `convertToBlob`, so its file is written after this returns — the same
+	* fire-and-forget contract as `gImage`.
+	* @param path - the destination file path
+	* @param mimeType - the image MIME type to encode
+	* @param label - the format name used in diagnostics ("jpeg" / "png")
+	* @return `t` on success, `Cons.nil` otherwise
+	*/
+	#writeCanvasToFile(path, mimeType, label) {
+		const fs = typeof process.getBuiltinModule === "function" ? process.getBuiltinModule("node:fs") : void 0;
+		if (fs === void 0) {
+			this.#print(`Can not save ${label}. Saving to a file path requires Node.js.`);
+			return Cons.nil;
+		}
+		try {
+			if ("toDataURL" in this.canvas) {
+				const dataUrl = this.canvas.toDataURL(mimeType);
+				const base64 = dataUrl.slice(dataUrl.indexOf(",") + 1);
+				fs.writeFileSync(path, Buffer.from(base64, "base64"));
+				return InterpretedSymbol.of("t");
+			}
+			this.canvas.convertToBlob({ type: mimeType }).then(async (blob) => {
+				fs.writeFileSync(path, new Uint8Array(await blob.arrayBuffer()));
+			});
+			return InterpretedSymbol.of("t");
+		} catch {
+			this.#print(`Can not save ${label}.`);
+			return Cons.nil;
+		}
 	}
 	/**
 	* Returns true if this plugin handles the given symbol.
@@ -104,7 +443,7 @@ var GraphicsPlugin = class GraphicsPlugin extends Object {
 	* @return true if `apply` should be called
 	*/
 	has(aSymbol) {
-		return GraphicsPlugin.buildInFunctions.has(aSymbol);
+		return GraphicsPlugin.#builtInFunctions.has(aSymbol);
 	}
 	/**
 	* Dispatches the given symbol to the matching `g…` method.
@@ -114,39 +453,17 @@ var GraphicsPlugin = class GraphicsPlugin extends Object {
 	* @return the method's result, or `Cons.nil` if dispatch fails
 	*/
 	apply(aSymbol, arguments_, _context) {
-		return this.selectProcedure(aSymbol, arguments_);
-	}
-	/**
-	* Resolves the procedure name and invokes the matching method.
-	* @param procedure - the Lisp symbol
-	* @param arguments_ - the evaluated argument list
-	* @return the method's result, or `Cons.nil` if not registered
-	*/
-	selectProcedure(procedure, arguments_) {
-		if (GraphicsPlugin.buildInFunctions.has(procedure)) return this.buildInFunction(procedure, arguments_);
-		this.#print(`I could find no procedure description for ${String(procedure)}`);
-		return Cons.nil;
-	}
-	/**
-	* Looks up and invokes the JS method that implements the given Lisp symbol.
-	* Throws `TypeError` when the dispatch table points to a method that does
-	* not exist on the instance — this matches the legacy behavior, where the
-	* Ramda `R.invoker(1, methodName)(args, this)` call would surface the same
-	* error by attempting to call `undefined`.
-	* @param procedure - the Lisp symbol
-	* @param arguments_ - the evaluated argument list
-	* @return the method's result
-	*/
-	buildInFunction(procedure, arguments_) {
-		const methodName = GraphicsPlugin.buildInFunctions.get(procedure);
-		const method = this[methodName];
-		if (typeof method !== "function") throw new TypeError(`${this.constructor.name} does not have a method named "${methodName}"`);
-		return method.call(this, arguments_);
+		const methodName = GraphicsPlugin.#builtInFunctions.get(aSymbol);
+		if (methodName === void 0) {
+			this.#print(`I could find no procedure description for ${String(aSymbol)}`);
+			return Cons.nil;
+		}
+		return this[methodName].call(this, arguments_);
 	}
 	/**
 	* Checks whether the canvas exposes a usable 2D context, and narrows
 	* `this.ctx` to non-null for the caller when it returns true.
-	* @return type predicate — true when ctx is non-null
+	* @return type predicate — true when context is non-null
 	*/
 	checkSupport() {
 		if (this.ctx === null) {
@@ -255,19 +572,15 @@ var GraphicsPlugin = class GraphicsPlugin extends Object {
 		this.#print("The canvas is closed and cannot be executed.");
 		return Cons.nil;
 	}
-	gClear() {
-		if (!this.checkSupport()) return Cons.nil;
-		if (this.isOpen) try {
-			this.ctx.fillStyle = "#ffffff";
-			this.ctx.fillRect(0, 0, this.canvas.width, this.canvas.height);
-			this.ctx.fillStyle = "#000000";
+	gClear(arguments_) {
+		return this.#execute("Can not clear.", (context) => {
+			const aColor = arguments_.length() === 0 ? "#ffffff" : this.selectColor(arguments_);
+			const previous = context.fillStyle;
+			context.fillStyle = aColor;
+			context.fillRect(0, 0, this.canvas.width, this.canvas.height);
+			context.fillStyle = previous;
 			return InterpretedSymbol.of("t");
-		} catch {
-			this.#print("Can not clear.");
-			return Cons.nil;
-		}
-		this.#print("The canvas is closed and cannot be executed.");
-		return Cons.nil;
+		});
 	}
 	gClose() {
 		if (!this.checkSupport()) return Cons.nil;
@@ -354,26 +667,17 @@ var GraphicsPlugin = class GraphicsPlugin extends Object {
 		return Cons.nil;
 	}
 	gFillText(arguments_) {
-		if (!this.checkSupport()) return Cons.nil;
-		if (this.isOpen) try {
-			if (arguments_.length() === 3) {
-				const a0 = arguments_.car;
-				const cdr1 = arguments_.cdr;
-				const a1 = cdr1.car;
-				const a2 = cdr1.cdr.car;
-				if (Cons.isString(a0) && Cons.isNumber(a1) && Cons.isNumber(a2)) {
-					this.ctx.fillText(a0, a1, a2);
-					return InterpretedSymbol.of("t");
-				}
-			}
-			this.#print("Can not draw fill text.");
-			return Cons.nil;
-		} catch {
-			this.#print("Can not draw fill text.");
-			return Cons.nil;
-		}
-		this.#print("The canvas is closed and cannot be executed.");
-		return Cons.nil;
+		return this.#execute("Can not draw fill text.", (context) => {
+			const length_ = arguments_.length();
+			if (length_ !== 3 && length_ !== 4) return null;
+			const [a0, a1, a2, a3] = this.#listValues(arguments_);
+			if (!Cons.isString(a0) || !Cons.isNumber(a1) || !Cons.isNumber(a2)) return null;
+			if (length_ === 4) {
+				if (!Cons.isNumber(a3)) return null;
+				context.fillText(a0, a1, a2, a3);
+			} else context.fillText(a0, a1, a2);
+			return InterpretedSymbol.of("t");
+		});
 	}
 	gFillTri(arguments_) {
 		if (!this.checkSupport()) return Cons.nil;
@@ -420,50 +724,21 @@ var GraphicsPlugin = class GraphicsPlugin extends Object {
 		return Cons.nil;
 	}
 	gImage(arguments_) {
-		if (!this.checkSupport()) return Cons.nil;
-		if (this.isOpen) try {
+		return this.#execute("Can not draw Image.", (context) => {
 			const length_ = arguments_.length();
-			if (length_ === 3) {
-				const a0 = arguments_.car;
-				const cdr1 = arguments_.cdr;
-				const a1 = cdr1.car;
-				const a2 = cdr1.cdr.car;
-				if (Cons.isString(a0) && Cons.isNumber(a1) && Cons.isNumber(a2)) {
-					const context = this.ctx;
-					const anImage = new Image();
-					anImage.src = a0;
-					anImage.onload = () => {
-						context.drawImage(anImage, a1, a2);
-					};
-					return InterpretedSymbol.of("t");
-				}
-			} else if (length_ === 5) {
-				const a0 = arguments_.car;
-				const cdr1 = arguments_.cdr;
-				const a1 = cdr1.car;
-				const cdr2 = cdr1.cdr;
-				const a2 = cdr2.car;
-				const cdr3 = cdr2.cdr;
-				const a3 = cdr3.car;
-				const a4 = cdr3.cdr.car;
-				if (Cons.isString(a0) && Cons.isNumber(a1) && Cons.isNumber(a2) && Cons.isNumber(a3) && Cons.isNumber(a4)) {
-					const context = this.ctx;
-					const anImage = new Image();
-					anImage.src = a0;
-					anImage.onload = () => {
-						context.drawImage(anImage, a1, a2, a3, a4);
-					};
-					return InterpretedSymbol.of("t");
-				}
-			}
-			this.#print("Can not draw Image.");
-			return Cons.nil;
-		} catch {
-			this.#print("Can not draw Image.");
-			return Cons.nil;
-		}
-		this.#print("The canvas is closed and cannot be executed.");
-		return Cons.nil;
+			if (length_ !== 3 && length_ !== 5) return null;
+			const [a0, a1, a2, a3, a4] = this.#listValues(arguments_);
+			if (!Cons.isString(a0) || !Cons.isNumber(a1) || !Cons.isNumber(a2)) return null;
+			if (length_ === 5) {
+				if (!Cons.isNumber(a3) || !Cons.isNumber(a4)) return null;
+				this.#withImage(a0, (image) => {
+					context.drawImage(image, a1, a2, a3, a4);
+				});
+			} else this.#withImage(a0, (image) => {
+				context.drawImage(image, a1, a2);
+			});
+			return InterpretedSymbol.of("t");
+		});
 	}
 	gLineTo(arguments_) {
 		if (!this.checkSupport()) return Cons.nil;
@@ -486,38 +761,20 @@ var GraphicsPlugin = class GraphicsPlugin extends Object {
 		return Cons.nil;
 	}
 	gLineCap(arguments_) {
-		if (!this.checkSupport()) return Cons.nil;
-		if (this.isOpen) try {
-			if (arguments_.length() === 1 && Cons.isNumber(arguments_.car)) {
-				const aString = arguments_.car === 0 ? "butt" : arguments_.car > 0 ? "round" : "square";
-				this.ctx.lineCap = aString;
-				return InterpretedSymbol.of("t");
-			}
-			this.#print("Can not set line cap.");
-			return Cons.nil;
-		} catch {
-			this.#print("Can not set line cap.");
-			return Cons.nil;
-		}
-		this.#print("The canvas is closed and cannot be executed.");
-		return Cons.nil;
+		return this.#execute("Can not set line cap. Expected \"butt\" / \"round\" / \"square\".", (context) => {
+			const value = this.#enumString(arguments_, LINE_CAPS);
+			if (value === null) return null;
+			context.lineCap = value;
+			return InterpretedSymbol.of("t");
+		});
 	}
 	gLineJoin(arguments_) {
-		if (!this.checkSupport()) return Cons.nil;
-		if (this.isOpen) try {
-			if (arguments_.length() === 1 && Cons.isNumber(arguments_.car)) {
-				const aString = arguments_.car === 0 ? "miter" : arguments_.car > 0 ? "round" : "bevel";
-				this.ctx.lineJoin = aString;
-				return InterpretedSymbol.of("t");
-			}
-			this.#print("Can not set line join.");
-			return Cons.nil;
-		} catch {
-			this.#print("Can not set line join.");
-			return Cons.nil;
-		}
-		this.#print("The canvas is closed and cannot be executed.");
-		return Cons.nil;
+		return this.#execute("Can not set line join. Expected \"miter\" / \"round\" / \"bevel\".", (context) => {
+			const value = this.#enumString(arguments_, LINE_JOINS);
+			if (value === null) return null;
+			context.lineJoin = value;
+			return InterpretedSymbol.of("t");
+		});
 	}
 	gLineWidth(arguments_) {
 		if (!this.checkSupport()) return Cons.nil;
@@ -573,30 +830,20 @@ var GraphicsPlugin = class GraphicsPlugin extends Object {
 		return Cons.nil;
 	}
 	gPattern(arguments_) {
-		if (!this.checkSupport()) return Cons.nil;
-		if (this.isOpen) try {
-			if (arguments_.length() === 2) {
-				const a0 = arguments_.car;
-				const a1 = arguments_.cdr.car;
-				if (Cons.isString(a0) && Cons.isNumber(a1)) {
-					const aString = a1 === 0 ? "repeat" : a1 > 0 ? "repeat-x" : "repeat-y";
-					const context = this.ctx;
-					const anImage = new Image();
-					anImage.src = a0;
-					anImage.onload = () => {
-						context.fillStyle = context.createPattern(anImage, aString);
-					};
-					return InterpretedSymbol.of("t");
+		return this.#execute("Can not set pattern. Expected an image source and a repetition (\"repeat\" / \"repeat-x\" / \"repeat-y\" / \"no-repeat\").", (context) => {
+			if (arguments_.length() !== 2) return null;
+			const [a0, a1] = this.#listValues(arguments_);
+			if (!Cons.isString(a0) || !Cons.isString(a1) || !PATTERN_REPETITIONS.has(a1)) return null;
+			this.#withImage(a0, (image) => {
+				const pattern = context.createPattern(image, a1);
+				if (pattern === null) {
+					this.#print("Can not set pattern. The image could not be used as a pattern.");
+					return;
 				}
-			}
-			this.#print("Can not set pattern.");
-			return Cons.nil;
-		} catch {
-			this.#print("Can not set pattern.");
-			return Cons.nil;
-		}
-		this.#print("The canvas is closed and cannot be executed.");
-		return Cons.nil;
+				context.fillStyle = pattern;
+			});
+			return InterpretedSymbol.of("t");
+		});
 	}
 	gQuadCurveTo(arguments_) {
 		if (!this.checkSupport()) return Cons.nil;
@@ -622,41 +869,28 @@ var GraphicsPlugin = class GraphicsPlugin extends Object {
 		this.#print("The canvas is closed and cannot be executed.");
 		return Cons.nil;
 	}
-	gSaveJpeg() {
-		if (!this.checkSupport()) return Cons.nil;
-		if (this.isOpen) try {
-			const anImage = new Image();
-			anImage.crossOrigin = "Anonymous";
-			anImage.src = this.canvas.toDataURL("image/jpeg");
-			const link = document.createElement("a");
-			link.href = anImage.src;
-			link.download = "canvas";
-			document.body.append(link);
-			link.click();
-			link.remove();
-			return InterpretedSymbol.of("t");
-		} catch {
-			this.#print("Can not save jpeg.  If you are using an image in the canvas, you can't save jpeg.");
-			return Cons.nil;
-		}
-		this.#print("The canvas is closed and cannot be executed.");
-		return Cons.nil;
+	gSaveJpeg(arguments_) {
+		return this.saveCanvas(arguments_, "image/jpeg", "jpeg");
 	}
-	gSavePng() {
+	gSavePng(arguments_) {
+		return this.saveCanvas(arguments_, "image/png", "png");
+	}
+	/**
+	* Shared implementation of `gsave-jpeg` / `gsave-png`. With no argument it
+	* triggers a browser download; with a single string argument it writes the
+	* encoded image to that file path on Node.js.
+	* @param arguments_ - the evaluated argument list (empty, or one path string)
+	* @param mimeType - the image MIME type to encode
+	* @param label - the format name used in diagnostics ("jpeg" / "png")
+	* @return `t` on success, `Cons.nil` otherwise
+	*/
+	saveCanvas(arguments_, mimeType, label) {
 		if (!this.checkSupport()) return Cons.nil;
-		if (this.isOpen) try {
-			const anImage = new Image();
-			anImage.crossOrigin = "Anonymous";
-			anImage.src = this.canvas.toDataURL("image/png");
-			const link = document.createElement("a");
-			link.href = anImage.src;
-			link.download = "canvas";
-			document.body.append(link);
-			link.click();
-			link.remove();
-			return InterpretedSymbol.of("t");
-		} catch {
-			this.#print("Can not save png. If you are using an image in the canvas, you can't save png.");
+		if (this.isOpen) {
+			const length_ = arguments_.length();
+			if (length_ === 0) return this.#downloadCanvas(mimeType, label);
+			if (length_ === 1 && Cons.isString(arguments_.car)) return this.#writeCanvasToFile(arguments_.car, mimeType, label);
+			this.#print(`Can not save ${label}.`);
 			return Cons.nil;
 		}
 		this.#print("The canvas is closed and cannot be executed.");
@@ -821,26 +1055,17 @@ var GraphicsPlugin = class GraphicsPlugin extends Object {
 		return Cons.nil;
 	}
 	gStrokeText(arguments_) {
-		if (!this.checkSupport()) return Cons.nil;
-		if (this.isOpen) try {
-			if (arguments_.length() === 3) {
-				const a0 = arguments_.car;
-				const cdr1 = arguments_.cdr;
-				const a1 = cdr1.car;
-				const a2 = cdr1.cdr.car;
-				if (Cons.isString(a0) && Cons.isNumber(a1) && Cons.isNumber(a2)) {
-					this.ctx.strokeText(a0, a1, a2);
-					return InterpretedSymbol.of("t");
-				}
-			}
-			this.#print("Can not draw stroke text.");
-			return Cons.nil;
-		} catch {
-			this.#print("Can not draw stroke text.");
-			return Cons.nil;
-		}
-		this.#print("The canvas is closed and cannot be executed.");
-		return Cons.nil;
+		return this.#execute("Can not draw stroke text.", (context) => {
+			const length_ = arguments_.length();
+			if (length_ !== 3 && length_ !== 4) return null;
+			const [a0, a1, a2, a3] = this.#listValues(arguments_);
+			if (!Cons.isString(a0) || !Cons.isNumber(a1) || !Cons.isNumber(a2)) return null;
+			if (length_ === 4) {
+				if (!Cons.isNumber(a3)) return null;
+				context.strokeText(a0, a1, a2, a3);
+			} else context.strokeText(a0, a1, a2);
+			return InterpretedSymbol.of("t");
+		});
 	}
 	gStrokeTri(arguments_) {
 		if (!this.checkSupport()) return Cons.nil;
@@ -876,53 +1101,28 @@ var GraphicsPlugin = class GraphicsPlugin extends Object {
 		return Cons.nil;
 	}
 	gTextAlign(arguments_) {
-		if (!this.checkSupport()) return Cons.nil;
-		if (this.isOpen) try {
-			if (arguments_.length() === 1 && Cons.isString(arguments_.car)) {
-				this.ctx.textAlign = arguments_.car;
-				return InterpretedSymbol.of("t");
-			}
-			this.#print("Can not set text align.");
-			return Cons.nil;
-		} catch {
-			this.#print("Can not set text align.");
-			return Cons.nil;
-		}
-		this.#print("The canvas is closed and cannot be executed.");
-		return Cons.nil;
+		return this.#execute("Can not set text align. Expected \"left\" / \"right\" / \"center\" / \"start\" / \"end\".", (context) => {
+			const value = this.#enumString(arguments_, TEXT_ALIGNS);
+			if (value === null) return null;
+			context.textAlign = value;
+			return InterpretedSymbol.of("t");
+		});
 	}
 	gTextBaseline(arguments_) {
-		if (!this.checkSupport()) return Cons.nil;
-		if (this.isOpen) try {
-			if (arguments_.length() === 1 && Cons.isString(arguments_.car)) {
-				this.ctx.textBaseline = arguments_.car;
-				return InterpretedSymbol.of("t");
-			}
-			this.#print("Can not set text baseline.");
-			return Cons.nil;
-		} catch {
-			this.#print("Can not set text baseline.");
-			return Cons.nil;
-		}
-		this.#print("The canvas is closed and cannot be executed.");
-		return Cons.nil;
+		return this.#execute("Can not set text baseline. Expected \"top\" / \"hanging\" / \"middle\" / \"alphabetic\" / \"ideographic\" / \"bottom\".", (context) => {
+			const value = this.#enumString(arguments_, TEXT_BASELINES);
+			if (value === null) return null;
+			context.textBaseline = value;
+			return InterpretedSymbol.of("t");
+		});
 	}
 	gTextDirection(arguments_) {
-		if (!this.checkSupport()) return Cons.nil;
-		if (this.isOpen) try {
-			if (arguments_.length() === 1 && Cons.isNumber(arguments_.car)) {
-				const aString = arguments_.car === 0 ? "inherit" : arguments_.car > 0 ? "rtl" : "ltr";
-				this.ctx.direction = aString;
-				return InterpretedSymbol.of("t");
-			}
-			this.#print("Can not set text direction.");
-			return Cons.nil;
-		} catch {
-			this.#print("Can not set text direction.");
-			return Cons.nil;
-		}
-		this.#print("The canvas is closed and cannot be executed.");
-		return Cons.nil;
+		return this.#execute("Can not set text direction. Expected \"ltr\" / \"rtl\" / \"inherit\".", (context) => {
+			const value = this.#enumString(arguments_, TEXT_DIRECTIONS);
+			if (value === null) return null;
+			context.direction = value;
+			return InterpretedSymbol.of("t");
+		});
 	}
 	gTextFont(arguments_) {
 		if (!this.checkSupport()) return Cons.nil;
@@ -1003,7 +1203,7 @@ var GraphicsPlugin = class GraphicsPlugin extends Object {
 	/**
 	* Pushes the current drawing state (styles, transform, clip) onto the
 	* context's state stack. Pairs with `gRestore` to let Lisp callers manage
-	* state explicitly. Replaces the legacy per-method `ctx.save()` calls, which
+	* state explicitly. Replaces the legacy per-method `context.save()` calls, which
 	* pushed state on every draw with no matching `restore()` and grew the stack
 	* unbounded.
 	* @return `t` on success, `Cons.nil` otherwise
@@ -1037,6 +1237,234 @@ var GraphicsPlugin = class GraphicsPlugin extends Object {
 		this.#print("The canvas is closed and cannot be executed.");
 		return Cons.nil;
 	}
+	gEllipse(arguments_) {
+		return this.#execute("Can not draw ellipse.", (context) => {
+			const a = this.#numbers(arguments_, 8);
+			if (a === null) return null;
+			context.ellipse(a[0], a[1], a[2], a[3], Math.PI / 180 * a[4], Math.PI / 180 * a[5], Math.PI / 180 * a[6], a[7] >= 0);
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gRoundRect(arguments_) {
+		return this.#execute("Can not draw round rectangle.", (context) => {
+			const a = this.#numbers(arguments_, 5);
+			if (a === null) return null;
+			context.roundRect(a[0], a[1], a[2], a[3], a[4]);
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gLineDash(arguments_) {
+		return this.#execute("Can not set line dash.", (context) => {
+			const segments = this.#numbers(arguments_, arguments_.length());
+			if (segments === null) return null;
+			context.setLineDash(segments);
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gLineDashOffset(arguments_) {
+		return this.#execute("Can not set line dash offset.", (context) => {
+			const a = this.#numbers(arguments_, 1);
+			if (a === null) return null;
+			context.lineDashOffset = a[0];
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gMiterLimit(arguments_) {
+		return this.#execute("Can not set miter limit.", (context) => {
+			const a = this.#numbers(arguments_, 1);
+			if (a === null) return null;
+			context.miterLimit = a[0];
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gClip() {
+		return this.#execute("Can not clip.", (context) => {
+			context.clip();
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gIsPointInPath(arguments_) {
+		return this.#execute("Can not test point in path.", (context) => {
+			const a = this.#numbers(arguments_, 2);
+			if (a === null) return null;
+			return context.isPointInPath(a[0], a[1]) ? InterpretedSymbol.of("t") : Cons.nil;
+		});
+	}
+	gIsPointInStroke(arguments_) {
+		return this.#execute("Can not test point in stroke.", (context) => {
+			const a = this.#numbers(arguments_, 2);
+			if (a === null) return null;
+			return context.isPointInStroke(a[0], a[1]) ? InterpretedSymbol.of("t") : Cons.nil;
+		});
+	}
+	gTransform(arguments_) {
+		return this.#execute("Can not transform.", (context) => {
+			const a = this.#numbers(arguments_, 6);
+			if (a === null) return null;
+			context.transform(a[0], a[1], a[2], a[3], a[4], a[5]);
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gSetTransform(arguments_) {
+		return this.#execute("Can not set transform.", (context) => {
+			const a = this.#numbers(arguments_, 6);
+			if (a === null) return null;
+			context.setTransform(a[0], a[1], a[2], a[3], a[4], a[5]);
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gResetTransform() {
+		return this.#execute("Can not reset transform.", (context) => {
+			context.resetTransform();
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gComposite(arguments_) {
+		return this.#execute("Can not set composite operation. Expected a globalCompositeOperation keyword such as \"source-over\" / \"multiply\" / \"screen\".", (context) => {
+			const value = this.#enumString(arguments_, COMPOSITE_OPERATIONS);
+			if (value === null) return null;
+			context.globalCompositeOperation = value;
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gFilter(arguments_) {
+		return this.#execute("Can not set filter.", (context) => {
+			if (arguments_.length() !== 1 || !Cons.isString(arguments_.car)) return null;
+			context.filter = arguments_.car;
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gImageSmoothing(arguments_) {
+		return this.#execute("Can not set image smoothing.", (context) => {
+			const quality = arguments_.length() === 1 ? arguments_.car : null;
+			if (quality !== "off" && quality !== "low" && quality !== "medium" && quality !== "high") return null;
+			if (quality === "off") context.imageSmoothingEnabled = false;
+			else {
+				context.imageSmoothingEnabled = true;
+				context.imageSmoothingQuality = quality;
+			}
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gMeasureText(arguments_) {
+		return this.#execute("Can not measure text.", (context) => {
+			if (arguments_.length() !== 1 || !Cons.isString(arguments_.car)) return null;
+			return context.measureText(arguments_.car).width;
+		});
+	}
+	gLetterSpacing(arguments_) {
+		return this.#execute("Can not set letter spacing.", (context) => {
+			if (arguments_.length() !== 1 || !Cons.isString(arguments_.car)) return null;
+			context.letterSpacing = arguments_.car;
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gWordSpacing(arguments_) {
+		return this.#execute("Can not set word spacing.", (context) => {
+			if (arguments_.length() !== 1 || !Cons.isString(arguments_.car)) return null;
+			context.wordSpacing = arguments_.car;
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gFontKerning(arguments_) {
+		return this.#execute("Can not set font kerning. Expected \"auto\" / \"normal\" / \"none\".", (context) => {
+			const value = this.#enumString(arguments_, FONT_KERNINGS);
+			if (value === null) return null;
+			context.fontKerning = value;
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gFontStretch(arguments_) {
+		return this.#execute("Can not set font stretch. Expected a font-stretch keyword such as \"condensed\" / \"normal\" / \"expanded\".", (context) => {
+			const value = this.#enumString(arguments_, FONT_STRETCHES);
+			if (value === null) return null;
+			context.fontStretch = value;
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gFontVariant(arguments_) {
+		return this.#execute("Can not set font variant. Expected a font-variant-caps keyword such as \"normal\" / \"small-caps\".", (context) => {
+			const value = this.#enumString(arguments_, FONT_VARIANTS);
+			if (value === null) return null;
+			context.fontVariantCaps = value;
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gTextRendering(arguments_) {
+		return this.#execute("Can not set text rendering. Expected \"auto\" / \"optimizeSpeed\" / \"optimizeLegibility\" / \"geometricPrecision\".", (context) => {
+			const value = this.#enumString(arguments_, TEXT_RENDERINGS);
+			if (value === null) return null;
+			context.textRendering = value;
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gClearRect(arguments_) {
+		return this.#execute("Can not clear rectangle.", (context) => {
+			const a = this.#numbers(arguments_, 4);
+			if (a === null) return null;
+			context.clearRect(a[0], a[1], a[2], a[3]);
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gReset() {
+		return this.#execute("Can not reset.", (context) => {
+			context.reset();
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gWidth() {
+		return this.#execute("Can not get width.", () => this.canvas.width);
+	}
+	gHeight() {
+		return this.#execute("Can not get height.", () => this.canvas.height);
+	}
+	gPixel(arguments_) {
+		return this.#execute("Can not read pixel.", (context) => {
+			const a = this.#numbers(arguments_, 2);
+			if (a === null) return null;
+			const data = context.getImageData(a[0], a[1], 1, 1).data;
+			return this.#toList([
+				data[0],
+				data[1],
+				data[2],
+				data[3]
+			]);
+		});
+	}
+	gSetPixel(arguments_) {
+		return this.#execute("Can not write pixel.", (context) => {
+			const a = this.#numbers(arguments_, 6);
+			if (a === null) return null;
+			const imageData = context.createImageData(1, 1);
+			imageData.data[0] = a[2];
+			imageData.data[1] = a[3];
+			imageData.data[2] = a[4];
+			imageData.data[3] = a[5];
+			context.putImageData(imageData, a[0], a[1]);
+			return InterpretedSymbol.of("t");
+		});
+	}
+	gLinearGradient(arguments_) {
+		return this.#execute("Can not set linear gradient.", (context) => {
+			const [x0, y0, x1, y1, ...stops] = this.#listValues(arguments_);
+			if (stops.length < 2 || !Cons.isNumber(x0) || !Cons.isNumber(y0) || !Cons.isNumber(x1) || !Cons.isNumber(y1)) return null;
+			return this.#installGradient(context, context.createLinearGradient(x0, y0, x1, y1), stops);
+		});
+	}
+	gRadialGradient(arguments_) {
+		return this.#execute("Can not set radial gradient.", (context) => {
+			const [x0, y0, r0, x1, y1, r1, ...stops] = this.#listValues(arguments_);
+			if (stops.length < 2 || !Cons.isNumber(x0) || !Cons.isNumber(y0) || !Cons.isNumber(r0) || !Cons.isNumber(x1) || !Cons.isNumber(y1) || !Cons.isNumber(r1)) return null;
+			return this.#installGradient(context, context.createRadialGradient(x0, y0, r0, x1, y1, r1), stops);
+		});
+	}
+	gConicGradient(arguments_) {
+		return this.#execute("Can not set conic gradient.", (context) => {
+			const [angle, x, y, ...stops] = this.#listValues(arguments_);
+			if (stops.length < 2 || !Cons.isNumber(angle) || !Cons.isNumber(x) || !Cons.isNumber(y)) return null;
+			return this.#installGradient(context, context.createConicGradient(Math.PI / 180 * angle, x, y), stops);
+		});
+	}
 	/**
 	* Parses a color spec from the head of the argument Cons. Accepts
 	* (1 string), (3 numbers — rgb), or (4 numbers — rgba); falls back to