Validate internal selectors via TypeScript

global.d.ts

@@ -1,4 +1,5 @@
 /* eslint-disable @typescript-eslint/consistent-type-definitions -- Module augmentation */
+/// <reference path="./node_modules/typed-query-selector/strict.d.ts" />
 
 // Broaden types because testing against `"undefined"` is fine for our regexes
 interface RegExp {

index.ts

@@ -1,8 +1,10 @@
 import reservedNames from 'github-reserved-names/reserved-names.json' with {type: 'json'};
 import {addTests} from './collector.ts';
 
-const $ = <E extends Element>(selector: string) => document.querySelector<E>(selector);
-const exists = (selector: string) => Boolean($(selector));
+// Selector helpers with typed-query-selector validation.
+// The generic parameter allows type override when selector inference isn't specific enough (e.g., attribute-only selectors)
+const $ = <E extends Element = Element>(selector: string) => document.querySelector<E>(selector);
+const exists = (selector: string): boolean => Boolean(document.querySelector(selector));
 
 const combinedTestOnly = ['combinedTestOnly']; // To be used only to skip tests of combined functions, i.e. isPageA() || isPageB()
 

package.json

@@ -56,6 +56,7 @@
 		"svelte-check": "^4.3.5",
 		"ts-morph": "^27.0.2",
 		"tsx": "^4.21.0",
+		"typed-query-selector": "^2.12.0",
 		"typescript": "5.9.3",
 		"vite": "^7.3.1",
 		"vitest": "^4.0.17",