Get started with the OPF toolkit

npm init -y
npm install --save-dev @openpresentation/cli @openpresentation/opf-render @openpresentation/opf-pptx
npm install --save-dev @expo-google-fonts/roboto@0.4.3 @expo-google-fonts/roboto-mono@0.4.2 @expo-google-fonts/caladea@0.4.2 @expo-google-fonts/arimo@0.4.3 @expo-google-fonts/tinos@0.4.2 @expo-google-fonts/cousine@0.4.3 @expo-google-fonts/gelasio@0.4.1 @expo-google-fonts/noto-sans@0.4.2

{
  "name": "First deck",
  "slides": [
    {
      "title": "Make the next action clear",
      "text": "Keep the message in OPF. Export PowerPoint when you need an Office handoff."
    }
  ]
}

npx opf validate deck.opf.json
npx opf convert deck.opf.json deck.pptx

npm install @openpresentation/opf@0.20.3 @openpresentation/opf-render@0.20.2 @openpresentation/opf-pptx@0.20.3 @openpresentation/gallery@^3.0.0
# PNG and PDF export and exact text measurement use the renderer's optional peers; an SVG-only install needs none of them.
npm install @resvg/resvg-js@^2.6.2 sharp@^0.35.5 pdf-lib@^1.17.1 @expo-google-fonts/roboto@0.4.3 @expo-google-fonts/roboto-mono@0.4.2 @expo-google-fonts/caladea@0.4.2 @expo-google-fonts/arimo@0.4.3 @expo-google-fonts/tinos@0.4.2 @expo-google-fonts/cousine@0.4.3 @expo-google-fonts/gelasio@0.4.1 @expo-google-fonts/noto-sans@0.4.2
npm install @openpresentation/opf-editor@0.20.3
npm install --save-dev @types/node

{
  "name": "Quarterly Review",
  "design": {
    "theme": "minimal",
    "fontScheme": "roboto",
    "footer": { "left": { "text": "Internal" }, "right": { "text": "{{slide.number}} / {{deck.slideCount}}" } }
  },
  "slides": [
    { "id": "title", "section": "Start", "title": "Quarterly Review", "subtitle": "Q3 2026" },
    { "id": "agenda", "title": "Agenda", "items": ["Revenue", "Product", "Hiring"] },
    {
      "id": "rev",
      "title": "Revenue",
      "chart": {
        "type": "column",
        "data": { "columns": ["Quarter", "Revenue"], "rows": [["Q1", 12], ["Q2", 18]] }
      }
    }
  ]
}

import { readFile } from "node:fs/promises"
import { assertValid, validate } from "@openpresentation/opf"
import { gallery as defaultCatalog } from "@openpresentation/gallery"
import type { Presentation } from "@openpresentation/opf/types"

const deck: unknown = JSON.parse(await readFile("deck.opf.json", "utf8"))

// Report style: never throws, returns every finding. Core ships no catalog records: register the catalogs your
// documents reference (the first is the host default), or only the records a document embeds resolve.
const catalogs = [defaultCatalog]
const { valid, findings } = validate(deck, { only: ["format", "references"], catalogs })
for (const finding of findings) console.error(finding.severity + " " + finding.path + ": " + finding.message)

// Guard style: throws OPFValidationError, then narrows the type.
assertValid(deck)
const typed: Presentation = deck

// A catalog is records keyed by id, grouped by kind.
const scheme = typeof typed.design?.fontScheme === "string" ? defaultCatalog.fontSchemes?.[typed.design.fontScheme] : undefined
console.log(valid, scheme)

import { readFile } from "node:fs/promises"
import { validate } from "@openpresentation/opf"

const source = await readFile("deck.opf.json", "utf8")

// One checker. Text is read as strict JSON, and its findings carry source ranges (and fixes where one is safe).
const report = validate(source)
console.log(report.valid, report.counts) // { error, warning, info }

// Run only what you need: a rule id, a bare rule name or a category (format, references, policy, accessibility, layout, content).
const accessibility = validate(JSON.parse(source), { only: ["text-contrast", "missing-alt-text"] })
console.log(accessibility.counts)

import { readFile } from "node:fs/promises"
import { paginate, resolveSlideContext } from "@openpresentation/opf"
import { gallery as defaultCatalog } from "@openpresentation/gallery"
import { composeSlide } from "@openpresentation/opf/composition"
import { loadFonts } from "@openpresentation/opf-render/fonts-node"

const deck = JSON.parse(await readFile("deck.opf.json", "utf8"))

const fonts = await loadFonts({ pack: "base" }) // bundled, hash-pinned font files
const catalogs = [defaultCatalog] // core ships no records: the host registers the catalogs a document's references resolve in

