> ## 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.

# Concepts

`PowerPointPresentation` is an Office.js-like API. It follows the names and shapes of the [Office JavaScript API for Microsoft PowerPoint](https://learn.microsoft.com/en-us/javascript/api/powerpoint), so if you know `PowerPoint.run`, you know most of it.

It is **not** compatible with Office.js. It is not a drop-in replacement, and add-in code does not run on it without changes. There is no `PowerPoint.run`, no request context and no `load`/`sync`. Some members are missing, and some are extensions that Office.js does not have. The differences are below.

## Try it

Edit the script. The slides on the right show the result when you stop typing. Click a shape on a slide to go to the line that made it.

```ts theme={null}
import type { PowerPointPresentation } from "@reductoai/pptx/officejs";

declare const presentation: PowerPointPresentation;

const NAVY = "#1F3864";
const master = presentation.slideMasters.getItemAt(0);

const cover = presentation.slides.add({ layoutId: master.getLayoutByName("Title Slide").id });
const [title, subtitle] = cover.shapes.items;
title!.textFrame.textRange.text = "Quarterly review";
title!.textFrame.textRange.font.color = NAVY;
subtitle!.textFrame.textRange.text = "Revenue by region, Q1 and Q2";

const slide = presentation.slides.add({ layoutId: master.getLayoutByName("Title Only").id });
slide.shapes.getItemAt(0).textFrame.textRange.text = "Revenue";

slide.shapes.addTable(4, 3, {
  left: 40,
  top: 140,
  width: 420,
  values: [
    ["Region", "Q1", "Q2"],
    ["EMEA", "4.2", "4.8"],
    ["APAC", "3.1", "3.6"],
    ["Americas", "5.0", "5.3"],
  ],
});

slide.shapes.addChart({
  type: "ColumnClustered",
  categories: ["EMEA", "APAC", "Americas"],
  series: [
    { name: "Q1", values: [4.2, 3.1, 5.0] },
    { name: "Q2", values: [4.8, 3.6, 5.3] },
  ],
  left: 500,
  top: 140,
  width: 420,
  height: 300,
  legendPosition: "bottom",
});

const note = slide.shapes.addGeometricShape("RoundRectangle", {
  left: 40,
  top: 360,
  width: 420,
  height: 60,
});
note.fill.setSolidColor(NAVY);
note.lineFormat.visible = false;
note.textFrame.textRange.text = "Every region grew in Q2";
note.textFrame.textRange.font.color = "#FFFFFF";
note.textFrame.textRange.paragraphFormat.horizontalAlignment = "Center";
```

## No `run`, `load` or `sync`

Office.js sends a batch of commands to Microsoft PowerPoint and waits. Here the deck is in memory, so every property reads at once and every edit applies at once.

```ts theme={null}
// Office.js in Microsoft PowerPoint
await PowerPoint.run(async (context) => {
  const shapes = context.presentation.slides.getItemAt(0).shapes;
  shapes.load("items/name");
  await context.sync();
  shapes.addTextBox("Draft", { left: 40, top: 40, width: 200, height: 40 });
  await context.sync();
});

// @reductoai/pptx
const shapes = deck.slides.getItemAt(0).shapes;
shapes.addTextBox("Draft", { left: 40, top: 40, width: 200, height: 40 });
```

There is no `load()` and no `sync()`. Remove them when you port add-in code. Values that Office.js wraps in a `ClientResult` (for example `getCount()`) have a `.value` that is ready at once.

## Handles and collections

* A collection (`slides`, `shapes`, `layouts`, `tags`) has `.items`, `.getItem(id)`, `.getItemAt(index)` and `.getCount()`.
* Collections are **live**. `items` is read again on every access, so it reflects the last edit.
* Handles are sealed. Assigning a property that the class does not have throws, so a typo does not fail silently.
* Methods that end in `OrNullObject` (`getTextFrameOrNullObject()`, `getParentSlideOrNullObject()`) return a handle with `isNullObject` instead of throwing.

## Units and indexes

Sizes and positions are in **points** (72 per inch), as in Office.js. A 16:9 deck is 960 × 540 points. Slide, shape, row and column indexes start at 0. `toPng({ pages })` also counts slides from 0.

## Hidden slides

A slide with `slideShowTransition.hidden = true` stays in the deck but is left out of `toPdf()`, `toPng()` and the pipeline. Pass `includeHiddenSlides: true` to paint it.

## Extensions

Some members do not exist in Office.js but exist in the VBA object model of Microsoft PowerPoint. They have the VBA name, and the type docs mark them as extensions. Examples: `presentation.sections` and `Slide.moveToSectionStart`, `presentation.customShows`, `Slide.comments`, `TextRange.insertMath`, `TextFrame.columnCount` and `columnSpacing`, `ParagraphFormat.spaceBefore`, `spaceAfter` and indents, `shapes.addChart`, `presentation.embeddedFonts`. Where Office.js has a member, the facade follows its name and behavior.

## Rendered members

`Slide.getImageAsBase64()` and `Shape.getImageAsBase64()` paint the slide or the shape. They need a renderer:

* In Node, `PowerPointPresentation` from `@reductoai/pptx/node` has one.
* With `@reductoai/pptx/officejs` alone there is none. Set `presentation.imageRenderer` to your own, or render the deck as in [JS API in the browser](https://docs.reducto.ai/office/pptx/js-api/browser.md).

## Save

`toBytes()` writes the deck. It leaves out what nothing uses, as Microsoft PowerPoint does: the media of a deleted picture, and the notes, charts and media of a deleted slide. Unchanged parts are copied as they are.
