feat(toolbox/domtargeter): adding navigationRetarget for SPA support

Author: korgon

packages/snap-preact/src/Instantiators/RecommendationInstantiator.tsx

@@ -133,12 +133,14 @@ export class RecommendationInstantiator {
 					}, script[type="searchspring/recommend"][profile="email"]`,
 					autoRetarget: true,
 					clickRetarget: true,
+					navigationRetarget: true,
 					emptyTarget: false,
 				},
 				{
 					selector: 'script[type="searchspring/recommendations"]',
 					autoRetarget: true,
 					clickRetarget: true,
+					navigationRetarget: true,
 					emptyTarget: false,
 				},
 			],
@@ -318,7 +320,10 @@ export class RecommendationInstantiator {
 			const targeters = Object.values(controller.targeters);
 
 			const hasConnectedTarget = targeters.some((targeter) =>
-				targeter.getTargetedElems().some((elem) => elem.isConnected && elem.getAttribute('ss-controller-id'))
+				targeter.getTargetedElems().some((elem) => {
+					const attr = elem.isConnected && elem.getAttribute('ss-controller-id');
+					return attr === id || attr === '...';
+				})
 			);
 			if (!hasConnectedTarget) {
 				Object.keys(controller.targeters).forEach((targeterId) => controller.targeters[targeterId].releaseTargets());

packages/snap-toolbox/src/DomTargeter/DomTargeter.test.ts

@@ -1383,4 +1383,131 @@ describe('DomTargeter', () => {
 			expect(receivedTargeter).toBe(targeter);
 		});
 	});
+
+	describe('destroy', () => {
+		it('releases all tracked elements', () => {
+			const dom = createDocument(`
+				<div id="content">
+					<div class="target-a"></div>
+					<div class="target-b"></div>
+				</div>
+			`);
+
+			const document = dom.window.document;
+			const targeter = new DomTargeter([{ selector: '.target-a' }, { selector: '.target-b' }], () => {}, document);
+
+			expect(targeter.getTargetedElems().length).toBe(2);
+
+			targeter.destroy();
+			expect(targeter.getTargetedElems().length).toBe(0);
+		});
+
+		it('stops autoRetarget polling after destroy', async () => {
+			const dom = createDocument(`
+				<div id="content"></div>
+			`);
+
+			const document = dom.window.document;
+			const onTarget = jest.fn();
+
+			const targeter = new DomTargeter([{ selector: '.dynamic', autoRetarget: true }], onTarget, document);
+
+			expect(onTarget).toHaveBeenCalledTimes(0);
+
+			targeter.destroy();
+
+			// add the element after destroy
+			const elem = document.createElement('div');
+			elem.className = 'dynamic';
+			document.getElementById('content')!.appendChild(elem);
+
+			await wait(500);
+
+			// should not have been targeted because polling was stopped
+			expect(onTarget).toHaveBeenCalledTimes(0);
+		});
+
+		it('removes click listeners after destroy', async () => {
+			const dom = createDocument(`
+				<div id="content"></div>
+			`);
+
+			const document = dom.window.document;
+			const onTarget = jest.fn();
+
+			const targeter = new DomTargeter([{ selector: '.dynamic', clickRetarget: true }], onTarget, document);
+
+			targeter.destroy();
+
+			// add element and click
+			const elem = document.createElement('div');
+			elem.className = 'dynamic';
+			document.getElementById('content')!.appendChild(elem);
+			document.dispatchEvent(new dom.window.MouseEvent('click', { bubbles: true }));
+
+			await wait(300);
+
+			expect(onTarget).toHaveBeenCalledTimes(0);
+		});
+
+		it('stops autoRetarget and listeners after destroy', async () => {
+			const dom = createDocument(`
+				<div id="content"></div>
+			`);
+
+			const document = dom.window.document;
+			const onTarget = jest.fn();
+
+			const targeter = new DomTargeter([{ selector: '.dynamic', autoRetarget: true }], onTarget, document);
+
+			targeter.destroy();
+
+			// add element after destroy - listeners should be cleaned up
+			const elem = document.createElement('div');
+			elem.className = 'dynamic';
+			document.getElementById('content')!.appendChild(elem);
+
+			await wait(300);
+
+			expect(onTarget).toHaveBeenCalledTimes(0);
+		});
+
+		it('frees elements for other targeters after destroy', () => {
+			const dom = createDocument(`
+				<div id="content">
+					<div class="target"></div>
+				</div>
+			`);
+
+			const document = dom.window.document;
+
+			const targeterA = new DomTargeter([{ selector: '.target' }], () => {}, document);
+
+			const onTargetB = jest.fn();
+			new DomTargeter([{ selector: '.target' }], onTargetB, document);
+			expect(onTargetB).toHaveBeenCalledTimes(0);
+
+			targeterA.destroy();
+
+			const onTargetC = jest.fn();
+			new DomTargeter([{ selector: '.target' }], onTargetC, document);
+			expect(onTargetC).toHaveBeenCalledTimes(1);
+		});
+
+		it('is safe to call multiple times', () => {
+			const dom = createDocument(`
+				<div id="content">
+					<div class="target"></div>
+				</div>
+			`);
+
+			const document = dom.window.document;
+			const targeter = new DomTargeter([{ selector: '.target' }], () => {}, document);
+
+			expect(() => {
+				targeter.destroy();
+				targeter.destroy();
+			}).not.toThrow();
+		});
+	});
 });

packages/snap-toolbox/src/DomTargeter/DomTargeter.ts

@@ -9,22 +9,33 @@ export type Target = {
 	autoRetarget?: boolean;
 	unsetTargetMinHeight?: boolean;
 	clickRetarget?: boolean | string;
+	navigationRetarget?: boolean;
 	[any: string]: unknown;
 };
 
 export type OnTarget = (target: Target, elem: Element, originalElem?: Element, targeter?: DomTargeter) => void | Promise<void>;
 
 let globallyTargetedElems: Array<Element> = [];
+
 export class DomTargeter {
 	private targets: Array<Target> = [];
 	private onTarget: OnTarget;
 	private document: Document;
 	private styleBlockRefs: Record<string, Node> = {};
 	private targetedElems: Array<Element> = [];
+	private abortController?: AbortController;
 
 	constructor(targets: Array<Target>, onTarget: OnTarget, document?: Document) {
 		this.document = document || window.document;
 
+		// use the document's own window AbortController to ensure realm compatibility (e.g., JSDOM)
+		// and gracefully handle environments where AbortController is not available (e.g., IE11)
+		try {
+			this.abortController = new ((this.document.defaultView || window) as any).AbortController();
+		} catch (e) {
+			// AbortController not available - listeners won't auto-cleanup on destroy()
+		}
+
 		this.targets = targets;
 
 		this.onTarget = onTarget;
@@ -34,6 +45,9 @@ export class DomTargeter {
 		this.targets.forEach((target) => {
 			let timeoutTime = 100;
 			const checker = () => {
+				if (this.abortController?.signal.aborted) {
+					return;
+				}
 				// lets not just keep trying forever - this waits roughly 12 seconds before giving up.
 				if (timeoutTime < 2000) {
 					// increase the time till next check
@@ -57,13 +71,33 @@ export class DomTargeter {
 				}
 
 				clickElems.map((elem) => {
-					elem.addEventListener('click', () => {
-						timeoutTime = 100;
-						checker();
-					});
+					elem.addEventListener(
+						'click',
+						() => {
+							timeoutTime = 100;
+							setTimeout(checker); // allow the click to complete
+						},
+						{ capture: true, signal: this.abortController!.signal }
+					);
 				});
 			}
 
+			// listen for SPA navigations via the Navigation API to restart retargeting
+			if (target.navigationRetarget) {
+				try {
+					(this.document.defaultView as any)?.navigation?.addEventListener(
+						'navigate',
+						() => {
+							timeoutTime = 100;
+							checker();
+						},
+						{ signal: this.abortController!.signal }
+					);
+				} catch (e) {
+					// Navigation API not available
+				}
+			}
+
 			if (target.autoRetarget) {
 				// do initial retargeting check
 				checker();
@@ -72,10 +106,14 @@ export class DomTargeter {
 				target.hideTarget && this.unhideTarget(target.selector);
 			} else {
 				// attempt retarget on DOMContentLoaded
-				this.document.addEventListener('DOMContentLoaded', () => {
-					this.retarget();
-					target.hideTarget && this.unhideTarget(target.selector);
-				});
+				this.document.addEventListener(
+					'DOMContentLoaded',
+					() => {
+						this.retarget();
+						target.hideTarget && this.unhideTarget(target.selector);
+					},
+					{ signal: this.abortController!.signal }
+				);
 			}
 		});
 	}
@@ -89,7 +127,7 @@ export class DomTargeter {
 		return [...this.targetedElems];
 	}
 
-	releaseTargets(elems?: Element[]): void {
+	releaseTargets(elems?: ReadonlyArray<Element>): void {
 		const toRelease = elems || this.targetedElems;
 		toRelease.forEach((elem) => {
 			const idx = globallyTargetedElems.indexOf(elem);
@@ -104,6 +142,12 @@ export class DomTargeter {
 		}
 	}
 
+	destroy(): void {
+		this.abortController?.abort();
+		this.releaseTargets();
+		Object.keys(this.styleBlockRefs).forEach((selector) => this.unhideTarget(selector));
+	}
+
 	retarget(): void {
 		// prune references to elements no longer in the DOM
 		globallyTargetedElems = globallyTargetedElems.filter((elem) => elem.isConnected);

packages/snap-toolbox/src/DomTargeter/README.md

@@ -202,6 +202,22 @@ Default: `false`
 }
 ```
 
