tracky-mouse 2.5.0 → 2.7.0

package/tracky-mouse.js

@@ -52,103 +52,114 @@ 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 = (s) => s;
+	const t = (key, options = {}) => options.defaultValue ?? key;
 
 	if (typeof config !== "object") {
-		throw new Error(t("configuration object required for initDwellClicking"));
+		throw new Error(t("api.errors.configRequired", { defaultValue: "configuration object required for initDwellClicking" }));
 	}
 	if (config.targets === undefined) {
-		throw new Error(t("config.targets is required (must be a CSS selector)"));
+		throw new Error(t("api.errors.targetsRequired", { defaultValue: "config.targets is required (must be a CSS selector)" }));
 	}
 	if (typeof config.targets !== "string") {
-		throw new Error(t("config.targets must be a string (a CSS selector)"));
+		throw new Error(t("api.errors.targetsMustBeSelectorString", { defaultValue: "config.targets must be a string (a CSS selector)" }));
 	}
 	if (!isSelectorValid(config.targets)) {
-		throw new Error(t("config.targets is not a valid CSS selector"));
+		throw new Error(t("api.errors.targetsInvalidSelector", { defaultValue: "config.targets is not a valid CSS selector" }));
 	}
 	if (config.click === undefined) {
-		throw new Error(t("config.click is required"));
+		throw new Error(t("api.errors.clickRequired", { defaultValue: "config.click is required" }));
 	}
 	if (typeof config.click !== "function") {
-		throw new Error(t("config.click must be a function"));
+		throw new Error(t("api.errors.functionRequired", { defaultValue: "%0 must be a function" }).replace("%0", "config.click"));
 	}
 	if (config.shouldDrag !== undefined && typeof config.shouldDrag !== "function") {
-		throw new Error(t("config.shouldDrag must be a function"));
+		throw new Error(t("api.errors.functionRequired", { defaultValue: "%0 must be a function" }).replace("%0", "config.shouldDrag"));
 	}
 	if (config.noCenter !== undefined && typeof config.noCenter !== "function") {
-		throw new Error(t("config.noCenter must be a function"));
+		throw new Error(t("api.errors.functionRequired", { defaultValue: "%0 must be a function" }).replace("%0", "config.noCenter"));
 	}
 	if (config.isEquivalentTarget !== undefined && typeof config.isEquivalentTarget !== "function") {
-		throw new Error(t("config.isEquivalentTarget must be a function"));
+		throw new Error(t("api.errors.functionRequired", { defaultValue: "%0 must be a function" }).replace("%0", "config.isEquivalentTarget"));
 	}
 	if (config.dwellClickEvenIfPaused !== undefined && typeof config.dwellClickEvenIfPaused !== "function") {
-		throw new Error(t("config.dwellClickEvenIfPaused must be a 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("config.beforeDispatch must be a function"));
+		throw new Error(t("api.errors.functionRequired", { defaultValue: "%0 must be a function" }).replace("%0", "config.beforeDispatch"));
 	}
 	if (config.afterDispatch !== undefined && typeof config.afterDispatch !== "function") {
-		throw new Error(t("config.afterDispatch must be a function"));
+		throw new Error(t("api.errors.functionRequired", { defaultValue: "%0 must be a function" }).replace("%0", "config.afterDispatch"));
 	}
 	if (config.beforePointerDownDispatch !== undefined && typeof config.beforePointerDownDispatch !== "function") {
-		throw new Error(t("config.beforePointerDownDispatch must be a function"));
+		throw new Error(t("api.errors.functionRequired", { defaultValue: "%0 must be a function" }).replace("%0", "config.beforePointerDownDispatch"));
 	}
 	if (config.isHeld !== undefined && typeof config.isHeld !== "function") {
-		throw new Error(t("config.isHeld must be a function"));
+		throw new Error(t("api.errors.functionRequired", { defaultValue: "%0 must be a function" }).replace("%0", "config.isHeld"));
 	}
 	if (config.retarget !== undefined) {
 		if (!Array.isArray(config.retarget)) {
-			throw new Error(t("config.retarget must be an array of objects"));
+			throw new Error(t("api.errors.retargetMustBeArray", { defaultValue: "config.retarget must be an array of objects" }));
 		}
 		for (let i = 0; i < config.retarget.length; i++) {
 			const rule = config.retarget[i];
 			if (typeof rule !== "object") {
-				throw new Error(t("config.retarget must be an array of objects"));
+				throw new Error(t("api.errors.retargetMustBeArray", { defaultValue: "config.retarget must be an array of objects" }));
 			}
 			if (rule.from === undefined) {
-				throw new Error(t("config.retarget[%0].from is required").replace("%0", i));
+				throw new Error(t("api.errors.retargetFromRequired", { defaultValue: "config.retarget[%0].from is required" }).replace("%0", i));
 			}
 			if (rule.to === undefined) {
-				throw new Error(t("config.retarget[%0].to is required (although can be null to ignore the element)").replace("%0", i));
+				throw new Error(t("api.errors.retargetToRequired", { defaultValue: "config.retarget[%0].to is required (although can be null to ignore the element)" }).replace("%0", i));
 			}
 			if (rule.withinMargin !== undefined && typeof rule.withinMargin !== "number") {
-				throw new Error(t("config.retarget[%0].withinMargin must be a number").replace("%0", i));
+				throw new Error(t("api.errors.numberRequired", { defaultValue: "%0 must be a number" }).replace("%0", `config.retarget[${i}].withinMargin`));
 			}
 			if (typeof rule.from !== "string" && typeof rule.from !== "function" && !(rule.from instanceof Element)) {
-				throw new Error(t("config.retarget[%0].from must be a CSS selector string, an Element, or a function").replace("%0", i));
+				throw new Error(t("api.errors.retargetFromInvalidType", { defaultValue: "config.retarget[%0].from must be a CSS selector string, an Element, or a function" }).replace("%0", i));
 			}
 			if (typeof rule.to !== "string" && typeof rule.to !== "function" && !(rule.to instanceof Element) && rule.to !== null) {
-				throw new Error(t("config.retarget[%0].to must be a CSS selector string, an Element, a function, or null").replace("%0", i));
+				throw new Error(t("api.errors.retargetToInvalidType", { defaultValue: "config.retarget[%0].to must be a CSS selector string, an Element, a function, or null" }).replace("%0", i));
 			}
 			if (typeof rule.from === "string" && !isSelectorValid(rule.from)) {
-				throw new Error(t("config.retarget[%0].from is not a valid CSS selector").replace("%0", i));
+				throw new Error(t("api.errors.retargetFromInvalidSelector", { defaultValue: "config.retarget[%0].from is not a valid CSS selector" }).replace("%0", i));
 			}
 			if (typeof rule.to === "string" && !isSelectorValid(rule.to)) {
-				throw new Error(t("config.retarget[%0].to is not a valid CSS selector").replace("%0", i));
+				throw new Error(t("api.errors.retargetToInvalidSelector", { defaultValue: "config.retarget[%0].to is not a valid CSS selector" }).replace("%0", i));
 			}
 		}
 	}
 
+	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,7 +597,57 @@ TrackyMouse.cleanupDwellClicking = function () {
 	}
 };
 
-TrackyMouse._initInner = function (div, { statsJs = false }, reinit) {
+TrackyMouse._initAudio = async function () {
+	let module;
+	try {
+		// console.log("Loading audio support...");
+		module = await import("./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 {
+		statsJs = false,
+		// Unstable
+		updateInputFeedback = window.electronAPI?.updateInputFeedback,
+		// Unstable
+		setMouseButtonState = window.electronAPI?.setMouseButtonState,
+		// Unstable
+		notifyToggleState = window.electronAPI?.notifyToggleState,
+		// Unstable
+		handleSettingsUpdate,
+		// Unstable
+		clickingModeSupported = false,
+		// TODO: manage all of electronAPI similarly? well, setOptions is already a function in scope here,
+		// and it's not like we want to expose all electronAPI as part of the public API necessarily
+		// 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;
 
@@ -617,7 +693,7 @@ TrackyMouse._initInner = function (div, { statsJs = false }, reinit) {
 	}
 	const rtlLanguages = ["ar", "he", "fa", "ur"]; // Right-to-left languages (current and future)
 	const isRTL = rtlLanguages.includes(locale.split("-")[0]);
-	const t = (s) => translations[s] ?? s;
+	const t = (key, options = {}) => translations[key] ?? options.defaultValue ?? key;
 	// console.trace("Initializing UI with locale", locale);
 
 	// language name mappings marked with * may not be ISO 639-1
@@ -826,7 +902,7 @@ TrackyMouse._initInner = function (div, { statsJs = false }, reinit) {
 	};
 
 
-	var languageToDefaultRegion = {
+	let languageToDefaultRegion = {
 		aa: "ET",
 		ab: "GE",
 		abr: "GH",
@@ -1571,9 +1647,9 @@ TrackyMouse._initInner = function (div, { statsJs = false }, 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()];
@@ -1588,38 +1664,38 @@ TrackyMouse._initInner = function (div, { statsJs = false }, 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";
 	uiContainer.innerHTML = `
 		<div class="tracky-mouse-controls">
-			<button class="tracky-mouse-start-stop-button" aria-pressed="false" aria-keyshortcuts="F9">${t("Start")}</button>
+			<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-canvas-container">
 				<div class="tracky-mouse-canvas-overlay">
-					<button class="tracky-mouse-use-camera-button">${t("Allow Camera Access")}</button>
-					<!--<button class="tracky-mouse-use-camera-button">${t("Use my camera")}</button>-->
-					<button class="tracky-mouse-use-demo-footage-button" hidden>${t("Use demo footage")}</button>
+					<button class="tracky-mouse-use-camera-button">${t("ui.camera.allowAccess", { defaultValue: "Allow Camera Access" })}</button>
+					<!--<button class="tracky-mouse-use-camera-button">${t("ui.camera.useMyCamera", { defaultValue: "Use my camera" })}</button>-->
+					<button class="tracky-mouse-use-demo-footage-button" hidden>${t("ui.camera.useDemoFootage", { defaultValue: "Use demo footage" })}</button>
 					<div class="tracky-mouse-error-message" role="alert" hidden></div>
 				</div>
 				<canvas class="tracky-mouse-canvas"></canvas>
 			</div>
 		</div>
 		<p class="tracky-mouse-desktop-app-download-message">
-			${t('You can control your entire computer with the <a href="https://trackymouse.js.org/">TrackyMouse</a> desktop app.')}
+			${t("ui.desktopAppPromo.message", { defaultValue: 'You can control your entire computer with the <a href="https://trackymouse.js.org/">TrackyMouse</a> desktop app.' })}
 		</p>
 	`;
 	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');
 
 	// Settings (initialized later; defaults are defined in settingsCategories)
 	const s = {};
@@ -1631,10 +1707,10 @@ TrackyMouse._initInner = function (div, { statsJs = false }, reinit) {
 	const settingsCategories = [
 		{
 			type: "group",
-			label: t("Cursor Movement"),
+			label: t("settings.sections.cursorMovement.label", { defaultValue: "Cursor Movement" }),
 			settings: [
 				{
-					label: t("Tilt influence"),
+					label: t("settings.tiltInfluence.label", { defaultValue: "Tilt influence" }),
 					className: "tracky-mouse-tilt-influence",
 					key: "headTrackingTiltInfluence",
 					settingValueToInputValue: (settingValue) => settingValue * 100,
@@ -1644,20 +1720,21 @@ TrackyMouse._initInner = function (div, { statsJs = false }, reinit) {
 					max: 100,
 					default: 0,
 					labels: {
-						// min: t("Optical flow"), // too technical
-						// min: t("Point tracking"), // still technical but at least it's terminology we're already using
-						min: t("Point tracking (2D)"),
-						// max: t("Head tilt"),
-						max: t("Head tilt (3D)"),
+						// min: t("settings.tiltInfluence.sliderMin.alt1", { defaultValue: "Optical flow" }), // too technical
+						// min: t("settings.tiltInfluence.sliderMin.alt2", { defaultValue: "Point tracking" }), // still technical but at least it's terminology we're already using
+						min: t("settings.tiltInfluence.sliderMin", { defaultValue: "Point tracking (2D)" }),
+						// max: t("settings.tiltInfluence.sliderMax.alt1", { defaultValue: "Head tilt" }),
+						max: t("settings.tiltInfluence.sliderMax", { defaultValue: "Head tilt (3D)" }),
 					},
-					// description: t("Determines whether cursor movement is based on 3D head tilt, or 2D motion of the face in the camera feed."),
-					description: t(`Blends between using point tracking (2D) and detected head tilt (3D).
+					// description: t("settings.tiltInfluence.description.alt1", { defaultValue: "Determines whether cursor movement is based on 3D head tilt, or 2D motion of the face in the camera feed." }),
+					description: t("settings.tiltInfluence.description", {
+						defaultValue: `Blends between using point tracking (2D) and detected head tilt (3D).
 - At 0% it will use only point tracking. This moves the cursor according to visible movement of 2D points on your face within the camera's view, so it responds to both head rotation and translation.
 - At 100% it will use only head tilt. This uses an estimate of your face's orientation in 3D space, and ignores head translation. Note that this is smoothed, so it's not as responsive as point tracking. In this mode you never need to recenter by pushing the cursor to the edge of the screen.
-- In between it will behave like an automatic calibration, subtly adjusting the point tracking to match the head tilt. This works by slowing down mouse movement that is moving away from the position that would be expected based on the head tilt, and (only past 80% on the slider) actively moving towards it.`),
+- In between it will behave like an automatic calibration, subtly adjusting the point tracking to match the head tilt. This works by slowing down mouse movement that is moving away from the position that would be expected based on the head tilt, and (only past 80% on the slider) actively moving towards it.` }),
 				},
 				{
-					label: t("Motion threshold"),
+					label: t("settings.motionThreshold.label", { defaultValue: "Motion threshold" }),
 					className: "tracky-mouse-min-distance",
 					key: "headTrackingMinDistance",
 					type: "slider",
@@ -1665,20 +1742,20 @@ TrackyMouse._initInner = function (div, { statsJs = false }, reinit) {
 					max: 10,
 					default: 0,
 					labels: {
-						min: t("Free"),
-						max: t("Steady"),
+						min: t("settings.motionThreshold.sliderMin", { defaultValue: "Free" }),
+						max: t("settings.motionThreshold.sliderMax", { defaultValue: "Steady" }),
 					},
-					description: t("Minimum distance to move the cursor in one frame, in pixels. Helps to fully stop the cursor."),
-					// description: t("Movement less than this distance in pixels will be ignored."),
-					// description: t("Speed in pixels/frame required to move the cursor."),
+					description: t("settings.motionThreshold.description", { defaultValue: "Minimum distance to move the cursor in one frame, in pixels. Helps to fully stop the cursor." }),
+					// description: t("settings.motionThreshold.description.alt1", { defaultValue: "Movement less than this distance in pixels will be ignored." }),
+					// description: t("settings.motionThreshold.description.alt2", { defaultValue: "Speed in pixels/frame required to move the cursor." }),
 				},
 				{
 					type: "group",
-					label: t("Point tracking"),
+					label: t("settings.sections.pointTracking.label", { defaultValue: "Point tracking" }),
 					disabled: () => s.headTrackingTiltInfluence === 1,
 					settings: [
 						{
-							label: t("Horizontal sensitivity"),
+							label: t("settings.pointTracking.horizontalSensitivity.label", { defaultValue: "Horizontal sensitivity" }),
 							className: "tracky-mouse-sensitivity-x",
 							key: "headTrackingSensitivityX",
 							settingValueToInputValue: (settingValue) => settingValue * 1000,
@@ -1688,13 +1765,13 @@ TrackyMouse._initInner = function (div, { statsJs = false }, reinit) {
 							max: 100,
 							default: 25,
 							labels: {
-								min: t("Slow"),
-								max: t("Fast"),
+								min: t("settings.shared.sliderMinSlow", { defaultValue: "Slow" }),
+								max: t("settings.shared.sliderMaxFast", { defaultValue: "Fast" }),
 							},
-							description: t("Speed of cursor movement in response to horizontal head movement."),
+							description: t("settings.pointTracking.horizontalSensitivity.description", { defaultValue: "Speed of cursor movement in response to horizontal head movement." }),
 						},
 						{
-							label: t("Vertical sensitivity"),
+							label: t("settings.pointTracking.verticalSensitivity.label", { defaultValue: "Vertical sensitivity" }),
 							className: "tracky-mouse-sensitivity-y",
 							key: "headTrackingSensitivityY",
 							settingValueToInputValue: (settingValue) => settingValue * 1000,
@@ -1704,13 +1781,13 @@ TrackyMouse._initInner = function (div, { statsJs = false }, reinit) {
 							max: 100,
 							default: 50,
 							labels: {
-								min: t("Slow"),
-								max: t("Fast"),
+								min: t("settings.shared.sliderMinSlow", { defaultValue: "Slow" }),
+								max: t("settings.shared.sliderMaxFast", { defaultValue: "Fast" }),
 							},
-							description: t("Speed of cursor movement in response to vertical head movement."),
+							description: t("settings.pointTracking.verticalSensitivity.description", { defaultValue: "Speed of cursor movement in response to vertical head movement." }),
 						},
 						// {
-						// 	label: t("Smoothing"),
+						// 	label: t("settings.pointTracking.smoothing.label", { defaultValue: "Smoothing" }),
 						// 	className: "tracky-mouse-smoothing",
 						// 	key: "headTrackingSmoothing",
 						// 	type: "slider",
@@ -1718,8 +1795,8 @@ TrackyMouse._initInner = function (div, { statsJs = false }, reinit) {
 						// 	max: 100,
 						// 	default: 50,
 						// 	labels: {
-						// 		min: t("Linear"), // or "Direct", "Raw", "None"
-						// 		max: t("Smooth"), // or "Smoothed"
+						// 		min: t("settings.shared.sliderMinLinear", { defaultValue: "Linear" }), // or "Direct", "Raw", "None"
+						// 		max: t("settings.shared.sliderMaxSmooth", { defaultValue: "Smooth" }), // or "Smoothed"
 						// 	},
 						// },
 
@@ -1732,7 +1809,7 @@ TrackyMouse._initInner = function (div, { statsJs = false }, reinit) {
 						// Should it be swapped? What does other software with acceleration control look like?
 						// In Windows it's just a checkbox apparently, but it could go as far as a custom curve editor.
 						{
-							label: t("Acceleration"),
+							label: t("settings.pointTracking.acceleration.label", { defaultValue: "Acceleration" }),
 							className: "tracky-mouse-acceleration",
 							key: "headTrackingAcceleration",
 							settingValueToInputValue: (settingValue) => settingValue * 100,
@@ -1742,23 +1819,24 @@ TrackyMouse._initInner = function (div, { statsJs = false }, reinit) {
 							max: 100,
 							default: 50,
 							labels: {
-								min: t("Linear"), // or "Direct", "Raw"
-								max: t("Smooth"),
+								min: t("settings.shared.sliderMinLinear", { defaultValue: "Linear" }), // or "Direct", "Raw"
+								max: t("settings.shared.sliderMaxSmooth", { defaultValue: "Smooth" }),
 							},
-							// description: t("Higher acceleration makes the cursor move faster when the head moves quickly, and slower when the head moves slowly."),
-							// description: t("Makes the cursor move extra fast for quick head movements, and extra slow for slow head movements. Helps to stabilize the cursor."),
-							description: t(`Makes the cursor move relatively fast for quick head movements, and relatively slow for slow head movements.
-Helps to stabilize the cursor. However, when using point tracking in combination with head tilt, a lower value may work better since head tilt is linear, and you want the point tracking to roughly match the head tracking for it to act as a seamless auto- calibration.`),
+							// description: t("settings.pointTracking.acceleration.description.alt1", { defaultValue: "Higher acceleration makes the cursor move faster when the head moves quickly, and slower when the head moves slowly." }),
+							// description: t("settings.pointTracking.acceleration.description.alt2", { defaultValue: "Makes the cursor move extra fast for quick head movements, and extra slow for slow head movements. Helps to stabilize the cursor." }),
+							description: t("settings.pointTracking.acceleration.description", {
+								defaultValue: `Makes the cursor move relatively fast for quick head movements, and relatively slow for slow head movements.
+Helps to stabilize the cursor. However, when using point tracking in combination with head tilt, a lower value may work better since head tilt is linear, and you want the point tracking to roughly match the head tracking for it to act as a seamless auto-calibration.` }),
 						},
 					],
 				},
 				{
 					type: "group",
-					label: t("Head tilt calibration"),
+					label: t("settings.sections.headTiltCalibration.label", { defaultValue: "Head tilt calibration" }),
 					disabled: () => s.headTrackingTiltInfluence === 0,
 					settings: [
 						{
-							label: t("Horizontal tilt range"),
+							label: t("settings.headTilt.horizontalRange.label", { defaultValue: "Horizontal tilt range" }),
 							className: "tracky-mouse-head-tilt-yaw-range",
 							key: "headTiltYawRange",
 							settingValueToInputValue: (settingValue) => settingValue * 180 / Math.PI,
@@ -1768,16 +1846,16 @@ Helps to stabilize the cursor. However, when using point tracking in combination
 							max: 90,
 							default: 60,
 							labels: {
-								min: t("Little neck movement"),
-								max: t("Large neck movement"),
+								min: t("settings.headTilt.range.sliderMinLittleNeckMovement", { defaultValue: "Little neck movement" }),
+								max: t("settings.headTilt.range.sliderMaxLargeNeckMovement", { defaultValue: "Large neck movement" }),
 							},
-							// description: t("Range of horizontal head tilt that moves the cursor from one side of the screen to the other."),
-							// description: t("How much you need to tilt your head left and right to reach the edges of the screen."),
-							// description: t("How much you need to tilt your head left or right to reach the edge of the screen."),
-							description: t("Controls how much you need to tilt your head left or right to reach the edge of the screen."),
+							// description: t("settings.headTilt.horizontalRange.description.alt1", { defaultValue: "Range of horizontal head tilt that moves the cursor from one side of the screen to the other." }),
+							// description: t("settings.headTilt.horizontalRange.description.alt2", { defaultValue: "How much you need to tilt your head left and right to reach the edges of the screen." }),
+							// description: t("settings.headTilt.horizontalRange.description.alt3", { defaultValue: "How much you need to tilt your head left or right to reach the edge of the screen." }),
+							description: t("settings.headTilt.horizontalRange.description", { defaultValue: "Controls how much you need to tilt your head left or right to reach the edge of the screen." }),
 						},
 						{
-							label: t("Vertical tilt range"),
+							label: t("settings.headTilt.verticalRange.label", { defaultValue: "Vertical tilt range" }),
 							className: "tracky-mouse-head-tilt-pitch-range",
 							key: "headTiltPitchRange",
 							settingValueToInputValue: (settingValue) => settingValue * 180 / Math.PI,
@@ -1787,17 +1865,17 @@ Helps to stabilize the cursor. However, when using point tracking in combination
 							max: 60,
 							default: 25,
 							labels: {
-								min: t("Little neck movement"),
-								max: t("Large neck movement"),
+								min: t("settings.headTilt.range.sliderMinLittleNeckMovement", { defaultValue: "Little neck movement" }),
+								max: t("settings.headTilt.range.sliderMaxLargeNeckMovement", { defaultValue: "Large neck movement" }),
 							},
-							// description: t("Range of vertical head tilt required to move the cursor from the top to the bottom of the screen."),
-							// description: t("How much you need to tilt your head up and down to reach the edges of the screen."),
-							// description: t("How much you need to tilt your head up or down to reach the edge of the screen."),
-							description: t("Controls how much you need to tilt your head up or down to reach the edge of the screen."),
+							// description: t("settings.headTilt.verticalRange.description.alt1", { defaultValue: "Range of vertical head tilt required to move the cursor from the top to the bottom of the screen." }),
+							// description: t("settings.headTilt.verticalRange.description.alt2", { defaultValue: "How much you need to tilt your head up and down to reach the edges of the screen." }),
+							// description: t("settings.headTilt.verticalRange.description.alt3", { defaultValue: "How much you need to tilt your head up or down to reach the edge of the screen." }),
+							description: t("settings.headTilt.verticalRange.description", { defaultValue: "Controls how much you need to tilt your head up or down to reach the edge of the screen." }),
 						},
 						{
 							// label: "Horizontal tilt offset",
-							label: t("Horizontal cursor offset"),
+							label: t("settings.headTilt.horizontalOffset.label", { defaultValue: "Horizontal cursor offset" }),
 							className: "tracky-mouse-head-tilt-yaw-offset",
 							key: "headTiltYawOffset",
 							settingValueToInputValue: (settingValue) => settingValue * 180 / Math.PI,
@@ -1807,8 +1885,8 @@ Helps to stabilize the cursor. However, when using point tracking in combination
 							max: 45,
 							default: 0,
 							labels: {
-								min: t("Left"),
-								max: t("Right"),
+								min: t("settings.shared.directionLeft", { defaultValue: "Left" }),
+								max: t("settings.shared.directionRight", { defaultValue: "Right" }),
 							},
 							// TODO: how to describe this??
 							// Specifically, how to disambiguate which direction is which / which way to adjust it?
@@ -1816,15 +1894,16 @@ Helps to stabilize the cursor. However, when using point tracking in combination
 							// Since it's opposite, even though it's technically yaw (angle units), it's easier to think of as moving the cursor.
 							// Hence I've renamed the setting.
 							// A later update might change the definitions and include a settings file format upgrade step.
-							// description: t("Adjusts the center position of horizontal head tilt. Not recommended. Move the camera instead if possible."),
-							// description: t("Adjusts the center position of horizontal head tilt. This horizontal offset is not recommended. Move the camera instead if possible."),
+							// description: t("settings.headTilt.horizontalOffset.description.alt1", { defaultValue: "Adjusts the center position of horizontal head tilt. Not recommended. Move the camera instead if possible." }),
+							// description: t("settings.headTilt.horizontalOffset.description.alt2", { defaultValue: "Adjusts the center position of horizontal head tilt. This horizontal offset is not recommended. Move the camera instead if possible." }),
 							// TODO: should this say "horizontal" in the (main part of the) description?
-							description: t(`Adjusts the position of the cursor when the camera sees the head facing straight ahead.
-⚠️ This horizontal offset is not recommended. Move the camera instead if possible. 📷`),
+							description: t("settings.headTilt.horizontalOffset.description", {
+								defaultValue: `Adjusts the position of the cursor when the camera sees the head facing straight ahead.
+⚠️ This horizontal offset is not recommended. Move the camera instead if possible. 📷` }),
 						},
 						{
 							// label: "Vertical tilt offset",
-							label: t("Vertical cursor offset"),
+							label: t("settings.headTilt.verticalOffset.label", { defaultValue: "Vertical cursor offset" }),
 							className: "tracky-mouse-head-tilt-pitch-offset",
 							key: "headTiltPitchOffset",
 							settingValueToInputValue: (settingValue) => settingValue * 180 / Math.PI,
@@ -1834,11 +1913,11 @@ Helps to stabilize the cursor. However, when using point tracking in combination
 							max: 30,
 							default: 2.5,
 							labels: {
-								min: t("Down"),
-								max: t("Up"),
+								min: t("settings.shared.directionDown", { defaultValue: "Down" }),
+								max: t("settings.shared.directionUp", { defaultValue: "Up" }),
 							},
-							// description: t("Adjusts the center position of vertical head tilt."),
-							description: t("Adjusts the position of the cursor when the camera sees the head facing straight ahead."),
+							// description: t("settings.headTilt.verticalOffset.description.alt1", { defaultValue: "Adjusts the center position of vertical head tilt." }),
+							description: t("settings.headTilt.verticalOffset.description", { defaultValue: "Adjusts the position of the cursor when the camera sees the head facing straight ahead." }),
 						},
 					],
 				},
@@ -1858,42 +1937,43 @@ Helps to stabilize the cursor. However, when using point tracking in combination
 		// which awkwardly affects what mouse button serenade-driver sends; this doesn't affect the web version.
 		{
 			type: "group",
-			label: t("Clicking"),
+			label: t("settings.sections.clicking.label", { defaultValue: "Clicking" }),
 			settings: [
 				{
-					label: t("Clicking mode:"), // TODO: ":"?
+					label: t("settings.clickingMode.label", { defaultValue: "Clicking mode:" }), // TODO: ":"?
 					className: "tracky-mouse-clicking-mode",
 					key: "clickingMode",
 					type: "dropdown",
 					options: [
-						{ value: "dwell", label: t("Dwell to click"), description: t("Hold the cursor in place for a short time to click.") },
-						{ value: "blink", label: t("Wink to click"), description: t("Close one eye to click. Left eye for left click, right eye for right click.") },
+						{ value: "dwell", label: t("settings.clickingMode.dwell.label", { defaultValue: "Dwell to click" }), description: t("settings.clickingMode.dwell.description", { defaultValue: "Hold the cursor in place for a short time to click." }) },
+						{ value: "blink", label: t("settings.clickingMode.wink.label", { defaultValue: "Wink to click" }), description: t("settings.clickingMode.wink.description", { defaultValue: "Close one eye to click. Left eye for left click, right eye for right click." }) },
 						// TODO: clarify that ooh works better than ah
 						// "open wide" refers to height, but could be misinterpreted as opposite advice - a wide mouth shape when narrow works better
 						// "open wide" is also perhaps unnecessary considering detection is improved... but who knows. maybe someone will try opening their mouth only slightly and expect it to work
 						// Some people may understand "tall and narrow" better than "ooh rather than ah" and visa-versa
-						{ value: "open-mouth-simple", label: t("Open mouth to click (simple)"), description: t("Open your mouth wide to click. At least one eye must be open to click.") },
-						{ value: "open-mouth-ignoring-eyes", label: t("Open mouth to click (ignoring eyes)"), description: t("Open your mouth wide to click. Eye state is ignored.") },
-						{ value: "open-mouth", label: t("Open mouth to click (with eye modifiers)"), description: t("Open your mouth wide to click. If left eye is closed, it's a right click; if right eye is closed, it's a middle click.") },
-						{ value: "off", label: t("Off"), description: t("Disable clicking. Use with an external switch or programs that provide their own dwell clicking.") },
+						{ value: "open-mouth-simple", label: t("settings.clickingMode.openMouthSimple.label", { defaultValue: "Open mouth to click (simple)" }), description: t("settings.clickingMode.openMouthSimple.description", { defaultValue: "Open your mouth wide to click. At least one eye must be open to click." }) },
+						{ value: "open-mouth-ignoring-eyes", label: t("settings.clickingMode.openMouthIgnoringEyes.label", { defaultValue: "Open mouth to click (ignoring eyes)" }), description: t("settings.clickingMode.openMouthIgnoringEyes.description", { defaultValue: "Open your mouth wide to click. Eye state is ignored." }) },
+						{ value: "open-mouth", label: t("settings.clickingMode.openMouthWithEyeModifiers.label", { defaultValue: "Open mouth to click (with eye modifiers)" }), description: t("settings.clickingMode.openMouthWithEyeModifiers.description", { defaultValue: "Open your mouth wide to click. If left eye is closed, it's a right click; if right eye is closed, it's a middle click." }) },
+						{ value: "off", label: t("settings.clickingMode.off.label", { defaultValue: "Off" }), description: t("settings.clickingMode.off.description", { defaultValue: "Disable clicking. Use with an external switch or programs that provide their own dwell clicking." }) },
 					],
 					default: "dwell",
-					visible: () => isDesktopApp,
-					description: t("Choose how to perform mouse clicks."),
+					visible: () => isDesktopApp || clickingModeSupported,
+					description: t("settings.clickingMode.description", { defaultValue: "Choose how to perform mouse clicks." }),
 				},
 				{
 					// on Windows, currently, when buttons are swapped at the system level, it affects serenade-driver's click()
 					// "swap" is purposefully generic language so we don't have to know what system-level setting is
 					// (also this may be seen as a weirdly named/designed option for right-clicking with the dwell clicker)
-					label: t("Swap mouse buttons"),
+					label: t("settings.swapMouseButtons.label", { defaultValue: "Swap mouse buttons" }),
 					className: "tracky-mouse-swap-mouse-buttons",
 					key: "swapMouseButtons",
 					type: "checkbox",
 					default: false,
 					visible: () => isDesktopApp,
-					description: t(`Switches the left and right mouse buttons.
+					description: t("settings.swapMouseButtons.description", {
+						defaultValue: `Switches the left and right mouse buttons.
 Useful if your system's mouse buttons are swapped.
-Could also be used to right click with the dwell clicker in a pinch.`),
+Could also be used to right click with the dwell clicker in a pinch.` }),
 				},
 
 				// This setting could called "click stabilization", "drag delay", "delay before dragging", "click drag delay", "drag prevention", etc.
@@ -1902,33 +1982,37 @@ Could also be used to right click with the dwell clicker in a pinch.`),
 				// at the end of the slider, although you shouldn't need to do that to effectively avoid dragging when trying to click,
 				// and it might complicate the design of the slider labeling.
 				{
-					label: t("Delay before dragging&nbsp;&nbsp;&nbsp;"), // TODO: avoid non-breaking space hack
+					label: t("settings.delayBeforeDragging.label", { defaultValue: "Delay before dragging" }),
 					className: "tracky-mouse-delay-before-dragging",
 					key: "delayBeforeDragging",
 					type: "slider",
 					min: 0,
 					max: 1000,
 					labels: {
-						min: t("Easy to drag"),
-						max: t("Easy to click"),
+						min: t("settings.delayBeforeDragging.sliderMin", { defaultValue: "Easy to drag" }),
+						max: t("settings.delayBeforeDragging.sliderMax", { defaultValue: "Easy to click" }),
 					},
 					default: 800,
-					visible: () => isDesktopApp,
+					visible: () => isDesktopApp || clickingModeSupported,
 					disabled: () => s.clickingMode === "off" || s.clickingMode === "dwell",
-					// description: t("Locks mouse movement during the start of a click to prevent accidental dragging."),
-					// description: t(`Prevents mouse movement for the specified time after a click starts.
-					// You may want to turn this off if you're drawing on a canvas, or increase it if you find yourself accidentally dragging when you try to click.`),
-					description: t(`Locks mouse movement for the given duration during the start of a click.
-You may want to turn this off if you're drawing on a canvas, or increase it if you find yourself accidentally dragging when you try to click.`),
+					// description: t("settings.delayBeforeDragging.description.alt1", { defaultValue: "Locks mouse movement during the start of a click to prevent accidental dragging." }),
+					// Throwing a // in here so it's not detected by i18next-cli, whereas the others are allowed
+					// simply because it wasn't previously detected and translated
+					// due to being both commented out and multiline (though multiline and commented out t() calls are separately supported)
+					// description: t//("settings.delayBeforeDragging.description.alt2", { defaultValue: `Prevents mouse movement for the specified time after a click starts.
+					// You may want to turn this off if you're drawing on a canvas, or increase it if you find yourself accidentally dragging when you try to click.` }),
+					description: t("settings.delayBeforeDragging.description", {
+						defaultValue: `Locks mouse movement for the given duration during the start of a click.
+You may want to turn this off if you're drawing on a canvas, or increase it if you find yourself accidentally dragging when you try to click.` }),
 				},
 			],
 		},
 		{
 			type: "group",
-			label: t("Video"),
+			label: t("settings.sections.video.label", { defaultValue: "Video" }),
 			settings: [
 				{
-					label: t("Camera source"),
+					label: t("settings.cameraSource.label", { defaultValue: "Camera source" }),
 					className: "tracky-mouse-camera-select",
 					key: "cameraDeviceId",
 					handleSettingChange: () => {
@@ -1936,15 +2020,15 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 					},
 					type: "dropdown",
 					options: [
-						{ value: "", label: t("Default") },
+						{ value: "", label: t("settings.cameraSource.defaultCamera", { defaultValue: "Default" }) },
 					],
 					default: "",
-					// description: t("Select which camera to use for head tracking."),
-					description: t("Selects which camera is used for head tracking."),
+					// description: t("settings.cameraSource.description.alt1", { defaultValue: "Select which camera to use for head tracking." }),
+					description: t("settings.cameraSource.description", { defaultValue: "Selects which camera is used for head tracking." }),
 				},
 				// TODO: move this inline with the camera source dropdown?
 				{
-					label: t("Open Camera Settings"),
+					label: t("settings.openCameraSettings.label", { defaultValue: "Open Camera Settings" }),
 					className: "tracky-mouse-open-camera-settings",
 					key: "openCameraSettings",
 					type: "button",
@@ -1954,45 +2038,59 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 						try {
 							knownCameras = JSON.parse(localStorage.getItem("tracky-mouse-known-cameras")) || {};
 						} catch (error) {
-							alert(t("Failed to open camera settings:\n") + t("Failed to parse known cameras from localStorage:\n") + error.message);
+							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);
 							return;
 						}
 
 						const activeStream = cameraVideo.srcObject;
 						const activeDeviceId = activeStream?.getVideoTracks()[0]?.getSettings()?.deviceId;
-						const selectedDeviceName = knownCameras[activeDeviceId]?.name || t("Default");
+						const selectedDeviceName = knownCameras[activeDeviceId]?.name || t("settings.cameraSource.defaultCamera", { defaultValue: "Default" });
 
 						try {
 							const result = await window.electronAPI.openCameraSettings(selectedDeviceName);
 							if (result?.error) {
-								alert(t("Failed to open camera settings:\n") + result.error);
+								alert(t("openCameraSettings.errors.sharedHeading", { defaultValue: "Failed to open camera settings:" }) + "\n" + result.error);
 							}
 						} catch (error) {
-							alert(t("Failed to open camera settings:\n") + error.message);
+							alert(t("openCameraSettings.errors.sharedHeading", { defaultValue: "Failed to open camera settings:" }) + "\n" + error.message);
 						}
 					},
-					// description: t("Open your camera's system settings window to adjust properties like brightness and contrast."),
-					// description: t("Opens the system settings window for your camera to adjust properties like auto-focus and auto-exposure."),
-					description: t("Opens the system settings dialog for the selected camera, to adjust properties like auto-focus and auto-exposure."),
+					// description: t("settings.openCameraSettings.description.alt1", { defaultValue: "Open your camera's system settings window to adjust properties like brightness and contrast." }),
+					// description: t("settings.openCameraSettings.description.alt2", { defaultValue: "Opens the system settings window for your camera to adjust properties like auto-focus and auto-exposure." }),
+					description: t("settings.openCameraSettings.description", { defaultValue: "Opens the system settings dialog for the selected camera, to adjust properties like auto-focus and auto-exposure." }),
 				},
 				// TODO: try moving this to the corner of the camera view, so it's clearer it applies only to the camera view
 				{
-					label: t("Mirror"),
+					label: t("settings.mirror.label", { defaultValue: "Mirror" }),
 					className: "tracky-mouse-mirror",
 					key: "mirror",
 					type: "checkbox",
 					default: true,
-					description: t("Mirrors the camera view horizontally."),
+					description: t("settings.mirror.description", { defaultValue: "Mirrors the camera view horizontally." }),
 				},
 			]
 		},
 		{
 			type: "group",
-			label: t("General"),
+			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("Start enabled"),
+					label: t("settings.startEnabled.label", { defaultValue: "Start enabled" }),
 					className: "tracky-mouse-start-enabled",
 					key: "startEnabled",
 					afterInitialLoad: () => { // TODO: does this hook make sense? right now it's the only usage. could this code not just be called later?
@@ -2000,10 +2098,10 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 					},
 					type: "checkbox",
 					default: false,
-					description: t("If enabled, Tracky Mouse will start controlling the cursor as soon as it's launched."),
-					// description: t("Makes Tracky Mouse active when launched. Otherwise, you can start it manually when you're ready."),
-					// description: t("Makes Tracky Mouse active as soon as it's launched."),
-					// description: t("Automatically starts Tracky Mouse as soon as it's run."),
+					description: t("settings.startEnabled.description", { defaultValue: "If enabled, Tracky Mouse will start controlling the cursor as soon as it's launched." }),
+					// description: t("settings.startEnabled.description.alt1", { defaultValue: "Makes Tracky Mouse active when launched. Otherwise, you can start it manually when you're ready." }),
+					// description: t("settings.startEnabled.description.alt2", { defaultValue: "Makes Tracky Mouse active as soon as it's launched." }),
+					// description: t("settings.startEnabled.description.alt3", { defaultValue: "Automatically starts Tracky Mouse as soon as it's run." }),
 				},
 				{
 					// For "experimental" label:
@@ -2011,36 +2109,37 @@ 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("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",
 					default: false,
-					description: t("If enabled, you can start or stop mouse control by holding both your eyes shut for a few seconds."),
+					description: t("settings.closeEyesToToggle.description", { defaultValue: "If enabled, you can start or stop mouse control by holding both your eyes shut for a few seconds." }),
 				},
 				{
-					label: t("Run at login"),
+					label: t("settings.runAtLogin.label", { defaultValue: "Run at login" }),
 					className: "tracky-mouse-run-at-login",
 					key: "runAtLogin",
 					type: "checkbox",
 					default: false,
 					visible: () => isDesktopApp,
-					description: t("If enabled, Tracky Mouse will automatically start when you log into your computer."),
-					// description: t("Makes Tracky Mouse start automatically when you log into your computer."),
+					description: t("settings.runAtLogin.description", { defaultValue: "If enabled, Tracky Mouse will automatically start when you log into your computer." }),
+					// description: t("settings.runAtLogin.description.alt1", { defaultValue: "Makes Tracky Mouse start automatically when you log into your computer." }),
 				},
 				{
-					label: t("Check for updates"),
+					label: t("settings.checkForUpdates.label", { defaultValue: "Check for updates" }),
 					className: "tracky-mouse-check-for-updates",
 					key: "checkForUpdates",
 					type: "checkbox",
 					default: true,
 					visible: () => isDesktopApp,
-					description: t("If enabled, Tracky Mouse will automatically check for updates when it starts."),
-					// description: t("Notifies you of new versions of Tracky Mouse."),
-					// description: t("Notifies you when a new version of Tracky Mouse is available."),
+					description: t("settings.checkForUpdates.description", { defaultValue: "If enabled, Tracky Mouse will automatically check for updates when it starts." }),
+					// description: t("settings.checkForUpdates.description.alt1", { defaultValue: "Notifies you of new versions of Tracky Mouse." }),
+					// description: t("settings.checkForUpdates.description.alt2", { defaultValue: "Notifies you when a new version of Tracky Mouse is available." }),
 				},
 				{
-					label: t("Language"),
+					label: t("settings.language.label", { defaultValue: "Language" }),
 					className: "tracky-mouse-language",
 					key: "language",
 					type: "dropdown",
@@ -2058,8 +2157,8 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 						}
 						reinit();
 					},
-					description: t("Select the language for the Tracky Mouse interface."),
-					// description: t("Changes the language Tracky Mouse is displayed in."),
+					description: t("settings.language.description", { defaultValue: "Select the language for the Tracky Mouse interface." }),
+					// description: t("settings.language.description.alt1", { defaultValue: "Changes the language Tracky Mouse is displayed in." }),
 				},
 			],
 		},
@@ -2181,7 +2280,7 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 				</select>
 			`;
 			if (setting.options.some(option => option.description)) {
-				setting.description += t("\n\nOptions:\n") + setting.options.map(option => `• ${option.label}${option.description ? `: ${option.description}` : ''}`).join("\n");
+				setting.description += "\n\n" + t("settings.dropdownDescriptionOptionsListHeading", { defaultValue: "Options:" }) + "\n" + setting.options.map(option => `• ${option.label}${option.description ? `: ${option.description}` : ''}`).join("\n");
 			}
 		} else if (setting.type === "button") {
 			rowEl.innerHTML = `
@@ -2284,26 +2383,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');
+	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';
@@ -2312,72 +2412,74 @@ 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;
 
 	// Other state
-	var paused = true;
-	var pointTracker;
+	let paused = true;
+	let pointTracker;
 
 	// Named lists of facemesh landmark indices
 	const MESH_ANNOTATIONS = {
@@ -2489,12 +2591,15 @@ 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) {
 			func();
 		}
 
+		// Unstable hook
+		handleSettingsUpdate?.(settings);
 	}
 	const formatVersion = 1;
 	const formatName = "tracky-mouse-settings";
@@ -2523,25 +2628,49 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 				console.error(e);
 			}
 		}
+		// Unstable hook
+		handleSettingsUpdate?.(options);
 	};
 	const loadOptions = async (initialLoad = false) => {
+		// Desktop app: start from any saved settings in the main process,
+		// then, on first load, push the renderer's canonical defaults back
+		// so the main process has the same effective settings (and can
+		// correctly drive features like dwell clicking on first run).
+		// Web demo: similarly needs canonical defaults pushed to
+		// correctly enable dwell clicking on first run,
+		// now that it supports multiple clicking modes.
+		// General API usage: does not yet support multiple clicking modes
+		// (there's a lot of glue code in the demo)
+		// but we only call handleSettingsUpdate if it exists.
+		let stored;
 		if (window.electronAPI) {
-			// Desktop app: start from any saved settings in the main process,
-			// then, on first load, push the renderer's canonical defaults back
-			// so the main process has the same effective settings (and can
-			// correctly drive features like dwell clicking on first run).
-			const stored = await window.electronAPI.getOptions();
-			deserializeSettings(stored, initialLoad);
-			if (initialLoad && (!stored || !stored.globalSettings || Object.keys(stored.globalSettings).length === 0)) {
-				setOptions(serializeSettings());
-			}
+			stored = await window.electronAPI.getOptions();
 		} else {
 			try {
 				if (localStorage.getItem("tracky-mouse-settings")) {
-					deserializeSettings(JSON.parse(localStorage.getItem("tracky-mouse-settings")), initialLoad);
+					stored = JSON.parse(localStorage.getItem("tracky-mouse-settings"));
 				}
 			} catch (e) {
 				console.error(e);
+				return;
+			}
+		}
+		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,
+			// but do we want to save to localStorage initially? Maybe not.
+			if (window.electronAPI) {
+				setOptions(serializeSettings()); // (includes handleSettingsUpdate)
+			} else {
+				handleSettingsUpdate?.(serializeSettings());
 			}
 		}
 	};
@@ -2592,14 +2721,14 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 
 				const defaultOption = document.createElement("option");
 				defaultOption.value = "";
-				defaultOption.text = t("Default");
+				defaultOption.text = t("settings.cameraSource.defaultCamera", { defaultValue: "Default" });
 				cameraSelect.appendChild(defaultOption);
 
 				let matchingDeviceId = "";
 				for (const device of videoDevices) {
 					const option = document.createElement('option');
 					option.value = device.deviceId;
-					option.text = device.label || t("Camera %0").replace("%0", cameraSelect.length);
+					option.text = device.label || t("settings.cameraSource.numberedCamera", { defaultValue: "Camera %0" }).replace("%0", cameraSelect.length);
 					cameraSelect.appendChild(option);
 					if (device.deviceId === s.cameraDeviceId) {
 						matchingDeviceId = device.deviceId;
@@ -2617,7 +2746,7 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 					const option = document.createElement("option");
 					option.value = s.cameraDeviceId;
 					const knownInfo = knownCameras[s.cameraDeviceId];
-					option.text = knownInfo ? `${knownInfo.name} (${t("Unavailable")})` : t("Unavailable camera");
+					option.text = knownInfo ? `${knownInfo.name} (${t("settings.cameraSource.unavailableCameraAdjective", { defaultValue: "Unavailable" })})` : t("settings.cameraSource.unavailableCamera", { defaultValue: "Unavailable camera" });
 					cameraSelect.appendChild(option);
 					cameraSelect.value = s.cameraDeviceId;
 				} else {
@@ -2647,9 +2776,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) {
@@ -2675,10 +2804,11 @@ 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;
 	useCameraButton.onclick = TrackyMouse.useCamera = async (optionsOrEvent = {}) => {
 		// Phases:
 		// 1. "tryPreferredCamera"
@@ -2803,7 +2933,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("No camera found. Please make sure you have a camera connected and enabled.");
+				errorMessage.textContent = 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
@@ -2811,7 +2941,7 @@ 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("Webcam is already in use. Please make sure you have no other programs using the camera.");
+				errorMessage.textContent = 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.
@@ -2819,7 +2949,7 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 				// 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("Please make sure no other programs are using the camera and try again.");
+				errorMessage.textContent = 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.";
@@ -2837,25 +2967,32 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 					// 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("The previously selected camera is not available. Try selecting \"Default\" for Video > Camera source, and then select a specific camera if you need to.");
+					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." });
 					// 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("Webcam does not support the required resolution. Please change your settings.");
+					errorMessage.textContent = 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("Permission denied. Please enable access to the camera.");
+				errorMessage.textContent = t("video.errors.permissionDenied", { defaultValue: "Permission denied. Please enable access to the camera." });
 			} else if (error.name == "TypeError") {
 				// empty constraints object
-				errorMessage.textContent = `${t("Something went wrong accessing the camera.")} (${error.name}: ${error.message})`;
+				errorMessage.textContent = `${t("video.errors.accessFailed", { defaultValue: "Something went wrong accessing the camera." })} (${error.name}: ${error.message})`;
 			} else {
 				// other errors
-				errorMessage.textContent = `${t("Something went wrong accessing the camera. Please try again.")} (${error.name}: ${error.message})`;
+				errorMessage.textContent = `${t("video.errors.accessFailedRetry", { defaultValue: "Something went wrong accessing the camera. Please try again." })} (${error.name}: ${error.message})`;
 			}
-			errorMessage.textContent = `${t("⚠️ ")}${errorMessage.textContent}`;
+			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 = () => {
@@ -2955,7 +3092,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;
@@ -2964,8 +3101,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;
@@ -3013,10 +3150,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);
@@ -3030,9 +3167,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]
 				// );
@@ -3050,11 +3187,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;
@@ -3091,9 +3228,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]
 			// );
@@ -3130,6 +3267,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
@@ -3144,6 +3282,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;
 		}
@@ -3279,39 +3424,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
@@ -3493,16 +3676,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);
 							}
 						}
 
@@ -3562,15 +3748,43 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 							}
 						}
 
