refactor: styles own their ringing tone directly (Pattern C)

Drop the injected AlarmSound Protocol and the wecker.Sound class. Each style
now owns its tone by using pygame directly; the runner owns only the audio
engine lifecycle (mixer init/quit), button sampling, and cleanup. This is the
seam for future styles that handle their own tone — a 'talk' style would just
import pygame and play speech, with no shared interface to extend.

- styles/base.py: AlarmStyle.__init__(set_led, music_file) + start() + update()
- styles/blink.py: start() loads+plays music via pygame.mixer.music
- styles/simple.py: owns its beep — synthesises a square-wave buffer in
  module (stdlib array+math) and plays it via pygame.mixer.Sound
- wecker.py: setup() brings up the mixer only; run_alarm constructs the style
  and guards start() with a clean log+exit on failure

Tests: a shared tests/conftest.py stubs RPi.GPIO/pygame in sys.modules before
any SUT import (order-independent, removes duplicated inline mocking); the
wecker mock_pygame fixture patches one fresh pygame mock into wecker + both
style modules so assertions see the same calls.

README: tone-ownership and plugin-contract updated.

tests/conftest.py

@@ -0,0 +1,14 @@
+"""Shared test setup: stub hardware/audio modules before any SUT import.
+
+wecker and the alarm styles import RPi.GPIO (hardware) and pygame (audio
+engine). The tests run off the Pi and without a real audio device, so these
+are replaced with MagicMocks in sys.modules before wecker/styles are imported.
+Loaded by pytest before any test module in this directory is collected.
+"""
+
+import sys
+from unittest.mock import MagicMock
+
+sys.modules["RPi"] = MagicMock()
+sys.modules["RPi.GPIO"] = MagicMock()
+sys.modules["pygame"] = MagicMock()

tests/test_single_instance.py

@@ -1,14 +1,9 @@
 import pytest
-import sys
-from unittest.mock import MagicMock, patch
+from unittest.mock import patch
 
-# Mock hardware modules before importing wecker (tests run off the Pi).
-sys.modules["RPi"] = MagicMock()
-sys.modules["RPi.GPIO"] = MagicMock()
-sys.modules["pygame"] = MagicMock()
-
-import common  # noqa: E402
-import wecker  # noqa: E402
+# Hardware/audio mocks live in tests/conftest.py (shared across all test files).
+import common
+import wecker
 
 
 @pytest.fixture

tests/test_styles_blink.py

