Forem: Guilherme Costa

How Code Telescope Handles Syntax Highlighting in a VS Code Webview

Guilherme Costa — Sun, 22 Mar 2026 02:05:02 +0000

When I started building Code Telescope — a Telescope.nvim-inspired fuzzy finder for VS Code — one of the hardest parts wasn't the fuzzy matching or the file indexing. It was the preview panel.

The preview needs to show syntax-highlighted code, update in real time as you navigate between files, and do all of this inside a VS Code webview — which is essentially a sandboxed iframe with no access to VS Code's own editor APIs.

Here's how I built it.

The Constraints

VS Code webviews are isolated. You can't use the editor's built-in tokenizer, you can't access TextMate grammars directly, and you can't load arbitrary node modules. Everything that runs in the webview is browser code.

This meant I needed a full syntax highlighting pipeline running entirely in the browser, capable of:

Loading language grammars on demand
Supporting whatever color theme the user has active in VS Code
Rendering large files without freezing the UI
Updating fast enough to feel instant while navigating

I chose Shiki as the highlighting engine. It uses the same TextMate grammar engine as VS Code, which means it produces accurate, consistent results. But making it work inside a webview with dynamic grammars and themes required some non-trivial plumbing.

Loading Grammars Dynamically

Shiki normally loads grammars from bundled imports. That doesn't work in a webview — the bundle size would be enormous, and you'd be shipping grammars for hundreds of languages the user never needs.

Instead, I load grammars on demand from the extension host via a message bridge.

When the preview needs to highlight a file, it checks if the language grammar is already loaded. If not, it sends a request to the backend:

static async loadLanguageIfNeeded(langId: string): AsyncResult<LanguageGrammar> {
  if (this.loadedLanguages.has(langId) && this.langMap.has(langId)) {
    return { ok: true, value: this.langMap.get(langId) };
  }

  const langGrammar = await MessageBridge.request<LanguageGrammar>("langGrammar", langId);
  return await this.registerLanguage(langGrammar);
}

On the backend, the extension reads the grammar directly from the VS Code extensions installed on the machine — not from a bundled copy:

for (const ext of vscode.extensions.all) {
  const grammars = ext.packageJSON.contributes?.grammars;
  const matched = grammars?.find((g: any) => g.scopeName === targetScope);
  if (!matched) continue;

  const grammarUri = vscode.Uri.joinPath(ext.extensionUri, matched.path);
  const bytes = await vscode.workspace.fs.readFile(grammarUri);
  const grammarJson = JsoncParser.parse(new TextDecoder().decode(bytes));
  // ...
}

This means Code Telescope automatically supports any language grammar that's installed in VS Code — including extensions the user has added themselves. No bundled grammar list to maintain.

The same approach applies to themes: the active color theme is resolved from the extension host and sent to the webview as raw JSON, which Shiki loads at runtime.

Chunked Rendering for Large Files

Loading the entire file content into the DOM at once doesn't scale. A 5000-line TypeScript file would take hundreds of milliseconds to tokenize and render, freezing the UI entirely.

The solution is chunked rendering. The file is split into chunks of 30 lines, and only the chunks near the visible area are rendered. As the user scrolls, new chunks are appended or prepended on demand.

const CHUNK_SIZE = 30;

const renderChunk = async (chunkIndex: number, position: "append" | "prepend" = "append") => {
  const start = chunkIndex * CHUNK_SIZE;
  const end = Math.min(start + CHUNK_SIZE, totalLines);
  const chunkText = getChunkText(start, end);

  const result = this.highlighter.codeToTokens(chunkText, {
    lang: finalLanguageId,
    theme: finalThemeName,
    ...(prevGrammarState ? { grammarState: prevGrammarState } : {}),
  });

  const html = makeHtmlFromTokens(result.tokens, themeBg, themeFg, ...);
  this.insertChunkIntoDOM(previewElement, html, chunkIndex, position);
};

For very large files (content over 5000 characters), a LazyLineParser pre-indexes line offsets instead of splitting the entire string upfront:

private indexLines(): void {
  this.lineOffsets = [0];
  let pos = 0;

  while ((pos = this.text.indexOf("\n", pos)) !== -1) {
    pos++;
    this.lineOffsets.push(pos);
  }
}

This allows slicing arbitrary line ranges in O(1) without holding the entire split array in memory.

The GrammarState Problem

Shiki's tokenizer is stateful. To correctly highlight line 500 of a TypeScript file, it needs to know what state the parser was in at line 499 — whether it was inside a template literal, a block comment, a generic type, and so on.

When you jump to the middle of a file and start rendering from chunk 16, Shiki has no idea about the context accumulated in chunks 0–15. The result is incorrect highlighting — tokens that should be orange come out white.

Shiki exposes a grammarState object that can be passed between tokenization calls to carry this context forward. The fix is to run a warmup pass that tokenizes chunks 0 through N-1 without rendering them — just to accumulate the grammar states:

