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

> Explore OfficeCLI watch mode for instant live preview. It streams real-time HTML fragments to your browser as you edit, avoiding page reloads for a seamless experience.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: internals
- Published: 2026-07-10

---

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

```csharp
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.

```javascript
// 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.

```javascript
// 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.HtmlPreview.cs)) calls `WatchNotifier.NotifyAsync`. This writes to a named pipe that `WatchServer` monitors.

```csharp
// 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash

# 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:

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WatchServer.cs) manages the socket, [`watch-sse-core.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-sse-core.js) handles the base render, and [`watch-overlay.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.HtmlPreview.cs), [`PowerPointHandler.HtmlPreview.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.HtmlPreview.cs), and [`ExcelHandler.HtmlPreview.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-sse-core.js) establishes an EventSource connection to the CLI's server, while [`watch-overlay.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.