@spec applied_change_sequence(t()) :: non_neg_integer()

Returns the applied buffer change sequence for durable line identity.

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

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

@spec changed_snapshot(t()) :: Minga.Buffer.RenderSnapshot.t() | nil

Returns the atomic bounded snapshot for pending resident deltas.

@spec content_epoch(t()) :: non_neg_integer()

Returns the window's durable content epoch.

@spec detect_context_change(
  t(),
  MingaEditor.Renderer.WindowCache.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 expected_buffer_version(t()) :: non_neg_integer() | nil

Returns the renderer-consumed version pinned for bounded line fetches.

@spec hydration_reason(t()) :: atom() | nil

Returns the explicit reason for the next resident hydration.

@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 line_identity(t()) :: Minga.RenderModel.Window.LineIdentity.t() | nil

Returns the window's durable logical-line identity sequence.

@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 pending_edit_deltas(t()) :: [Minga.Buffer.EditDelta.t()]

Returns renderer-consumed edit deltas pending resident composition.

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

Prepares the retained GUI content epoch for the current frame.

@spec put_lineage(
  t(),
  Minga.RenderModel.Window.LineIdentity.t(),
  non_neg_integer()
) :: t()

Overlays renderer-owned committed lineage onto a window snapshot.

@spec put_resident_build(t(), MingaEditor.RenderModel.Window.ResidentBuild.t() | nil) ::
  t()

Stores the current frame's residence build state for incremental reuse next frame (#2658).

@spec put_retained_rows(t(), %{
  optional(non_neg_integer()) => MingaEditor.Renderer.WindowCache.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.Renderer.WindowCache.retained_wrap_line()
  }
) :: t()

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

@spec put_row_slot_allocator(t(), Minga.RenderModel.Window.RowSlotAllocator.t()) ::
  t()

Stores the producer-owned stable row-slot allocator.

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

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

@spec reset_content_identity(t(), Minga.Buffer.RenderSnapshot.t()) :: t()

Explicitly rebuilds durable content identity in a fresh epoch.

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

Returns whether residence was armed by the previous eligible frame (#2679).

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

Returns whether this window was a full-document resident window as of the last rendered frame.

@spec resident_build(t()) :: MingaEditor.RenderModel.Window.ResidentBuild.t() | nil

Returns the persistent full-document residence build state (#2658).

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

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

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

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

@spec row_slot_allocator(t()) :: Minga.RenderModel.Window.RowSlotAllocator.t()

Returns the producer-owned stable row-slot allocator.

@spec scroll_seq(t()) :: non_neg_integer()

Returns the renderer-owned monotonic scroll-authority sequence.

@spec set_cursor(t(), Minga.Buffer.position()) :: t()

Stores the renderer-local cursor for this window.

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

Arms or disarms residence promotion for the next frame (#2679 first-paint-then-promote).

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

Records whether this window is a full-document resident window (#2653/#2658).

Stored in the render cache because residence is a renderer-computed value and the render cache is the only per-window struct copied back from the async render pipeline (see MingaEditor.State.merge_renderer_window/2). The input layer (mouse wheel/trackpad handling) reads it via resident?/1 so it can branch on residence without recomputing it. Stale by at most one frame, which is harmless: residence is a document-size property that doesn't flip mid-gesture.

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

Stores the computed viewport for this window.

@spec settle_scroll_seq(t()) :: t()

Settles the per-frame scroll_seq decision against the render cache baseline.

Delegates to MingaEditor.Window.RenderCache.settle_scroll_seq/4 with this frame's committed viewport top, the sticky scroll_echo_top recorded by the input path, and the authoritative_scroll_seq request counter set by command handlers. scroll_seq advances when EITHER an authoritative jump was marked since the last settle OR the top moved to a value that is neither the previous committed top nor a frontend-reported free-scroll top (a genuine BEAM-initiated anchor move). Wheel/trackpad free-scroll frames share the reported top, so they are echoes and do not advance the sequence. A jump that also moves the top bumps once, not twice (a single OR decision per settle). The counter, its baseline, and the authoritative-request baseline all live in the render cache, so the sequence is monotonic across the serially threaded, written-back render cache.

@spec snapshot_after_render(
  t(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  MingaEditor.Renderer.WindowCache.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 sync_line_identity(t(), Minga.Buffer.RenderSnapshot.t()) :: t()

Reconciles durable logical-line identities from an atomic buffer snapshot.