const warmupChunks = async (): Promise<boolean> => {
  for (let i = 0; i < initialChunk; i += BATCH_SIZE) {
    if (this.abortController?.signal.aborted) return false;

    for (let j = i; j < Math.min(i + BATCH_SIZE, initialChunk); j++) {
      const result = this.highlighter.codeToTokens(chunkText, {
        lang: finalLanguageId,
        theme: finalThemeName,
        ...(prevState ? { grammarState: prevState } : {}),
      });
      if (result.grammarState) {
        this.grammarStates.set(j, result.grammarState as GrammarState);
      }
    }

    // yield between batches to avoid blocking the thread
    await new Promise((r) => setTimeout(r, 0));
  }

  return true;
};

The warmup runs in background after the initial render. The chunk is first rendered with whatever state is available (possibly wrong), then re-rendered with the correct state once the warmup completes.

Caching GrammarStates Per File

The warmup adds latency — tokenizing 30 chunks in the background takes time, especially on large files. And if the user navigates away before it finishes, the abort controller cancels the operation and the states are discarded.

The solution is to cache the grammar states per file path. Once a warmup completes successfully, the accumulated states are stored:

warmupChunks().then((completed) => {
  if (!completed || this.abortController?.signal.aborted) return;

  // only persist if warmup completed without abort
  this.grammarStateCache.set(cacheKey, new Map(this.grammarStates));

  // re-render the initial chunk with correct state
  this.loadedChunks.delete(initialChunk);
  this.chunkHtmlCache.delete(initialChunk);
  renderChunk(initialChunk);
});

On subsequent visits to the same file, the cached states are restored before rendering — the warmup is skipped entirely and the first render is already correct.

The cache key is the file path. Partial warmups (aborted mid-way) are never persisted, so the cache always contains complete, reliable state maps.

Scroll-Driven Chunk Loading

Once the initial chunks are rendered, a scroll listener loads more chunks as the user scrolls:

this.scrollHandler = () => {
  requestAnimationFrame(async () => {
    const { scrollTop, scrollHeight, clientHeight } = previewElement;

    if (scrollTop + clientHeight >= scrollHeight - SCROLL_THRESHOLD) {
      await renderChunk(this.maxLoadedChunk + 1, "append");
    }

    if (scrollTop <= SCROLL_THRESHOLD) {
      await renderChunk(this.minLoadedChunk - 1, "prepend");
    }
  });
};

When prepending chunks, the scroll position is adjusted to prevent the viewport from jumping:

const oldScrollTop = previewElement.scrollTop;
const oldScrollHeight = previewElement.scrollHeight;
previewElement.prepend(chunkContainer);
previewElement.scrollTop = oldScrollTop + (previewElement.scrollHeight - oldScrollHeight);

The Result

The preview panel renders large files without blocking the UI, supports any language grammar installed in VS Code, applies the user's active color theme, and correctly highlights code even when jumping to the middle of a file.

Most of the complexity is invisible to the user — they just see fast, accurate syntax highlighting as they navigate.

Code Telescope is open source. If you're a Neovim user who ended up in VS Code and misses Telescope, give it a try.

Code Telescope: bringing Telescope's power to VS Code

Guilherme Costa — Sat, 14 Feb 2026 18:38:46 +0000

If you're a Neovim user, you've probably heard of (or use) Telescope.nvim

One of the most powerful tools in the Neovim ecosystem for fuzzy navigation—files, text, symbols, git commits, branches, and more, all in a single interface.

What if you could have that same experience in VS Code?

That's the motivation behind Code Telescope—an extension that brings Telescope's philosophy to Visual Studio Code.

🎯 The Problem It Solves

Let's be honest: VS Code already has several ways to search for things:

Ctrl+P for files
Ctrl+Shift+F for text
Ctrl+Shift+O for symbols
Ctrl+Shift+G for git

But each of these is a different interface, with different behaviors, and different keyboard shortcuts. There's no unified "hub" for searching.

Code Telescope solves this by providing a single interface that abstracts all these functionalities—and more—into a consistent, extensible, and powerful fuzzy finder.

🏗️ Architecture: Extensibility via Decorators

The extension is built on three architectural pillars:

Annotation-based adapters — Each finder is registered via decorators
Backend/UI separation — Extension host (backend) separate from webview (UI)
Type-safe communication — Shared interfaces between layers

┌─────────────────────────────────────────────────────────────┐
│                    Extension Host (Backend)                 │
│  ┌─────────────────┐                                        │
│  │ Finder Providers│                                        │
│  │ @FuzzyFinder()  │                                        │
│  └────────┬────────┘                                        │
│           │                                                 │
│           │                                                 │
│           │                                                 │
│    ┌──────▼────────┐                                        │
│    │ Presentation  │                                        │
│    │     Layer     │                                        │
│    │  - Registry   │                                        │
│    │  - Handlers   │                                        │
│    └──────┬────────┘                                        │
└───────────┼─────────────────────────────────────────────────┘
            │ Message Protocol (type-safe)
