Code Refactoring — Extract and Simplify

Refactor this code following these principles:
1. Extract functions that do more than one thing into single-responsibility functions
2. Replace magic numbers and strings with named constants
3. Simplify nested conditionals (use early returns, guard clauses)
4. Extract repeated logic into shared utility functions
5. Use descriptive variable names that explain intent, not implementation
6. Replace imperative loops with declarative array methods where clearer
7. Add TypeScript types to any untyped parameters or returns
8. Remove dead code and unused imports
9. Preserve ALL existing behavior — this is refactoring, not feature work
10. Add brief comments only where the WHY is non-obvious

Do NOT:
- Change the public API/interface
- Add new dependencies
- Rename exported functions/classes (would break consumers)
- Gold-plate or over-engineer