Type-Safe DOM Query Utilities

Problem/Feature Description

A front-end team is building a component testing harness that wraps native DOM APIs to add safety guarantees (throwing instead of returning null, logging query failures, etc.). They've run into a frustrating problem: their wrapper functions lose the precise element types that the native APIs provide. When a developer calls the native document.querySelector("input"), TypeScript correctly infers HTMLInputElement | null. But after wrapping it in their helper, the return type degrades to Element | null, breaking IntelliSense and forcing explicit casts throughout their test suite.

The team wants wrapper functions that are as type-smart as the originals — calling the wrapper with "button" should give back HTMLButtonElement, calling it with "canvas" should give back HTMLCanvasElement, and calling it with an arbitrary CSS selector string should fall back to Element. They also want the implementation to be understandable enough that junior engineers on the team can learn from it.

Output Specification

Produce the following files:

• dom-utils.ts — the wrapper utilities implementing type-safe versions of at least querySelector and querySelectorAll
• type-tests.ts — compile-time tests verifying specific element types are inferred and that invalid usages produce errors
• EXPLANATION.md — an explanation of the approach, including a before/after comparison showing the return type degradation problem and the solution, and a discussion of the resolution mechanism and why the ordering of signatures matters