> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sinelaw/fresh/llms.txt
> Use this file to discover all available pages before exploring further.

# Overlays API

> Add visual decorations to buffer text without modifying content

The Overlays API allows you to add visual decorations to buffer text - such as syntax highlighting, error markers, search results, and more - without modifying the actual buffer content.

## Overlay Operations

### addOverlay

Add a visual overlay to a buffer range.

```typescript theme={null}
addOverlay(
  buffer_id: number,
  namespace: string,
  start: number,
  end: number,
  r: number,
  g: number,
  b: number,
  bg_r: number,
  bg_g: number,
  bg_b: number,
  underline: boolean,
  bold: boolean,
  italic: boolean,
  extend_to_line_end: boolean
): boolean
```

<ParamField path="buffer_id" type="number" required>
  Target buffer ID
</ParamField>

<ParamField path="namespace" type="string" required>
  Namespace for grouping (use for batch removal)
</ParamField>

<ParamField path="start" type="number" required>
  Start byte offset
</ParamField>

<ParamField path="end" type="number" required>
  End byte offset
</ParamField>

<ParamField path="r" type="number" required>
  Foreground red (0-255)
</ParamField>

<ParamField path="g" type="number" required>
  Foreground green (0-255)
</ParamField>

<ParamField path="b" type="number" required>
  Foreground blue (0-255)
</ParamField>

<ParamField path="bg_r" type="number" required>
  Background red (0-255, or -1 for transparent)
</ParamField>

<ParamField path="bg_g" type="number" required>
  Background green (0-255, or -1 for transparent)
</ParamField>

<ParamField path="bg_b" type="number" required>
  Background blue (0-255, or -1 for transparent)
</ParamField>

<ParamField path="underline" type="boolean" required>
  Add underline decoration
</ParamField>

<ParamField path="bold" type="boolean" required>
  Use bold text
</ParamField>

<ParamField path="italic" type="boolean" required>
  Use italic text
</ParamField>

<ParamField path="extend_to_line_end" type="boolean" required>
  Extend background to end of visual line
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if overlay was added successfully
</ResponseField>

<Note>
  Overlays persist until explicitly removed. Use namespaces for batch removal (e.g., "spell", "todo"). Multiple overlays can apply to the same range; colors blend.
</Note>

**Example:**

```typescript theme={null}
// Highlight TODO comments in orange
const bufferId = editor.getActiveBufferId();
const text = await editor.getBufferText(bufferId, 0, 1000);
const match = text.match(/TODO:/i);

if (match) {
  editor.addOverlay(
    bufferId,
    "todo-highlight",  // namespace
    match.index!,       // start
    match.index! + match[0].length,  // end
    255, 165, 0,       // orange foreground
    -1, -1, -1,        // transparent background
    false,             // no underline
    true,              // bold
    false,             // not italic
    false              // don't extend to line end
  );
}
```

### removeOverlay

Remove a specific overlay by its handle.

```typescript theme={null}
removeOverlay(buffer_id: number, handle: string): boolean
```

<ParamField path="buffer_id" type="number" required>
  The buffer ID
</ParamField>

<ParamField path="handle" type="string" required>
  The overlay handle to remove
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if overlay was removed
</ResponseField>

### clearNamespace

Clear all overlays in a namespace.

```typescript theme={null}
clearNamespace(buffer_id: number, namespace: string): boolean
```

<ParamField path="buffer_id" type="number" required>
  The buffer ID
</ParamField>

<ParamField path="namespace" type="string" required>
  The namespace to clear
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if namespace was cleared
</ResponseField>

**Example:**

```typescript theme={null}
// Clear all TODO highlights
editor.clearNamespace(bufferId, "todo-highlight");
```

### clearOverlaysInRange

Clear all overlays that overlap with a byte range.

```typescript theme={null}
clearOverlaysInRange(buffer_id: number, start: number, end: number): boolean
```

<ParamField path="buffer_id" type="number" required>
  The buffer ID
</ParamField>

<ParamField path="start" type="number" required>
  Start byte position (inclusive)
</ParamField>

<ParamField path="end" type="number" required>
  End byte position (exclusive)
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if overlays were cleared
</ResponseField>

