How to Use OfficeCLI Layer 2 (L2) DOM Operations for Structured Element Manipulation

OfficeCLI Layer 2 (L2) DOM operations enable structured element manipulation through path-based overlays that merge in-memory with the base document, allowing instant preview and atomic persistence via commands like add, set, remove, and move.

The iOfficeAI/OfficeCLI repository implements a four-layer architecture that treats Word, Excel, and PowerPoint documents as DOM-like trees. Layer 2 (L2) — the Overlay/Decoration layer — provides the structured element manipulation capabilities that let you modify document structure without immediately altering the underlying XML or ZIP payload.

Understanding the L2 Overlay Architecture

OfficeCLI represents each document as a hierarchical tree where nodes are addressable via path strings (e.g., "/slide[2]/shape[3]"). When you execute an L2 command, the CLI creates an overlay object that records the intended mutation in memory.

According to the source code in src/officecli/Resources/watch-overlay.js, these overlay objects hold the intent of changes without touching the original file format. The merge algorithm — executed by the resident layer in src/officecli/ResidentServer.cs — applies overlays in priority order to compute the effective document view that you see in previews and queries.

Key characteristics of the L2 system include:

• Atomic operations: Each CLI command translates to a single overlay entry, allowing you to stack, reorder, or rollback mutations before final write-out.
• In-memory merging: Changes exist only in the overlay layer until you explicitly persist them.
• Validation: The path parser in src/officecli/Handlers/Word/WordHandler.Selector.cs validates selector syntax, element existence, and attribute types before accepting mutations.

Path Syntax for DOM Navigation

L2 operations rely on a path syntax to identify nodes within the document tree. The selector engine supports indexes, attribute filters, and wildcards to pinpoint specific elements.

Valid path patterns include:

• /slide[1] — Selects the first slide.
• /slide[1]/shape[2] — Selects the second shape on the first slide.
• /slide[1]/shape[@name=Title] — Selects a shape by attribute filter.
• /slide[1]/shape[?] — Wildcard for anonymous positioning.

The validation logic in src/officecli/Handlers/Word/WordHandler.Selector.cs performs bracket balance checks and syntax verification before executing any command.

Core L2 DOM Commands

The CLI exposes L2 functionality through a consistent command interface. All mutations create overlay entries that remain in the resident session until explicitly closed.

Querying Elements with get

Before modifying the document, identify the exact path of your target element using the get command with JSON output:

officecli get deck.pptx '/slide[1]/shape[?name=Title]' --json

Example output:

{
  "tag": "shape",
  "path": "/slide[1]/shape[2]",
  "attributes": {
    "name": "Title",
    "text": "Q4 Report"
  }
}

This queries the effective DOM (base layer merged with existing overlays) and returns the canonical path for subsequent operations.

Adding Elements with add

Create new nodes by specifying the parent path and properties. The following example adds a shape to slide 1:

officecli add deck.pptx '/slide[1]' \
  --type shape \
  --prop name="RevenueChart" \
  --prop text="Revenue 2025" \
  --prop x=2cm \
  --prop y=5cm \
  --prop fill=ff5733

This creates an L2 overlay entry that adds the shape node. If you have a live watch session running (officecli watch deck.pptx), the preview updates instantly as the overlay merges with the base document.

Modifying Elements with set

Update existing elements by targeting their path and specifying new properties:

officecli set deck.pptx '/slide[1]/shape[2]' \
  --prop fill=0066ff \
  --prop rotation=15

Each --prop argument generates a separate overlay entry. The final effective state reflects the cumulative application of all overlays, with later entries overriding earlier ones for the same attribute.

Moving and Removing Elements

Relocate elements between containers using the move command:

officecli move deck.pptx '/slide[1]/shape[2]' \
  --to '/slide[3]/shape[?]'

Delete elements entirely with remove:

officecli remove deck.pptx '/slide[2]/shape[5]'

Both operations create overlay entries that mark nodes as moved or removed. The underlying file remains unchanged until the session closes.

The Live Preview Workflow

The L2 architecture enables a preview-first workflow where you can validate changes before committing them to disk.

1. Launch a watch session: officecli watch deck.pptx starts the resident server and opens a browser preview.
2. Apply overlays: Each add, set, move, or remove command creates an overlay that the merge algorithm integrates in real time.
3. Preview rendering: As implemented in src/officecli/Handlers/Word/WordHandler.HtmlPreview.cs, the system merges all overlay layers before rendering the HTML preview, ensuring you see the effective document state.
4. Persist changes: Execute officecli close deck.pptx to flush the merged state (base + all L2 overlays) back to the original file format.

This workflow is particularly powerful for PowerPoint automation, where src/officecli/Handlers/Pptx/PowerPointHandler.StyleList.cs implements a cascade-layer model allowing L2 overlays to sit between the base XML and the final style view.

Summary

• OfficeCLI L2 provides DOM-like manipulation of Office documents through path-based selectors and in-memory overlay objects.
• Four-layer architecture keeps mutations in the overlay layer until explicitly persisted via officecli close.
• Path syntax supports indexes, attribute filters ([@name=Title]), and wildcards ([?]), validated by WordHandler.Selector.cs.
• Real-time preview merges overlays on-the-fly via the watch system in watch-overlay.js and WordHandler.HtmlPreview.cs.
• Atomic operations allow complex, multi-step modifications that can be previewed instantly and committed atomically.

Frequently Asked Questions

What is the difference between L1 and L2 in OfficeCLI?

Layer 1 (L1) represents the raw XML/ZIP payload of the Office document, while Layer 2 (L2) is the Overlay/Decoration layer that holds mutation intents without altering the underlying file. L2 translates high-level DOM operations into overlay entries that merge with L1 to produce the effective view.

How does the overlay merge algorithm handle conflicting changes?

The merge algorithm applies overlays in priority order (lowest to highest) as implemented in the resident layer. When multiple overlays target the same element attribute, the last-written overlay takes precedence, guaranteeing deterministic final state regardless of command order.

Can I rollback L2 overlays before closing the session?

Yes. Because overlays exist only in the resident server's memory until officecli close is called, you can discard the entire overlay batch by simply terminating the session without closing, or by implementing custom rollback logic that removes specific overlay entries from the batch tracked in ResidentServer.cs.

Which Office document types support L2 DOM operations?

OfficeCLI supports L2 DOM operations across Word (DOCX), Excel (XLSX), and PowerPoint (PPTX) files. The path syntax and overlay mechanism are consistent across formats, though specific element types (slides, shapes, cells) vary by handler implementation found in src/officecli/Handlers/.

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