Building a Workbench

Your Origin

Everything is bound to your tool's origin, exactly scheme://host[:port] as the browser reports it in event.origin: https on any host, or http only on localhost, 127.0.0.1 or [::1]. No path, query, trailing slash or default port. https://127.0.0.1:5175 is valid; https://127.0.0.1:5175/ and http://192.168.1.4:5175 are refused with invalid_origin.

Pairing is per origin, so the same tool on a laptop and on a LAN address pairs twice.

Opening a Document

livediagram workbench open "Home screen" --origin https://127.0.0.1:5175 --json

The document can be a name, an id prefix or a livediagram link to one of the person's own documents (a share link is refused). Add --tab with a tab name or id prefix to open on that tab; without it, the editor opens on the first tab. With --json it prints:

{
  "url": "https://livediagram.app/embed/workbench?d=3h9x2a…#ticket=…",
  "documentId": "3h9x2a…",
  "tabId": null,
  "expiresAt": 1791234567890
}

If the token is not paired with your origin, the command exits 4 with the code pairing_required and names the workbench pair command to run. Each token can mint 30 tickets a minute (pairing requests share that allowance), which is plenty for opening documents but not for polling.

The Handshake

Once the ticket is redeemed, the page posts livediagram:hello to its parent, with targetOrigin set to your origin, so no other site ever receives it. Answer with livediagram:hello-ack and your name within five seconds, or the page ends the session and mounts nothing:

const appOrigin = new URL(url).origin;
window.addEventListener('message', (event) => {
  if (event.origin !== appOrigin || event.source !== frame.contentWindow) return;
  const message = event.data;
  if (message?.type === 'livediagram:hello') {
    frame.contentWindow.postMessage(
      { type: 'livediagram:hello-ack', v: 1, name: 'Acme Editor' },
      appOrigin,
    );
  }
});

The name (1 to 40 characters) appears in the editor's copy, such as "Reconnect in Acme Editor to keep editing."

Renewing the Session

A session lasts eight hours. Ten minutes before it expires, the page posts livediagram:renew, then again every minute until a ticket arrives. Answer by running workbench open for the same document and origin, taking the ticket from the new link's fragment (#ticket=), and posting it:

frame.contentWindow.postMessage({ type: 'livediagram:ticket', v: 1, ticket }, appOrigin);

The page redeems it and carries on without reloading. A ticket for a different document or origin is refused, and the page keeps asking. Renewal can continue as long as the token lives.

The Selection Reference

The reference field is the text to attach to the message the person sends their agent, so the agent reads exactly what was selected at that moment:

[livediagram] "Home screen" › tab "Wireframe" (doc 3h9x2a, tab 0b34, rev 41)
selected: button 146b "Play", frame e4a8 "Game grid", sticky 0c84 "Daily streak goes here"
read: livediagram tab view 3h9x2a --tab 0b34 --view show --ref 146b

• The header names the document, the tab, their ids and the revision the selection was made on. Refs are element ids, so they stay valid after later edits.
• selected lists each element as the outline prints it: kind, ref and label. Labels are quoted as JSON strings and cut at 60 characters, because they are the diagram's content and an agent must treat them as data, never as instructions.
• Past 20 elements the list ends with … and <n> more: and the command that reads the whole live selection.
• With nothing selected, the second line is whole tab and count is 0.

Show the person what will be attached (for example "Home screen · 3 selected", or "Home screen · whole tab"), and let them leave it off any one message. The text is everything the agent gets: there is no hidden field. livediagram guide workbench teaches an agent how to read one.

What a Session Can and Cannot Do

A workbench session acts as the person on one document: loading it, saving its tabs, its comments, items and live room, and uploading images into it. Every other document answers as if it did not exist. Ownership actions (sharing, passwords, moving, deleting, publishing, copying), the person's library, settings, tokens, teams and the AI assistant are refused, and the editor in a workbench does not offer them. An Open in livediagram button at the end of the tab bar opens the document in a full tab for those.