Feature: State size guard / large-state warning

[fsecada01]

Background

The README notes: "State must be JSON-serialisable" and "State size limits not enforced (keep state minimal)".

In practice it is easy to accidentally embed large payloads in component state — for example, an AI query response with hundreds of transaction records. This serialised state is embedded in the DOM (data-state attribute) and sent back with every subsequent event request.

Request

1. Dev-mode warning: When StateSerializer.serialize() produces a payload larger than a configurable threshold (e.g. 64 KB), emit a logger.warning:

serialized = json.dumps(state, default=str)
if len(serialized) > settings.STATE_SIZE_WARN_BYTES:
    logger.warning(
        f"Component state is {len(serialized)} bytes "
        f"(threshold: {settings.STATE_SIZE_WARN_BYTES}). "
        "Consider moving large data out of state."
    )

2. Optional hard limit: Raise ComponentError if state exceeds a hard cap (e.g. 512 KB) to prevent browser/network issues.

3. Docs guidance: Best-practice patterns for keeping state small:

   • Store IDs/keys, not full objects
   • Separate large result sets from component state (server-side cache keyed by a short token in state)
   • Paginate embedded lists

Real example that triggered this

An on_analyze handler embedded 100+ transaction records into state, producing a ~180 KB data-state attribute. There was no warning — the issue was only found by inspecting the DOM.