-						// TODO: implement these clicking modes for the web library version
-						// and unhide the "Clicking mode" setting in the UI
-						// https://github.com/1j01/tracky-mouse/issues/72
 						const buttonNames = ["left", "middle", "right"];
 						for (let buttonIndex = 0; buttonIndex < 3; buttonIndex++) {
-							if ((clickButton === buttonIndex) !== buttonStates[buttonNames[buttonIndex]]) {
-								window.electronAPI?.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.
@@ -3589,13 +3803,11 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 			pointTracker.update(imageData);
 		}
 
-		if (window.electronAPI) {
-			window.electronAPI.updateInputFeedback({
-				headNotFound: !face && !facemeshPrediction,
-				blinkInfo,
-				mouthInfo,
-			});
-		}
+		updateInputFeedback?.({
+			headNotFound: !face && !facemeshPrediction,
+			blinkInfo,
+			mouthInfo,
+		});
 
 		if (facemeshPrediction) {
 			ctx.fillStyle = "red";
@@ -3640,17 +3852,20 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 					const textYStart = -10;
 
 
-					const pitchText = t("Pitch: ") + `${(headTilt.pitch * 180 / Math.PI).toFixed(1)}°`;
-					const yawText = t("Yaw:   ") + `${(headTilt.yaw * 180 / Math.PI).toFixed(1)}°`;
-					const rollText = t("Roll:  ") + `${(headTilt.roll * 180 / Math.PI).toFixed(1)}°`;
-
-					const boxWidth = Math.max(
-						ctx.measureText(pitchText).width,
-						ctx.measureText(yawText).width,
-						ctx.measureText(rollText).width
-					);
-					const boxHeight = textLineHeight * 3;
-					const padding = 10;
+					const headTiltRows = [
+						{ label: t("debug.headTilt.pitch", { defaultValue: "Pitch:" }), value: `${(headTilt.pitch * 180 / Math.PI).toFixed(1)}°` },
+						{ label: t("debug.headTilt.yaw", { defaultValue: "Yaw:" }), value: `${(headTilt.yaw * 180 / Math.PI).toFixed(1)}°` },
+						{ label: t("debug.headTilt.roll", { defaultValue: "Roll:" }), value: `${(headTilt.roll * 180 / Math.PI).toFixed(1)}°` },
+					];
+					const labelWidths = headTiltRows.map(row => ctx.measureText(row.label).width);
+					const maxLabelWidth = Math.max(...labelWidths);
+					const valueColumnTemplate = "-180.0°";
+					const maxValueWidth = ctx.measureText(valueColumnTemplate).width;
+					const labelToValueGap = 10;
+					const boxPadding = 10;
+					const boxWidth = boxPadding * 2 + maxLabelWidth + labelToValueGap + maxValueWidth;
+					const boxHeight = textLineHeight * headTiltRows.length;
+					const valueColumnRightOffset = boxPadding + maxLabelWidth + labelToValueGap + maxValueWidth;
 
 					// Calculate screen coordinates for the text box
 					let screenX = s.mirror ? canvas.width - cx : cx;
@@ -3661,7 +3876,7 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 					let textScreenY = screenY + textYStart;
 
 					// Clamp to canvas bounds
-					textScreenX = Math.max(padding, Math.min(canvas.width - boxWidth - padding, textScreenX));
+					textScreenX = Math.max(boxPadding, Math.min(canvas.width - boxWidth - boxPadding, textScreenX));
 					textScreenY = Math.max(textLineHeight, Math.min(canvas.height - boxHeight + textLineHeight, textScreenY));
 
 					ctx.save();
@@ -3675,12 +3890,18 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 					const dx = textScreenX - screenNoseX;
 					const dy = textScreenY - screenNoseY;
 
-					ctx.strokeText(pitchText, dx, dy);
-					ctx.fillText(pitchText, dx, dy);
-					ctx.strokeText(yawText, dx, dy + textLineHeight);
-					ctx.fillText(yawText, dx, dy + textLineHeight);
-					ctx.strokeText(rollText, dx, dy + textLineHeight * 2);
-					ctx.fillText(rollText, dx, dy + textLineHeight * 2);
+					for (let i = 0; i < headTiltRows.length; i++) {
+						const row = headTiltRows[i];
+						const baselineY = dy + textLineHeight * (i + 1);
+						const labelX = dx + boxPadding;
+						const valueTextWidth = ctx.measureText(row.value).width;
+						const valueRightX = dx + valueColumnRightOffset;
+						const valueX = valueRightX - valueTextWidth;
+						ctx.strokeText(row.label, labelX, baselineY);
+						ctx.fillText(row.label, labelX, baselineY);
+						ctx.strokeText(row.value, valueX, baselineY);
+						ctx.fillText(row.value, valueX, baselineY);
+					}
 
 					ctx.restore();
 
@@ -3836,14 +4057,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]
 						);
