Output Formats

CmdCal produces editable OOXML outputs for both presentations and spreadsheets. PPTX remains the presentation primary, while XLSX is the spreadsheet surface for reporting, exports, templates, validation, and repair workflows. PNG previews are available for review surfaces in the presentation flow.

XLSX

CmdCal XLSX produces standards-compliant Excel workbooks from structured JSON.

Key characteristics:

• Declarative workbook generation: describe sheets, rows, cells, styles, tables, validations, formulas, merges, and print setup in structured JSON.
• Template-aware workflows: inspect existing workbook templates, inject through named ranges, and perform supported row-expansion flows.
• Quality APIs: validate finished workbooks, repair common structural damage conservatively, and revalidate after repair.
• Large-workbook planning: use preflight(...), plan(...), and renderWithMetrics(...) to reason about size, chunking, and output cost before or after render.

Start with the XLSX Quickstart if you want your first workbook fast, jump to Validation & Repair for operational workflows, or use the comparison guides for ExcelJS and SheetJS when you need to position CmdCal against incumbent approaches.

PPTX (Primary)

Every render produces a standards-compliant OOXML .pptx file. The output is a ZIP archive containing XML slide definitions, embedded media, theme files, and relationship manifests.

Key characteristics:

• Editable charts: Charts include embedded Excel data (/ppt/embeddings/). Recipients can double-click a chart in PowerPoint to edit the underlying data, change chart types, or adjust series. The engine uses the OOXML c:chart and cx:chart namespaces with full c:numRef cell references.
• Office compatibility: Output targets PowerPoint 2016+ and is tested against PowerPoint for Windows, PowerPoint for Mac, and Google Slides import.
• Font embedding: When using embeddedFonts in the PaperDocument, font subsets are embedded in the archive so the file renders correctly on machines that lack the original fonts.
• Structural validation: The engine can run structural validation (validationMode: "structural") to verify that all relationship IDs resolve, content types are declared, and slide XML is well-formed.

PNG Previews

PNG slide previews are raster images rendered from the layout tree using @napi-rs/canvas.

Hosted API

The hosted API returns preview URLs in the job record:

{
  "data": {
    "preview_url": "https://paperjsx.com/api/v2/jobs/job_xyz/preview"
  }
}

Self-Hosted

Use renderWithPreviews() on the engine:

import { PaperEngine } from "@paperjsx/pptx-core";

const result = await PaperEngine.renderWithPreviews(doc, {
  width: 1280,
  height: 720,
  scale: 2,
});

// result.pptx -- Buffer (PPTX file)
// result.previews -- Buffer[] (one PNG per slide)
// result.qualityReport -- QualityReport

The PreviewRenderOptions control output dimensions:

Chart Fallback Images

For environments where recipients may not have PowerPoint (or where you need guaranteed visual fidelity), enable chartFallbackImages on the document:

const doc: PaperDocument = {
  type: "Document",
  meta: { title: "Report" },
  chartFallbackImages: true,
  slides: [/* ... */],
};

When enabled, the engine renders each chart as a raster image and embeds it alongside the editable chart data using the OOXML AlternateContent mechanism. PowerPoint displays the editable chart; other viewers fall back to the image.

Output Mode

The outputMode option on render requests controls how aggressively the engine preserves editability vs. visual accuracy. This applies to both the hosted API and the self-hosted engine.

The quality report's documentVerdict field reflects the outcome:

• native_editable -- all slides are fully editable.
• editable_with_constraints -- some slides use anchored positioning but remain editable.
• visual_fallback -- one or more slides were rasterized.
• rejected -- the output violated the requested contract.

Per-Slide Editability

Each slide in the quality report includes an editabilityVerdict:

• editable -- fully native OOXML.
• editable_with_constraints -- editable but with anchored positioning.
• visual_only -- rasterized fallback.

How Charts Stay Editable

The engine generates charts using the OOXML chart namespace with embedded Excel workbooks:

1. Chart data is written to an embedded .xlsx file under /ppt/embeddings/.
2. The chart XML references cells via c:numRef and c:strRef formulas (e.g. Sheet1!$B$2:$B$5).
3. PowerPoint reads the chart XML for display and opens the embedded workbook when the user edits the chart.

This approach works for all standard chart types: bar, column, line, area, pie, doughnut, scatter, bubble, radar, waterfall, funnel, treemap, and sunburst. Extended chart types (waterfall, funnel, treemap, sunburst) use the cx:chart namespace for ChartEx support.

Format Comparison

Format Selection Guidance

• Client deliverables: Use PPTX with editable_preferred. Recipients get a file they can edit in PowerPoint.
• Internal review: Use the hosted API and inspect preview URLs. No file download needed.
• Automated pipelines: Use PPTX with strict_editable to enforce that every render is fully editable. Fail the pipeline if the contract is violated.
• Visual-critical output: Use visual_safe when pixel-perfect appearance matters more than editability (e.g. PDF-like distribution).
• Thumbnails and previews: Use renderWithPreviews() with scale: 2 for high-DPI thumbnail generation.