@fresh-editor/fresh-editor 0.1.76 → 0.1.77

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Release Notes
 
+## 0.1.77
+
+### Documentation
+
+* **macOS Terminal Tips**: Added keyboard enhancement flags configuration guide.
+
+### Features
+
+* **LSP Semantic Highlighting** (@Asuka-Minato).
+* **macOS Keybinding Display**: Native symbols (⌃, ⌥, ⇧) instead of Ctrl+/Alt+/Shift+.
+* **Odin Language Support**: Syntax highlighting (sublime-syntax from @Tetralux) and OLS LSP configuration (@xoxorwr).
+* **File Explorer Git Indicators**: Shows modified/added status for files and folders via new plugin (#526) (@Asuka-Minato).
+* **Keyboard Enhancement Flags Config**: New config options for more granular control over kitty protocol usage (`keyboard_disambiguate_escape_codes`, `keyboard_report_event_types`, `keyboard_report_alternate_keys`, `keyboard_report_all_keys_as_escape_codes`).
+
+### Bug Fixes
+
+* **Menu Keybinding Display**: Consistent keybinding symbols in menus on macOS (#703).
+* **Git Find File Popup**: Smart path truncation preserving filename (#707).
+* **File Owner Preservation**: Preserve owner when saving files with group write privileges (#743).
+
+### Internal
+
+* Telemetry and update checks now debounce to once per day.
+* Terminal mode handling refactored into dedicated module.
+* Resolved ~300+ clippy warnings.
+* Bumped url (2.5.8), libc (0.2.180) (@dependabot).
+
+---
+
 ## 0.1.76
 
 ### Features

package/README.md

@@ -71,6 +71,8 @@ Or, pick your preferred method:
 
 On macOS and some linux distros (Bazzite/Bluefin/Aurora):
 
+> **Note:** On macOS, see [macOS Terminal Tips](docs/USER_GUIDE.md#macos-terminal-tips) for recommended terminal configuration.
+
 ```bash
 brew tap sinelaw/fresh
 brew install fresh-editor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fresh-editor/fresh-editor",
-  "version": "0.1.76",
+  "version": "0.1.77",
   "description": "A modern terminal-based text editor with plugin support",
   "repository": {
     "type": "git",

package/plugins/config-schema.json

@@ -42,6 +42,7 @@
         "large_file_threshold_bytes": 1048576,
         "estimated_line_length": 80,
         "enable_inlay_hints": true,
+        "enable_semantic_tokens_full": false,
         "recovery_enabled": true,
         "auto_save_interval_secs": 2,
         "highlight_context_bytes": 10000,
@@ -52,6 +53,10 @@
         "file_tree_poll_interval_ms": 3000,
         "default_line_ending": "lf",
         "cursor_style": "default",
+        "keyboard_disambiguate_escape_codes": true,
+        "keyboard_report_event_types": false,
+        "keyboard_report_alternate_keys": true,
+        "keyboard_report_all_keys_as_escape_codes": false,
         "quick_suggestions": true,
         "show_menu_bar": true,
         "show_tab_bar": true
@@ -225,7 +230,7 @@
           "default": 100
         },
         "large_file_threshold_bytes": {
-          "description": "File size threshold in bytes for \"large file\" behavior\nFiles larger than this will:\n- Skip LSP features\n- Use constant-size scrollbar thumb (1 char)\nFiles smaller will count actual lines for accurate scrollbar rendering",
+          "description": "File size threshold in bytes for \"large file\" behavior\nFiles larger than this will:\n- Skip LSP features\n- Use constant-size scrollbar thumb (1 char)\n\nFiles smaller will count actual lines for accurate scrollbar rendering",
           "type": "integer",
           "format": "uint64",
           "minimum": 0,
@@ -243,6 +248,11 @@
           "type": "boolean",
           "default": true
         },
+        "enable_semantic_tokens_full": {
+          "description": "Whether to request full-document LSP semantic tokens.\nRange requests are still used when supported.\nDefault: false (range-only to avoid heavy full refreshes).",
+          "type": "boolean",
+          "default": false
+        },
         "recovery_enabled": {
           "description": "Whether to enable file recovery (Emacs-style auto-save)\nWhen enabled, buffers are periodically saved to recovery files\nso they can be recovered if the editor crashes.",
           "type": "boolean",
@@ -305,6 +315,26 @@
           "$ref": "#/$defs/CursorStyle",
           "default": "default"
         },
+        "keyboard_disambiguate_escape_codes": {
+          "description": "Enable keyboard enhancement: disambiguate escape codes using CSI-u sequences.\nThis allows unambiguous reading of Escape and modified keys.\nRequires terminal support (kitty keyboard protocol).\nDefault: true",
+          "type": "boolean",
+          "default": true
+        },
+        "keyboard_report_event_types": {
+          "description": "Enable keyboard enhancement: report key event types (repeat/release).\nAdds extra events when keys are autorepeated or released.\nRequires terminal support (kitty keyboard protocol).\nDefault: false",
+          "type": "boolean",
+          "default": false
+        },
+        "keyboard_report_alternate_keys": {
+          "description": "Enable keyboard enhancement: report alternate keycodes.\nSends alternate keycodes in addition to the base keycode.\nRequires terminal support (kitty keyboard protocol).\nDefault: true",
+          "type": "boolean",
+          "default": true
+        },
+        "keyboard_report_all_keys_as_escape_codes": {
+          "description": "Enable keyboard enhancement: report all keys as escape codes.\nRepresents all keyboard events as CSI-u sequences.\nRequired for repeat/release events on plain-text keys.\nRequires terminal support (kitty keyboard protocol).\nDefault: false",
+          "type": "boolean",
+          "default": false
+        },
         "quick_suggestions": {
           "description": "Enable quick suggestions (VS Code-like behavior).\nWhen enabled, completion suggestions appear automatically while typing,\nnot just on trigger characters (like `.` or `::`).\nDefault: true",
           "type": "boolean",

package/plugins/git_explorer.ts

@@ -0,0 +1,159 @@
+/// <reference path="../types/fresh.d.ts" />
+const editor = getEditor();
+
+/**
+ * Git Explorer Decorations
+ *
+ * Adds VS Code-style status badges (M/A/U/D/...) to the file explorer.
+ */
+
+const NAMESPACE = "git-explorer";
+
+const COLORS = {
+  added: [80, 250, 123] as [number, number, number],
+  modified: [255, 184, 108] as [number, number, number],
+  deleted: [255, 85, 85] as [number, number, number],
+  renamed: [139, 233, 253] as [number, number, number],
+  untracked: [241, 250, 140] as [number, number, number],
+  conflicted: [255, 121, 198] as [number, number, number],
+};
+
+const PRIORITY = {
+  conflicted: 90,
+  deleted: 80,
+  added: 60,
+  modified: 50,
+  renamed: 40,
+  untracked: 30,
+};
+
+let refreshInFlight = false;
+
+function statusToDecoration(status: string, staged: boolean) {
+  switch (status) {
+    case "A":
+      return { symbol: "A", color: COLORS.added, priority: PRIORITY.added };
+    case "M":
+      return {
+        symbol: "M",
+        color: staged ? COLORS.added : COLORS.modified,
+        priority: PRIORITY.modified + (staged ? 2 : 0),
+      };
+    case "D":
+      return { symbol: "D", color: COLORS.deleted, priority: PRIORITY.deleted };
+    case "R":
+      return { symbol: "R", color: COLORS.renamed, priority: PRIORITY.renamed };
+    case "C":
+      return { symbol: "C", color: COLORS.renamed, priority: PRIORITY.renamed };
+    case "U":
+      return { symbol: "!", color: COLORS.conflicted, priority: PRIORITY.conflicted };
+    default:
+      return null;
+  }
+}
+
+function parseStatusOutput(output: string, repoRoot: string) {
+  const separator = output.includes("\0") ? "\0" : "\n";
+  const entries = output
+    .split(separator)
+    .map((entry) => entry.replace(/\r$/, ""))
+    .filter((entry) => entry.length > 0);
+  const byPath = new Map<string, { path: string; symbol: string; color: [number, number, number]; priority: number }>();
+
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.length < 3) {
+      continue;
+    }
+    const x = entry[0];
+    const y = entry[1];
+    let path = entry.slice(3);
+
+    if ((x === "R" || x === "C") && separator === "\0" && i + 1 < entries.length) {
+      i += 1;
+      path = entries[i];
+    } else if (entry.includes(" -> ") && (x === "R" || x === "C" || y === "R" || y === "C")) {
+      path = entry.split(" -> ").pop() ?? path;
+    }
+
+    let decoration = null;
+    if (x === "?" && y === "?") {
+      decoration = { symbol: "U", color: COLORS.untracked, priority: PRIORITY.untracked };
+    } else if (x !== " " && x !== "?") {
+      decoration = statusToDecoration(x, true);
+    } else if (y !== " ") {
+      decoration = statusToDecoration(y, false);
+    }
+
+    if (!decoration) {
+      continue;
+    }
+
+    const absolutePath = editor.pathJoin(repoRoot, path);
+    const existing = byPath.get(absolutePath);
+    if (!existing || decoration.priority >= existing.priority) {
+      byPath.set(absolutePath, { path: absolutePath, ...decoration });
+    }
+  }
+
+  return Array.from(byPath.values());
+}
+
+async function refreshGitExplorerDecorations() {
+  if (refreshInFlight) {
+    return;
+  }
+  refreshInFlight = true;
+  try {
+    const cwd = editor.getCwd();
+    const rootResult = await editor.spawnProcess("git", ["rev-parse", "--show-toplevel"], cwd);
+    if (rootResult.exit_code !== 0) {
+      editor.clearFileExplorerDecorations(NAMESPACE);
+      return;
+    }
+    const repoRoot = rootResult.stdout.trim();
+    if (!repoRoot) {
+      editor.clearFileExplorerDecorations(NAMESPACE);
+      return;
+    }
+
+    const statusResult = await editor.spawnProcess(
+      "git",
+      ["status", "--porcelain"],
+      repoRoot
+    );
+    if (statusResult.exit_code !== 0) {
+      editor.clearFileExplorerDecorations(NAMESPACE);
+      return;
+    }
+
+    const decorations = parseStatusOutput(statusResult.stdout, repoRoot);
+    if (decorations.length === 0) {
+      editor.clearFileExplorerDecorations(NAMESPACE);
+    } else {
+      editor.setFileExplorerDecorations(NAMESPACE, decorations);
+    }
+  } catch (_err) {
+    editor.clearFileExplorerDecorations(NAMESPACE);
+  } finally {
+    refreshInFlight = false;
+  }
+}
+
+globalThis.onGitExplorerAfterFileOpen = () => {
+  refreshGitExplorerDecorations();
+};
+
+globalThis.onGitExplorerAfterFileSave = () => {
+  refreshGitExplorerDecorations();
+};
+
+globalThis.onGitExplorerEditorInitialized = () => {
+  refreshGitExplorerDecorations();
+};
+
+editor.on("after_file_open", "onGitExplorerAfterFileOpen");
+editor.on("after_file_save", "onGitExplorerAfterFileSave");
+editor.on("editor_initialized", "onGitExplorerEditorInitialized");
+
+refreshGitExplorerDecorations();

package/plugins/lib/fresh.d.ts

@@ -170,6 +170,18 @@ interface ProcessHandle extends PromiseLike<SpawnResult> {
   kill(): Promise<boolean>;
 }
 
+/** File explorer decoration entry provided by plugins */
+interface FileExplorerDecoration {
+  /** Absolute or workspace-relative path to decorate */
+  path: string;
+  /** Symbol to display (single character recommended) */
+  symbol?: string | null;
+  /** RGB color for the symbol */
+  color?: [u8; 3] | null;
+  /** Priority for resolving conflicts (higher wins) */
+  priority?: number | null;
+}
+
 /** Result from spawnProcess */
 interface SpawnResult {
   /** Complete stdout as string. Newlines preserved; trailing newline included. */
@@ -786,6 +798,19 @@ interface EditorAPI {
    * @returns true if indicators were cleared
    */
   clearLineIndicators(buffer_id: number, namespace: string): boolean;
+  /**
+   * Set file explorer decorations for a namespace
+   * @param namespace - Namespace for grouping (e.g., "git-status")
+   * @param decorations - Decoration entries
+   * @returns true if decorations were accepted
+   */
+  setFileExplorerDecorations(namespace: string, decorations: FileExplorerDecoration[]): boolean;
+  /**
+   * Clear file explorer decorations for a namespace
+   * @param namespace - Namespace to clear (e.g., "git-status")
+   * @returns true if decorations were cleared
+   */
+  clearFileExplorerDecorations(namespace: string): boolean;
   /**
    * Submit a transformed view stream for a viewport
    * @param buffer_id - Buffer to apply the transform to

package/plugins/lib/index.ts

@@ -11,7 +11,15 @@
  */
 
 // Types
-export type { RGB, Location, PanelOptions, PanelState, NavigationOptions, HighlightPattern } from "./types.ts";
+export type {
+  RGB,
+  Location,
+  PanelOptions,
+  PanelState,
+  NavigationOptions,
+  HighlightPattern,
+  FileExplorerDecoration,
+} from "./types.ts";
 
 // Panel Management
 export { PanelManager } from "./panel-manager.ts";

package/plugins/lib/types.ts

@@ -11,6 +11,20 @@
  */
 export type RGB = [number, number, number];
 
+/**
+ * File explorer decoration metadata provided by plugins
+ */
+export interface FileExplorerDecoration {
+  /** Absolute or workspace-relative path to decorate */
+  path: string;
+  /** Symbol to display (single character recommended) */
+  symbol?: string;
+  /** RGB color for the symbol */
+  color?: RGB;
+  /** Priority for resolving conflicts (higher wins) */
+  priority?: number;
+}
+
 /**
  * File location with line and column
  */

package/plugins/odin-lsp.ts

@@ -0,0 +1,135 @@
+/// <reference path="./lib/fresh.d.ts" />
+const editor = getEditor();
+
+
+/**
+ * Odin LSP Helper Plugin
+ *
+ * Provides user-friendly error handling for Odin LSP server issues.
+ * When ols (Odin Language Server) fails to start, this plugin shows an actionable
+ * popup with installation instructions.
+ *
+ * Features:
+ * - Detects Odin LSP server errors (ols)
+ * - Shows popup with build instructions
+ * - Allows copying build commands to clipboard
+ * - Provides option to disable Odin LSP
+ *
+ * OLS: https://github.com/DanielGavin/ols
+ */
+
+interface LspServerErrorData {
+  language: string;
+  server_command: string;
+  error_type: string;
+  message: string;
+}
+
+interface LspStatusClickedData {
+  language: string;
+  has_error: boolean;
+}
+
+interface ActionPopupResultData {
+  popup_id: string;
+  action_id: string;
+}
+
+// OLS GitHub repository
+const OLS_URL = "https://github.com/DanielGavin/ols";
+
+// Track error state for Odin LSP
+let odinLspError: { serverCommand: string; message: string } | null = null;
+
+/**
+ * Handle LSP server errors for Odin
+ */
+globalThis.on_odin_lsp_server_error = function (data: LspServerErrorData): void {
+  // Only handle Odin language errors
+  if (data.language !== "odin") {
+    return;
+  }
+
+  editor.debug(`odin-lsp: Server error - ${data.error_type}: ${data.message}`);
+
+  // Store error state for later reference
+  odinLspError = {
+    serverCommand: data.server_command,
+    message: data.message,
+  };
+
+  // Show a status message for immediate feedback
+  if (data.error_type === "not_found") {
+    editor.setStatus(
+      `Odin LSP server '${data.server_command}' not found. Click status bar for help.`
+    );
+  } else {
+    editor.setStatus(`Odin LSP error: ${data.message}`);
+  }
+};
+
+// Register hook for LSP server errors
+editor.on("lsp_server_error", "on_odin_lsp_server_error");
+
+/**
+ * Handle status bar click when there's an Odin LSP error
+ */
+globalThis.on_odin_lsp_status_clicked = function (
+  data: LspStatusClickedData
+): void {
+  // Only handle Odin language clicks when there's an error
+  if (data.language !== "odin" || !odinLspError) {
+    return;
+  }
+
+  editor.debug("odin-lsp: Status clicked, showing help popup");
+
+  // Show action popup with install options
+  editor.showActionPopup({
+    id: "odin-lsp-help",
+    title: "Odin Language Server Not Found",
+    message: `"${odinLspError.serverCommand}" (OLS) provides code completion, diagnostics, and navigation for Odin files.\n\nInstallation: ${OLS_URL}`,
+    actions: [
+      { id: "disable", label: "Disable Odin LSP" },
+      { id: "dismiss", label: "Dismiss (ESC)" },
+    ],
+  });
+};
+
+// Register hook for status bar clicks
+editor.on("lsp_status_clicked", "on_odin_lsp_status_clicked");
+
+/**
+ * Handle action popup results for Odin LSP help
+ */
+globalThis.on_odin_lsp_action_result = function (
+  data: ActionPopupResultData
+): void {
+  // Only handle our popup
+  if (data.popup_id !== "odin-lsp-help") {
+    return;
+  }
+
+  editor.debug(`odin-lsp: Action selected - ${data.action_id}`);
+
+  switch (data.action_id) {
+    case "disable":
+      editor.disableLspForLanguage("odin");
+      editor.setStatus("Odin LSP disabled");
+      odinLspError = null;
+      break;
+
+    case "dismiss":
+    case "dismissed":
+      // Just close the popup without action
+      break;
+
+    default:
+      editor.debug(`odin-lsp: Unknown action: ${data.action_id}`);
+  }
+};
+
+// Register hook for action popup results
+editor.on("action_popup_result", "on_odin_lsp_action_result");
+
+editor.debug("odin-lsp: Plugin loaded");