Presentations

Witan Presentations is an API-backed .pptx engine for creating, inspecting, editing, and rendering PowerPoint decks. The CLI sends presentation bytes, or a cached presentation revision, to Witan Cloud or your self-hosted Witan API. The API runs sandboxed Office.js-compatible TypeScript or JavaScript in the Witan PPTX runtime and returns structured JSON plus updated presentation bytes when requested.

The compatibility goal is straightforward: decks created or edited by Witan should remain ordinary PowerPoint files, and PowerPoint-authored decks should remain usable through Witan within the supported feature set.

For coding agents, the core workflow is a visual verification loop: inspect or edit a deck with witan pptx exec, render the affected slide with witan pptx render, and use pixel diffs when a visual change needs regression checking.

Architecture

┌──────────────────────────┐
│   witan CLI              │
│                          │
│  • local .pptx path      │
│  • Office.js code        │
│  • optional --save       │
└────────────┬─────────────┘
             │ HTTPS
             ▼
┌──────────────────────────┐
│   Witan API              │
│                          │
│  • auth / rate limits    │
│  • file cache / stateless│
│  • starts pptx runtime   │
└────────────┬─────────────┘
             │ JSON-RPC
             ▼
┌──────────────────────────┐
│   Witan PPTX runtime     │
│                          │
│  • Office.js sandbox     │
│  • PowerPoint model      │
│  • Slide renderer        │
│  • Chart engine          │
└──────────────────────────┘

TypeScript or JavaScript code runs in a headless PowerPoint runtime. The runtime exposes PowerPoint.run, OfficeExtension types, and the Office.js-style PowerPoint object model. The presentation is available through context.presentation.

This split is deliberate:

• Local CLI for ergonomics - pass file paths, code, input JSON, and image files from an agent or shell.
• API-backed execution - Witan Cloud or a self-hosted API handles authentication, file transport, cached revisions, and runtime lifecycle.
• Sandboxed TypeScript/JavaScript - no filesystem access, no network, and no imports. Scripts can only work through the supplied presentation object model and the input global.
• PowerPoint-compatible output - writes are serialized back to standard .pptx files.

The two engines

Unlike Spreadsheets, Presentations does not expose separate JavaScript or Python SDKs today. The public surfaces are the CLI commands, the Office.js-compatible scripting API, and render-based verification.

Office.js plus Witan chart extensions

Witan implements an Office.js-compatible PowerPoint superset for headless presentation automation: presentations, slides, layouts, masters, theme color schemes, shapes, text, images, tables, tags, custom XML, properties, hyperlinks, export, and rendering.

Witan also adds chart APIs that are not present in upstream Microsoft PowerPoint Office.js. Scripts can create and edit chart shapes with slide.shapes.addChart(...), then mutate chart titles, legends, axes, series, data labels, fills, borders, fonts, and modern chart options.

See CLI Scripting for the scripting workflow and pptx API for the implemented object model.

Stateless vs. files-backed operation

Witan chooses its transport mode from the credential context:

• Unauthenticated / Personal - stateless by default. Every command sends the presentation bytes for that request.
• Authenticated / organization-backed - files-backed by default. The CLI uploads presentation revisions and reuses them across commands.
• Forced stateless - set WITAN_STATELESS=1 or pass --stateless to send bytes on every request even when credentials are available.

See CLI Reference for setup and retention behavior.

What Witan does not do

• No PowerPoint application automation. Microsoft Office is not launched or required.
• No arbitrary Office.js host UI. UI/session-only APIs are either omitted or return explicit errors.
• No VBA or add-in execution. The runtime edits the document model; it does not run macros or external add-ins.

Next steps

• Quickstart - create, edit, and render your first deck.
• CLI Scripting - full witan pptx exec workflow.
• Render - slide rendering and pixel diffing.
• Themes and Color Schemes - scoped theme colors on slides, layouts, and masters.
• Charts - Witan chart extension examples and rendered screenshots.
• pptx API - generated Office.js-compatible API reference.