// The slide's canvas, layout, theme and font families, resolved the one way every engine resolves them.
const { options } = resolveSlideContext(deck, 0, { fonts, catalogs })
const geometry = composeSlide(deck.slides[0], options)
const { presentation, pages } = paginate(deck, { fonts, catalogs })
console.log(geometry.width, geometry.height, presentation.slides.length, pages.length)

import { readFile, writeFile } from "node:fs/promises"
import { gallery as defaultCatalog } from "@openpresentation/gallery"
import { paginate } from "@openpresentation/opf/pagination"
import { toPdf, toPng, toSvg } from "@openpresentation/opf-render"
import { loadFonts } from "@openpresentation/opf-render/fonts-node"

const deck = JSON.parse(await readFile("deck.opf.json", "utf8"))

const fonts = await loadFonts({ pack: "office", substitutionPolicy: "visual" })
const catalogs = [defaultCatalog]
const { presentation } = paginate(deck, { fonts, catalogs })

const svgs = toSvg(presentation, { fonts, catalogs, trace: true }) // one SVG per slide, data-opf-path on every element
await writeFile("slide-1.svg", svgs[0])
await writeFile("slide-1.png", await toPng(presentation, 1, { fonts, catalogs })) // slides count from 1
await writeFile("deck.pdf", await toPdf(svgs, { fonts })) // a deck or its SVGs; vector, selectable text
console.log(fonts.registry.substitutions) // what replaced what

<script type="module">import "@openpresentation/opf-render/element/define"</script>
<opf-deck src="/deck.opf.json" fonts="/opf-fonts/" thumbnails present></opf-deck>

import { readFile, writeFile } from "node:fs/promises"
import { gallery as defaultCatalog } from "@openpresentation/gallery"
import { paginate } from "@openpresentation/opf/pagination"
import { loadFonts } from "@openpresentation/opf-render/fonts-node"
import { fromPptx, toPptx } from "@openpresentation/opf-pptx"

const deck = JSON.parse(await readFile("deck.opf.json", "utf8"))
const fonts = await loadFonts({ pack: "office", substitutionPolicy: "visual" })
const catalogs = [defaultCatalog]
const { presentation } = paginate(deck, { fonts, catalogs })

const bytes = await toPptx(presentation, { fonts, catalogs }) // the same fonts and catalogs as the preview
await writeFile("deck.pptx", bytes)

const roundTrip = await fromPptx(bytes) // mechanical reimport; retain the original OPF source
console.log(roundTrip.name, (roundTrip.slides as unknown[]).length)

import { readFile, writeFile } from "node:fs/promises"
import { gallery as defaultCatalog } from "@openpresentation/gallery"
import { fromPptx, toPptx } from "@openpresentation/opf-pptx"

// A deck made elsewhere: a mechanical import, plus raw per-shape facts to rebuild semantics yourself.
const { presentation, signals } = await fromPptx(await readFile("incoming.pptx"), { signals: true })
console.log(Object.keys(presentation), Object.keys(signals))

// Fill a template while exporting.
const template = JSON.parse(await readFile("quarterly.opf.json", "utf8"))
const filled = await toPptx(template, { catalogs: [defaultCatalog], variables: { client: "Globex", revenue: 1250000, wins: ["Faster onboarding"] } })
await writeFile("globex.pptx", filled)

import { readFile } from "node:fs/promises"
import { gallery as defaultCatalog } from "@openpresentation/gallery"
import { createEditorSession, saveDocument } from "@openpresentation/opf-editor"
import { switchDimension } from "@openpresentation/opf-editor/switches"

const deck = JSON.parse(await readFile("deck.opf.json", "utf8"))
// The editor imports no catalog data: the host registers the catalogs once, and pickers, the canvas and exports all use them.
const editor = createEditorSession(deck, { rejectInvalid: true, catalogs: [defaultCatalog] })

const change = editor.set("slides.0.title", "Quarterly plan")
console.log(change.patches) // [{ op: "replace", path: "/slides/0/title", value: "Quarterly plan" }]
editor.undo()
editor.redo()

// A gallery dimension is one transaction, so one undo restores the deck.
switchDimension(editor, "font-schemes", "georgia")
editor.undo()

// Saving embeds every record the deck references (core embed), so the file renders the same with no catalog registered.
const { document: saved } = saveDocument(editor)
console.log(Object.keys((saved as { catalogs?: object }).catalogs ?? {}))

