refactor: improve InitialStateService robustness and maintainability

[joshtrichards]

• Resolves: #
• Target version: main

Summary

This PR refactors the InitialStateService class to enhance robustness, maintainability, and clarity:

• Guards against duplicate provisioning by introducing $hasProvidedOptions flags to ensure option state is only set once per request.
• Introduces strict validation of universally critical parameters (urlsrc, fileId, token) in provideDocument(), throwing exceptions when missing to prevent frontend/session errors.
• Modularizes frontend option setup by breaking out theming and logo logic into dedicated helper methods (setThemeOptions, setLogoOption), improving readability and separation of concerns.
• Enhances documentation with comprehensive PHPDoc and inline comments, making intent and requirements clearer to maintainers.

These improvements collectively make the service safer, easier to follow, and more maintainable for future development.

No breaking changes introduced; the new exceptions will only trigger on situations that would have already failed in some other way.

TODO

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Documentation (manuals or wiki) has been updated or is not required