@spec decode(data :: binary(), format :: format()) :: {:ok, map()} | {:error, term()}

Decodes a wire-format binary into a string-keyed map without dispatch.

Unlike decode_message/2 which dispatches into Elixir event structs and internal tuples, this returns the raw deserialized map. Used by script and test helpers that handle renderer responses (query_response, interact_response, etc.) directly.

@spec decode_event(event :: map()) :: Plushie.Event.delivered_t()

Decodes a renderer event map into a typed Plushie event struct.

This is the shared event-map decoder used for interact responses and other already-deserialized renderer events. Raises on unknown or malformed events. Every event from the renderer must include window_id.

@spec decode_message(data :: binary(), format :: format()) :: decode_result()

Decodes a protocol message into an event struct or internal tuple.

Returns {:error, reason} on parse failure or an unrecognised message shape. Use decode_message!/2 for the strict runtime path.

Examples

iex> Plushie.Protocol.decode_message(~s({"type":"event","family":"click","id":"btn_save","window_id":"main"}), :json)
%Plushie.Event.WidgetEvent{type: :click, id: "btn_save", scope: ["main"], window_id: "main", value: nil, data: nil}

iex> match?({:error, {:decode_failed, _}}, Plushie.Protocol.decode_message("not json"))
true

@spec decode_message!(data :: binary(), format :: format()) :: decoded_message()

Decodes a protocol message into an event struct or internal tuple.

Raises Plushie.Protocol.Error when the payload is malformed or violates the SDK's protocol contract.

@spec encode(message :: map(), format :: format()) :: iodata()

Encodes an arbitrary map as wire-format iodata.

For :json, returns a JSON string with a trailing newline. For :msgpack, returns msgpack iodata (no length prefix -- the Erlang {:packet, 4} Port driver handles framing).

@spec encode_advance_frame(timestamp :: non_neg_integer(), format :: format()) ::
  iodata()

Encodes an advance_frame message for headless/test mode.

@spec encode_effect(
  id :: String.t(),
  kind :: String.t(),
  payload :: term(),
  format :: format()
) :: iodata()

Encodes an effect request as a protocol message.

Example

Plushie.Protocol.encode_effect("req_1", "file_open", %{title: "Pick a file"}, :json)
#=> ~s({"id":"req_1","kind":"file_open","payload":{"title":"Pick a file"},"session":"","type":"effect"}) <> "\n"

@spec encode_image_op(op :: String.t(), payload :: map(), format :: format()) ::
  iodata()

Encodes an image operation as a protocol message.

Image ops are create_image, update_image, or delete_image. The payload map contains the op-specific fields (handle, data/pixels, width, height).

Binary fields (data, pixels) are encoded based on the wire format:

• :msgpack -- wrapped in Msgpax.Bin for native msgpack binary type (zero overhead)
• :json -- base64-encoded strings (JSON has no binary type)

Example

Plushie.Protocol.encode_image_op("create_image", %{handle: "logo", data: <<1, 2, 3>>}, :json)
#=> ~s({"data":"AQID","handle":"logo","op":"create_image","session":"","type":"image_op"}) <> "\n"

@spec encode_interact(
  id :: String.t(),
  action :: String.t(),
  selector :: map(),
  payload :: map(),
  format :: format()
) :: iodata()

Encodes an interact request as a protocol message.

The renderer will process the interaction and respond with interact_step / interact_response messages.

@spec encode_patch(ops :: list(), format :: format()) :: iodata()

Encodes a list of patch operations as a protocol message.

The ops list is encoded as-is into the payload.

Example

Plushie.Protocol.encode_patch([], :json)
#=> ~s({"ops":[],"session":"","type":"patch"}) <> "\n"

@spec encode_register_effect_stub(
  kind :: String.t(),
  response :: term(),
  format :: format()
) ::
  iodata()

Encodes an effect stub registration message.

@spec encode_settings(settings :: map(), format :: format()) :: iodata()

