Host API: commands, events, and agents

A contract for the pilot, not the current API

Below is the contract proposed for locking in with you before the pilot. Of the listed methods, only mount and unmount exist in the SumDoc surface today; the other names are up for agreement, not ready-made calls.

What works now: Rust Session Protocol — 41 document session commands, and the Surface interface in the browser — mounting the surface and host events.

Embedding needs a small, stable contract, not access to hundreds of the desktop app’s internal channels.

Minimal Host API for a pilot

Group	Examples	Why you need it
Lifecycle	mount, unmount, open, close	Create a session and close it cleanly.
Save	save, saveAs, checkpoint	Return a confirmed result to your storage.
View	focus, setReadOnly, setLocale, setTheme	Fit the surface into your application’s environment.
State queries	getVersion, getCapabilities, getStatus	Find out the contract version and which features are available.
Commands	Editing, formatting, undo and redo, review actions	Apply only permitted changes.

Events your application receives

• ready — the document is parsed and the surface is ready to accept agreed actions.

• dirty — a change was accepted, and an unsaved revision has appeared.

• saved — the write is complete, and you can register the result as a version on your side.

• error — the operation failed; you get a code and a description of the cause that contains no document content.

• unmounted — the surface was removed from your window; after this, the session no longer responds.

Agents and automation

An agent shouldn’t impersonate a user by clicking. The order is different: open a session, find out the available capabilities, request a bounded slice of the document, find a stable reference to the needed spot, propose a point edit, apply it with the expected revision given, check the result, save, and reopen the file. Every step of this route can be logged, constrained by rules, and repeated — none of that is possible with clicks on the screen.

Office.js and VBA

These are familiar examples of events and automation from Microsoft, but not the way to embed SumDoc. In SumDoc, VBA macros run as separate calls behind a guard, not as a channel for controlling the editor, and full compatibility with Office automation is not promised: it is more reliable to work through typed commands, events, and policy enforcement points.