import { createEditorSession, createSvgTraceBinding } from "@openpresentation/opf-editor"
import { createCanvasEditor } from "@openpresentation/opf-editor/canvas"
import { toSvg } from "@openpresentation/opf-render/svg"
import { loadFonts } from "@openpresentation/opf-render/fonts-browser"
import { gallery as defaultCatalog } from "@openpresentation/gallery"

// Your own preview: draw one slide with trace on, then bind the drawn elements back to the document.
const editor = createEditorSession(deck, { rejectInvalid: true, catalogs: [defaultCatalog] })
preview.innerHTML = toSvg(editor.presentation, 1, { trace: true, catalogs: editor.catalogs }) // slides count from 1

const binding = createSvgTraceBinding(preview.querySelector("svg")!, editor, {
  onSelect(selection) {
    inspector.open({ path: selection.path, commit: (value: unknown) => binding.commit(selection.element, value) })
  },
})

// Or take the ready-made canvas, with inline text editing and a fonts handle (fonts load before pixels).
const fonts = await loadFonts({ faces, lazyFontsBaseUrl: "/opf-fonts/lazy/", scriptBaseUrl: "/opf-fonts/scripts/" })
const canvas = createCanvasEditor(container, {
  editor, // the session registers the catalogs the canvas draws with
  fonts,
  onCommit: ({ editor }) => save(editor.presentation),
})
await canvas.ready

{
  "datasets": {
    "revenue": {
      "columns": ["Quarter", { "name": "Revenue", "format": "$#,##0.0" }, "Costs"],
      "rows": [["Q1", 12, 8], ["Q2", 18, 11], ["Q3", 24, 15]],
      "source": { "src": "./data/revenue.csv", "retrieved": "2026-10-05" }
    }
  },
  "slides": [
    {
      "title": "Revenue",
      "chart": {
        "type": "line",
        "data": { "dataset": "revenue" },
        "mapping": { "series": ["Revenue"] },
        "legend": "bottom",
        "axisTitles": { "value": "USD m" }
      }
    },
    { "title": "Detail", "table": { "dataset": "revenue", "fields": ["Quarter", "Revenue"] } }
  ]
}

opf ingest revenue.csv --as chart --category Quarter --into deck.opf.json --in-place
opf ingest revenue.csv --as table --dataset revenue --into deck.opf.json --in-place

---
name: Q3 Business Review
language: en-US
---

<!-- slide: id=cover layout=title section=Overview -->
# Q3 Business Review
## Operations and growth

Note: Two minutes on the agenda, then straight into the numbers.

---

# Revenue grew every quarter

```chart column
Quarter,Revenue
Q1,12
Q2,18
```

import { readFile, writeFile } from "node:fs/promises"
import { fromMarkdown, toMarkdown } from "@openpresentation/opf/markdown"

const { presentation, valid, findings } = fromMarkdown(await readFile("deck.md", "utf8"))
if (!valid) {
  for (const finding of findings) {
    console.error(finding.location.line + ":" + finding.location.column + " " + finding.message)
  }
}

// Any valid deck writes back out. What the dialect cannot express goes into opf-slide and opf-block YAML fences.
const { markdown, report } = toMarkdown(presentation)
await writeFile("roundtrip.md", markdown)
console.log(report.lossless)

import { readFile, writeFile } from "node:fs/promises"
import { parse, stringify } from "@openpresentation/opf"
import { gallery as defaultCatalog } from "@openpresentation/gallery"

// One entry point for every text form. The file name decides the form: .opf.md is Markdown, .yaml and .yml are YAML,
// anything else is JSON (the content is never sniffed, and a plain .md file is never a deck).
// parse returns the deck, and throws an OPFValidationError for a syntax, schema or reference error, with every finding
// located (error.report.findings, line and column) in the text that was read. validate(text) returns the full report.
const presentation = parse(await readFile("deck.md", "utf8"), {
  filename: "deck.opf.md",
  catalogs: [defaultCatalog],
})
console.log(presentation.slides.length)

await writeFile("deck.opf.md", stringify(presentation, { filename: "deck.opf.md" }))
await writeFile("deck.out.opf.json", stringify(presentation, { filename: "deck.out.opf.json" }))

{
  "template": true,
  "name": "Quarterly review for {{client}}",
  "variables": {
    "client": { "type": "text", "example": "Acme Corp" },
    "revenue": { "type": "number", "format": "$#,##0", "example": 1250000 },
    "wins": { "type": "list", "example": ["Faster onboarding", "Lower churn"] }
  },
  "slides": [
    { "id": "cover", "title": "Quarterly review: {{client}}" },
    { "id": "wins", "title": "Wins", "bullets": ["Revenue {{revenue}}", "var:wins"] }
  ]
}