Encodes application-level settings as a protocol message.

Example

Plushie.Protocol.encode_settings(%{antialiasing: true, default_text_size: 16}, :json)
#=> ~s({"session":"","settings":{"antialiasing":true,"default_text_size":16,"protocol_version":1},"type":"settings"}) <> "\n"

@spec encode_snapshot(tree :: term(), format :: format()) :: iodata()

Encodes a UI tree snapshot as a protocol message.

Example

Plushie.Protocol.encode_snapshot(%{tag: "text", value: "hello"}, :json)
#=> ~s({"session":"","tree":{"tag":"text","value":"hello"},"type":"snapshot"}) <> "\n"

@spec encode_subscribe(
  kind :: String.t(),
  tag :: String.t(),
  format :: format(),
  max_rate :: non_neg_integer() | nil,
  window_id :: String.t() | nil
) :: iodata()

Encodes a subscribe message as a protocol message.

An optional max_rate (events per second) can be included to enable renderer-side event coalescing for this subscription. An optional window_id scopes the subscription to a specific window.

Example

Plushie.Protocol.encode_subscribe("on_key_press", "keys", :json)
#=> ~s({"kind":"on_key_press","session":"","tag":"keys","type":"subscribe"}) <> "\n"

@spec encode_system_op(op :: String.t(), settings :: map(), format :: format()) ::
  iodata()

Encodes a system-wide operation as a protocol message.

@spec encode_system_query(op :: String.t(), settings :: map(), format :: format()) ::
  iodata()

Encodes a system-wide query as a protocol message.

@spec encode_unregister_effect_stub(kind :: String.t(), format :: format()) ::
  iodata()

Encodes an effect stub removal message.

@spec encode_unsubscribe(
  kind :: String.t(),
  format :: format(),
  tag :: String.t() | nil
) :: iodata()

Encodes an unsubscribe message as a protocol message.

An optional tag identifies the specific subscription to remove (when multiple subscriptions share the same kind).

Example

Plushie.Protocol.encode_unsubscribe("on_key_press", :json)
#=> ~s({"kind":"on_key_press","session":"","type":"unsubscribe"}) <> "\n"

@spec encode_widget_command(
  node_id :: String.t(),
  op :: String.t(),
  payload :: map(),
  format :: format()
) :: iodata()

Encodes a single widget command as a protocol message.

Widget commands bypass the normal tree update / diff / patch cycle and are delivered directly to the target native widget on the Rust side.

@spec encode_widget_commands(
  commands :: [{String.t(), String.t(), map()}],
  format :: format()
) :: iodata()

Encodes a batch of widget commands as a protocol message.

Each command in the list is a {node_id, op, payload} tuple. All commands in the batch are processed in a single cycle on the Rust side.

@spec encode_widget_op(op :: String.t(), payload :: map(), format :: format()) ::
  iodata()

Encodes a widget operation as a protocol message.

Example

Plushie.Protocol.encode_widget_op("focus", %{target: "username"}, :json)
#=> ~s({"op":"focus","payload":{"target":"username"},"session":"","type":"widget_op"}) <> "\n"

@spec encode_window_op(
  op :: String.t(),
  window_id :: String.t(),
  settings :: map(),
  format :: format()
) :: iodata()

Encodes a window lifecycle operation as a protocol message.

Example

Plushie.Protocol.encode_window_op("open", "main", %{title: "My App"}, :json)
#=> ~s({"op":"open","session":"","settings":{"title":"My App"},"type":"window_op","window_id":"main"}) <> "\n"

@spec parse_key(key :: String.t()) :: atom() | String.t()

Converts a key name string to an atom for named keys, or returns the string unchanged for single-character keys.

Examples

iex> Plushie.Protocol.parse_key("Escape")
:escape

iex> Plushie.Protocol.parse_key("a")
"a"

@spec protocol_version() :: non_neg_integer()

Returns the current protocol version number.