Embedding kit: structure, events, menu

There’s no public embedding kit yet

Structural projections of the workbook, and handling clicks, double-clicks, object selection, and context menus inside SumSheet already work, but they stay internal interfaces of the product. Below is a description of what the public embedding kit (Embedding API) should become, not what you can call today.

The contract itself has already shipped as a separate version: the list of events, refusal codes, the editor’s settings, and the object that controls it are all declared and don’t change arbitrarily. What’s missing is the other half — what implements this contract and ships to you as a package. So you can write code against the names and types ahead of time, but you can’t run it yet.

Here are those refusal codes — all ten, from that very package:

Code	When it arrives
transport-unavailable	The runtime didn’t come up, or the startup handshake failed.
transport-crashed	The core died mid-session. This is the end: you’ll have to create the editor again.
document-open-failed	The bytes or the address couldn’t be read, or it isn’t a workbook.
document-format-unsupported	A format outside the declared list, or a blocked load path.
save-failed	Writing failed. The document stays open, with unsaved changes.
host-persistence-failed	Your own save handler refused.
invalid-selection	setSelection got an unknown sheet or an unparseable A1-style range.
no-document	The operation requires an open document, and there isn’t one.
editor-destroyed	Calling the editor after destroy().
contract-error	The core returned a refusal not covered by the rows above.

This is a closed list — unlike the operations contract’s own codes, which have no closed list at all.

There are eight events in the same package, and they’re a closed list too. The pilot page links here for their contents, so here they are:

Event	When it arrives
ready	The editor is created and ready to accept calls. There’s no workbook yet.
opened	The workbook is open: from this moment there’s something to edit and something to save.
dirty	Unsaved changes appeared — a signal for your save button.
change	The workbook’s content changed. Fires on every edit, unlike dirty, which marks the transition.
selection	The selection changed: a different sheet, a different cell, or a different range.
save-requested	The user asked to save. Your side does the saving — the core only reports the request.
closed	The workbook is closed; the editor is still alive.
error	Something failed; the code is from the table above.

The difference between dirty and change is worth noting: the first says something unsaved appeared, the second says the workbook changed yet again. You light up the save button on the first, and recompute your own panels on the second.

The embedding contract also declares fewer formats than the core can handle: five — XLSX, XLSB, XLS, ODS, and CSV. The other eight from the format matrix — XLSM, XLTX, XLTM, FODS, SpreadsheetML 2003, TSV, TXT, and HTML — aren’t part of it, and a workbook in one of those formats gets the document-format-unsupported refusal. The gap is most visible with XLSM: the core reads and plans macros, but the embedded editor won’t accept such a workbook yet.

What is available now: Compute Contract—the contract has 208 operations for reading and changing the workbook, 206 of which are accepted by the core of the latest release. Do not use DOM selectors, internal CustomEvents, or the global __f1… entry points: they are not the contract and change without notice.

Status	Item	What it means
Exists now	The operations contract in the core	Reading structure, cells, and objects, typed change operations.
Exists now	Handling actions in the surface	Hit-testing, clicks and menu invocation, selection, and internal semantic events.
Needs to be formalized	The public embedding kit	Stable methods and events, adding your own menu items, permissions, and versioning.

What API embedding needs

• Read — find out the workbook’s contents, the selection, a cell, an object.
• Events — respond to user actions.
• Commands — safely change the workbook.
• Interface extension — add your own commands and menu items.

Not the document’s DOM, but structural projections and commands

The proposed kit

You can’t call what’s described below today: the names and types are declared, but there’s no package yet that implements them.

The spreadsheet in SumSheet isn’t laid out on the page as an element tree. It’s drawn on a canvas, and only the visible part of the workbook is held in memory — so the cell or object you need may not exist in the markup at all, even while the user sees it. You need to reach the logical structure through a set of calls.

