Add ESC key handler to dismiss highlights

- Add command to clear brace matching and property-argument highlights
- Bind ESC key to clear highlights command (C# files only)
- Add tests for ESC handler functionality
- Update documentation with ESC feature

Author: willibrandon

CLAUDE.md

@@ -85,13 +85,14 @@ vsce publish
 - **Project Setup**: package.json, TypeScript config, webpack bundling, extension entry point
 - **Core Parsing**: Template parser, expression parser & tokenizer, string literal parser, Serilog call detector
 - **Decoration-based Highlighting**: Full highlighting system with decoration manager
+- **Brace Matching**: Real-time brace pair highlighting with multi-line support
+- **Property-Argument Highlighting**: Visual connection between template properties and arguments
+- **Navigation Provider**: Code actions to jump from properties to their arguments
+- **ESC Handler**: Keyboard shortcut (ESC key) to temporarily dismiss highlights
 - **Performance Optimization**: Caching system, debouncing, LRU cache for templates
 - **Theme Management**: Automatic theme detection and WCAG AA compliant colors
 - **Testing Infrastructure**: Jest setup with comprehensive test coverage
 - **Configuration**: Extensive user customization options
-- **Property-Argument Highlighting**: Cursor-based highlighting showing connection between properties and arguments
-- **Navigation Provider**: Code actions to jump from properties to their arguments
-- **Brace Matching**: Highlights matching braces in all Serilog contexts (templates, expressions, output templates)
 
 ### 🚫 Not Implemented (by design)
 - **Semantic Tokens Provider**: Replaced with decoration-based approach for better control

Example/README.md

@@ -94,11 +94,12 @@ Open `Program.cs` in Visual Studio with the Serilog Syntax extension installed t
 Colors automatically adapt for light themes with WCAG AA compliant contrast ratios - darker variants of the same color families for optimal readability on light backgrounds.
 
 ### Interactive Features
-- **Brace matching** when cursor is on `{` or `}` in any Serilog context
-- **Property-Argument highlighting** when cursor is on a property or argument
-- **Light bulb navigation** from properties to arguments
-- **Immediate highlighting** as you type (before closing quotes)
-- **Multi-line support** for verbatim and raw strings
+- **Brace matching** - Position cursor on `{` or `}` to see matching brace highlighted
+- **Property-argument highlighting** - Click on a property or argument to see its pair highlighted
+- **Light bulb navigation** - Code actions to jump from properties to arguments
+- **ESC to clear** - Press ESC to temporarily dismiss all highlights
+- **Immediate highlighting** - Updates as you type (before closing quotes)
+- **Multi-line support** - Works across verbatim and raw string boundaries
 
 ## Output
 

README.md

@@ -52,6 +52,7 @@ A Visual Studio Code extension that provides syntax highlighting and enhanced su
 - Works in all Serilog contexts: message templates, output templates, and Serilog.Expressions
 - **Multi-line support** - matches braces across line boundaries in verbatim and raw strings
 - Uses colored, bold braces for visibility without interfering with other highlighting
+- **Press ESC** to temporarily dismiss brace matching highlights
 
 ### 🎯 Property-Argument Highlighting
 - **Synchronous highlighting** of template properties and their corresponding arguments
@@ -60,6 +61,7 @@ A Visual Studio Code extension that provides syntax highlighting and enhanced su
 - Includes quotes when highlighting string arguments (e.g., `"userId"`)
 - Helps visualize the connection between template properties and their values
 - Uses background fill to distinguish from brace matching
+- **Press ESC** to temporarily dismiss property-argument highlights
 
 ## Installation
 

package.json

@@ -33,6 +33,18 @@
         "command": "serilog.navigateToArgument",
         "title": "Navigate to Argument",
         "category": "Serilog"
+      },
+      {
+        "command": "serilog.clearHighlights",
+        "title": "Clear Highlights",
+        "category": "Serilog"
+      }
+    ],
+    "keybindings": [
+      {
+        "command": "serilog.clearHighlights",
+        "key": "escape",
+        "when": "editorTextFocus && editorLangId == csharp"
       }
     ],
     "configuration": {

src/extension.ts

@@ -368,6 +368,16 @@ export function activate(context: vscode.ExtensionContext) {
     });
     context.subscriptions.push(refreshCommand);
 
