@fresh-editor/fresh-editor 0.2.12 → 0.2.14

package/plugins/lib/fresh.d.ts

@@ -16,6 +16,23 @@
 * Plugins must call this at the top of their file to get a scoped editor object.
 */
 declare function getEditor(): EditorAPI;
+/**
+* Register a function as a named handler on the global scope.
+*
+* Handler functions registered this way can be referenced by name in
+* `editor.registerCommand()`, `editor.on()`, and mode keybindings.
+*
+* The `fn` parameter is typed as `Function` because the runtime passes
+* different argument shapes depending on the caller: command handlers
+* receive no arguments, event handlers receive an event-specific data
+* object (e.g. `{ buffer_id: number }`), and prompt handlers receive
+* `{ prompt_type: string, input: string }`. Type-annotate your handler
+* parameters to match the event you are handling.
+*
+* @param name - Handler name (referenced by registerCommand, on, etc.)
+* @param fn - The handler function
+*/
+declare function registerHandler(name: string, fn: Function): void;
 /** Handle for a cancellable async operation */
 interface ProcessHandle<T> extends PromiseLike<T> {
 	/** Promise that resolves to the result when complete */
@@ -36,6 +53,14 @@ type TextPropertyEntry = {
 	* Optional properties attached to this text (e.g., file path, line number)
 	*/
 	properties?: Record<string, unknown>;
+	/**
+	* Optional whole-entry styling
+	*/
+	style?: Partial<OverlayOptions>;
+	/**
+	* Optional sub-range styling within this entry
+	*/
+	inlineOverlays?: Array<InlineOverlay>;
 };
 type TsCompositeLayoutConfig = {
 	/**
@@ -45,7 +70,7 @@ type TsCompositeLayoutConfig = {
 	/**
 	* Width ratios for side-by-side (e.g., [0.5, 0.5])
 	*/
-	ratios: Array<number> | null;
+	ratios?: Array<number>;
 	/**
 	* Show separator between panes
 	*/
@@ -53,7 +78,7 @@ type TsCompositeLayoutConfig = {
 	/**
 	* Spacing for stacked layout
 	*/
-	spacing: number | null;
+	spacing?: number;
 };
 type TsCompositeSourceConfig = {
 	/**
@@ -78,19 +103,19 @@ type TsCompositePaneStyle = {
 	* Background color for added lines (RGB)
 	* Using [u8; 3] instead of (u8, u8, u8) for better rquickjs_serde compatibility
 	*/
-	addBg: [number, number, number] | null;
+	addBg?: [number, number, number];
 	/**
 	* Background color for removed lines (RGB)
 	*/
-	removeBg: [number, number, number] | null;
+	removeBg?: [number, number, number];
 	/**
 	* Background color for modified lines (RGB)
 	*/
-	modifyBg: [number, number, number] | null;
+	modifyBg?: [number, number, number];
 	/**
 	* Gutter style: "line-numbers", "diff-markers", "both", or "none"
 	*/
-	gutterStyle: string | null;
+	gutterStyle?: string;
 };
 type TsCompositeHunk = {
 	/**
@@ -158,11 +183,11 @@ type LayoutHints = {
 	/**
 	* Optional compose width for centering/wrapping
 	*/
-	composeWidth: number | null;
+	composeWidth?: number;
 	/**
 	* Optional column guides for aligned tables
 	*/
-	columnGuides: Array<number> | null;
+	columnGuides?: Array<number>;
 };
 type ViewTokenWire = {
 	/**
@@ -386,6 +411,20 @@ type FormatterPackConfig = {
 	*/
 	args: Array<string>;
 };
+type ProcessLimitsPackConfig = {
+	/**
+	* Maximum memory usage as percentage of total system memory (null = no limit)
+	*/
+	maxMemoryPercent: number | null;
+	/**
+	* Maximum CPU usage as percentage of total CPU (null = no limit)
+	*/
+	maxCpuPercent: number | null;
+	/**
+	* Enable resource limiting
+	*/
+	enabled: boolean | null;
+};
 type TerminalResult = {
 	/**
 	* The created buffer ID (for use with setSplitBuffer, etc.)
@@ -431,6 +470,61 @@ type CursorInfo = {
 		end: number;
 	} | null;
 };
+type OverlayOptions = {
+	/**
+	* Foreground color - RGB array or theme key string
+	*/
+	fg?: OverlayColorSpec | null;
+	/**
+	* Background color - RGB array or theme key string
+	*/
+	bg?: OverlayColorSpec | null;
+	/**
+	* Whether to render with underline
+	*/
+	underline: boolean;
+	/**
+	* Whether to render in bold
+	*/
+	bold: boolean;
+	/**
+	* Whether to render in italic
+	*/
+	italic: boolean;
+	/**
+	* Whether to render with strikethrough
+	*/
+	strikethrough: boolean;
+	/**
+	* Whether to extend background color to end of line
+	*/
+	extendToLineEnd: boolean;
+	/**
+	* Optional URL for OSC 8 terminal hyperlinks.
+	* When set, the overlay text becomes a clickable hyperlink in terminals
+	* that support OSC 8 escape sequences.
+	*/
+	url?: string | null;
+};
+type OverlayColorSpec = [number, number, number] | string;
+type InlineOverlay = {
+	/**
+	* Start byte offset within the entry's text
+	*/
+	start: number;
+	/**
+	* End byte offset within the entry's text (exclusive)
+	*/
+	end: number;
+	/**
+	* Styling options for this range
+	*/
+	style: Partial<OverlayOptions>;
+	/**
+	* Optional properties for this sub-range (e.g., click target metadata)
+	*/
+	properties?: Record<string, any>;
+};
 type BackgroundProcessResult = {
 	/**
 	* Unique process ID for later reference
@@ -621,6 +715,10 @@ type LspServerPackConfig = {
 	* LSP initialization options
 	*/
 	initializationOptions: Record<string, unknown> | null;
+	/**
+	* Process resource limits (memory and CPU)
+	*/
+	processLimits: ProcessLimitsPackConfig | null;
 };
 type SpawnResult = {
 	/**
@@ -683,10 +781,16 @@ interface EditorAPI {
 	copyToClipboard(text: string): void;
 	setClipboard(text: string): void;
 	/**
-	* Register a command - reads plugin name from __pluginName__ global
-	* context is optional - can be omitted, null, undefined, or a string
+	* Register a command in the command palette (Ctrl+P).
+	* 
+	* Usually you should omit `context` so the command is always visible.
+	* If provided, the command is **hidden** unless your plugin has activated
+	* that context with `editor.setContext(name, true)` or the focused buffer's
+	* virtual mode (from `defineMode()`) matches. This is for plugin-defined
+	* contexts only (e.g. `"tour-active"`, `"review-mode"`), not built-in
+	* editor modes.
 	*/
-	registerCommand(name: string, description: string, handlerName: string, context?: unknown): boolean;
+	registerCommand(name: string, description: string, handlerName: string, context?: string | null): boolean;
 	/**
 	* Unregister a command by name
 	*/
@@ -899,6 +1003,10 @@ interface EditorAPI {
 	*/
 	reloadThemes(): void;
 	/**
+	* Reload theme registry and apply a theme atomically
+	*/
+	reloadAndApplyTheme(themeName: string): void;
+	/**
 	* Register a TextMate grammar file for a language
 	* The grammar will be pending until reload_grammars() is called
 	*/
@@ -912,10 +1020,11 @@ interface EditorAPI {
 	*/
 	registerLspServer(language: string, config: LspServerPackConfig): boolean;
 	/**
-	* Reload the grammar registry to apply registered grammars
-	* Call this after registering one or more grammars
+	* Reload the grammar registry to apply registered grammars (async)
+	* Call this after registering one or more grammars.
+	* Returns a Promise that resolves when the grammar rebuild completes.
 	*/
-	reloadGrammars(): void;
+	reloadGrammars(): Promise<void>;
 	/**
 	* Get config directory path
 	*/
@@ -941,6 +1050,18 @@ interface EditorAPI {
 	*/
 	deleteTheme(name: string): boolean;
 	/**
+	* Get theme data (JSON) by name from the in-memory cache
+	*/
+	getThemeData(name: string): unknown;
+	/**
+	* Save a theme file to the user themes directory, returns the saved path
+	*/
+	saveThemeFile(name: string, content: string): string;
+	/**
+	* Check if a user theme file exists
+	*/
+	themeFileExists(name: string): boolean;
+	/**
 	* Get file stat information
 	*/
 	fileStat(path: string): unknown;
@@ -1223,6 +1344,10 @@ interface EditorAPI {
 	*/
 	disableLspForLanguage(language: string): boolean;
 	/**
+	* Restart LSP server for a specific language
+	*/
+	restartLspForLanguage(language: string): boolean;
+	/**
 	* Set the workspace root URI for a specific language's LSP server
 	* This allows plugins to specify project roots (e.g., directory containing .csproj)
 	*/

package/plugins/live_grep.ts

@@ -75,7 +75,7 @@ async function searchWithRipgrep(query: string): Promise<GrepMatch[]> {
 }
 
 // Start live grep
-globalThis.start_live_grep = function (): void {
+function start_live_grep() : void {
   finder.prompt({
     title: editor.t("prompt.live_grep"),
     source: {
@@ -85,7 +85,8 @@ globalThis.start_live_grep = function (): void {
       minQueryLength: 2,
     },
   });
-};
+}
+registerHandler("start_live_grep", start_live_grep);
 
 // Register command
 editor.registerCommand(

package/plugins/markdown_compose.ts

@@ -390,7 +390,7 @@ function enableMarkdownCompose(bufferId: number): void {
   editor.setLineWrap(bufferId, null, true);
 
   // Set layout hints for centered margins
-  editor.setLayoutHints(bufferId, null, { composeWidth: config.composeWidth });
+  editor.setLayoutHints(bufferId, null, { composeWidth: config.composeWidth ?? undefined });
 
   // Trigger a refresh so lines_changed hooks fire for visible content
   editor.refreshLines(bufferId);
@@ -421,7 +421,7 @@ function disableMarkdownCompose(bufferId: number): void {
 }
 
 // Toggle markdown compose mode for current buffer
-globalThis.markdownToggleCompose = function(): void {
+function markdownToggleCompose() : void {
   const bufferId = editor.getActiveBufferId();
   const info = editor.getBufferInfo(bufferId);
 
@@ -442,7 +442,8 @@ globalThis.markdownToggleCompose = function(): void {
     editor.refreshLines(bufferId);
     editor.setStatus(editor.t("status.compose_on"));
   }
-};
+}
+registerHandler("markdownToggleCompose", markdownToggleCompose);
 
 /**
  * Extract text content from incoming tokens
@@ -1360,7 +1361,7 @@ function processTableAlignment(
 }
 
 // lines_changed: called for newly visible or invalidated lines
-globalThis.onMarkdownLinesChanged = function(data: {
+function onMarkdownLinesChanged(data: {
   buffer_id: number;
   lines: Array<{
     line_number: number;
@@ -1394,7 +1395,8 @@ globalThis.onMarkdownLinesChanged = function(data: {
   if (tableWidthsGrew) {
     editor.refreshLines(data.buffer_id);
   }
-};
+}
+registerHandler("onMarkdownLinesChanged", onMarkdownLinesChanged);
 
 // after_insert: no-op for conceals/overlays.
 // The edit automatically invalidates seen_byte_ranges for affected lines,
@@ -1402,7 +1404,7 @@ globalThis.onMarkdownLinesChanged = function(data: {
 // handles clearing and rebuilding atomically.
 // Marker-based positions auto-adjust with buffer edits, so existing conceals
 // remain visually correct until lines_changed rebuilds them.
-globalThis.onMarkdownAfterInsert = function(data: {
+function onMarkdownAfterInsert(data: {
   buffer_id: number;
   position: number;
   text: string;
@@ -1411,10 +1413,11 @@ globalThis.onMarkdownAfterInsert = function(data: {
 }): void {
   if (!isComposingInAnySplit(data.buffer_id)) return;
   editor.debug(`[mc] after_insert: pos=${data.position} text="${data.text.replace(/\n/g,'\\n')}" affected=${data.affected_start}..${data.affected_end}`);
-};
+}
+registerHandler("onMarkdownAfterInsert", onMarkdownAfterInsert);
 
 // after_delete: no-op for conceals/overlays (same reasoning as after_insert).
-globalThis.onMarkdownAfterDelete = function(data: {
+function onMarkdownAfterDelete(data: {
   buffer_id: number;
   start: number;
   end: number;
@@ -1424,10 +1427,11 @@ globalThis.onMarkdownAfterDelete = function(data: {
 }): void {
   if (!isComposingInAnySplit(data.buffer_id)) return;
   editor.debug(`[mc] after_delete: start=${data.start} end=${data.end} deleted="${data.deleted_text.replace(/\n/g,'\\n')}" affected_start=${data.affected_start} deleted_len=${data.deleted_len}`);
-};
+}
+registerHandler("onMarkdownAfterDelete", onMarkdownAfterDelete);
 
 // cursor_moved: update cursor-aware reveal/conceal for old and new cursor lines
-globalThis.onMarkdownCursorMoved = function(data: {
+function onMarkdownCursorMoved(data: {
   buffer_id: number;
   cursor_id: number;
   old_position: number;
@@ -1445,7 +1449,8 @@ globalThis.onMarkdownCursorMoved = function(data: {
   // auto-expose is span-level (cursor entering/leaving an emphasis or link
   // span within the same line must toggle its syntax markers).
   editor.refreshLines(data.buffer_id);
-};
+}
+registerHandler("onMarkdownCursorMoved", onMarkdownCursorMoved);
 
 // view_transform_request is no longer needed — soft wrapping is handled by
 // marker-based soft breaks (computed in lines_changed), and layout hints
@@ -1453,12 +1458,13 @@ globalThis.onMarkdownCursorMoved = function(data: {
 // caused by the async view_transform round-trip.
 
 // Handle buffer close events - clean up compose mode tracking
-globalThis.onMarkdownBufferClosed = function(data: { buffer_id: number }): void {
+function onMarkdownBufferClosed(data: { buffer_id: number }) : void {
   // View state is cleaned up automatically when the buffer is removed from keyed_states
-};
+}
+registerHandler("onMarkdownBufferClosed", onMarkdownBufferClosed);
 
 // viewport_changed: recalculate table column widths on terminal resize
-globalThis.onMarkdownViewportChanged = function(data: {
+function onMarkdownViewportChanged(data: {
   split_id: number;
   buffer_id: number;
   top_byte: number;
@@ -1485,12 +1491,13 @@ globalThis.onMarkdownViewportChanged = function(data: {
     setTableWidths(data.buffer_id, bufWidths);
   }
   editor.refreshLines(data.buffer_id);
-};
+}
+registerHandler("onMarkdownViewportChanged", onMarkdownViewportChanged);
 
 // Re-enable compose mode for buffers restored from a saved session.
 // The Rust side restores ViewMode::Compose and compose_width, but the plugin
 // needs to re-apply line numbers, line wrap, and layout hints when activated.
-globalThis.onMarkdownBufferActivated = function(data: { buffer_id: number }): void {
+function onMarkdownBufferActivated(data: { buffer_id: number }) : void {
   const bufferId = data.buffer_id;
 
   const info = editor.getBufferInfo(bufferId);
@@ -1505,7 +1512,8 @@ globalThis.onMarkdownBufferActivated = function(data: { buffer_id: number }): vo
     }
     enableMarkdownCompose(bufferId);
   }
-};
+}
+registerHandler("onMarkdownBufferActivated", onMarkdownBufferActivated);
 
 // Register hooks
 editor.on("lines_changed", "onMarkdownLinesChanged");
@@ -1519,7 +1527,7 @@ editor.on("prompt_confirmed", "onMarkdownComposeWidthConfirmed");
 editor.on("buffer_activated", "onMarkdownBufferActivated");
 
 // Set compose width command - starts interactive prompt
-globalThis.markdownSetComposeWidth = function(): void {
+function markdownSetComposeWidth() : void {
   const currentValue = config.composeWidth === null ? "None" : String(config.composeWidth);
   editor.startPromptWithInitial(editor.t("prompt.compose_width"), "markdown-compose-width", currentValue);
   editor.setPromptInputSync(true);
@@ -1527,10 +1535,11 @@ globalThis.markdownSetComposeWidth = function(): void {
     { text: "None", description: editor.t("suggestion.none") },
     { text: "120", description: editor.t("suggestion.default") },
   ]);
-};
+}
+registerHandler("markdownSetComposeWidth", markdownSetComposeWidth);
 
 // Handle compose width prompt confirmation
-globalThis.onMarkdownComposeWidthConfirmed = function(args: {
+function onMarkdownComposeWidthConfirmed(args: {
   prompt_type: string;
   input: string;
 }): void {
@@ -1543,7 +1552,7 @@ globalThis.onMarkdownComposeWidthConfirmed = function(args: {
 
     const bufferId = editor.getActiveBufferId();
     if (isComposing(bufferId)) {
-      editor.setLayoutHints(bufferId, null, { composeWidth: null });
+      editor.setLayoutHints(bufferId, null, {});
       editor.refreshLines(bufferId);
     }
     return;
@@ -1557,13 +1566,14 @@ globalThis.onMarkdownComposeWidthConfirmed = function(args: {
     // Re-process active buffer if in compose mode
     const bufferId = editor.getActiveBufferId();
     if (isComposing(bufferId)) {
-      editor.setLayoutHints(bufferId, null, { composeWidth: config.composeWidth });
+      editor.setLayoutHints(bufferId, null, { composeWidth: config.composeWidth ?? undefined });
       editor.refreshLines(bufferId);  // Trigger soft break recomputation
     }
   } else {
     editor.setStatus(editor.t("status.invalid_width"));
   }
-};
+}
+registerHandler("onMarkdownComposeWidthConfirmed", onMarkdownComposeWidthConfirmed);
 
 // Register commands
 editor.registerCommand(

package/plugins/markdown_source.ts

@@ -148,7 +148,7 @@ async function readRestOfLine(bufferId: number, cursorPos: number): Promise<stri
 // Enter handler: auto-continue list items or match indentation
 // ---------------------------------------------------------------------------
 
-globalThis.md_src_enter = async function (): Promise<void> {
+async function md_src_enter() : Promise<void> {
   const bufferId = editor.getActiveBufferId();
   if (!bufferId) {
     editor.executeAction("insert_newline");
@@ -203,13 +203,14 @@ globalThis.md_src_enter = async function (): Promise<void> {
     }
   }
   editor.insertAtCursor("\n" + indent);
-};
+}
+registerHandler("md_src_enter", md_src_enter);
 
 // ---------------------------------------------------------------------------
 // Tab handler: indent + cycle bullet on blank list items, else insert spaces
 // ---------------------------------------------------------------------------
 
-globalThis.md_src_tab = async function (): Promise<void> {
+async function md_src_tab() : Promise<void> {
   const bufferId = editor.getActiveBufferId();
   if (!bufferId) {
     editor.insertAtCursor(" ".repeat(TAB_SIZE));
@@ -249,13 +250,14 @@ globalThis.md_src_tab = async function (): Promise<void> {
 
   // Default: insert spaces
   editor.insertAtCursor(" ".repeat(TAB_SIZE));
-};
+}
+registerHandler("md_src_tab", md_src_tab);
 
 // ---------------------------------------------------------------------------
 // Shift+Tab handler: de-indent + reverse-cycle bullet on blank list items
 // ---------------------------------------------------------------------------
 
-globalThis.md_src_shift_tab = async function (): Promise<void> {
+async function md_src_shift_tab() : Promise<void> {
   const bufferId = editor.getActiveBufferId();
   if (!bufferId) {
     editor.executeAction("dedent_selection");
@@ -300,7 +302,8 @@ globalThis.md_src_shift_tab = async function (): Promise<void> {
 
   // Default: fall through to built-in dedent
   editor.executeAction("dedent_selection");
-};
+}
+registerHandler("md_src_shift_tab", md_src_shift_tab);
 
 // ---------------------------------------------------------------------------
 // Mode definition
@@ -340,13 +343,15 @@ function updateMarkdownMode(): void {
   }
 }
 
-globalThis.md_src_on_buffer_activated = function (): void {
+function md_src_on_buffer_activated() : void {
   updateMarkdownMode();
-};
+}
+registerHandler("md_src_on_buffer_activated", md_src_on_buffer_activated);
 
-globalThis.md_src_on_language_changed = function (): void {
+function md_src_on_language_changed() : void {
   updateMarkdownMode();
-};
+}
+registerHandler("md_src_on_language_changed", md_src_on_language_changed);
 
 editor.on("buffer_activated", "md_src_on_buffer_activated");
 editor.on("language_changed", "md_src_on_language_changed");

package/plugins/marksman-lsp.ts

@@ -22,7 +22,7 @@ interface ActionPopupResultData {
 const INSTALL_URL = "https://github.com/artempyanykh/marksman#how-to-install";
 let markdownLspError: { serverCommand: string; message: string } | null = null;
 
-globalThis.on_markdown_lsp_server_error = function (data: LspServerErrorData): void {
+function on_markdown_lsp_server_error(data: LspServerErrorData) : void {
   if (data.language !== "markdown") return;
   markdownLspError = { serverCommand: data.server_command, message: data.message };
   if (data.error_type === "not_found") {
@@ -30,10 +30,11 @@ globalThis.on_markdown_lsp_server_error = function (data: LspServerErrorData): v
   } else {
     editor.setStatus(`Markdown LSP error: ${data.message}`);
   }
-};
+}
+registerHandler("on_markdown_lsp_server_error", on_markdown_lsp_server_error);
 editor.on("lsp_server_error", "on_markdown_lsp_server_error");
 
-globalThis.on_markdown_lsp_status_clicked = function (data: LspStatusClickedData): void {
+function on_markdown_lsp_status_clicked(data: LspStatusClickedData) : void {
   if (data.language !== "markdown" || !markdownLspError) return;
   editor.showActionPopup({
     id: "marksman-lsp-help",
@@ -45,10 +46,11 @@ globalThis.on_markdown_lsp_status_clicked = function (data: LspStatusClickedData
       { id: "dismiss", label: "Dismiss (ESC)" },
     ],
   });
-};
+}
+registerHandler("on_markdown_lsp_status_clicked", on_markdown_lsp_status_clicked);
 editor.on("lsp_status_clicked", "on_markdown_lsp_status_clicked");
 
-globalThis.on_markdown_lsp_action_result = function (data: ActionPopupResultData): void {
+function on_markdown_lsp_action_result(data: ActionPopupResultData) : void {
   if (data.popup_id !== "marksman-lsp-help") return;
   switch (data.action_id) {
     case "copy_url":
@@ -61,5 +63,6 @@ globalThis.on_markdown_lsp_action_result = function (data: ActionPopupResultData
       markdownLspError = null;
       break;
   }
-};
+}
+registerHandler("on_markdown_lsp_action_result", on_markdown_lsp_action_result);
 editor.on("action_popup_result", "on_markdown_lsp_action_result");