Struct Editor 

pub struct Editor<B: Buffer = Buffer, H: Host = DefaultHost> {
    pub keybinding_mode: KeybindingMode,
    pub last_yank: Option<String>,
    pub styled_spans: Vec<Vec<(usize, usize, Style)>>,
    /* private fields */
}

Fields

keybinding_mode: KeybindingMode

last_yank: Option<String>

Set when the user yanks/cuts; caller drains this to write to OS clipboard.

styled_spans: Vec<Vec<(usize, usize, Style)>>

Per-row syntax styling, kept here so the host can do incremental window updates (see apply_window_spans in the host). Same (start_byte, end_byte, Style) tuple shape the textarea used to host. The Buffer-side opaque-id spans are derived from this on every install. Behind the ratatui feature.

Implementations

impl<H: Host> Editor<Buffer, H>

pub fn new(buffer: Buffer, host: H, options: Options) -> Self

Build an Editor from a buffer, host adapter, and SPEC options.

0.1.0 (Patch C-δ): canonical, frozen constructor per SPEC §“Editor surface”. Replaces the pre-0.1.0 Editor::new(KeybindingMode) / with_host / with_options triad — there is no shim.

Consumers that don’t need a custom host pass crate::types::DefaultHost::new(); consumers that don’t need custom options pass crate::types::Options::default().

impl<B: Buffer, H: Host> Editor<B, H>

pub fn buffer(&self) -> &B

Borrow the buffer (typed &B). Host renders through this via hjkl_buffer::BufferView when B = hjkl_buffer::Buffer.

pub fn buffer_mut(&mut self) -> &mut B

Mutably borrow the buffer (typed &mut B).

pub fn host(&self) -> &H

Borrow the host adapter directly (typed &H).

pub fn host_mut(&mut self) -> &mut H

Mutably borrow the host adapter (typed &mut H).

impl<H: Host> Editor<Buffer, H>

pub fn set_iskeyword(&mut self, spec: impl Into<String>)

