Declarative authoring

The declarative API is the recommended authoring surface for applications and agents. You choose a semantic layout and provide content; Runstamp owns coordinates and compiles through the same PaperDocument used by the renderer and React viewer.

import {
  PaperEngine,
  compileDeclarativeDocument,
  validate,
} from "@runstamp/pptx";

const deck = {
  title: "Launch readiness",
  slides: [
    {
      layout: "title",
      title: "Launch readiness",
      subtitle: "One declarative document, native PowerPoint output",
    },
    {
      layout: "bullets",
      title: "What is ready",
      bullets: ["Packaging", "Documentation", "Support coverage"],
    },
  ],
};

const result = validate(deck);
if (!result.ok) throw new Error(JSON.stringify(result.issues, null, 2));

const document = compileDeclarativeDocument(deck);
const buffer = await PaperEngine.render(document);

Document shape

DeclarativeDocument has these fields:

Unknown document and slide fields are rejected. This catches misspellings instead of silently dropping content.

Layouts

Every slide may also have an id and up to six speaker-note strings in notes.

Chart data

Chart kinds are bar, line, pie, area, and doughnut. All series must use the same categories in the same order. Pie and doughnut charts accept exactly one series. Radar is not exposed by the free declarative facade; use the appropriate Pro authoring path when that chart type is required.

import { validate } from "@runstamp/pptx";

const result = validate({
  title: "Pipeline",
  slides: [
    {
      layout: "chart",
      title: "Qualified pipeline",
      chart: {
        kind: "bar",
        series: [
          {
            name: "Pipeline",
            dataPoints: [
              { category: "Enterprise", value: 2.8 },
              { category: "Mid-market", value: 1.9 },
            ],
          },
        ],
      },
    },
  ],
});

if (!result.ok) throw new Error(JSON.stringify(result.issues, null, 2));

validate(input)

function validate(input: unknown): ValidationResult;

interface ValidationResult {
  ok: boolean;
  issues: ValidationIssue[];
}

interface ValidationIssue {
  path: Array<string | number>;
  code: string;
  severity: "error" | "warning";
  fix: string;
}

Validation never renders and never throws for invalid input. Schema failures preserve exact path segments; valid schemas also pass through layout-safety preflight. ok is false when any error is present.

import { validate } from "@runstamp/pptx";

const result = validate({
  title: "Broken example",
  slides: [{ layout: "kpi-row", metrics: [{ label: "ARR", value: "$8.4M" }] }],
});

if (result.ok) throw new Error("Expected the one-metric KPI row to fail.");
const [issue] = result.issues;
if (!issue?.path.length || !issue.code || !issue.fix) {
  throw new Error("Expected an actionable validation issue.");
}

compileDeclarativeDocument(input)

Validates and compiles input to a PaperDocument. Invalid input throws DeclarativeValidationError; its issues property uses the same issue shape as validate().

Use validate() when errors should be returned to a user or agent. Use the compiler error as a final fail-closed boundary, not as the primary form-validation flow.

toPresentationSpec(document)

Converts a parsed DeclarativeDocument to the lower-level protocol-v2 PresentationSpec. Most applications do not need this function. Use it when an integration already consumes protocol-v2 specs and needs to inspect the normalized slide mapping before compilation.

Schemas and types

Runtime Zod exports are DeclarativeDocumentSchema, DeclarativeSlideSchema, DeclarativeLayoutSchema, DeclarativeMetricSchema, DeclarativeChartSchema, and DeclarativeChartSeriesSchema.

TypeScript exports are DeclarativeDocument, DeclarativeSlide, DeclarativeLayout, DeclarativeMetric, DeclarativeChart, DeclarativeChartSeries, ValidationIssue, and ValidationResult.