@@ -3871,18 +4092,18 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 			const screenWidth = window.electronAPI ? screen.width : innerWidth;
 			const screenHeight = window.electronAPI ? screen.height : innerHeight;
 
-			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 = [
@@ -4013,8 +4234,8 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 					pointerEl.style.display = "none";
 				} else {
 					pointerEl.style.display = "";
-					pointerEl.style.left = `${mouseX}px`;
-					pointerEl.style.top = `${mouseY}px`;
+					pointerEl.style.left = `${Math.floor(mouseX)}px`;
+					pointerEl.style.top = `${Math.floor(mouseY)}px`;
 				}
 				if (TrackyMouse.onPointerMove) {
 					TrackyMouse.onPointerMove(mouseX, mouseY);
@@ -4030,9 +4251,9 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 			ctx.lineWidth = 3;
 			ctx.font = "20px sans-serif";
 			ctx.beginPath();
-			const text3 = t("Face convergence score: ") + ((useFacemesh && facemeshPrediction) ? t("N/A") : faceConvergence.toFixed(4));
-			const text1 = t("Face tracking score: ") + ((useFacemesh && facemeshPrediction) ? facemeshPrediction.faceInViewConfidence : faceScore).toFixed(4);
-			const text2 = t("Points based on score: ") + ((useFacemesh && facemeshPrediction) ? pointsBasedOnFaceInViewConfidence : pointsBasedOnFaceScore).toFixed(4);
+			const text3 = `${t("debug.faceConvergenceScore", { defaultValue: "Face convergence score:" })} ${((useFacemesh && facemeshPrediction) ? t("common.notApplicable", { defaultValue: "N/A" }) : faceConvergence.toFixed(4))}`;
+			const text1 = `${t("debug.faceTrackingScore", { defaultValue: "Face tracking score:" })} ${((useFacemesh && facemeshPrediction) ? facemeshPrediction.faceInViewConfidence : faceScore).toFixed(4)}`;
+			const text2 = `${t("debug.pointsBasedOnScore", { defaultValue: "Points based on score:" })} ${((useFacemesh && facemeshPrediction) ? pointsBasedOnFaceInViewConfidence : pointsBasedOnFaceScore).toFixed(4)}`;
 			ctx.strokeText(text1, 50, 50);
 			ctx.fillText(text1, 50, 50);
 			ctx.strokeText(text2, 50, 70);
@@ -4055,7 +4276,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;
@@ -4068,14 +4289,26 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 		TrackyMouse.useDemoFootage();
 	} else if (window.electronAPI) {
 		TrackyMouse.useCamera();
+	} else {
+		// Passively querying the camera permission isn't supported in all browsers,
+		// hence some of the complex logic in useCamera, but when it is,
+		// we can connect to the camera right away if the permission is already granted.
+		// This speeds up the development cycle, at the very least.
+		navigator.permissions?.query?.({ name: "camera" }).then((status) => {
+			if (status.state === "granted") {
+				TrackyMouse.useCamera();
+			}
+		}, (error) => {
+			console.log("Error querying permissions:", error);
+		});
 	}
 
 	const updateStartStopButton = () => {
 		if (paused) {
-			startStopButton.textContent = t("Start");
+			startStopButton.textContent = t("ui.startStopButton.start", { defaultValue: "Start" });
 			startStopButton.setAttribute("aria-pressed", "false");
 		} else {
-			startStopButton.textContent = t("Stop");
+			startStopButton.textContent = t("ui.startStopButton.stop", { defaultValue: "Stop" });
 			startStopButton.setAttribute("aria-pressed", "true");
 		}
 	};
