@fresh-editor/fresh-editor 0.2.22 → 0.2.24

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 = {
 	/**
@@ -399,9 +434,9 @@ type FileExplorerDecoration = {
 	*/
 	symbol: string;
 	/**
-	* Color as RGB array (rquickjs_serde requires array, not tuple)
+	* Color as RGB array or theme key string (e.g., "ui.file_status_added_fg")
 	*/
-	color: [number, number, number];
+	color: OverlayColorSpec;
 	/**
 	* Priority for display when multiple decorations exist (higher wins)
 	*/
@@ -947,6 +982,17 @@ interface EditorAPI {
 	*/
 	scrollToLineCenter(splitId: number, bufferId: number, line: number): boolean;
 	/**
+	* Scroll any split/panel showing `buffer_id` so `line` is visible.
+	* Unlike `scrollToLineCenter`, this does not require a split id — it
+	* updates every split's viewport whose active buffer is the given
+	* buffer, including inner leaves of a buffer group. Use this from
+	* a panel plugin to keep the user's "selected" row in view after
+	* arrow-key navigation (the plugin's own selection state isn't
+	* automatically reflected in the buffer cursor, so the core-driven
+	* viewport would otherwise stay put).
+	*/
+	scrollBufferToLine(bufferId: number, line: number): boolean;
+	/**
 	* Find buffer by file path, returns buffer ID or 0 if not found
 	*/
 	findBufferByPath(path: string): number;
@@ -1132,6 +1178,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;
@@ -1265,6 +1317,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;
@@ -1325,8 +1388,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
@@ -1350,7 +1419,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
 	*/
@@ -1400,6 +1469,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;
@@ -1501,6 +1579,18 @@ interface EditorAPI {
 	*/
 	createVirtualBufferInExistingSplit(opts: CreateVirtualBufferInExistingSplitOptions): Promise<VirtualBufferResult>;
 	/**
+	* Set the content of a panel within a buffer group
+	*/
+	setPanelContent(groupId: number, panelName: string, entriesArr: Record<string, unknown>[]): boolean;
+	/**
+	* Close a buffer group
+	*/
+	closeBufferGroup(groupId: number): boolean;
+	/**
+	* Focus a specific panel within a buffer group
+	*/
+	focusBufferGroupPanel(groupId: number, panelName: string): boolean;
+	/**
 	* Set virtual buffer content (takes array of entry objects)
 	* 
 	* Note: entries should be TextPropertyEntry[] - uses manual parsing for HashMap support