IncrementalHighlighter

A stateful, single-threaded highlighter that reuses prior parse / capture / span work across successive update calls. Use this for editor-style scenarios where the source code changes incrementally; for one-shot or whole-file recomposition the existing highlight / rememberHighlightedString paths remain the right choice.

Thread-safety: instances are not thread-safe. Every update and close call must happen on the same thread (or be externally serialised). Sharing an instance across a UI thread and a background dispatcher is unsafe — the engine holds its own tree-sitter Query cursor whose state would be corrupted by concurrent access.

The first call to update runs the same code path as highlight (full parse + full query iteration). Subsequent calls reuse the previous parse tree via tree-sitter's incremental parse, run the highlights query only over the byte range affected by the edit, and splice the resulting captures into the cached span list. When the new code equals the previous code, update short-circuits to a theme re-resolve only.

Instances must be closed; closing is idempotent. After closing, update throws IllegalStateException. Native memory of the underlying Tree / Parser / Query is reclaimed by ktreesitter's Cleaner once the engine becomes garbage-collectible.