import { readFile } from "node:fs/promises"
import { resolveVariables } from "@openpresentation/opf"

const template = JSON.parse(await readFile("quarterly.opf.json", "utf8"))

// Pure and deterministic. A value comes from you or the declaration, never from the library.
const result = resolveVariables(template, { client: "Globex", revenue: 1250000, wins: ["Faster onboarding"] }, { strict: true })
console.log(result)

[
  { "op": "test", "path": "/slides/0/id", "value": "title" },
  { "op": "replace", "path": "/slides/0/title", "value": "Approve the next milestone" },
  { "op": "add", "path": "/slides/-", "value": { "id": "next", "title": "Next steps" } }
]

import { readFile } from "node:fs/promises"
import { diff, merge } from "@openpresentation/opf/diff"
import { applyPatch, applyPatchWithInverse, invertPatch } from "@openpresentation/opf/patch"

const base = JSON.parse(await readFile("deck.opf.json", "utf8"))
const patch = JSON.parse(await readFile("changes.json", "utf8"))

// Apply a patch, validate the result, and keep the patch that undoes it.
const ours = applyPatchWithInverse(base, patch, { validate: true })
console.log(ours.inverse, invertPatch(base, patch))

// Compare two decks: slides match by id, then content, then similarity.
const changes = diff(base, ours.presentation)
console.log(changes.summary, changes.patch)

// Three-way merge. Collisions come back as conflicts, never as a silent choice.
const theirs = applyPatch(base, [{ op: "replace", path: "/slides/1/title", value: "Agenda and goals" }])
const { merged, conflicts, clean } = merge(base, ours.presentation, theirs)
console.log(clean, conflicts.length, merged)

npm install -g @openpresentation/cli @openpresentation/opf-render @openpresentation/opf-pptx @resvg/resvg-js@^2.6.2 sharp@^0.35.5 pdf-lib@^1.17.1 @expo-google-fonts/roboto@0.4.3 @expo-google-fonts/roboto-mono@0.4.2 @expo-google-fonts/caladea@0.4.2 @expo-google-fonts/arimo@0.4.3 @expo-google-fonts/tinos@0.4.2 @expo-google-fonts/cousine@0.4.3 @expo-google-fonts/gelasio@0.4.1 @expo-google-fonts/noto-sans@0.4.2
opf --version

import * as opf from "@openpresentation/opf"

// One import in every runtime; in Node it also has the file API. Files in, files out; the extensions name the formats.
// opf convert does the same from a shell.
await opf.convert("deck.opf.json", "deck.pdf")
await opf.convert("deck.opf.json", "deck.pptx")
await opf.convert("deck.opf.json", "slides/deck.png", { slides: "1-3", scale: 2 }) // slides/deck-1.png, -2, -3

// open reads .opf.md, .yaml, .yml or .json (or imports a .pptx); save writes the form the extension names.
const deck = await opf.open("deck.opf.json")
deck.slides.push({ title: "Q4" })
await opf.save(deck, "deck.opf.md")

// With no output path, convert writes nothing and returns the files: { files: [{ name, type, bytes }], findings }.
const { files } = await opf.convert(deck, { format: "pdf" })

// Import is a conversion, not a lossless round trip: what it cannot keep is in findings.
const { findings } = await opf.convert("deck.pptx", "deck.imported.opf.json")
console.log(files[0].name, deck.slides.length, findings.length)

opf create deck.opf.json --title "Quarterly Review"
opf validate deck.opf.json --fail-on warning
opf validate deck.opf.json --only accessibility --format text
opf validate --list-rules
opf stats deck.opf.json --format text

opf convert deck.md deck.opf.json
opf convert deck.opf.json deck.opf.md
opf fill quarterly.opf.json clients.csv "decks/qbr-{client}.opf.json"
opf fill quarterly.opf.json --examples > preview.opf.json

opf edit deck.opf.json --patch changes.json --in-place --expect-sha256 "$SHA"
opf diff before.opf.json after.opf.json --format patch
opf merge base.opf.json ours.opf.json theirs.opf.json merged.opf.json
opf format decks/*.opf.json --check

opf convert deck.opf.json slides/deck.png --slides 1,3-5 --scale 2
opf convert deck.opf.json deck.pdf --raster --scale 2
opf convert deck.opf.json deck.pptx --charts native
opf convert deck.pptx deck.opf.json --signals signals.json
opf doctor deck.opf.json --format text

opf convert deck.opf.json deck.pdf
opf convert deck.opf.md - --to pdf > deck.pdf
opf convert deck.pptx deck.opf.yaml

npx @openpresentation/cli@latest skills install
npx @openpresentation/cli@latest skills install --agent claude-code