Struct Editor 

pub struct Editor<'a> {
    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.

Implementations

impl<'a> Editor<'a>

pub fn new(keybinding_mode: KeybindingMode) -> Self

pub fn set_syntax_fold_ranges(&mut self, ranges: Vec<(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.

pub fn settings(&self) -> &Settings

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

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

Install styled syntax spans into both the host-visible cache (styled_spans) and the buffer’s opaque-id span table. Drops zero-width runs and clamps end to the line’s char length so the buffer cache doesn’t see runaway ranges. Replaces the previous set_syntax_spans + sync_buffer_spans_from_textarea round-trip.

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 intern_style(&mut self, style: Style) -> u32

Intern a ratatui::style::Style and return the opaque id used in hjkl_buffer::Span::style. The render-side StyleResolver closure (built by [Editor::style_resolver]) uses the id to look up the style back. Linear-scan dedup — the table grows only as new tree-sitter token kinds appear, so it stays tiny.

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.

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

Intern a SPEC crate::types::Style and return its opaque id. The id matches the one [intern_style] would return for the equivalent ratatui::Style — both methods share the underlying table.

Hosts that don’t depend on ratatui (buffr, future GUI shells) reach this method to populate the table during syntax span installation. Internally converts to ratatui::Style today; the trait extraction will flip the storage to engine-native.

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 buffer(&self) -> &Buffer

Borrow the migration buffer. Host renders through this via hjkl_buffer::BufferView.

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

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

Force the buffer 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. Note: does not touch the textarea — the migration buffer’s viewport is what BufferView renders from, and the textarea’s own scroll path would clamp the cursor into its (often-zero) visible window.

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 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 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: Rect) -> Option<(u16, u16)>

Returns the cursor’s screen position (x, y) for area (the textarea rect). Accounts for line-number gutter and viewport scroll. Returns None if the cursor is outside the visible viewport.

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

Today’s emission is search-match-only: when the buffer has an armed search pattern, every regex hit on that line surfaces as a crate::types::Highlight with kind crate::types::HighlightKind::SearchMatch. Selection, IncSearch, MatchParen, and Syntax 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 the buffer has no search pattern 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: Rect, col: u16, row: u16)

Jump cursor to the terminal-space mouse position; exits Visual modes if active.

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: Rect, col: u16, row: u16)

Extend an in-progress mouse drag to the given terminal-space position.

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

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

pub fn handle_key(&mut self, key: KeyEvent) -> bool

Returns true if the key was consumed by the editor.