# How the Markdown Editor Handles Partial File Awareness in File Previews

> Discover how the DesktopCommanderMCP Markdown Editor achieves partial file awareness for efficient large file previews, loading only initial fragments for faster loading and seamless editing.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: internals
- Published: 2026-07-09

---

**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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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.