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

Returns the sequence through which the line identity has been applied.

@spec apply_edit_deltas(
  t(),
  pid(),
  [Minga.Buffer.EditDelta.t()],
  Minga.Buffer.RenderSnapshot.t() | nil
) :: t()

Applies renderer-consumed deltas and retains their atomic changed snapshot.

@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 durable content epoch.

@spec detect_context_change(t(), context_fingerprint()) :: t()

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

If the fingerprint changed, marks all lines dirty. Catches changes to visual selection, search matches, syntax highlights, diagnostic signs, git signs, horizontal scroll, active/inactive status, and theme colors.

@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 marks all lines dirty if anything requiring a full redraw has changed.

Structural redraw triggers: viewport scroll, gutter width, line count, buffer version, first frame (sentinel values). Only first frame and gutter-width geometry changes request a retained-GUI epoch reset; ordinary text edits and line-count changes use row hashes without bumping the content epoch.

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

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

@spec fetch_version(t()) :: non_neg_integer() | nil

Returns the renderer-consumed version required by bounded fetches.

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

Returns the explicit reason for the next full resident hydration.

@spec line_identity(t()) :: Minga.RenderModel.Window.LineIdentity.t() | nil

Returns the 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. Pass a list of buffer line numbers for targeted invalidation. If already fully dirty, adding specific lines is a no-op.

@spec mark_identity_reset(t()) :: t()

Forces the next hydration to establish a fresh durable content epoch.

@spec mark_reset_pending(t()) :: t()

Marks the next retained GUI frame as a frontend-state reset.

@spec pending_edit_deltas(t()) :: [Minga.Buffer.EditDelta.t()]

Returns renderer-consumed deltas pending resident composition.

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

Prepares the retained GUI content epoch for the current frame.

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

Overlays renderer-owned committed lineage onto a stale editor snapshot.

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

Replaces the persistent residence build state captured by the last frame.

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

Replaces the retained-row map with the current frame's composed rows.

Stored wholesale (not merged) so the map stays bounded to the visible row set and never accumulates rows that scrolled out of view.

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

Replaces the retained wrapped-line map with the current frame's logical lines.

Stored wholesale (not merged) so the map stays bounded to the visible logical lines and never accumulates lines that scrolled out of view.

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

Stores the producer row-slot allocator after a successful content build.

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

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

@spec require_hydration(t(), atom()) :: t()

Invalidates retained composition for full hydration while preserving residence promotion.

@spec reset() :: t()

Returns a fresh cache with all lines dirty.

Use after any event that invalidates render state: buffer switch, resize, theme change, etc.

@spec reset(t()) :: t()

Returns a fresh cache invalidation while preserving retained-render epoch state.

@spec reset_content_identity(t(), pid(), 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 the residence flag captured by the last rendered frame.

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

Returns the persistent full-document residence build state, or nil when the window has not built on the residence path since the last reset. Carries the resident entry list and its incremental content digest across frames.

@spec retained_rows(t()) :: %{optional(non_neg_integer()) => retained_row()}

Returns the {row_id => {input_hash, Row.t()}} map captured by the last semantic content build. The Builder consults it to skip recomposing rows whose cheap input fingerprint is unchanged.

@spec retained_wrap_lines(t()) :: %{
  optional(non_neg_integer()) => retained_wrap_line()
}

Returns the {durable_row_id => {input_hash, entries}} map captured by the last semantic content build for wrapped windows. The Builder consults it to skip recomposing and re-wrapping logical lines whose input fingerprint is unchanged.

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

Returns the persistent producer row-slot allocator.

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

Returns the monotonic scroll-authority sequence (#2661).

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

Arms (or disarms) full-document residence for the next frame (#2679).

First-paint-then-promote: a resident-eligible window renders viewport-windowed on its first frame after becoming eligible, arming promotion; the next frame sees residence_armed?/1 true and emits full residence. This keeps the expensive O(document) first build off file-open first paint. The flag is reset by reset/1 so a layout_generation rebuild (resize, font, wrap) re-defers.

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

Records the render pipeline's full-document residence decision for the frame.

Lives in the render cache (not a top-level Window field) because the render cache is the only per-window struct the async render writeback copies back to the live window (MingaEditor.State.merge_renderer_window/2). The input layer reads it via resident?/1.

@spec settle_scroll_seq(t(), integer(), integer() | nil, non_neg_integer()) :: t()

Advances the scroll-authority sequence when this frame made a genuine BEAM-initiated scroll, and records the new baselines.

scroll_seq bumps when EITHER of two independent signals fires:

• Authoritative marker (#2652): authoritative_seq (the editor-owned Window.authoritative_scroll_seq request counter) moved past the last count this cache settled against. Command handlers increment it for the commands that must discard a frontend offset — at dispatch for always-authoritative viewport commands, and in the success branch of failable jumps (the MingaEditor.Commands @authoritative_scroll_commands comment is the source of truth for the set). This is the only signal that catches a jump landing exactly on the previous or echoed top (zz while already centered, a search hit already on screen), which the top comparison below cannot see.

• Top comparison: top differs from both the previous committed top (scroll_seq_last_top) and the frontend-reported free-scroll top (echo_top). A move to the echoed top is the frontend's own report reflected back (a wheel/trackpad free scroll, always viewport-only), so it does not advance the sequence. The first settle after a fresh cache (nil baseline) does not bump via this path (it only records the baseline).

The two signals are OR-combined into one bump, so a jump that both marks the counter and moves the top advances scroll_seq exactly once, never twice.

The marker cannot latch: the render cache overwrites scroll_seq_last_authoritative to the observed counter on every settle rather than the counter being cleared on the live window, so a single increment causes at most one bump per rendered lineage. Because the counter (scroll_seq) and both baselines live here and the render cache is written back to the live window, the sequence is monotonic per rendered lineage; overlapped in-flight frames can emit duplicate or regressing values, which the frontend tolerates (strict greater-than check, with anchor-key and reset_required covering discards).

@spec snapshot(
  t(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  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.

@spec sync_line_identity(t(), pid(), Minga.Buffer.RenderSnapshot.t()) :: t()

Reconciles durable logical-line identity from one atomic buffer snapshot.

@spec with_fetch_version(t(), non_neg_integer() | nil) :: t()

Pins bounded line fetches to the version atomically consumed by the renderer.