presentation-king

name	presentation-king
description	Create and edit presentation decks (deck.json scene graph) through the presentation-king MCP tools. Use when the user asks to make slides, edit a deck, or respond to pinned selections from the presentation-king editor.

presentation-king — agent usage guide

You are collaborating with a human on a slide deck. You draft and revise the deck through MCP tools; the human polishes it by hand in a local editor. Respect their manual work.

The deck model

deck.json is a scene graph: fixed 1280×720 canvas, absolute coordinates, stable ids.

{
  "version": 1,
  "meta": { "title": "…", "designSet": "dark-tech" },   // theme: optional override
  "canvas": { "width": 1280, "height": 720 },
  "slides": [
    {
      "id": "sl-…", "name": "…", "notes": "speaker notes", "layout": "title",
      "background": "token:background",
      "elements": [
        { "id": "el-…", "type": "text", "x": 120, "y": 240, "w": 1040, "h": 140,
          "text": "Hello", "style": { "token": "heading-1", "color": "token:accent" } },
        { "id": "el-…", "type": "image", "x": 0, "y": 0, "w": 400, "h": 300,
          "src": "assets/pic.png", "fit": "cover" },
        { "id": "el-…", "type": "shape", "shape": "rect", "x": 0, "y": 0, "w": 300, "h": 200,
          "fill": "token:surface", "radius": 12 },
        { "id": "el-…", "type": "html-embed", "x": 0, "y": 0, "w": 600, "h": 400,
          "html": "<table>…</table>" }   // escape hatch for tables/charts
      ]
    }
  ]
}

Rules:

• Use design tokens, not raw values: colors as token:<name> (token:accent, token:text-secondary, …), text styles via the style dictionary (display, heading-1..3, body-large, body, caption, label, quote, code). Raw hex is an escape hatch only.
• Ids must be unique and stable — never rename existing ids.
• External image URLs are fine in ops: they are auto-downloaded into assets/ and rewritten to relative paths.
• Tables/charts go in html-embed (theme switching does not restyle their innards).

Workflow

1. get_guidelines — merged global guide + deck guide + the design set's own instructions (layout intents, palette do/don'ts). Read before composing.
2. get_deck — current scene graph + validation issues. Take target ids from here.
3. get_selection — the user's pinned selection (element/slide ids + their note). If a pin exists, work only inside it.
4. get_user_changes — semantic digest of manual edits since your last checkpoint (element ids + change kinds). Never overwrite what the user just polished; ack_user_changes once accounted for.
5. apply_ops — batched, atomic writes (see below).
6. get_screenshot — render a slide to PNG to check your work visually.

apply_ops

Ops target explicit ids; a batch applies atomically and becomes one checkpoint the user can revert in the editor.

• add_slide {slide, index?} / remove_slide {slideId} / move_slide {slideId, index} / update_slide {slideId, patch} (patch: name/notes/layout/background; null removes a key)
• add_element {slideId, element, index?} / remove_element {slideId, elementId} / update_element {slideId, elementId, patch} / reorder_element {slideId, elementId, index} (z-order = array order)
• set_theme {theme} — switch tokens+styles deck-wide (geometry untouched)
• update_meta {patch} — title/theme

Blast radius: if the user pinned a selection, any op outside the pin makes the whole batch fail with an error and no change. Deck-level ops (add_slide, set_theme, update_meta) are always outside a pin. Don't fight it — do what was asked within the pin, or ask the user to unpin.

Waiting mode (wait_for_prompt)

When asked to "open the editor and wait", or to iterate live with the user:

1. Ensure the editor is open (npx presentation-king serve <deck> — get_deck_info gives the URL).
2. Call wait_for_prompt. It blocks until the user submits a prompt from the editor's prompt bar, then returns {status:"prompt", text, pin} — the text plus whatever selection was pinned at submit time.
3. On {status:"no_prompt"} (timeout, default 55 s) simply call it again — that's the intended keep-alive pattern for long waits.
4. Act on the prompt (respecting the pin), then loop back to wait_for_prompt.

Layout guidance

Each design set bundles layout templates (title, section, content, two-column, image-caption, full-bleed-data, quote) with slot geometry. Set slide.layout and place elements roughly on those slots; get_guidelines explains when to use which. Keep ≥80px margins except full-bleed layouts, one accent emphasis per slide, and don't hand-pick font sizes when a style token fits.

What not to do

• Don't edit deck.json directly while a deck server may be running — MCP ops are the primary path. (Direct file edits are only detected/quarantined, not merged.)
• Don't revert or overwrite the user's manual changes; read the digest first.
• Don't use raw hex/font sizes when tokens exist.
• Don't put text inside html-embed that belongs in normal text elements.