# OfficeCLI Core Rendering Engine: Features for High-Fidelity Document Visualization

> Explore the OfficeCLI Core Rendering Engine's features for high-fidelity document visualization. See Word, Excel, and PowerPoint rendered precisely in HTML or SVG with live updates.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: deep-dive
- Published: 2026-07-14

---

**The OfficeCLI Core Rendering Engine employs a plugin architecture that cleanly separates document-type handling from output generation, enabling high-fidelity visualization of Word, Excel, and PowerPoint files in HTML or SVG with support for live-watch updates and precise hit-testing.**

The OfficeCLI Core Rendering Engine powers high-fidelity document visualization within the iOfficeAI/OfficeCLI repository. It abstracts the complexities of Office document formats through a modular interface-based design, allowing developers to render documents with byte-identical accuracy while supporting extensible output pipelines. The engine dynamically selects appropriate renderers based on capability matching and priority scoring, ensuring optimal document fidelity across different formats.

## Renderer Registry and Dynamic Selection

The `RendererRegistry` class, located in [`src/officecli/Core/Rendering/RendererRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Rendering/RendererRegistry.cs), serves as the central dispatcher for all rendering operations. It maintains a registry of **IRenderer** implementations and resolves the best match for each request at runtime.

### Selection Criteria

The registry evaluates three specific criteria when selecting a renderer:

1. **Availability** – Checks `IRenderer.IsAvailable` to confirm the renderer can execute in the current environment.
2. **Capability Coverage** – Validates `RenderCapabilities.Covers(format, output, mode)` to ensure the renderer supports the specific document format, output kind, and rendering mode requested.
3. **Priority** – Selects the renderer with the highest `RenderCapabilities.Priority` value when multiple candidates qualify.

After registering built-in renderers at startup, the registry fires a **Composing** event. This allows third-party renderers to plug into the pipeline without modifying core source files, enabling custom extensions to override or supplement default behaviors.

## Render Capabilities Model

The `RenderCapabilities` record, defined in [`src/officecli/Core/Rendering/RenderCapabilities.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Rendering/RenderCapabilities.cs), acts as a capability descriptor for each renderer. It declares supported input formats (such as `docx`, `xlsx`, or `pptx`), output kinds (HTML or SVG), and feature flags including watch-mode and hit-test support.

This model enables the registry to perform lightweight capability checks without instantiating renderer objects. By querying capabilities upfront, the engine avoids the overhead of creating renderers that cannot satisfy the current request, improving performance and reducing memory allocations.

## Built-In Basic Renderers

The built-in renderers are implemented in [`src/officecli/Handlers/Rendering/BasicRenderers.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Rendering/BasicRenderers.cs). These adapters serve as thin wrappers around the existing document handlers, ensuring **byte-identical output** to legacy rendering paths while integrating with the new plugin system.

| Renderer | Formats | Outputs | Priority | Watch Support | Key Method |
|----------|---------|---------|----------|---------------|------------|
| `WordBasicRenderer` | `docx` | `Html` | 0 | ✔︎ | `WordHandler.ViewAsHtml` |
| `ExcelBasicRenderer` | `xlsx` | `Html` | 0 | ✔︎ | `ExcelHandler.ViewAsHtml` |
| `PptBasicRenderer` | `pptx` | `Html` & `Svg` | 0 | ✔︎ | `PowerPointHandler.ViewAsHtml` / `ViewAsSvg` |

The `RenderingBootstrap` class ensures these renderers register automatically at application startup. Each delegates to its corresponding handler's `ViewAs` methods—such as `WordHandler.ViewAsHtml` or `PowerPointHandler.ViewAsSvg`—preserving the exact output characteristics of the original implementation while exposing them through the standardized `IRenderer` interface.

## Watch-Mode and Hit-Testing

Renderers can opt-in to **watch mode** by specifying `RenderMode.Watch` in their capabilities. When enabled, the engine generates HTML output containing `data-path` attributes that map DOM nodes directly to their underlying OOXML structure elements.

This mapping enables two advanced features: **live-preview updates** that refresh the visualization when the source document changes, and **hit-testing** through `RenderResult.HitTest`, which translates screen coordinates back to specific document elements. The `RenderResult` class, defined in [`src/officecli/Core/Rendering/RenderResult.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Rendering/RenderResult.cs), encapsulates the rendered output along with hit-testing metadata required for interactive document viewers.

