@fresh-editor/fresh-editor 0.3.8 → 0.3.10

package/plugins/env-manager.ts

@@ -82,28 +82,26 @@ function isTrusted(): boolean {
 /** Activate (or, when already active, reload) the detected environment. */
 function activate(): void {
   if (!isTrusted()) {
-    editor.setStatus(
-      "Workspace not trusted — run “Workspace Trust: Trust This Folder” to activate the environment",
-    );
+    editor.setStatus(editor.t("status.not_trusted"));
     return;
   }
   const det = detect();
   if (!det) {
-    editor.setStatus("No environment manager detected in this project");
+    editor.setStatus(editor.t("status.no_env_detected"));
     return;
   }
   // Core captures `snippet` on the active backend and applies it to every
   // spawn; it restarts so language servers re-spawn under the fresh env.
   editor.setEnv(det.snippet, editor.getCwd());
   editor.setStatus(
-    `${editor.envActive() ? "Reloading" : "Activating"} ${det.name} environment…`,
+    editor.t(editor.envActive() ? "status.reloading" : "status.activating", { name: det.name }),
   );
 }
 registerHandler("env_activate_handler", activate);
 
 function useSystem(): void {
   editor.clearEnv();
-  editor.setStatus("Environment deactivated — using the system environment");
+  editor.setStatus(editor.t("status.deactivated"));
 }
 registerHandler("env_use_system_handler", useSystem);
 
@@ -111,37 +109,23 @@ function showStatus(): void {
   const det = detect();
   const trust = editor.workspaceTrustLevel() || "unavailable";
   if (editor.envActive()) {
-    editor.setStatus(`Environment active${det ? ` (${det.name})` : ""}`);
-  } else if (det) {
     editor.setStatus(
-      `Detected ${det.name} (trust: ${trust}). Run “Env: Activate” to use it.`,
+      det
+        ? editor.t("status.env_active_named", { name: det.name })
+        : editor.t("status.env_active"),
     );
+  } else if (det) {
+    editor.setStatus(editor.t("status.env_detected", { name: det.name, trust }));
   } else {
-    editor.setStatus(`No environment detected (trust: ${trust})`);
+    editor.setStatus(editor.t("status.no_env", { trust }));
   }
 }
 registerHandler("env_status_handler", showStatus);
 
-editor.registerCommand(
-  "env_activate",
-  "Env: Activate Detected Environment (venv / direnv / mise)",
-  "env_activate_handler",
-);
-editor.registerCommand(
-  "env_reload",
-  "Env: Reload Environment (re-capture after .envrc/mise.toml change)",
-  "env_activate_handler",
-);
-editor.registerCommand(
-  "env_use_system",
-  "Env: Use System (Deactivate Environment)",
-  "env_use_system_handler",
-);
-editor.registerCommand(
-  "env_status",
-  "Env: Show Environment Status",
-  "env_status_handler",
-);
+editor.registerCommand("%cmd.activate", "%cmd.activate_desc", "env_activate_handler");
+editor.registerCommand("%cmd.reload", "%cmd.reload_desc", "env_activate_handler");
+editor.registerCommand("%cmd.use_system", "%cmd.use_system_desc", "env_use_system_handler");
+editor.registerCommand("%cmd.status", "%cmd.status_desc", "env_status_handler");
 
 // === Status pill (opt-in to a user's status-bar layout) ===
 
@@ -151,14 +135,20 @@ function refreshStatus(): void {
   const det = detect();
   let value: string;
   if (editor.envActive()) {
-    value = det ? `${det.name} ✓` : "active";
+    value = det
+      ? editor.t("statusbar.active", { name: det.name })
+      : editor.t("statusbar.active_unknown");
+  } else if (det) {
+    value = isTrusted()
+      ? det.name
+      : editor.t("statusbar.locked", { name: det.name });
   } else {
-    value = det ? `${det.name}${isTrusted() ? "" : " (locked)"}` : "system";
+    value = editor.t("statusbar.system");
   }
   editor.setStatusBarValue(bufferId, STATUS_TOKEN, value);
 }
 
-editor.registerStatusBarElement(STATUS_TOKEN, "Environment");
+editor.registerStatusBarElement(STATUS_TOKEN, editor.t("statusbar.label"));
 
 registerHandler("env_refresh_status", refreshStatus);
 for (const event of ["buffer_activated", "after_file_open", "focus_gained"]) {

package/plugins/examples/bookmarks.ts

@@ -46,8 +46,9 @@ function getCurrentLocation(): {
 
 // Helper: Get actual line number using the API
 function getCurrentLineCol(): { line: number; column: number } {
-  // Use the actual getCursorLine API for accurate line number
-  const lineNumber = editor.getCursorLine();
+  // Read the primary cursor's line from the snapshot. `line` is null when the
+  // buffer has no line index yet (huge files); fall back to 0 there.
+  const lineNumber = editor.getPrimaryCursor()?.line ?? 0;
 
   // Get cursor position within the line by reading buffer content
   const bufferId = editor.getActiveBufferId();

package/plugins/lib/finder.ts

@@ -116,9 +116,37 @@ export interface FinderConfig<T> {
   /** Panel-specific: navigate source split when cursor moves (preview without focus change) */
   navigateOnCursorMove?: boolean;
 
+  /**
+   * Panel-specific: whether selecting an entry (Enter) closes the
+   * panel. Defaults to `true` — the panel dismisses as it jumps, which
+   * suits one-shot lists like Find References. Set `false` to keep the
+   * panel docked so the user can step through entries (Vim quickfix /
+   * VS Code results list). Only consulted by the default selection
+   * handler — a custom `onSelect` owns close behaviour itself.
+   *
+   * Note: leaving the panel open while `navigateOnCursorMove` is also
+   * on re-introduces the focus race the close was guarding against
+   * (a `focusSplit` queued after the jump can re-grab the panel), so
+   * the two shouldn't be combined without care.
+   */
+  closeOnSelect?: boolean;
+
   /** Called when the panel or prompt is closed (e.g. via Escape) */
   onClose?: () => void;
 
+  /**
+   * Panel-specific: extra key bindings active while the panel buffer
+   * is focused, as `[key, command]` pairs (e.g. `["q", "my_close"]`).
+   * `command` is dispatched as a plugin action, so it should name a
+   * handler registered via `registerHandler`. These augment the
+   * built-in `Return` (select) and `Escape` (close) bindings.
+   *
+   * Without this, keys a plugin advertises in its panel UI (e.g.
+   * "q: close") fall through to the read-only text layer and trip
+   * "Editing disabled in this buffer" (issue #2125).
+   */
+  panelKeys?: Array<[string, string]>;
+
   /**
    * When true, panels created by this Finder are routed into the
    * shared Utility Dock (issue #1796 / Section 2 of
@@ -447,6 +475,33 @@ export class Finder<T> {
   // Mode flags
   private isPromptMode = false;
   private isPanelMode = false;
+  /** True when the active prompt is a centred floating overlay. Search
+   *  status then goes to the overlay's own footer (visible inside the frame)
+   *  rather than the editor status bar (off at the bottom, easy to miss). */
+  private isOverlay = false;
+
+  /** Present a search-status message where the user is actually looking: on
+   *  the overlay's input row (right-aligned by the match count) for a
+   *  floating overlay, else the editor status bar. */
+  private setSearchStatus(message: string): void {
+    if (this.isOverlay) {
+      this.editor.setPromptStatus(message);
+    } else {
+      this.editor.setStatus(message);
+    }
+  }
+
+  /** Report a successful search with `count` matches. In overlay mode the
+   *  "N / total" count on the input row already conveys this, so the status
+   *  is cleared to avoid duplicating it; the status bar (non-overlay) still
+   *  shows "Found N matches". */
+  private reportFound(count: number): void {
+    if (this.isOverlay) {
+      this.editor.setPromptStatus("");
+    } else {
+      this.editor.setStatus(`Found ${count} matches`);
+    }
+  }
 
   // Handler names (for cleanup)
   private handlerPrefix: string;
@@ -513,6 +568,7 @@ export class Finder<T> {
 
     // Start the prompt
     const overlay = options.floatingOverlay === true;
+    this.isOverlay = overlay;
     if (options.initialQuery) {
       this.editor.startPromptWithInitial(
         options.title,
@@ -525,7 +581,7 @@ export class Finder<T> {
       const result = this.editor.startPrompt(options.title, this.config.id, overlay);
       this.editor.debug(`[Finder] startPrompt returned: ${result}`);
     }
-    this.editor.setStatus("Type to search...");
+    this.setSearchStatus("Type to search…");
   }
 
   /**
@@ -545,6 +601,11 @@ export class Finder<T> {
     // unchanged query.
     this.promptState.lastQuery = "";
     if (query.length === 0) return;
+    // The backend (or scope set) changed, so the on-screen results are now
+    // stale. Clear them and show progress immediately rather than leaving the
+    // previous output up while the (possibly slow) new search runs.
+    this.updatePromptResults([]);
+    this.setSearchStatus("Searching…");
     await this.runSearch(query, this.currentSource);
   }
 
@@ -713,9 +774,9 @@ export class Finder<T> {
       this.updatePromptResults(filtered);
 
       if (filtered.length > 0) {
-        this.editor.setStatus(`Found ${filtered.length} matches`);
+        this.reportFound(filtered.length);
       } else {
-        this.editor.setStatus("No matches");
+        this.setSearchStatus("No matches");
       }
     } else {
       // Search mode: run external search
@@ -745,6 +806,7 @@ export class Finder<T> {
       }
       this.editor.setPromptSuggestions([]);
       this.promptState.results = [];
+      this.setSearchStatus("");
       return;
     }
 
@@ -768,6 +830,11 @@ export class Finder<T> {
     }
     this.promptState.lastQuery = query;
 
+    // A search is now actually starting (every query change that gets here —
+    // typing, deleting, provider/scope refresh). Show pending status so the
+    // user sees the re-scan in progress rather than a stale result count.
+    this.setSearchStatus("Searching…");
+
     try {
       const searchResult = source.search(query);
 
@@ -793,21 +860,21 @@ export class Finder<T> {
           this.updatePromptResults(parsed);
 
           if (parsed.length > 0) {
-            this.editor.setStatus(`Found ${parsed.length} matches`);
+            this.reportFound(parsed.length);
             // Show preview of first result
             if (this.shouldShowPreview()) {
               await this.updatePreview(this.promptState.entries[0]);
             }
           } else {
-            this.editor.setStatus("No matches");
+            this.setSearchStatus("No matches");
           }
         } else if (result.exit_code === 1) {
           // No matches
           this.updatePromptResults([]);
-          this.editor.setStatus("No matches");
+          this.setSearchStatus("No matches");
         } else if (result.exit_code !== -1) {
           // Error (ignore -1 which means killed)
-          this.editor.setStatus(`Search error: ${result.stderr}`);
+          this.setSearchStatus(`Search error: ${result.stderr}`);
         }
       } else {
         // Promise<T[]>
@@ -821,12 +888,12 @@ export class Finder<T> {
         this.updatePromptResults(results);
 
         if (results.length > 0) {
-          this.editor.setStatus(`Found ${results.length} matches`);
+          this.reportFound(results.length);
           if (this.shouldShowPreview()) {
             await this.updatePreview(this.promptState.entries[0]);
           }
         } else {
-          this.editor.setStatus("No matches");
+          this.setSearchStatus("No matches");
         }
       }
     } catch (e) {
@@ -864,7 +931,15 @@ export class Finder<T> {
       (entry, i) => ({
         text: entry.label,
         description: entry.description,
-        value: `${i}`,
+        // The preview pane uses `value` as the authoritative
+        // `path:line:col` for the result. We must not rely on parsing the
+        // user-facing label, which may carry source badges (e.g. "[term]")
+        // that make the label unparseable as a path.
+        value: entry.location
+          ? `${entry.location.file}:${entry.location.line}:${
+            entry.location.column ?? 1
+          }`
+          : `${i}`,
         disabled: false,
       })
     );
@@ -1064,12 +1139,17 @@ export class Finder<T> {
   private registerPanelHandlers(): void {
     const self = this;
 
-    // Define panel mode
+    // Define panel mode. The built-in Return/Escape bindings are
+    // augmented with any caller-supplied `panelKeys` so plugin-specific
+    // shortcuts (e.g. Diagnostics' "q: close | a: toggle filter") resolve
+    // to their handlers instead of falling through to the read-only text
+    // layer (issue #2125).
     this.editor.defineMode(
       this.modeName,
       [
         ["Return", `${this.handlerPrefix}_panel_select`],
         ["Escape", `${this.handlerPrefix}_panel_close`],
+        ...(this.config.panelKeys ?? []),
       ],
       true
     );
@@ -1351,13 +1431,17 @@ export class Finder<T> {
     } else if (entry.location) {
       const loc = entry.location;
 
-      // Close the panel first. This is necessary because
-      // navigateOnCursorMove's focusSplit(panelSplitId) can interfere with
-      // the jump — it queues a FocusSplit that runs after OpenFileInSplit
-      // and restores the panel as the active split.
-      this.closePanel();
+      // Close the panel first (unless the consumer opted to keep it
+      // docked via `closeOnSelect: false`). Closing is the default
+      // because navigateOnCursorMove's focusSplit(panelSplitId) can
+      // interfere with the jump — it queues a FocusSplit that runs after
+      // OpenFileInSplit and restores the panel as the active split.
+      if (this.config.closeOnSelect !== false) {
+        this.closePanel();
+      }
 
-      // Now navigate with the panel gone — only one split remains
+      // openFile routes away from the dock leaf, so with the panel kept
+      // open the file lands in the editor pane and the list stays put.
       this.editor.openFile(loc.file, loc.line, loc.column);
       this.editor.setStatus(`Jumped to ${loc.file}:${loc.line}`);
     }

package/plugins/lib/fresh.d.ts

@@ -735,6 +735,13 @@ type CursorInfo = {
 		start: number;
 		end: number;
 	} | null;
+	/**
+	* 0-indexed line number of the cursor. `null` when the line index is
+	* unavailable — e.g. a huge file whose line scan hasn't completed, where
+	* the editor positions purely by byte offset. Plugins must treat `null`
+	* as "unknown", never as line 0.
+	*/
+	line: number | null;
 };
 type OverlayOptions = {
 	/**
@@ -896,6 +903,15 @@ type WidgetSpec = {
 	"kind": "row";
 	children: Array<WidgetSpec>;
 	key?: string | null;
+	/**
+	* When true, children that don't fit on one line reflow onto
+	* additional lines (growing the row's height) instead of being
+	* truncated. Children are never split — wrap happens at child
+	* boundaries — so wrap a logical group (e.g. a toggle + its
+	* accelerator) in a nested non-wrapping `Row` to keep it intact.
+	* Ignored when the row contains multi-line (block) children.
+	*/
+	wrap: boolean;
 } | {
 	"kind": "col";
 	children: Array<WidgetSpec>;
@@ -1206,6 +1222,16 @@ interface SearchHandle {
 	take(): SearchTakeResult;
 	cancel(): void;
 }
+type ReplaceResult = {
+	/**
+	* Number of replacements made
+	*/
+	replacements: number;
+	/**
+	* Buffer ID of the edited buffer
+	*/
+	bufferId: number;
+};
 type AuthorityFilesystem = {
 	kind: "local";
 };
@@ -1489,16 +1515,6 @@ type RemoteIndicatorStatePayload = {
 	kind: "disconnected";
 	label?: string | null;
 };
-type ReplaceResult = {
-	/**
-	* Number of replacements made
-	*/
-	replacements: number;
-	/**
-	* Buffer ID of the edited buffer
-	*/
-	bufferId: number;
-};
 type SpawnResult = {
 	/**
 	* Complete stdout as string
@@ -1622,6 +1638,13 @@ interface EditorAPI {
 	*/
 	executeAction(actionName: string): boolean;
 	/**
+	* Cancel the active prompt / overlay — the same teardown the
+	* Escape key triggers. Lets a plugin dismiss a prompt it opened
+	* (e.g. exporting Live Grep results to a dock panel) without
+	* routing a synthetic keypress.
+	*/
+	cancelPrompt(): boolean;
+	/**
 	* Register a custom statusbar token.
 	* Token will be named "plugin_name:token_name" where plugin_name is the current plugin.
 	* Returns true if registration succeeded, false if invalid or already registered.
@@ -1695,7 +1718,13 @@ interface EditorAPI {
 	*/
 	listSplits(): SplitSnapshot[];
 	/**
-	* Get the line number (0-indexed) of the primary cursor
+	* Get the line number (0-indexed) of the primary cursor.
+	* 
+	* @deprecated Use `getPrimaryCursor()?.line` instead. This accessor cannot
+	* represent "line index unavailable" (huge files before their line scan) —
+	* it returns `0` in that case, indistinguishable from a real first line.
+	* `getPrimaryCursor().line` is `number | null` and also covers every cursor
+	* via `getAllCursors()`.
 	*/
 	getCursorLine(): number;
 	/**
@@ -1864,38 +1893,17 @@ interface EditorAPI {
 	*/
 	getAuthorityLabel(): string;
 	/**
-	* Current Workspace Trust level for the active project:
-	* `"restricted"`, `"trusted"`, or `"blocked"` (empty `""` when trust
-	* state is unavailable, e.g. the default local authority).
-	*
-	* Trust is a per-project, user-granted decision. Plugins that run
-	* repo-controlled work (env activation, project tooling, repo-local
-	* binaries) MUST gate on this and treat anything other than
-	* `"trusted"` as "do not execute".
-	*/
-	workspaceTrustLevel(): "restricted" | "trusted" | "blocked" | "";
-	/**
-	* Activate an environment by setting the live env recipe: an activation
-	* shell `snippet` (e.g. `eval "$(direnv export bash)"`,
-	* `source .venv/bin/activate`, or `""` for a pure login shell) run in
-	* `dir` (defaults to the workspace). It is re-evaluated on demand on the
-	* active backend and applied to every spawn — language servers,
-	* formatters, `spawnProcess` — so they see the project environment. No
-	* authority rebuild; the LSP is restarted to pick it up.
-	*
-	* Honored only when `workspaceTrustLevel() === "trusted"` (it runs
-	* repo-controlled code). Call `clearEnv()` to deactivate.
-	*/
-	setEnv(snippet: string, dir?: string): void;
-	/**
-	* Deactivate the environment set by `setEnv` — spawns return to the
-	* inherited environment.
+	* Current Workspace Trust level for the active project: `"restricted"`,
+	* `"trusted"`, or `"blocked"` (empty when unavailable). Exposed to JS as
+	* `editor.workspaceTrustLevel()`. Plugins that run repo-controlled work
+	* should treat anything other than `"trusted"` as "do not execute".
 	*/
-	clearEnv(): void;
+	workspaceTrustLevel(): string;
 	/**
-	* Whether an environment is currently active (a recipe was set via
-	* `setEnv`). Survives the restart `setEnv` triggers, so a plugin can
-	* re-establish its file watch and reflect activation after reloading.
+	* Whether an environment is currently active (set via `editor.setEnv`).
+	* Exposed to JS as `editor.envActive()`. Lets the env-manager plugin
+	* reflect activation and re-establish its file watch after the restart
+	* that `setEnv` triggers.
 	*/
 	envActive(): boolean;
 	/**
@@ -2134,6 +2142,21 @@ interface EditorAPI {
 	*/
 	getDataDir(): string;
 	/**
+	* Directory holding terminal scrollback backing files for the current
+	* working directory. Each project root / worktree has its own subdir, so
+	* Universal Search's terminal scope can stay scoped to the active
+	* project rather than spanning every project's terminals.
+	*/
+	getTerminalDir(): string;
+	/**
+	* Per-working-directory data root for plugin state scoped to the current
+	* project root / worktree (`<data_dir>/workdirs/<encoded-cwd>/`). Use
+	* instead of `getDataDir()` for state that should not be shared across
+	* worktrees. The directory is not created here — callers create what
+	* they need under it.
+	*/
+	getWorkingDataDir(): string;
+	/**
 	* Get themes directory path
 	*/
 	getThemesDir(): string;
@@ -2267,6 +2290,12 @@ interface EditorAPI {
 	*/
 	clearOverlaysInRange(bufferId: number, start: number, end: number): boolean;
 	/**
+	* Clear overlays in a single namespace that overlap with a byte range.
+	* Unlike clearOverlaysInRange, overlays in other namespaces (e.g.
+	* editor-owned LSP diagnostics) are left untouched.
+	*/
+	clearOverlaysInRangeForNamespace(bufferId: number, namespace: string, start: number, end: number): boolean;
+	/**
 	* Remove an overlay by its handle
 	*/
 	removeOverlay(bufferId: number, handle: string): boolean;
@@ -2472,6 +2501,24 @@ interface EditorAPI {
 	*/
 	setPromptFooter(footer: StyledText[]): boolean;
 	/**
+	* Set the floating-overlay prompt's input-row status text (right-aligned,
+	* left of the match count). Empty string clears it.
+	*/
+	setPromptStatus(status: string): boolean;
+	/**
+	* Set the floating-overlay prompt's toolbar as a `WidgetSpec` (real,
+	* clickable `Toggle`/`Button` widgets rendered in the header band, in
+	* place of the styled-text title). Pass `null`/`undefined` to clear it.
+	*/
+	setPromptToolbar(specObj: unknown): boolean;
+	/**
+	* Toggle a floating-overlay toolbar control by its widget `key`. The host
+	* owns the toggle's checked state, flips it, and emits a `widget_event`
+	* the plugin can listen for. Lets a plugin route its own Alt+… shortcut
+	* through the same host path as a click / Space on the toggle.
+	*/
+	toggleOverlayToolbarWidget(key: string): boolean;
+	/**
 	* Override the currently-highlighted suggestion row in the
 	* open prompt. The editor clamps `index` to the suggestion
 	* list's bounds and the renderer scrolls it into view on
@@ -2860,6 +2907,16 @@ interface EditorAPI {
 	*/
 	clearAuthority(): void;
 	/**
+	* Activate an environment: set the live env recipe (`snippet` run in
+	* `dir`). Applied to every spawn, re-evaluated on demand — no restart.
+	* Honored only when the workspace is Trusted.
+	*/
+	setEnv(snippet: string, dir: string | null): void;
+	/**
+	* Deactivate the environment — spawns return to the inherited env.
+	*/
+	clearEnv(): void;
+	/**
 	* Override the Remote Indicator's displayed state. Plugins call
 	* this to surface lifecycle transitions that the authority layer
 	* doesn't know about yet — "Connecting" while `devcontainer up`
@@ -2926,13 +2983,14 @@ interface EditorAPI {
 		caseSensitive?: boolean;
 		maxResults?: number;
 		wholeWords?: boolean;
+		sourceBufferId?: number;
 	}): SearchHandle;
 	/**
 	* Replace matches in a file's buffer (async)
 	* Opens the file if not already in a buffer, applies edits via the buffer model,
 	* and saves. All edits are grouped as a single undo action.
 	*/
-	replaceInFile(filePath: string, matches: number[][], replacement: string): Promise<ReplaceResult>;
+	replaceInFile(filePath: string, matches: number[][], replacement: string, bufferId?: number): Promise<ReplaceResult>;
 	/**
 	* Send LSP request (async, returns request_id)
 	*/

package/plugins/lib/widgets.ts

@@ -60,6 +60,14 @@ export function row(...children: WidgetSpec[]): WidgetSpec {
   return { kind: "row", children };
 }
 
+/** Horizontal layout that **wraps**: children that don't fit on one line
+ * reflow onto additional lines (growing the row's height) instead of being
+ * truncated. Children are never split, so wrap a logical group (e.g. a
+ * toggle + its accelerator) in a nested `row(...)` to keep it intact. */
+export function wrappingRow(...children: WidgetSpec[]): WidgetSpec {
+  return { kind: "row", children, wrap: true };
+}
+
 /** Vertical layout. Children stacked top-to-bottom. */
 export function col(...children: WidgetSpec[]): WidgetSpec {
   return { kind: "col", children };

package/plugins/live_diff.ts

@@ -978,7 +978,18 @@ async function recompute(bufferId: number): Promise<void> {
     }
 
     const length = editor.getBufferLength(bufferId);
-    const newText = await editor.getBufferText(bufferId, 0, length);
+    let newText: string;
+    try {
+      newText = await editor.getBufferText(bufferId, 0, length);
+    } catch (e) {
+      // The buffer can close between the awaits above (the git `show`
+      // for the reference is slow) and this fetch — e.g. the user
+      // closes the file, or an external process churns it while it's
+      // open. `buffer_closed` deletes our state, so if it's gone the
+      // recompute is moot: bail quietly instead of logging an error.
+      if (!states.has(bufferId)) return;
+      throw e;
+    }
 
     // Skip 1: same buffer text as last recompute. `lines_changed` fires
     // on viewport scrolls (cursor up/down past the visible area), and