@openpresentation/opf-pptx 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenPresentation
+
+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,108 @@
+# OPF PPTX
+
+Pure local PowerPoint conversion tooling for Open Presentation Format documents. This repo owns the Phase 3 and Phase 4 toolkit lanes: OPF to PPTX export and PPTX to OPF import.
+
+## Scope
+
+- Package: `@openpresentation/opf-pptx`
+- Repository: `OpenPresentation/opf-pptx`
+- License: MIT
+- Compatibility target: `@openpresentation/opf`
+- Renderer relationship: may use `@openpresentation/opf-render` for chart rasterization and visual verification
+- Public export API: `toPptx(opf, opts)`
+- Public import API: `fromPptx(buffer, opts)`
+
+The export path validates OPF with `@openpresentation/opf`, maps slide titles and common content payloads to editable PowerPoint objects through `pptxgenjs`, then normalizes the generated ZIP for stable entry ordering, fixed timestamps, and reproducible bytes.
+
+```js
+import { toPptx } from "@openpresentation/opf-pptx";
+
+const bytes = await toPptx({
+  $schema: "https://openpresentation.org/schema/opf/v1",
+  name: "Quarterly Review",
+  slides: [
+    {
+      title: "Revenue grew across all regions",
+      items: ["North America +18%", "EMEA +14%", "APAC +11%"]
+    }
+  ]
+});
+
+await fs.promises.writeFile("quarterly-review.pptx", bytes);
+```
+
+`toPptx` returns a `Uint8Array` containing a PowerPoint-openable `.pptx`. It does not fetch remote assets. Data URI images and local paths can be embedded directly; hosts that need private asset loading should pass `imageResolver(src, context)`. Set `strictAssets: true` to turn unresolved or remote image assets into structured `OPFPptxError` failures instead of editable placeholder boxes.
+
+`fromPptx` parses an existing `.pptx` buffer locally and returns an OPF document that validates with `@openpresentation/opf`:
+
+```js
+import { fromPptx, toPptx } from "@openpresentation/opf-pptx";
+
+const opf = await fromPptx(await fs.promises.readFile("source.pptx"));
+const roundTripBytes = await toPptx(opf);
+
+await fs.promises.writeFile("round-trip.pptx", roundTripBytes);
+```
+
+The importer reads core properties, slide order, text boxes, speaker notes, embedded images, tables, and basic cached chart data from the OOXML parts. Slides or objects that do not map cleanly fall back to editable `blocks[]` payloads; OOXML positions are used for deterministic ordering and title/subtitle detection while keeping the emitted OPF schema-valid.
+
+## v1 Placeholder and OOXML Mapping
+
+The first exporter keeps the public API stable while using `pptxgenjs` internally:
+
+- `Slide.title`, `Slide.subtitle`, and `Slide.tag` become editable text boxes, not PowerPoint master placeholders.
+- Root payloads, `blocks[]`, and promoted region keys become editable slide objects in deterministic regions. Promoted keys use the OPF 3x3 region vocabulary (`top`, `middle`, `bottom`, `left`, `center`, `right`).
+- Text, lists, metrics, quotes, timelines, code, tables, and inline-data charts are emitted as editable PowerPoint text, table, and chart objects.
+- Image assets are embedded only when supplied as data URIs, local paths, or host-resolved bytes/paths. Remote asset URLs are never fetched by the runtime path.
+- ZIP entries, generated chart/workbook part names, core-property timestamps, and nested chart workbook timestamps are normalized for reproducible bytes.
+
+This pass did not require an OPF schema change. The deferred full OOXML placeholder mapping from `docs/plans/layout-placeholders.md` remains a later hand-written OOXML emitter concern.
+
+## v1 Import Mapping
+
+The first importer is mechanical and schema-compatible:
+
+- Presentation core properties map to OPF `name`, `description`, and `author`.
+- Slide text placeholders and large top-of-slide text boxes map to `title` and `subtitle` when recognizable.
+- Remaining text boxes map to `blocks[]` as text or list payloads, sorted by OOXML position.
+- PowerPoint tables map to OPF table blocks, embedded images map to data URI image blocks, and cached chart series map to basic OPF chart blocks.
+- Unknown non-text shapes and unsupported graphic frames become editable text fallback blocks instead of failing the import.
+
+There is no AI classification pass in the OSS runtime. Hosts can run optional cleanup or semantic remapping after `fromPptx` returns.
+
+## Runtime Policy
+
+The package runtime must stay local and deterministic:
+
+- No hosted service in the critical path
+- No telemetry or hidden analytics
+- No commercial SDK dependency in the critical path
+- No required network calls
+- No required AI dependency
+- No required AI cleanup or classification pass for PPTX import
+- No required LibreOffice dependency in the runtime path; LibreOffice is allowed only as an optional verification tool in CI
+- Host applications own auth, storage, queues, analytics, collaboration, branding, and product workflow
+
+## Development
+
+```sh
+npm ci
+npm run build
+npm run typecheck
+npm test
+npm run validate
+```
+
+LibreOffice is not a runtime dependency. When it is installed in CI or a local verification environment, generated `.pptx` files can be smoke-opened there as an optional export check.
+
+## Release Lane
+
+Public npm package publication is handled by `.github/workflows/release.yml` with npm provenance.
+
+Required first-publish setup:
+
+1. An npm owner for the `@openpresentation` scope must run the first publish or reserve/grant the `@openpresentation/opf-pptx` package.
+2. Configure npm Trusted Publishing for GitHub repository `OpenPresentation/opf-pptx` and workflow `.github/workflows/release.yml`.
+3. Publish by creating a GitHub Release or manually running the Release workflow after CI passes.
+
+This repo does not require an npm automation token when Trusted Publishing is configured.

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+export declare const packageName = "@openpresentation/opf-pptx";
+
+export declare const releaseLane: Readonly<{
+  githubRepository: "OpenPresentation/opf-pptx";
+  npmPackage: "@openpresentation/opf-pptx";
+  compatibilityPackage: "@openpresentation/opf";
+  rendererPackage: "@openpresentation/opf-render";
+}>;
+
+export declare const runtimePolicy: Readonly<{
+  hostedServiceInCriticalPath: false;
+  telemetry: false;
+  commercialSdkInCriticalPath: false;
+  requiredAiDependency: false;
+  requiredLibreOfficeDependency: false;
+  requiredNetworkCalls: false;
+  deterministicLocalExecution: true;
+}>;
+
+export type ImageResolverResult =
+  | string
+  | Uint8Array
+  | {
+      data?: string | Uint8Array;
+      path?: string;
+      mediaType?: string;
+    };
+
+export interface ImageResolverContext {
+  asset: unknown;
+  presentation: unknown;
+  path: string;
+}
+
+export interface ToPptxOptions {
+  baseDir?: string;
+  compressionLevel?: number;
+  imageResolver?: (src: string, context: ImageResolverContext) => ImageResolverResult | Promise<ImageResolverResult | null | undefined> | null | undefined;
+  seed?: number;
+  strictAssets?: boolean;
+  timestamp?: string;
+  zipDate?: string | number | Date;
+}
+
+export interface FromPptxOptions {
+  fallbackName?: string;
+  schema?: string;
+}
+
+export declare class OPFPptxError extends Error {
+  readonly code: string;
+  readonly details: Record<string, unknown>;
+  readonly issues?: unknown[];
+  readonly path?: string;
+  constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+
+export declare function toPptx(input: unknown, options?: ToPptxOptions): Promise<Uint8Array>;
+
+export declare function fromPptx(input: Uint8Array | ArrayBuffer, options?: FromPptxOptions): Promise<Record<string, unknown>>;