# Slides

The actions of the slide group, with their input fields and their names on every transport.

20 actions: 20 on the command line, 20 as MCP tools, 20 as HTTP endpoints and 20 in the page.

## slide.list

**List slides.** Every slide in deck order with its number, section, title, kind and lint counts.

| Field       | Type   | Required | Description |
| ----------- | ------ | -------- | ----------- |
| `sectionId` | string | no       |             |

* Command line: `turboslide slides`
* MCP tool: `deck_list_slides`
* HTTP: `POST /api/actions/slide.list`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: no.

## slide.get

**Get slide.** The normalized slide, the assets it references and its last render record.

| Field     | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `slideId` | string | yes      |             |

* Command line: `turboslide slide get <slideId>`
* MCP tool: `deck_get_slide`
* HTTP: `POST /api/actions/slide.get`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: no.

## slide.insert

**Insert slide.** Inserts a slide into a section after the named slide, or first.

| Field          | Type                                                     | Required | Description                                                      |
| -------------- | -------------------------------------------------------- | -------- | ---------------------------------------------------------------- |
| `sectionId`    | string                                                   | yes      |                                                                  |
| `after`        | string                                                   | no       |                                                                  |
| `slide`        | object \| object \| object \| object \| object \| object | yes      |                                                                  |
| `baseRevision` | integer                                                  | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide slide insert --section <sectionId> --after <after> < slide.json`
* MCP tool: `deck_insert_slide`
* HTTP: `POST /api/actions/slide.insert`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## slide.remove

**Remove slide.** Removes a slide from the deck and its section.

| Field          | Type    | Required | Description                                                      |
| -------------- | ------- | -------- | ---------------------------------------------------------------- |
| `slideId`      | string  | yes      |                                                                  |
| `baseRevision` | integer | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide slide remove <slideId>`
* MCP tool: `deck_remove_slide`
* HTTP: `POST /api/actions/slide.remove`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## slide.move

**Move slide.** Moves a slide to a section after the named slide, or first.

| Field          | Type    | Required | Description                                                      |
| -------------- | ------- | -------- | ---------------------------------------------------------------- |
| `slideId`      | string  | yes      |                                                                  |
| `sectionId`    | string  | yes      |                                                                  |
| `after`        | string  | no       |                                                                  |
| `baseRevision` | integer | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide slide move <slideId> --to <sectionId> --after <after>`
* MCP tool: `deck_move_slide`
* HTTP: `POST /api/actions/slide.move`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## slide.update

**Patch slide.** Applies a mutation list to one slide and returns the normalized slide with its findings.

| Field          | Type                                                                                                                                                                      | Required | Description                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------- |
| `slideId`      | string                                                                                                                                                                    | yes      |                                                                  |
| `baseRevision` | integer                                                                                                                                                                   | yes      | The revision the caller read; a stale value is rejected with 409 |
| `mutations`    | object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object\[] | yes      |                                                                  |

* Command line: `turboslide slide patch <slideId> --set <pointer>=<value>`
* MCP tool: `deck_update_slide`
* HTTP: `POST /api/actions/slide.update`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## slide.replace

**Replace slide.** Replaces a slide with the given document; what the source drawer’s Apply emits.

| Field          | Type                                                     | Required | Description                                                      |
| -------------- | -------------------------------------------------------- | -------- | ---------------------------------------------------------------- |
| `slideId`      | string                                                   | yes      |                                                                  |
| `baseRevision` | integer                                                  | yes      | The revision the caller read; a stale value is rejected with 409 |
| `slide`        | object \| object \| object \| object \| object \| object | yes      |                                                                  |

* Command line: `turboslide slide put <slideId> < slide.json`
* MCP tool: `deck_replace_slide`
* HTTP: `POST /api/actions/slide.replace`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## slide.setLayout

**Set layout.** Moves a content slide to another layout and refiles its blocks: to freeform the slide converts to the canvas, every block getting the position box it is drawn at (measured); from freeform the boxes are dropped and the blocks fall into the target slots by geometry (docs/freeform.md).

| Field          | Type                                                     | Required | Description                                                      |
| -------------- | -------------------------------------------------------- | -------- | ---------------------------------------------------------------- |
| `slideId`      | string                                                   | yes      |                                                                  |
| `layout`       | object \| object \| object \| object \| object \| object | yes      | The target layout with its options                               |
| `baseRevision` | integer                                                  | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide slide set-layout <slideId> --type <type> --ratio <ratio> --gap <gap> --layout <layout>`
* MCP tool: `deck_set_layout`
* HTTP: `POST /api/actions/slide.setLayout`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## slide.new

**New slide.** Inserts one slide made from a layout with empty placeholders after the named slide (or first in the section), as one slide.insert with template set; a Section header starts a new section that takes the slides after the anchor.

