defmodule PdfEx.Op.Behaviour do
  @moduledoc """
  Behaviour for a collaborative edit operation.

  `PdfEx.Op.apply_op/2` dispatches to the op struct's own module, so adding a new
  operation is a new file — define a struct, implement this behaviour, and route
  to a pure edit function — with no edit to the dispatcher:

      defmodule MyApp.Op.InsertText do
        @behaviour PdfEx.Op.Behaviour
        defstruct [:uid, :text]

        @impl true
        def apply_to(%__MODULE__{} = op, doc), do: MyApp.Editing.insert(doc, op)
      end

  `apply_to/2` must be pure and never raise — return `{:error, %PdfEx.Error{}}`.
  """

  @doc "Applies the op to `doc`, returning the new document or a tagged error."
  @callback apply_to(struct(), PdfEx.Document.t()) ::
              {:ok, PdfEx.Document.t()} | {:error, PdfEx.Error.t()}
end