How the Markdown Editor Handles Partial File Awareness in File Previews

The DesktopCommanderMCP Markdown Editor uses a state-aware controller to display lightweight previews of large files by loading only initial fragments, then seamlessly fetches the complete document when users transition to edit mode.

The Markdown Editor in the wonderwhy-er/DesktopCommanderMCP repository implements partial file awareness to deliver fast preview experiences without sacrificing editing capabilities. When opening large Markdown documents, the system loads only a fragment into memory initially, allowing the UI to render instantly while preserving the ability to fetch full content on demand. This architecture centers on the MarkdownController class in src/ui/file-preview/src/markdown/controller.ts, which orchestrates the transition between partial previews and complete document editing.

Detecting and Storing Partial Payloads

When a file preview is requested, the controller receives a payload containing filePath, fileName, fileType, and a boolean partial flag. If partial is true, the content represents only a fragment of the full file—typically the first N lines or bytes—rather than the complete document.

The controller maintains internal state through controller.state.partialPayload, which preserves the fragment until the full document is required. This storage mechanism allows the preview component to render immediately without blocking the UI thread while waiting for disk I/O operations on large files.

Auto-Loading Full Content on Edit

Upon entering edit mode via controller.requestEditMode(), the system checks whether state.partialPayload exists. If the current view is based on a partial fragment, the controller issues a read request with offset: 0 and length: -1 to fetch the entire file, replaces the partial state with the complete content, and mounts the editor with the full document.

During this transition, the controller preserves cursor positions, scroll offsets, and text selections. Once the complete document loads, it restores this context to ensure a seamless user experience without cursor jumps or view resets.

Core Implementation in the Markdown Controller

The MarkdownController class encapsulates the logic for handling partial file awareness in file previews through three primary methods:

// src/ui/file-preview/src/markdown/controller.ts (excerpt)
export class MarkdownController {
  private state = {
    partialPayload?: PartialPayload,
    fullDocument?: DocumentContent,
    // …
  };

  // Called when a preview payload arrives
  async handlePreviewPayload(payload: PreviewPayload) {
    if (payload.partial) {
      this.state.partialPayload = payload;           // keep the fragment
    } else {
      this.state.fullDocument = payload.content;    // full file already loaded
    }
    this.renderPreview();                           // render whatever we have
  }

  // Switch to edit mode – triggers a full read if we only have a fragment
  async requestEditMode() {
    if (this.state.partialPayload) {
      // Ask the server for the complete file (offset 0, length -1)
      const full = await readFile(this.state.partialPayload.filePath, {offset: 0, length: -1});
      this.state.fullDocument = full;
      this.state.partialPayload = undefined;
    }
    this.mountEditor(this.state.fullDocument!);
  }

  // Save routine – can emit a partial update if only a small region changed
  async saveChanges(changes: ChangeSet) {
    if (changes.isPartial && this.state.partialPayload) {
      await writePartial(this.state.partialPayload.filePath, changes);
    } else {
      await writeFull(this.state.fullDocument!.path, this.state.fullDocument!);
    }
  }
}

Partial File Handling Workflow

Opening a Markdown File (Preview-First)

To initiate a preview with partial file awareness, the UI requests a fragment rather than the full document:

// UI code that initiates a preview request
const payload = await requestFilePreview({
  path: '/docs/guide.md',
  partial: true,          // ask the backend for a small fragment only
  length: 200,            // e.g., first 200 bytes
});

// The controller receives the partial payload and renders it immediately
markdownController.handlePreviewPayload(payload);

Switching to Edit Mode

When the user clicks the edit button, the controller automatically resolves the partial state:

// User clicks the "Edit" button
editButton.addEventListener('click', async () => {
  await markdownController.requestEditMode(); // triggers a full read if needed
});

This call triggers the full file read with offset: 0 and length: -1, replacing the partial payload before mounting the editor.

Saving After Partial Edits

The controller optimizes write operations by detecting when only a subset of the file has changed:

// During edit, only the first few lines changed
const changes = {
  start: 0,
  end: 10,
  text: '# Updated Title\n',

  isPartial: true,
};

await markdownController.saveChanges(changes);

When changes.isPartial is true and the original state was a partial payload, the system uses writePartial() to update only the modified region rather than rewriting the entire file.

Verification Through Test Coverage

The test suite in test/test-markdown-preview.js validates the partial file handling logic through explicit assertions:

• Partial-save detection: Verifies the preview retains the partialPayload state after simulated disk saves using assert.ok(controller.getState(partialPayload).partial)
• Full-load replacement: Confirms that entering fullscreen edit mode replaces the partial baseline with the full document via controller.requestEditMode(partialPayload)
• Partial-read auto-load: Validates that the UI correctly auto-loads missing sections when the full file becomes available, checking that read arguments match { path: partialPayload.filePath, offset: 0, length: 3, origin: 'ui' }

Summary

• The MarkdownController in src/ui/file-preview/src/markdown/controller.ts manages the transition between partial previews and full document editing.
• Partial payloads are detected via the partial flag and stored in state.partialPayload for immediate rendering.
• Entering edit mode triggers an automatic full file read with offset: 0 and length: -1 if only a fragment is currently loaded.
• The editor preserves cursor position and scroll context during the transition from preview to edit mode.
• Save operations can use partial writes when changes.isPartial is true, optimizing disk I/O for large files.

Frequently Asked Questions

What is partial file awareness in DesktopCommanderMCP?

Partial file awareness is an optimization technique where the Markdown Editor loads only a small fragment of a large file (such as the first 200 bytes) to display an instant preview, then fetches the complete document only when the user initiates edit mode. This approach minimizes memory usage and reduces initial load times for large Markdown files.

How does the MarkdownController detect if a file is partially loaded?

The controller checks the partial boolean field in the incoming PreviewPayload. When handlePreviewPayload() receives a payload with partial: true, it stores the content in state.partialPayload rather than state.fullDocument, signaling that the complete file content is not yet available in memory.

What happens when you switch from preview to edit mode?

When requestEditMode() is called, the controller checks if state.partialPayload exists. If present, it automatically issues a readFile() call with offset: 0 and length: -1 to fetch the entire document, replaces the partial state with the complete content, and then mounts the editor while preserving the user's scroll position and cursor location.

Can the editor save only modified portions of a file?

Yes. The saveChanges() method accepts a ChangeSet object with an isPartial flag. If this flag is true and the original state was a partial payload, the controller invokes writePartial() to update only the modified region rather than rewriting the entire file, which significantly improves performance for minor edits in large documents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}