Documentation

This directory contains the maintained project documentation for ts-pptx. Prefer docs here over legacy upstream-era notes in demos or generated artifacts.

Start Here

• Project target: what this project is optimized for.
• Runtime and package support: supported imports, dropped upstream support, and shipped artifacts.
• Development guide: setup, source layout, generated outputs, and contribution rules.
• Testing guide: regression, schema, package, demo, and manual verification.
• Release workflow: scoped-package release preparation, automated npm publishing, and package-surface checks.
• Agent development guide: expectations for Codex and other agent-assisted changes.
• OOXML agent context: project-specific OOXML reference and validation workflow.
• Evidence and fixtures: what counts as evidence before implementing, and when to wait for a genuine PowerPoint fixture instead of guessing the target XML.

Feature Guides

• Tables: the cell model, the styling precedence chain, borders (per-cell default vs. perimeter, dash styles, diagonals), merges, auto-paging, reading/editing an existing table, and what PowerPoint will not keep.
• Grouping objects: addGroup() / groupObjects(), the identity child space, framing, nesting, and cross-references into a group.
• Connectors: addConnector() straight/elbow/curved lines, bend control, shape binding, and the addShape() vs. addConnector() split.
• Image embedded in a shape: clip a picture to a preset or freeform shape and crop it to fill the box.
• OLE embedded objects: addOleObject() embeds a workbook, document, or any payload so it opens in place on double-click.
• 3D models: addModel3d() embeds a .glb that PowerPoint 2019+ renders live, the scale and camera you almost always need to set, and the preview picture everything else shows.
• Animations and transitions: slide/shape animation and transition emit.
• Native backgrounds and gradients: native PPTX gradient fills and required review gates.
• PPTX to script: turn an existing deck into runnable TypeScript, the two output tiers, and the fidelity notes that state what a conversion drops.
• Math and LaTeX: OMML math emit.
• Embedded fonts: font embedding, merge, and fixtures.
• Measured text fit: the export-time shrink/resize pass.
• Diagnostics: routing, silencing, or escalating the library's non-fatal warnings, and the stable code vocabulary behind them.
• Errors: the five error classes, the stable code each carries, and what a consumer may branch on.

Documentation Rules

• Keep docs aligned with the current package target.
• Do not document CJS or IIFE as supported workflows.
• Keep release runtime and declaration artifacts under dist/ treated as generated outputs unless a task explicitly asks to refresh them.
• For OOXML behavior, prefer small repo-specific notes with section references over copied standards text.