feat: add state size guard with configurable warn and hard limits

Closes #14 — StateSerializer.serialize() now checks serialised state size:
- Logs a warning when state exceeds warn_bytes (default 64 KB)
- Raises ComponentError when state exceeds max_bytes (default 512 KB)
- Both thresholds are configurable via class attributes and can be
  disabled by setting to 0
- 5 new tests covering warning, error, threshold, and disable paths

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: fsecada01

src/component_framework/core/component.py

@@ -335,12 +335,45 @@ async def async_dispatch(
 
 
 class StateSerializer:
-    """Handles safe serialization/deserialization of component state."""
+    """Handles safe serialization/deserialization of component state.
+
+    Class attributes:
+        warn_bytes: Emit a warning when serialised state exceeds this size
+            (default 64 KB).  Set to ``0`` to disable warnings.
+        max_bytes: Raise :class:`ComponentError` when serialised state exceeds
+            this size (default 512 KB).  Set to ``0`` to disable the hard limit.
+    """
+
+    warn_bytes: int = 64 * 1024  # 64 KB
+    max_bytes: int = 512 * 1024  # 512 KB
 
     @staticmethod
     def serialize(state: dict) -> str:
-        """Serialize state to JSON string."""
-        return json.dumps(state, default=str)
+        """Serialize state to JSON string.
+
+        Emits a warning if the result exceeds :attr:`warn_bytes` and raises
+        :class:`ComponentError` if it exceeds :attr:`max_bytes`.
+        """
+        serialized = json.dumps(state, default=str)
+        size = len(serialized)
+
+        if StateSerializer.max_bytes and size > StateSerializer.max_bytes:
+            raise ComponentError(
+                f"Component state is {size:,} bytes "
+                f"(hard limit: {StateSerializer.max_bytes:,}). "
+                "Move large data out of state — store IDs/keys instead of "
+                "full objects, or use server-side caching."
+            )
+
+        if StateSerializer.warn_bytes and size > StateSerializer.warn_bytes:
+            logger.warning(
+                "Component state is %s bytes (threshold: %s). "
+                "Consider moving large data out of state.",
+                f"{size:,}",
+                f"{StateSerializer.warn_bytes:,}",
+            )
+
+        return serialized
 
     @staticmethod
     def deserialize(data: str) -> dict:

tests/test_component.py

@@ -260,6 +260,61 @@ def test_deserialize_invalid_json_raises(self):
             StateSerializer.deserialize("not json")
 
 
+# ---------- State Size Guard ----------
+
+
+class TestStateSizeGuard:
+    def setup_method(self):
+        self._orig_warn = StateSerializer.warn_bytes
+        self._orig_max = StateSerializer.max_bytes
+
+    def teardown_method(self):
+        StateSerializer.warn_bytes = self._orig_warn
+        StateSerializer.max_bytes = self._orig_max
+
+    def test_warning_on_large_state(self, caplog):
+        StateSerializer.warn_bytes = 50
+        StateSerializer.max_bytes = 0  # disable hard limit
+        big_state = {"data": "x" * 100}
+        import logging
+
+        with caplog.at_level(logging.WARNING):
+            StateSerializer.serialize(big_state)
+        assert "Component state is" in caplog.text
+        assert "threshold" in caplog.text
+
+    def test_no_warning_under_threshold(self, caplog):
+        StateSerializer.warn_bytes = 100_000
+        StateSerializer.max_bytes = 0
+        import logging
+
+        with caplog.at_level(logging.WARNING):
+            StateSerializer.serialize({"small": True})
+        assert "Component state is" not in caplog.text
+
+    def test_error_on_exceeding_hard_limit(self):
+        StateSerializer.max_bytes = 50
+        big_state = {"data": "x" * 100}
+        with pytest.raises(ComponentError, match="hard limit"):
+            StateSerializer.serialize(big_state)
+
+    def test_no_error_under_hard_limit(self):
+        StateSerializer.max_bytes = 100_000
+        result = StateSerializer.serialize({"small": True})
+        assert result  # no exception
+
+    def test_guards_disabled_when_zero(self, caplog):
+        StateSerializer.warn_bytes = 0
+        StateSerializer.max_bytes = 0
+        big_state = {"data": "x" * 10_000}
+        import logging
+
+        with caplog.at_level(logging.WARNING):
+            result = StateSerializer.serialize(big_state)
+        assert result
+        assert "Component state is" not in caplog.text
+
+
 # ---------- Async Event Handling ----------