@christophervr/pptx-viewer 0.0.2 → 1.1.27

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project are documented here.
+This file is generated from [Conventional Commits](https://www.conventionalcommits.org)
+by [git-cliff](https://git-cliff.org); do not edit it by hand.
+
+## [1.1.26](https://github.com/ChristopherVR/pptx-viewer/releases/tag/pptx-viewer-core@1.1.26) - 2026-06-21
+
+### Documentation
+
+- Sharpen npm descriptions and keywords for discoverability (by @ChristopherVR) ([8fea56d](https://github.com/ChristopherVR/pptx-viewer/commit/8fea56d7650f7dc2f3167dea97b94b612a03a4e7))
+- **core:** Reword README in plain language (by @ChristopherVR) ([793c26e](https://github.com/ChristopherVR/pptx-viewer/commit/793c26ec7e2415c66f34c637cb541483bf395a11))
+
+## [1.1.24](https://github.com/ChristopherVR/pptx-viewer/releases/tag/pptx-viewer-core@1.1.24) - 2026-06-20
+
+### Features
+
+- **core:** Add signature-node module and shared signature utilities (by @ChristopherVR) ([e7cb263](https://github.com/ChristopherVR/pptx-viewer/commit/e7cb26335f15e633cfc37371f16a6ad210be5e11))
+
+### Bug Fixes
+
+- Enable vitest globals in all packages to fix expectTypeOf errors (by @ChristopherVR) ([6d90d72](https://github.com/ChristopherVR/pptx-viewer/commit/6d90d72ff0107ad0194f9c73ceeb3df244f4cfc6))
+- **test:** Add i18n mocks to react tests and bump versions to 1.2.0 (by @ChristopherVR) ([2c1c962](https://github.com/ChristopherVR/pptx-viewer/commit/2c1c9628714b905b28592493abf02fb270107b65))
+- **deps:** Pin @xmldom/xmldom to 0.8.x in core to fix build (by @ChristopherVR) ([2ed7b2e](https://github.com/ChristopherVR/pptx-viewer/commit/2ed7b2e777d4e740a3e4c9ca7e2b3d6fc2bbd21f))
+- **core:** Declare jszip and fast-xml-parser as runtime dependencies (by @ChristopherVR) ([b6636be](https://github.com/ChristopherVR/pptx-viewer/commit/b6636be972206bb2c6acee0fed05c45b4759fbdc))
+
+### Refactor
+
+- **core:** Consume emf-converter and mtx-decompressor from npm (by @ChristopherVR) ([2f6013d](https://github.com/ChristopherVR/pptx-viewer/commit/2f6013d5b8fab0aef5b32901841d94c0fa886f24))
+
+### Documentation
+
+- Restructure root README, elevate limitations, fix outdated claims (by @ChristopherVR) ([86dcda9](https://github.com/ChristopherVR/pptx-viewer/commit/86dcda9b5e3129f2223341337055778db574e985))
+- Rewrite limitations with technical explanations and remove inaccurate claims (by @ChristopherVR) ([ac4bc84](https://github.com/ChristopherVR/pptx-viewer/commit/ac4bc84ed9bd03f62e3ae29c35baf3f444a3c0bf))
+- **readme:** Npm-friendly READMEs — hero image, capabilities & install first (by @ChristopherVR) ([c843d19](https://github.com/ChristopherVR/pptx-viewer/commit/c843d1934b846f901bba92e63d2b01f9479594d0))
+- Streamline npm READMEs and add badges, screenshots, demo links (by @ChristopherVR) ([92e980d](https://github.com/ChristopherVR/pptx-viewer/commit/92e980d434900abd223c4d70c6cae19a623f9ca8))
+
+### Build & CI
+
+- Independent per-package versioning, tags, and changelogs (by @ChristopherVR) ([79595d9](https://github.com/ChristopherVR/pptx-viewer/commit/79595d972d7c4102e8b1e1e3926f439486f76ba1))
+
+### Dependencies
+
+- **deps:** Update all dependencies to latest (by @ChristopherVR) ([e3287c0](https://github.com/ChristopherVR/pptx-viewer/commit/e3287c03ff58b1a1ae103ed32a513468a454a084))
+- **deps:** Bump all workspace manifest floors to latest (by @ChristopherVR) ([890c33d](https://github.com/ChristopherVR/pptx-viewer/commit/890c33d667a39480a69e6a3da893964382993b29))
+
+### Chores
+
+- Add license files, NOTICE, and package metadata for npm publishing (by @ChristopherVR) ([9464bb8](https://github.com/ChristopherVR/pptx-viewer/commit/9464bb8b91734daf35131d3c7e52e60895fe0a1c))
+- Bump all packages to v1.1.0 and remove remaining MyClawAssist refs (by @ChristopherVR) ([c386511](https://github.com/ChristopherVR/pptx-viewer/commit/c38651150c08011cee5e17e15f7ee8adc0014b80))
+- Bump all packages to 1.x.1 patch versions (by @ChristopherVR) ([c75205a](https://github.com/ChristopherVR/pptx-viewer/commit/c75205a96cc7797d1647ac4705395b7707ac8910))
+- Bump all packages to minor versions for SDK table support (by @ChristopherVR) ([2d4b635](https://github.com/ChristopherVR/pptx-viewer/commit/2d4b6351b0bf328f8a556cf593733fd8ad36c7b5))
+- Bump dependencies to latest and minor-bump packages for parity work (by @ChristopherVR) ([da19fdf](https://github.com/ChristopherVR/pptx-viewer/commit/da19fdf9a4670d274d9973b67aa22d34217b8555))
+- Roll TypeScript back to 5.9.x; quiet new oxlint vitest rules (by @ChristopherVR) ([713c020](https://github.com/ChristopherVR/pptx-viewer/commit/713c020ac2428db0fb1eb6cb30e56b2cff19a80f))
+- Relicense from MIT to Apache-2.0 (by @ChristopherVR) ([e12f926](https://github.com/ChristopherVR/pptx-viewer/commit/e12f9266f02bebbfc218986b617c418fee43a56b))

package/NOTICE

@@ -0,0 +1,18 @@
+pptx-viewer-core
+Copyright (c) 2025-present pptx-viewer contributors
+
+This package is licensed under the Apache License 2.0. See the LICENSE file for
+details. Under Section 4(d) of that license, please preserve this NOTICE (or the
+attribution it contains) in any derivative works you distribute.
+
+This package bundles the following component under a different license:
+
+  mtx-decompressor — MicroType Express (MTX) font decompressor
+  License: Mozilla Public License 2.0 (MPL-2.0)
+  Source:  https://github.com/ChristopherVR/pptx-viewer/tree/main/packages/mtx-decompressor
+  Origin:  Ported from libeot (https://github.com/nicowilliams/libeot)
+           by Brennan T. Vincent, licensed under MPL-2.0.
+
+Under MPL-2.0, the source code of the mtx-decompressor component remains
+available under the terms of the Mozilla Public License 2.0. The full text
+of the MPL-2.0 can be found at: https://mozilla.org/MPL/2.0/

package/README.md

@@ -1,40 +1,185 @@
-# @christophervr/pptx-viewer
+# pptx-viewer-core
 
-> ⚠️ **For now, this package is just an alias for [`pptx-viewer-core`](https://www.npmjs.com/package/pptx-viewer-core).**
-> Installing it installs the core engine, and importing from it re-exports the
-> entire core API. There is no extra functionality on top yet.
+[![npm version](https://img.shields.io/npm/v/pptx-viewer-core.svg)](https://www.npmjs.com/package/pptx-viewer-core)
+[![license](https://img.shields.io/npm/l/pptx-viewer-core.svg)](https://github.com/ChristopherVR/pptx-viewer/blob/main/LICENSE)
+[![types](https://img.shields.io/npm/types/pptx-viewer-core.svg)](https://www.npmjs.com/package/pptx-viewer-core)
+
+> **Also published as [`@christophervr/pptx-viewer`](https://www.npmjs.com/package/@christophervr/pptx-viewer)** -- the two package names are identical releases of the same code. Use whichever name you prefer; they are always published together and kept in sync.
+
+> A TypeScript library that **reads, creates, edits, and saves** PowerPoint (`.pptx`) files. It runs in the browser and in Node.js, with no native or system dependencies.
+
+Hand it the bytes of a `.pptx` file and it gives you back a structured, fully typed object that describes every slide: text, shapes, images, charts, tables, and more. Change anything in that object and write it back to a valid `.pptx`. You can also build new presentations from scratch with a simple chainable API, or turn a deck into Markdown.
+
+There is no UI here: this is the engine on its own. Use it directly when you need to process `.pptx` files without a screen, for example on a server, in a script, or in a build step. The same engine powers the [`pptx-react-viewer`](https://www.npmjs.com/package/pptx-react-viewer), `pptx-vue-viewer`, and `pptx-angular-viewer` UI components.
+
+<samp>**[📦 npm](https://www.npmjs.com/package/pptx-viewer-core)** · **[📖 Full docs](https://christophervr.github.io/pptx-viewer/)** · **[▶️ Live demo](https://christophervr.github.io/pptx-viewer/demo/)** · **[⚛️ React UI](https://www.npmjs.com/package/pptx-react-viewer)**</samp>
+
+---
+
+## Install
 
 ```bash
-npm install @christophervr/pptx-viewer
+npm install pptx-viewer-core
+# required companions:
+npm install jszip fast-xml-parser
 ```
 
-```ts
-// These are equivalent today:
-import { PptxHandler } from '@christophervr/pptx-viewer';
+> Two packages are always needed alongside it: **jszip** (a `.pptx` is a ZIP file, and this reads and writes that container) and **fast-xml-parser** (the slides inside are XML, and this reads and writes it). Password protection and digital signatures need a few extra packages (`node-forge`, `xml-crypto`, `@xmldom/xmldom`), but only if you actually use those features.
+
+## What it does
+
+| Capability  | Description                                                                                                                                      |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Read**    | Open a `.pptx` and pull out slides, text, shapes, images, charts, tables, SmartArt, themes, comments, animations, transitions, and document info |
+| **Edit**    | Change the data in memory: add, remove, or reorder slides; insert elements; edit text; restyle; switch themes                                    |
+| **Save**    | Write the changed data back to a valid `.pptx`, leaving everything you did not touch untouched                                                   |
+| **Convert** | Turn a deck into Markdown, optionally pulling the images out alongside it                                                                        |
+| **Export**  | Save individual slides as their own standalone `.pptx` files                                                                                     |
+| **Protect** | Open and save password-protected files (AES-128/256 encryption)                                                                                  |
+
+Positions and sizes use PowerPoint's own internal unit, the EMU (English Metric Unit): 1 inch = 914,400 EMU, 1 point = 12,700 EMU, and 1 pixel = 9,525 EMU at 96 DPI. You rarely deal with the raw numbers: helpers (`inches`, `cm`, `mm`, `pt`) let you work in familiar units instead.
+
+---
+
+## Quick start
+
+```typescript
 import { PptxHandler } from 'pptx-viewer-core';
+
+// 1. Open a .pptx file
+const handler = new PptxHandler();
+const buffer = await fetch('presentation.pptx').then((r) => r.arrayBuffer());
+const data = await handler.load(buffer);
+
+console.log(
+	`${data.slides.length} slides, canvas ${data.canvasSize.width}×${data.canvasSize.height}`,
+);
+
+// 2. Change a slide
+data.slides[0].elements[0].text = 'Updated title';
+
+// 3. Save it back to .pptx bytes
+const outputBytes = await handler.save(data.slides); // => Uint8Array
+
+// 4. Or pull out just a few slides as separate files
+const exports = await handler.exportSlides(data.slides, { slideIndexes: [0, 2] }); // => Map<number, Uint8Array>
+```
+
+`load()` gives you a `PptxData` object: a plain, fully typed description of the presentation. Read from it, change it, and pass its `slides` back to `save()` to get a valid `.pptx` file as bytes.
+
+### Build a presentation from scratch
+
+The chainable API lets you create a deck step by step, without touching any file format details:
+
+```typescript
+import { Presentation, ThemePresets, ChartBuilder } from 'pptx-viewer-core';
+
+const pptx = await Presentation.create({
+	title: 'Sales Report',
+	theme: ThemePresets.MODERN_BLUE,
+});
+
+// Each slide is added to the deck automatically: no manual .build() or .push() needed
+pptx
+	.addSlide('Title Slide')
+	.addText('Q4 Sales Report', { fontSize: 44, bold: true, x: 100, y: 200, width: 800, height: 80 });
+
+pptx
+	.addSlide('Blank')
+	.addText('Revenue by Region', { fontSize: 28, x: 50, y: 30, width: 600, height: 50 })
+	.addBuilderElement(
+		ChartBuilder.create('bar')
+			.categories(['North', 'South', 'East', 'West'])
+			.addSeries('2026', [210, 150, 180, 120], '#2563EB')
+			.title('Revenue ($M)')
+			.bounds(50, 100, 860, 420),
+	);
+
+pptx.replaceText('2026', 'FY2026'); // find/replace, merge, and templates all chain the same way
+
+const bytes = await pptx.save();
+```
+
+The builder API comes in three levels, from highest to lowest:
+
+1. **`Presentation`**: the whole deck at once (slides, text operations, sections, templates, merging, saving).
+2. **Element builders**: one per element type, for fine-grained control: `TextBuilder`, `ShapeBuilder`, `ChartBuilder`, `TableBuilder`, `ImageBuilder`, `ConnectorBuilder`, `MediaBuilder`, `GroupBuilder`.
+3. **`PptxXmlBuilder`**: raw XML, for the rare cases the higher levels do not cover.
+
+It also ships unit helpers (`inches`, `cm`, `mm`, `pt`), common slide sizes (`SlideSizes`), and 8 ready-made themes (`ThemePresets`). The [full docs](https://christophervr.github.io/pptx-viewer/) cover every builder.
+
+### Turn a deck into Markdown
+
+```typescript
+import { PptxMarkdownConverter } from 'pptx-viewer-core';
+
+const converter = new PptxMarkdownConverter({ includeMetadata: true, imageHandling: 'extract' });
+const result = await converter.convert(
+	buffer,
+	{ outputPath: 'output.md', mediaFolderName: 'media' },
+	fileSystemAdapter,
+);
+// => the Markdown text, plus stats on any images that were pulled out
 ```
 
-`pptx-viewer-core` is the framework-agnostic engine: parse, edit, serialize, and
-convert PowerPoint (`.pptx`) files in memory.
+To write files to disk, pass a `FileSystemAdapter` (an object with `writeFile`, `writeBinaryFile`, and `createFolder` methods); this keeps the converter free of any assumptions about where it runs. By default it keeps each element where it sat on the slide (absolutely positioned HTML); set `semanticMode: true` to get clean headings, paragraphs, and lists instead.
+
+---
+
+## `PptxHandler` API
+
+`PptxHandler` is the one class you use to open, change, and save files. Its main methods:
+
+| Method                     | Signature                                               | What it does                                           |
+| -------------------------- | ------------------------------------------------------- | ------------------------------------------------------ |
+| `load`                     | `(data, options?) => Promise<PptxData>`                 | Open a `.pptx` and return the structured data          |
+| `save`                     | `(slides, options?) => Promise<Uint8Array>`             | Write slides back to `.pptx` bytes                     |
+| `exportSlides`             | `(slides, options) => Promise<Map<number, Uint8Array>>` | Save chosen slides as standalone files                 |
+| `getImageData`             | `(path) => Promise<string \| undefined>`                | Get an embedded image as a base64 data URL             |
+| `getMediaArrayBuffer`      | `(path) => Promise<ArrayBuffer \| undefined>`           | Get the raw bytes of an embedded media file            |
+| `getLayoutOptions`         | `() => PptxLayoutOption[]`                              | List the slide layouts available                       |
+| `getCompatibilityWarnings` | `() => PptxCompatibilityWarning[]`                      | List features in the file that are not fully supported |
+| `applyTheme`               | `(colors, fonts, name?) => Promise<void>`               | Apply a complete theme                                 |
+| `setPresentationTheme`     | `(path, applyToAll?) => Promise<void>`                  | Load a `.thmx` theme file                              |
+
+The `PptxData` you get from `load()` exposes `slides`, `canvasSize`, `theme`, `slideMasters`, `slideLayouts`, `sections`, `coreProperties`, `embeddedFonts`, and more. See the [full docs](https://christophervr.github.io/pptx-viewer/) for the complete `PptxHandler`, chart/SmartArt, and theme APIs.
+
+## What's supported
+
+| Category          | Details                                                                                                                                             |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Element types** | 16: text, shape, connector, image, picture, table, chart, smartArt, ole, media, group, ink, contentPart, zoom, model3d, unknown                     |
+| **Preset shapes** | 187+ PowerPoint shapes, including ones with adjustable handles                                                                                      |
+| **Chart types**   | 23, including waterfall, funnel, treemap, sunburst, box-whisker, region-map, and combo charts; with trendlines, error bars, and embedded Excel data |
+| **Transitions**   | 42 types (including morph, vortex, ripple, and shred)                                                                                               |
+| **Animations**    | 40+ presets, including colour animation, motion paths, and text that builds in by word, letter, or paragraph                                        |
+| **SmartArt**      | 13 layout types, broken down into editable shapes                                                                                                   |
+| **Fills**         | Solid, gradient (linear, radial, path), image, and 48 patterns                                                                                      |
+| **Themes**        | 8 built-in presets, switchable at runtime, with layout and placeholder remapping                                                                    |
+| **Security**      | AES-128/256 encryption and decryption, modify-password (SHA), and detection of digital signatures                                                   |
+| **Preserved**     | VBA macros, custom XML, comment authors, and strict-format files are kept intact through a save                                                     |
+
+## How it works
+
+You only ever work with one class, `PptxHandler`, and one data object, `PptxData`. The engine takes care of the rest: when you call `load()` it unzips the file, reads the XML, resolves the theme, masters, and layouts, and hands you a clean object. `save()` runs those same steps in reverse.
 
-## Want a UI component?
+A few things worth knowing as you use it:
 
-This package does **not** provide a viewer component. Use the framework-specific
-package for your stack — each is built on `pptx-viewer-core`:
+- **Every element has a `type` field** (`text`, `shape`, `image`, `chart`, `table`, and so on). Check it before reading element-specific properties, for example `if (element.type === 'image')`. TypeScript then knows exactly which fields exist.
+- **Shapes are drawn from a built-in catalogue** of 187+ PowerPoint shapes, so curves, arrows, and callouts come out with the right outlines.
+- **Colours follow PowerPoint's theme rules**, so a colour defined as "accent 1, but 20% lighter" resolves to the correct final value for the active theme.
 
-- **React** — [`pptx-react-viewer`](https://www.npmjs.com/package/pptx-react-viewer)
-- **Vue 3** — [`pptx-vue-viewer`](https://www.npmjs.com/package/pptx-vue-viewer)
-- **Angular** — [`pptx-angular-viewer`](https://www.npmjs.com/package/pptx-angular-viewer)
+Under the hood the engine is split into many small, focused modules. If you want the full load and save pipeline, the complete type system, and a module-by-module map, see the [full documentation](https://christophervr.github.io/pptx-viewer/).
 
-## Status
+## Limitations
 
-This is a reserved scope name that currently forwards to the core engine. It may
-gain its own surface in the future; until then, prefer importing `pptx-viewer-core`
-directly or the framework package above.
+- **OLE objects** (embedded Word docs, spreadsheets, and similar) are read-only: you get their preview image, not their contents.
+- **SmartArt** is broken into editable shapes using the drawing data PowerPoint already saved in the file. There is no engine that re-flows the layout if you change it.
+- **Chart editing is data-only**: you can change series, data points, categories, and the chart type. Other chart properties are read for display but cannot be edited.
+- **Strict-format files** (ISO/IEC 29500 Strict) are converted to the more common Transitional form when opened and converted back when saved.
 
-See the [project repository](https://github.com/ChristopherVR/pptx-viewer) for
-full documentation.
+See the [full docs](https://christophervr.github.io/pptx-viewer/) for the details behind each of these.
 
 ## License
 
-Apache-2.0 © ChristopherVR
+[Apache-2.0](LICENSE). Please keep the [`NOTICE`](NOTICE) file with redistributions.