Interaction contract for a pilot

A stable reference to a place in the document, a minimal set of methods, and events, locked in before integration begins.

Semantic goal

For your application to say “what to do” instead of “where to click”, it needs a common addressing unit: a stable reference to a place in the document. DocumentTarget describes exactly that — the element kind, its identifier, and the revision in which that identifier is valid. This contract deliberately has no references to DOM nodes or coordinates: those change on redraw.

export interface DocumentTarget {
  kind: "paragraph" | "run" | "table" | "tableCell" |
        "image" | "comment" | "field" | "header" | "footer" |
        "hostObject";
  nodeId: string; // stable ID within the revision
  revision: number;
  ancestors: Array<{ kind: string; nodeId: string }>;
  capabilities: string[]; // read, editText, insertRow, openProperties...
  hostData?: { type: string; id: string };
}

Minimal set of session methods

A set of methods sufficient for a pilot: read the document’s state, resolve an object from a point, check whether a command is available, run a single command or a batch, save. Anything that changes the document returns confirmation with a new revision — that’s how you know the change was accepted.

interface A4DocumentSession {
  getDocumentSnapshot(options?: { depth: "semantic" }): Promise<Model>;
  getProjection(request: ProjectionRequest): Promise<Projection>;
  hitTest(point: PagePoint): Promise<HitResult>;
  getSelection(): Promise<SelectionSnapshot>;
  getCommandState(target: DocumentTarget): Promise<CommandState>;
  execute(request: ExecuteRequest): Promise<CommandReceipt>;
  executeBatch(request: AtomicBatchRequest): Promise<BatchReceipt>;
  save(request: SaveRequest): Promise<SaveReceipt>;
}

Events

Event	When it arrives	Required fields
`selectionChanged`	The selection or caret position changed	selection, revision, source of the change
`elementActivated`	A click, double-click, or keyboard activation	gesture kind, object, hit point, selection
`contextMenuRequested`	Before showing the context menu	request identifier, object, point, built-in items
`contentChanged`	A command changed the document	new revision, confirmation, which nodes changed
`commandStateChanged`	A command became available or unavailable, its mark changed	object, new states
dirtyChanged, saved, error	Changes, saving, and errors	revision, file path, or error description

How the surface embeds into your window — Embedding Surface.
What arrives in the events — Host API.