SubMiner/backlog/tasks/task-79 - Introduce-explicit-runtime-state-transitions-and-reducers-in-main.md

id, title, status, assignee, created_date, updated_date, labels, dependencies, priority

id	title	status	assignee	created_date	updated_date	labels	dependencies	priority
TASK-79	Introduce explicit runtime state transitions and reducers in main	To Do		2026-02-18 11:43	2026-02-18 11:43	main-process state-management architecture	TASK-71	medium

Description

Main runtime state is currently mutable from many callsites. This task introduces explicit state-transition functions (reducer-like actions) for critical state domains to improve traceability and reduce accidental cross-feature coupling.

Suggestions

• Start with high-risk domains: overlay visibility, MPV connection/session, AniList/Jellyfin runtime status.
• Use action-style transition helpers (setMediaPath, setOverlayVisibility, setAnilistState) instead of direct field mutation.
• Keep transition helpers side-effect free; invoke effects in orchestration layer.

Action Steps

1. Inventory direct mutation hotspots in src/main.ts and runtime modules.
2. Define state transition API in src/main/state.ts for priority domains.
3. Migrate callsites incrementally to transition helpers.
4. Add unit tests for transition behavior and invariant enforcement.
5. Add lightweight debug tracing for transition events in debug mode.
6. Document state ownership and mutation rules in architecture docs.

Acceptance Criteria

• #1 Critical runtime state domains mutate through explicit transition helpers
• #2 State invariants are test-covered
• #3 Direct ad-hoc mutation in migrated domains is removed
• #4 Ownership/mutation rules documented

Definition of Done

• #1 Core tests pass after migration
• #2 No behavior regressions in startup/IPC/overlay flows