@@ -1,4 +1,4 @@
-from unittest.mock import MagicMock
+from unittest.mock import MagicMock, patch
 
 from styles.blink import (
     STATE_BLINKING,
@@ -11,20 +11,20 @@ from styles.blink import (
 
 
 def _make_blink(music_file="music.mp3"):
-    """Return (style, sound_mock) for a BlinkStyle ready to start."""
-    sound = MagicMock()
-    style = BlinkStyle(lambda on: None, sound, music_file)
-    return style, sound
+    """Return (style, set_led calls) for a BlinkStyle ready to update."""
+    calls = []
+    style = BlinkStyle(lambda on: calls.append(on), music_file)
+    return style, calls
 
 
 def test_start_plays_music_and_led_off():
-    calls = []
-    sound = MagicMock()
-    style = BlinkStyle(lambda on: calls.append(on), sound, "track.mp3")
-    style.start()
-    sound.play_music.assert_called_once_with("track.mp3")
+    style, calls = _make_blink("track.mp3")
+    with patch("styles.blink.pygame", MagicMock()) as pg:
+        style.start()
+    pg.mixer.music.load.assert_called_with("track.mp3")
+    pg.mixer.music.set_volume.assert_called_with(1.0)
+    pg.mixer.music.play.assert_called_with(-1)
     assert calls == [False]  # LED off while music plays until a press starts the puzzle
-    assert style.state == 0  # STATE_RINGING until a press
 
 
 def test_press_starts_puzzle():
@@ -74,8 +74,7 @@ def test_blink_incorrect_retries():
 
 
 def test_blinking_non_blocking():
-    calls = []
-    style, _ = _make_blink()
+    style, calls = _make_blink()
     style.set_led = calls.append
     style.state = STATE_BLINKING
     style.target_blinks = 2

tests/test_styles_simple.py

@@ -1,49 +1,55 @@
-from unittest.mock import MagicMock
+from unittest.mock import MagicMock, patch
 
 from styles.simple import SimpleStyle
 
 
 def _make_style():
-    sound = MagicMock()
-    style = SimpleStyle(lambda on: None, sound)
-    return style, sound
+    calls = []
+    return SimpleStyle(lambda on: calls.append(on)), calls
 
 
 def test_simple_keeps_ringing_when_not_pressed():
     style, _ = _make_style()
-    assert style.update(0.0, False) is True
+    with patch("styles.simple.pygame", MagicMock()):
+        style.start()
+        assert style.update(0.0, False) is True
 
 
 def test_simple_stops_on_first_press():
     style, _ = _make_style()
-    assert style.update(0.0, True) is False  # press -> stop
+    with patch("styles.simple.pygame", MagicMock()):
+        style.start()
+        assert style.update(0.0, True) is False  # press -> stop
 
 
 def test_simple_led_solid_on():
-    calls = []
-    sound = MagicMock()
-    style = SimpleStyle(lambda on: calls.append(on), sound)
-    style.start()
-    assert calls == [True]
-    style.update(0.0, False)
-    assert calls[-1] is True  # stays on every tick
+    style, calls = _make_style()
+    with patch("styles.simple.pygame", MagicMock()):
+        style.start()
+        style.update(0.0, False)
+    assert calls == [True, True]  # start sets LED on; update keeps it on
 
 
 def test_simple_beeps_on_interval():
-    style, sound = _make_style()
-    style.start()
-    style.update(100.0, False)  # first tick -> beep
-    assert sound.play_beep.called
-    sound.play_beep.reset_mock()
-    style.update(100.4, False)  # before interval -> no beep
-    assert not sound.play_beep.called
-    style.update(100.5, False)  # at interval -> beep
-    assert sound.play_beep.called
+    style, _ = _make_style()
+    with patch("styles.simple.pygame", MagicMock()) as pg:
+        style.start()
+        style.update(100.0, False)  # first tick -> beep
+        assert pg.mixer.Sound.return_value.play.called
+        pg.mixer.Sound.return_value.play.reset_mock()
+
+        style.update(100.4, False)  # before interval -> no beep
+        assert not pg.mixer.Sound.return_value.play.called
+
+        style.update(100.5, False)  # at interval -> beep
+        assert pg.mixer.Sound.return_value.play.called
 
 
 def test_simple_never_plays_music():
-    style, sound = _make_style()
-    style.start()
-    style.update(0.0, False)
-    style.update(0.0, True)  # press -> stop
-    assert not sound.play_music.called
+    style, _ = _make_style()
+    with patch("styles.simple.pygame", MagicMock()) as pg:
+        style.start()
+        style.update(0.0, False)
+        style.update(0.0, True)  # press -> stop
+    assert not pg.mixer.music.play.called
+    assert not pg.mixer.music.load.called

tests/test_wecker.py

@@ -1,13 +1,9 @@
 import pytest
-import sys
 from unittest.mock import MagicMock, patch
 
-# Mock RPi.GPIO and pygame before importing wecker
-sys.modules["RPi"] = MagicMock()
-sys.modules["RPi.GPIO"] = MagicMock()
-sys.modules["pygame"] = MagicMock()
-
-import wecker  # noqa: E402
+import styles.blink
+import styles.simple
+import wecker
 
 
 @pytest.fixture
@@ -20,7 +16,18 @@ def mock_gpio():
 
 @pytest.fixture
 def mock_pygame():
-    with patch.object(wecker, "pygame") as mock:
+    """One fresh pygame mock shared by wecker and both styles.
+
+    Under Pattern C the styles use pygame directly, so a single mock must be
+    patched into wecker (setup) and the style modules (start) for assertions
+    to see the same calls.
+    """
+    mock = MagicMock()
+    with (
+        patch.object(wecker, "pygame", mock),
+        patch.object(styles.blink, "pygame", mock),
+        patch.object(styles.simple, "pygame", mock),
+    ):
         yield mock
 
 
@@ -50,7 +57,7 @@ def test_run_alarm_unknown_style_raises(mock_gpio, mock_pygame):
 
 
 def test_run_alarm_uses_selected_style(mock_gpio, mock_pygame):
-    """run_alarm looks up the style, injects a Sound, and calls start()."""
+    """run_alarm looks up the style, injects set_led + music_file, calls start()."""
     fake = MagicMock()
     fake.update.return_value = True  # keep ringing
     fake_style_cls = MagicMock(return_value=fake)
@@ -61,7 +68,7 @@ def test_run_alarm_uses_selected_style(mock_gpio, mock_pygame):
     get_style.assert_called_once_with("whatever")
     args = fake_style_cls.call_args.args
     assert args[0] is wecker.set_led
-    assert isinstance(args[1], wecker.Sound)
+    assert isinstance(args[1], str)  # resolved music file
     fake.start.assert_called_once()
     fake.update.assert_called()
 
@@ -73,7 +80,7 @@ def test_run_alarm_default_music_file(mock_gpio, mock_pygame, monkeypatch):
     fake_style_cls = MagicMock(return_value=fake)
     with patch("wecker.get_style", return_value=fake_style_cls):
         wecker.run_alarm(test_mode=True)
-    assert fake_style_cls.call_args.args[2] == wecker.DEFAULT_MUSIC_FILE
+    assert fake_style_cls.call_args.args[1] == wecker.DEFAULT_MUSIC_FILE
 
 
 def test_run_alarm_env_music_file(mock_gpio, mock_pygame, monkeypatch):
@@ -83,7 +90,7 @@ def test_run_alarm_env_music_file(mock_gpio, mock_pygame, monkeypatch):
     fake_style_cls = MagicMock(return_value=fake)
     with patch("wecker.get_style", return_value=fake_style_cls):
         wecker.run_alarm(test_mode=True)
-    assert fake_style_cls.call_args.args[2] == "/env/track.mp3"
+    assert fake_style_cls.call_args.args[1] == "/env/track.mp3"
 
 
 def test_run_alarm_music_file_arg_overrides_env(mock_gpio, mock_pygame, monkeypatch):
@@ -93,11 +100,10 @@ def test_run_alarm_music_file_arg_overrides_env(mock_gpio, mock_pygame, monkeypa
     fake_style_cls = MagicMock(return_value=fake)
     with patch("wecker.get_style", return_value=fake_style_cls):
         wecker.run_alarm(music_file="/arg/track.mp3", test_mode=True)
-    assert fake_style_cls.call_args.args[2] == "/arg/track.mp3"
+    assert fake_style_cls.call_args.args[1] == "/arg/track.mp3"
 
 
-@patch("wecker.time.time")
-def test_run_alarm_blink_plays_music(mock_time, mock_gpio, mock_pygame):
+def test_run_alarm_blink_plays_music(mock_gpio, mock_pygame):
     """The default (blink) style plays music on an endless loop."""
     wecker.run_alarm(test_mode=True)
     assert mock_pygame.mixer.music.play.called
@@ -109,18 +115,3 @@ def test_run_alarm_simple_beeps_and_plays_no_music(mock_gpio, mock_pygame):
     wecker.run_alarm(style_name="simple", test_mode=True)
     assert mock_pygame.mixer.Sound.return_value.play.called  # beep played
     assert not mock_pygame.mixer.music.play.called  # no music
-
-
-def test_sound_play_music_loads_and_loops(mock_pygame):
-    s = wecker.Sound()
-    s.play_music("/track.mp3")
-    mock_pygame.mixer.music.load.assert_called_with("/track.mp3")
-    mock_pygame.mixer.music.set_volume.assert_called_with(1.0)
-    mock_pygame.mixer.music.play.assert_called_with(-1)
-
-
-def test_sound_play_beep_plays_buffer(mock_pygame):
-    s = wecker.Sound()
-    s.play_beep()
-    mock_pygame.mixer.Sound.assert_called_once_with(wecker._BEEP_BUFFER)
-    mock_pygame.mixer.Sound.return_value.play.assert_called_once()