+    // Register ESC handler to clear highlights
+    const clearHighlightsCommand = vscode.commands.registerCommand('serilog.clearHighlights', () => {
+        // Clear brace matching highlights
+        braceMatchProvider.clearHighlights();
+
+        // Clear property-argument highlights
+        propertyArgumentHighlighter.clearDecorations();
+    });
+    context.subscriptions.push(clearHighlightsCommand);
+
     // Initial update without debouncing
     updateDecorations();
 

src/providers/braceMatchProvider.test.ts

@@ -378,6 +378,67 @@ describe('SerilogBraceMatchProvider', () => {
         });
     });
 
+    describe('ESC Handler', () => {
+        test('should clear highlights when clearHighlights is called', () => {
+            // Arrange
+            const text = 'logger.LogInformation("User {UserId} logged in", userId);';
+
+            // Mock vscode window
+            const mockSetDecorations = jest.fn();
+            const mockEditor: any = {
+                document: {
+                    languageId: 'csharp',
+                    lineAt: jest.fn(() => ({ text: text })),
+                    getText: jest.fn(() => text),
+                    offsetAt: jest.fn((pos: any) => pos.character),
+                    positionAt: jest.fn((offset: number) => new (vscode as any).Position(0, offset))
+                },
+                selection: {
+                    active: new (vscode as any).Position(0, 29) // On { of {UserId}
+                },
+                setDecorations: mockSetDecorations
+            };
+
+            (vscode.window as any).activeTextEditor = mockEditor;
+
+            // Mock isSerilogCall
+            (isSerilogCall as jest.Mock).mockReturnValue(true);
+
+            // Mock string parser
+            const mockFindAllStringLiterals = jest.fn();
+            StringLiteralParser.prototype.findAllStringLiterals = mockFindAllStringLiterals;
+            mockFindAllStringLiterals.mockReturnValue([{
+                type: 'regular',
+                content: 'User {UserId} logged in',
+                contentStart: 23,
+                contentEnd: 47
+            }]);
+
+            const provider = new SerilogBraceMatchProvider();
+
+            // Act - First update to set highlights
+            provider.updateBraceMatching(mockEditor);
+
+            // Assert - Highlights are set
+            expect(mockSetDecorations).toHaveBeenCalledWith(
+                expect.anything(),
+                expect.arrayContaining([
+                    expect.any(Object),
+                    expect.any(Object)
+                ])
+            );
+
+            // Act - Clear highlights
+            provider.clearHighlights();
+
+            // Assert - Highlights are cleared
+            expect(mockSetDecorations).toHaveBeenLastCalledWith(
+                expect.anything(),
+                []
+            );
+        });
+    });
+
     describe('Edge Cases', () => {
         test('should not match when cursor not on brace', () => {
             const lineText = 'logger.LogInformation("User {UserId} logged in", userId);';

src/providers/propertyArgumentHighlighter.test.ts

@@ -295,6 +295,25 @@ describe('PropertyArgumentHighlighter', () => {
         });
     });
 
+    describe('ESC Handler', () => {
+        test('should clear decorations when clearDecorations is called', () => {
+            // Arrange
+            highlighter = new PropertyArgumentHighlighter();
+
+            // Mock active editor
+            (vscode.window as any).activeTextEditor = mockEditor;
+
+            // Act - Clear decorations
+            highlighter.clearDecorations();
+
+            // Assert - Decorations are cleared
+            expect(mockSetDecorations).toHaveBeenCalledWith(
+                expect.anything(),
+                []
+            );
+        });
+    });
+
     describe('LogError with Exception parameter', () => {
         test('should highlight property-argument pairs when Exception is first parameter (single-line)', () => {
             // Arrange

src/providers/propertyArgumentHighlighter.ts

@@ -407,7 +407,7 @@ export class PropertyArgumentHighlighter implements vscode.Disposable {
         editor.setDecorations(this.decorationType, decorations);
     }
 
-    private clearDecorations(): void {
+    public clearDecorations(): void {
         if (vscode.window.activeTextEditor) {
             vscode.window.activeTextEditor.setDecorations(this.decorationType, []);
         }