pptx-kit-preview 0.0.0 → 0.2.0

package/README.md

@@ -1,6 +1,103 @@
 # pptx-kit-preview
 
-Experimental preview renderer for [pptx-kit](https://github.com/baseballyama/pptx-kit): render slides to SVG (browser + Node) or rasterize to PNG in Node, with no browser binary.
+Preview renderer for [`pptx-kit`](https://github.com/baseballyama/pptx-kit).
+Turns a `pptx-kit` slide model into an **SVG** (browser + Node) or rasterizes
+it to a **PNG / RGBA image in Node — with no headless browser**.
 
-This `0.0.0` release is a name reservation. The real package ships shortly from
-[baseballyama/pptx-kit](https://github.com/baseballyama/pptx-kit) — watch the repo for the first release.
+> **Experimental (0.x).** This package lives in the `pptx-kit` monorepo and
+> also powers the docs-site playground and the fidelity harness. The renderer
+> is an _approximation_ of PowerPoint / LibreOffice output and is still
+> evolving; the API may change between minor versions, and `0.x` semver applies
+> (a minor bump may break). See [fidelity](#fidelity) below.
+
+## Why
+
+`pptx-kit` core does not render — by design. But "show me this deck" comes up
+constantly: a docs playground, a thumbnail service, a visual-diff test. The
+hard requirement is that rendering must work **in Node and rasterize to an
+image without spawning a browser**, so it fits CI and serverless. This package
+lays text out as pure SVG `<text>` (no `<foreignObject>`) and paints it with
+[resvg](https://github.com/yisibl/resvg-js), which has no browser dependency.
+
+## Entry points
+
+| Import                  | Runtime        | Use                                                 |
+| ----------------------- | -------------- | --------------------------------------------------- |
+| `pptx-kit-preview`      | browser + Node | `renderSlideToSvg` → an SVG string                  |
+| `pptx-kit-preview/node` | Node only      | `renderSlideToImage` / `renderSlideToRgba` → pixels |
+
+The browser entry pulls in **no** Node built-ins (no `node:fs`, resvg, or
+fontkit), so it bundles cleanly for the web.
+
+## Usage
+
+### SVG (browser or Node)
+
+```ts
+import { renderSlideToSvg } from 'pptx-kit-preview';
+import { loadPresentation, getSlides } from 'pptx-kit';
+
+const pres = await loadPresentation(bytes);
+const svg = renderSlideToSvg(pres, getSlides(pres)[0]);
+// → '<svg …>…</svg>'  (text laid out via <foreignObject> — the browser wraps it)
+```
+
+### PNG / RGBA (Node, no browser)
+
+```ts
+import { renderSlideToImage, renderSlideToRgba } from 'pptx-kit-preview/node';
+import { loadPresentationFile, getSlides } from 'pptx-kit/node';
+
+const pres = await loadPresentationFile('deck.pptx');
+const slide = getSlides(pres)[0];
+
+// PNG-encoded bytes:
+const png = renderSlideToImage(pres, slide, { width: 1280 });
+
+// Raw RGBA pixels (+ the same frame PNG-encoded), for SSIM / diffing:
+const { image, png: png2 } = renderSlideToRgba(pres, slide, { width: 1280 });
+// image: { width, height, data: Uint8Array }  // row-major RGBA
+```
+
+The Node path lays text out as pure `<text>` and measures it with a fontkit
+measurer over **bundled** metric-compatible fonts (Carlito ≈ Calibri, Caladea ≈
+Cambria, Liberation ≈ Arial/Times/Courier; OFL / Apache-2.0, see
+`fonts/LICENSES.md`). The measurer, resvg's font set, and the SVG family names
+all reference the same fonts, so wrap/positioning math agrees with the painted
+glyphs and the result is deterministic (no system fonts).
+
+## Fidelity
+
+This is a high-fidelity preview, not a spec-complete PowerPoint renderer.
+Preset and custom geometry, solid/gradient/pattern/image fills (including the
+placeholder layout/master cascade), strokes, rotation, effects (shadow, glow,
+soft edge, reflection), images with adjustments, charts (column, bar, line,
+area, pie, doughnut, scatter, radar, bubble), tables with per-run cell text,
+vertical and multi-column text in both text-layout modes, picture bullets, and
+template (layout/master) decoration all render. SmartArt, animations, 3D, and
+EMF/WMF fall back to labelled placeholders carrying a machine-readable marker
+(below). Per-slide closeness to a LibreOffice baseline is measured and gated
+in CI by the fidelity harness in the monorepo (`site/fidelity`) — mean
+fg-SSIM ≈ 0.78 across the corpus, with the residual gaps documented there.
+
+### Fallback markers
+
+When a shape cannot be rendered (unsupported format, missing bytes, or
+unrecognised content type), the renderer emits a labelled placeholder rectangle.
+The placeholder's top-level `<g>` element carries a `data-pptx-fallback`
+attribute so automated tooling can detect partial renders without string-parsing
+the label text:
+
+| Value            | Trigger                                                     |
+| ---------------- | ----------------------------------------------------------- |
+| `"image"`        | Image bytes missing (external link) or format not decodable |
+| `"chart"`        | Chart kind not modelled by this renderer                    |
+| `"graphicFrame"` | Graphic frame with no recognised content (SmartArt, etc.)   |
+| `"custGeom"`     | Shape uses custom geometry (`<a:custGeom>`)                 |
+
+Example: `svg.querySelectorAll('[data-pptx-fallback]')` lists every shape that
+did not fully render.
+
+## License
+
+MIT (code). Bundled fonts: OFL-1.1 / Apache-2.0 — see `fonts/LICENSES.md`.

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { PresentationData, SlideData } from 'pptx-kit';
+
+/** What a measurer needs to size one run. Pixels at 96 DPI; the caller has
+ *  already applied EMU→px, pt→px and the autofit fontScale. `family` is the
+ *  resolved internal family name (see `substituteFamily`), not a CSS list. */
+interface FontSpec {
+    readonly family: string;
+    readonly sizePx: number;
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly letterSpacingPx: number;
+}
+/** Advance width of `text` in px, plus optional vertical metrics. A real
+ *  measurer returns ascent/descent/lineGap so line height matches the font;
+ *  the heuristic returns width only and the engine falls back to a ratio. */
+interface MeasureResult {
+    readonly widthPx: number;
+    readonly ascentPx?: number;
+    readonly descentPx?: number;
+    readonly lineGapPx?: number;
+}
+type TextMeasurer = (text: string, spec: FontSpec) => MeasureResult;
+type TextLayoutMode = 'foreignObject' | 'svg';
+interface RenderSlideOptions {
+    /** Measurer used by the pure-SVG text path. Required when `textLayout` is
+     *  'svg'; ignored otherwise. */
+    readonly measureText?: TextMeasurer;
+    /** Which text path to use. Defaults to 'foreignObject' (the browser path)
+     *  so existing callers are unaffected; the harness opts into 'svg'. */
+    readonly textLayout?: TextLayoutMode;
+}
+declare const SANS = "Carlito";
+declare const SERIF = "Caladea";
+declare const ARIAL = "Liberation Sans";
+declare const TIMES = "Liberation Serif";
+declare const MONO = "Liberation Mono";
+declare const substituteFamily: (family: string | null | undefined) => string;
+declare const defaultMeasurer: TextMeasurer;
+
+declare const renderSlideSvg: (pres: PresentationData, slide: SlideData, opts?: RenderSlideOptions) => string;
+
+export { ARIAL, type FontSpec, MONO, type MeasureResult, type RenderSlideOptions, SANS, SERIF, TIMES, type TextLayoutMode, type TextMeasurer, defaultMeasurer, renderSlideSvg as renderSlideToSvg, substituteFamily };