Module insert 

Insert-mode completion – the editor surface that turns the existing pipeline (cmdline today) into a buffer-level input flow.

Behavioural spec lives in docs/dev/architecture/insert-completion.md. This module is the data-flow layer: state types, trigger enum, sync source trait, fuzzy matcher tuned for code completion, and the per-buffer aggregator that holds it all together. The host (lattice-ui-tui) owns the async glue (LSP request fan-out, tokio spawn, the popup widget); this crate stays sync + pure-data so plugins can target it without pulling in tokio.

Two kinds of source

• Sync (InsertSource). Buffer-words, snippets, path, tree-sitter – everything that runs in microseconds. The aggregator calls produce() directly when the popup query changes.
• Async (host-orchestrated). LSP, plugin generators, anything that round-trips. The host spawns a tokio task that pushes RawCandidates through a channel into InsertCompletionState::raw; the aggregator coalesces pushes on a 16 ms tick and re-runs matcher / ranker.

The split keeps this crate dependency-light. Hosts add the async dance; we don’t.

Structs

BufferWordsSource

Sync source emitting word-completions from a buffer’s text. Cheap enough to walk the rope once per query change. Words shorter than min_word_length are skipped; duplicates are deduped.

DocPopupState

One side popup showing the focused candidate’s full documentation. Lazy: not opened until <C-d> / cmd:completion-toggle-docs flips it on.

FuzzyInsertMatcher

Built-in fuzzy matcher tuned for Insert-mode completion.

InsertCompletionState

Live state for an in-flight Insert-mode completion. Held by the host (App.insert_completion: Option<…>) while the popup is up; dropped on dismiss. Per-source channels and cancellation tokens live host-side – they pull in tokio types this crate avoids – so this struct stays dependency-light enough that any host (TUI today, GPU later) can reuse it.

InsertContext

Snapshot of editor state a source reads when producing candidates. Held by reference so the aggregator borrows from the surrounding frame for the duration of produce().

InsertRanker

Built-in ranker tuned for Insert-mode completion. Sorts by final_score descending, where:

PerLanguageOverrides

Per-language overrides for the insert-completion popup. Each field is Option so a TOML override at [completion.per-language.<lang>] can flip exactly the keys it cares about; unset fields fall back to the global typed option (or, for sources, “every enabled source contributes”).

SourceId

Stable identifier for a source. Strings keep the registry transparent ("gen:lsp-completion", "gen:buffer-words", "plugin:foo"); the host’s per-source priority / enable config keys off this string so users see the same name in :set completion.source.<id>.priority=… and in :help completion-sources.

Enums

CompletionTrigger

What opened the popup. Stays constant for the popup’s lifetime; rides on LSP completion requests as CompletionTriggerKind.

Constants

LSP_COMPLETION_SOURCE_ID

Source id for the host-orchestrated LSP completion source.

PATH_SOURCE_ID

Source id for the host-orchestrated path-completion source (Phase 4.2.g.6 (2/2)). Triggered when the cursor sits inside a string literal (per tree-sitter scope detection); walks the directory of the partial path and emits filesystem entries.

SNIPPET_SOURCE_ID

Source id for the host-orchestrated snippet completion source.

TREE_SITTER_SYMBOL_SOURCE_ID

Source id for the host-orchestrated tree-sitter local-symbol source (Phase 4.2.g.6 (1/2)). Walks the buffer’s syntax tree per popup-trigger via lattice_syntax::Syntax::collect_symbols.

Traits

InsertSource

A sync candidate source. Implementations are cheap to call – the aggregator invokes produce() once per query change (a re-filter on each keystroke). Async sources don’t implement this trait; they are orchestrated host-side via tokio::spawn + a channel that pushes into InsertCompletionState.raw directly.

Functions

canonical_source_id

Map a user-friendly source label ("lsp", "snippet", "buffer-words") to its canonical source id. Unknown labels pass through as-is, so plugin sources can be referenced by their full id ("plugin:my-source").

fuzzy_match

Free-function fuzzy match – the algorithm beneath FuzzyInsertMatcher. Exposed so surfaces that need to match on a string other than RawCandidate.text (e.g. the vertico picker, which matches on the user-visible display while text carries a routing payload) get the same 5-tier scoring without duplicating the algorithm.

per_language_defaults

Spec-driven defaults shipping with v1 (docs/dev/architecture/insert-completion.md §9). Markdown / text restrict to snippet + buffer-words (no LSP for prose); rust enables auto-fire + auto-insert-single since rust-analyzer’s items are precise.