| Field          | Type             | Required | Description                                                                                                                                                                                                                                                    |
| -------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `layout`       | one of 22 values | yes      | One of the layout list                                                                                                                                                                                                                                         |
| `after`        | string           | no       | The slide the new one follows; first in the section when absent                                                                                                                                                                                                |
| `sectionId`    | string           | no       | The section; the anchor's section, or the last section, when absent                                                                                                                                                                                            |
| `id`           | string           | no       | The slide id; \<layout>-\<n> with the first free n when absent. A browser tab mints \<layout>-\<n>-\<four base36 characters of its client id>, so two tabs adding a slide within the same moment never mint one id (docs/archive/rounds/POLISH.md 2.8 item 99) |
| `baseRevision` | integer          | yes      | The revision the caller read; a stale value is rejected with 409                                                                                                                                                                                               |

* Command line: `turboslide slide new --layout <layout> --after <after> --section <sectionId> --id <id>`
* MCP tool: `deck_new_slide`
* HTTP: `POST /api/actions/slide.new`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## slide.duplicate

**Duplicate slide.** Copies the named slides with fresh ids after the last of them, in one write; a copied section header starts a new section.

| Field          | Type      | Required | Description                                                      |
| -------------- | --------- | -------- | ---------------------------------------------------------------- |
| `slideIds`     | string\[] | yes      | One or more slide ids                                            |
| `baseRevision` | integer   | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide slide duplicate <slideIds>`
* MCP tool: `deck_duplicate_slide`
* HTTP: `POST /api/actions/slide.duplicate`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## slide.skip

**Skip slide.** Sets or clears skip on the named slides in one write: a skipped slide is left out of the slideshow, the shared view, the downloads and the print unless asked.

| Field          | Type      | Required | Description                                                      |
| -------------- | --------- | -------- | ---------------------------------------------------------------- |
| `slideIds`     | string\[] | yes      | One or more slide ids                                            |
| `skip`         | boolean   | yes      | true skips the slides, false shows them again                    |
| `baseRevision` | integer   | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide slide skip <slideIds> --off`
* MCP tool: `deck_skip_slide`
* HTTP: `POST /api/actions/slide.skip`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## slide.applyLayout

**Apply layout.** Applies a layout to the named slides in one write, one slide.replace per slide: the title, the body, the lists, the tables and the pictures move into the matching placeholders and the rest is appended; only a Title slide or a Main point drops what does not fit, and the output names the dropped blocks.

| Field          | Type             | Required | Description                                                      |
| -------------- | ---------------- | -------- | ---------------------------------------------------------------- |
| `slideIds`     | string\[]        | yes      | One or more slide ids                                            |
| `layout`       | one of 22 values | yes      | One of the layout list                                           |
| `baseRevision` | integer          | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide slide apply-layout <slideIds> <layout>`
* MCP tool: `deck_apply_layout`
* HTTP: `POST /api/actions/slide.applyLayout`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## slide.import

**Import slides.** Copies slides from another deck after the named slide in one write: the assets they use are copied into this deck, colliding slide ids are renamed, and the output lists the slides and the assets that came over.

| Field          | Type      | Required | Description                                                         |
| -------------- | --------- | -------- | ------------------------------------------------------------------- |
| `sourceDeckId` | string    | yes      | The deck the slides come from                                       |
| `slideIds`     | string\[] | yes      | The slides to copy, in the order they land                          |
| `after`        | string    | no       | The slide the copies follow; first in the section when absent       |
| `sectionId`    | string    | no       | The section; the anchor's section, or the last section, when absent |
| `baseRevision` | integer   | yes      | The revision the caller read; a stale value is rejected with 409    |

* Command line: `turboslide slide import <sourceDeckId> <slideIds> --after <after> --section <sectionId>`
* MCP tool: `deck_import_slides`
* HTTP: `POST /api/actions/slide.import`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## slide.toCanvas

**Arrange by hand.** Converts slides to the canvas, the freeform layout, every object taking the position box it is drawn at (measured on a rendered sheet); a slide already on the freeform layout is left as it is; one write, one browser page for the call.

| Field          | Type      | Required | Description                                                      |
| -------------- | --------- | -------- | ---------------------------------------------------------------- |
| `slideIds`     | string\[] | yes      | One or more slide ids                                            |
| `baseRevision` | integer   | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide slide to-canvas <slideIds>`
* MCP tool: `deck_slide_to_canvas`
* HTTP: `POST /api/actions/slide.toCanvas`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## slide.setBackground

**Change background.** Writes the background colour of slides in one write; null removes it and the theme default applies. A background picture is a picture object at the bottom of the stack.

| Field          | Type           | Required | Description                                                      |
| -------------- | -------------- | -------- | ---------------------------------------------------------------- |
| `slideIds`     | string\[]      | yes      | One or more slide ids                                            |
| `background`   | object \| null | yes      |                                                                  |
| `baseRevision` | integer        | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide slide background <slideIds> --color <color>`
* MCP tool: `deck_set_slide_background`
* HTTP: `POST /api/actions/slide.setBackground`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## text.replaceAll

**Find and replace.** Replaces every occurrence of a string in the visible text of the deck (every Text of every block, the title slide fields, the table cells and the speaker notes) in one write, case insensitive unless asked; the output counts the replacements.

| Field          | Type      | Required | Description                                                      |
| -------------- | --------- | -------- | ---------------------------------------------------------------- |
| `find`         | string    | yes      |                                                                  |
| `replace`      | string    | yes      |                                                                  |
| `matchCase`    | boolean   | no       | Match the case exactly; off by default                           |
| `slideIds`     | string\[] | no       | Restrict to these slides                                         |
| `baseRevision` | integer   | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide text replace <find> <replace> --match-case --slides <slideIds>`
* MCP tool: `deck_replace_text`
* HTTP: `POST /api/actions/text.replaceAll`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## diagram.insert