Item	What it gives you	Where the data comes from
WorkbookSession	The workbook and session identifiers, the revision, an unsaved-changes flag, the active sheet, and the available formats.	The core session.
WorkbookInfo	Sheets with stable identifiers, their names, visibility, and which sheet is active.	A projection from the core.
Selection	The sheet, the selected range, the active cell, and the identifiers of the selected objects.	Hit-testing in the surface, plus identifiers from the core.
CellDetails	The stored value, the displayed value, the formula, the type, the format, input validation, a comment, and a link.	The read_cell_details operation.
RangeSnapshot	A bounded range: values, formulas, styles, and related data.	A request to the core with the range’s boundaries stated explicitly.
ObjectInventory	Shapes, charts, images, controls, their anchoring, stacking order, and available actions.	An object inventory from the file.
ContextTarget	What’s under the pointer: a cell, a table, a chart, a shape, a header.	Semantic hit-testing.

The main rule

Never keep live references

What you get is a projection — a snapshot of the state with a stable identifier and a revision number. Don’t keep a markup node or a mutable workbook object on your side and write into it directly: by the next action, both the markup and the state will have already changed. Before every action, the identifier, the revision, the permissions, and whether the operation is available are all checked again.

This is the proposed naming for the public calls — these names don’t exist in the current contract.

const session = await F1.open({
  mount, documentId, bytes, mode: "edit"
});

const workbook = await session.getWorkbookInfo();
const selection = await session.getSelection();
const cell = await session.getCellDetails(selection.activeCell);

How to get sheets, a range, a table, and a graphic object

The proposed kit

The projections below are the shape of the future kit. What the core hands over already today is stated at the end of the section.

Task	Proposed call	What comes back
Get the sheets	session.getWorkbookInfo()	The list of sheets, with identifiers, names, visibility, and order.
Read a cell	session.getCellDetails(...)	The stored and displayed value, the formula, the type, the style, and related data.
Read a range	session.getRangeSnapshot(...)	The values, formulas, and styles of the requested range — without the whole workbook.
Look up a table	session.getTableAt(...)	The table’s identifier, its range, columns, filters, totals, and available actions.
Get the objects	session.getObjects(...)	An object inventory with identifiers, types, anchoring, stacking order, and a mutability flag.
Look up the object under a point	session.hitTest(...)	What’s under the pointer: the object kind and its stable identifier.

Example: find a chart and rename it through a command

const objects = await session.getObjects({ sheetId });
const chart = objects.find(x => x.type === "chart");

if (chart?.capabilities.rename) {
  await session.execute({
    operation: "renameObject",
    objectId: chart.stableId,
    name: "Shipping plan",
    expectedRevision: session.revision
  });
}

What the core’s projection already hands over now

Opening the workbook already returns the active sheet, the list of sheets, the visible area, a cell preview, table details, and an object inventory. For every object, you get a stable identifier, the sheet, the type, the name, anchoring, relationships with other parts, stacking order, visibility, locking, and the list of allowed changes. For an individual cell, there’s the read_cell_details operation.

Limit

There shouldn’t be a “return the whole workbook tree” request. It unfolds the entire workbook into memory — the very thing the sparse model lets you avoid — and along the way exposes parts the reader of this request wasn’t supposed to see. Reading needs to be addressed and bounded.

Clicks, selection, and object actions

The proposed kit

The names and types below are declared by the contract, but you can’t call them today: there’s no package yet that implements them. What’s available now — the Compute Contract.

Event	When it arrives	Main fields
selectionChanged	The selection changed, and it’s confirmed.	the new and previous selection, the source of the change, the revision.
cellActivated	A single click or tap made the cell active.	the cell reference, the range, the modifier keys pressed, the source.
cellDoubleClicked	A double-click on a cell — after determining exactly what was hit.	the cell reference, the edit intent, the modifier keys.
objectSelected	A shape, chart, image, or control is selected.	the stable identifier, the object type, anchoring, available actions.
objectDoubleClicked	A double-click on a graphic object.	the object itself, the default action, the modifier keys.
contextMenuOpening	A right-click, or a long-press on a phone.	the object under the pointer, the selection, the built-in menu items, available actions.
workbookChanged	The core applied the change.	the new revision, which operation, what changed, an unsaved-changes flag.
operationRefused	The core refused — before anything changed.	the refusal code and text, the object, the current revision.

