Address PR #364 review comments from Copilot

- Extract renderDelegate cache invalidation into refreshEstimatedLineHeightCache() helper
- Normalize modifier flags to [shift, control, option, command] so Ctrl-N/P work with Caps Lock/Fn
- Fix handleArrowKey doc comment to accurately describe supported modifier combinations
- Centralize key code constants (tab, downArrow, upArrow) as static properties

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: objectiveous

Sources/CodeEditSourceEditor/Controller/TextViewController+Lifecycle.swift

@@ -204,17 +204,25 @@ extension TextViewController {
         }
     }
 
+    // MARK: - Key Codes
+
+    static let tabKeyCode: UInt16 = 0x30
+    static let downArrowKeyCode: UInt16 = 125
+    static let upArrowKeyCode: UInt16 = 126
+
+    /// The set of modifier flags relevant to key binding matching.
+    /// Masks out transient flags like Caps Lock, Fn, and numeric pad that would
+    /// prevent exact-match comparisons from succeeding.
+    private static let relevantModifiers: NSEvent.ModifierFlags = [.shift, .control, .option, .command]
+
     func handleEvent(event: NSEvent) -> NSEvent? {
         let modifierFlags = event.modifierFlags.intersection(.deviceIndependentFlagsMask)
+            .intersection(Self.relevantModifiers)
         switch event.type {
         case .keyDown:
-            let tabKey: UInt16 = 0x30
-            let downArrow: UInt16 = 125
-            let upArrow: UInt16 = 126
-
-            if event.keyCode == downArrow || event.keyCode == upArrow {
+            if event.keyCode == Self.downArrowKeyCode || event.keyCode == Self.upArrowKeyCode {
                 return self.handleArrowKey(event: event, modifierFlags: modifierFlags)
-            } else if event.keyCode == tabKey {
+            } else if event.keyCode == Self.tabKeyCode {
                 return self.handleTab(event: event, modifierFlags: modifierFlags.rawValue)
             } else {
                 return self.handleCommand(event: event, modifierFlags: modifierFlags)
@@ -291,12 +299,14 @@ extension TextViewController {
         }
     }
 
-    /// Handles up/down arrow key events with all modifier combinations.
+    /// Handles up/down arrow key events for plain, Shift, Option, Command,
+    /// and their combinations among these modifiers.
     /// Dispatches the appropriate movement method on the text view and consumes the event.
     ///
-    /// - Returns: `nil` to consume the event after dispatching the movement action.
+    /// - Returns: `nil` to consume the event after dispatching the movement action,
+    ///   or the original event for unsupported modifier combinations.
     private func handleArrowKey(event: NSEvent, modifierFlags: NSEvent.ModifierFlags) -> NSEvent? {
-        let isDown = event.keyCode == 125
+        let isDown = event.keyCode == Self.downArrowKeyCode
         let shift = modifierFlags.contains(.shift)
         let option = modifierFlags.contains(.option)
         let command = modifierFlags.contains(.command)

Sources/CodeEditSourceEditor/Controller/TextViewController.swift

@@ -163,6 +163,21 @@ public class TextViewController: NSViewController {
     /// Toggle the visibility of the gutter view in the editor.
     public var showGutter: Bool { configuration.peripherals.showGutter }
 
+    /// Optional provider for custom gutter decorations.
+    public var gutterDecorationProvider: (any GutterDecorationProviding)? {
+        didSet {
+            gutterView.decorationProvider = gutterDecorationProvider
+            gutterView.needsDisplay = true
+        }
+    }
+
+    /// Optional interaction delegate for gutter decorations.
+    public var gutterDecorationInteractionDelegate: (any GutterDecorationInteractionDelegate)? {
+        didSet {
+            gutterView.decorationInteractionDelegate = gutterDecorationInteractionDelegate
+        }
+    }
+
     /// Toggle the visibility of the minimap view in the editor.
     public var showMinimap: Bool { configuration.peripherals.showMinimap }
 
@@ -290,6 +305,16 @@ public class TextViewController: NSViewController {
         self.gutterView.setNeedsDisplay(self.gutterView.frame)
     }
 
+    /// Force the layout manager to recalculate its cached estimated line height.
+    ///
+    /// The estimated line height is cached and not invalidated when the font or line height multiplier changes,
+    /// causing vertical cursor movement (`moveDown:`/`moveUp:`) to use stale values and fail to cross line
+    /// boundaries. Re-assigning `renderDelegate` triggers the cache to refresh.
+    func refreshEstimatedLineHeightCache() {
+        let renderDelegate = textView.layoutManager.renderDelegate
+        textView.layoutManager.renderDelegate = renderDelegate
+    }
+
     deinit {
         if let highlighter {
             textView.removeStorageDelegate(highlighter)

Sources/CodeEditSourceEditor/SourceEditorConfiguration/SourceEditorConfiguration+Appearance.swift

@@ -87,11 +87,7 @@ extension SourceEditorConfiguration {
                 controller.textView.font = font
                 controller.textView.typingAttributes = controller.attributesFor(nil)
                 controller.gutterView.font = font.rulerFont
-                // Force the layout manager to recalculate its cached estimated line height.
-                // The estimate is cached and not invalidated by font changes, causing vertical
-                // cursor movement (moveDown:) to use stale values and fail to cross line boundaries.
-                let renderDelegate = controller.textView.layoutManager.renderDelegate
-                controller.textView.layoutManager.renderDelegate = renderDelegate
+                controller.refreshEstimatedLineHeightCache()
                 needsHighlighterInvalidation = true
             }
 
@@ -108,9 +104,7 @@ extension SourceEditorConfiguration {
 
             if oldConfig?.lineHeightMultiple != lineHeightMultiple {
                 controller.textView.layoutManager.lineHeightMultiplier = lineHeightMultiple
-                // Also invalidate the cached estimated line height (same issue as font change above).
-                let renderDelegate = controller.textView.layoutManager.renderDelegate
-                controller.textView.layoutManager.renderDelegate = renderDelegate
+                controller.refreshEstimatedLineHeightCache()
             }
 
             if oldConfig?.wrapLines != wrapLines {