@@ -4085,9 +4318,7 @@ You may want to turn this off if you're drawing on a canvas, or increase it if y
 			pointerEl.style.display = "none";
 		}
 		updateStartStopButton();
-		if (window.electronAPI) {
-			window.electronAPI.notifyToggleState(!paused);
-		}
+		notifyToggleState?.(!paused);
 	};
 	const handleShortcut = (shortcutType) => {
 		if (shortcutType === "toggle-tracking") {
@@ -4229,15 +4460,17 @@ TrackyMouse.init = function (div, opts = {}) {
 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="../images/manual-takeback.svg" alt="hand reaching for mouse" width="128" height="128">
+				<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="../images/head-not-found.svg" alt="head not found" width="128" height="128">
+				<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>
 	`;
 	const fragment = document.createRange().createContextualFragment(template);
 	document.body.appendChild(fragment);
@@ -4245,8 +4478,11 @@ TrackyMouse.initScreenOverlay = () => {
 	const message = document.getElementById("tracky-mouse-screen-overlay-message");
 	message.dir = "auto";
 
+	const hideNearCursorEls = document.querySelectorAll(".tracky-mouse-hide-near-cursor");
+
 	const inputFeedbackCanvas = document.createElement("canvas");
-	inputFeedbackCanvas.style.position = "absolute";
+	inputFeedbackCanvas.style.position = "fixed";
+	inputFeedbackCanvas.style.zIndex = "899990"; // just below .tracky-mouse-pointer
 	inputFeedbackCanvas.style.top = "0";
 	inputFeedbackCanvas.style.left = "0";
 	inputFeedbackCanvas.style.pointerEvents = "none";
@@ -4282,10 +4518,11 @@ TrackyMouse.initScreenOverlay = () => {
 		// inputFeedbackCanvas.style.transform = `translate(${x - inputFeedbackCanvas.width / 2}px, ${y - inputFeedbackCanvas.height / 2}px)`;
 		// inputFeedbackCanvas.style.transform = `translate(${x}px, ${y}px)`;
 		inputFeedbackCanvas.style.transform = `translate(${Math.min(x, window.innerWidth - inputFeedbackCanvas.width)}px, ${Math.min(y, window.innerHeight - inputFeedbackCanvas.height)}px)`;
+
 	}
 
 	function update(data) {
-		const { messageText, isEnabled, isManualTakeback, inputFeedback, bottomOffset } = data;
+		const { messageText, isEnabled, isManualTakeback, inputFeedback, bottomOffset, systemMousePosition } = data;
 
 		message.style.bottom = `${bottomOffset}px`;
 
@@ -4294,21 +4531,31 @@ TrackyMouse.initScreenOverlay = () => {
 		// - bad lighting conditions
 		// see: https://github.com/1j01/tracky-mouse/issues/26
 
-		document.body.classList.toggle("tracky-mouse-manual-takeback", isManualTakeback);
-		document.body.classList.toggle("tracky-mouse-head-not-found", inputFeedback.headNotFound);
+		document.body.classList.toggle("tracky-mouse-manual-takeback", isManualTakeback ?? false);
+		document.body.classList.toggle("tracky-mouse-head-not-found", inputFeedback.headNotFound ?? false);
 
 		message.innerText = messageText;
 
 		if (!isEnabled && !isManualTakeback) {
 			// Fade out the message after a little while so it doesn't get in the way.
 			// TODO: make sure animation isn't interrupted by inputFeedback updates.
-			message.style.animation = "tracky-mouse-screen-overlay-message-fade-out 2s ease-in-out forwards 10s";
+			message.style.animation = "tracky-mouse-fade-out 2s ease-in-out forwards 10s";
 		} else {
 			message.style.animation = "";
 			message.style.opacity = "1";
 		}
 
 		drawInputFeedback(data);
+
+		if (systemMousePosition) {
+			const { x, y } = systemMousePosition;
+			// TODO: optimize CSS parsing by using CSS variables?
+			const maskImage = `radial-gradient(circle at ${x}px ${y}px, transparent 0, transparent 50px, rgba(0, 0, 0, 0.85) 140px, rgba(0, 0, 0, 1) 200px, rgba(0, 0, 0, 1) 100%)`;
+			for (const el of hideNearCursorEls) {
+				el.style.webkitMaskImage = maskImage;
+				el.style.maskImage = maskImage;
+			}
+		}
 	}
 
 	return {