Subscribing to semantic events

const unsubscribe = session.on("cellDoubleClicked", async event => {
  const details = await session.getCellDetails(event.cellRef);
  hostPanel.open({ documentId, cell: details });
});

session.on("objectSelected", event => {
  propertiesPanel.show(event.target);
});

// When closing the integration:
unsubscribe();

The gesture handling sequence

pointer or touch → hit-testing → selection confirmation → semantic event → default action

Why not browser events

The canvas can be recreated between clicks, and two clicks can land on different markup nodes — by browser events, this looks like two separate clicks, not a double-click. So the surface itself determines a double-click on the same object, not you, from browser events.

How to change the menu depending on the selected element

The proposed kit

This section is about the future kit too. Today the editor’s menu can’t be extended with your own items.

You don’t search the markup for an internal menu element and insert a button into it. Instead, you register a menu item provider: before showing the menu, SumSheet determines what’s under the pointer and asks you for additional items.

ContextTarget.kind	Example context data
cell / range	sheetId, address, valueType, formula, validation, comment, hyperlink, protected.
table	tableId, name, range, columnId, totals/filter state, mutation capabilities.
chart	objectId, chartType, source range, anchor, editable capabilities.
shape / image	objectId, anchor, zOrder, groupId, metadata, supported mutations.
rowHeader / columnHeader	track index, hidden state, size, protection.
sheetTab	sheetId, name, visibility, active/grouped state.
canvas	sheetId, pointer coordinates, no semantic object.

Example menu contribution for a table row

session.contextMenu.registerProvider(async context => {
  if (context.target.kind !== "table") return [];

  return [{
    id: "partner.open-shipment-card",
    label: "Open shipment card",
    icon: "external-link",
    enabled: Boolean(context.target.rowKey),
    group: "partner",
    order: 20,
    run: () => host.openCard(context.target.rowKey)
  }];
});

Rules for extending the menu

• An item has its own name with your prefix, a translatable label, an optional icon, a group, its order within the group, and a rule for when it’s enabled or visible.

• The item provider gets a safe snapshot of the context, not the internal markup and not the whole workbook.

• Built-in commands stay SumSheet’s own; you add your own items and, in the agreed spots, replace the ones that are allowed.

• If your item provider takes too long to think, the wait cuts off: the menu must never hang because of your back end.

Commands instead of writing directly into the structure

The proposed kit

This too describes what the kit should become. Today, workbook edits go through contract operations — how the session works.

Every operation that changes the document goes through the operations contract in the core. That’s how behavior stays the same in the browser, in the desktop app, and on the server, and how the change history stays consistent.

Step	What happens
1. Assemble the intent	The operation name, a stable reference to the object or range, the parameters, and the expected revision.
2. Check access	Read-only mode, sheet protection, declared capabilities, the source file’s format, and the session’s rules.
3. Pass it to the core	The same contract — through the browser build, the desktop processor, or the server service.
4. Apply it whole	On success, the revision and the history change; on refusal, the workbook stays untouched — there’s no such thing as half an edit.
5. Hand back the result	A new projection and a workbook-change event — or a refusal event.

Example of an edit with revision checking

const result = await session.execute({
  operation: "setCellValue",
  target: { sheetId, row: 12, col: 4 },
  value: { kind: "string", value: "Delivered" },
  expectedRevision: session.revision
});

if (!result.ok && result.code.endsWith("-stale-revision")) {
  await session.refreshProjection();
}

The forbidden model

// DON'T: this bypasses Rust, the history, and saving.
document.querySelector("[data-cell='E13']").textContent = "Delivered";
session.workbook.sheets[0].cells[12][4].value = "Delivered";

Undo and redo

Editing the workbook creates exactly one entry in the core’s shared history. You don’t need to build your own undo stack on your side: the two histories will drift apart, and undo will start restoring a state the user never saw.