tracky-mouse 2.6.0 → 2.8.0

package/tracky-mouse.js

@@ -52,24 +52,30 @@ const isSelectorValid = ((dummyElement) =>
 
 const dwellClickers = [];
 
+let playSound = () => { console.log("audio module not loaded yet; can't play sound effect"); };
+let initialAudioEnabled = false;
+let setAudioEnabled = (enabled) => { initialAudioEnabled = enabled; };
+
+/**
+ * @param {Object} config
+ * @param {string} config.targets - a CSS selector for the elements to click. Anything else will be ignored (except as an occluder).
+ * @param {(el: Element) => boolean} [config.shouldDrag] - a function that returns true if the element should be dragged rather than simply clicked.
+ * @param {(el: Element) => boolean} [config.noCenter] - a function that returns true if the element should be clicked anywhere on the element, rather than always at the center.
+ * @param {Array<{
+ *   from: string | Element | ((el: Element) => boolean), // - an array of `{ from, to, withinMargin }` objects, which define rules for dynamically changing what is hovered/clicked when the mouse is over a different element.
+ *   to: string | Element | ((el: Element) => Element | null), // - the element to retarget from. Can be a CSS selector, an element, or a function taking the element under the mouse and returning whether it should be retargeted.
+ *   withinMargin?: number // - the element to retarget to. Can be a CSS selector for an element which is an ancestor or descendant of the `from` element, or an element, or a function taking the element under the mouse and returning an element to retarget to, or null to ignore the element.
+ * }>} [config.retarget] - a number of pixels within which to consider the mouse over the `to` element. Default to infinity.
+ * @param {(el1: Element, el2: Element) => boolean} [config.isEquivalentTarget] - a function that returns true if two elements should be considered part of the same control, i.e. if clicking either should do the same thing. Elements that are equal are always considered equivalent even if you return false. This option is used for preventing the system from detecting occluding elements as separate controls, and rejecting the click. (When an occlusion is detected, it flashes a red box.)
+ * @param {(el: Element) => boolean} [config.dwellClickEvenIfPaused] - a function that returns true if the element should be clicked even while dwell clicking is otherwise paused. Use this for a dwell clicking toggle button, so it's possible to resume dwell clicking. With dwell clicking it's important to let users take a break, since otherwise you have to constantly move the cursor in order to not click on things!
+ * @param {(el: Element) => boolean} [config.shouldClickThrough] - a function that returns true if the element should be totally ignored, allowing clicking on content behind it. Prefer `pointer-events: none` when possible, which will work for all input methods. Use this only if you need to differentiate input methods. Default: `(el) => el.matches(".tracky-mouse-click-through, .tracky-mouse-click-through *")`
+ * @param {(args: {x: number, y: number, target: Element}) => void} config.click - a function to trigger a click on the given target element.
+ * @param {() => void} [config.beforeDispatch] - a function to call before a pointer event is dispatched. For detecting un-trusted user gestures, outside of an event handler.
+ * @param {() => void} [config.afterDispatch] - a function to call after a pointer event is dispatched. For detecting un-trusted user gestures, outside of an event handler.
+ * @param {() => void} [config.beforePointerDownDispatch] - a function to call before a `pointerdown` event is dispatched. Likely to be merged with `config.beforeDispatch()` in the future.
+ * @param {() => boolean} [config.isHeld] - a function that returns true if the next dwell should be a release (triggering `pointerup`).
+ */
 const initDwellClicking = (config) => {
-	/*
-		Arguments:
-		- `config.targets` (required): a CSS selector for the elements to click. Anything else will be ignored.
-		- `config.shouldDrag(el)` (optional): a function that returns true if the element should be dragged rather than simply clicked.
-		- `config.noCenter(el)` (optional): a function that returns true if the element should be clicked anywhere on the element, rather than always at the center.
-		- `config.retarget` (optional): an array of `{ from, to, withinMargin }` objects, which define rules for dynamically changing what is hovered/clicked when the mouse is over a different element.
-			- `from` (required): the element to retarget from. Can be a CSS selector, an element, or a function taking the element under the mouse and returning whether it should be retargeted.
-			- `to` (required): the element to retarget to. Can be a CSS selector for an element which is an ancestor or descendant of the `from` element, or an element, or a function taking the element under the mouse and returning an element to retarget to, or null to ignore the element.
-			- `withinMargin` (optional): a number of pixels within which to consider the mouse over the `to` element. Default to infinity.
-		- `config.isEquivalentTarget(el1, el2)` (optional): a function that returns true if two elements should be considered part of the same control, i.e. if clicking either should do the same thing. Elements that are equal are always considered equivalent even if you return false. This option is used for preventing the system from detecting occluding elements as separate controls, and rejecting the click. (When an occlusion is detected, it flashes a red box.)
-		- `config.dwellClickEvenIfPaused(el)` (optional): a function that returns true if the element should be clicked even while dwell clicking is otherwise paused. Use this for a dwell clicking toggle button, so it's possible to resume dwell clicking. With dwell clicking it's important to let users take a break, since otherwise you have to constantly move the cursor in order to not click on things!
-		- `config.click({x, y, target})` (required): a function to trigger a click on the given target element.
-		- `config.beforeDispatch()` (optional): a function to call before a pointer event is dispatched. For detecting un-trusted user gestures, outside of an event handler.
-		- `config.afterDispatch()` (optional): a function to call after a pointer event is dispatched. For detecting un-trusted user gestures, outside of an event handler.
-		- `config.beforePointerDownDispatch()` (optional): a function to call before a `pointerdown` event is dispatched. Likely to be merged with `config.beforeDispatch()` in the future.
-		- `config.isHeld()` (optional): a function that returns true if the next dwell should be a release (triggering `pointerup`).
-	*/
 
 	/** translation placeholder */
 	const t = (key, options = {}) => options.defaultValue ?? key;
@@ -104,6 +110,9 @@ const initDwellClicking = (config) => {
 	if (config.dwellClickEvenIfPaused !== undefined && typeof config.dwellClickEvenIfPaused !== "function") {
 		throw new Error(t("api.errors.functionRequired", { defaultValue: "%0 must be a function" }).replace("%0", "config.dwellClickEvenIfPaused"));
 	}
+	if (config.shouldClickThrough !== undefined && typeof config.shouldClickThrough !== "function") {
+		throw new Error(t("api.errors.functionRequired", { defaultValue: "%0 must be a function" }).replace("%0", "config.shouldClickThrough"));
+	}
 	if (config.beforeDispatch !== undefined && typeof config.beforeDispatch !== "function") {
 		throw new Error(t("api.errors.functionRequired", { defaultValue: "%0 must be a function" }).replace("%0", "config.beforeDispatch"));
 	}
@@ -149,6 +158,8 @@ const initDwellClicking = (config) => {
 		}
 	}
 
+	const shouldClickThrough = config.shouldClickThrough ?? ((el) => el.matches(".tracky-mouse-click-through, .tracky-mouse-click-through *"));
+
 	// trackyMouseContainer.querySelector(".tracky-mouse-canvas").classList.add("inset-deep");
 
 	const circleRadiusMax = 50; // dwell indicator size in pixels
@@ -222,6 +233,14 @@ const initDwellClicking = (config) => {
 			return null;
 		}
 
+		if (shouldClickThrough(target)) {
+			const elements = document.elementsFromPoint(clientX, clientY);
+			target = elements.find(el => !shouldClickThrough(el));
+			if (!target) {
+				return null;
+			}
+		}
+
 		let hoverCandidate = {
 			x: clientX,
 			y: clientY,
@@ -365,6 +384,9 @@ const initDwellClicking = (config) => {
 						showOccluderIndicator(apparentHoverCandidate.target);
 					}
 				} else {
+					// TODO: ignore .tracky-mouse-click-through elements here as well
+					// TODO: distinguish occlusion vs moved element (i.e. element is no longer in the elementsFromPoint list)
+					// for example for the archery targets in the demo on the website, which animate
 					let occluder = document.elementFromPoint(hoverCandidate.x, hoverCandidate.y);
 					hoverCandidate = null;
 					deactivateForAtLeast(inactiveAfterInvalidTimespan);
@@ -391,6 +413,7 @@ const initDwellClicking = (config) => {
 							})
 						));
 						config.afterDispatch?.();
