pptx-ts 3.7.0 → 4.0.0

package/README.md

@@ -1,87 +1,37 @@
 # ts-pptx
 
-> **`pptx-ts` is an alias.** It is the same package as
-> [`@shbernal/ts-pptx`](https://www.npmjs.com/package/@shbernal/ts-pptx), published from the
-> same commit at the same version with the same contents. Install one or the other,
-> never both: two copies of this library in one dependency tree are two module
-> registries, and state such as the diagnostic handler is per-copy. The scoped name is
-> canonical, and the issue tracker, the changelog and every example below use it.
-
-[![npm](https://img.shields.io/npm/v/%40shbernal%2Fts-pptx)](https://www.npmjs.com/package/@shbernal/ts-pptx)
-[![weekly downloads](https://img.shields.io/npm/dw/%40shbernal%2Fts-pptx.svg?label=npm%20downloads&logo=npm)](https://www.npmjs.com/package/@shbernal/ts-pptx)
-[![total downloads](https://img.shields.io/npm/dt/%40shbernal%2Fts-pptx.svg?label=npm%20total%20downloads&logo=npm)](https://www.npmjs.com/package/@shbernal/ts-pptx)
+[![npm](https://img.shields.io/npm/v/pptx-ts)](https://www.npmjs.com/package/pptx-ts)
+[![weekly downloads](https://img.shields.io/npm/dw/pptx-ts.svg?label=npm%20downloads&logo=npm)](https://www.npmjs.com/package/pptx-ts)
+[![total downloads](https://img.shields.io/npm/dt/pptx-ts.svg?label=npm%20total%20downloads&logo=npm)](https://www.npmjs.com/package/pptx-ts)
 [![CI](https://github.com/shbernal/ts-pptx/actions/workflows/ci.yml/badge.svg)](https://github.com/shbernal/ts-pptx/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-ts-pptx generates PowerPoint `.pptx` files from TypeScript and modern
-JavaScript. This project targets ESM package consumers, typed application code,
-reproducible package verification, and agent-assisted OOXML development.
+**Write a program, get a PowerPoint file.**
 
-> **Lineage.** ts-pptx descends from [gitbrent/PptxGenJS](https://github.com/gitbrent/PptxGenJS)
-> (MIT), detached at its v6.0.0 (June 2025) and developed independently since. It
-> does not track, merge from, or mirror the original project, and pursues its own
-> Node-first direction (see _Project Target_). The original work remains under its
-> MIT license: see _License_ below.
+A `.pptx` is a zip full of XML. ts-pptx writes that zip for you, so you describe
+slides in TypeScript and a `.pptx` comes out the other end. PowerPoint never runs, no
+Office licence is involved, and nothing has to be installed on the machine doing the
+writing. The file opens cleanly in desktop PowerPoint, and Keynote, LibreOffice Impress
+and Google Slides import it on a best-effort basis.
 
-## Project Target
-
-- Generate standards-based PowerPoint `.pptx` packages without requiring
-  PowerPoint at runtime.
-- Support TypeScript-first workflows with checked declarations and modern
-  bundler resolution.
-- Ship a small, explicit ESM package boundary for Node.js, Vite, React,
-  Angular, Electron, and similar modern toolchains.
-- Keep OOXML changes grounded in fixtures, schema validation, and PowerPoint
-  compatibility evidence.
-- Make the repository practical for human and agent-driven maintenance.
+Reach for it when a deck has to be built from data that changes: a monthly report,
+one deck per customer, a hundred decks per night, or a download button on a page that
+hands the user a deck built from what they are looking at.
 
 ## Install
 
 ```bash
-pnpm add @shbernal/ts-pptx
-```
-
-```bash
-npm install @shbernal/ts-pptx
-```
-
-```bash
-yarn add @shbernal/ts-pptx
-```
-
-The unscoped name [`pptx-ts`](https://www.npmjs.com/package/pptx-ts) is an alias
-for the same package: same contents, same version, published from the same
-commit by the same workflow. Take it if a scoped name is awkward somewhere in
-your toolchain. Install one or the other and never both, because two copies of
-this library in one dependency tree are two module registries and state such as
-the diagnostic handler is per-copy. The scoped name is canonical: the issue
-tracker, the changelog and every example in these docs use it.
-
-### Installing an unreleased commit
-
-Any commit is installable directly from GitHub, without waiting for a release:
-
-```bash
-npm install github:shbernal/ts-pptx#<commit-sha>
+pnpm add pptx-ts
 ```
 
-`master` (`github:shbernal/ts-pptx`) works too, but pin the sha: a branch spec
-re-resolves to whatever is at the head of it when the lockfile is next written.
-
-`dist/` is not committed, so this builds the package on install: your package
-manager clones the repo, installs this package's `devDependencies`, and runs its
-`prepare` script. That makes the install slow (a couple of minutes) and heavier
-than a registry install, and it needs a working Node toolchain. It is meant for
-trying a fix before it ships, not for production dependencies.
-
-Note that `pres.version` reports the version in `package.json` at that commit, so
-several different commits report the same number. The sha in your `package.json`
-is what identifies the build.
+`@shbernal/ts-pptx` is the same package under its first name, so install one or the other.
+[Installation](docs/getting-started/installation.md) covers npm, CommonJS and the optional
+math dependencies.
 
-## Quick Start
+## Quick start
 
 ```ts
-import TsPptx from "@shbernal/ts-pptx"
+import TsPptx from "pptx-ts"
 
 const pptx = new TsPptx()
 const slide = pptx.addSlide()
@@ -98,218 +48,115 @@ slide.addText("Hello from ts-pptx", {
 await pptx.writeFile({ fileName: "example.pptx" })
 ```
 
-## What It Can Generate
-
-- Slides, layouts, masters, sections, notes, and metadata.
-- Text, tables, shapes, images, SVGs, charts, and media.
-- Browser-downloadable, streamed, buffered, Blob, base64, or file outputs,
-  depending on the runtime.
-- OOXML that is intended to open cleanly in Microsoft PowerPoint and other
-  `.pptx` consumers such as Keynote, LibreOffice Impress, and Google Slides
-  import.
-
-## Scope And Contributions
-
-This project is **Node-first**: it generates and is tested without a browser or any
-office application. Two areas are out of *active* maintenance scope, not because
-they lack merit, but because there is no in-house use case driving them, so the
-maintainer generally will not pick up bugs or feature requests there:
-
-- **Live-DOM / browser-layout features**, anything whose answer comes from a
-  *rendered* page: real `offsetWidth` after layout, the resolved cascade, fonts as
-  the browser actually chose them. (Converting an HTML `<table>` is *not* in this
-  category: see [HTML tables → slides](#html-tables--slides) below. Only real
-  measurement needs a browser.)
-- **Third-party office-suite interop quirks** that appear only after a file is
-  round-tripped through another application (for example, copy/paste inside WPS
-  Office, then opening in PowerPoint) when the generated package is itself valid
-  OOXML. The supported bar is that output opens cleanly in Microsoft PowerPoint.
-
-**Contributions in these areas are welcome**: issues and pull requests are
-encouraged even though the maintainer is not actively developing them. See
-[`docs/project-target.md`](docs/project-target.md) for the full scope statement
-and suggested testing approaches.
-
-## Hit A Bug? There Is A Skill For That
-
-Most code that uses this library is written by an agent, and an agent that hits a
-library defect will usually route around it silently, so the defect is never
-reported and never fixed. `ts-pptx-upstream` is a skill that turns that moment into
-a filed issue with a minimal reproduction, which is what becomes a permanent
-regression test here. It ships inside the package, so it is already on disk:
-
-```bash
-# Name the skill and the runtimes, and take the defaults: this is the form that
-# completes unattended, which is how an agent will be running it.
-npx skills add ./node_modules/@shbernal/ts-pptx -s '*' -a claude-code -a codex -a universal -y
-
-npx skills add shbernal/ts-pptx   # same flags, straight from the repo instead of node_modules
-```
-
-Drop the flags for an interactive prompt if you are at a terminal yourself. Do not reach
-for `--all` to avoid the prompt: it installs into every runtime the CLI knows about,
-around seventy of them, and leaves an `agent/` directory at your repository root for
-runtimes nobody there uses. Name the ones you have.
-
-Two things about living with the installed copy. It is a copy, so **a version bump does
-not update it**: re-run the command above, or `npx skills update ts-pptx-upstream`, in
-the same commit as the bump. And if you track it, track `skills-lock.json` and ignore the
-copy: `skills experimental_install` restores the file from that lock but creates none of
-the runtime links, so it is a record, not a restore command.
-
-It covers triage (is this ours, your deck's, or out of scope?), reducing a failure to
-a script that builds its own deck, and (because presentations carry client names and
-unreleased numbers) never uploading one to a public tracker. Once the reproduction
-stands on its own it files without interrupting you, and tells you the issue number
-afterwards. It also covers the far end of the cycle, which is the half that usually
-rots: when a release lands, finding every workaround it retires and deleting them.
-
-You do not need it to report something: <https://github.com/shbernal/ts-pptx/issues>
-is open, and errors the library knows are its own fault print that link themselves.
-See [errors](docs/errors.md#which-failures-are-worth-reporting) for which failures are
-worth a report.
-
-## Runtime And Package Support
-
-The package is ESM-only.
-
-Supported package surface:
-
-- `import TsPptx, { ShapeType } from "@shbernal/ts-pptx"` (enums, shared types, and
-  layout helpers ship from the main entry)
-- `import { inspectPptx } from "@shbernal/ts-pptx/inspect"`
-- `import { measureText } from "@shbernal/ts-pptx/measure"`
-- `import { Presentation } from "@shbernal/ts-pptx/read"`
-- `import { latexToOmml } from "@shbernal/ts-pptx/math"`
-- `import { tableToSlides } from "@shbernal/ts-pptx/html"`
-- `import TsPptx from "@shbernal/ts-pptx/node"`
-- `import TsPptx from "@shbernal/ts-pptx/browser"`:
-  the bare specifier resolves to one of these two by export condition, so Node
-  and bundled browser apps get the right build without naming it. A runtime that
-  sets neither (Deno, Bun, edge workers) gets a runtime-agnostic build that
-  authors and exports bytes normally but has no `writeFile` destination; see
-  [Runtime And Package Support](docs/runtime-and-package-support.md#which-build-the-bare-import-gives-you).
-- generated runtime and declaration artifacts under `dist/`
-- Node.js `>=24`
-- modern bundlers and module-aware app frameworks
-
-Deliberately not supported:
-
-- No CommonJS: no `require("@shbernal/ts-pptx")`, no CJS export condition, and no
-  `.cjs` artifact. Modern Node.js may provide `require()` interop for ESM, but it
-  is not a maintained API.
-- No IIFE/global browser bundle: no classic-script global, no `dist/*.bundle.js`,
-  and no `dist/*.min.js`.
-
-Use the package exports rather than direct `dist/` artifact paths.
-
-See [runtime and package support](docs/runtime-and-package-support.md) for the
-complete support contract.
-
-## HTML Tables → Slides
-
-`@shbernal/ts-pptx/html` reproduces an existing HTML `<table>` as a PowerPoint
-table, auto-paging across as many slides as its rows need. It works in the
-browser and under Node with any DOM implementation, from one artifact.
-
-```ts
-import { TsPptx } from '@shbernal/ts-pptx'
-import { tableToSlides } from '@shbernal/ts-pptx/html'
-import { Window } from 'happy-dom'
-
-const win = new Window()
-win.document.body.innerHTML = '<table id="report">…</table>'
-
-const pptx = new TsPptx()
-tableToSlides(pptx, win.document.getElementById('report'))
-await pptx.writeFile({ fileName: 'report.pptx' })
-```
-
-Pass the element itself and no global DOM is consulted at all. To pass a string
-id instead, say which document it belongs to:
-
-```ts
-tableToSlides(pptx, 'report', { document: win.document })
-```
-
-In a browser, `options.document` defaults to the global `document`, so
-`tableToSlides(pptx, 'report')` is enough. The equivalent method form,
-`pptx.tableToSlides('report', options)`, remains on the browser build and
-delegates to the same implementation.
-
-**Column widths need a layout engine.** In a browser the columns are sized from
-each cell's rendered `offsetWidth`, reproducing the table's real proportions.
-Nothing outside a browser lays a table out, so `offsetWidth` is `0` there and
-the conversion falls back in two steps: it uses the computed CSS `width`s when the
-stylesheet states them for every column in one unit (all `px` or all `%`), and
-an equal split when it does not.
-
-The first step is a *fallback*, not a graceful loss of precision: `offsetWidth` is
-the border box and computed `width` the content box, so padding alone can put the
-two bases in different proportions. The same table can therefore come out with
-different column widths in a browser and outside one.
-
-To pin widths regardless of runtime, annotate the `<thead>` header cells, which
-win outright on every path:
-
-```html
-<thead>
-  <tr>
-    <th data-pptx-width="2.5">Name</th>
-    <th data-pptx-min-width="1">Qty</th>
-  </tr>
-</thead>
-```
-
-Everything else behaves the same wherever it runs: cell text (with `<br>` kept
-as a line break), `colspan`/`rowspan`, computed colors, weight, alignment,
-padding and borders, and auto-paging.
+That is the whole shape of it. Make a presentation, add a slide, put things on the
+slide, write the file. Positions are in inches by default, so `x: 1, y: 1` is an inch
+in from the top-left corner of a 10 by 5.625 inch slide.
+[Your first deck](docs/getting-started/first-deck.md) builds a bigger one from data, with a
+table, a chart and speaker notes.
+
+## What you can put on a slide
+
+Text and rich paragraphs. Tables, including ones that spill onto as many slides as
+they need. Shapes and connectors between them. Pictures, SVGs, video and audio.
+Charts, with a real embedded workbook behind them, so double-clicking a chart in
+PowerPoint opens its data the way it does for a chart a human made. Speaker notes,
+sections, slide masters and layouts, gradients, an image clipped to a shape, a
+spreadsheet embedded as an object, a 3D model, and LaTeX maths.
+
+Two features worth knowing about by name:
+
+- **[An HTML table becomes slides](docs/html-tables.md).** Point `tableToSlides` at a
+  `<table>` you already have and it comes out as a PowerPoint table, paged across
+  slides. Works in a browser and under Node.
+- **[Text that has to fit](docs/text-fit.md).** ts-pptx can measure the text
+  against the real font and shrink or grow the box before it writes the file, instead
+  of leaving you to guess at font sizes.
+
+## Reading decks, not only writing them
+
+Writing is half of it. ts-pptx also opens a `.pptx` you already have, which is
+unusual: the library it descends from generates decks and does not read them.
+
+- **[Look inside one](docs/reference/pptx-inspection.md)** and get slide count, size,
+  parts, media and fonts, without loading the whole thing into a model.
+- **[Edit one](docs/reading/read-and-edit.md)**. Open a deck, change the text on slide
+  four, save it back. Parts you did not touch come out byte for byte as they went in.
+- **[Turn one into code](docs/reference/pptx-to-script.md)**. Point it at a deck and
+  get TypeScript that rebuilds it. Anything it could not express is reported to you
+  rather than dropped in silence. It is the fastest way to learn the API: build a
+  slide by hand in PowerPoint, then read the script for it.
+
+## Where it runs
+
+| Runtime | Load it with | `writeFile` |
+| --- | --- | --- |
+| Node.js 24 or later | `import`, or `require()` with the class on `.default` | writes to disk |
+| A browser app built with a bundler | `import` | downloads the file |
+| A browser page with no build step | `import TsPptx from "https://esm.sh/pptx-ts/browser"` in a module script | downloads the file |
+| Deno, Bun, edge workers | `import` | throws; use `toBytes()` |
+
+[Where it runs](docs/getting-started/runtime.md) lists every entry point and how each runtime
+loads the one ESM build.
+
+<!-- comparison:start -->
+<!-- GENERATED REGION. Do not edit by hand.
+     Regenerate with `pnpm run comparison:render`.
+     Source: `scripts/comparison/snapshot.json`, written by `scripts/comparison/measure.mjs`. -->
+
+## How this compares with PptxGenJS
+
+ts-pptx is an independent derivative of
+[PptxGenJS](https://github.com/gitbrent/PptxGenJS), detached at its v4.0.1. Both were
+measured on 2026-09-21 by building the same 22 deck intents with each library and reading
+the bytes that came out.
+
+- **Construct coverage:** ts-pptx emitted 21 of 22, pptxgenjs 10 of 22. Nothing in the
+  corpus is emitted by pptxgenjs and not by ts-pptx.
+- **Schema validity:** of the decks each library built, 21 of 21 ts-pptx decks and 0 of 10
+  pptxgenjs decks validate with no error against the Open XML SDK.
+- **Adoption:** pptxgenjs is downloaded 10,539,687 times a month, against 1,780 for
+  ts-pptx. If a large installed base matters to you more than the differences above, use
+  pptxgenjs.
+- **Activity:** last commit on the default branch, 2026-09-15 for ts-pptx and 2025-06-26
+  for pptxgenjs. Last npm publish, 2026-08-29 and 2025-06-26.
+
+Where the two libraries part company is on the [comparison page](docs/comparison.md), and
+[how it was measured](docs/comparison-method.md) has every full table. Every intent as
+each library expresses it, including the calls that differ, is on [porting from
+PptxGenJS](docs/comparison-syntax.md).
+
+<!-- comparison:end -->
 
 ## Documentation
 
-The full documentation site is published at
-**<https://shbernal.github.io/ts-pptx/>**, including the generated API reference.
-
-- [Documentation index](docs/README.md)
-- [Project target](docs/project-target.md)
-- [Runtime and package support](docs/runtime-and-package-support.md)
-- [Development guide](docs/development.md)
-- [Testing guide](docs/testing.md)
-- [Agent development guide](docs/agent-development.md)
-- [OOXML agent context](docs/ooxml-agent-context.md)
-- [Evidence and fixtures](docs/evidence-and-fixtures.md)
-
-## Repository Development
+The documentation site, with the generated API reference, is at
+**<https://shbernal.github.io/ts-pptx/>**. The [demos page](https://shbernal.github.io/ts-pptx/demos)
+builds a quarterly review deck in your browser and previews the slides.
 
-This repository uses `pnpm` and requires Node.js `>=24`.
+- Start with the [Introduction](docs/getting-started/introduction.md),
+  [Your first deck](docs/getting-started/first-deck.md) and
+  [Core concepts](docs/getting-started/concepts.md)
+- [Tables](docs/tables.md), [connectors](docs/connectors.md), [groups](docs/groups.md) and
+  [HTML tables to slides](docs/html-tables.md)
+- [Smaller bundles](docs/bundle-size.md) for a browser program that composes only what it uses
+- [Errors and warnings](docs/errors-and-warnings.md) and
+  [troubleshooting](docs/troubleshooting.md)
 
-```bash
-pnpm install
-pnpm run verify
-```
+## Something wrong, or missing?
 
-OOXML serialization changes should also add or update a schema fixture in
-`test/schema-cases.js`. The schema suite validates through `ooxml-validate`, which
-fetches and caches its oracle binary on first use, so there is nothing to install.
+Open an issue: <https://github.com/shbernal/ts-pptx/issues>. Errors the library knows
+are its own fault print that link themselves.
 
-Package-boundary changes should run:
+If an agent writes most of your code, install the `ts-pptx-upstream` skill that ships inside
+the package. It turns a library defect the agent hits into a filed issue with a small
+reproduction, instead of a silent workaround:
 
 ```bash
-pnpm run check:package
+npx skills add ./node_modules/pptx-ts -s '*' -a claude-code -a codex -a universal -y
 ```
 
-## Demos
-
-- `demos/showcases` builds the two flagship decks from one command.
-- `demos/node` exercises Node.js ESM generation and stream output.
-- The [demos page](https://shbernal.github.io/ts-pptx/demos) builds the quarterly review in
-  your browser and previews the slides: nothing to clone.
-
-## Relationship To Upstream
-
-ts-pptx builds on the original work of Brent Ely and the gitbrent/PptxGenJS
-contributors. The modernized package target is intentionally narrower than the
-original in order to simplify the runtime contract and keep maintenance focused.
+Name the runtimes you use. [CONTRIBUTING.md](CONTRIBUTING.md) covers what the skill does
+with a report and how to refresh it after a version bump.
 
 ## License