Update the active iskeyword spec for word motions (w/b/e/ge and engine-side */# pickup). 0.0.28 hoisted iskeyword storage out of Buffer — Editor is the single owner now. Equivalent to assigning settings_mut().iskeyword directly; the dedicated setter is retained for source-compatibility with 0.0.27 callers.

pub fn emit_cursor_shape_if_changed(&mut self)

Emit Host::emit_cursor_shape if the public mode has changed since the last emit. Engine calls this at the end of every input step so mode transitions surface to the host without sprinkling the call across every vim.mode = ... site.

pub fn sticky_col(&self) -> Option<usize>

Vim’s sticky column (curswant). None before the first motion; hosts shouldn’t normally need to read this directly — it’s surfaced for migration off Buffer::sticky_col and for snapshot tests.

pub fn set_sticky_col(&mut self, col: Option<usize>)

Replace the sticky column. Hosts should rarely touch this — motion code maintains it through the standard horizontal / vertical motion paths.

pub fn mark(&self, c: char) -> Option<(usize, usize)>

Host hook: replace the cached syntax-derived block ranges that :foldsyntax consumes. the host calls this on every re-parse; the cost is just a Vec swap. Look up a named mark by character. Returns (row, col) if set; None otherwise. Both lowercase ('a–'z) and uppercase ('A–'Z) marks live in the same unified Editor::marks map as of 0.0.36.

pub fn set_mark(&mut self, c: char, pos: (usize, usize))

Set the named mark c to (row, col). Used by the FSM’s m{a-zA-Z} keystroke and by Editor::restore_snapshot.

pub fn clear_mark(&mut self, c: char)

Remove the named mark c (no-op if unset).

pub fn buffer_mark(&self, c: char) -> Option<(usize, usize)>

👎Deprecated since 0.0.36:

use Editor::mark — lowercase + uppercase marks now live in a single map

Look up a buffer-local lowercase mark ('a–'z). Kept as a thin wrapper over Editor::mark for source compatibility with pre-0.0.36 callers; new code should call Editor::mark directly.

pub fn pop_last_undo(&mut self) -> bool

Discard the most recent undo entry. Used by ex commands that pre-emptively pushed an undo state (:s, :r) but ended up matching nothing — popping prevents a no-op undo step from polluting the user’s history.

Returns true if an entry was discarded.

pub fn marks(&self) -> impl Iterator<Item = (char, (usize, usize))> + '_

Read all named marks set this session — both lowercase ('a–'z) and uppercase ('A–'Z). Iteration is deterministic (BTreeMap-ordered) so snapshot / :marks output is stable.

pub fn buffer_marks(&self) -> impl Iterator<Item = (char, (usize, usize))> + '_

👎Deprecated since 0.0.36:

use Editor::marks — lowercase + uppercase marks now live in a single map

Read all buffer-local lowercase marks. Kept for source compatibility with pre-0.0.36 callers (e.g. :marks ex command); new code should use Editor::marks which iterates the unified map.

pub fn last_jump_back(&self) -> Option<(usize, usize)>

Position the cursor was at when the user last jumped via <C-o> / g; / similar. None before any jump.

pub fn last_edit_pos(&self) -> Option<(usize, usize)>

Position of the last edit (where . would replay). None if no edit has happened yet in this session.

pub fn file_marks(&self) -> impl Iterator<Item = (char, (usize, usize))> + '_

Read-only view of the file-marks table — uppercase / “file” marks ('A–'Z) the host has set this session. Returns an iterator of (mark_char, (row, col)) pairs.

Mutate via the FSM (m{A-Z} keystroke) or via Editor::restore_snapshot.

0.0.36: file marks now live in the unified Editor::marks map; this accessor is kept for source compatibility and filters the unified map to uppercase entries.

pub fn syntax_fold_ranges(&self) -> &[(usize, usize)]

Read-only view of the cached syntax-derived block ranges that :foldsyntax consumes. Returns the slice the host last installed via Editor::set_syntax_fold_ranges; empty when no syntax integration is active.

pub fn set_syntax_fold_ranges(&mut self, ranges: Vec<(usize, usize)>)

pub fn settings(&self) -> &Settings

Live settings (read-only). :set mutates these via Editor::settings_mut.

pub fn settings_mut(&mut self) -> &mut Settings

Live settings (mutable). :set flows through here to mutate shiftwidth / tabstop / textwidth / ignore_case / wrap. Hosts configuring at startup typically construct a [Settings] snapshot and overwrite via *editor.settings_mut() = ….

pub fn is_readonly(&self) -> bool

Returns true when :set readonly is active. Convenience accessor for hosts that cannot import the internal [Settings] type. Phase 5 binary uses this to gate :w writes.

pub fn search_state(&self) -> &SearchState

Borrow the engine search state. Hosts inspecting the committed / / ? pattern (e.g. for status-line display) or feeding the active regex into BufferView::search_pattern read it from here.

pub fn search_state_mut(&mut self) -> &mut SearchState

Mutable engine search state. Hosts driving search programmatically (test fixtures, scripted demos) write the pattern through here.

pub fn set_search_pattern(&mut self, pattern: Option<Regex>)

Install pattern as the active search regex on the engine state and clear the cached row matches. Pass None to clear. 0.0.37: dropped the buffer-side mirror that 0.0.35 introduced — BufferView now takes the regex through its search_pattern field per step 3 of DESIGN_33_METHOD_CLASSIFICATION.md.

pub fn search_advance_forward(&mut self, skip_current: bool) -> bool

Drive n (or the / commit equivalent) — advance the cursor to the next match of search_state.pattern from the cursor’s current position. Returns true when a match was found. skip_current = true excludes a match the cursor sits on.

pub fn search_advance_backward(&mut self, skip_current: bool) -> bool

Drive N — symmetric counterpart of Editor::search_advance_forward.

pub fn install_ratatui_syntax_spans( &mut self, spans: Vec<Vec<(usize, usize, Style)>>, )

Install styled syntax spans using ratatui::style::Style. The ratatui-flavoured variant of Editor::install_syntax_spans. Drops zero-width runs and clamps end to the line’s char length so the buffer cache doesn’t see runaway ranges. Behind the ratatui feature; non-ratatui hosts use the unprefixed Editor::install_syntax_spans (engine-native Style).

Renamed from install_syntax_spans in 0.0.32 — the unprefixed name now belongs to the engine-native variant per SPEC 0.1.0 freeze (“engine never imports ratatui”).

pub fn yank(&self) -> &str

Snapshot of the unnamed register (the default p / P source).

pub fn registers(&self) -> &Registers

Borrow the full register bank — ", "0–"9, "a–"z.

pub fn registers_mut(&mut self) -> &mut Registers

Mutably borrow the full register bank. Hosts that share registers across multiple editors (e.g. multi-buffer yy / p) overwrite the slots here on buffer switch.

pub fn sync_clipboard_register(&mut self, text: String, linewise: bool)

Host hook: load the OS clipboard’s contents into the "+ / "* register slot. the host calls this before letting vim consume a paste so "*p / "+p reflect the live clipboard rather than a stale snapshot from the last yank.

pub fn pending_register(&self) -> Option<char>

Return the user’s pending register selection (set via "<reg> chord before an operator). None if no register was selected — caller should use the unnamed register ".

Read-only — does not consume / clear the pending selection. The register is cleared by the engine after the next operator fires.

Promoted in 0.6.X for Phase 4e to let the App’s visual-op dispatch arm honor "a + visual op chord sequences.

pub fn pending_register_is_clipboard(&self) -> bool

True when the user’s pending register selector is + or *. the host peeks this so it can refresh sync_clipboard_register only when a clipboard read is actually about to happen.

pub fn recording_register(&self) -> Option<char>

Register currently being recorded into via q{reg}. None when no recording is active. Hosts use this to surface a “recording @r” indicator in the status line.

pub fn pending_count(&self) -> Option<u32>

Pending repeat count the user has typed but not yet resolved (e.g. pressing 5 before d). None when nothing is pending. Hosts surface this in a “showcmd” area.

pub fn pending_op(&self) -> Option<char>

The operator character for any in-flight operator that is waiting for a motion (e.g. d after the user types d but before a motion). Returns None when no operator is pending.

pub fn is_chord_pending(&self) -> bool

true when the engine is in any pending chord state — waiting for the next key to complete a command (e.g. r<char> replace, f<char> find, m<a> set-mark, '<a> goto-mark, operator-pending after d / c / y, g-prefix continuation, z-prefix continuation, register selection "<reg>, macro recording target, etc).

Hosts use this to bypass their own chord dispatch (keymap tries, etc.) and forward keys directly to the engine so in-flight commands can complete without the host eating their continuation keys.

pub fn is_insert_register_pending(&self) -> bool

true when insert_ctrl_r_arm() has been called and the dispatcher is waiting for the next typed character to name the register to paste. The dispatcher should call insert_paste_register(c) instead of insert_char(c) for the next printable key, then the flag auto-clears.

Phase 6.5: exposed so the app-level dispatch_insert_key can branch without having to drive the full FSM.

pub fn clear_insert_register_pending(&mut self)

Clear the Ctrl-R register-paste pending flag. Call this immediately before insert_paste_register(c) in app-level dispatchers so that the flag does not persist into the next key. Call before insert_paste_register_bridge (which hjkl_vim::insert does).

Phase 6.5: used by dispatch_insert_key in the app crate.

pub fn jump_list(&self) -> (&[(usize, usize)], &[(usize, usize)])

Read-only view of the jump-back list (positions pushed on “big” motions). Newest entry is at the back — Ctrl-o pops from there.

pub fn change_list(&self) -> (&[(usize, usize)], Option<usize>)

Read-only view of the change list (positions of recent edits) plus the current walk cursor. Newest entry is at the back.

pub fn set_yank(&mut self, text: impl Into<String>)

Replace the unnamed register without touching any other slot. For host-driven imports (e.g. system clipboard); operator code uses [record_yank] / [record_delete].

pub fn install_syntax_spans(&mut self, spans: Vec<Vec<(usize, usize, Style)>>)

Install styled syntax spans using the engine-native crate::types::Style. Always available, regardless of the ratatui feature. Hosts depending on ratatui can use the ratatui-flavoured Editor::install_ratatui_syntax_spans.

Renamed from install_engine_syntax_spans in 0.0.32 — at the 0.1.0 freeze the unprefixed name is the universally-available engine-native variant (“engine never imports ratatui”).

pub fn intern_ratatui_style(&mut self, style: Style) -> u32

Intern a ratatui::style::Style and return the opaque id used in hjkl_buffer::Span::style. The ratatui-flavoured variant of Editor::intern_style. Linear-scan dedup — the table grows only as new tree-sitter token kinds appear, so it stays tiny. Behind the ratatui feature.

Renamed from intern_style in 0.0.32 — at 0.1.0 freeze the unprefixed name belongs to the engine-native variant.

pub fn style_table(&self) -> &[Style]

Read-only view of the style table — id i → style_table[i]. The render path passes a closure backed by this slice as the StyleResolver for BufferView. Behind the ratatui feature.

pub fn buffer_spans(&self) -> &[Vec<Span>]

Per-row syntax span overlay, one Vec<Span> per buffer row. Hosts feed this slice into hjkl_buffer::BufferView::spans per draw frame.

0.0.37: replaces editor.buffer().spans() per step 3 of DESIGN_33_METHOD_CLASSIFICATION.md. The buffer no longer caches spans; they live on the engine and route through the Host::syntax_highlights pipeline.

pub fn intern_style(&mut self, style: Style) -> u32

Intern a SPEC crate::types::Style and return its opaque id. With the ratatui feature on, the id matches the one Editor::intern_ratatui_style would return for the equivalent ratatui::Style (both share the underlying table). With it off, the engine keeps a parallel crate::types::Style-keyed table — ids are still stable per-editor.

Hosts that don’t depend on ratatui (buffr, future GUI shells) reach this method to populate the table during syntax span installation.

Renamed from intern_engine_style in 0.0.32 — at 0.1.0 freeze the unprefixed name is the universally-available engine-native variant.

pub fn engine_style_at(&self, id: u32) -> Option<Style>

Look up an interned style by id and return it as a SPEC crate::types::Style. Returns None for ids past the end of the table.

pub fn push_buffer_cursor_to_textarea(&mut self)

Historical reverse-sync hook from when the textarea mirrored the buffer. Now that Buffer is the cursor authority this is a no-op; call sites can remain in place during the migration.

pub fn set_viewport_top(&mut self, row: usize)

Force the host viewport’s top row without touching the cursor. Used by tests that simulate a scroll without the SCROLLOFF cursor adjustment that scroll_down / scroll_up apply.

0.0.34 (Patch C-δ.1): writes through Host::viewport_mut instead of the (now-deleted) Buffer::viewport_mut.

pub fn jump_cursor(&mut self, row: usize, col: usize)

Set the cursor to (row, col), clamped to the buffer’s content. Hosts use this for goto-line, jump-to-mark, and programmatic cursor placement.

pub fn cursor(&self) -> (usize, usize)

(row, col) cursor read sourced from the migration buffer. Equivalent to self.textarea.cursor() when the two are in sync — which is the steady state during Phase 7f because every step opens with sync_buffer_content_from_textarea and every ported motion pushes the result back. Prefer this over self.textarea.cursor() so call sites keep working unchanged once the textarea field is ripped.

pub fn take_lsp_intent(&mut self) -> Option<LspIntent>

Drain any pending LSP intent raised by the last key. Returns None when no intent is armed.

pub fn take_fold_ops(&mut self) -> Vec<FoldOp>

Drain every crate::types::FoldOp raised since the last call. Hosts that mirror the engine’s fold storage (or that project folds onto a separate fold tree, LSP folding ranges, …) drain this each step and dispatch as their own crate::types::Host::Intent requires.

The engine has already applied every op locally against the in-tree hjkl_buffer::Buffer fold storage via crate::buffer_impl::BufferFoldProviderMut, so hosts that don’t track folds independently can ignore the queue (or simply never call this drain).

Introduced in 0.0.38 (Patch C-δ.4).

pub fn apply_fold_op(&mut self, op: FoldOp)

Dispatch a crate::types::FoldOp through the canonical fold surface: queue it for host observation (drained by Editor::take_fold_ops) and apply it locally against the in-tree buffer fold storage via crate::buffer_impl::BufferFoldProviderMut. Engine call sites (vim FSM z… chords, :fold* Ex commands, edit-pipeline invalidation) route every fold mutation through this method.

Introduced in 0.0.38 (Patch C-δ.4).

pub fn record_jump(&mut self, pos: (usize, usize))

Push a (row, col) onto the back-jumplist so Ctrl-o returns to it later. Used by host-driven jumps (e.g. gd) that move the cursor without going through the vim engine’s motion machinery, where push_jump fires automatically.

pub fn set_viewport_height(&self, height: u16)

Host apps call this each draw with the current text area height so scroll helpers can clamp the cursor without recomputing layout.

pub fn viewport_height_value(&self) -> u16

Last height published by set_viewport_height (in rows).

pub fn mutate_edit(&mut self, edit: Edit) -> Edit

Apply edit against the buffer and return the inverse so the host can push it onto an undo stack. Side effects: dirty flag, change-list ring, mark / jump-list shifts, change_log append, fold invalidation around the touched rows.

The primary edit funnel — both FSM operators and ex commands route mutations through here so the side effects fire uniformly.

pub fn mark_content_dirty(&mut self)

Single choke-point for “the buffer just changed”. Sets the dirty flag and drops the cached content_arc snapshot so subsequent reads rebuild from the live textarea. Callers mutating textarea directly (e.g. the TUI’s bracketed-paste path) must invoke this to keep the cache honest.

pub fn take_dirty(&mut self) -> bool

Returns true if content changed since the last call, then clears the flag.

pub fn take_content_edits(&mut self) -> Vec<ContentEdit>

Drain the queue of crate::types::ContentEdits emitted since the last call. Each entry corresponds to a single buffer mutation funnelled through Editor::mutate_edit; block edits fan out to one entry per row touched.

Hosts call this each frame (after Editor::take_content_reset) to fan edits into a tree-sitter parser via Tree::edit.

pub fn take_content_reset(&mut self) -> bool

Returns true if a bulk buffer replacement happened since the last call (e.g. set_content / restore / undo restore), then clears the flag. When this returns true, hosts should drop any retained syntax tree before consuming Editor::take_content_edits.

pub fn take_content_change(&mut self) -> Option<Arc<String>>

Pull-model coarse change observation. If content changed since the last call, returns Some(Arc<String>) with the new content and clears the dirty flag; otherwise returns None.

Hosts that need fine-grained edit deltas (e.g., DOM patching at the character level) should diff against their own previous snapshot. The SPEC take_changes() -> Vec<EditOp> API lands once every edit path inside the engine is instrumented; this coarse form covers the pull-model use case in the meantime.

pub fn cursor_screen_row(&mut self, height: u16) -> u16

Returns the cursor’s row within the visible textarea (0-based), updating the stored viewport top so subsequent calls remain accurate.

pub fn cursor_screen_pos( &self, area_x: u16, area_y: u16, area_width: u16, area_height: u16, ) -> Option<(u16, u16)>

Returns the cursor’s screen position (x, y) for the textarea described by (area_x, area_y, area_width, area_height). Accounts for line-number gutter and viewport scroll. Returns None if the cursor is outside the visible viewport. Always available (engine-native; no ratatui dependency).

Renamed from cursor_screen_pos_xywh in 0.0.32 — the ratatui-flavoured Rect variant is now Editor::cursor_screen_pos_in_rect (cfg ratatui).

pub fn cursor_screen_pos_in_rect(&self, area: Rect) -> Option<(u16, u16)>

Ratatui Rect-flavoured wrapper around Editor::cursor_screen_pos. Behind the ratatui feature.

Renamed from cursor_screen_pos in 0.0.32 — the unprefixed name now belongs to the engine-native variant.

pub fn vim_mode(&self) -> VimMode

Returns the current vim mode. Phase 6.3: reads from the stable current_mode field (kept in sync by both the FSM step loop and the Phase 6.3 primitive bridges) rather than deriving from the FSM-internal mode field via public_mode().

pub fn search_prompt(&self) -> Option<&SearchPrompt>

Bounds of the active visual-block rectangle as (top_row, bot_row, left_col, right_col) — all inclusive. None when we’re not in VisualBlock mode. Read-only view of the live / or ? prompt. None outside search-prompt mode.

pub fn last_search(&self) -> Option<&str>

Most recent committed search pattern (persists across n / N and across prompt exits). None before the first search.

pub fn last_search_forward(&self) -> bool

Whether the last committed search was a forward / (true) or a backward ? (false). n and N consult this to honour the direction the user committed.

pub fn set_last_search(&mut self, text: Option<String>, forward: bool)

Set the most recent committed search text + direction. Used by host-driven prompts (e.g. apps/hjkl’s / ? prompt that lives outside the engine’s vim FSM) so n / N repeat the host’s most recent commit with the right direction. Pass None / true to clear.

pub fn char_highlight(&self) -> Option<((usize, usize), (usize, usize))>

Start/end (row, col) of the active char-wise Visual selection (inclusive on both ends, positionally ordered). None when not in Visual mode.

pub fn line_highlight(&self) -> Option<(usize, usize)>

Top/bottom rows of the active VisualLine selection (inclusive). None when we’re not in VisualLine mode.

pub fn block_highlight(&self) -> Option<(usize, usize, usize, usize)>

pub fn buffer_selection(&self) -> Option<Selection>

Active selection in hjkl_buffer::Selection shape. None when not in a Visual mode. Phase 7d-i wiring — the host hands this straight to BufferView once render flips off textarea (Phase 7d-ii drops the paint_*_overlay calls on the same switch).

pub fn force_normal(&mut self)

Force back to normal mode (used when dismissing completions etc.)

pub fn content(&self) -> String

pub fn content_arc(&mut self) -> Arc<String>

Same logical output as [content], but returns a cached Arc<String> so back-to-back reads within an un-mutated window are ref-count bumps instead of multi-MB joins. The cache is invalidated by every [mark_content_dirty] call.

pub fn set_content(&mut self, text: &str)

pub fn take_changes(&mut self) -> Vec<Edit>

Drain the pending change log produced by buffer mutations.

Returns a Vec<EditOp> covering edits applied since the last call. Empty when no edits ran. Pull-model, complementary to Editor::take_content_change which gives back the new full content.

Mapping coverage:

• InsertChar / InsertStr → exact EditOp with empty range + replacement.
• DeleteRange (Char kind) → exact range + empty replacement.
• Replace → exact range + new replacement.
• DeleteRange (Line/Block), JoinLines, SplitLines, InsertBlock, DeleteBlockChunks → best-effort placeholder covering the touched range. Hosts wanting per-cell deltas should diff their own lines() snapshot.

pub fn current_options(&self) -> Options

Read the engine’s current settings as a SPEC crate::types::Options.

Bridges between the legacy [Settings] (which carries fewer fields than SPEC) and the planned 0.1.0 trait surface. Fields not present in Settings fall back to vim defaults (e.g., expandtab=false, wrapscan=true, timeout_len=1000ms). Once trait extraction lands, this becomes the canonical config reader and Settings retires.

pub fn apply_options(&mut self, opts: &Options)

Apply a SPEC crate::types::Options to the engine’s settings. Only the fields backed by today’s [Settings] take effect; remaining options become live once trait extraction wires them through.

pub fn selection_highlight(&self) -> Option<Highlight>

Active visual selection as a SPEC crate::types::Highlight with crate::types::HighlightKind::Selection.

Returns None when the editor isn’t in a Visual mode. Visual-line and visual-block selections collapse to the bounding char range of the selection — the SPEC Selection kind doesn’t carry sub-line info today; hosts that need full line / block geometry continue to read [buffer_selection] (the legacy hjkl_buffer::Selection shape).

pub fn highlights_for_line(&mut self, line: u32) -> Vec<Highlight>

SPEC-typed highlights for line.

Two emission modes:

• IncSearch: the user is typing a / or ? prompt and Editor::search_prompt is Some. Live-preview matches of the in-flight pattern surface as crate::types::HighlightKind::IncSearch.
• SearchMatch: the prompt has been committed (or absent) and the buffer’s armed pattern is non-empty. Matches surface as crate::types::HighlightKind::SearchMatch.

Selection / MatchParen / Syntax(id) variants land once the trait extraction routes the FSM’s selection set + the host’s syntax pipeline through the crate::types::Host trait.

Returns an empty vec when there is nothing to highlight or line is out of bounds.

pub fn render_frame(&self) -> RenderFrame

Build the engine’s crate::types::RenderFrame for the current state. Hosts call this once per redraw and diff across frames.

Coarse today — covers mode + cursor + cursor shape + viewport top + line count. SPEC-target fields (selections, highlights, command line, search prompt, status line) land once trait extraction routes them through SelectionSet and the Highlight pipeline.

pub fn take_snapshot(&self) -> EditorSnapshot

Capture the editor’s coarse state into a serde-friendly crate::types::EditorSnapshot.

Today’s snapshot covers mode, cursor, lines, viewport top. Registers, marks, jump list, undo tree, and full options arrive once phase 5 trait extraction lands the generic Editor<B: Buffer, H: Host> constructor — this method’s surface stays stable; only the snapshot’s internal fields grow.

Distinct from the internal snapshot used by undo (which returns (Vec<String>, (usize, usize))); host-facing persistence goes through this one.

pub fn restore_snapshot( &mut self, snap: EditorSnapshot, ) -> Result<(), EngineError>

Restore editor state from an [EditorSnapshot]. Returns crate::EngineError::SnapshotVersion if the snapshot’s version doesn’t match [EditorSnapshot::VERSION].

Mode is best-effort: SnapshotMode only round-trips the status-line summary, not the full FSM state. Visual / Insert mode entry happens through synthetic key dispatch when needed.

pub fn seed_yank(&mut self, text: String)

Install text as the pending yank buffer so the next p/P pastes it. Linewise is inferred from a trailing newline, matching how yy/dd shape their payload.

pub fn scroll_down(&mut self, rows: i16)

Scroll the viewport down by rows. The cursor stays on its absolute line (vim convention) unless the scroll would take it off-screen — in that case it’s clamped to the first row still visible.

pub fn scroll_up(&mut self, rows: i16)

Scroll the viewport up by rows. Cursor stays unless it would fall off the bottom of the new viewport, then clamp to the bottom-most visible row.

pub fn ensure_cursor_in_scrolloff(&mut self)

Scroll the viewport so the cursor stays at least SCROLLOFF rows from each edge. Replaces the bare Buffer::ensure_cursor_visible call at end-of-step so motions don’t park the cursor on the very last visible row.

pub fn goto_line(&mut self, line: usize)

pub fn jump_to(&mut self, line: usize, col: usize)

Jump the cursor to the given 1-based line/column, clamped to the document.

pub fn mouse_click(&mut self, area_x: u16, area_y: u16, col: u16, row: u16)

Jump cursor to the terminal-space mouse position; exits Visual modes if active. Engine-native coordinate flavour — pass the outer editor rect’s (x, y) plus the click (col, row). Always available (no ratatui dependency).

Renamed from mouse_click_xy in 0.0.32 — at 0.1.0 freeze the unprefixed name belongs to the universally-available variant.

pub fn mouse_click_in_rect(&mut self, area: Rect, col: u16, row: u16)

Ratatui Rect-flavoured wrapper around Editor::mouse_click. Behind the ratatui feature.

Renamed from mouse_click in 0.0.32 — the unprefixed name now belongs to the engine-native variant.

pub fn mouse_begin_drag(&mut self)

Begin a mouse-drag selection: anchor at current cursor and enter Visual mode.

pub fn mouse_extend_drag( &mut self, area_x: u16, area_y: u16, col: u16, row: u16, )

Extend an in-progress mouse drag to the given terminal-space position. Engine-native coordinate flavour. Always available.

Renamed from mouse_extend_drag_xy in 0.0.32 — at 0.1.0 freeze the unprefixed name belongs to the universally-available variant.

pub fn mouse_extend_drag_in_rect(&mut self, area: Rect, col: u16, row: u16)

Ratatui Rect-flavoured wrapper around Editor::mouse_extend_drag. Behind the ratatui feature.

Renamed from mouse_extend_drag in 0.0.32 — the unprefixed name now belongs to the engine-native variant.

pub fn insert_str(&mut self, text: &str)

pub fn accept_completion(&mut self, completion: &str)

pub fn undo(&mut self)

Walk one step back through the undo history. Equivalent to the user pressing u in normal mode. Drains the most recent undo entry and pushes it onto the redo stack.

pub fn redo(&mut self)

Walk one step forward through the redo history. Equivalent to <C-r> in normal mode.

pub fn push_undo(&mut self)

Snapshot current buffer state onto the undo stack and clear the redo stack. Bounded by settings.undo_levels — older entries pruned. Call before any group of buffer mutations the user might want to undo as a single step.

pub fn restore(&mut self, lines: Vec<String>, cursor: (usize, usize))

Replace the buffer with lines joined by \n and set the cursor to cursor. Used by undo / :e! / snapshot restore paths. Marks the editor dirty.

pub fn replace_char_at(&mut self, ch: char, count: usize)

Returns true if the key was consumed by the editor. Replace the char under the cursor with ch, count times. Matches vim r<x> semantics: cursor ends on the last replaced char, undo snapshot taken once at start. Promoted to public surface in 0.5.5 so hjkl-vim’s pending-state reducer can dispatch Replace without re-entering the FSM.

pub fn find_char(&mut self, ch: char, forward: bool, till: bool, count: usize)

Apply vim’s f<x> / F<x> / t<x> / T<x> motion. Moves the cursor to the count-th occurrence of ch on the current line, respecting forward (direction) and till (stop one char before target). Records last_find so ; / , repeat work.

No-op if the target char isn’t on the current line within range. Cursor / scroll / sticky-col semantics match f<x> via execute_motion.

pub fn after_g(&mut self, ch: char, count: usize)

Apply the g-chord effect for g<ch> with a pre-captured count. Mirrors the full handle_after_g dispatch table — gg, gj, gk, gv, gU / gu / g~ (→ operator-pending), gi, g*, g#, etc.

Promoted to public surface in 0.5.10 so hjkl-vim’s PendingState::AfterG reducer can dispatch AfterGChord without re-entering the engine FSM.

pub fn after_z(&mut self, ch: char, count: usize)

Apply the z-chord effect for z<ch> with a pre-captured count. Mirrors the full handle_after_z dispatch table — zz / zt / zb (scroll-cursor), zo / zc / za / zR / zM / zE / zd (fold ops), and zf (fold-add over visual selection or → op-pending).

Promoted to public surface in 0.5.11 so hjkl-vim’s PendingState::AfterZ reducer can dispatch AfterZChord without re-entering the engine FSM.

pub fn apply_op_motion( &mut self, op: Operator, motion_key: char, total_count: usize, )

Apply an operator over a single-key motion. op is the engine Operator and motion_key is the raw character (e.g. 'w', '$', 'G'). The engine resolves the char to a vim::Motion via parse_motion, applies the vim quirks (cw → ce, cW → cE, FindRepeat → stored find), then calls apply_op_with_motion. total_count is already the product of the prefix count and any inner count accumulated by the reducer.

No-op when motion_key does not map to a known motion (engine silently cancels the operator, matching vim’s behaviour on unknown motions).

Promoted to the public surface in 0.5.12 so the hjkl-vim PendingState::AfterOp reducer can dispatch ApplyOpMotion without re-entering the engine FSM.

pub fn apply_op_double(&mut self, op: Operator, total_count: usize)

Apply a doubled-letter line op (dd / yy / cc / >> / <<). total_count is the product of prefix count and inner count.

Promoted to the public surface in 0.5.12 so the hjkl-vim PendingState::AfterOp reducer can dispatch ApplyOpDouble without re-entering the engine FSM.

pub fn apply_op_find( &mut self, op: Operator, ch: char, forward: bool, till: bool, total_count: usize, )

Apply an operator over a find motion (df<x> / dF<x> / dt<x> / dT<x>). Builds Motion::Find { ch, forward, till }, applies it via apply_op_with_motion, records last_find for ; / , repeat, and updates last_change when op is Change (for dot-repeat).

total_count is the product of prefix count and any inner count accumulated by the reducer — already folded at transition time.

Promoted to the public surface in 0.5.14 so the hjkl-vim PendingState::OpFind reducer can dispatch ApplyOpFind without re-entering the engine FSM. handle_op_find_target (used by the chord-init op path) delegates here to avoid logic duplication.

pub fn apply_op_text_obj( &mut self, op: Operator, ch: char, inner: bool, total_count: usize, )

Apply an operator over a text-object range (diw / daw / di" etc.). Maps ch to a TextObject per the standard vim table, calls apply_op_with_text_object, and records last_change when op is Change (dot-repeat). Unknown ch values are silently ignored (no-op), matching the engine FSM’s behaviour on unrecognised text-object chars.

total_count is accepted for API symmetry with apply_op_motion / apply_op_find but is currently unused — text objects don’t repeat in vim’s current grammar. Kept for future-proofing.

Promoted to the public surface in 0.5.15 so the hjkl-vim PendingState::OpTextObj reducer can dispatch ApplyOpTextObj without re-entering the engine FSM. handle_text_object (chord-init op path) delegates to the shared apply_op_text_obj_inner helper to avoid logic duplication.

pub fn apply_op_g(&mut self, op: Operator, ch: char, total_count: usize)

Apply an operator over a g-chord motion or case-op linewise form (dgg / dge / dgE / dgj / dgk / gUgU etc.).

• If op is Uppercase/Lowercase/ToggleCase and ch matches the op’s letter (U/u/~), executes the line op (linewise form).
• Otherwise maps ch to a motion:
  • 'g' → Motion::FileTop (gg)
  • 'e' → Motion::WordEndBack (ge)
  • 'E' → Motion::BigWordEndBack (gE)
  • 'j' → Motion::ScreenDown (gj)
  • 'k' → Motion::ScreenUp (gk)
  • unknown → no-op (silently ignored, matching engine FSM behaviour)
• Updates last_change for dot-repeat when op is a change operator.

total_count is the already-folded product of prefix and inner counts.

Promoted to the public surface in 0.5.16 so the hjkl-vim PendingState::OpG reducer can dispatch ApplyOpG without re-entering the engine FSM. handle_op_after_g (chord-init op path) delegates to the shared apply_op_g_inner helper to avoid logic duplication.

pub fn delete_range( &mut self, start: (usize, usize), end: (usize, usize), kind: RangeKind, register: char, )

Delete the region [start, end) and stash the removed text in register. '"' selects the unnamed register (vim default); 'a'–'z' select named registers.

Pure range-mutation primitive — does not consume input. Called by hjkl-vim’s visual-mode operator path which has already resolved the range from the visual selection.

Promoted to the public surface in 0.6.7 for Phase 4 visual-mode op grammar migration (kryptic-sh/hjkl#70).

pub fn yank_range( &mut self, start: (usize, usize), end: (usize, usize), kind: RangeKind, register: char, )

Yank (copy) the region [start, end) into register without mutating the buffer. '"' selects the unnamed register; '0' the yank-only register; 'a'–'z' select named registers.

Pure range-mutation primitive — does not consume input. Called by hjkl-vim’s visual-mode operator path which has already resolved the range from the visual selection.

Promoted to the public surface in 0.6.7 for Phase 4 visual-mode op grammar migration (kryptic-sh/hjkl#70).

pub fn change_range( &mut self, start: (usize, usize), end: (usize, usize), kind: RangeKind, register: char, )

Delete the region [start, end) and transition to Insert mode (vim c operator). The deleted text is stashed in register. On return the editor is in Insert mode; the caller must not issue further normal-mode ops until the insert session ends.

Pure range-mutation primitive — does not consume input. Called by hjkl-vim’s visual-mode operator path which has already resolved the range from the visual selection.

Promoted to the public surface in 0.6.7 for Phase 4 visual-mode op grammar migration (kryptic-sh/hjkl#70).

pub fn indent_range( &mut self, start: (usize, usize), end: (usize, usize), count: i32, shiftwidth: u32, )

Indent (count > 0) or outdent (count < 0) the row span [start.0, end.0]. Column components are ignored — indent is always linewise. shiftwidth overrides the editor’s configured shiftwidth for this call; pass 0 to use the current editor setting. count == 0 is a no-op.

Pure range-mutation primitive — does not consume input. Called by hjkl-vim’s visual-mode operator path which has already resolved the range from the visual selection.

Promoted to the public surface in 0.6.7 for Phase 4 visual-mode op grammar migration (kryptic-sh/hjkl#70).

pub fn case_range( &mut self, start: (usize, usize), end: (usize, usize), kind: RangeKind, op: Operator, )

Apply a case transformation (Operator::Uppercase / Operator::Lowercase / Operator::ToggleCase) to the region [start, end). Other Operator variants are silently ignored (no-op). Yanks registers are left untouched — vim’s case operators do not write to registers.

Pure range-mutation primitive — does not consume input. Called by hjkl-vim’s visual-mode operator path which has already resolved the range from the visual selection.

Promoted to the public surface in 0.6.7 for Phase 4 visual-mode op grammar migration (kryptic-sh/hjkl#70).

pub fn delete_block( &mut self, top_row: usize, bot_row: usize, left_col: usize, right_col: usize, register: char, )

Delete a rectangular VisualBlock selection. top_row / bot_row are inclusive line bounds; left_col / right_col are inclusive column bounds at the visual (display) column level. Ragged-edge handling matches engine FSM’s VisualBlock op behavior — short lines that don’t reach right_col lose only the chars that exist.

register honors the user’s pending register selection.

Promoted in 0.6.X for Phase 4e block-op grammar migration.

pub fn yank_block( &mut self, top_row: usize, bot_row: usize, left_col: usize, right_col: usize, register: char, )

Yank a rectangular VisualBlock selection into register without mutating the buffer. '"' selects the unnamed register.

Promoted in 0.6.X for Phase 4e block-op grammar migration.

pub fn change_block( &mut self, top_row: usize, bot_row: usize, left_col: usize, right_col: usize, register: char, )

Delete a rectangular VisualBlock selection and enter Insert mode (c operator). The deleted text is stashed in register. Mode is Insert on return; the caller must not issue further normal-mode ops until the insert session ends.

Promoted in 0.6.X for Phase 4e block-op grammar migration.

pub fn indent_block( &mut self, top_row: usize, bot_row: usize, _left_col: usize, _right_col: usize, count: i32, )

Indent (count > 0) or outdent (count < 0) rows top_row..=bot_row. Column bounds are ignored — vim’s block indent is always linewise. count == 0 is a no-op.

Promoted in 0.6.X for Phase 4e block-op grammar migration.

pub fn text_object_inner_word(&self) -> Option<((usize, usize), (usize, usize))>

Resolve the range of iw (inner word) at the current cursor position.

An inner word is the contiguous run of keyword characters (or punctuation characters if the cursor is on punctuation) under the cursor, without any surrounding whitespace. Whitespace-only positions return None.

Pure function — does not move the cursor or change any editor state. Called by hjkl-vim’s OpTextObj reducer to resolve the range before invoking a range-mutation primitive (delete_range, etc.).

Promoted to the public surface in 0.6.X for Phase 4b text-object grammar migration (kryptic-sh/hjkl#70).

pub fn text_object_around_word( &self, ) -> Option<((usize, usize), (usize, usize))>

Resolve the range of aw (around word) at the current cursor position.

Like iw but extends the range to include trailing whitespace after the word. If no trailing whitespace exists, leading whitespace before the word is absorbed instead (vim :help text-objects behaviour).

Pure function — does not move the cursor or change any editor state.

Promoted to the public surface in 0.6.X for Phase 4b text-object grammar migration (kryptic-sh/hjkl#70).

pub fn text_object_inner_big_word( &self, ) -> Option<((usize, usize), (usize, usize))>

Resolve the range of iW (inner WORD) at the current cursor position.

A WORD is any contiguous run of non-whitespace characters — punctuation is not treated as a word boundary. Returns the span of the WORD under the cursor, without surrounding whitespace.

Pure function — does not move the cursor or change any editor state.

Promoted to the public surface in 0.6.X for Phase 4b text-object grammar migration (kryptic-sh/hjkl#70).

pub fn text_object_around_big_word( &self, ) -> Option<((usize, usize), (usize, usize))>

Resolve the range of aW (around WORD) at the current cursor position.

Like iW but extends the range to include trailing whitespace after the WORD. If no trailing whitespace exists, leading whitespace before the WORD is absorbed instead.

Pure function — does not move the cursor or change any editor state.

Promoted to the public surface in 0.6.X for Phase 4b text-object grammar migration (kryptic-sh/hjkl#70).

pub fn text_object_inner_quote( &self, quote: char, ) -> Option<((usize, usize), (usize, usize))>

Resolve the range of i<quote> (inner quote) at the cursor position.

quote is one of '"', '\'', or '`'. Returns None when the cursor’s line contains fewer than two occurrences of quote, or when no matching pair can be found around or ahead of the cursor.

Inner range excludes the quote characters themselves.

Pure function — no cursor mutation.

Promoted to the public surface in 0.6.X for Phase 4c text-object grammar migration (kryptic-sh/hjkl#70).

pub fn text_object_around_quote( &self, quote: char, ) -> Option<((usize, usize), (usize, usize))>

Resolve the range of a<quote> (around quote) at the cursor position.

Like i<quote> but includes the quote characters themselves plus surrounding whitespace on one side: trailing whitespace after the closing quote if any exists; otherwise leading whitespace before the opening quote. This matches vim :help text-objects behaviour.

Pure function — no cursor mutation.

Promoted to the public surface in 0.6.X for Phase 4c text-object grammar migration (kryptic-sh/hjkl#70).

pub fn text_object_inner_bracket( &self, open: char, ) -> Option<((usize, usize), (usize, usize))>

Resolve the range of i<bracket> (inner bracket pair) at the cursor.

open must be one of '(', '{', '[', '<' — the corresponding close bracket is derived automatically. Close-bracket chars (), }, ], >) are not accepted; hjkl-vim normalises close→open before calling this method. Returns None when no enclosing pair is found.

The cursor may be anywhere inside the pair or on a bracket character itself. When not inside any pair the resolver falls back to a forward scan (targets.vim-style: ci( works when the cursor is before ().

Inner range excludes the bracket characters. Multi-line pairs are supported; the returned range spans the full content between the brackets.

Pure function — no cursor mutation.

ib / iB aliases live in the hjkl-vim grammar layer and are not handled here.

Promoted to the public surface in 0.6.X for Phase 4c text-object grammar migration (kryptic-sh/hjkl#70).

pub fn text_object_around_bracket( &self, open: char, ) -> Option<((usize, usize), (usize, usize))>

Resolve the range of a<bracket> (around bracket pair) at the cursor.

Like i<bracket> but includes the bracket characters themselves. open must be one of '(', '{', '[', '<'.

Pure function — no cursor mutation.

aB alias lives in the hjkl-vim grammar layer and is not handled here.

Promoted to the public surface in 0.6.X for Phase 4c text-object grammar migration (kryptic-sh/hjkl#70).

pub fn text_object_inner_sentence( &self, ) -> Option<((usize, usize), (usize, usize))>

Resolve is (inner sentence) at the cursor position.

Returns the range of the current sentence, excluding trailing whitespace. Sentence boundaries follow vim’s is semantics (period / ? / ! followed by whitespace or end-of-paragraph).

Pure function — no cursor mutation.

Promoted to the public surface in 0.6.X for Phase 4d text-object grammar migration (kryptic-sh/hjkl#70).

pub fn text_object_around_sentence( &self, ) -> Option<((usize, usize), (usize, usize))>

Resolve as (around sentence) at the cursor position.

Like is but includes trailing whitespace after the sentence terminator.

Pure function — no cursor mutation.

Promoted to the public surface in 0.6.X for Phase 4d text-object grammar migration (kryptic-sh/hjkl#70).

pub fn text_object_inner_paragraph( &self, ) -> Option<((usize, usize), (usize, usize))>

Resolve ip (inner paragraph) at the cursor position.

A paragraph is a block of non-blank lines bounded by blank lines or buffer edges. Returns None when the cursor is on a blank line.

Pure function — no cursor mutation.

Promoted to the public surface in 0.6.X for Phase 4d text-object grammar migration (kryptic-sh/hjkl#70).

pub fn text_object_around_paragraph( &self, ) -> Option<((usize, usize), (usize, usize))>

Resolve ap (around paragraph) at the cursor position.

Like ip but includes one trailing blank line when present.

Pure function — no cursor mutation.

Promoted to the public surface in 0.6.X for Phase 4d text-object grammar migration (kryptic-sh/hjkl#70).

pub fn text_object_inner_tag(&self) -> Option<((usize, usize), (usize, usize))>

Resolve it (inner tag) at the cursor position.

Matches XML/HTML-style <tag>...</tag> pairs. Returns the range of inner content between the open and close tags (excluding the tags themselves).

Pure function — no cursor mutation.

Promoted to the public surface in 0.6.X for Phase 4d text-object grammar migration (kryptic-sh/hjkl#70).

pub fn text_object_around_tag(&self) -> Option<((usize, usize), (usize, usize))>

Resolve at (around tag) at the cursor position.

Like it but includes the open and close tag delimiters themselves.

Pure function — no cursor mutation.

Promoted to the public surface in 0.6.X for Phase 4d text-object grammar migration (kryptic-sh/hjkl#70).

pub fn apply_motion(&mut self, kind: MotionKind, count: usize)

Execute a named cursor motion kind repeated count times.

Maps the keymap-layer crate::MotionKind to the engine’s internal motion primitives, bypassing the engine FSM. Identical cursor semantics to the FSM path — sticky column, scroll sync, and big-jump tracking are all applied via vim::execute_motion (for Down/Up) or the same helpers used by the FSM arms.

Introduced in 0.6.1 as the host entry point for Phase 3a of kryptic-sh/hjkl#69: the app keymap dispatches AppAction::Motion and calls this method rather than re-entering the engine FSM.

Engine FSM arms for h/j/k/l/<BS>/<Space>/+/- remain intact for macro-replay coverage (macros re-feed raw keys through the FSM). This method is the keymap / controller path only.

pub fn set_pending_register(&mut self, reg: char)

Set vim.pending_register to Some(reg) if reg is a valid register selector (a–z, A–Z, 0–9, ", +, *, _). Invalid chars are silently ignored (no-op), matching the engine FSM’s handle_select_register behaviour.

Promoted to the public surface in 0.5.17 so the hjkl-vim PendingState::SelectRegister reducer can dispatch SetPendingRegister without re-entering the engine FSM. handle_select_register (engine FSM path for macro-replay / defensive coverage) delegates here to avoid logic duplication.

pub fn set_mark_at_cursor(&mut self, ch: char)

Record a mark named ch at the current cursor position.

Validates ch (must be a–z or A–Z to match vim’s mark-name rules). Invalid chars are silently ignored (no-op), matching the engine FSM’s handle_set_mark behaviour.

Promoted to the public surface in 0.6.7 so the hjkl-vim PendingState::SetMark reducer can dispatch EngineCmd::SetMark without re-entering the engine FSM. handle_set_mark delegates here.

pub fn replay_last_change(&mut self, count: usize)

. dot-repeat: replay the last buffered change at the current cursor. count scales repeats (e.g. 3. runs the last change 3 times). When count is 0, defaults to 1. No-op when no change has been buffered yet.

Storage of LastChange stays inside engine for now; Phase 5c of kryptic-sh/hjkl#71 just lifts the . chord binding into the app keymap so the engine FSM . arm is no longer the entry point. Engine FSM . arm stays for macro-replay defensive coverage.

pub fn goto_mark_line(&mut self, ch: char)

Jump to the mark named ch, linewise (row only; col snaps to first non-blank). Pushes the pre-jump position onto the jumplist if the cursor actually moved.

Accepts the same mark chars as vim’s '<ch> command: a–z, A–Z, '/` (jump-back peek), . (last edit), and the special auto-marks [, ], <, >. Unset marks and invalid chars are silently ignored (no-op), matching the engine FSM’s handle_goto_mark behaviour.

Promoted to the public surface in 0.6.7 so the hjkl-vim PendingState::GotoMarkLine reducer can dispatch EngineCmd::GotoMarkLine without re-entering the engine FSM.

pub fn goto_mark_char(&mut self, ch: char)

Jump to the mark named ch, charwise (exact row + col). Pushes the pre-jump position onto the jumplist if the cursor actually moved.

Accepts the same mark chars as vim’s `<ch> command: a–z, A–Z, '/` (jump-back peek), . (last edit), and the special auto-marks [, ], <, >. Unset marks and invalid chars are silently ignored (no-op), matching the engine FSM’s handle_goto_mark behaviour.

Promoted to the public surface in 0.6.7 so the hjkl-vim PendingState::GotoMarkChar reducer can dispatch EngineCmd::GotoMarkChar without re-entering the engine FSM.

pub fn start_macro_record(&mut self, reg: char)

Begin recording keystrokes into register reg. The caller (app) is responsible for stopping the recording via stop_macro_record when the user presses bare q.

• Uppercase reg (e.g. 'A') appends to the existing lowercase recording by pre-seeding recording_keys with the decoded text of the matching lowercase register, matching vim’s capital-register append semantics.
• Lowercase reg clears recording_keys (fresh recording).
• Invalid chars (non-alphabetic, non-digit) are silently ignored.

Promoted to the public surface in Phase 5b so the app’s route_chord_key can start a recording without re-entering the engine FSM. handle_record_macro_target (engine FSM path for macro-replay defensive coverage) continues to use the same logic via delegation.

pub fn stop_macro_record(&mut self)

Finalize the active recording: encode recording_keys as text and write to the matching (lowercase) named register. Clears both recording_macro and recording_keys. No-ops if no recording is active.

Promoted to the public surface in Phase 5b so the app’s QChord action can stop a recording when the user presses bare q without re-entering the engine FSM.

pub fn is_recording_macro(&self) -> bool

Returns true while a q{reg} recording is in progress. Hosts use this to show a “recording @r” status indicator and to decide whether bare q should stop the recording or open the RecordMacroTarget chord.

pub fn is_replaying_macro(&self) -> bool

Returns true while a macro is being replayed. The app sets this flag (via play_macro) and clears it (via end_macro_replay) around the re-feed loop so the recorder hook can skip double-capture.

pub fn play_macro(&mut self, reg: char, count: usize) -> Vec<Input>

Decode the named register reg into a Vec<crate::input::Input> and prepare for replay, returning the inputs the app should re-feed through route_chord_key.

Resolves reg:

• '@' → use vim.last_macro; returns empty vec if none.
• Any other char → lowercase it, read the register, decode.

Side-effects:

• Sets vim.last_macro to the resolved register.
• Sets vim.replaying_macro = true so the recorder hook skips during replay. The app calls end_macro_replay after the loop finishes.

Returns an empty vec (and no side-effects for '@') if the register is unset or empty.

pub fn end_macro_replay(&mut self)

Clear the replaying_macro flag. Called by the app after the re-feed loop in the PlayMacro commit arm completes (or aborts).

pub fn record_input(&mut self, input: Input)

Append input to the active recording (recording_keys) if and only if a recording is in progress AND we are not currently replaying. Called by the app’s route_chord_key recorder hook so that user keystrokes captured through the app-level chord path are recorded (rather than relying solely on the engine FSM’s in-step hook).

pub fn insert_char(&mut self, ch: char)

Insert ch at the cursor. In Replace mode, overstrike the cell under the cursor instead of inserting; at end-of-line, always appends. With smartindent on, closing brackets (}/)/]) trigger one-unit dedent on an otherwise-whitespace line.

Callers must ensure the editor is in Insert or Replace mode before calling this method.

pub fn insert_newline(&mut self)

Insert a newline at the cursor, applying autoindent / smartindent to prefix the new line with the appropriate leading whitespace.

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_tab(&mut self)

Insert a tab character (or spaces up to the next softtabstop boundary when expandtab is set).

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_backspace(&mut self)

Delete the character before the cursor (Backspace). With softtabstop active, deletes the entire soft-tab run at an aligned boundary. Joins with the previous line when at column 0.

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_delete(&mut self)

Delete the character under the cursor (Delete key). Joins with the next line when at end-of-line.

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_arrow(&mut self, dir: InsertDir)

Move the cursor one step in dir (arrow key), breaking the undo group per undo_break_on_motion.

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_home(&mut self)

Move the cursor to the start of the current line (Home key), breaking the undo group.

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_end(&mut self)

Move the cursor to the end of the current line (End key), breaking the undo group.

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_pageup(&mut self, viewport_h: u16)

Scroll up one full viewport height (PageUp), moving the cursor with it. viewport_h is the current viewport height in rows; pass self.viewport_height_value() if the stored value is current.

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_pagedown(&mut self, viewport_h: u16)

Scroll down one full viewport height (PageDown), moving the cursor with it. viewport_h is the current viewport height in rows.

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_ctrl_w(&mut self)

Delete from the cursor back to the start of the previous word (Ctrl-W). At column 0, joins with the previous line (vim b-motion semantics).

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_ctrl_u(&mut self)

Delete from the cursor back to the start of the current line (Ctrl-U). No-op when already at column 0.

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_ctrl_h(&mut self)

Delete one character backwards (Ctrl-H) — alias for Backspace in insert mode. Joins with the previous line when at col 0.

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_ctrl_o_arm(&mut self)

Enter “one-shot normal” mode (Ctrl-O): suspend insert for the next complete normal-mode command, then return to insert automatically.

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_ctrl_r_arm(&mut self)

Arm the register-paste selector (Ctrl-R). The next call to insert_paste_register(reg) will insert the register contents. Alternatively, feeding a Key::Char(c) through the FSM will consume the armed state and paste register c.

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_ctrl_t(&mut self)

Indent the current line by one shiftwidth and shift the cursor right by the same amount (Ctrl-T).

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_ctrl_d(&mut self)

Outdent the current line by up to one shiftwidth and shift the cursor left by the amount stripped (Ctrl-D).

Callers must ensure the editor is in Insert mode before calling.

pub fn insert_paste_register(&mut self, reg: char)

Paste the contents of register reg at the cursor (the commit arm of Ctrl-R {reg}). Unknown or empty registers are a no-op.

Callers must ensure the editor is in Insert mode before calling.

pub fn leave_insert_to_normal(&mut self)

Exit insert mode to Normal: finish the insert session, step the cursor one cell left (vim convention on Esc), record the gi target position, and update the sticky column.

Callers must ensure the editor is in Insert mode before calling.

pub fn enter_insert_i(&mut self, count: usize)

i — transition to Insert mode at the current cursor position. count is stored in the insert session and replayed by dot-repeat as a repeat count on the inserted text.

pub fn enter_insert_shift_i(&mut self, count: usize)

I — move to the first non-blank character on the line, then transition to Insert mode. count is stored for dot-repeat.

pub fn enter_insert_a(&mut self, count: usize)

a — advance the cursor one cell past the current position, then transition to Insert mode (append). count is stored for dot-repeat.

pub fn enter_insert_shift_a(&mut self, count: usize)

A — move the cursor to the end of the line, then transition to Insert mode (append at end). count is stored for dot-repeat.

pub fn open_line_below(&mut self, count: usize)

o — open a new line below the current line with smart-indent, then transition to Insert mode. count is stored for dot-repeat replay.

pub fn open_line_above(&mut self, count: usize)

O — open a new line above the current line with smart-indent, then transition to Insert mode. count is stored for dot-repeat replay.

pub fn enter_replace_mode(&mut self, count: usize)

R — enter Replace mode: subsequent typed characters overstrike the cell under the cursor rather than inserting. count is for replay.

pub fn delete_char_forward(&mut self, count: usize)

x — delete count characters forward from the cursor and write them to the unnamed register. No-op on an empty line. Records for ..

pub fn delete_char_backward(&mut self, count: usize)

X — delete count characters backward from the cursor and write them to the unnamed register. No-op at column 0. Records for ..

pub fn substitute_char(&mut self, count: usize)

s — substitute count characters: delete them (writing to the unnamed register) then enter Insert mode. Equivalent to cl. Records as OpMotion { Change, Right } for dot-repeat.

pub fn substitute_line(&mut self, count: usize)

S — substitute the current line: wipe its contents (writing to the unnamed register) then enter Insert mode. Equivalent to cc. Records as LineOp { Change } for dot-repeat.

pub fn delete_to_eol(&mut self)

D — delete from the cursor to end-of-line, writing to the unnamed register. The cursor parks on the new last character. Records for ..

pub fn change_to_eol(&mut self)

C — change from the cursor to end-of-line: delete to EOL then enter Insert mode. Equivalent to c$. Does not record its own last_change (the insert session records DeleteToEol on exit, like c motions).

pub fn yank_to_eol(&mut self, count: usize)

Y — yank from the cursor to end-of-line into the unnamed register. Vim 8 default: equivalent to y$. count multiplies the motion.

pub fn join_line(&mut self, count: usize)

J — join count lines (default 2) onto the current line, inserting a single space between each non-empty pair. Records for dot-repeat.

pub fn toggle_case_at_cursor(&mut self, count: usize)

~ — toggle the case of count characters from the cursor, advancing right after each toggle. Records ToggleCase for dot-repeat.

pub fn paste_after(&mut self, count: usize)

p — paste the unnamed register (or the register selected via "r) after the cursor. Linewise content opens a new line below; charwise content is inserted inline. Records Paste { before: false } for ..

pub fn paste_before(&mut self, count: usize)

P — paste the unnamed register (or the "r register) before the cursor. Linewise content opens a new line above; charwise is inline. Records Paste { before: true } for dot-repeat.

pub fn jump_back(&mut self, count: usize)

<C-o> — jump back count entries in the jumplist, saving the current position on the forward stack so <C-i> can return.

pub fn jump_forward(&mut self, count: usize)

<C-i> / Tab — redo count entries on the forward jumplist stack, saving the current position on the backward stack.

pub fn scroll_full_page(&mut self, dir: ScrollDir, count: usize)

<C-f> / <C-b> — scroll the cursor by one full viewport height (height − 2 rows, preserving two-line overlap). count multiplies. dir = Down for <C-f>, Up for <C-b>.

pub fn scroll_half_page(&mut self, dir: ScrollDir, count: usize)

<C-d> / <C-u> — scroll the cursor by half the viewport height. count multiplies the step. dir = Down for <C-d>, Up for <C-u>.

pub fn scroll_line(&mut self, dir: ScrollDir, count: usize)

<C-e> / <C-y> — scroll the viewport count lines without moving the cursor (cursor is clamped to the new visible region if necessary). dir = Down for <C-e> (scroll text up), Up for <C-y>.

pub fn search_repeat(&mut self, forward: bool, count: usize)

n — repeat the last / or ? search count times in its original direction. forward = true keeps the direction; false inverts (N).

pub fn word_search(&mut self, forward: bool, whole_word: bool, count: usize)

* / # / g* / g# — search for the word under the cursor. forward chooses direction; whole_word wraps the pattern in \b anchors (true for * / #, false for g* / g#). count repeats.

pub fn enter_visual_char(&mut self)

v from Normal — enter charwise Visual mode, anchoring the selection at the current cursor position.

pub fn enter_visual_line(&mut self)

V from Normal — enter linewise Visual mode, anchoring on the current line. Motions extend the selection by whole lines.

pub fn enter_visual_block(&mut self)

<C-v> from Normal — enter Visual-block mode. The selection is a rectangle whose corners are the anchor and the live cursor.

pub fn exit_visual_to_normal(&mut self)

Esc from any visual mode — set < / > marks, stash the selection for gv re-entry, then return to Normal mode.

pub fn visual_o_toggle(&mut self)

o in Visual / VisualLine / VisualBlock — swap the cursor and anchor so the user can extend the other end of the selection. Does NOT mutate the selection range; only the active endpoint changes.

pub fn reenter_last_visual(&mut self)

gv — restore the last visual selection (mode + anchor + cursor position). No-op when no visual selection has been exited yet.

pub fn set_mode(&mut self, mode: VimMode)

Direct mode-transition entry point. Sets both the internal FSM mode and the stable current_mode field read by Editor::vim_mode.

Prefer the semantic primitives (enter_visual_char, enter_insert_i, …) which also set up required bookkeeping (anchors, sessions, …). Use set_mode only when you need a raw mode flip without side-effects.

impl<H: Host> Editor<Buffer, H>

pub fn pending(&self) -> Pending

Return a clone of the current pending chord state.

pub fn set_pending(&mut self, p: Pending)

Overwrite the pending chord state.

pub fn take_pending(&mut self) -> Pending

Atomically take the pending chord, replacing it with Pending::None.

pub fn count(&self) -> usize

Return the raw digit-prefix count (0 = no prefix typed yet).

pub fn set_count(&mut self, c: usize)

Overwrite the digit-prefix count directly.

pub fn accumulate_count_digit(&mut self, digit: usize)

Accumulate one more digit into the count prefix (mirrors count * 10 + digit).

pub fn reset_count(&mut self)

Reset the count prefix to zero (no pending count).

pub fn take_count(&mut self) -> usize

Consume the count and return it; resets to zero. Returns 1 when no prefix was typed (mirrors take_count in vim.rs).

pub fn fsm_mode(&self) -> Mode

Return the FSM-internal mode (Normal / Insert / Visual / …).

pub fn set_fsm_mode(&mut self, m: Mode)

Overwrite the FSM-internal mode without side-effects. Prefer the semantic primitives (enter_insert_i, enter_visual_char, …).

pub fn is_replaying(&self) -> bool

true while the . dot-repeat replay is running.

pub fn set_replaying(&mut self, v: bool)

Set or clear the dot-replay flag.

pub fn is_one_shot_normal(&self) -> bool

true when we entered Normal from Insert via Ctrl-o and will return to Insert after the next complete command.

pub fn set_one_shot_normal(&mut self, v: bool)

Set or clear the Ctrl-o one-shot-normal flag.

pub fn last_find(&self) -> Option<(char, bool, bool)>

Return the last f/F/t/T target as (char, forward, till), or None before any find command was executed.

pub fn set_last_find(&mut self, target: Option<(char, bool, bool)>)

Overwrite the stored last-find target.

pub fn last_change(&self) -> Option<LastChange>

Return a clone of the last recorded mutating change, or None before any change has been made.

pub fn set_last_change(&mut self, lc: Option<LastChange>)

Overwrite the stored last-change record.

pub fn last_change_mut(&mut self) -> Option<&mut LastChange>

Borrow the last-change record mutably (e.g. to fill in an inserted field after the insert session completes).

pub fn insert_session(&self) -> Option<&InsertSession>

Borrow the active insert session, or None when not in Insert mode.

pub fn insert_session_mut(&mut self) -> Option<&mut InsertSession>

Borrow the active insert session mutably.

pub fn take_insert_session(&mut self) -> Option<InsertSession>

Atomically take the insert session out, leaving None.

pub fn set_insert_session(&mut self, s: Option<InsertSession>)

Install a new insert session, replacing any existing one.

pub fn visual_anchor(&self) -> (usize, usize)

Return the charwise Visual-mode anchor (row, col).

pub fn set_visual_anchor(&mut self, anchor: (usize, usize))

Overwrite the charwise Visual-mode anchor.

pub fn visual_line_anchor(&self) -> usize

Return the VisualLine anchor row.

pub fn set_visual_line_anchor(&mut self, row: usize)

Overwrite the VisualLine anchor row.

pub fn block_anchor(&self) -> (usize, usize)

Return the VisualBlock anchor (row, col).

pub fn set_block_anchor(&mut self, anchor: (usize, usize))

Overwrite the VisualBlock anchor.

pub fn block_vcol(&self) -> usize

Return the VisualBlock virtual column used to survive j/k row clamping.

pub fn set_block_vcol(&mut self, vcol: usize)

Overwrite the VisualBlock virtual column.

pub fn yank_linewise(&self) -> bool

true when the last yank/cut was linewise (affects p/P layout).

pub fn set_yank_linewise(&mut self, v: bool)

Set or clear the linewise-yank flag.

pub fn set_pending_register_raw(&mut self, reg: Option<char>)

Overwrite the pending register selector (Phase 6.6b mutator companion to the existing pending_register() getter).

pub fn take_pending_register_raw(&mut self) -> Option<char>

Atomically take the pending register, returning None afterward.

pub fn recording_macro(&self) -> Option<char>

Return the register currently being recorded into, or None.

pub fn set_recording_macro(&mut self, reg: Option<char>)

Overwrite the recording-macro target register.

pub fn push_recording_key(&mut self, input: Input)

Append one input to the in-progress macro recording buffer.

pub fn take_recording_keys(&mut self) -> Vec<Input>

Atomically take the recorded key sequence, leaving an empty vec.

pub fn set_recording_keys(&mut self, keys: Vec<Input>)

Overwrite the recording-keys buffer (e.g. to seed from a register).

pub fn is_replaying_macro_raw(&self) -> bool

true while @reg macro replay is running (suppresses re-recording).

pub fn set_replaying_macro_raw(&mut self, v: bool)

Set or clear the macro-replay-in-progress flag.

pub fn last_macro(&self) -> Option<char>

Return the register of the most recently played macro (@@ source).

pub fn set_last_macro(&mut self, reg: Option<char>)

Overwrite the last-played-macro register.

pub fn last_insert_pos(&self) -> Option<(usize, usize)>

Return the cursor position when Insert mode was last exited (for gi).

pub fn set_last_insert_pos(&mut self, pos: Option<(usize, usize)>)

Overwrite the stored last-insert position.

pub fn last_visual(&self) -> Option<LastVisual>

Return the saved visual selection snapshot for gv, or None.

pub fn set_last_visual(&mut self, snap: Option<LastVisual>)

Overwrite the saved visual selection snapshot.

pub fn viewport_pinned(&self) -> bool

true when zz/zt/zb pinned the viewport this step (suppresses the end-of-step scrolloff pass).

pub fn set_viewport_pinned(&mut self, v: bool)

Set or clear the viewport-pinned flag.

pub fn insert_pending_register(&self) -> bool

true while waiting for the register-name key after Ctrl-R in Insert mode.

pub fn set_insert_pending_register(&mut self, v: bool)

Set or clear the Ctrl-R register-wait flag.

pub fn change_mark_start(&self) -> Option<(usize, usize)>

Return the stashed [ mark start for a Change operation, or None.

pub fn take_change_mark_start(&mut self) -> Option<(usize, usize)>

Atomically take the change-mark start, leaving None.

pub fn set_change_mark_start(&mut self, pos: Option<(usize, usize)>)

Overwrite the change-mark start.

pub fn last_input_at(&self) -> Option<Instant>

Return the wall-clock Instant of the last keystroke.

pub fn set_last_input_at(&mut self, t: Option<Instant>)

Overwrite the wall-clock last-input timestamp.

pub fn last_input_host_at(&self) -> Option<Duration>

Return the Host::now() duration at the last keystroke.

pub fn set_last_input_host_at(&mut self, d: Option<Duration>)

Overwrite the host-clock last-input timestamp.

pub fn search_prompt_state(&self) -> Option<&SearchPrompt>

Borrow the live search prompt, or None when not in search-prompt mode.

pub fn search_prompt_state_mut(&mut self) -> Option<&mut SearchPrompt>

Borrow the live search prompt mutably.

pub fn take_search_prompt_state(&mut self) -> Option<SearchPrompt>

Atomically take the search prompt, leaving None.

pub fn set_search_prompt_state(&mut self, prompt: Option<SearchPrompt>)

Install a new search prompt (entering search-prompt mode).

pub fn last_search_pattern(&self) -> Option<&str>

Return the most recently committed search pattern, or None.

pub fn set_last_search_pattern_only(&mut self, pattern: Option<String>)

Overwrite the stored last-search pattern without changing direction (use the existing set_last_search for the combined update).

pub fn set_last_search_forward_only(&mut self, forward: bool)

Overwrite only the last-search direction flag.

pub fn search_history(&self) -> &[String]

Borrow the committed search-pattern history (oldest first).

pub fn search_history_mut(&mut self) -> &mut Vec<String>

Borrow the search history mutably (e.g. to push a new entry).

pub fn search_history_cursor(&self) -> Option<usize>

Return the current search-history navigation cursor index.

pub fn set_search_history_cursor(&mut self, idx: Option<usize>)

Overwrite the search-history navigation cursor.

pub fn jump_back_list(&self) -> &[(usize, usize)]

Borrow the back half of the jump list (entries Ctrl-o pops from).

pub fn jump_back_list_mut(&mut self) -> &mut Vec<(usize, usize)>

Borrow the back jump list mutably (push / pop).

pub fn jump_fwd_list(&self) -> &[(usize, usize)]

Borrow the forward half of the jump list (entries Ctrl-i pops from).

pub fn jump_fwd_list_mut(&mut self) -> &mut Vec<(usize, usize)>

Borrow the forward jump list mutably (push / pop / clear).

pub fn push_search_pattern(&mut self, pattern: &str)

Compile pattern into a regex and install it as the active search pattern. Respects :set ignorecase / :set smartcase. An empty or invalid pattern clears the highlight without raising an error.

pub fn push_jump(&mut self, from: (usize, usize))

Record a pre-jump cursor position onto the back jumplist. Called before any “big jump” motion (gg/G, %, */#, n/N, committed / or ?, …). Branching off the history clears the forward half, matching vim’s “redo-is-lost” semantics.

pub fn record_search_history(&mut self, pattern: &str)

Push pattern onto the committed search history. Skips if the most recent entry already matches (consecutive dedupe) and trims the oldest entries beyond the history cap.

pub fn walk_search_history(&mut self, dir: isize)

Walk the search-prompt history by dir steps. dir = -1 moves toward older entries (Ctrl-P / Up); dir = 1 toward newer ones (Ctrl-N / Down). Stops at the ends; does nothing if there is no active search prompt.

pub fn begin_step(&mut self, input: Input) -> Result<StepBookkeeping, bool>

Pre-dispatch bookkeeping that must run before every per-mode FSM step.

Call this at the start of every step; pass the returned StepBookkeeping to [end_step] after the FSM body finishes.

Returns Ok(bk) when the caller should proceed with FSM dispatch. Returns Err(consumed) when the prelude itself handled the input (macro-stop chord); in that case skip the FSM body and do NOT call end_step — the macro-stop path is a true short-circuit with no epilogue needed.

This method does NOT handle the search-prompt intercept — callers must check search_prompt_state().is_some() before calling begin_step and dispatch to the search-prompt FSM body directly.

pub fn end_step( &mut self, input: Input, bk: StepBookkeeping, consumed: bool, ) -> bool

Post-dispatch bookkeeping that must run after every per-mode FSM step.

input is the same input that was passed to begin_step. bk is the StepBookkeeping returned by begin_step. consumed is the return value of the FSM body; this method returns it after running all epilogue invariants.

Must NOT be called when begin_step returned Err(...).

pub fn is_visual(&self) -> bool

true when the editor is in any visual mode (Visual / VisualLine / VisualBlock). Convenience wrapper around vim_mode() for hjkl-vim.

pub fn visual_block_bounds(&self) -> (usize, usize, usize, usize)

Compute the VisualBlock rectangle corners: (top_row, bot_row, left_col, right_col). Uses block_anchor and block_vcol (the virtual column, which survives j/k clamping to shorter rows).

Promoted in Phase 6.6e so hjkl-vim::normal can compute the block extents needed for VisualBlock I / A / r without accessing engine-private helpers.

pub fn line_char_count(&self, row: usize) -> usize

Return the character count (code-point count) of line row, or 0 when row is out of range. Used by hjkl-vim::normal for VisualBlock I / A column computations.

pub fn apply_op_with_motion_direct( &mut self, op: Operator, motion: &Motion, count: usize, )

Apply operator over motion with count repetitions. The full vim-quirks path (operator context for l, clamping, etc.) is applied.

Promoted to the public surface in Phase 6.6e so hjkl-vim::normal’s relocated handle_after_op can call it directly with a parsed Motion without re-entering the engine FSM.

pub fn adjust_number(&mut self, delta: i64)

Ctrl-a / Ctrl-x — adjust the number under or after the cursor. delta = 1 increments; delta = -1 decrements; larger deltas multiply as in vim’s 5<C-a>. Promoted in Phase 6.6e so hjkl-vim::normal can dispatch Ctrl-a / Ctrl-x.

pub fn enter_search(&mut self, forward: bool)

Open the / or ? search prompt. forward = true for /, false for ?. Promoted in Phase 6.6e so hjkl-vim::normal can dispatch / and ? without re-entering the engine FSM.

pub fn visual_block_insert_at_left( &mut self, top: usize, bot: usize, col: usize, )

Enter Insert mode at the left edge of a VisualBlock selection for I. Moves the cursor to (top, col), resets to Normal internally, then begins an insert session with InsertReason::BlockEdge.

Promoted in Phase 6.6e so hjkl-vim::normal can dispatch the VisualBlock I command without accessing engine-private helpers.

pub fn visual_block_append_at_right( &mut self, top: usize, bot: usize, col: usize, )

Enter Insert mode at the right edge of a VisualBlock selection for A. Moves the cursor to (top, col), resets to Normal internally, then begins an insert session with InsertReason::BlockEdge.

Promoted in Phase 6.6e so hjkl-vim::normal can dispatch the VisualBlock A command without accessing engine-private helpers.

pub fn execute_motion(&mut self, motion: Motion, count: usize)

Execute a motion (cursor movement), push to the jumplist for big jumps, and update the sticky column. Mirrors the engine FSM’s execute_motion free function. Promoted in Phase 6.6e for hjkl-vim::normal.

pub fn update_block_vcol(&mut self, motion: &Motion)

Update the VisualBlock virtual column after a motion in VisualBlock mode. Horizontal motions sync block_vcol to the cursor column; vertical / non-h/l motions leave it alone so the intended column survives clamping to shorter rows. Promoted in Phase 6.6e for hjkl-vim::normal.

pub fn apply_visual_operator(&mut self, op: Operator)

Apply op over the current visual selection (char-wise, linewise, or block). Mirrors the engine’s internal apply_visual_operator free fn. Promoted in Phase 6.6e for hjkl-vim::normal.

pub fn replace_block_char(&mut self, ch: char)

Replace each character cell in the current VisualBlock selection with ch. Mirrors the engine’s block_replace free fn. Promoted in Phase 6.6e for the VisualBlock r<ch> command in hjkl-vim::normal.

pub fn visual_text_obj_extend(&mut self, ch: char, inner: bool)

Extend the current visual selection to cover the text object identified by ch and inner. Maps ch to a TextObject, resolves its range via text_object_range, then updates the visual anchor and cursor.

Promoted in Phase 6.6e for the visual-mode i<ch> / a<ch> commands in hjkl-vim::normal::handle_visual_text_obj.