### clearAllOverlays

Remove all overlays from a buffer.

```typescript theme={null}
clearAllOverlays(buffer_id: number): boolean
```

<ParamField path="buffer_id" type="number" required>
  The buffer ID
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if all overlays were cleared
</ResponseField>

## Virtual Text

Virtual text appears inline in the buffer without modifying the actual content. Useful for displaying inline hints, diagnostics, or git blame information.

### addVirtualText

Add virtual text (inline decoration) at a position.

```typescript theme={null}
addVirtualText(
  buffer_id: number,
  virtual_text_id: string,
  position: number,
  text: string,
  r: number,
  g: number,
  b: number,
  before: boolean,
  use_bg: boolean
): boolean
```

<ParamField path="buffer_id" type="number" required>
  The buffer ID
</ParamField>

<ParamField path="virtual_text_id" type="string" required>
  Unique identifier for this virtual text
</ParamField>

<ParamField path="position" type="number" required>
  Byte position to insert at
</ParamField>

<ParamField path="text" type="string" required>
  The virtual text to display
</ParamField>

<ParamField path="r" type="number" required>
  Red color component (0-255)
</ParamField>

<ParamField path="g" type="number" required>
  Green color component (0-255)
</ParamField>

<ParamField path="b" type="number" required>
  Blue color component (0-255)
</ParamField>

<ParamField path="before" type="boolean" required>
  Whether to insert before (true) or after (false) the position
</ParamField>

<ParamField path="use_bg" type="boolean" required>
  Whether to use the color as background (true) or foreground (false)
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if virtual text was added
</ResponseField>

**Example:**

```typescript theme={null}
// Add inline type hint
const bufferId = editor.getActiveBufferId();
const position = editor.getCursorPosition();

editor.addVirtualText(
  bufferId,
  "type-hint-1",
  position,
  " : string",
  128, 128, 128,  // gray color
  false,          // insert after
  false           // use as foreground
);
```

### removeVirtualText

Remove virtual text by ID.

```typescript theme={null}
removeVirtualText(buffer_id: number, virtual_text_id: string): boolean
```

<ParamField path="buffer_id" type="number" required>
  The buffer ID
</ParamField>

<ParamField path="virtual_text_id" type="string" required>
  The virtual text ID to remove
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if virtual text was removed
</ResponseField>

### removeVirtualTextsByPrefix

Remove all virtual texts with IDs starting with a prefix.

```typescript theme={null}
removeVirtualTextsByPrefix(buffer_id: number, prefix: string): boolean
```

<ParamField path="buffer_id" type="number" required>
  The buffer ID
</ParamField>

<ParamField path="prefix" type="string" required>
  The prefix to match virtual text IDs against
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if virtual texts were removed
</ResponseField>

**Example:**

```typescript theme={null}
// Remove all type hints
editor.removeVirtualTextsByPrefix(bufferId, "type-hint-");
```

### clearVirtualTexts

Remove all virtual texts from a buffer.

```typescript theme={null}
clearVirtualTexts(buffer_id: number): boolean
```

<ParamField path="buffer_id" type="number" required>
  The buffer ID
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if all virtual texts were cleared
</ResponseField>

### clearVirtualTextNamespace

Clear all virtual texts in a namespace.

```typescript theme={null}
clearVirtualTextNamespace(buffer_id: number, namespace: string): boolean
```

<ParamField path="buffer_id" type="number" required>
  The buffer ID
</ParamField>

<ParamField path="namespace" type="string" required>
  The namespace to clear (e.g., "git-blame")
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if namespace was cleared
</ResponseField>

## Line Decorations

### addVirtualLine

Add a virtual line above or below a source line.

```typescript theme={null}
addVirtualLine(
  buffer_id: number,
  position: number,
  text: string,
  fg_r: number,
  fg_g: number,
  fg_b: number,
  bg_r: number,
  bg_g: number,
  bg_b: number,
  above: boolean,
  namespace: string,
  priority: number
): boolean
```

<ParamField path="buffer_id" type="number" required>
  The buffer ID
</ParamField>

<ParamField path="position" type="number" required>
  Byte position to anchor the virtual line to
</ParamField>

