@office-kit/pptx-preview 0.14.0 → 1.0.0

package/README.md

@@ -6,7 +6,7 @@ it to a **PNG / RGBA image in Node — with no headless browser**.
 
 > **Experimental (0.x).** This package lives in the `@office-kit/pptx` monorepo and
 > also powers the docs-site playground and the fidelity harness. The renderer
-> is an _approximation_ of PowerPoint / LibreOffice output and is still
+> is an _approximation_ of desktop presentation app / 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.
 
@@ -42,6 +42,12 @@ const svg = renderSlideToSvg(pres, getSlides(pres)[0]);
 // → '<svg …>…</svg>'  (text laid out via <foreignObject> — the browser wraps it)
 ```
 
+`renderSlideLayoutToSvg(pres, layout, { master })` draws what a slide master
+editor shows behind the placeholders: the layout's background and decorative
+shapes over its master's (the master's are left out when the layout hides
+background graphics), or with `master: true` the slide master's own background
+and shapes. Placeholders are not drawn.
+
 ### Underlines in custom HTML editors
 
 `textUnderlineStyle(underline, color)` returns inline CSS for a DrawingML
@@ -119,22 +125,25 @@ Options:
   wrapping is normal for body text; turn it on when auditing titles or labels
   meant to stay on one line.
 
-Accuracy: the bundled fonts are metric-compatible with the Office defaults, so
+Accuracy: the bundled fonts are metric-compatible with the common default fonts, so
 verdicts for Calibri / Cambria / Arial / Times / Courier decks match real glyph
 widths; for any other font (custom brand fonts, Japanese fonts), register the
 real files via `buildFontkitMeasurer({ fonts })` — a registered font is used
 both for runs that name it and as a glyph fallback for CJK text in runs that
-resolve to a Latin face. Line-break positions can differ from PowerPoint by a
+resolve to a Latin face. Line-break positions can differ from the reference desktop app by a
 few characters in edge cases (kinsoku, hyphenation), which is what the default
 1 px tolerance absorbs. Table cell text is not audited yet.
 
 ## Fidelity
 
-This is a high-fidelity preview, not a spec-complete PowerPoint renderer.
+This is a high-fidelity preview, not a spec-complete presentation 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,
+area, pie, doughnut, scatter, radar, bubble), tables with per-run cell text and
+every part of their table style (the 74 built-in table styles included:
+fills, translucent bands, borders, text, the Themed Styles' background, and
+the six style options; the background's shadow is not drawn),
 vertical and multi-column text in both text-layout modes, picture bullets, and
 template (layout/master) decoration all render. EMF pictures containing solid-filled
 line/Bézier paths, including rectangular and path clipping with copy semantics,

package/dist/{index-DUFPGYOf.d.ts → index-74n14k3Y.d.ts}

@@ -1,4 +1,4 @@
-import { BulletStyle, PresentationData, SlideData, SlideShapeData, TextFormat, getParagraphBullet, getParagraphIndent, getParagraphPropertiesEffective, getShapeBodyPrEffective, getShapeTextAutoFitParams, getShapeTextColumns, getShapeTextDirection } from "@office-kit/pptx";
+import { BulletStyle, PresentationData, SlideData, SlideLayoutData, SlideShapeData, TextFormat, getParagraphBullet, getParagraphIndent, getParagraphPropertiesEffective, getShapeBodyPrEffective, getShapeTextAutoFitParams, getShapeTextColumns, getShapeTextDirection } from "@office-kit/pptx";
 
 //#region src/text-layout.d.ts
 /** What a measurer needs to size one run. Pixels at 96 DPI; the caller has
@@ -42,6 +42,9 @@ interface RenderSlideOptions {
    *  Bodies with custom tab stops use SVG positioning in either mode, since
    *  CSS cannot represent their alignment. The harness opts into 'svg'. */
   readonly textLayout?: TextLayoutMode;
+  /** `false` paints only the slide's own shapes on a transparent surface:
+   *  no background fill and no master or layout graphics. Defaults to `true`. */
+  readonly background?: boolean;
 }
 declare const SANS = "Carlito";
 declare const SERIF = "Caladea";
@@ -69,6 +72,17 @@ declare const renderTextEffectsSvg: (pres: PresentationData, slide: SlideData, s
   };
 }) => string;
 declare const renderSlideSvg: (pres: PresentationData, slide: SlideData, opts?: RenderSlideOptions) => string;
+/**
+ * Draws a slide layout — or, with `master`, its slide master — the way
+ * the reference desktop app's Slide Master view shows it behind the placeholders: the
+ * background and the decorative (non-placeholder) shapes of the master and,
+ * for a layout, of the layout itself. A layout that hides background graphics
+ * leaves the master's shapes out. Placeholders are not drawn; an editor draws
+ * them with their prompt text over this.
+ */
+declare const renderSlideLayoutSvg: (pres: PresentationData, layout: SlideLayoutData, opts?: RenderSlideOptions & {
+  readonly master?: boolean;
+}) => string;
 //#endregion
 //#region src/audit.d.ts
 interface IssueBase {
@@ -96,7 +110,7 @@ interface AuditTextLayoutOptions {
    *  `@office-kit/pptx-preview/node` for real glyph metrics. */
   readonly measureText?: TextMeasurer;
   /** Overflow at or below this many px (96 DPI) is ignored. Default 1 —
-   *  measurement and PowerPoint disagree by sub-pixel amounts routinely. */
+   *  measurement and the reference desktop app disagree by sub-pixel amounts routinely. */
   readonly tolerancePx?: number;
   /** Also report paragraphs that wrap onto more lines than their explicit
    *  breaks author (段落ち). Off by default: wrapping is normal for body
@@ -120,6 +134,16 @@ declare const paragraphNumberLabels: (paraData: ReadonlyArray<{
   level: number;
 }>) => Array<string | null>;
 //#endregion
+//#region src/decimal-separator.d.ts
+/**
+ * The character a decimal tab stop aligns on for a run's language
+ * (`<a:rPr lang>`): `,` for `de-DE`, `.` for `en-US`. Runs without a
+ * language, or with one Intl does not know, align on `.`. The reference desktop app on Mac
+ * uses the run language too, not the UI or system locale (native capture
+ * 2026-10-07: Set Proofing Language to German moved alignment to `,`).
+ */
+declare function decimalSeparatorOf(lang: string | null | undefined): string;
+//#endregion
 //#region src/text-body-rect.d.ts
 /** A text rectangle as fractions of the shape's extent. */
 interface TextRectFractions {
@@ -145,7 +169,7 @@ declare function shapeTextRect(shape: SlideShapeData): TextRectFractions | null;
  * {@link shapeTextRect}, or `null` for the whole box) placed in `bounds`, less
  * the body insets. All coordinates and margins must use the same unit
  * (normally EMU). When margins collapse a region, the region is kept without
- * them, as PowerPoint does.
+ * them, as the reference desktop app does.
  */
 declare function resolveTextBodyRect(bounds: {
   x: number;
@@ -175,8 +199,8 @@ interface VerticalTextStyle {
 }
 /**
  * `<a:bodyPr vert="…"/>` as CSS. `writing-mode` is the right primitive for
- * the East-Asian and Mongolian cases, and `text-orientation` for the WordArt
- * ones, which stack upright glyphs. `vert270` reads bottom-to-top, which no
+ * the East-Asian and Mongolian cases, and `text-orientation` for the
+ * `wordArtVert` ones, which stack upright glyphs. `vert270` reads bottom-to-top, which no
  * writing-mode expresses on its own — hence the half turn. Its columns still
  * follow the OOXML vertical-rl progression before that half turn; using
  * vertical-lr here reverses the column order relative to the SVG renderer.
@@ -212,7 +236,7 @@ interface ShapeAutoFitScaleOptions {
  *
  * `1` for a shape with no `<a:normAutofit>`: `<a:noAutofit>` overflows and
  * `<a:spAutoFit>` grows the box instead, so neither shrinks the text. A shape
- * with a baked `fontScale` reports that, unchanged — it is what PowerPoint
+ * with a baked `fontScale` reports that, unchanged — it is what the reference desktop app
  * itself applied.
  */
 declare function shapeAutoFitScale(pres: PresentationData, shape: SlideShapeData, options?: ShapeAutoFitScaleOptions): number;
@@ -232,5 +256,5 @@ declare function shapeTextAnchorOffset(pres: PresentationData, shape: SlideShape
  */
 declare function textUnderlineStyle(underline: TextFormat['underline'], color: string, includeDecorationColor?: boolean): string;
 //#endregion
-export { SERIF as C, defaultMeasurer as D, TextMeasurer as E, substituteFamily as O, SANS as S, TextLayoutMode as T, ARIAL as _, VerticalTextStyle as a, MeasureResult as b, TextRectFractions as c, paragraphNumberLabels as d, AuditTextLayoutOptions as f, renderTextEffectsSvg as g, renderSlideSvg as h, shapeTextAnchorOffset as i, resolveTextBodyRect as l, auditTextLayout as m, ShapeAutoFitScaleOptions as n, textColumnsStyle as o, TextAuditIssue as p, shapeAutoFitScale as r, verticalTextStyle as s, textUnderlineStyle as t, shapeTextRect as u, FontSpec as v, TIMES as w, RenderSlideOptions as x, MONO as y };
-//# sourceMappingURL=index-DUFPGYOf.d.ts.map
+export { substituteFamily as A, RenderSlideOptions as C, TextLayoutMode as D, TIMES as E, TextMeasurer as O, MeasureResult as S, SERIF as T, renderSlideSvg as _, VerticalTextStyle as a, FontSpec as b, TextRectFractions as c, decimalSeparatorOf as d, paragraphNumberLabels as f, renderSlideLayoutSvg as g, auditTextLayout as h, shapeTextAnchorOffset as i, defaultMeasurer as k, resolveTextBodyRect as l, TextAuditIssue as m, ShapeAutoFitScaleOptions as n, textColumnsStyle as o, AuditTextLayoutOptions as p, shapeAutoFitScale as r, verticalTextStyle as s, textUnderlineStyle as t, shapeTextRect as u, renderTextEffectsSvg as v, SANS as w, MONO as x, ARIAL as y };
+//# sourceMappingURL=index-74n14k3Y.d.ts.map

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { C as SERIF, D as defaultMeasurer, E as TextMeasurer, O as substituteFamily, S as SANS, T as TextLayoutMode, _ as ARIAL, a as VerticalTextStyle, b as MeasureResult, c as TextRectFractions, d as paragraphNumberLabels, f as AuditTextLayoutOptions, g as renderTextEffectsSvg, h as renderSlideSvg, i as shapeTextAnchorOffset, l as resolveTextBodyRect, m as auditTextLayout, n as ShapeAutoFitScaleOptions, o as textColumnsStyle, p as TextAuditIssue, r as shapeAutoFitScale, s as verticalTextStyle, t as textUnderlineStyle, u as shapeTextRect, v as FontSpec, w as TIMES, x as RenderSlideOptions, y as MONO } from "./index-DUFPGYOf.js";
-export { ARIAL, type AuditTextLayoutOptions, type FontSpec, MONO, type MeasureResult, type RenderSlideOptions, SANS, SERIF, type ShapeAutoFitScaleOptions, TIMES, type TextAuditIssue, type TextLayoutMode, type TextMeasurer, type TextRectFractions, type VerticalTextStyle, auditTextLayout, defaultMeasurer, paragraphNumberLabels, renderSlideSvg as renderSlideToSvg, renderTextEffectsSvg, resolveTextBodyRect, shapeAutoFitScale, shapeTextAnchorOffset, shapeTextRect, substituteFamily, textColumnsStyle, textUnderlineStyle, verticalTextStyle };
+import { A as substituteFamily, C as RenderSlideOptions, D as TextLayoutMode, E as TIMES, O as TextMeasurer, S as MeasureResult, T as SERIF, _ as renderSlideSvg, a as VerticalTextStyle, b as FontSpec, c as TextRectFractions, d as decimalSeparatorOf, f as paragraphNumberLabels, g as renderSlideLayoutSvg, h as auditTextLayout, i as shapeTextAnchorOffset, k as defaultMeasurer, l as resolveTextBodyRect, m as TextAuditIssue, n as ShapeAutoFitScaleOptions, o as textColumnsStyle, p as AuditTextLayoutOptions, r as shapeAutoFitScale, s as verticalTextStyle, t as textUnderlineStyle, u as shapeTextRect, v as renderTextEffectsSvg, w as SANS, x as MONO, y as ARIAL } from "./index-74n14k3Y.js";
+export { ARIAL, type AuditTextLayoutOptions, type FontSpec, MONO, type MeasureResult, type RenderSlideOptions, SANS, SERIF, type ShapeAutoFitScaleOptions, TIMES, type TextAuditIssue, type TextLayoutMode, type TextMeasurer, type TextRectFractions, type VerticalTextStyle, auditTextLayout, decimalSeparatorOf, defaultMeasurer, paragraphNumberLabels, renderSlideLayoutSvg as renderSlideLayoutToSvg, renderSlideSvg as renderSlideToSvg, renderTextEffectsSvg, resolveTextBodyRect, shapeAutoFitScale, shapeTextAnchorOffset, shapeTextRect, substituteFamily, textColumnsStyle, textUnderlineStyle, verticalTextStyle };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { _ as textColumnsStyle, a as renderTextEffectsSvg, b as shapeTextRect, c as MONO, d as TIMES, f as defaultMeasurer, g as textUnderlineStyle, h as paragraphNumberLabels, i as renderSlideSvg, l as SANS, m as substituteFamily, n as shapeTextAnchorOffset, o as ARIAL, r as auditTextLayout, t as shapeAutoFitScale, u as SERIF, v as verticalTextStyle, y as resolveTextBodyRect } from "./src-Bwmf324Z.js";
-export { ARIAL, MONO, SANS, SERIF, TIMES, auditTextLayout, defaultMeasurer, paragraphNumberLabels, renderSlideSvg as renderSlideToSvg, renderTextEffectsSvg, resolveTextBodyRect, shapeAutoFitScale, shapeTextAnchorOffset, shapeTextRect, substituteFamily, textColumnsStyle, textUnderlineStyle, verticalTextStyle };
+import { S as shapeTextRect, _ as paragraphNumberLabels, a as renderSlideSvg, b as verticalTextStyle, d as SERIF, f as TIMES, g as decimalSeparatorOf, h as substituteFamily, i as renderSlideLayoutSvg, l as MONO, n as shapeTextAnchorOffset, o as renderTextEffectsSvg, p as defaultMeasurer, r as auditTextLayout, s as ARIAL, t as shapeAutoFitScale, u as SANS, v as textUnderlineStyle, x as resolveTextBodyRect, y as textColumnsStyle } from "./src-pb3C61GD.js";
+export { ARIAL, MONO, SANS, SERIF, TIMES, auditTextLayout, decimalSeparatorOf, defaultMeasurer, paragraphNumberLabels, renderSlideLayoutSvg as renderSlideLayoutToSvg, renderSlideSvg as renderSlideToSvg, renderTextEffectsSvg, resolveTextBodyRect, shapeAutoFitScale, shapeTextAnchorOffset, shapeTextRect, substituteFamily, textColumnsStyle, textUnderlineStyle, verticalTextStyle };

package/dist/node.d.ts

@@ -1,4 +1,4 @@
-import { C as SERIF, D as defaultMeasurer, E as TextMeasurer, O as substituteFamily, S as SANS, T as TextLayoutMode, _ as ARIAL, a as VerticalTextStyle, b as MeasureResult, c as TextRectFractions, d as paragraphNumberLabels, f as AuditTextLayoutOptions, g as renderTextEffectsSvg, h as renderSlideSvg, i as shapeTextAnchorOffset, l as resolveTextBodyRect, m as auditTextLayout, n as ShapeAutoFitScaleOptions, o as textColumnsStyle, p as TextAuditIssue, r as shapeAutoFitScale, s as verticalTextStyle, t as textUnderlineStyle, u as shapeTextRect, v as FontSpec, w as TIMES, x as RenderSlideOptions, y as MONO } from "./index-DUFPGYOf.js";
+import { A as substituteFamily, C as RenderSlideOptions, D as TextLayoutMode, E as TIMES, O as TextMeasurer, S as MeasureResult, T as SERIF, _ as renderSlideSvg, a as VerticalTextStyle, b as FontSpec, c as TextRectFractions, d as decimalSeparatorOf, f as paragraphNumberLabels, g as renderSlideLayoutSvg, h as auditTextLayout, i as shapeTextAnchorOffset, k as defaultMeasurer, l as resolveTextBodyRect, m as TextAuditIssue, n as ShapeAutoFitScaleOptions, o as textColumnsStyle, p as AuditTextLayoutOptions, r as shapeAutoFitScale, s as verticalTextStyle, t as textUnderlineStyle, u as shapeTextRect, v as renderTextEffectsSvg, w as SANS, x as MONO, y as ARIAL } from "./index-74n14k3Y.js";
 import { PresentationData, SlideData } from "@office-kit/pptx";
 
 //#region src/measure.d.ts
@@ -73,5 +73,5 @@ declare const renderSlideToRgba: (pres: PresentationData, slide: SlideData, opts
   readonly png: Uint8Array;
 };
 //#endregion
-export { ARIAL, type AuditTextLayoutOptions, FONT_DIR, FONT_FILES, type FontSpec, type FontkitMeasurerOptions, MONO, type MeasureResult, type RegisteredFont, RenderImageOptions, type RenderSlideOptions, RgbaImage, SANS, SERIF, type ShapeAutoFitScaleOptions, TIMES, type TextAuditIssue, type TextLayoutMode, type TextMeasurer, type TextRectFractions, type VerticalTextStyle, auditTextLayout, buildFontkitMeasurer, defaultMeasurer, paragraphNumberLabels, renderSlideToImage, renderSlideToRgba, renderSlideSvg as renderSlideToSvg, renderTextEffectsSvg, resolveTextBodyRect, shapeAutoFitScale, shapeTextAnchorOffset, shapeTextRect, substituteFamily, textColumnsStyle, textUnderlineStyle, verticalTextStyle };
+export { ARIAL, type AuditTextLayoutOptions, FONT_DIR, FONT_FILES, type FontSpec, type FontkitMeasurerOptions, MONO, type MeasureResult, type RegisteredFont, RenderImageOptions, type RenderSlideOptions, RgbaImage, SANS, SERIF, type ShapeAutoFitScaleOptions, TIMES, type TextAuditIssue, type TextLayoutMode, type TextMeasurer, type TextRectFractions, type VerticalTextStyle, auditTextLayout, buildFontkitMeasurer, decimalSeparatorOf, defaultMeasurer, paragraphNumberLabels, renderSlideLayoutSvg as renderSlideLayoutToSvg, renderSlideToImage, renderSlideToRgba, renderSlideSvg as renderSlideToSvg, renderTextEffectsSvg, resolveTextBodyRect, shapeAutoFitScale, shapeTextAnchorOffset, shapeTextRect, substituteFamily, textColumnsStyle, textUnderlineStyle, verticalTextStyle };
 //# sourceMappingURL=node.d.ts.map

package/dist/node.js

@@ -1,4 +1,4 @@
-import { _ as textColumnsStyle, a as renderTextEffectsSvg, b as shapeTextRect, c as MONO, d as TIMES, f as defaultMeasurer, g as textUnderlineStyle, h as paragraphNumberLabels, i as renderSlideSvg, l as SANS, m as substituteFamily, n as shapeTextAnchorOffset, o as ARIAL, p as isCjk, r as auditTextLayout, s as AVG_GLYPH_W_RATIO, t as shapeAutoFitScale, u as SERIF, v as verticalTextStyle, y as resolveTextBodyRect } from "./src-Bwmf324Z.js";
+import { S as shapeTextRect, _ as paragraphNumberLabels, a as renderSlideSvg, b as verticalTextStyle, c as AVG_GLYPH_W_RATIO, d as SERIF, f as TIMES, g as decimalSeparatorOf, h as substituteFamily, i as renderSlideLayoutSvg, l as MONO, m as isCjk, n as shapeTextAnchorOffset, o as renderTextEffectsSvg, p as defaultMeasurer, r as auditTextLayout, s as ARIAL, t as shapeAutoFitScale, u as SANS, v as textUnderlineStyle, x as resolveTextBodyRect, y as textColumnsStyle } from "./src-pb3C61GD.js";
 import { getSlideSize } from "@office-kit/pptx";
 import { Resvg } from "@resvg/resvg-js";
 import * as fontkit from "fontkit";
@@ -195,6 +195,6 @@ const renderSlideToRgba = (pres, slide, opts = {}) => {
 	};
 };
 //#endregion
-export { ARIAL, FONT_DIR, FONT_FILES, MONO, SANS, SERIF, TIMES, auditTextLayout, buildFontkitMeasurer, defaultMeasurer, paragraphNumberLabels, renderSlideToImage, renderSlideToRgba, renderSlideSvg as renderSlideToSvg, renderTextEffectsSvg, resolveTextBodyRect, shapeAutoFitScale, shapeTextAnchorOffset, shapeTextRect, substituteFamily, textColumnsStyle, textUnderlineStyle, verticalTextStyle };
+export { ARIAL, FONT_DIR, FONT_FILES, MONO, SANS, SERIF, TIMES, auditTextLayout, buildFontkitMeasurer, decimalSeparatorOf, defaultMeasurer, paragraphNumberLabels, renderSlideLayoutSvg as renderSlideLayoutToSvg, renderSlideToImage, renderSlideToRgba, renderSlideSvg as renderSlideToSvg, renderTextEffectsSvg, resolveTextBodyRect, shapeAutoFitScale, shapeTextAnchorOffset, shapeTextRect, substituteFamily, textColumnsStyle, textUnderlineStyle, verticalTextStyle };
 
 //# sourceMappingURL=node.js.map