## Extensibility and Third-Party Integration

The engine supports custom renderers through a clean extension model. Third-party implementations require three components:

- **Interface Implementation** – Create a class implementing `IRenderer` from [`src/officecli/Core/Rendering/IRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Rendering/IRenderer.cs).
- **Capability Declaration** – Return a `RenderCapabilities` record describing supported formats, outputs, and priority level.
- **Registration** – Call `RendererRegistry.Register` during the `Composing` event to insert the renderer into the pipeline.

Because the registry references only the `IRenderer` interface, alternative engines—such as native PDF renderers or specialized SVG generators—can replace built-in implementations simply by registering with a higher priority value. This design ensures the core rendering engine remains agnostic to specific document formats while supporting unlimited extensibility.

## Implementation Example

The following pattern demonstrates resolving a renderer and executing a watch-mode render:

```csharp
// Resolve a renderer for a Word doc, HTML output, normal mode
var registry = RendererRegistry.Default;
var renderer = registry.Resolve("docx", RenderOutputKind.Html, RenderMode.Normal);
var result   = renderer!.Render(renderInput, new RenderOptions());

// Use watch-mode to get live-preview data-paths
var watchRenderer = registry.Resolve("pptx", RenderOutputKind.Html, RenderMode.Watch);
var watchResult   = watchRenderer!.Render(pptInput,
    new RenderOptions { Output = RenderOutputKind.Html, Watch = true });

```

## Summary

- The **OfficeCLI Core Rendering Engine** uses a plugin architecture based on `RendererRegistry` to dynamically match document requests with capable renderers.
- **RenderCapabilities** provide lightweight description of renderer features, enabling efficient selection without instantiation overhead.
- Built-in renderers in [`BasicRenderers.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/BasicRenderers.cs) wrap legacy `ViewAs` methods to ensure byte-identical output while supporting new features like watch-mode.
- **Watch-mode** injects `data-path` attributes into HTML output, enabling live updates and precise hit-testing via `RenderResult.HitTest`.
- Third-party renderers integrate cleanly by implementing `IRenderer` and registering during the `Composing` event, with priority-based override support.

## Frequently Asked Questions

### How does the OfficeCLI Core Rendering Engine select which renderer to use?

The engine evaluates three criteria in sequence: availability (`IRenderer.IsAvailable`), capability coverage (`RenderCapabilities.Covers`), and priority value (`RenderCapabilities.Priority`). The renderer with the highest priority that satisfies the format and output requirements wins the selection.

### What is watch-mode rendering and when should I use it?

Watch-mode (`RenderMode.Watch`) generates HTML with `data-path` attributes that map DOM elements back to their OOXML source paths. Use this mode when building interactive viewers that require live-update capabilities or precise hit-testing to identify which document element was clicked at specific screen coordinates.

### Can I replace the built-in HTML renderers with a custom implementation?

Yes. Implement the `IRenderer` interface, define your `RenderCapabilities` with a higher priority than the built-in renderers (which use priority 0), and register your implementation via `RendererRegistry.Register` during the `Composing` event. The registry will automatically select your renderer for matching document types.

### Where are the core rendering interfaces and results defined?

The core abstractions reside in `src/officecli/Core/Rendering/`: [`IRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/IRenderer.cs) defines the interface contract, [`RenderCapabilities.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/RenderCapabilities.cs) describes feature sets, [`RendererRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/RendererRegistry.cs) manages resolution and registration, and [`RenderResult.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/RenderResult.cs) contains the output data and hit-testing functionality.