Slides

A presentation surface built so an agent can fill it: layouts are computed rather than stored as coordinates, and every placeholder is addressed by its role rather than its position.

6 min

Why an agent can drive it

Roles, not coordinates.

A slide’s placeholders have names — title, body, caption — and you fill them by name. The same call works on every layout, so an agent never has to know where a text box sits or how big it is. Layouts are computed from the deck size and theme, which is why changing a deck from 16:9 to 4:3 genuinely rescales the content rather than clipping it.

beehaven call deck-update-slide '{
  "id": "<deckId>", "index": 0,
  "roles": { "title": "Q1 review", "body": "Three things changed." }
}'

One renderer feeds the editor, every export, the gallery thumbnail and the CLI — so what you see, what you export and what an agent perceives cannot drift apart. That is worth stating because it is the failure mode most of this repo’s history is made of.

The verbs

Twenty-six.

Deck

deck-create— A new deck
deck-list · deck-get— Find one, read one
deck-settings— Size and deck-level options
deck-theme · deck-themes— Apply a theme, list what is available
deck-master · deck-layouts— The master, and the layouts it offers
deck-save · deck-render · deck-export— Persist, rasterise, export (.pptx)

Slides

deck-add-slide— Append a slide on a chosen layout
deck-update-slide— Fill it — by role
deck-move-slide— Reorder — requires `to`
deck-duplicate-slide · deck-delete-slide— The other two

Elements

deck-add-element · deck-update-element · deck-delete-element— Text, shapes, lines, tables
deck-add-image · deck-add-media · deck-add-chart— Richer content
deck-align · deck-connect— Arrange, and join with connectors
deck-layout-save · deck-layout-delete— Keep a layout you built

Eleven built-in layouts, including title, section, picture, caption, quote, statement and blank.

Two things that will waste your time

Both are real today.

deck-theme takes an object, not a string — its published schema says theme: string and the handler refuses anything but an object, so following the schema fails every time. Pass a theme object. (deck-create gets it the other way round: it silently drops a theme string and returns success.)

deck-create does not mint a canvas composition. It creates a deck. If you then pass its id as a compositionId to a canvas verb, that call answers composition-not-found — the deck exists and the canvas object does not, because they are different things.

Both are filed. They are here because reading about them costs less than hitting them.

Not a canvas

Two surfaces, two models.

	Slides	Canvas
Made of	Slides holding text, images, shapes, lines and tables	Nodes on an infinite surface
Layout	Computed from layout + theme	Placed, with optional auto layout
Exports to	.pptx, PDF, images	SVG, PNG, PDF
Reach it with	`deck-*`	`canvas-*`

A slide is not a frame and a deck is not a composition. If you want an infinite design surface, that is the canvas.

Do not edit one as a document

A deck is stored as a document row, so document-update can address it — and would replace it with prose while the gallery went on drawing a deck card over the wreckage. The document verbs refuse a deck by type now and name the verb that works.

Sheets →The canvas →The action surface →