Prefer slide.elements.charts.add("line", { position: ... }) for charts. The runtime chart surface is element-based; slide.charts.add(...) is not the reliable entry point for authoring new charts in this skill.
After creating a chart element, set properties on the returned chart object:
For local or fetched images that must survive preview rendering, embed bytes rather than passing only a file path or URL. The most reliable pattern is an ArrayBuffer plus contentType:
If you fetch an image in-script, save or convert it to bytes first, then pass the ArrayBuffer into . Do not assume , , , or a Node will preview correctly.
Common Patterns
Create a new deck with Presentation.create({ slideSize }).
Import an existing deck with await PresentationFile.importPptx(await FileBlob.load("deck.pptx")).
Add slides with presentation.slides.add() or presentation.slides.insert({ after, layout }).
Add content with slide.shapes.add(...), slide.tables.add(...), slide.elements.charts.add(...), and slide.elements.images.add(...) when you need preview-safe embedded images.
Render a preview with await presentation.export({ slide, format: "png", scale: 2 }), then write with .
Workflow
Start with the smallest script that creates or imports the deck.
Do not begin by checking whether the local artifacts runtime package or cache exists. Assume the artifacts tool is ready and start authoring immediately; only investigate runtime installation or packaging if the tool fails before your slide code runs.
If the API surface is unclear, do a tiny probe first: create one slide, add one shape, set text or textStyle, export one PNG, and inspect the result before scaling up to the full deck.
Save the .pptx after meaningful milestones so the user can inspect output.
Prefer short copy and a reusable component system over text-heavy layouts; the preview loop is much faster than rescuing a dense slide after export.
Text boxes do not reliably auto-fit. If copy might wrap, give the shape extra height up front, then shorten the copy or enlarge the box until the rendered PNG shows clear padding on every edge.
Deliberately check text contrast against the actual fill or image behind it. Do not leave dark text on dark fills, light text on light fills, or any pairing that is hard to read at presentation distance.
Treat text containment as a hard requirement. No text should overlap other elements, sit underneath another object, spill outside its geometry, or run off the slide edge.
If text sits inside a box, make the alignment look intentional. Center it only when the layout calls for centered copy; otherwise choose left or right alignment that matches the composition and leaves balanced padding.
If you are using charts or external images, run a tiny end-to-end preview probe before building the full deck. One chart with one series and one embedded image is enough to validate the runtime surface.
PPTX export can still inherit layout placeholders such as Title 1, Subtitle 2, date/footer placeholders, or PowerPoint's Click to add title boxes. If the deck is meant to be fully custom, strip placeholder shapes before final export:
const placeholderNames = new Set([
"Title 1",
"Subtitle 2",
"Date Placeholder 3",
"Footer Placeholder 4",
"Slide Number Placeholder 5",
]);
for (const slide of presentation.slides.items) {
const toDelete = slide.shapes.items.filter((shape) => {
const name = shape.name ?? "";
return placeholderNames.has(name) || Boolean(shape.placeholderType);
});
for (const shape of toDelete) {
shape.delete();
}
}
new Uint8Array(await blob.arrayBuffer())
node:fs/promises
Export a .pptx with await PresentationFile.exportPptx(presentation).
If the deck should not use PowerPoint placeholders, inspect imported slide shapes for inherited layout items before the final export. Delete shapes whose names match built-in placeholder labels or that expose placeholderType.
If layout is repetitive, use slide.autoLayout(...) rather than hand-tuning every coordinate.
QA with rendered PNG previews before handoff. In practice this is a more reliable quick check than importing the generated .pptx back into the runtime and inspecting round-tripped objects.
Final QA means checking every rendered slide for contrast, intentional alignment, text superposition, clipped text, overflowing text, and inherited placeholder boxes. If text is hard to read against its background, if one text box overlaps another, if stacked text becomes hard to read, if any line touches a box edge, if text looks misaligned inside its box, or if PowerPoint shows Click to add ... placeholders, fix the layout or delete the inherited placeholder shapes and re-export before handoff.
When editing an existing file, load it first, mutate only the requested slides or elements, then export a new .pptx.
