@spec cached_total_visual_rows(t(), term()) :: non_neg_integer() | nil

Returns a cached wrapped visual row total when the key matches.

@spec detect_context_change(t(), MingaEditor.Window.RenderCache.context_fingerprint()) ::
  t()

Compares the current render context fingerprint against the last frame's.

If the fingerprint changed, marks all lines dirty. This catches changes to visual selection, search matches, syntax highlights, diagnostic signs, git signs, horizontal scroll, active/inactive status, and theme colors, all of which affect every visible line's draw output.

@spec detect_invalidation(
  t(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer()
) :: t()

Checks current frame parameters against last-frame tracking fields and returns the window with dirty_lines: :all if anything that requires a full redraw has changed.

Structural triggers (checked here): viewport scroll, gutter width, line count, buffer version, first frame (sentinel values).

Context triggers (checked separately via detect_context_change/2): visual selection, search matches, syntax highlights, diagnostic signs, git signs, viewport horizontal scroll, active status, theme colors.

@spec dirty?(t(), non_neg_integer()) :: boolean()

Returns true if the given buffer line needs re-rendering.

Always true when dirty_lines is :all.

@spec fold_all(t()) :: t()

Folds all available ranges.

@spec fold_at(t(), non_neg_integer()) :: t()

Folds the range containing the given buffer line.

@spec fold_recursive_at(t(), non_neg_integer()) :: t()

Folds the outermost range containing the given buffer line and every nested range.

@spec has_folds?(t()) :: boolean()

Returns true if this window has any active folds.

@spec invalidate(t()) :: t()

Marks all lines dirty (full redraw needed).

Clears all caches and resets tracking fields to sentinels so the next render pass starts from scratch. Use this when the window's buffer changes, on resize, or any other event that makes all cached draws invalid.

@spec mark_dirty(t(), [non_neg_integer()] | :all) :: t()

Marks specific buffer lines as needing re-render.

Pass :all to force a complete redraw (scroll, resize, theme change, etc.). Pass a list of buffer line numbers for targeted invalidation (edits). If the window is already fully dirty, adding specific lines is a no-op.

@spec mark_frontend_reset_pending(t()) :: t()

Marks the next retained GUI frame as a frontend-state reset without discarding TUI draw caches.

@spec new(id(), pid(), pos_integer(), pos_integer()) :: t()

Creates a new window with the given id, buffer, and viewport dimensions.

Sets both content (the polymorphic content reference) and buffer (backward-compatible pid field). During the migration, callers access window.buffer directly. Once all callers are updated to use Content.buffer_pid(window.content), the buffer field will be removed.

@spec new(id(), pid(), pos_integer(), pos_integer(), Minga.Buffer.position()) :: t()

Creates a new window with the given id, buffer, viewport dimensions, and cursor position.

@spec new_agent_chat(id(), pid(), pos_integer(), pos_integer()) :: t()

Creates a new agent chat window.

The buffer field is set to the agent's *Agent* Buffer.Process pid for backward compatibility with code that reads window.buffer. The content field uses the :agent_chat tag so the render pipeline can dispatch to the agent chat renderer.

@spec next_textobject(t(), atom(), {non_neg_integer(), non_neg_integer()}) ::
  {non_neg_integer(), non_neg_integer()} | nil

Finds the next textobject position of the given type after (row, col).

@spec popup?(t()) :: boolean()

Returns true if this window is a popup (has popup metadata attached).

@spec prepare_render_epoch(t(), term()) :: {t(), non_neg_integer(), boolean()}

Prepares the retained GUI content epoch for the current frame.

@spec prev_textobject(t(), atom(), {non_neg_integer(), non_neg_integer()}) ::
  {non_neg_integer(), non_neg_integer()} | nil

Finds the previous textobject position of the given type before (row, col).

@spec put_retained_rows(t(), %{
  optional(non_neg_integer()) => MingaEditor.Window.RenderCache.retained_row()
}) :: t()

Stores the current frame's retained composed rows for upstream reuse next frame (#2287).

@spec put_retained_wrap_lines(
  t(),
  %{
    optional(non_neg_integer()) =>
      MingaEditor.Window.RenderCache.retained_wrap_line()
  }
) :: t()

Stores the current frame's retained wrapped logical lines for upstream reuse next frame (#2287).

@spec put_total_visual_rows(t(), term(), non_neg_integer()) :: t()

Stores the wrapped visual row total for the current cache key.

@spec resize(t(), non_neg_integer(), non_neg_integer()) :: t()

Updates the viewport dimensions for this window, marking all lines dirty.

@spec retained_rows(t()) :: %{
  optional(non_neg_integer()) => MingaEditor.Window.RenderCache.retained_row()
}

Returns the retained composed rows from the previous semantic content build (#2287).

@spec retained_wrap_lines(t()) :: %{
  optional(non_neg_integer()) =>
    MingaEditor.Window.RenderCache.retained_wrap_line()
}

Returns the retained wrapped logical lines from the previous semantic content build (#2287).

@spec scroll_horizontal(t(), integer()) :: t()

Scrolls the window horizontally by display columns.

@spec scroll_viewport(t(), integer(), non_neg_integer()) :: t()

Scrolls the window's viewport by delta lines and updates pinned state.

Scrolling up always unpins. Scrolling down re-pins only when the viewport reaches the bottom. total_lines is the buffer's line count.

Returns the updated window.

@spec set_document_symbols(t(), [Minga.Language.Symbol.t()]) :: t()

Updates the document symbols available for this window.

@spec set_fold_ranges(t(), [Minga.Editing.Fold.Range.t()]) :: t()

Updates the available fold ranges (from a provider). Preserves existing folds that still exist in the new ranges.

@spec set_pinned(t(), boolean()) :: t()

Sets whether the window should stay pinned to the bottom while content streams.

@spec set_viewport(t(), MingaEditor.Viewport.t()) :: t()

Stores the computed viewport for this window.

@spec snapshot_after_render(
  t(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  MingaEditor.Window.RenderCache.context_fingerprint()
) :: t()

Snapshots tracking fields after a successful render pass.

Clears the dirty set and records the current frame's parameters so the next frame can detect what changed. The context fingerprint captures all per-frame render context inputs (visual selection, search matches, syntax highlights, signs, etc.) so context changes trigger full redraws.

@spec toggle_fold(t(), non_neg_integer()) :: t()

Toggles the fold at the given buffer line using the window's available fold ranges.

@spec unfold_all(t()) :: t()

Unfolds all folds.

@spec unfold_at(t(), non_neg_integer()) :: t()

Unfolds the range containing the given buffer line.

@spec unfold_containing(t(), [non_neg_integer()]) :: t()

Unfolds any folds that contain the given lines (used by search auto-unfold).

@spec unfold_recursive_at(t(), non_neg_integer()) :: t()

Unfolds every active fold inside the outermost range containing the given buffer line.