+Note: Click listeners use the capture phase to ensure they fire even when frameworks call `stopPropagation()` on click events.
+
+### `navigationRetarget`
+When `true`, listens for SPA navigation events using the [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API) (`navigate` event). When a navigation occurs, the retargeting checker is restarted. This is useful for single-page applications that use `pushState` or `replaceState` for client-side routing.
+
+Falls back gracefully in browsers that do not support the Navigation API.
+
+Default: `false`
+
+```js
+{
+	selector: '#content',
+	navigationRetarget: true
+}
+```
+
 ### `unsetTargetMinHeight`
 When `true`, removes any `min-height` CSS property from the target element after successful targeting. This is useful for removing placeholder styles.
 
@@ -259,6 +275,31 @@ Returns the array of targets specified during construction.
 const targets = contentTarget.getTargets();
 ```
 
+### `getTargetedElems` method
+Returns a read-only array of elements currently tracked by this DomTargeter instance. Automatically prunes disconnected elements before returning.
+
+```js
+const elems = contentTarget.getTargetedElems();
+```
+
+### `releaseTargets` method
+Releases elements from both instance and global tracking, allowing them to be retargeted by other DomTargeter instances. Can release all tracked elements or a specific subset.
+
+```js
+// release all tracked elements
+contentTarget.releaseTargets();
+
+// release specific elements
+contentTarget.releaseTargets([elem1, elem2]);
+```
+
+### `destroy` method
+Fully cleans up the DomTargeter instance. Aborts all event listeners (click, navigation, DOMContentLoaded), releases all tracked elements, and removes any style blocks created by `hideTarget`.
+
+```js
+contentTarget.destroy();
+```
+
 ## Complete Example
 
 ```js
@@ -272,6 +313,8 @@ const targeter = new DomTargeter(
 			component: <SearchResults />,
 			hideTarget: true,
 			autoRetarget: true,
+			clickRetarget: true,
+			navigationRetarget: true,
 			unsetTargetMinHeight: true
 		},
 		{