<ParamField path="text" type="string" required>
  The text content of the virtual line
</ParamField>

<ParamField path="fg_r" type="number" required>
  Foreground red color component (0-255)
</ParamField>

<ParamField path="fg_g" type="number" required>
  Foreground green color component (0-255)
</ParamField>

<ParamField path="fg_b" type="number" required>
  Foreground blue color component (0-255)
</ParamField>

<ParamField path="bg_r" type="number" required>
  Background red color component (0-255), -1 for transparent
</ParamField>

<ParamField path="bg_g" type="number" required>
  Background green color component (0-255), -1 for transparent
</ParamField>

<ParamField path="bg_b" type="number" required>
  Background blue color component (0-255), -1 for transparent
</ParamField>

<ParamField path="above" type="boolean" required>
  Whether to insert above (true) or below (false) the line
</ParamField>

<ParamField path="namespace" type="string" required>
  Namespace for bulk removal (e.g., "git-blame")
</ParamField>

<ParamField path="priority" type="number" required>
  Priority for ordering multiple lines at same position
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if virtual line was added
</ResponseField>

### setLineIndicator

Set a line indicator in the gutter's indicator column.

```typescript theme={null}
setLineIndicator(
  buffer_id: number,
  line: number,
  namespace: string,
  symbol: string,
  r: number,
  g: number,
  b: number,
  priority: number
): boolean
```

<ParamField path="buffer_id" type="number" required>
  The buffer ID
</ParamField>

<ParamField path="line" type="number" required>
  Line number (0-indexed)
</ParamField>

<ParamField path="namespace" type="string" required>
  Namespace for grouping (e.g., "git-gutter", "breakpoints")
</ParamField>

<ParamField path="symbol" type="string" required>
  Symbol to display (e.g., "│", "●", "★")
</ParamField>

<ParamField path="r" type="number" required>
  Red color component (0-255)
</ParamField>

<ParamField path="g" type="number" required>
  Green color component (0-255)
</ParamField>

<ParamField path="b" type="number" required>
  Blue color component (0-255)
</ParamField>

<ParamField path="priority" type="number" required>
  Priority for display when multiple indicators exist (higher wins)
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if line indicator was set
</ResponseField>

**Example:**

```typescript theme={null}
// Add git gutter indicator for modified line
editor.setLineIndicator(
  bufferId,
  42,                 // line number
  "git-gutter",       // namespace
  "│",                // symbol
  255, 200, 0,        // orange color
  100                 // priority
);
```

### clearLineIndicators

Clear all line indicators for a specific namespace.

```typescript theme={null}
clearLineIndicators(buffer_id: number, namespace: string): boolean
```

<ParamField path="buffer_id" type="number" required>
  The buffer ID
</ParamField>

<ParamField path="namespace" type="string" required>
  Namespace to clear (e.g., "git-gutter")
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if line indicators were cleared
</ResponseField>

## Examples

### Highlight search results

```typescript theme={null}
function highlightSearchResults(bufferId: number, query: string) {
  // Clear existing highlights
  editor.clearNamespace(bufferId, "search");
  
  // Get buffer content
  const length = editor.getBufferLength(bufferId);
  const text = await editor.getBufferText(bufferId, 0, length);
  
  // Find all matches
  const regex = new RegExp(query, "gi");
  let match;
  
  while ((match = regex.exec(text)) !== null) {
    editor.addOverlay(
      bufferId,
      "search",
      match.index,
      match.index + match[0].length,
      0, 0, 0,           // black text
      255, 255, 0,       // yellow background
      false, false, false, false
    );
  }
}
```

### Show inline diagnostics

```typescript theme={null}
function showDiagnostics(bufferId: number) {
  const diagnostics = editor.getAllDiagnostics();
  const path = editor.getBufferPath(bufferId);
  
  for (const diag of diagnostics) {
    if (diag.uri.endsWith(path)) {
      const message = ` ← ${diag.message}`;
      const position = /* calculate byte position from diag.range */;
      
      editor.addVirtualText(
        bufferId,
        `diag-${position}`,
        position,
        message,
        255, 0, 0,  // red for errors
        false,      // after position
        false       // foreground color
      );
    }
  }
}
```