Add complete type hints and enable mypy static checking

[carpalsgrabby]

Summary

The script has partial type hints, but not complete coverage. Adding full annotations increases readability and catching type errors automatically.

Proposal

• Add type hints to all functions.
• Add a mypy.ini file with basic configuration.
• (Optional) Add GitHub Action workflow to run mypy on PRs.

Benefit

Improves maintainability and avoids subtle type bugs.