> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless editor

`PptxEditor` from `@reductoai/pptx/editor` is the editor without a UI. You send commands; it edits the deck, keeps undo history and returns a laid-out view. It has no DOM, so it runs in Node, in a worker or in a page. The [editor UI](https://docs.reducto.ai/office/pptx/ui/editor.md) runs on it.

```ts theme={null}
import { HMM_PER_PT, PptxEditor } from "@reductoai/pptx/editor";

const editor = await PptxEditor.open(bytes);

await editor.apply({ type: "addSlide" });
await editor.apply({
  type: "addTextBox",
  frame: { x: 72 * HMM_PER_PT, y: 72 * HMM_PER_PT, w: 360 * HMM_PER_PT, h: 48 * HMM_PER_PT },
  text: "Agenda",
});
const view = await editor.apply({ type: "undo" });

console.log(view.slide, view.canUndo, editor.slideCount);
const saved = await editor.toBytes();
```

Frames and click points are in hundredths of a millimetre (`HMM_PER_PT` per point), the unit of the layout IR.

## The view

`apply` returns an `EditorView`; `editor.view` holds the last one.

| Field | Holds |
| - | - |
| `ir` | Every slide as a `LayoutDocument`, one page each |
| `slide` | The current slide index |
| `objects` | The current slide's shapes, back to front |
| `selection` | What is selected: shapes, text with a caret, or table cells |
| `caret`, `selectionRects` | Where to paint the caret and the text selection |
| `prompts`, `markers` | Empty placeholder prompts ("Click to add title") and bullets of empty paragraphs, to paint over the slide |
| `notes`, `comments`, `sections`, `slides` | Speaker notes, comment threads, sections and per-slide state (hidden, layout part) |
| `layouts` | Every slide layout (`part`, `name`, `master`), for New Slide and Layout |
| `canUndo`, `canRedo` | Undo state |
| `table`, `chart` | The table or chart the selection is in |
| `list` | The selected paragraphs' bullet or number (`kind`, `marker`) and whether their level can move |
| `spacing`, `align` | The line spacing, space before and after, and alignment the selected paragraphs share; a field they differ on is absent |
| `verticalAlign` | Where the text sits in the selected shapes or cells (`top`, `middle`, `bottom`); absent when they differ |
| `direction`, `columns` | Text Direction (`horizontal`, `rotate90`, `rotate270`, `stacked`) and text columns (`{ count, spacing }`, spacing in points) the selected shapes share; absent when they differ |
| `themeColors` | The slide's theme colours as `#RRGGBB`, in the order of PowerPoint's Theme Colors row |

## Commands

Every edit is a `PptxCommand`, a plain object with a `type`. The main groups:

| Group | Types |
| - | - |
| Slides | `goToSlide`, `addSlide` (optionally with a `layout`), `setLayout`, `resetSlide`, `duplicateSlide`, `deleteSlide`, `moveSlide`, `hideSlide`, `setNotes`, `headerFooter` (Insert > Header & Footer; `headerFooter()` reads a slide's settings) |
| Sections | `addSection`, `renameSection`, `removeSection`, `moveSection` |
| Selection | `select`, `click`, `doubleClick`, `escape`, `selectAll`, `selectText`, `hideObjects`, `renameObject` (Selection Pane; `selectionPane()` lists the slide's shapes, hidden ones too, front-most first) |
| Shapes | `addShape`, `addLine`, `addFreeform` (Curve, Freeform: Shape and Freeform: Scribble from page points; a closed path takes the shape style, an open one a line; `simplifyStroke` thins a hand-drawn run), `addTextBox`, `addPicture`, `addMedia`, `setFrames`, `nudge`, `deleteObjects`, `group`, `ungroup`, `zOrder`, `alignObjects`, `distributeObjects`, `rotateObjects`, `flipObjects`, `shapeFill`, `shapeGradient` (a Light or Dark Variation in one of `GRADIENT_DIRECTIONS`; `variation: null` is No Gradient), `shapeGradientFill` (Format Shape > Gradient fill: without `edit` the pane's first gradient; `edit` sets the type, the angle, or one stop's colour, position and transparency, adds or removes a stop; `view.shapeStyle.gradient` is the state), `shapePictureFill`, `shapeOutline` (`view.shapeStyle` is the fill, line, weight, dash and arrows the selection shares), `align`, `glueConnector` (a connector end to a site of `connectionSites()`; a moved shape reroutes its glued connectors) |
| Text | `insertText`, `insertRuns`, `deleteBackward`, `deleteForward`, `moveCaret`, `setCaret`, `format` (at a caret: the word around it, else the text typed next; also superscript, subscript, character spacing), `changeCase`, `clearFormatting`, `formatPainter`, `paintFormat` (Format Painter; `view.painter` while it holds a format), `link`, `removeLink` (Insert > Link on text or shapes; `link()` reads what the dialog shows). An edit to the text of a Resize Shape to Fit Text frame (`a:spAutoFit`) sizes the frame to it in the same undo step; `objects[i].textFit` is the size it needs. A Shrink Text on Overflow frame (`a:normAutofit`) stores the scale and line reduction that fit, in PowerPoint's steps |
| Lists | `toggleList`, `setList`, `listLevel`, `listFormat` (Bullets and Numbering: size as % of text, colour, Start at; `view.list.format` is the current value), `listPicture` (an image as the bullet; `view.list.picture`); `tab` at a list paragraph's start changes its level |
| Change Shape | `changeShape` (a `GeometricShapeType` on every selected shape and picture; Crop to Shape on a picture; the old adjustments go) |
| Pictures | `cropPicture` (the share cut off each side; the picture stays where it is and its frame moves, turned and mirrored too), `pictureTransparency` (0 to 1), `pictureRecolor` (Color > Recolor on every selected picture: a tile of `PICTURE_RECOLORS`, or `none`; a tile replaces any earlier recolor and `a:lum`, transparency stays), `changePicture` (new bytes, same frame and crop), `pictureAspect` (Crop > Aspect Ratio from `PICTURE_ASPECTS`: the largest centred frame of that shape), `pictureFit` (`fill` or `fit`: the whole picture, centred, covers the frame or shows inside it); `view.picture` is the one selected picture's crop, transparency and recolor tile |
| Background | `slideBackground` (Format Background: solid, gradient, pattern or picture fill, a Background Styles cell 1 to 12, or `reset`; `all` is Apply to All, which sets the masters and lets every layout and slide follow), `backgroundGraphics` (Hide background graphics); `view.background` is the current page's, `backgroundStyles()` draws the gallery |
| Slide Size | `slideSize` (points; `scale` is `"EnsureFit"` or `"Maximize"` when the slide gets smaller): slides scale evenly and sit centred, layouts and masters stretch; `view.slideSize` |
| Theme | `themeColors`, `themeFonts` (Design > Colors and Fonts: an Office scheme from `THEME_COLOR_SETS` or `THEME_FONT_SETS`, or your own, on the master theme of the current page; other masters keep theirs); `view.theme` |
| Replace Fonts | `replaceFont` (Home > Replace > Replace Fonts: each run, end mark and table cell on slides, layouts, masters and notes that uses `from` takes `to`; a theme face stays in the theme and each run that inherits it gets its own face, as PowerPoint for Windows does); `presentationFonts()` lists the faces the deck's text uses |
| Design | `applyTemplate` puts the first master of a .pptx or .potx (`template` bytes, or `OFFICE_THEME`) on `slides` (all when absent): each slide moves to the layout of its type, then of its name for a custom one, and a layout with no match is copied. A master no slide follows is dropped unless it is marked preserve. `applyDesign` does the same with a master already in the deck. `view.designs` lists each master with its theme's name and slide count; `view.design` is the current slide's |
| Alt Text | `altText` sets the one selected object's description, or marks it decorative (which drops the description, as PowerPoint does); `view.altText` |
| Shadow | `shapeShadow` puts one of `SHADOW_PRESETS` (Outer, Inner, Perspective) on the selected shapes, or `null` for No Shadow; other effects stay. `view.shapeStyle.shadow` is the preset the selection shares |
| Glow, Reflection, Soft Edges | `shapeEffect` with a `kind` (`glow`, `reflection`, `softEdge`) puts one of `EFFECT_PRESETS[kind]` (24 glows, 9 reflections, 6 soft edges) on the selected shapes, or `null` to remove that kind; other effects stay. `view.shapeStyle.glow`, `.reflection` and `.softEdge` are the presets the selection shares |
| Guides | `addGuide` puts a guide at `position` points (the centre when absent), `moveGuide` moves one and keeps it on the slide, `deleteGuide` drops it and `centerGuides` adds PowerPoint's two centre guides to a deck with none. Each is one undo step. `guideColor` sets a guide's `#RRGGBB`. In Slide Master view they edit the master's or layout's own guides; on a slide `view.guides` also lists the layout's and master's, marked `locked`. `view.guides` gives points from the top or left edge. `gridSettings` sets Snap objects to grid and the grid's spacing in points (0.72–144), shown as `view.snapToGrid` and `view.gridSpacing` |
| Symbol | `insertSymbol` types `code` in `font` at the caret as PowerPoint does: a symbol font (`SYMBOL_FONTS`) puts the character at U+F000 + code with the face in `a:sym`; another font's character is itself, set in that font (`latin` and `ea`) when the run's face differs. One undo step; `symbolRun` gives the run without an editor |
| Paragraph | `align`, `paragraphSpacing` (line spacing, space before and after, and the Paragraph dialog's indentation: `leftIndent`, `firstLineIndent`), `verticalAlign` (Align Text on shapes and cells), `textDirection`, `textColumns` (Columns and More Columns: count 1–16, spacing in points), `textBox` (Format Shape > Text Box: autofit `none`, `shrink` or `resize`, the four margins in points, `wrap`; `view.textBox` shows what the selected shapes share) |
| Transitions | `transition` puts an effect from `TRANSITIONS` on `slides` (the current one when absent): a gallery pick takes the effect's first option at its own length, an `option` keeps a duration you set, `none` drops the effect and keeps the advance timing. `transitionTiming` sets `duration` (0–59.99 s), `advanceOnClick` and `advanceAfter` (seconds, or `null`); `applyTransitionToAll` copies the current slide's transition and timing to every slide in one undo step. `view.transition` |
| Animations | `animation` puts an effect from `ANIMATIONS` on the selected shapes: on a shape with no effect it adds one click effect, on an animated shape it replaces all of that shape's effects with one (at the first one's place, keeping its start, delay and sequence); `add: true` (Add Animation) appends one; `none` removes them. A body placeholder builds By Paragraph. `animationOption` sets the direction and keeps the length, `animationBuild` sets `object`, `allAtOnce` or `paragraph`, `animationTiming` sets `start` (`click`, `with`, `after`), `duration` (0.01–59 s) and `delay` (0–59 s), `moveAnimation` moves the effects one place earlier or later. `view.animation`, `view.animations` |
| Clipboard | `copy`, `cut`, `paste`, `duplicate`; `clipPicture()` lays the copied shapes alone for Paste Special > Picture, which the host adds with `addPicture`'s `size` |
| Tables | `addTable`, `selectCells`, `tab`, `moveCaret` across a cell edge, `tableInsert`, `tableDelete`, `mergeCells`, `splitCell`, `cellFill`, `cellBorders`, `tableOptions`, `tableStyle` (an id from `tableStyles()`, or `null` for Clear Table), `cellMargins` (points; `CELL_MARGIN_PRESETS`), `tablePen` (what `cellBorders` draws with; no edit), `resizeTrack`, `distributeTracks`, `trackSize` (exact row height or column width in points) |
| Charts | `addChart`, `chartData`, `chartType`, `chartTitle`, `chartLegend`, `chartLabels`, `chartDesign`, `chartSeries` (Select Data's Legend Entries), `chartEmptyCells` and `chartWorkbook`'s `visibleOnly` (Select Data > Hidden and Empty Cells; `view.chart.cells`), `chartPart`, `chartFormat` |
| Comments | `addComment`, `replyComment`, `editComment`, `deleteComment`, `resolveComment`. `addComment` with `key` and `range` (`{ start, length }`, from `editor.selectedSpan()`) points at those characters of the shape's text, as PowerPoint's `ac:txMk` does; with `cell` too it points at a table cell's characters, and gives the table the `a16:rowId` and `a16:colId` PowerPoint names cells by when it lacks them. A caret or an empty range points at the shape. `deleteComments` with `scope: "slide"` or `"deck"` is Delete All Comments on Slide or in This Presentation, in one undo step; the author list stays, as in PowerPoint. `editor.commentStep(by, active)` gives the thread Review > Previous (`-1`) or Next (`1`) goes to: every thread in the deck in pane order, wrapping; with no active thread, Next takes the first on or after the current slide and Previous the last on or before it |
| View | `setMode` (`"masters"` for Slide Master view), `present` |
| History | `undo`, `redo` |

`isViewCommand(command)` tells a view-only command (selection, navigation) from an edit.

## Read the deck

| Member | Gives |
| - | - |
| `storyText(story, slide?)` | The text of one shape or cell story |
| `notesText(slide?)` | A slide's speaker notes |
| `find(query, { matchCase })` | Every hit in the deck; select one with `selectText` |
| `notesPage(slide?)` | Notes Page: the page size and the slide image, notes and page number frames in points, and the notes font size |
| `outline()` | Outline View: each slide's title and body placeholder paragraphs with level and frame offset; edit a line with `selectText` and typing |
| `selectedText()`, `textFormat()` | The selected text and its format |
| `slideObjects(slide)` | The shapes of any slide |
| `slideShow()` | Slides with notes, transitions and timings, for a show |
| `toBytes()` | The edited deck |

`PptxEditor.open(bytes, { onProgress })` reports parse and layout progress. To share the editor with other writers, see [Collaboration](https://docs.reducto.ai/office/pptx/recipes/collab.md).
