OfficeCLI Watch Mode for Live Preview: Real-Time Document Streaming Explained

OfficeCLI watch mode starts a local Server-Sent Events (SSE) server that pushes live HTML fragments to your browser as you edit, delivering instantaneous previews without reloading the page.

The OfficeCLI watch mode for live preview is a document synchronization engine built into the iOfficeAI/OfficeCLI repository. When you run officecli watch <file>, the tool initiates a three-layer pipeline that renders Office documents (Word, PowerPoint, Excel) into HTML and streams differential updates to a connected browser, keeping the visual preview in lockstep with your edits.

Architecture Overview

The watch system splits responsibilities across three distinct layers to ensure responsiveness and safety.

Core Server Layer (WatchServer.cs)

The entry point resides in src/officecli/Core/Watch/WatchServer.cs. This class initializes a lightweight TCP listener restricted to localhost, loads embedded JavaScript payloads, and manages process lifetime through a unified cancellation token.

internal class WatchServer : IDisposable
{
    // Loads embedded resources from the assembly
    var core = LoadWatchResource("Resources.watch-sse-core.js");
    var overlay = LoadWatchResource("Resources.watch-overlay.js");
    // ... starts SSE listener on localhost
}

SSE Script Layer (watch-sse-core.js)

The first client-side layer, src/officecli/Resources/watch-sse-core.js, establishes the EventSource connection and exposes the rendering hook. It creates window._watchEs and defines window._watchReapplyHook for downstream mutation handling.

// watch-sse-core.js
window._watchEs = es;
if (typeof window._watchReapplyHook === 'function')
    window._watchReapplyHook();

Overlay Script Layer (watch-overlay.js)

The second client-side layer, src/officecli/Resources/watch-overlay.js, registers the actual DOM update logic. It replaces window._watchReapplyHook with its own reapplyDecorations routine, allowing the overlay to receive incremental updates via the named pipe and inject them into the preview without a full page refresh.

// watch-overlay.js
var es = window._watchEs;
window._watchReapplyHook = reapplyDecorations;

How the Live Preview Pipeline Works

The OfficeCLI watch mode operates through a six-stage pipeline that guarantees isolation and real-time synchronization.

1. Start watch – The CLI creates a temporary marker file (officecli-watch-<hash>.port) and launches WatchServer, binding to a local TCP port.

2. Serve SSE – The server transmits the concatenated JavaScript payload with Content-Type: text/event-stream, establishing a persistent connection to the browser.

3. Initial render – watch-sse-core.js generates the initial HTML preview from the document and injects it into the DOM, creating the EventSource instance.

4. Overlay activation – watch-overlay.js attaches to the EventSource and prepares the mutation handling layer, enabling UI decorations like selection highlights.

5. Notify changes – When the document changes, the handler (e.g., WordHandler.HtmlPreview.cs) calls WatchNotifier.NotifyAsync. This writes to a named pipe that WatchServer monitors.

// WatchNotifier.cs
internal static void Notify(string html) {
    client.Connect(100);   // fast-fail if no watch is running
    // ... writes HTML fragment to pipe
}

6. Browser update – The server forwards the message as an SSE event, which the overlay receives and applies to the DOM via the reapply hook, updating the preview instantly.

Security and Isolation Guarantees

Watch-Isolation Principle

The subsystem enforces strict watch-isolation: WatchNotifier pushes rendered HTML snapshots to the running process without reopening the original Office file. This guarantees that the live preview cannot corrupt the source document, as the watch server only manipulates the HTML stream.

Localhost-Only Binding

WatchServer.cs restricts connections to 127.0.0.1 by default. You can whitelist additional hosts via the OFFICECLI_WATCH_ALLOWED_HOSTS environment variable, preventing DNS rebinding attacks while allowing local network flexibility.

Starting and Stopping a Watch Session

Open a terminal and target any Office document:

# Start live preview for a Word document

officecli watch my-document.docx

# The CLI prints a localhost URL (e.g., http://localhost:12345)

# Open this in your browser to see the live preview.

To terminate the session:

# Option 1: Press Ctrl-C in the terminal

# Option 2: Explicitly unwatch the file

officecli unwatch my-document.docx

Both methods trigger the graceful shutdown sequence in WatchServer.Shutdown(), which cancels the watchdog, removes the marker file, and disposes the TCP listener.

Summary

• OfficeCLI watch mode uses an SSE-based architecture to stream HTML fragments from the CLI to your browser.
• Three-layer design: WatchServer.cs manages the socket, watch-sse-core.js handles the base render, and watch-overlay.js applies live updates.
• Strict isolation ensures the watch process never touches the original Office file, only the rendered HTML snapshot.
• Named-pipe notifications via WatchNotifier.NotifyAsync enable sub-second update latency without polling.
• Localhost-only security prevents unauthorized remote access, with optional host whitelisting via environment variables.

Frequently Asked Questions

How do I start a live preview with OfficeCLI?

Run officecli watch <filename> in your terminal. The command launches a local server and prints a http://localhost:<port> URL. Opening this URL in any browser initiates the SSE connection, and the page updates automatically as you edit the document.

What file formats does OfficeCLI watch mode support?

The watch pipeline supports Word documents (docx), PowerPoint presentations (pptx), and Excel workbooks (xlsx). Each format handler—WordHandler.HtmlPreview.cs, PowerPointHandler.HtmlPreview.cs, and ExcelHandler.HtmlPreview.cs—implements a uniform HtmlPreview method that feeds the same SSE stream, ensuring a consistent preview experience across all Office types.

How does OfficeCLI update the browser without reloading the page?

The browser runs two embedded scripts: watch-sse-core.js establishes an EventSource connection to the CLI's server, while watch-overlay.js registers a window._watchReapplyHook function. When you save changes, WatchNotifier sends an HTML fragment through a named pipe; the server pushes this as an SSE event, and the overlay script injects the new fragment into the existing DOM, preserving scroll position and selection state.

Is the OfficeCLI watch server accessible from other machines on my network?

By default, no. WatchServer.cs binds exclusively to localhost (127.0.0.1) to prevent external access. You can permit specific hosts by setting the OFFICECLI_WATCH_ALLOWED_HOSTS environment variable before starting the watch process, though this is recommended only for trusted local networks.

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