Building a Workbench

Pairing

A token opens designs only in a workbench its owner has approved. The first time, run:

livedesign workbench pair --origin https://127.0.0.1:5175 --name "Acme Editor"

--name is optional, 1 to 40 characters, and is only a label shown beside the origin. The command prints the approval link on its first line of stdout before it waits (with --json, a line {"status":"pending","pairingUrl":"…","expiresAt":…}), so your tool can read it straight away and show it as one button, "Approve in livedesign". It opens the browser itself only when stdout is a terminal.

The link opens a page headed Allow this workbench? in the person's own signed-in browser, where only the token's owner can choose Allow or Don't allow. The command then exits:

• 0 once paired, printing paired <origin> as <name> (or {"status":"paired","origin":…,"name":…} with --json). An origin already paired exits 0 at once.
• 4 when declined (pairing_declined), when the request expired after ten minutes unanswered (pairing_expired), or when it disappeared, for example because the token was revoked (pairing_gone).

A pairing lasts as long as its token. The person can end it from Settings, under API Tokens, with Unpair.

Opening the Workspace

livedesign workbench open --workspace --folder Minigames --origin https://127.0.0.1:5175 --json

The workspace scope frames the person's Explorer: Home, or the folder --folder names (its id, id prefix or name, as livedesign folder ls prints them). It is a second approval: a token paired only for designs exits 4 naming livedesign workbench pair --origin <origin> --workspace. With --json it prints:

{
  "url": "https://livedesign.app/embed/workbench/explorer/folder/f1…#ticket=…",
  "scope": "workspace",
  "folderId": "f1…",
  "expiresAt": 1791234567890
}

Inside the frame the person browses, opens designs (with a Back) and makes new ones in place; the account, Settings and team administration stay out. The frame moves by itself, so keep listening to livedesign:place.

The Handshake

Once the ticket is redeemed, the page posts livedesign:hello to its parent, with targetOrigin set to your origin, so no other site ever receives it. Answer with livedesign: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 === 'livedesign:hello') {
    frame.contentWindow.postMessage(
      { type: 'livedesign: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 livedesign:renew, then again every minute until a ticket arrives. Answer by running workbench open for the same design and origin, taking the ticket from the new link's fragment (#ticket=), and posting it:

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

The page redeems it and carries on without reloading. A ticket for a different design 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:

[livedesign] "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: livedesign tab view 3h9x2a --tab 0b34 --view show --ref 146b

• The header names the design, 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 design'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. livedesign 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 design: loading it, saving its tabs, its comments and live room, and uploading images into it. Every other design 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 livedesign button at the end of the tab bar opens the design in a full tab for those.