tracky-mouse 1.1.0 → 1.2.0

package/README.md

@@ -102,13 +102,16 @@ TrackyMouse.loadDependencies().then(function() {
 
 Set this to the path to the folder where you installed tracky-mouse, without a trailing slash.
 
-### `TrackyMouse.loadDependencies()`
+### `TrackyMouse.loadDependencies([options])`
 
 This loads dependencies needed *for head tracking*. (It is not needed for dwell clicking.)
 
+If you pass an options object, it can have the following properties:
+- `statsJs` (optional): a boolean, whether to load stats.js for performance monitoring. Default is `false`.
+
 Returns a promise that resolves when the dependencies are loaded.
 
-### `TrackyMouse.init([element])`
+### `TrackyMouse.init([element, options])`
 
 `TrackyMouse.init` initializes the library *for head tracking*. (It is not needed for dwell clicking.)
 
@@ -118,6 +121,13 @@ or using, and modifying, and existing element.
 If you pass an element, it should be an empty `<div>` element.
 It will add `class="tracky-mouse-ui"` directly to the element if it doesn't already have it.
 
+If you pass an options object, it can have the following properties:
+- `statsJs` (optional): a boolean, whether to include the stats.js performance monitor. Default is `false`.
+
+Returns an object with a `dispose` method that you can call to remove the UI and clean up the web worker and camera stream.
+
+*(Search keywords: disposal, destroy, teardown, cleanup, clean-up, clean up, deinitialize, de-initialize, remove, stop, end)* - see return value
+
 ### `TrackyMouse.useCamera()`
 
 This requests permission to use the camera, and starts the camera stream.
@@ -154,8 +164,8 @@ Arguments:
 
 Returns an object with the following properties:
 - `paused`: a getter/setter for whether dwell clicking is paused. Use this to implement a pause/resume button, in conjunction with `config.dwellClickEvenIfPaused`.
-- (that's all for now)
-
+- `dispose`: a method to clean up the dwell clicker.  
+  *(Search keywords: disposal, destroy, teardown, cleanup, clean-up, clean up, deinitialize, de-initialize, remove, stop, end)*
 
 Example:
 ```javascript
@@ -248,7 +258,9 @@ const config = {
 	beforePointerDownDispatch: () => { window.pointers = []; },
 	afterReleaseDrag: () => { window.pointers = []; },
 };
-TrackyMouse.initDwellClicking(config);
+const dwellClicker = TrackyMouse.initDwellClicking(config);
+// dwellClicker.paused = !dwellClicker.paused; // toggle
+// dwellClicker.dispose(); // clean up
 
 // Source: https://stackoverflow.com/a/54492696/2624876
 function getCurrentRotation(el) {
@@ -269,6 +281,8 @@ function getCurrentRotation(el) {
 
 ### `TrackyMouse.cleanupDwellClicking()`
 
+**Deprecated**: instead call `dispose()` on the object returned from `initDwellClicking()`.
+
 This stops the dwell clicker.
 
 ## Changelog

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracky-mouse",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Add facial mouse accessibility to JavaScript applications",
   "license": "MIT",
   "author": {

package/tracky-mouse.js

@@ -3,7 +3,7 @@ const TrackyMouse = {
 	dependenciesRoot: "./tracky-mouse",
 };
 
-TrackyMouse.loadDependencies = function () {
+TrackyMouse.loadDependencies = function ({ statsJs = false } = {}) {
 	TrackyMouse.dependenciesRoot = TrackyMouse.dependenciesRoot.replace(/\/+$/, "");
 	const loadScript = src => {
 		return new Promise((resolve, reject) => {
@@ -25,8 +25,10 @@ TrackyMouse.loadDependencies = function () {
 	const scriptFiles = [
 		`${TrackyMouse.dependenciesRoot}/lib/no-eval.js`, // generated with eval-is-evil.html, this instruments clmtrackr.js so I don't need unsafe-eval in the CSP
 		`${TrackyMouse.dependenciesRoot}/lib/clmtrackr.js`,
-		`${TrackyMouse.dependenciesRoot}/lib/stats.js`,
 	];
+	if (statsJs) {
+		scriptFiles.push(`${TrackyMouse.dependenciesRoot}/lib/stats.js`);
+	}
 	// TODO: figure out how to preload worker-context dependencies that use `importScripts`.
 	// `<link rel="preload">` can be injected at runtime,
 	// which wouldn't make sense for the main thread's dependencies, since we're injecting all the scripts at once anyway,
@@ -46,7 +48,9 @@ const is_selector_valid = ((dummy_element) =>
 		return true;
 	})(document.createDocumentFragment());
 
-let clean_up_dwell_clicking = () => { };
+
+const dwell_clickers = [];
+
 const init_dwell_clicking = (config) => {
 	/*
 		Arguments:
@@ -525,7 +529,7 @@ const init_dwell_clicking = (config) => {
 	};
 	raf_id = requestAnimationFrame(animate);
 
-	clean_up_dwell_clicking = () => {
+	const dispose = () => {
 		cancelAnimationFrame(raf_id);
 		halo.remove();
 		dwell_indicator.remove();
@@ -536,7 +540,6 @@ const init_dwell_clicking = (config) => {
 		window.removeEventListener("blur", on_blur);
 		document.removeEventListener("mouseleave", on_mouse_leave_page);
 		document.removeEventListener("mouseenter", on_mouse_enter_page);
-		clean_up_dwell_clicking = () => { };
 	};
 
 	const dwellClicker = {
@@ -545,8 +548,10 @@ const init_dwell_clicking = (config) => {
 		},
 		set paused(value) {
 			paused = value;
-		}
+		},
+		dispose,
 	};
+	dwell_clickers.push(dwellClicker);
 	return dwellClicker;
 };
 
@@ -554,10 +559,12 @@ TrackyMouse.initDwellClicking = function (config) {
 	return init_dwell_clicking(config);
 };
 TrackyMouse.cleanupDwellClicking = function () {
-	clean_up_dwell_clicking();
+	for (const dwell_clicker of dwell_clickers) {
+		dwell_clicker.dispose();
+	}
 };
 
-TrackyMouse.init = function (div) {
+TrackyMouse.init = function (div, { statsJs = false } = {}) {
 
 	var uiContainer = div || document.createElement("div");
 	uiContainer.classList.add("tracky-mouse-ui");
@@ -706,7 +713,7 @@ TrackyMouse.init = function (div) {
 	// required to work in iOS 11 & up:
 	cameraVideo.setAttribute('playsinline', '');
 
-	if (typeof Stats !== 'undefined') {
+	if (statsJs) {
 		var stats = new Stats();
 		stats.domElement.style.position = 'absolute';
 		stats.domElement.style.top = '0px';
@@ -1834,13 +1841,60 @@ TrackyMouse.init = function (div) {
 	if (window.electronAPI) {
 		window.electronAPI.onShortcut(handleShortcut);
 	}
-	addEventListener("keydown", (event) => {
+	const handleKeydown = (event) => {
 		// Same shortcut as the global shortcut in the electron app
 		if (!event.ctrlKey && !event.metaKey && !event.altKey && !event.shiftKey && event.key === "F9") {
 			handleShortcut("toggle-tracking");
 		}
-	});
+	};
+	addEventListener("keydown", handleKeydown);
+
+	return {
+		dispose() {
+			// TODO: re-structure so that cleanup can succeed even if initialization fails
+			// OOP would help with this, by storing references in an object, but it doesn't necessarily
+			// need to be converted to a class, it could just be an object, with a try-finally used for returning the API with a `dispose` method.
+			// Wouldn't need to change the API that way.
+			// (Would also be easy to maintain backwards compatibility while switching to using a class,
+			// returning an instance of the class from `TrackyMouse.init` but deprecating it in favor of constructing the class.)
+
+			// clean up camera stream
+			if (cameraVideo.srcObject) {
+				for (const track of cameraVideo.srcObject.getTracks()) {
+					track.stop();
+				}
+			}
+			cameraVideo.srcObject = null; // probably pointless
 
+			// not sure this helps
+			reset();
+			// just in case there's any async code looking at whether it's paused
+			paused = true;
+
+			if (facemeshWorker) {
+				facemeshWorker.terminate();
+			}
+			if (clmTracker) {
+				// not sure this helps clean up any resources
+				clmTracker.reset();
+			}
+
+			pointerEl.remove();
+
+			stats?.domElement.remove(); // there is no dispose method but this may be all that it would need to do https://github.com/mrdoob/stats.js/pull/96
+
+			removeEventListener("keydown", handleKeydown);
+
+			// This is a little awkward, reversing the initialization based on a possibly-preexisting element
+			// Could save and restore innerHTML but that won't restore event listeners, references, etc.
+			// and may not even be desired if the HTML was placeholder text mentioning it not yet being initialized for example.
+			uiContainer.classList.remove("tracky-mouse-ui");
+			uiContainer.innerHTML = "";
+			if (!div) {
+				uiContainer.remove();
+			}
+		},
+	};
 };
 
 // CommonJS export is untested. Script tag usage recommended.