@fresh-editor/fresh-editor 0.2.23 → 0.2.25

package/plugins/lib/fresh.d.ts

@@ -44,6 +44,32 @@ interface ProcessHandle<T> extends PromiseLike<T> {
 type BufferId = number;
 /** Split identifier */
 type SplitId = number;
+/**
+* Payload delivered to handlers registered with `editor.on("mouse_click", ...)`.
+*
+* All coordinate fields are in cell (terminal character) units. `buffer_*`
+* fields are `null` when the click did not land in any buffer panel.
+*/
+interface MouseClickHookArgs {
+	/** Screen column (0-indexed). */
+	column: number;
+	/** Screen row (0-indexed). */
+	row: number;
+	/** Mouse button: "left", "right", "middle". */
+	button: string;
+	/** Modifier keys (e.g. "shift"). */
+	modifiers: string;
+	/** X offset of the content area the click landed in. */
+	content_x: number;
+	/** Y offset of the content area the click landed in. */
+	content_y: number;
+	/** Buffer under the click, or `null` when outside any buffer panel. */
+	buffer_id: number | null;
+	/** 0-indexed buffer row (line number) of the click, accounting for scroll. */
+	buffer_row: number | null;
+	/** 0-indexed byte column inside the buffer row. */
+	buffer_col: number | null;
+}
 type TextPropertyEntry = {
 	/**
 	* Text content for this entry
@@ -308,6 +334,15 @@ type BufferInfo = {
 	* The detected language for this buffer (e.g., "rust", "markdown", "text")
 	*/
 	language: string;
+	/**
+	* Whether this tab was opened in "preview" (ephemeral) mode — true when
+	* opened via single-click in the file explorer and not yet committed
+	* (no edit, no double-click, no tab-click, no layout change). Plugins
+	* that react to buffer lifecycle events should generally treat preview
+	* buffers as transient; e.g. a diagnostics panel may want to skip
+	* refreshing itself for a preview tab.
+	*/
+	is_preview: boolean;
 };
 type JsDiagnostic = {
 	/**
@@ -1094,11 +1129,16 @@ interface EditorAPI {
 	*/
 	getTempDir(): string;
 	/**
-	* Get current config as JS object
+	* Get current config as JS object.
+	* 
+	* The snapshot holds an `Arc<serde_json::Value>` that was serialized
+	* on the editor side the last time the underlying `Arc<Config>`
+	* changed. Cloning the Arc inside the read lock is a refcount bump;
+	* the actual walk into the JS runtime happens outside the lock.
 	*/
 	getConfig(): unknown;
 	/**
-	* Get user config as JS object
+	* Get user config as JS object. Same Arc-clone pattern as `get_config`.
 	*/
 	getUserConfig(): unknown;
 	/**
@@ -1143,6 +1183,12 @@ interface EditorAPI {
 	*/
 	getConfigDir(): string;
 	/**
+	* Get the persistent data directory path (DirectoryContext::data_dir).
+	* Intended for plugin state that should outlive a single session — e.g.
+	* review-diff comments keyed off git state.
+	*/
+	getDataDir(): string;
+	/**
 	* Get themes directory path
 	*/
 	getThemesDir(): string;
@@ -1276,6 +1322,17 @@ interface EditorAPI {
 	*/
 	clearConcealsInRange(bufferId: number, start: number, end: number): boolean;
 	/**
+	* Add a collapsed fold range. Hides bytes [start, end) from
+	* rendering — the line containing `start - 1` (the fold "header")
+	* stays visible, while subsequent lines covered by the range are
+	* skipped.
+	*/
+	addFold(bufferId: number, start: number, end: number, placeholder?: string): boolean;
+	/**
+	* Clear every collapsed fold range on the buffer.
+	*/
+	clearFolds(bufferId: number): boolean;
+	/**
 	* Add a soft break point for marker-based line wrapping
 	*/
 	addSoftBreak(bufferId: number, namespace: string, position: number, indent: number): boolean;
@@ -1336,8 +1393,14 @@ interface EditorAPI {
 	clearVirtualTextNamespace(bufferId: number, namespace: string): boolean;
 	/**
 	* Add a virtual line (full line above/below a position)
+	* 
+	* The `options` object accepts:
+	* * `fg`, `bg` — either an `[r, g, b]` array (each `0..=255`) or a
+	* theme-key string (e.g. `"editor.line_number_fg"`).  Theme keys
+	* are resolved at render time so the line follows theme changes.
+	* Both default to `null` (no foreground / transparent background).
 	*/
-	addVirtualLine(bufferId: number, position: number, text: string, fgR: number, fgG: number, fgB: number, bgR: number, bgG: number, bgB: number, above: boolean, namespace: string, priority: number): boolean;
+	addVirtualLine(bufferId: number, position: number, text: string, options: Record<string, unknown>, above: boolean, namespace: string, priority: number): boolean;
 	/**
 	* Show a prompt and wait for user input (async)
 	* Returns the user input or null if cancelled
@@ -1361,7 +1424,7 @@ interface EditorAPI {
 	/**
 	* Define a buffer mode (takes bindings as array of [key, command] pairs)
 	*/
-	defineMode(name: string, bindingsArr: string[][], readOnly?: boolean, allowTextInput?: boolean): boolean;
+	defineMode(name: string, bindingsArr: string[][], readOnly?: boolean, allowTextInput?: boolean, inheritNormalBindings?: boolean): boolean;
 	/**
 	* Set the global editor mode
 	*/
@@ -1411,6 +1474,15 @@ interface EditorAPI {
 	*/
 	setBufferCursor(bufferId: number, position: number): boolean;
 	/**
+	* Toggle whether the editor draws a native caret in this buffer.
+	* 
+	* Buffer-group panel buffers default to `show_cursors = false`, which
+	* also blocks all native movement actions in `action_to_events`. Plugins
+	* that want native cursor motion in a panel (e.g. magit-style row
+	* navigation) call this with `true` after `createBufferGroup` returns.
+	*/
+	setBufferShowCursors(bufferId: number, show: boolean): boolean;
+	/**
 	* Set a line indicator in the gutter
 	*/
 	setLineIndicator(bufferId: number, line: number, namespace: string, symbol: string, r: number, g: number, b: number, priority: number): boolean;