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 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 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 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

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 feed_input(&mut self, input: PlannedInput) -> bool

Feed an SPEC crate::PlannedInput into the engine.

Bridge for hosts that don’t carry crossterm — buffr’s CEF shell, future GUI frontends. Converts directly to the engine’s internal Input type and dispatches through the vim FSM, bypassing crossterm entirely so this entry point is always available regardless of the crossterm feature.

Input::Mouse, Input::Paste, Input::FocusGained, Input::FocusLost, and Input::Resize currently fall through without effect — the legacy FSM doesn’t dispatch them. They’re accepted so the host can pump them into the engine without special-casing.

Returns true when the keystroke was consumed.

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: MotionKind, 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: MotionKind, 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: MotionKind, 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: MotionKind, 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 hjkl_vim::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 handle_key(&mut self, key: KeyEvent) -> bool