Integration recipes

This is a proposed API, not the current one

The examples below show how responding to user actions is proposed to work: element events, context menu providers, and sending external commands. This API doesn’t exist in SumDoc’s current contract — you can’t write working code from these examples today.

What is available now: Rust Session Protocol — 41 document session commands, and the Surface interface in the browser — embedding the surface and host events. The shape of the future profile is described in the interaction contract; it is fixed by agreement before integration starts.

Examples: click, double-click, and menu

This is a proposed API

The code in this section shows the shape of the future profile. You can’t call it today — see what’s available now.

How to respond to a click and double-click

editor.interactions.on("elementActivated", async (event) => {
  const { gesture, target } = event;

  if (gesture === "click" && target.kind === "comment") {
    hostSidebar.openComment(target.nodeId);
  }

  if (gesture === "doubleClick" &&
      target.hostData?.type === "shipment") {
    await hostApp.openShipment(target.hostData.id);
  }
});

Context menu for a table cell

editor.contextMenu.registerProvider("transport-suite", async (ctx) => {
  if (ctx.target.kind !== "tableCell") return [];

  return [
    { id: "transport.openCargo", label: "Open cargo card",
      enabled: Boolean(ctx.target.hostData?.id) },
    { id: "transport.bindRoute", label: "Bind to route",
      enabled: !ctx.readOnly },
    { type: "separator" },
    { id: "a4.table.insertRowBelow", label: "Insert row below",
      command: { type: "insert_table_row", position: "below" } }
  ];
});

Running an external command

editor.commands.register("transport.bindRoute", async (ctx) => {
  const route = await hostUi.chooseRoute();
  if (!route) return;

  return ctx.session.execute({
    operationId: crypto.randomUUID(),
    expectedRevision: ctx.revision,
    target: ctx.target,
    command: { type: "replace_target_text", text: route.displayName }
  });
});

Why the menu is declarative

You return the item’s identifier, label, state, and typed command — the editor itself draws the menu and checks permissions. That way every item keeps the same behavior, translation, keyboard accessibility, and a single security check. You don’t need your own markup or your own scripts inside the canvas for this.

Transport-system scenario from event to DOCX

This is still a proposed API

The scenario below shows the shape of the future profile in full — from the click to the finished DOCX. This API doesn’t exist in SumDoc’s current contract: see what’s available today.

Step by step: a right-click on a cargo row

• The user right-clicks. The surface translates the click coordinates into document page coordinates and asks the core what was hit.

• The core answers what’s under the pointer. For example, a table cell: its stable identifier, row and column numbers, enclosing elements, and the revision number in which all this is valid.

• The editor asks your menu item providers, passing them this context — and only this context, not a reference to a markup element.

• Your provider adds its own actions. “Open cargo card” and “Bind to route” appear alongside the permitted built-in items.

• The user picks a route. Your interface returns its identifier; the command to change the document is assembled separately — the choice in your system and the edit in the document stay separate actions.

• The core accepts the command or refuses it. The expected revision and the list of allowed actions prevent an edit from being applied to a stale document or to an object it wasn’t meant for.

• The surface updates. The contentChanged and commandStateChanged events bring the new revision number, and only the affected pages are redrawn, not the whole document.

• Saving and reopening confirm the result. The document is saved as a separate file or published all at once, then read back — this verifies that what landed on disk is exactly what the user saw.

What the passed context looks like

{
  "schema": "a4.interaction-context.v1",
  "gesture": "contextMenu",
  "revision": 42,
  "readOnly": false,
  "target": {
    "kind": "tableCell",
    "nodeId": "body.block[18].row[2].cell[1]",
    "ancestors": [{"kind":"table","nodeId":"body.block[18]"}],
    "capabilities": ["read","editText","insertRow"],
    "hostData": {"type":"shipment","id":"SHP-009173"}
  },
  "hit": {"pageIndex":3,"xMilliPx":412000,"yMilliPx":286000}
}

What arrives on a stale revision

{
  "ok": false,
  "error": {
    "code": "revision_conflict",
    "expectedRevision": 42,
    "actualRevision": 43,
    "retry": "refresh_target_and_command_state"
  }
}

What a refusal looks like in the current contract

The response format above is part of the proposed API. Today the session responds differently: the error field holds a string, not an object with a code.

{"id":"tx-1","ok":false,"cmd":"apply-text-transaction","elapsed_ms":1,
 "error":"stale revision: expected 43, received 42"}

Read this line from the core’s side: expected is the revision the document is currently on, received is the one that came in the request. So here the document has moved on to 43, while the command was built for 42.

The response breakdown is described in Request and response objects.