┌───────────┼─────────────────────────────────────────────────┐
│    ┌──────▼────────┐           Webview (UI)                 │
│    │   Webview     │                                        │
│    │  Controller   │                                        │
│    └──────┬────────┘                                        │
│           │                                                 │
│           ┼────────────────┐                                │
│           │                │                                │
│     ┌─────▼─────┐  ┌───────▼────────┐                       │
│     │   Data    │  │    Preview     │                       │
│     │  Adapters │  │   Renderers    │                       │
│     └───────────┘  │ @PreviewRender │                       │
│                    │      ()        │                       │
│                    └────────┬───────┘                       │
│                             │                               │
│                    ┌────────▼────────┐                      │
│                    │    Keyboard     │                      │
│                    │    Handlers     │                      │
│                    └─────────────────┘                      │
└─────────────────────────────────────────────────────────────┘

🔌 Finders (Backend)

Finders are data providers registered via @FuzzyFinderAdapter:

@FuzzyFinderAdapter({
  fuzzy: "workspace.files",
})
export class WorkspaceFileProvider implements IFuzzyFinderProvider {
  async querySelectableOptions(): Promise<QueryResult> {
    // Return list of files
  }

  async onSelect(identifier: string): Promise<SelectResult> {
    // Action on selection (open file, navigate, etc.)
  }
}

🔄 Data Adapters (UI)

On the UI side, data adapters transform backend data into displayable options:

export class FileDataAdapter implements IFuzzyFinderDataAdapter {
  parseOptions(data: any): FileOption[] {
    // Convert backend data to UI options
  }

  getDisplayText(option: FileOption): string {
    // Define how the option appears in the list
  }

  filterOption(option: FileOption, query: string): boolean {
    // Custom filtering logic
  }
}

Data adapters are the bridge between raw backend responses and the interactive list shown to users.

🎨 Preview Renderers (UI)

Preview renderers are also on the UI side and transform raw data into visual representations, registered via @PreviewRendererAdapter:

@PreviewRendererAdapter({
  adapter: "preview.codeHighlighted",
})
export class CodeHighlightedPreviewRenderer implements IPreviewRendererAdapter {
  async render(
    previewElement: HTMLElement,
    data: PreviewData,
    theme: string
  ): Promise<void> {
    // Render syntax-highlighted code in the preview pane
  }
}

This keeps the backend clean—it only provides data—while the UI is responsible for how that data looks.
Code Telescope supports any VS Code theme out of the box. The preview uses Shiki as the syntax highlighter, optimized for minimal bundle size by loading only the necessary grammars on-demand. This means syntax highlighting that perfectly matches your current theme—whether you're using Dracula, One Dark Pro, or any custom theme—without bloating the extension.

📦 What's Built-In

The extension ships with a complete suite of finders:

Workspace files — Fuzzy matching across all files
Text search — Integrated ripgrep
Symbols — Functions, classes, variables
Git branches — Quick branch switching
Keybindings — Browse VS Code shortcuts
Recent files — Recently opened files
Color schemes — Theme switching
Diagnostics — Errors, warnings, hints
Tasks — Workspace tasks
Call hierarchy — Function call relationships

And the best part: all with inline preview and keyboard-only navigation.

🎯 Harpoon: Bookmarking Style

Inspired by ThePrimeagen's Harpoon, I also included a bookmarking system:

Mark files with Ctrl+Alt+M
Navigate with Ctrl+1 through Ctrl+9
View all marks with Ctrl+Alt+H
Persists per workspace

This allows instant navigation to your most important files—no searching required.

🔧 Extensibility: Creating Your Own Finders

One of the coolest parts: you can create custom finders without touching the extension code.

Just create a .cjs file in .vscode/code-telescope/:

module.exports = {
  fuzzyAdapterType: "custom.example",

  backend: {
    async querySelectableOptions() {
      return { items: ["Item 1", "Item 2"] };
    },

    async onSelect(item) {
      return { data: item, action: "showMessage" };
    }
  },

  ui: {
    dataAdapter: {
      parseOptions(data) {
        return data.items.map((item, i) => ({ id: i, text: item }));
      },
      getDisplayText(option) {
        return option.text;
      },
      filterOption(option, query) {
        return option.text.toLowerCase().includes(query.toLowerCase());
      }
    }
  }
};

The system does the rest—automatic wiring via the type system. You can check an example here

🤔 Why This Architecture?

I chose this design for several reasons:

Decoupling — Finders don't know about UI, UI doesn't know about implementation details
Testability — Each component can be tested independently
Type safety — Compile-time guarantees prevent integration bugs
Extensibility — New finders without touching existing code

The decorator-based approach means the registry is built at compile-time, and the message protocol ensures the backend and UI stay in sync.

💡 Inspiration

Obviously, Telescope.nvim by tjdevries (TJ DeVries) was the main inspiration—the fuzzy finder that revolutionized Neovim navigation.

And Harpoon by ThePrimeagen—the bookmarking system that changed how we think about file navigation.

What makes Telescope special isn't just the functionality—it's the extensibility and the unified experience. Code Telescope tries to capture that same essence.

If you use VS Code and miss Telescope's power, check it out on the VS Code Marketplace or Open VSX.
Youtube video explaining (It is in portuguese BR, but you can enable automatic translation)

Check code on Github

Feedback and contributions are welcome!