feat(figment): add trigger protocol and command types

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

engine/figment_trigger.py

@@ -0,0 +1,36 @@
+"""
+Figment trigger protocol and command types.
+
+Defines the extensible input abstraction for triggering figment displays
+from any control surface (ntfy, MQTT, serial, etc.).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Protocol
+
+
+class FigmentAction(Enum):
+    TRIGGER = "trigger"
+    SET_INTENSITY = "set_intensity"
+    SET_INTERVAL = "set_interval"
+    SET_COLOR = "set_color"
+    STOP = "stop"
+
+
+@dataclass
+class FigmentCommand:
+    action: FigmentAction
+    value: float | str | None = None
+
+
+class FigmentTrigger(Protocol):
+    """Protocol for figment trigger sources.
+
+    Any input source (ntfy, MQTT, serial) can implement this
+    to trigger and control figment displays.
+    """
+
+    def poll(self) -> FigmentCommand | None: ...

tests/test_figment_trigger.py

@@ -0,0 +1,40 @@
+"""Tests for engine.figment_trigger module."""
+
+from enum import Enum
+
+from engine.figment_trigger import FigmentAction, FigmentCommand
+
+
+class TestFigmentAction:
+    def test_is_enum(self):
+        assert issubclass(FigmentAction, Enum)
+
+    def test_has_trigger(self):
+        assert FigmentAction.TRIGGER.value == "trigger"
+
+    def test_has_set_intensity(self):
+        assert FigmentAction.SET_INTENSITY.value == "set_intensity"
+
+    def test_has_set_interval(self):
+        assert FigmentAction.SET_INTERVAL.value == "set_interval"
+
+    def test_has_set_color(self):
+        assert FigmentAction.SET_COLOR.value == "set_color"
+
+    def test_has_stop(self):
+        assert FigmentAction.STOP.value == "stop"
+
+
+class TestFigmentCommand:
+    def test_trigger_command(self):
+        cmd = FigmentCommand(action=FigmentAction.TRIGGER)
+        assert cmd.action == FigmentAction.TRIGGER
+        assert cmd.value is None
+
+    def test_set_intensity_command(self):
+        cmd = FigmentCommand(action=FigmentAction.SET_INTENSITY, value=0.8)
+        assert cmd.value == 0.8
+
+    def test_set_color_command(self):
+        cmd = FigmentCommand(action=FigmentAction.SET_COLOR, value="orange")
+        assert cmd.value == "orange"