Declarative Authoring API

The declarative API is the recommended way for apps and agents to author decks. You pick a semantic layout and supply content. Runstamp owns coordinates and compiles through the same PaperDocument as the renderer and React viewer.

import { writeFile } from "node:fs/promises";
import type { DeclarativeDocument } from "@runstamp/sdk/react";
import { createRunstampRenderer } from "@runstamp/sdk/react/server";

const deck: DeclarativeDocument = {
  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"],
    },
  ],
};

// Invalid input throws DeclarativeValidationError before anything is rendered.
const buffer = await createRunstampRenderer().renderPptx(deck);
await writeFile("launch-readiness.pptx", buffer);

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 take exactly one series. Radar is not exposed by this API, and no paid local feature gate enables it.

import type { DeclarativeDocument } from "@runstamp/sdk/react";
import { renderDeckToPptx } from "@runstamp/sdk/react/server";

const deck: DeclarativeDocument = {
  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 },
            ],
          },
        ],
      },
    },
  ],
};

await renderDeckToPptx(deck); // throws with `issues` if the deck is invalid

Validation issues

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

The published SDK validates inside every render. renderPptx and renderDeckToPptx throw DeclarativeValidationError before rendering anything, and its issues array has the shape above. Schema failures keep exact path segments. Valid input also passes layout-safety preflight.

import { renderDeckToPptx } from "@runstamp/sdk/react/server";

type Issue = { path: Array<string | number>; code: string; fix: string };

const failure = await renderDeckToPptx({
  title: "Broken example",
  slides: [{ layout: "kpi-row", metrics: [{ label: "ARR", value: "$8.4M" }] }],
}).then(
  () => undefined,
  (error: { issues?: Issue[] }) => error,
);

console.log(failure?.issues?.[0]); // { path, code, fix }

Compilation

Rendering compiles the declarative document to a PaperDocument with the same engine as the React viewer. Invalid input throws DeclarativeValidationError, whose issues use the shape above. Return issues to a user or agent so they can fix the deck.

toPresentationSpec(document)

Converts a parsed DeclarativeDocument to the lower-level protocol-v2 PresentationSpec. Most apps don't need it. Use it when an integration already consumes protocol-v2 specs and must 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.