@spec add_block_decoration(server(), non_neg_integer(), keyword()) :: reference()

Add a block decoration (multi-line annotation) anchored to a line.

@spec add_highlight(
  server(),
  Minga.Core.Decorations.highlight_range_pos(),
  Minga.Core.Decorations.highlight_range_pos(),
  keyword()
) :: reference()

Add a highlight range.

@spec add_virtual_text(
  server(),
  Minga.Core.Decorations.highlight_range_pos(),
  keyword()
) :: reference()

Add virtual text anchored to a line.

@spec append(server(), String.t()) :: :ok

Append text to the end of the buffer.

@spec apply_edit(
  server(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  String.t(),
  Minga.Buffer.EditSource.t()
) :: :ok

Replace text in a range with new text (the general-purpose edit operation).

@spec apply_edits(
  server(),
  [Minga.Buffer.Server.text_edit()],
  Minga.Buffer.EditSource.t()
) :: :ok

Apply a batch of edits atomically (for LSP workspace edits).

@spec apply_snapshot(server(), document()) :: :ok

Restore a previously captured document snapshot.

@spec batch_decorations(server(), (Minga.Core.Decorations.t() ->
                               Minga.Core.Decorations.t())) :: :ok

Apply a batch of decoration changes atomically.

@spec break_undo_coalescing(server()) :: :ok

Force the next edit to start a new undo group.

@spec buffer_name(server()) :: String.t() | nil

Logical name of the buffer (e.g., *Messages*), or nil for file buffers.

@spec buffer_type(server()) :: :file | :scratch | :special

Buffer kind: :file, :scratch, or :special.

@spec byte_offset_for_line(server(), non_neg_integer()) :: non_neg_integer()

Byte offset of the start of a line (for tree-sitter integration).

@spec child_spec([Minga.Buffer.Server.start_opt()]) :: Supervisor.child_spec()

Supervisor child spec for starting a buffer process.

@spec clear_face_override(server(), String.t()) :: :ok

Remove a face override for this buffer.

@spec clear_line(server(), non_neg_integer()) :: {:ok, String.t()}

Clear the contents of a single line.

@spec content(server()) :: String.t()

Full text content of the buffer.

@spec content_and_cursor(server()) :: {String.t(), position()}

Content and cursor position in a single call (avoids two round-trips).

@spec cursor(server()) :: position()

Current cursor position as {line, col}.

@spec decorations(server()) :: Minga.Core.Decorations.t()

Current decoration state (highlights, virtual text, folds, etc.).

@spec decorations_version(server()) :: non_neg_integer()

Version counter for decorations (for change detection).

@spec delete_at(server()) :: :ok

Delete the character at the cursor.

@spec delete_before(server()) :: :ok

Delete the character before the cursor.

@spec delete_lines(server(), non_neg_integer(), non_neg_integer()) :: :ok

Delete lines from start_line to end_line (inclusive).

@spec delete_range(server(), position(), position()) :: :ok

Delete text between two positions.

@spec dirty?(server()) :: boolean()

Whether the buffer has unsaved changes.

@spec display_name(server()) :: String.t()

Human-readable display name (file basename or buffer name).

@spec ensure_for_path(String.t()) :: {:ok, pid()} | {:error, term()}

Returns the pid for a buffer at path, starting one if it doesn't exist.

If a buffer is already registered for path, returns its pid immediately. Otherwise, starts a new buffer under Minga.Buffer.Supervisor and broadcasts a :buffer_opened event so the Editor and other subscribers can pick it up.

Used by agent tools to guarantee every edited file has a buffer with undo integration, without depending on the Editor (Layer 2).

@spec face_overrides(server()) :: %{required(String.t()) => keyword()}

Current face override map.

@spec file_path(server()) :: String.t() | nil

File path of the buffer, or nil for scratch buffers.

@spec filetype(server()) :: atom()

Detected filetype (e.g., :elixir, :json).

@spec find_and_replace(
  server(),
  String.t(),
  String.t(),
  Minga.Buffer.Server.boundary()
) ::
  {:ok, String.t()} | {:error, String.t()}

Find and replace the first occurrence of old_text with new_text.

@spec find_and_replace_batch(
  server(),
  [Minga.Buffer.Server.replace_edit()],
  Minga.Buffer.Server.boundary()
) :: {:ok, [Minga.Buffer.Server.replace_result()]} | {:error, String.t()}

Find and replace multiple patterns atomically.

@spec flush_edits(server(), atom()) :: [Minga.Buffer.EditDelta.t()]

Flush edit deltas accumulated since the given consumer's last read.

@spec force_save(server()) :: :ok | {:error, term()}

Save even if the buffer appears clean.

@spec get_option(server(), atom()) :: term()

Read a per-buffer option (falls back to global config).

@spec insert_char(server(), String.t(), Minga.Buffer.EditSource.t()) :: :ok

Insert a single character at the cursor.

@spec insert_text(server(), String.t(), Minga.Buffer.EditSource.t()) :: :ok

Insert a multi-character string at the cursor.

@spec line_count(server()) :: pos_integer()

Number of lines in the buffer.

@spec lines(server(), non_neg_integer(), non_neg_integer()) :: [String.t()]

A range of lines starting at start (0-indexed), returning count lines.

@spec lines_content(server(), non_neg_integer(), non_neg_integer()) :: String.t()

Content of lines from start_line to end_line (inclusive, 0-indexed).

@spec move(server(), direction()) :: :ok

Move the cursor one step in a direction.

@spec move_if_possible(server(), :left | :right) ::
  {:ok, position()} | {:at_boundary, position()}

Move cursor if possible, returning the result position and whether a boundary was hit.

@spec move_to(server(), position()) :: :ok

Move the cursor to an exact position.

@spec open(server(), String.t()) :: :ok | {:error, term()}

Open a file into the buffer, replacing current content.

@spec persistent?(server()) :: boolean()

Whether the buffer survives tab close (e.g., *Messages*).

@spec pid_for_path(String.t()) :: {:ok, pid()} | :not_found

Look up a buffer process by its file path. Returns :not_found if no buffer has that file open.

@spec read_only?(server()) :: boolean()

Whether the buffer is read-only.

@spec redo(server()) :: :ok | :empty

Redo the last undone edit.

@spec reload(server()) :: :ok | {:error, term()}

Reload content from disk, discarding unsaved changes.

@spec remap_face(server(), String.t(), keyword()) :: :ok

Override a face's attributes for this buffer.

@spec remove_block_decoration(server(), reference()) :: :ok

Remove a block decoration by ID.

@spec remove_highlight(server(), reference()) :: :ok

Remove a highlight by ID.

@spec remove_highlight_group(server(), atom()) :: :ok

Remove all highlights in a group.

@spec remove_virtual_text(server(), reference()) :: :ok

Remove virtual text by ID.

@spec render_snapshot(server(), non_neg_integer(), non_neg_integer()) ::
  Minga.Buffer.RenderSnapshot.t()

Render-ready snapshot of visible lines for the rendering pipeline.

@spec replace_content(server(), String.t(), Minga.Buffer.State.edit_source()) ::
  :ok | {:error, term()}

Replace the entire buffer content.

@spec replace_content_force(server(), String.t()) :: :ok

Replace content unconditionally (bypasses read-only check).

@spec replace_content_with_decorations(server(), String.t(), function(), keyword()) ::
  :ok

Replace buffer content and apply decorations in one atomic operation.

@spec save(server()) :: :ok | {:error, term()}

Save the buffer to disk.

@spec save_all_dirty() :: {non_neg_integer(), [String.t()]}

Saves all dirty file-backed buffers to disk.

Enumerates the Buffer.Registry, filters for dirty buffers, and saves each one. Read-only buffers and save failures are logged as warnings but do not block other saves. Returns the count of successfully saved buffers and a list of any warnings (path + error reason).

@spec save_as(server(), String.t()) :: :ok | {:error, term()}

Save the buffer to a new file path.

@spec set_filetype(server(), atom()) :: :ok

Override the detected filetype.

@spec set_option(server(), atom(), term()) :: {:ok, term()} | {:error, String.t()}

Set a per-buffer option override.

@spec snapshot(server()) :: document()

Capture a snapshot of the document state (for undo boundaries and tab switching).

@spec start_link([Minga.Buffer.Server.start_opt()]) :: GenServer.on_start()

Start a new buffer process.

@spec text_between(server(), position(), position()) :: String.t()

Text between two positions (end exclusive).

@spec text_between_inclusive(server(), position(), position()) :: String.t()

Text between two positions (end inclusive, includes the character at end_pos).

@spec undo(server()) :: :ok | :empty

Undo the last edit.

@spec unlisted?(server()) :: boolean()

Whether the buffer is hidden from buffer lists.

@spec version(server()) :: non_neg_integer()

Monotonic version counter (incremented on every content change).