@s8fy/pptx-parser 1.0.0

package/LICENSE

@@ -0,0 +1,36 @@
+Default license for this package's original code and modifications:
+
+PolyForm Noncommercial License 1.0.0
+https://polyformproject.org/licenses/noncommercial/1.0.0
+
+Required Notice: Copyright (c) 2025-PRESENT hustcer
+
+This package is source-available, not open source. No commercial use is granted
+to third parties for the licensor's original code and modifications unless
+separately licensed.
+
+Third-party notice:
+This package includes material derived from `pptxtojson` by `pipipi-pikachu`.
+The preserved upstream MIT notice for those portions is reproduced below.
+
+MIT License
+
+Copyright (c) 2020-PRESENT pipipi-pikachu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,336 @@
+# @s8fy/pptx-parser
+
+A browser-first TypeScript library for parsing `.pptx` files into structured data with JavaScript or WebAssembly, and converting original PPTX bytes to PDF. Node.js **22.12+** is also supported through ESM and CommonJS entrypoints.
+
+### Architecture
+
+- **Structured text output** — text content outputs `TextParagraph[]` JSON arrays with full formatting metadata, replacing raw HTML strings and eliminating `dangerouslySetInnerHTML`
+- **Pure data output** — parser only outputs raw parsed data; model adaptation lives in `@s8fy/pptx-core` and DOM/SVG rendering lives in `@s8fy/pptx-renderer`
+- **Full TypeScript rewrite** — all source files converted from JavaScript to TypeScript with strict mode
+
+### New Features
+
+- **Embedded font extraction** — extracts font binary data (EOT/ODTTF/TTF/OTF/WOFF) from PPTX embedded font list; opt-in via `extractFonts` option (default `false` to avoid loading large CJK fonts)
+- **Arrow endpoints** — parses `a:headEnd`/`a:tailEnd` on lines with support for arrow, stealth, diamond, dot marker types and sm/med/lg sizing
+- **Chart type mapping** — OOXML chart types mapped to simplified types (`bar`, `column`, `line`, `pie`, `ring`, `area`, `radar`, `scatter`) directly in the parser
+
+## Install
+
+```sh
+pnpm add @s8fy/pptx-parser
+# or
+npm install @s8fy/pptx-parser
+```
+
+## Usage
+
+### Browser
+
+```html
+<input
+  type="file"
+  accept="application/vnd.openxmlformats-officedocument.presentationml.presentation"
+/>
+```
+
+```javascript
+import { parsePptx, revokeBlobUrls } from '@s8fy/pptx-parser'
+
+const input = document.querySelector('input[type="file"]')
+if (!(input instanceof HTMLInputElement)) throw new Error('Missing file input')
+input.addEventListener('change', async () => {
+  const file = input.files?.[0]
+  if (!file) return
+  try {
+    const result = await parsePptx(await file.arrayBuffer(), { parser: 'wasm' })
+    console.log(result)
+    // Keep result while its media is used; see cleanup below.
+    revokeBlobUrls(result)
+  } catch (error) {
+    console.error(error)
+  }
+})
+```
+
+### Node.js
+
+```javascript
+const { parsePptx } = require('@s8fy/pptx-parser')
+const { readFileSync } = require('node:fs')
+
+async function main() {
+  const bytes = readFileSync('test.pptx')
+  const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength)
+  const result = await parsePptx(buffer)
+  console.log(result)
+}
+
+main().catch(console.error)
+```
+
+## API
+
+### `parsePptx(file: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>`
+
+#### Options
+
+| Option         | Type             | Default          | Description                                                     |
+| -------------- | ---------------- | ---------------- | --------------------------------------------------------------- |
+| `extractFonts` | `boolean`        | `false`          | Whether to extract embedded font binary data                    |
+| `parser`       | `'js' \| 'wasm'` | `'js'`           | Parser engine for this low-level package                        |
+| `unzipMode`    | `'js' \| 'wasm'` | `'wasm'`         | ZIP engine when `parser: 'wasm'`                                |
+| `wasmUrl`      | `string \| URL`  | Package-relative | Override the parser WASM URL for CDN or self-hosted deployments |
+| `timing`       | `boolean`        | `false`          | Include per-phase timing in the optional `_timing` result field |
+| `signal`       | `AbortSignal`    | None             | Cancel this parse request without cancelling other callers      |
+
+`@s8fy/pptx-core`, the renderer, and the viewer facade default to the WASM parser. The low-level parser defaults to JavaScript for backward compatibility.
+
+The package ships package-relative JS/WASM/PDF workers and both WASM binaries. Modern bundlers such as Vite copy these assets from the static runtime references. The UMD entry resolves adjacent assets from the current `<script>` URL, so keep the published `dist/` files together when loading it directly. CommonJS is intended for Node.js/SSR and can load the packaged WASM files directly when `parser: 'wasm'` is requested. Browser applications should prefer the ESM entry. Both the parser and PDF APIs accept explicit `wasmUrl` overrides; the PDF API additionally accepts `workerUrl`.
+
+### Parser WASM deployment
+
+Automatic package-relative resolution is the default. For a CDN, offline bundle, or private deployment, copy `node_modules/@s8fy/pptx-parser/dist/mbt/main.wasm` into the application's static assets and pass its deployed URL:
+
+```ts
+await parsePptx(buffer, {
+  parser: 'wasm',
+  wasmUrl: '/vendor/s8fy/main.wasm',
+})
+```
+
+- The package-relative Worker/WASM paths are covered by the repository's Vite consumer smoke. For other bundlers, verify the deployed assets; use the bundler's public/copy-asset facility when supplying an override.
+- Next.js and Nuxt serve the copied file from `public/`; call the SDK from client-side code and pass a root-relative URL.
+- SvelteKit serves it from `static/`; pass the matching root-relative URL.
+- Angular CLI can add the source file as an `assets` glob in `angular.json`, then pass the configured output URL.
+
+The same-origin server should return the file without HTML fallback content and preferably with `Content-Type: application/wasm`. Cross-origin URLs must allow the application origin through CORS.
+
+### PDF and resource helpers
+
+- `pptxToPdf(file, options?)` returns PDF bytes as `Uint8Array`.
+- `pptxToPdfBlob(file, options?)` returns a browser `Blob`.
+- `revokeBlobUrls(data)` releases Blob URLs created while parsing media.
+- `transferBlobUrls(source, target)` moves cleanup ownership to a custom adapted object, without copying bytes. After transfer, clean up `target` instead of `source`.
+- `ResourcePolicyError` and `RESOURCE_POLICY_CONTRACT` expose the parser's deterministic input/resource-limit contract.
+
+PDF conversion accepts explicit `wasmUrl`, `wasmBytes`, and `workerUrl` overrides, font/emoji fallback sources, watermarks, and signed-license runtime data. Prefer the higher-level `@s8fy/pptx-core` facade unless the raw parser result is required.
+
+```ts
+import { pptxToPdf } from '@s8fy/pptx-parser'
+
+export async function convertFile(file: File): Promise<Uint8Array> {
+  return pptxToPdf(await file.arrayBuffer(), {
+    unicodeFallbackFont: { url: '/fonts/NotoSansSC-Regular.ttf' },
+  })
+}
+```
+
+Serve that font URL yourself or omit it for documents that do not need a Unicode fallback. The PDF API always uses its PDF WASM engine; choosing JS for parsing does not make PDF conversion JavaScript-only. PDF `wasmUrl` points to `pdf-converter.wasm`, not parser `main.wasm`. Browser-window conversion requires a working PDF Worker and does not silently retry on the main thread if the Worker fails. Node conversion runs on the current thread.
+
+Both PDF functions accept `signal` for cancellation. Font options include `regularFonts` (with regular/bold/italic/boldItalic styles), `unicodeFallbackFont`, `mathFallbackFont`, `emojiFallbackFont`, and `emojiBitmapFallback`. Browser font CSS does not automatically supply PDF font bytes. The low-level `watermarks`/`licenseRuntime` options differ from core/viewer's `watermark`/`license` facade; do not interchange their option objects.
+
+### Cancellation, errors, and cleanup
+
+Pass `new AbortController().signal` to parsing or PDF conversion, then call that controller's `abort()` when the request is obsolete. Cancellation rejects the request; synchronous work on the same JavaScript thread cannot be interrupted until control returns.
+
+When a parsed result is no longer displayed or otherwise used, call `revokeBlobUrls(result)` on that same object. Media URLs may be `blob:` URLs rather than base64 strings and are not portable across sessions. A JSON clone does not retain the original cleanup ownership. Use `transferBlobUrls` only when intentionally replacing the owner with an adapted model.
+
+`ResourcePolicyError.details` contains `reason`, `stage`, `subject`, `limit`, `observed`, `unit`, and `policyVersion`. These engineering limits are independent of commercial licenses (`commercialUpgradeApplicable` is false); catch and inspect the error rather than retrying the same oversized input. Other parse/conversion failures can be ordinary `Error` instances.
+
+#### ParseResult
+
+```typescript
+{
+  slides: Slide[]
+  themeColors: string[]
+  hlinkColor: string | null
+  fonts: EmbeddedFont[]
+  size: {
+    width: number   // px
+    height: number  // px
+  }
+}
+```
+
+## Output Example
+
+```javascript
+{
+  slides: [
+    {
+      fill: { type: 'color', value: '#FFFFFF' },
+      elements: [
+        {
+          type: 'text',
+          left: 100,
+          top: 50,
+          width: 600,
+          height: 80,
+          content: [
+            {
+              align: 'center',
+              lineHeight: 1.2,
+              runs: [
+                {
+                  text: 'Hello World',
+                  fontSize: '24pt',
+                  fontFamily: 'Calibri',
+                  fontWeight: 'bold',
+                  color: '#333333'
+                }
+              ]
+            }
+          ],
+          vAlign: 'mid',
+          name: 'Title 1',
+          order: 0,
+          // ...
+        },
+        // more elements...
+      ],
+      layoutElements: [/* master/layout elements */],
+      note: 'Speaker notes...',
+      transition: { type: 'fade', duration: 500, direction: null }
+    },
+    // more slides...
+  ],
+  themeColors: ['#4472C4', '#ED7D31', '#A5A5A5', '#FFC000', '#5B9BD5', '#70AD47'],
+  hlinkColor: null,
+  fonts: [/* embedded fonts if extractFonts: true */],
+  size: { width: 960, height: 540 }
+}
+```
+
+## Element Types
+
+### Text (`type: 'text'`)
+
+Text box with structured paragraphs. `content` is a `TextParagraph[]` array containing runs with font/color/decoration info, list/bullet info, and paragraph-level alignment/spacing.
+
+### Shape (`type: 'shape'`)
+
+Predefined or custom shapes. Also uses `TextParagraph[]` for `content`. Includes `shapType`, optional `path` (SVG), `keypoints`, and arrow endpoints (`headEnd`/`tailEnd`).
+
+### Image (`type: 'image'`)
+
+Image element with `src` (data URI or an owned Blob URL), optional `rect` (crop), `geom` (clip shape), and `filters` (sharpen, brightness, contrast, saturation, color temperature).
+
+### Table (`type: 'table'`)
+
+Table with `data` (2D `TableCell[][]`), `rowHeights`, `colWidths`. Cells support `rowSpan`/`colSpan` merging, per-cell borders and fill.
+
+### Chart (`type: 'chart'`)
+
+Chart data with `chartType` (`bar`, `column`, `line`, `pie`, `ring`, `area`, `radar`, `scatter`), `rawChartType` (original OOXML type), `colors`, and optional `barDir`, `marker`, `holeSize`, `grouping`, `style`.
+
+### Video (`type: 'video'`)
+
+Video element with `blob` (Blob URL) or `src` (external URL), optional `poster` (thumbnail image from slide), `ext` (file extension), and `rotate`.
+
+### Audio (`type: 'audio'`)
+
+Audio element with `blob` (Blob URL, optional if format unsupported), optional `ext` (file extension), and `rotate`.
+
+### Diagram (`type: 'diagram'`)
+
+SmartArt with `elements` (Shape/Text sub-elements) and `textList` (fallback text content).
+
+### Math (`type: 'math'`)
+
+Math formula with `latex` (LaTeX expression), `picBase64` (fallback image), and optional `text` (mixed text/formula content).
+
+### Group (`type: 'group'`)
+
+Group container with nested `elements` array.
+
+## Structured Text Format
+
+Text content uses structured `TextParagraph[]` instead of HTML strings:
+
+```typescript
+interface TextParagraph {
+  align: string // 'left' | 'center' | 'right' | 'justify'
+  lineHeight?: number // CSS line-height value
+  spaceBefore?: string // e.g. '12pt'
+  spaceAfter?: string // e.g. '6pt'
+  list?: {
+    type: 'ul' | 'ol'
+    level: number
+    bullet?: BulletInfo
+  }
+  runs: (TextRun | TextLink | TextBreak)[]
+}
+
+interface TextRun {
+  text: string
+  color?: string | GradientColor
+  fontSize?: string // e.g. '18pt'
+  fontFamily?: string
+  fontWeight?: string // e.g. 'bold'
+  fontStyle?: string // e.g. 'italic'
+  textDecoration?: string // e.g. 'underline'
+  textDecorationLine?: string // e.g. 'line-through'
+  letterSpacing?: string
+  verticalAlign?: string // 'super' | 'sub'
+  textShadow?: string
+  highlightColor?: string
+}
+
+interface TextLink extends TextRun {
+  linkURL: string
+  linkColor?: string
+}
+
+interface TextBreak {
+  type: 'br'
+}
+```
+
+## Fill Types
+
+All fill-capable elements support four fill types:
+
+- **Color** (`type: 'color'`) — solid color value
+- **Image** (`type: 'image'`) — base64 image with opacity
+- **Gradient** (`type: 'gradient'`) — linear/circle/rect/shape gradient with color stops
+- **Pattern** (`type: 'pattern'`) — pattern type with foreground/background colors
+
+## Embedded Fonts
+
+When `extractFonts: true` is passed:
+
+```typescript
+interface EmbeddedFont {
+  typeface: string
+  styles: {
+    regular?: { path: string; data: ArrayBuffer }
+    bold?: { path: string; data: ArrayBuffer }
+    italic?: { path: string; data: ArrayBuffer }
+    boldItalic?: { path: string; data: ArrayBuffer }
+  }
+}
+```
+
+## Build Outputs
+
+| Format | File                | Usage                                         |
+| ------ | ------------------- | --------------------------------------------- |
+| ESM    | `dist/index.js`     | Modern bundlers (Vite, Webpack 5+)            |
+| CJS    | `dist/index.cjs`    | Node.js `require()`                           |
+| UMD    | `dist/index.umd.js` | Browser `<script>` tag (global: `pptxParser`) |
+
+## Type Definitions
+
+The package root exports the complete bundled TypeScript declarations through its `types` and conditional `exports` fields. No deep import is required.
+
+WASM parsing/PDF conversion requires WebAssembly GC support. Workers may be unavailable in some hosts: parsing has a main-thread fallback, while browser-window PDF conversion requires its Worker. The parsed model is a subset of PowerPoint behavior; output presence does not imply pixel-identical rendering or support for every animation/chart effect.
+
+## Credits
+
+This library is based on [pptxtojson](https://github.com/pipipi-pikachu/pptxtojson) by pipipi-pikachu.
+
+## License
+
+Default license for original contributions: `PolyForm-Noncommercial-1.0.0`
+
+Commercial use of those contributions requires a separate commercial license.