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

Returns true if the key was consumed by the editor.