How the Core/Watch Component Enables Live Previews and Inline Editing in OfficeCLI

The Core/Watch component uses Server-Sent Events (SSE) and fine-grained DOM patching to deliver real-time document updates without page reloads, while a re-apply hook architecture keeps inline editing decorations synchronized across Word, Excel, and PowerPoint previews.

The iOfficeAI/OfficeCLI repository provides a command-line interface for Office document manipulation, featuring a sophisticated Core/Watch component that transforms static previews into live editing environments. This system eliminates the traditional save-refresh cycle by establishing persistent server connections and surgically updating only changed DOM elements. Understanding how the Core/Watch component enables live previews and inline editing reveals a lightweight, event-driven architecture that supports Word, Excel, and PowerPoint documents through two embedded JavaScript resources.

Core Architecture: SSE and DOM Patching

The Core/Watch implementation relies on two primary files: src/officecli/Resources/watch-sse-core.js handles the server communication and mutation logic, while src/officecli/Resources/watch-overlay.js manages the user interface layer. Together they create a reactive preview system that maintains state across document modifications.

Establishing the Server-Sent Events Channel

When a preview page loads, the component immediately creates an EventSource connection pointing to the /events endpoint. According to the source code in watch-sse-core.js (lines 11-13), this connection is stored on window._watchEs to make it accessible to the overlay layer:

// Automatically initialized on page load
// The SSE endpoint remains open for the duration of the session
window._watchEs = new EventSource('/events');

This persistent connection allows the backend to push updates instantly, eliminating the need for polling or manual refresh actions.

The Re-apply Hook Pattern

A critical architectural feature is the separation between DOM mutations and UI decoration updates. The core layer defines _callReapplyHook() (lines 16-18 in watch-sse-core.js), which invokes a function registered by the overlay as window._watchReapplyHook. This callback executes after every DOM mutation to restore highlights, selection marks, and other visual decorations:

// Implementation in watch-overlay.js
function reapplyDecorations() {
  // Restore highlights, cursors, and selection states
  // after the core layer modifies the DOM
}
window._watchReapplyHook = reapplyDecorations;

This hook ensures that inline editing controls remain functional and visible even as the underlying document content changes.

Document-Specific Update Strategies

The Core/Watch component handles different Office document types through specialized update handlers. When the SSE listener receives an update event (lines 17-67 in watch-sse-core.js), it parses the JSON payload and dispatches to the appropriate handler based on msg.action.

Word Documents: Patch and Diff Updates

For Word-type documents, the system supports two update modes. Patch updates (word-patch) manipulate block-level markers (.wb and .we classes) to replace, add, or remove content sections. After each mutation, _callReapplyHook() runs to preserve inline decorations (lines 38-45). Diff updates (word-diff) perform lightweight section comparisons, re-paginate the content, and then trigger the re-apply hook to refresh the UI.

Excel Spreadsheets: Row-Level Mutations

Excel documents receive updates through row-specific selectors (tr[data-row]). The handler refreshes styles, adds new rows, removes deleted ones, or replaces modified data while maintaining spreadsheet structure. As with Word documents, each mutation concludes with a call to the re-apply hook (lines 47-55 in watch-sse-core.js).

PowerPoint Presentations: Slide Container Management

PowerPoint updates target <div class="slide-container"> elements directly. The action handlers support replace, add, and remove operations that manipulate individual slides without disturbing the rest of the deck. After updating the DOM, the system re-executes embedded scripts, synchronizes thumbnail navigation, and adjusts the scroll target (lines 27-65).

Handling Navigation and Full Replacements

Not all updates require DOM manipulation. For scroll-only updates, the scroll action moves the view to a specific selector or slide without touching the document structure, enabling instant navigation while the document remains live (lines 22-32 in watch-sse-core.js).

When the backend signals a full action, the Core/Watch component performs either a diff fallback (for Word documents) or a complete body replacement via _replaceDocumentBody. This replacement strategically preserves the SSE script and scroll position before calling the re-apply hook to restore the UI state (lines 13-26).

Overlay Integration for Inline Editing

The watch-overlay.js file completes the live editing experience by registering UI controls and binding the decoration system to the core's mutation cycle. This layer sets window._watchReapplyHook to its own reapplyDecorations function, creating a tight contract where visual overlays automatically synchronize with document updates.

You can also implement custom listeners for debugging or extension purposes:

// Custom client: listen for patch events
window._watchEs.addEventListener('update', e => {
  const msg = JSON.parse(e.data);
  console.log('Patch received:', msg);
});

Summary

• The Core/Watch component establishes an SSE connection via window._watchEs to receive real-time updates without polling.
• Fine-grained DOM patching handles specific actions (word-patch, word-diff, slide updates) while preserving page state and scroll position.
• The re-apply hook pattern (window._watchReapplyHook) ensures inline editing decorations remain synchronized after every mutation.
• Document-specific handlers in watch-sse-core.js manage Word block markers, Excel row data, and PowerPoint slide containers.
• Full document replacements preserve the SSE connection and UI state through _replaceDocumentBody and strategic script preservation.

Frequently Asked Questions

How does the Core/Watch component maintain connection stability during live previews?

The component stores the EventSource instance on window._watchEs and includes the connection script in every preview page via src/officecli/Client/preview.html. Because the SSE endpoint remains open during DOM mutations and full document replacements, the connection persists across updates without requiring reinitialization.

What happens when a full document refresh is required?

When the backend sends a full action, the Core/Watch component executes _replaceDocumentBody to swap the document content while preserving the SSE script and current scroll position. After replacement, it calls _callReapplyHook() to restore inline editing decorations, ensuring the user experience remains seamless.

How does inline editing work with the re-apply hook?

The overlay layer in watch-overlay.js registers a callback function as window._watchReapplyHook. Whenever the core layer modifies the DOM—whether through patches, row updates, or slide changes—it executes this hook to refresh highlights, selection marks, and editing controls. This architecture keeps the visual editing layer synchronized with the underlying document state.

Can I programmatically trigger scroll actions in the Core/Watch component?

Yes, the backend can send SSE messages with the scroll action and a scrollTo parameter (e.g., data-slide="3"), which the client handles at lines 22-32 in watch-sse-core.js. This moves the viewport to the target element without reloading the page or modifying the document structure, enabling precise navigation during live editing sessions.

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