**Insert diagram.** Inserts a diagram template as one group of shape, text and line objects, centred on the sheet unless a box is given; a slide that is not a canvas yet converts first; the output names the ids.

| Field          | Type                                                                          | Required | Description                                                      |
| -------------- | ----------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------- |
| `slideId`      | string                                                                        | yes      |                                                                  |
| `kind`         | "grid" \| "hierarchy" \| "timeline" \| "process" \| "relationship" \| "cycle" | yes      |                                                                  |
| `count`        | integer                                                                       | yes      |                                                                  |
| `style`        | "outline" \| "plate" \| "ink"                                                 | no       |                                                                  |
| `pos`          | object                                                                        | no       |                                                                  |
| `after`        | string                                                                        | no       |                                                                  |
| `baseRevision` | integer                                                                       | yes      | The revision the caller read; a stale value is rejected with 409 |

* Command line: `turboslide diagram insert <slideId> --kind <kind> --count <count> --style <style> --pos <pos>`
* MCP tool: `deck_insert_diagram`
* HTTP: `POST /api/actions/diagram.insert`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## slide.lease

**Lease slide.** Takes a lease on a slide for the author; another author’s write is rejected with 409 unless forced.

| Field     | Type    | Required | Description                               |
| --------- | ------- | -------- | ----------------------------------------- |
| `slideId` | string  | yes      |                                           |
| `minutes` | integer | no       | Defaults to 10                            |
| `force`   | boolean | no       |                                           |
| `release` | boolean | no       | Give the author’s lease on the slide back |

* Command line: `turboslide lease <slideId> --minutes <minutes> --force --release`
* MCP tool: `deck_lease_slide`
* HTTP: `POST /api/actions/slide.lease`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes.

## slide.setBackgroundPicture

**Background picture.** One write for a covering picture object at the back of each named slide with an optional dither, replacing the covering picture already there unless told not to; the file, url and upload forms run asset.add server side first.

| Field          | Type      | Required | Description                                                            |
| -------------- | --------- | -------- | ---------------------------------------------------------------------- |
| `slideIds`     | string\[] | yes      | One or more slide ids                                                  |
| `assetId`      | string    | no       |                                                                        |
| `file`         | string    | no       | A path on the machine, or a data: URL                                  |
| `url`          | string    | no       | An http(s) URL fetched through safeFetch                               |
| `upload`       | string    | no       | Hosted: the key of a presigned client upload                           |
| `alt`          | string    | no       |                                                                        |
| `dither`       | object    | no       |                                                                        |
| `replace`      | boolean   | no       | Replace the covering picture at the bottom of the stack; on unless set |
| `baseRevision` | integer   | yes      | The revision the caller read; a stale value is rejected with 409       |

* Command line: `turboslide slide background-picture <slideIds> --asset <assetId> --file <file> --url <url> --alt <alt> --dither --no-replace`
* MCP tool: `deck_set_slide_background_picture`
* HTTP: `POST /api/actions/slide.setBackgroundPicture`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.

## slide.setBackgroundMaterial

**Background material.** Captures a shader material at an anchor and places the frozen frame as a covering picture object at the back of each named slide with an optional dither, in one call, or stores the frame the client sends with `frame` without a render; server side.

| Field          | Type      | Required | Description                                                                                                                                                                                         |
| -------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slideIds`     | string\[] | yes      | One or more slide ids                                                                                                                                                                               |
| `materialId`   | string    | yes      |                                                                                                                                                                                                     |
| `preset`       | string    | no       |                                                                                                                                                                                                     |
| `uniforms`     | record    | no       |                                                                                                                                                                                                     |
| `anchor`       | number    | no       | The frame time in ms; the catalog default unless set                                                                                                                                                |
| `dither`       | object    | no       |                                                                                                                                                                                                     |
| `frame`        | object    | no       | The frame the editor drew in its own WebGL at the sheet’s aspect (3200 by 1800); with it no browser launches in the function and the bytes are stored under the key derived id the block frames use |
| `baseRevision` | integer   | yes      | The revision the caller read; a stale value is rejected with 409                                                                                                                                    |

* Command line: `turboslide slide background-material <slideIds> <materialId> --preset <preset> --anchor <anchor> --dither`
* MCP tool: `deck_set_slide_background_material`
* HTTP: `POST /api/actions/slide.setBackgroundMaterial`
* Runs on: command line, MCP, HTTP, page.
* Changes the presentation: yes; send the `baseRevision` you read.