@fresh-editor/fresh-editor 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Release Notes
 
+## 0.2.5
+
+### Features
+
+* **Persistent Auto-Save**: New `auto_save_enabled` config option (default: false) to automatically save modified buffers to their original file at a configurable interval (`auto_save_interval_secs`, default: 30s) (#542)
+
+* **Smart Home**: Home key now uses smart home behavior by default, toggling between the first non-whitespace character and column 0. On soft-wrapped lines, smart home respects visual line boundaries instead of jumping to the physical line start (#1064).
+
+### Bug Fixes
+
+* **Diff View Scrollbar**: Fixed scrollbar click-to-jump and thumb drag not working in side-by-side diff views. Composite buffer views now use row-based scrolling via CompositeViewState.
+
+* **Terminal Bracket Paste**: Fixed pasted text going into the editor buffer instead of the terminal PTY when in terminal mode (#1056).
+
+* **LSP did_open Reliability**: Fixed buffer being incorrectly marked as LSP-opened when the did_open send fails, which prevented retry and could corrupt server document state.
+
+* **Remote Editing Data Loss**: Fixed intermittent data loss when loading large files via SSH remote editing on macOS. The bounded channel now uses backpressure instead of silently dropping data when the buffer overflows (#1059).
+
+### Configuration
+
+* Renamed `auto_save_interval_secs` (recovery) to `auto_recovery_save_interval_secs` to distinguish it from the new persistent auto-save feature. Added `auto_recovery_save_interval_secs` config option (default: 2s).
+
+### Internal
+
+* Introduced typed `LeafId` and `ContainerId` wrappers around `SplitId` to enforce leaf-vs-container constraints at compile time.
+* Enabled `#![deny(clippy::let_underscore_must_use)]` crate-wide; all ignored `Result` values now have explicit annotations or proper error handling.
+* Made `request_completion` and `request_signature_help` infallible, removing dead `Result` return types.
+* Added CONTRIBUTING.md with development guidelines.
+
+---
+
+## 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/README.md

@@ -2,7 +2,7 @@
 
 A modern, full-featured terminal text editor, **with zero configuration**. Familiar keybindings, mouse support, and IDE-level features — no learning curve required.
 
-[Official Website](https://sinelaw.github.io/fresh/)  ·  [Documentation](https://getfresh.dev/docs)  ·  [Discord](https://discord.gg/qUutBj9t)  ·  [Contributing](#contributing)
+[Official Website](https://sinelaw.github.io/fresh/)  ·  [Documentation](https://getfresh.dev/docs)  ·  [Discord](https://discord.gg/GpNWqMUH)  ·  [Contributing](#contributing)
 
 **[Quick Install](#installation):**   `curl https://raw.githubusercontent.com/sinelaw/fresh/refs/heads/master/scripts/install.sh | sh`
 
@@ -240,30 +240,7 @@ cargo build --release
 
 ## Contributing
 
-Thanks for contributing!
-
-1. **Reproduce Before Fixing**: Always include a test case that reproduces the bug (fails) without the fix, and passes with the fix. This ensures the issue is verified and prevents future regressions.
-
-2. **E2E Tests for New Flows**: Any new user flow or feature must include an end-to-end (e2e) test. E2E tests send keyboard/mouse events and examines the final rendered output, do not examine internal state.
-
-3. **No timeouts or time-sensitive tests**: Use "semantic waiting" (waiting for specific state changes/events) instead of fixed timers to ensure test stability. Wait indefinitely, don't put timeouts inside tests (cargo nextest will timeout externally).
-
-4. **Test isolation**: Tests should run in parallel. Use the internal clipboard mode in tests to isolate them from the host system and prevent flakiness in CI. Same for other external resources (temp files, etc. should all be isolated between tests, under a per-test temporary workdir).
-
-5. **Required Formatting**: All code must be formatted with `cargo fmt` before submission. PRs that fail formatting checks will not be merged.
-
-6. **Cross-Platform Consistency**: Avoid hard-coding newline or CRLF related logic, consider the buffer mode.
-
-7. **LSP**: Ensure LSP interactions follow the correct lifecycle (e.g., `didOpen` must always precede other requests to avoid server-side errors). Use the appropriate existing helpers for this pattern.
-
-8. **Regenerate plugin types and schemas**: After modifying the plugin API or config types:
-   - **TypeScript definitions** (`plugins/lib/fresh.d.ts`): Auto-generated from Rust types with `#[derive(TS)]`. Run: `cargo test -p fresh-plugin-runtime write_fresh_dts_file -- --ignored`
-   - **JSON schemas** (`plugins/config-schema.json`, `plugins/schemas/theme.schema.json`): Auto-generated from Rust types with `#[derive(JsonSchema)]`. Run: `./scripts/gen_schema.sh`
-   - **Package schema** (`plugins/schemas/package.schema.json`): Manually maintained - edit directly when adding new language pack fields
-
-9. **Type check plugins**: Run `crates/fresh-editor/plugins/check-types.sh` (requires `tsc`)
-
-**Tip**: You can use tmux + send-keys + render-pane to script ad-hoc tests on the UI, for example when trying to reproduce an issue.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## Privacy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fresh-editor/fresh-editor",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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,
@@ -55,8 +58,10 @@
         "mouse_hover_enabled": true,
         "mouse_hover_delay_ms": 500,
         "double_click_time_ms": 500,
+        "auto_save_enabled": false,
+        "auto_save_interval_secs": 30,
         "recovery_enabled": true,
-        "auto_save_interval_secs": 2,
+        "auto_recovery_save_interval_secs": 2,
         "auto_revert_poll_interval_ms": 2000,
         "keyboard_disambiguate_escape_codes": true,
         "keyboard_report_event_types": false,
@@ -88,6 +93,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 +243,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 +267,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",
@@ -354,14 +390,28 @@
           "default": 500,
           "x-section": "Mouse"
         },
+        "auto_save_enabled": {
+          "description": "Whether to enable persistent auto-save (save to original file on disk).\nWhen enabled, modified buffers are saved to their original file path\nat a configurable interval.\nDefault: false",
+          "type": "boolean",
+          "default": false,
+          "x-section": "Recovery"
+        },
+        "auto_save_interval_secs": {
+          "description": "Interval in seconds for persistent auto-save.\nModified buffers are saved to their original file at this interval.\nOnly effective when auto_save_enabled is true.\nDefault: 30 seconds",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0,
+          "default": 30,
+          "x-section": "Recovery"
+        },
         "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",
           "default": true,
           "x-section": "Recovery"
         },
-        "auto_save_interval_secs": {
-          "description": "Auto-save interval in seconds for file recovery\nModified buffers are saved to recovery files at this interval.\nDefault: 2 seconds for fast recovery with minimal data loss.\nSet to 0 to disable periodic auto-save (manual recovery only).",
+        "auto_recovery_save_interval_secs": {
+          "description": "Interval in seconds for auto-recovery-save.\nModified buffers are saved to recovery files at this interval.\nOnly effective when recovery_enabled is true.\nDefault: 2 seconds",
           "type": "integer",
           "format": "uint32",
           "minimum": 0,
@@ -529,6 +579,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;