@fresh-editor/fresh-editor 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Release Notes
 
+## 0.2.4
+
+### Features
+
+* **Markdown Compose Mode**: Distraction-free writing mode with concealed markup, soft breaks, table rendering, and mouse support. Split-view allows editing source and rendered markdown side-by-side with synchronized scrolling.
+
+* **Vertical Rulers**: Configurable column rulers with add/remove commands via command palette. Per-buffer state and Settings UI JSON editor support (#1028).
+
+* **Horizontal Scrollbar**: New horizontal scrollbar with drag support and toggle commands (#972).
+
+* **Smooth Scrolling**: Cursor movement now scrolls one line at a time instead of jumping/recentering the viewport (#1040).
+
+### Improvements
+
+* **Macro Keybinding**: F4 shortcut for Play Last Macro. Removed Ctrl+0-9 and Alt+Shift+0-9 macro keybindings (#700).
+
+* **Configurable Clipboard**: New `clipboard` config with `use_osc52` and `use_system_clipboard` toggles to prevent hangs in certain terminals (#964). Useful for Putty and other terminals that sometimes cause Fresh to hang on OSC 52.
+
+* **Scrollbar Visibility**: New `show_vertical_scrollbar` and `show_horizontal_scrollbar` config options (#974).
+
+* **Package Manager**: Reinstall support for local-path packages.
+
+* **File Explorer Persistence**: Show hidden and show gitignored toggles now persist to config immediately (#569).
+
+### Bug Fixes
+
+* **Macro correctness**: Replaying a macro now respects the exact same effect as interactive flow.
+
+* **Cursor Navigation**: Cursor up/down now lands at end-of-line when goal column is past content (#514).
+
+* **Line Numbers**: Fixed line numbers leaking between splits due to shared margins state. Line numbers now live exclusively in per-split BufferViewState.
+
+### Plugin API
+
+* **Plugin API v2**: Versioned plugin API with `createTerminal`, `sendTerminalInput`, `closeTerminal`, `getAllCursors`, and plugin state API. Improved type declarations in `fresh.d.ts` (#1045).
+
+* **Split Labels**: Splits can be labeled to prevent files opening in managed splits. Labels persist across save/restore. New `before` option to place buffers left/top.
+
+### Internal
+
+* Refactored per-buffer view state: cursors owned by SplitViewState, ComposeState extracted from EditorState.
+* Conceal ranges, soft breaks, and overlay filtering by view_mode at render time.
+* Plugin state snapshot reports active split's view_mode and compose flag.
+* i18n updates for vertical rulers and macro shortcuts across all locales.
+* PieceTree Performance: Use binary search instead of linear scan in line lookup.
+
+---
+
 ## 0.2.3
 
 ### Bug Fixes

package/package.json

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

package/plugins/config-schema.json

@@ -36,8 +36,11 @@
         "syntax_highlighting": true,
         "show_menu_bar": true,
         "show_tab_bar": true,
+        "show_vertical_scrollbar": true,
+        "show_horizontal_scrollbar": false,
         "use_terminal_bg": false,
         "cursor_style": "default",
+        "rulers": [],
         "tab_size": 4,
         "auto_indent": true,
         "scroll_offset": 3,
@@ -88,6 +91,14 @@
         "show_hidden": false
       }
     },
+    "clipboard": {
+      "description": "Clipboard settings (which clipboard methods to use)",
+      "$ref": "#/$defs/ClipboardConfig",
+      "default": {
+        "use_osc52": true,
+        "use_system_clipboard": true
+      }
+    },
     "terminal": {
       "description": "Terminal settings",
       "$ref": "#/$defs/TerminalConfig",
@@ -230,6 +241,18 @@
           "default": true,
           "x-section": "Display"
         },
+        "show_vertical_scrollbar": {
+          "description": "Whether the vertical scrollbar is visible in each split pane.\nCan be toggled at runtime via command palette or keybinding.\nDefault: true",
+          "type": "boolean",
+          "default": true,
+          "x-section": "Display"
+        },
+        "show_horizontal_scrollbar": {
+          "description": "Whether the horizontal scrollbar is visible in each split pane.\nThe horizontal scrollbar appears when line wrap is disabled and content extends beyond the viewport.\nCan be toggled at runtime via command palette or keybinding.\nDefault: false",
+          "type": "boolean",
+          "default": false,
+          "x-section": "Display"
+        },
         "use_terminal_bg": {
           "description": "Use the terminal's default background color instead of the theme's editor background.\nWhen enabled, the editor background inherits from the terminal emulator,\nallowing transparency or custom terminal backgrounds to show through.\nDefault: false",
           "type": "boolean",
@@ -242,6 +265,17 @@
           "default": "default",
           "x-section": "Display"
         },
+        "rulers": {
+          "description": "Vertical ruler lines at specific column positions.\nDraws subtle vertical lines to help with line length conventions.\nExample: [80, 120] draws rulers at columns 80 and 120.\nDefault: [] (no rulers)",
+          "type": "array",
+          "items": {
+            "type": "integer",
+            "format": "uint",
+            "minimum": 0
+          },
+          "default": [],
+          "x-section": "Display"
+        },
         "tab_size": {
           "description": "Number of spaces per tab character",
           "type": "integer",
@@ -529,6 +563,22 @@
         }
       }
     },
+    "ClipboardConfig": {
+      "description": "Clipboard configuration\n\nControls which clipboard methods are used for copy/paste operations.\nBy default, all methods are enabled and the editor tries them in order:\n1. OSC 52 escape sequences (works in modern terminals like Kitty, Alacritty, Wezterm)\n2. System clipboard via X11/Wayland APIs (works in Gnome Console, XFCE Terminal, etc.)\n3. Internal clipboard (always available as fallback)\n\nIf you experience hangs or issues (e.g., when using PuTTY or certain SSH setups),\nyou can disable specific methods.",
+      "type": "object",
+      "properties": {
+        "use_osc52": {
+          "description": "Enable OSC 52 escape sequences for clipboard access (default: true)\nDisable this if your terminal doesn't support OSC 52 or if it causes hangs",
+          "type": "boolean",
+          "default": true
+        },
+        "use_system_clipboard": {
+          "description": "Enable system clipboard access via X11/Wayland APIs (default: true)\nDisable this if you don't have a display server or it causes issues",
+          "type": "boolean",
+          "default": true
+        }
+      }
+    },
     "TerminalConfig": {
       "description": "Terminal configuration",
       "type": "object",

package/plugins/lib/fresh.d.ts

@@ -250,6 +250,25 @@ type BufferInfo = {
 	* Length of buffer in bytes
 	*/
 	length: number;
+	/**
+	* Whether this is a virtual buffer (not backed by a file)
+	*/
+	is_virtual: boolean;
+	/**
+	* Current view mode of the active split: "source" or "compose"
+	*/
+	view_mode: string;
+	/**
+	* True if any split showing this buffer has compose mode enabled.
+	* Plugins should use this (not view_mode) to decide whether to maintain
+	* decorations, since decorations live on the buffer and are filtered
+	* per-split at render time.
+	*/
+	is_composing_in_any_split: boolean;
+	/**
+	* Compose width (if set), from the active split's view state
+	*/
+	compose_width: number | null;
 };
 type JsDiagnostic = {
 	/**
@@ -359,61 +378,66 @@ type FormatterPackConfig = {
 	*/
 	args: Array<string>;
 };
-type BackgroundProcessResult = {
+type TerminalResult = {
 	/**
-	* Unique process ID for later reference
+	* The created buffer ID (for use with setSplitBuffer, etc.)
 	*/
-	process_id: number;
+	bufferId: number;
 	/**
-	* Process exit code (0 usually means success, -1 if killed)
-	* Only present when the process has exited
+	* The terminal ID (for use with sendTerminalInput, closeTerminal)
 	*/
-	exit_code: number;
-};
-type BufferSavedDiff = {
-	equal: boolean;
-	byte_ranges: Array<[number, number]>;
-	line_ranges: Array<[number, number]> | null;
-};
-type TsCompositeHunk = {
+	terminalId: number;
 	/**
-	* Starting line in old buffer (0-indexed)
+	* The split ID (if created in a new split)
 	*/
-	oldStart: number;
+	splitId: number | null;
+};
+type CreateTerminalOptions = {
 	/**
-	* Number of lines in old buffer
+	* Working directory for the terminal (defaults to editor cwd)
 	*/
-	oldCount: number;
+	cwd?: string;
 	/**
-	* Starting line in new buffer (0-indexed)
+	* Split direction: "horizontal" or "vertical" (default: "vertical")
 	*/
-	newStart: number;
+	direction?: string;
 	/**
-	* Number of lines in new buffer
+	* Split ratio 0.0-1.0 (default: 0.5)
 	*/
-	newCount: number;
-};
-type TsCreateCompositeBufferOptions = {
+	ratio?: number;
 	/**
-	* Buffer name (displayed in tabs/title)
+	* Whether to focus the new terminal split (default: true)
 	*/
-	name: string;
+	focus?: boolean;
+};
+type CursorInfo = {
 	/**
-	* Mode for keybindings
+	* Byte position of the cursor
 	*/
-	mode: string;
+	position: number;
 	/**
-	* Layout configuration
+	* Selection range (if any)
 	*/
-	layout: TsCompositeLayoutConfig;
+	selection: {
+		start: number;
+		end: number;
+	} | null;
+};
+type BackgroundProcessResult = {
 	/**
-	* Source pane configurations
+	* Unique process ID for later reference
 	*/
-	sources: Array<TsCompositeSourceConfig>;
+	process_id: number;
 	/**
-	* Diff hunks for alignment (optional)
+	* Process exit code (0 usually means success, -1 if killed)
+	* Only present when the process has exited
 	*/
-	hunks: Array<TsCompositeHunk> | null;
+	exit_code: number;
+};
+type BufferSavedDiff = {
+	equal: boolean;
+	byte_ranges: Array<[number, number]>;
+	line_ranges: Array<[number, number]> | null;
 };
 type CreateVirtualBufferInExistingSplitOptions = {
 	/**
@@ -495,6 +519,10 @@ type CreateVirtualBufferInSplitOptions = {
 	*/
 	lineWrap?: boolean;
 	/**
+	* Place the new buffer before (left/top of) the existing content (default: false)
+	*/
+	before?: boolean;
+	/**
 	* Initial content entries with optional properties
 	*/
 	entries?: Array<TextPropertyEntry>;
@@ -600,28 +628,6 @@ type SpawnResult = {
 	*/
 	exit_code: number;
 };
-type PromptSuggestion = {
-	/**
-	* The text to display
-	*/
-	text: string;
-	/**
-	* Optional description
-	*/
-	description?: string;
-	/**
-	* The value to use when selected (defaults to text if None)
-	*/
-	value?: string;
-	/**
-	* Whether this suggestion is disabled (greyed out, defaults to false)
-	*/
-	disabled?: boolean;
-	/**
-	* Optional keyboard shortcut
-	*/
-	keybinding?: string;
-};
 type TextPropertiesAtCursor = Array<Record<string, unknown>>;
 type TsHighlightSpan = {
 	start: number;
@@ -644,6 +650,11 @@ type VirtualBufferResult = {
 * Main editor API interface
 */
 interface EditorAPI {
+	/**
+	* Get the plugin API version. Plugins can check this to verify
+	* the editor supports the features they need.
+	*/
+	apiVersion(): number;
 	/**
 	* Get the active buffer ID (0 if none)
 	*/
@@ -713,15 +724,15 @@ interface EditorAPI {
 	/**
 	* Get primary cursor info for active buffer
 	*/
-	getPrimaryCursor(): unknown;
+	getPrimaryCursor(): CursorInfo | null;
 	/**
 	* Get all cursors for active buffer
 	*/
-	getAllCursors(): unknown;
+	getAllCursors(): CursorInfo[];
 	/**
 	* Get all cursor positions as byte offsets
 	*/
-	getAllCursorPositions(): unknown;
+	getAllCursorPositions(): number[];
 	/**
 	* Get viewport info for active buffer
 	*/
@@ -825,6 +836,16 @@ interface EditorAPI {
 	*/
 	pathIsAbsolute(path: string): boolean;
 	/**
+	* Get the UTF-8 byte length of a JavaScript string.
+	* 
+	* JS strings are UTF-16 internally, so `str.length` returns the number of
+	* UTF-16 code units, not the number of bytes in a UTF-8 encoding.  The
+	* editor API uses byte offsets for all buffer positions (overlays, cursor,
+	* getBufferText ranges, etc.).  This helper lets plugins convert JS string
+	* lengths / regex match indices to the byte offsets the editor expects.
+	*/
+	utf8ByteLength(text: string): number;
+	/**
 	* Check if file exists
 	*/
 	fileExists(path: string): boolean;
@@ -906,7 +927,7 @@ interface EditorAPI {
 	/**
 	* Check if a background process is still running
 	*/
-	isProcessRunning(ProcessId: number): boolean;
+	isProcessRunning(processId: number): boolean;
 	/**
 	* Kill a process by ID (alias for killBackgroundProcess)
 	*/
@@ -921,13 +942,13 @@ interface EditorAPI {
 	* Uses typed CreateCompositeBufferOptions - serde validates field names at runtime
 	* via `deny_unknown_fields` attribute
 	*/
-	createCompositeBuffer(opts: CreateCompositeBufferOptions): Promise<number>;
+	createCompositeBuffer(opts: TsCreateCompositeBufferOptions): Promise<number>;
 	/**
 	* Update alignment hunks for a composite buffer
 	* 
 	* Uses typed Vec<CompositeHunk> - serde validates field names at runtime
 	*/
-	updateCompositeAlignment(bufferId: number, hunks: CompositeHunk[]): boolean;
+	updateCompositeAlignment(bufferId: number, hunks: TsCompositeHunk[]): boolean;
 	/**
 	* Close a composite buffer
 	*/
@@ -944,12 +965,16 @@ interface EditorAPI {
 	* 
 	* Theme key examples: "ui.status_bar_fg", "editor.selection_bg", "syntax.keyword"
 	* 
+	* Options: fg, bg (RGB array or theme key string), bold, italic, underline,
+	* strikethrough, extend_to_line_end (all booleans, default false).
+	* 
 	* Example usage in TypeScript:
 	* ```typescript
 	* editor.addOverlay(bufferId, "my-namespace", 0, 10, {
 	* fg: "syntax.keyword",           // theme key
 	* bg: [40, 40, 50],               // RGB array
 	* bold: true,
+	* strikethrough: true,
 	* });
 	* ```
 	*/
@@ -971,6 +996,30 @@ interface EditorAPI {
 	*/
 	removeOverlay(bufferId: number, handle: string): boolean;
 	/**
+	* Add a conceal range that hides or replaces a byte range during rendering
+	*/
+	addConceal(bufferId: number, namespace: string, start: number, end: number, replacement: string | null): boolean;
+	/**
+	* Clear all conceal ranges in a namespace
+	*/
+	clearConcealNamespace(bufferId: number, namespace: string): boolean;
+	/**
+	* Clear all conceal ranges that overlap with a byte range
+	*/
+	clearConcealsInRange(bufferId: number, start: number, end: number): boolean;
+	/**
+	* Add a soft break point for marker-based line wrapping
+	*/
+	addSoftBreak(bufferId: number, namespace: string, position: number, indent: number): boolean;
+	/**
+	* Clear all soft breaks in a namespace
+	*/
+	clearSoftBreakNamespace(bufferId: number, namespace: string): boolean;
+	/**
+	* Clear all soft breaks that fall within a byte range
+	*/
+	clearSoftBreaksInRange(bufferId: number, start: number, end: number): boolean;
+	/**
 	* Submit a view transform for a buffer/split
 	* 
 	* Accepts tokens in the simple format:
@@ -985,6 +1034,11 @@ interface EditorAPI {
 	*/
 	clearViewTransform(bufferId: number, splitId: number | null): boolean;
 	/**
+	* Set layout hints (compose width, column guides) for a buffer/split
+	* without going through the view_transform pipeline.
+	*/
+	setLayoutHints(bufferId: number, splitId: number | null, hints: LayoutHints): boolean;
+	/**
 	* Set file explorer decorations for a namespace
 	*/
 	setFileExplorerDecorations(namespace: string, decorations: Record<string, unknown>[]): boolean;
@@ -1034,7 +1088,8 @@ interface EditorAPI {
 	* 
 	* Uses typed Vec<Suggestion> - serde validates field names at runtime
 	*/
-	setPromptSuggestions(suggestions: Suggestion[]): boolean;
+	setPromptSuggestions(suggestions: PromptSuggestion[]): boolean;
+	setPromptInputSync(sync: boolean): boolean;
 	/**
 	* Define a buffer mode (takes bindings as array of [key, command] pairs)
 	*/
@@ -1068,6 +1123,18 @@ interface EditorAPI {
 	*/
 	setSplitRatio(splitId: number, ratio: number): boolean;
 	/**
+	* Set a label on a split (e.g., "sidebar")
+	*/
+	setSplitLabel(splitId: number, label: string): boolean;
+	/**
+	* Remove a label from a split
+	*/
+	clearSplitLabel(splitId: number): boolean;
+	/**
+	* Find a split by label (async)
+	*/
+	getSplitByLabel(label: string): Promise<number | null>;
+	/**
 	* Distribute all splits evenly
 	*/
 	distributeSplitsEvenly(): boolean;
@@ -1088,10 +1155,22 @@ interface EditorAPI {
 	*/
 	setLineNumbers(bufferId: number, enabled: boolean): boolean;
 	/**
+	* Set the view mode for a buffer ("source" or "compose")
+	*/
+	setViewMode(bufferId: number, mode: string): boolean;
+	/**
 	* Enable or disable line wrapping for a buffer/split
 	*/
 	setLineWrap(bufferId: number, splitId: number | null, enabled: boolean): boolean;
 	/**
+	* Set plugin-managed per-buffer view state (write-through to snapshot + command for persistence)
+	*/
+	setViewState(bufferId: number, key: string, value: unknown): boolean;
+	/**
+	* Get plugin-managed per-buffer view state (reads from snapshot)
+	*/
+	getViewState(bufferId: number, key: string): unknown;
+	/**
 	* Create a scroll sync group for anchor-based synchronized scrolling
 	*/
 	createScrollSyncGroup(groupId: number, leftSplit: number, rightSplit: number): boolean;
@@ -1183,6 +1262,18 @@ interface EditorAPI {
 	*/
 	killBackgroundProcess(processId: number): boolean;
 	/**
+	* Create a new terminal in a split (async, returns TerminalResult)
+	*/
+	createTerminal(opts?: CreateTerminalOptions): Promise<TerminalResult>;
+	/**
+	* Send input data to a terminal
+	*/
+	sendTerminalInput(terminalId: number, data: string): boolean;
+	/**
+	* Close a terminal
+	*/
+	closeTerminal(terminalId: number): boolean;
+	/**
 	* Force refresh of line display
 	*/
 	refreshLines(bufferId: number): boolean;