+						playSound("clickRelease");
 					} else {
 						config.beforePointerDownDispatch?.();
 						config.beforeDispatch?.();
@@ -403,6 +426,7 @@ const initDwellClicking = (config) => {
 						config.afterDispatch?.();
 						if (config.shouldDrag?.(hoverCandidate.target)) {
 							dwellDragging = hoverCandidate.target;
+							playSound("clickPress");
 						} else {
 							config.beforeDispatch?.();
 							hoverCandidate.target.dispatchEvent(new PointerEvent("pointerup",
@@ -413,6 +437,8 @@ const initDwellClicking = (config) => {
 							));
 							config.click(hoverCandidate);
 							config.afterDispatch?.();
+							playSound("clickPress");
+							playSound("clickRelease", { delay: 0.03 }); // fully separating the sounds sounded worse
 						}
 					}
 					hoverCandidate = null;
@@ -571,6 +597,28 @@ TrackyMouse.cleanupDwellClicking = function () {
 	}
 };
 
+TrackyMouse._initAudio = async function () {
+	let module;
+	try {
+		// console.log("Loading audio support...");
+		module = await import("./src/audio.js");
+	} catch (e) {
+		console.warn("Failed to load audio module, click sounds will be disabled:", e);
+	}
+	// console.log("Audio module loaded.");
+	try {
+		const { initAudio } = module;
+		initAudio();
+		playSound = module.playSound;
+		setAudioEnabled = module.setAudioEnabled;
+		setAudioEnabled(initialAudioEnabled);
+		// console.log("Audio is initially " + (initialAudioEnabled ? "enabled" : "disabled"));
+	} catch (e) {
+		console.warn("Failed to initialize audio support, click sounds will be disabled:", e);
+	}
+	return module;
+};
+
 TrackyMouse._initInner = function (div, initOptions, reinit) {
 
 	const {
@@ -590,6 +638,17 @@ TrackyMouse._initInner = function (div, initOptions, reinit) {
 		// Could group things under an "unstable" object, or ideally, design nice APIs for everything.
 	} = initOptions;
 
+	/** @type {SleepSweep | null} */
+	let sleepSweep = null;
+
+	TrackyMouse._initAudio().then((module) => {
+		// _initAudio warns in the console and resolves to undefined if it fails to load audio support
+		if (module) {
+			const { SleepSweep } = module;
+			sleepSweep = new SleepSweep();
+		}
+	});
+
 	const isDesktopApp = !!window.electronAPI;
 
 	let translations = {};
@@ -843,7 +902,7 @@ TrackyMouse._initInner = function (div, initOptions, reinit) {
 	};
 
 
-	var languageToDefaultRegion = {
+	let languageToDefaultRegion = {
 		aa: "ET",
 		ab: "GE",
 		abr: "GH",
@@ -1588,9 +1647,9 @@ TrackyMouse._initInner = function (div, initOptions, reinit) {
 			// </svg>`;
 		}
 
-		var split = locale.toUpperCase().split(/-|_/);
-		var lang = split.shift();
-		var code = split.pop();
+		let split = locale.toUpperCase().split(/-|_/);
+		let lang = split.shift();
+		let code = split.pop();
 
 		if (!/^[A-Z]{2}$/.test(code)) {
 			code = languageToDefaultRegion[lang.toLowerCase()];
@@ -1605,7 +1664,7 @@ TrackyMouse._initInner = function (div, initOptions, reinit) {
 		return a + b;
 	}
 
-	var uiContainer = div || document.createElement("div");
+	let uiContainer = div || document.createElement("div");
 	uiContainer.classList.add("tracky-mouse-ui");
 	uiContainer.classList.toggle("tracky-mouse-rtl", isRTL);
 	uiContainer.dir = isRTL ? "rtl" : "ltr";
@@ -1613,7 +1672,7 @@ TrackyMouse._initInner = function (div, initOptions, reinit) {
 		<div class="tracky-mouse-controls">
 			<button class="tracky-mouse-start-stop-button" aria-pressed="false" aria-keyshortcuts="F9">${t("ui.startStopButton.start", { defaultValue: "Start" })}</button>
 		</div>
-		<div class="tracky-mouse-canvas-container-container">
+		<div class="tracky-mouse-camera-area">
 			<div class="tracky-mouse-canvas-container">
 				<div class="tracky-mouse-canvas-overlay">
 					<button class="tracky-mouse-use-camera-button">${t("ui.camera.allowAccess", { defaultValue: "Allow Camera Access" })}</button>
@@ -1631,12 +1690,43 @@ TrackyMouse._initInner = function (div, initOptions, reinit) {
 	if (!div) {
 		document.body.appendChild(uiContainer);
 	}
-	var startStopButton = uiContainer.querySelector(".tracky-mouse-start-stop-button");
-	var useCameraButton = uiContainer.querySelector(".tracky-mouse-use-camera-button");
-	var useDemoFootageButton = uiContainer.querySelector(".tracky-mouse-use-demo-footage-button");
-	var errorMessage = uiContainer.querySelector(".tracky-mouse-error-message");
-	var canvasContainer = uiContainer.querySelector('.tracky-mouse-canvas-container');
-	var desktopAppDownloadMessage = uiContainer.querySelector('.tracky-mouse-desktop-app-download-message');
+	let startStopButton = uiContainer.querySelector(".tracky-mouse-start-stop-button");
+	let useCameraButton = uiContainer.querySelector(".tracky-mouse-use-camera-button");
+	let useDemoFootageButton = uiContainer.querySelector(".tracky-mouse-use-demo-footage-button");
+	let errorMessage = uiContainer.querySelector(".tracky-mouse-error-message");
+	let canvasContainer = uiContainer.querySelector('.tracky-mouse-canvas-container');
+	let desktopAppDownloadMessage = uiContainer.querySelector('.tracky-mouse-desktop-app-download-message');
+
+	let lastShownErrorDetails = null;
+	function showError(message, error, { warningIcon = true, errorClass = "other" } = {}) {
+		const alreadyShown = !errorMessage.hidden && lastShownErrorDetails?.message === message && lastShownErrorDetails?.error?.name === error?.name && lastShownErrorDetails?.error?.message === error?.message;
+		if (alreadyShown) {
+			// Play CSS animation to indicate repeated errors
+			// but not if they're occurring constantly
+			// Note: for constant errors, with this scheme, it may animate
+			// when returning to the tab due to timer throttling, or due to lag.
+			if (performance.now() > lastShownErrorDetails.time + 100) {
+				errorMessage.style.animation = "none";
+				if (alreadyShown) {
+					void errorMessage.offsetWidth; // trigger reflow to allow restarting animation
+					errorMessage.style.animation = "";
+				}
+			}
+		} else {
+			if (warningIcon) {
+				errorMessage.textContent = `${t("common.warningIcon", { defaultValue: "⚠️" })} ${message}`;
+			} else {
+				errorMessage.textContent = message;
+			}
+			if (error) {
+				const pre = document.createElement("pre");
+				pre.textContent = error.name + ": " + error.message;
+				errorMessage.appendChild(pre);
+			}
+			errorMessage.hidden = false;
+		}
+		lastShownErrorDetails = { message, error, time: performance.now(), errorClass };
+	}
 
 	// Settings (initialized later; defaults are defined in settingsCategories)
 	const s = {};
@@ -1975,11 +2065,21 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 					type: "button",
 					visible: () => isDesktopApp,
 					onClick: async () => {
+						function showToast(message) {
+							const toast = document.createElement("div");
+							toast.className = "tracky-mouse-toast";
+							toast.textContent = message;
+							document.body.appendChild(toast);
+							setTimeout(() => {
+								toast.remove();
+							}, 5000);
+						}
+
 						let knownCameras = {};
 						try {
 							knownCameras = JSON.parse(localStorage.getItem("tracky-mouse-known-cameras")) || {};
 						} catch (error) {
-							alert(t("openCameraSettings.errors.sharedHeading", { defaultValue: "Failed to open camera settings:" }) + "\n" + t("openCameraSettings.errors.parseKnownCameras", { defaultValue: "Failed to parse known cameras from localStorage:" }) + "\n" + error.message);
+							showToast(t("openCameraSettings.errors.sharedHeading", { defaultValue: "Failed to open camera settings:" }) + "\n" + t("openCameraSettings.errors.parseKnownCameras", { defaultValue: "Failed to parse known cameras from localStorage:" }) + "\n" + error.name + ": " + error.message);
 							return;
 						}
 
@@ -1990,10 +2090,10 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 						try {
 							const result = await window.electronAPI.openCameraSettings(selectedDeviceName);
 							if (result?.error) {
-								alert(t("openCameraSettings.errors.sharedHeading", { defaultValue: "Failed to open camera settings:" }) + "\n" + result.error);
+								showToast(t("openCameraSettings.errors.sharedHeading", { defaultValue: "Failed to open camera settings:" }) + "\n" + result.error);
 							}
 						} catch (error) {
-							alert(t("openCameraSettings.errors.sharedHeading", { defaultValue: "Failed to open camera settings:" }) + "\n" + error.message);
+							showToast(t("openCameraSettings.errors.sharedHeading", { defaultValue: "Failed to open camera settings:" }) + "\n" + error.name + ": " + error.message);
 						}
 					},
 					// description: t("settings.openCameraSettings.description.alt1", { defaultValue: "Open your camera's system settings window to adjust properties like brightness and contrast." }),
@@ -2015,6 +2115,20 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 			type: "group",
 			label: t("settings.sections.general.label", { defaultValue: "General" }),
 			settings: [
+				{
+					label: t("settings.soundEffects.label", { defaultValue: "Sound effects" }),
+					className: "tracky-mouse-sound-effects",
+					key: "soundEffects",
+					type: "checkbox",
+					default: true,
+					afterInitialLoad: () => {
+						setAudioEnabled(s.soundEffects);
+					},
+					handleSettingChange: () => {
+						setAudioEnabled(s.soundEffects);
+					},
+					description: t("settings.soundEffects.description", { defaultValue: "Plays sounds when you click." }),
+				},
 				// opposite, "Start paused", might be clearer, especially if I add a "pause" button
 				{
 					label: t("settings.startEnabled.label", { defaultValue: "Start enabled" }),
@@ -2036,7 +2150,8 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 					// - I considered adding "⚠︎" but it feels a little too alarming
 					// label: "Close eyes to start/stop (<span style=\"border-bottom: 1px dotted;\" title=\"Planned refinements include: visual and auditory feedback, improved detection accuracy, and separate settings for durations to toggle on and off.\">experimental</span>)",
 					// label: "Close eyes to start/stop (<span style=\"border-bottom: 1px dotted;\" title=\"• Missing visual and auditory feedback.\n• Missing settings for duration(s) to toggle on and off.\n• Affected by false positive blink detections, especially when looking downward.\">Experimental</span>)",
-					label: t("settings.closeEyesToToggle.label", { defaultValue: "Close eyes to start/stop (<span style=\"border-bottom: 1px dotted;\" title=\"• There is currently no visual or auditory feedback.\n• There are no settings for duration(s) to toggle on and off.\n• It is affected by false positive blink detections, especially when looking downward.\">Experimental</span>)" }),
+					// label: t("settings.closeEyesToToggle.label", { defaultValue: "Close eyes to start/stop (<span style=\"border-bottom: 1px dotted;\" title=\"• There is currently no visual or auditory feedback.\n• There are no settings for duration(s) to toggle on and off.\n• It is affected by false positive blink detections, especially when looking downward.\">Experimental</span>)" }),
+					label: t("settings.closeEyesToToggle.label", { defaultValue: "Close eyes to start/stop" }),
 					className: "tracky-mouse-close-eyes-to-toggle",
 					key: "closeEyesToToggle",
 					type: "checkbox",
@@ -2309,26 +2424,27 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 		});
 	}
 
-	var canvas = uiContainer.querySelector(".tracky-mouse-canvas");
-	var ctx = canvas.getContext('2d', { willReadFrequently: true });
+	let canvas = uiContainer.querySelector(".tracky-mouse-canvas");
+	let ctx = canvas.getContext('2d', { willReadFrequently: true });
 
-	var debugEyeCanvas = document.createElement("canvas");
+	let debugEyeCanvas = document.createElement("canvas");
 	debugEyeCanvas.className = "tracky-mouse-debug-eye-canvas";
 	debugEyeCanvas.style.display = "none";
-	uiContainer.querySelector(".tracky-mouse-canvas-container-container").appendChild(debugEyeCanvas);
-	var debugEyeCtx = debugEyeCanvas.getContext('2d');
+	uiContainer.querySelector(".tracky-mouse-camera-area").appendChild(debugEyeCanvas);
+	let debugEyeCtx = debugEyeCanvas.getContext('2d');
 
-	var pointerEl = document.createElement('div');
+	let pointerEl = document.createElement('div');
 	pointerEl.className = "tracky-mouse-pointer";
 	pointerEl.style.display = "none";
 	document.body.appendChild(pointerEl);
 
-	var cameraVideo = document.createElement('video');
+	let cameraVideo = document.createElement('video');
 	// required to work in iOS 11 & up:
 	cameraVideo.setAttribute('playsinline', '');
 
+	let stats;
 	if (statsJs) {
-		var stats = new Stats();
+		stats = new Stats();
 		stats.domElement.style.position = 'fixed';
 		stats.domElement.style.top = '0px';
 		stats.domElement.style.right = '0px';
@@ -2337,72 +2453,86 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 	}
 
 	// Debug flags (not shown in the UI; could become Advanced Settings in the future)
-	var debugAcceleration = false;
-	var showDebugText = false;
-	var showDebugEyeZoom = false;
-	var showDebugHeadTilt = false;
+	let debugAcceleration = false;
+	let showDebugText = false;
+	let showDebugEyeZoom = false;
+	let showDebugHeadTilt = false;
+	let showDebugRegionFilter = false;
 
 	// Constants (could become Advanced Settings in the future)
-	var defaultWidth = 640;
-	var defaultHeight = 480;
-	var maxPoints = 1000;
-	var faceScoreThreshold = 0.5;
-	var facemeshOptions = {
+	let defaultWidth = 640;
+	let defaultHeight = 480;
+	let maxPoints = 1000;
+	let faceScoreThreshold = 0.5;
+	let facemeshOptions = {
 		maxContinuousChecks: 5,
 		detectionConfidence: 0.9,
 		maxFaces: 1,
 		iouThreshold: 0.3,
 		scoreThreshold: 0.75
 	};
-	var useFacemesh = true;
+	let useFacemesh = true;
+	let sleepGestureEyesClosedDuration = 2000;
 	// maybe should be based on size of head in view?
 	const pruningGridSize = 5;
 	const minDistanceToAddPoint = pruningGridSize * 1.5;
 
 	// Head tracking and facial gesture state
 	// ## Clmtrackr state
-	var face;
-	var faceScore = 0;
-	var faceConvergence = 0;
-	// var faceConvergenceThreshold = 50;
-	var pointsBasedOnFaceScore = 0;
+	let face;
+	let faceScore = 0;
+	let faceConvergence = 0;
+	// let faceConvergenceThreshold = 50;
+	let pointsBasedOnFaceScore = 0;
 	// ## Facemesh state
 	let detector;
 	let currentCameraImageData;
-	var facemeshLoaded = false;
-	var facemeshFirstEstimation = true;
-	var facemeshEstimating = false;
-	var facemeshRejectNext = 0;
-	var facemeshPrediction;
-	var facemeshEstimateFaces;
-	var faceInViewConfidenceThreshold = 0.7;
-	var pointsBasedOnFaceInViewConfidence = 0;
-	var cameraFramesSinceFacemeshUpdate = [];
-	var blinkInfo;
-	var mouthInfo;
-	var headTilt = { pitch: 0, yaw: 0, roll: 0 };
-	var headTiltFilters = { pitch: null, yaw: null, roll: null };
-	var lastTimeWhenAnEyeWasOpen = Infinity; // far future rather than far past so that sleep gesture doesn't trigger initially, skipping the delay
+	let facemeshLoaded = false;
+	let facemeshFirstEstimation = true;
+	let facemeshEstimating = false;
+	let facemeshRejectNext = 0;
+	let facemeshPrediction;
+	let facemeshEstimateFaces;
+	let faceInViewConfidenceThreshold = 0.7;
+	let pointsBasedOnFaceInViewConfidence = 0;
+	let cameraFramesSinceFacemeshUpdate = [];
+	let blinkInfo;
+	let mouthInfo;
+	let headTilt = { pitch: 0, yaw: 0, roll: 0 };
+	let headTiltFilters = { pitch: null, yaw: null, roll: null };
+	let sleepGestureProgress = 0;
 	// ## State related to switching between head trackers
-	var useClmTracking = true;
-	var showClmTracking = useClmTracking;
-	var fallbackTimeoutID;
+	let useClmTracking = true;
+	let showClmTracking = useClmTracking;
+	let fallbackTimeoutID;
 
 	// Mouse state
-	var mouseX = 0;
-	var mouseY = 0;
-	var buttonStates = {
+	let mouseX = 0;
+	let mouseY = 0;
+	let buttonStates = {
 		left: false,
 		right: false,
 		middle: false,
 	};
-	var mouseButtonUntilMouthCloses = -1;
-	var lastMouseDownTime = -Infinity;
-	var mouseNeedsInitPos = true;
+	let mouseButtonUntilMouthCloses = -1;
+	let lastMouseDownTime = -Infinity;
+	let mouseNeedsInitPos = true;
+
+	// Virtual display bounds cache (Electron only); covers all connected monitors.
+	let virtualDisplayBounds = null;
+	if (window.electronAPI?.getVirtualDisplayBounds) {
+		window.electronAPI.getVirtualDisplayBounds().then((bounds) => {
+			virtualDisplayBounds = bounds;
+		});
+		window.electronAPI.onVirtualDisplayBoundsChanged?.((bounds) => {
+			virtualDisplayBounds = bounds;
+			mouseNeedsInitPos = true;
+		});
+	}
 
 	// Other state
-	var paused = true;
-	var pointTracker;
+	let paused = true;
+	let pointTracker;
 
 	// Named lists of facemesh landmark indices
 	const MESH_ANNOTATIONS = {
@@ -2471,14 +2601,17 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 
 		try {
 			detector = await faceLandmarksDetection.createDetector(model, detectorConfig);
+			if (lastShownErrorDetails?.errorClass === "faceLandmarksDetection.createDetector") {
+				errorMessage.hidden = true;
+			}
 		} catch (error) {
 			detector = null;
-			// TODO: avoid alert
 			console.error("Failed to create facemesh detector:", error);
-			alert(error);
+			showError(t("faceDetectorInitError", { defaultValue: "Failed to create face detector" }), error, { errorClass: "faceLandmarksDetection.createDetector" });
 		}
 
 		facemeshLoaded = true;
+		let loggedDetectorError = false;
 		facemeshEstimateFaces = async () => {
 			const imageData = currentCameraImageData;//getCameraImageData();
 			if (!imageData) {
@@ -2492,11 +2625,17 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 				}
 				return faces;
 			} catch (error) {
-				detector.dispose();
+				if (!loggedDetectorError) {
+					console.error("Facemesh estimation failed:", error);
+					loggedDetectorError = true;
+				}
+				try {
+					detector?.dispose();
+				} catch (disposeError) {
+					console.error("Failed to dispose facemesh detector after estimation error:", disposeError);
+				}
 				detector = null;
-				// TODO: avoid alert
-				console.error("Facemesh estimation failed:", error);
-				alert(error);
+				showError(t("faceDetectorError", { defaultValue: "Face detector error" }), error);
 			}
 			return [];
 		};
@@ -2514,6 +2653,7 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 				setting._load?.(settings, initialLoad);
 			});
 		}
+		setAudioEnabled(s.soundEffects);
 
 		// Now that all settings are loaded, update disabled states
 		for (const func of functionsToUpdateDisabledStates) {
@@ -2579,6 +2719,12 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 		}
 		if (stored) {
 			deserializeSettings(stored, initialLoad);
+		} else {
+			// HACK: ensure handleInitialLoad is called even for first run
+			// Combined with the below, this feels very redundant, and I'd like to
+			// move to a subscription-based pattern, more of a formal "settings store", something like that.
+			// This is currently necessary for sound effects to work on the first run of the web demo.
+			deserializeSettings(serializeSettings(), initialLoad);
 		}
 		if (initialLoad && (!stored || !stored.globalSettings || Object.keys(stored.globalSettings).length === 0)) {
 			// We could just call setOptions in both cases,
@@ -2692,9 +2838,9 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 	const settingsLoadedPromise = loadOptions(true);
 
 	// Don't use WebGL because clmTracker is our fallback! It's also not much slower than with WebGL.
-	var clmTracker = new clm.tracker({ useWebGL: false });
+	let clmTracker = new clm.tracker({ useWebGL: false });
 	clmTracker.init();
-	var clmTrackingStarted = false;
+	let clmTrackingStarted = false;
 
 	const stopCameraStream = () => {
 		if (cameraVideo.srcObject) {
@@ -2720,11 +2866,21 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 		pointsBasedOnFaceScore = 0;
 		faceScore = 0;
 		faceConvergence = 0;
-		lastTimeWhenAnEyeWasOpen = Infinity; // far future rather than far past so that sleep gesture doesn't trigger initially, skipping the delay
+		sleepGestureProgress = 0;
 		updateStartStopButton();
 	};
 
-	let showedCameraError = false;
+	// Handle monkey-patched alert() replacement in face-landmarks-detection.min.js
+	// (Hm, could make it throw instead. Then we wouldn't need this.)
+	window._TrackyMouse_faceLandmarksDetectionAlert = (message) => {
+		// TODO: i18n (it's just one message; we could check for the string (or not) and translate it)
+		// const isContextCreationMessage = message === "Failed to create WebGL canvas context when passing video frame.";
+		errorMessage.textContent = `${t("common.warningIcon", { defaultValue: "⚠️" })} ${message}`;
+		errorMessage.hidden = false;
+	};
+
+	const cameraAccessSlowWarningDelayMS = 5000;
+	let cameraAccessSlowWarningTimeoutID;
 	useCameraButton.onclick = TrackyMouse.useCamera = async (optionsOrEvent = {}) => {
 		// Phases:
 		// 1. "tryPreferredCamera"
@@ -2814,8 +2970,15 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 			delete constraints.video.facingMode;
 			constraints.video.deviceId = { exact: deviceIdToTry };
 		}
+		clearTimeout(cameraAccessSlowWarningTimeoutID);
+		errorMessage.hidden = true;
+		cameraAccessSlowWarningTimeoutID = setTimeout(() => {
+			errorMessage.textContent = t("video.status.accessTakingLongerThanExpected", { defaultValue: "Accessing the camera is taking longer than expected..." });
+			errorMessage.hidden = false;
+		}, cameraAccessSlowWarningDelayMS);
 		console.log("TrackyMouse.useCamera phase", phase, "constraints", constraints);
 		navigator.mediaDevices.getUserMedia(constraints).then(async (stream) => {
+			clearTimeout(cameraAccessSlowWarningTimeoutID);
 			if (phase === "justGetPermission") {
 				for (const track of stream.getTracks()) {
 					track.stop();
@@ -2838,6 +3001,7 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 			useCameraButton.hidden = true;
 			errorMessage.hidden = true;
 		}, async (error) => {
+			clearTimeout(cameraAccessSlowWarningTimeoutID);
 			console.log("TrackyMouse.useCamera phase", phase, "error", error);
 			if (
 				phase === "tryPreferredCamera" &&
@@ -2849,7 +3013,7 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 			}
 			if (error.name == "NotFoundError" || error.name == "DevicesNotFoundError") {
 				// required track is missing
-				errorMessage.textContent = t("video.errors.noCameraFound", { defaultValue: "No camera found. Please make sure you have a camera connected and enabled." });
+				showError(t("video.errors.noCameraFound", { defaultValue: "No camera found. Please make sure you have a camera connected and enabled." }));
 			} else if (error.name == "NotReadableError" || error.name == "TrackStartError") {
 				// webcam is already in use
 				// or: OBS Virtual Camera is present but OBS is not running with Virtual Camera started
@@ -2857,18 +3021,18 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 				// (listing devices and showing only the OBS Virtual Camera would also be a good clue in itself;
 				// though care should be given to make it clear it's a list with one item, with something like "(no more cameras detected)" following the list
 				// or "1 camera source detected" preceding it)
-				errorMessage.textContent = t("video.errors.cameraInUse", { defaultValue: "Webcam is already in use. Please make sure you have no other programs using the camera." });
+				showError(t("video.errors.cameraInUse", { defaultValue: "Webcam is already in use. Please make sure you have no other programs using the camera." }));
 			} else if (error.name === "AbortError") {
 				// webcam is likely already in use
 				// I observed AbortError in Firefox 132.0.2 but I don't know it's used exclusively for this case.
 				// Update: it definitely isn't, but I can't say exactly what it means in other cases.
 				// Like, it might have to do with permissions being denied outside of a user gesture (distinct from the user denying the permission)
 				// I really hope that isn't the problem.
-				// errorMessage.textContent = "Webcam may already be in use. Please make sure you have no other programs using the camera.";
-				errorMessage.textContent = t("video.errors.retryAfterClosingOtherPrograms", { defaultValue: "Please make sure no other programs are using the camera and try again." });
+				// showError("Webcam may already be in use. Please make sure you have no other programs using the camera.");
+				showError(t("video.errors.retryAfterClosingOtherPrograms", { defaultValue: "Please make sure no other programs are using the camera and try again." }));
 				// A more honest/helpful message might be:
-				// errorMessage.textContent = "Please try again and then make sure no other programs are using the camera and try again again.";
-				// errorMessage.textContent = "Please try again before/after making sure no other programs are using the camera.";
+				// showError("Please try again and then make sure no other programs are using the camera and try again again.");
+				// showError("Please try again before/after making sure no other programs are using the camera.");
 				// if it were not to be confusing.
 				// That is, one could save some time by just hitting the button to try again before trying to figure out of another program is using the camera,
 				// because sometimes that's enough.
@@ -2879,36 +3043,27 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 				// either due to the device not being present, or the ID having changed (don't ask me why that can happen but it can)
 				// Note: OverconstrainedError has a `constraint` property but not in Firefox so it's not very helpful.
 				if (constraints.video.deviceId?.exact) {
-					// errorMessage.textContent = "The previously selected camera is not available. Please select a different camera from the dropdown and try again.";
-					// errorMessage.textContent = "The previously selected camera is not available. Please mess around with Video > Camera source.";
-					// errorMessage.textContent = "The previously selected camera is not available. Try changing Video > Camera source.";
-					// errorMessage.textContent = "The previously selected camera is not available. Please select a camera from the \"Camera source\" dropdown in the Video settings and if it doesn't show up, it might after you select Default.";
-					errorMessage.textContent = t("video.errors.previouslySelectedUnavailable", { defaultValue: "The previously selected camera is not available. Try selecting \"Default\" for Video > Camera source, and then select a specific camera if you need to." });
+					// showError("The previously selected camera is not available. Please select a different camera from the dropdown and try again.");
+					// showError("The previously selected camera is not available. Please mess around with Video > Camera source.");
+					// showError("The previously selected camera is not available. Try changing Video > Camera source.");
+					// showError("The previously selected camera is not available. Please select a camera from the \"Camera source\" dropdown in the Video settings and if it doesn't show up, it might after you select Default.");
+					showError(t("video.errors.previouslySelectedUnavailable", { defaultValue: "The previously selected camera is not available. Try selecting \"Default\" for Video > Camera source, and then select a specific camera if you need to." }));
 					// It's awkward but that's my best attempt at conveying how you may need to proceed
 					// without complicated description of how/why the dropdown might be populated with
 					// fake information until a camera stream is successfully opened.
 				} else {
-					errorMessage.textContent = t("video.errors.unsupportedResolution", { defaultValue: "Webcam does not support the required resolution. Please change your settings." });
+					showError(t("video.errors.unsupportedResolution", { defaultValue: "Webcam does not support the required resolution. Please change your settings." }));
 				}
 			} else if (error.name == "NotAllowedError" || error.name == "PermissionDeniedError") {
 				// permission denied in browser
-				errorMessage.textContent = t("video.errors.permissionDenied", { defaultValue: "Permission denied. Please enable access to the camera." });
+				showError(t("video.errors.permissionDenied", { defaultValue: "Permission denied. Please enable access to the camera." }));
 			} else if (error.name == "TypeError") {
 				// empty constraints object
-				errorMessage.textContent = `${t("video.errors.accessFailed", { defaultValue: "Something went wrong accessing the camera." })} (${error.name}: ${error.message})`;
+				showError(t("video.errors.accessFailed", { defaultValue: "Something went wrong accessing the camera." }), error);
 			} else {
 				// other errors
-				errorMessage.textContent = `${t("video.errors.accessFailedRetry", { defaultValue: "Something went wrong accessing the camera. Please try again." })} (${error.name}: ${error.message})`;
+				showError(t("video.errors.accessFailedRetry", { defaultValue: "Something went wrong accessing the camera. Please try again." }), error);
 			}
-			errorMessage.textContent = `${t("common.warningIcon", { defaultValue: "⚠️" })} ${errorMessage.textContent}`;
-			errorMessage.hidden = false;
-			// Play CSS animation only on retries
-			errorMessage.style.animation = "none";
-			if (showedCameraError) {
-				void errorMessage.offsetWidth; // trigger reflow to allow restarting animation
-				errorMessage.style.animation = "";
-			}
-			showedCameraError = true;
 		});
 	};
 	useDemoFootageButton.onclick = TrackyMouse.useDemoFootage = () => {
@@ -3008,7 +3163,7 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 		}
 		addPoint(x, y) {
 			if (this.pointCount < maxPoints) {
-				var pointIndex = this.pointCount * 2;
+				let pointIndex = this.pointCount * 2;
 				this.curXY[pointIndex] = x;
 				this.curXY[pointIndex + 1] = y;
 				this.prevXY[pointIndex] = x;
@@ -3017,8 +3172,8 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 			}
 		}
 		filterPoints(condition) {
-			var outputPointIndex = 0;
-			for (var inputPointIndex = 0; inputPointIndex < this.pointCount; inputPointIndex++) {
+			let outputPointIndex = 0;
+			for (let inputPointIndex = 0; inputPointIndex < this.pointCount; inputPointIndex++) {
 				if (condition(inputPointIndex)) {
 					if (outputPointIndex < inputPointIndex) {
 						const inputOffset = inputPointIndex * 2;
@@ -3066,10 +3221,10 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 			[this.prevPyramid, this.curPyramid] = [this.curPyramid, this.prevPyramid];
 
 			// these are options worth breaking out and exploring
-			var winSize = 20;
-			var maxIterations = 30;
-			var epsilon = 0.01;
-			var minEigen = 0.001;
+			let winSize = 20;
+			let maxIterations = 30;
+			let epsilon = 0.01;
+			let minEigen = 0.001;
 
 			jsfeat.imgproc.grayscale(imageData.data, imageData.width, imageData.height, this.curPyramid.data[0]);
 			this.curPyramid.build(this.curPyramid.data[0], true);
@@ -3083,9 +3238,9 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 			this.prunePoints();
 		}
 		draw(ctx) {
-			for (var i = 0; i < this.pointCount; i++) {
-				var pointOffset = i * 2;
-				// var distMoved = Math.hypot(
+			for (let i = 0; i < this.pointCount; i++) {
+				let pointOffset = i * 2;
+				// let distMoved = Math.hypot(
 				// 	this.prevXY[pointOffset] - this.curXY[pointOffset],
 				// 	this.prevXY[pointOffset + 1] - this.curXY[pointOffset + 1]
 				// );
@@ -3103,11 +3258,11 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 			}
 		}
 		getMovement() {
-			var movementX = 0;
-			var movementY = 0;
-			var numMovements = 0;
-			for (var i = 0; i < this.pointCount; i++) {
-				var pointOffset = i * 2;
+			let movementX = 0;
+			let movementY = 0;
+			let numMovements = 0;
+			for (let i = 0; i < this.pointCount; i++) {
+				let pointOffset = i * 2;
 				movementX += this.curXY[pointOffset] - this.prevXY[pointOffset];
 				movementY += this.curXY[pointOffset + 1] - this.prevXY[pointOffset + 1];
 				numMovements += 1;
@@ -3144,9 +3299,9 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 		// in order to keep a smooth overall tracking calculation,
 		// don't add points if they're close to an existing point.
 		// Otherwise, it would not just be redundant, but often remove the older points, in the pruning.
-		for (var pointIndex = 0; pointIndex < oops.pointCount; pointIndex++) {
-			var pointOffset = pointIndex * 2;
-			// var distance = Math.hypot(
+		for (let pointIndex = 0; pointIndex < oops.pointCount; pointIndex++) {
+			let pointOffset = pointIndex * 2;
+			// let distance = Math.hypot(
 			// 	x - oops.curXY[pointOffset],
 			// 	y - oops.curXY[pointOffset + 1]
 			// );
@@ -3183,6 +3338,7 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 		return ((px - x1) * nx + (py - y1) * ny) / Math.hypot(nx, ny);
 	}
 
+	let lastTimestamp = -Infinity;
 	function draw(update = true) {
 		ctx.resetTransform(); // in case there is an error, don't flip constantly back and forth due to mirroring
 		ctx.clearRect(0, 0, canvas.width, canvas.height); // in case there's no footage
@@ -3197,6 +3353,13 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 			ctx.drawImage(cameraVideo, 0, 0, canvas.width, canvas.height);
 		}
 
+		const timestamp = performance.now();
+		const deltaTime = Math.min(timestamp - lastTimestamp, 100);
+		lastTimestamp = timestamp;
+
+		sleepSweep?.setEnabled(s.closeEyesToToggle);
+		sleepSweep?.update(sleepGestureProgress);
+
 		if (!pointTracker) {
 			return;
 		}
@@ -3332,39 +3495,77 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 
 						// TODO: separate confidence threshold for removing vs adding points?
 
+
 						// cull points to those within useful facial region
-						pointTracker.filterPoints((pointIndex) => {
-							var pointOffset = pointIndex * 2;
+						function regionFilter([x, y]) {
+
 							// distance from tip of nose (stretched so make an ellipse taller than wide)
-							var distance = Math.hypot(
-								(annotations.noseTip[0][0] - pointTracker.curXY[pointOffset]) * 1.4,
-								annotations.noseTip[0][1] - pointTracker.curXY[pointOffset + 1]
+							let distance = Math.hypot(
+								(annotations.noseTip[0][0] - x) * 1.4,
+								annotations.noseTip[0][1] - y
 							);
-							var headSize = Math.hypot(
+							let headSize = Math.hypot(
 								annotations.leftCheek[0][0] - annotations.rightCheek[0][0],
 								annotations.leftCheek[0][1] - annotations.rightCheek[0][1]
 							);
 							if (distance > headSize) {
 								return false;
 							}
+							// Avoid mouth affecting pointer position.
+							distance = annotations.lipsLowerInner.map((lipPoint) =>
+								Math.min(
+									Math.hypot(lipPoint[0] - x, lipPoint[1] - y),
+									Math.hypot(lipPoint[0] - x, lipPoint[1] + headSize * 0.1 - y), // a bit below too
+									Math.hypot(lipPoint[0] - x, lipPoint[1] + headSize * 0.2 - y), // a bit below too
+									Math.hypot(lipPoint[0] - x, lipPoint[1] + headSize * 0.3 - y), // a bit below too
+									Math.hypot(lipPoint[0] - x, lipPoint[1] + headSize * 0.4 - y), // a bit below too (yeah I'm being a little lazy here)
+								)
+							).reduce((a, b) => Math.min(a, b), Infinity);
+							if (distance < headSize * 0.1) {
+								return false;
+							}
 							// Avoid blinking eyes affecting pointer position.
 							// distance to outer corners of eyes
 							distance = Math.min(
 								Math.hypot(
-									annotations.leftEyeLower0[0][0] - pointTracker.curXY[pointOffset],
-									annotations.leftEyeLower0[0][1] - pointTracker.curXY[pointOffset + 1]
+									annotations.leftEyeLower0[0][0] - x,
+									annotations.leftEyeLower0[0][1] - y
 								),
 								Math.hypot(
-									annotations.rightEyeLower0[0][0] - pointTracker.curXY[pointOffset],
-									annotations.rightEyeLower0[0][1] - pointTracker.curXY[pointOffset + 1]
+									annotations.rightEyeLower0[0][0] - x,
+									annotations.rightEyeLower0[0][1] - y
 								),
 							);
 							if (distance < headSize * 0.42) {
 								return false;
 							}
 							return true;
+						}
+						pointTracker.filterPoints((pointIndex) => {
+							let pointOffset = pointIndex * 2;
+							const point = [pointTracker.curXY[pointOffset], pointTracker.curXY[pointOffset + 1]];
+							return regionFilter(point);
 						});
 
+						// Debug visualization for region filter (a sort of heatmap of where points will be culled)
+						if (showDebugRegionFilter) {
+							ctx.save();
+							if (s.mirror) {
+								ctx.translate(canvas.width, 0);
+								ctx.scale(-1, 1);
+							}
+							ctx.fillStyle = "rgba(255, 0, 0, 0.5)";
+							const vizStep = 4;
+							for (let x = 0; x < canvas.width; x += vizStep) {
+								for (let y = 0; y < canvas.height; y += vizStep) {
+									if (!regionFilter([x, y])) {
+										ctx.fillRect(x - 5, y - 5, vizStep, vizStep);
+									}
+								}
+							}
+							ctx.restore();
+						}
+
 						const keypoints = facemeshPrediction.keypoints;
 						if (keypoints) {
 							const top = keypoints[10]; // Top of forehead
@@ -3546,16 +3747,19 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 
 						blinkInfo = detectBlinks();
 						mouthInfo = detectMouthOpen();
-						if (blinkInfo.rightEye.open || blinkInfo.leftEye.open) {
-							lastTimeWhenAnEyeWasOpen = performance.now();
+						if (!blinkInfo.rightEye.open && !blinkInfo.leftEye.open) {
+							sleepGestureProgress += deltaTime / sleepGestureEyesClosedDuration;
+							sleepGestureProgress = Math.min(sleepGestureProgress, 1);
+						} else {
+							sleepGestureProgress -= deltaTime / sleepGestureEyesClosedDuration;
+							sleepGestureProgress = Math.max(sleepGestureProgress, 0);
 						}
-						if (performance.now() - lastTimeWhenAnEyeWasOpen > 2000) {
+						if (sleepGestureProgress >= 1) {
+							sleepGestureProgress = 0;
 							if (s.closeEyesToToggle) {
 								paused = !paused;
 								updatePaused();
-								// TODO: handle edge cases
-								// TODO: try to keep variable names meaningful
-								lastTimeWhenAnEyeWasOpen = Infinity;
+								sleepSweep?.sleepModeWasToggled(paused);
 							}
 						}
 
@@ -3617,10 +3821,41 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 
 						const buttonNames = ["left", "middle", "right"];
 						for (let buttonIndex = 0; buttonIndex < 3; buttonIndex++) {
-							if ((clickButton === buttonIndex) !== buttonStates[buttonNames[buttonIndex]]) {
-								setMouseButtonState(buttonIndex, clickButton === buttonIndex);
-								buttonStates[buttonNames[buttonIndex]] = clickButton === buttonIndex;
-								if ((clickButton === buttonIndex)) {
+							const buttonIsActive = clickButton === buttonIndex;
+							if (buttonIsActive !== buttonStates[buttonNames[buttonIndex]]) {
+								// Wait for confirmation of the button state change before playing SFX
+								// but not before updating buttonStates, since we check that in this loop
+								// to decide whether to call setMouseButtonState.
+								// We don't want to send extraneous mouse button changes to the main process,
+								// even if it does track button states itself. If nothing else it's wasted IPC.
+								// That said, an argument could be made for updating lastMouseDownTime later
+								// if the IPC is slow, to extend the time frame for making a simple click
+								// rather than a drag.
+								if (!setMouseButtonState) {
+									console.warn("setMouseButtonState function not provided");
+								} else {
+									const maybeAPromise = setMouseButtonState(buttonIndex, buttonIsActive);
+									const playSoundForButton = (changedButtonState) => {
+										if (changedButtonState) {
+											if (buttonIndex === 1) {
+												playSound(buttonIsActive ? "middleClickPress" : "middleClickRelease", {
+													volume: 4,
+												});
+											} else {
+												playSound(buttonIsActive ? "clickPress" : "clickRelease", {
+													playbackRate: buttonIndex === 0 ? 1 : buttonIndex === 2 ? 1.2 : 1.5,
+												});
+											}
+										}
+									};
+									if (maybeAPromise instanceof Promise) {
+										maybeAPromise.then(playSoundForButton);
+									} else {
+										playSoundForButton(maybeAPromise);
+									}
+								}
+								buttonStates[buttonNames[buttonIndex]] = buttonIsActive;
+								if (buttonIsActive) {
 									lastMouseDownTime = performance.now();
 								} else {
 									// Limit "Delay Before Dragging" effect to the duration of a click.
@@ -3893,14 +4128,14 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 
 					// cull points to those within useful facial region
 					pointTracker.filterPoints((pointIndex) => {
-						var pointOffset = pointIndex * 2;
+						let pointOffset = pointIndex * 2;
 						// distance from tip of nose (stretched so make an ellipse taller than wide)
-						var distance = Math.hypot(
+						let distance = Math.hypot(
 							(face[62][0] - pointTracker.curXY[pointOffset]) * 1.4,
 							face[62][1] - pointTracker.curXY[pointOffset + 1]
 						);
 						// distance based on outer eye corners
-						var headSize = Math.hypot(
+						let headSize = Math.hypot(
 							face[23][0] - face[28][0],
 							face[23][1] - face[28][1]
 						);
@@ -3925,21 +4160,23 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 		pointTracker.draw(debugPointsCtx);
 
 		if (update) {
-			const screenWidth = window.electronAPI ? screen.width : innerWidth;
-			const screenHeight = window.electronAPI ? screen.height : innerHeight;
+			const screenWidth = window.electronAPI ? (virtualDisplayBounds?.width ?? screen.width) : innerWidth;
+			const screenHeight = window.electronAPI ? (virtualDisplayBounds?.height ?? screen.height) : innerHeight;
+			const screenOffsetX = window.electronAPI ? (virtualDisplayBounds?.x ?? 0) : 0;
+			const screenOffsetY = window.electronAPI ? (virtualDisplayBounds?.y ?? 0) : 0;
 
-			var [movementX, movementY] = pointTracker.getMovement();
+			let [movementX, movementY] = pointTracker.getMovement();
 
 			// Acceleration curves add a lot of stability,
 			// letting you focus on a specific point without jitter, but still move quickly.
 
-			// var accelerate = (delta, distance) => (delta / 10) * (distance ** 0.8);
-			// var accelerate = (delta, distance) => (delta / 1) * (Math.abs(delta) ** 0.8);
-			var accelerate = (delta, _distance) => (delta / 1) * (Math.abs(delta * 5) ** s.headTrackingAcceleration);
+			// let accelerate = (delta, distance) => (delta / 10) * (distance ** 0.8);
+			// let accelerate = (delta, distance) => (delta / 1) * (Math.abs(delta) ** 0.8);
+			let accelerate = (delta, _distance) => (delta / 1) * (Math.abs(delta * 5) ** s.headTrackingAcceleration);
 
-			var distance = Math.hypot(movementX, movementY);
-			var deltaX = accelerate(movementX * s.headTrackingSensitivityX, distance);
-			var deltaY = accelerate(movementY * s.headTrackingSensitivityY, distance);
+			let distance = Math.hypot(movementX, movementY);
+			let deltaX = accelerate(movementX * s.headTrackingSensitivityX, distance);
+			let deltaY = accelerate(movementY * s.headTrackingSensitivityY, distance);
 
 			if (s.headTrackingTiltInfluence > 0) {
 				const yawRange = [
@@ -4056,13 +4293,13 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 				mouseX -= deltaX * screenWidth;
 				mouseY += deltaY * screenHeight;
 
-				mouseX = Math.min(Math.max(0, mouseX), screenWidth);
-				mouseY = Math.min(Math.max(0, mouseY), screenHeight);
+				mouseX = Math.min(Math.max(screenOffsetX, mouseX), screenOffsetX + screenWidth);
+				mouseY = Math.min(Math.max(screenOffsetY, mouseY), screenOffsetY + screenHeight);
 
 				if (mouseNeedsInitPos) {
 					// TODO: option to get preexisting mouse position instead of set it to center of screen
-					mouseX = screenWidth / 2;
-					mouseY = screenHeight / 2;
+					mouseX = screenOffsetX + screenWidth / 2;
+					mouseY = screenOffsetY + screenHeight / 2;
 					mouseNeedsInitPos = false;
 				}
 				if (window.electronAPI) {
@@ -4112,7 +4349,7 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 
 	// Can't use requestAnimationFrame, doesn't work with webPreferences.backgroundThrottling: false (at least in some version of Electron (v12 I think, when I tested it), on Ubuntu, with XFCE)
 	const iid = setInterval(function animationLoop() {
-		draw(!paused || document.visibilityState === "visible");
+		draw(!paused || document.visibilityState === "visible" || isDesktopApp);
 	}, 15);
 
 	let autoDemo = false;
@@ -4191,6 +4428,15 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 		_waitForSettingsLoaded() {
 			return settingsLoadedPromise;
 		},
+		get _facemeshPrediction() {
+			return facemeshPrediction;
+		},
+		get _headTilt() {
+			return headTilt;
+		},
+		get _video() {
+			return cameraVideo;
+		},
 		dispose() {
 			// TODO: re-structure so that cleanup can succeed even if initialization fails
 			// OOP would help with this, by storing references in an object, but it doesn't necessarily
@@ -4285,11 +4531,13 @@ TrackyMouse.init = function (div, opts = {}) {
 
 	createInner();
 
-	return {
-		dispose() {
-			inner.dispose();
-		},
-	};
+	return new Proxy({}, {
+		get(_target, prop) {
+			if (prop in inner) {
+				return inner[prop];
+			}
+		}
+	});
 
 };
 
@@ -4297,21 +4545,24 @@ TrackyMouse.initScreenOverlay = () => {
 
 	const template = `
 	<div class="tracky-mouse-hide-near-cursor">
-		<div class="tracky-mouse-absolute-center">
-			<div class="tracky-mouse-screen-overlay-status-indicator tracky-mouse-manual-takeback-indicator">
-				<img src="${TrackyMouse.dependenciesRoot}/images/manual-takeback.svg" alt="hand reaching for mouse" width="128" height="128">
-			</div>
-			<div class="tracky-mouse-screen-overlay-status-indicator tracky-mouse-head-not-found-indicator">
-				<img src="${TrackyMouse.dependenciesRoot}/images/head-not-found.svg" alt="head not found" width="128" height="128">
+		<div id="tracky-mouse-screen-overlay-work-area">
+			<div class="tracky-mouse-absolute-center">
+				<div class="tracky-mouse-screen-overlay-status-indicator tracky-mouse-manual-takeback-indicator">
+					<img src="${TrackyMouse.dependenciesRoot}/images/manual-takeback.svg" alt="hand reaching for mouse" width="128" height="128">
+				</div>
+				<div class="tracky-mouse-screen-overlay-status-indicator tracky-mouse-head-not-found-indicator">
+					<img src="${TrackyMouse.dependenciesRoot}/images/head-not-found.svg" alt="head not found" width="128" height="128">
+				</div>
 			</div>
+			<div id="tracky-mouse-screen-overlay-message"></div>
 		</div>
-		<div id="tracky-mouse-screen-overlay-message"></div>
 	</div>
 	`;
 	const fragment = document.createRange().createContextualFragment(template);
 	document.body.appendChild(fragment);
 
 	const message = document.getElementById("tracky-mouse-screen-overlay-message");
+	const workAreaContainer = document.getElementById("tracky-mouse-screen-overlay-work-area");
 	message.dir = "auto";
 
 	const hideNearCursorEls = document.querySelectorAll(".tracky-mouse-hide-near-cursor");
@@ -4358,9 +4609,30 @@ TrackyMouse.initScreenOverlay = () => {
 	}
 
 	function update(data) {
-		const { messageText, isEnabled, isManualTakeback, inputFeedback, bottomOffset, systemMousePosition } = data;
-
-		message.style.bottom = `${bottomOffset}px`;
+		const {
+			messageText,
+			isEnabled,
+			isManualTakeback,
+			inputFeedback,
+			workAreaContainerBounds,
+			bottomOffset,
+			systemMousePosition,
+		} = data;
+
+		if (workAreaContainerBounds) {
+			workAreaContainer.style.left = `${workAreaContainerBounds.x}px`;
+			workAreaContainer.style.top = `${workAreaContainerBounds.y}px`;
+			workAreaContainer.style.width = `${workAreaContainerBounds.width}px`;
+			workAreaContainer.style.height = `${workAreaContainerBounds.height}px`;
+			message.style.bottom = "0px";
+		} else {
+			// bottomOffset was a never-released part of an unstable API.
+			// workAreaContainerBounds could be made required, just like bottomOffset was.
+			workAreaContainer.style.left = "0px";
+			workAreaContainer.style.top = "0px";
+			workAreaContainer.style.width = "100%";
+			workAreaContainer.style.height = `calc(100% - ${bottomOffset ?? 0}px)`;
+		}
 
 		// Other diagnostics in the future would be stuff like:
 		// - head too far away (smaller than a certain size) https://github.com/1j01/tracky-mouse/issues/49