pptx-react-viewer 3.1.5 → 3.2.0

package/dist/index.js

@@ -1,176 +1,176 @@
 'use strict';
 
-var chunkZPF4L6SD_js = require('./chunk-ZPF4L6SD.js');
-require('./chunk-LGVNUG3G.js');
-var chunkLXYDXLKZ_js = require('./chunk-LXYDXLKZ.js');
-var chunkT2QG2HD5_js = require('./chunk-T2QG2HD5.js');
-var chunkYDEEINER_js = require('./chunk-YDEEINER.js');
-var chunkSWRY3SI5_js = require('./chunk-SWRY3SI5.js');
+var chunkRRAL4Y7V_js = require('./chunk-RRAL4Y7V.js');
+require('./chunk-Q52HT4EZ.js');
+var chunkARQGUUYU_js = require('./chunk-ARQGUUYU.js');
+var chunkB6UIVRFA_js = require('./chunk-B6UIVRFA.js');
+var chunkFJDZ7AEE_js = require('./chunk-FJDZ7AEE.js');
+var chunkALO4ZOHQ_js = require('./chunk-ALO4ZOHQ.js');
 require('./chunk-4VNS5WPM.js');
 
 
 
 Object.defineProperty(exports, "PowerPointViewer", {
   enumerable: true,
-  get: function () { return chunkZPF4L6SD_js.PowerPointViewer; }
+  get: function () { return chunkRRAL4Y7V_js.PowerPointViewer; }
 });
 Object.defineProperty(exports, "SlideCanvas", {
   enumerable: true,
-  get: function () { return chunkZPF4L6SD_js.SlideCanvas; }
+  get: function () { return chunkRRAL4Y7V_js.SlideCanvas; }
 });
 Object.defineProperty(exports, "SlideTemplateGalleryDialog", {
   enumerable: true,
-  get: function () { return chunkZPF4L6SD_js.SlideTemplateGalleryDialog; }
+  get: function () { return chunkRRAL4Y7V_js.SlideTemplateGalleryDialog; }
 });
 Object.defineProperty(exports, "SlideTemplatePreview", {
   enumerable: true,
-  get: function () { return chunkZPF4L6SD_js.SlideTemplatePreview; }
+  get: function () { return chunkRRAL4Y7V_js.SlideTemplatePreview; }
 });
 Object.defineProperty(exports, "Toolbar", {
   enumerable: true,
-  get: function () { return chunkZPF4L6SD_js.Toolbar; }
+  get: function () { return chunkRRAL4Y7V_js.Toolbar; }
 });
 Object.defineProperty(exports, "ViewerThemeProvider", {
   enumerable: true,
-  get: function () { return chunkZPF4L6SD_js.ViewerThemeProvider; }
+  get: function () { return chunkRRAL4Y7V_js.ViewerThemeProvider; }
 });
 Object.defineProperty(exports, "useViewerTheme", {
   enumerable: true,
-  get: function () { return chunkZPF4L6SD_js.useViewerTheme; }
+  get: function () { return chunkRRAL4Y7V_js.useViewerTheme; }
 });
 Object.defineProperty(exports, "renderToCanvas", {
   enumerable: true,
-  get: function () { return chunkLXYDXLKZ_js.renderToCanvas; }
+  get: function () { return chunkARQGUUYU_js.renderToCanvas; }
 });
 Object.defineProperty(exports, "useViewerBuildingBlocks", {
   enumerable: true,
-  get: function () { return chunkLXYDXLKZ_js.useViewerBuildingBlocks; }
+  get: function () { return chunkARQGUUYU_js.useViewerBuildingBlocks; }
 });
 Object.defineProperty(exports, "getAnimationInitialStyle", {
   enumerable: true,
-  get: function () { return chunkT2QG2HD5_js.getAnimationInitialStyle; }
+  get: function () { return chunkB6UIVRFA_js.getAnimationInitialStyle; }
 });
 Object.defineProperty(exports, "AVATAR_COLOR_SWATCHES", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.AVATAR_COLOR_SWATCHES; }
+  get: function () { return chunkFJDZ7AEE_js.AVATAR_COLOR_SWATCHES; }
 });
 Object.defineProperty(exports, "DEFAULT_VIEWER_PROFILE", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.DEFAULT_VIEWER_PROFILE; }
+  get: function () { return chunkFJDZ7AEE_js.DEFAULT_VIEWER_PROFILE; }
 });
 Object.defineProperty(exports, "PPTX_OPEN_ACCEPT", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.PPTX_OPEN_ACCEPT; }
+  get: function () { return chunkFJDZ7AEE_js.PPTX_OPEN_ACCEPT; }
 });
 Object.defineProperty(exports, "PRESENTATION_OPEN_EXTENSIONS", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.PRESENTATION_OPEN_EXTENSIONS; }
+  get: function () { return chunkFJDZ7AEE_js.PRESENTATION_OPEN_EXTENSIONS; }
 });
 Object.defineProperty(exports, "SLIDE_TEMPLATES", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.SLIDE_TEMPLATES; }
+  get: function () { return chunkFJDZ7AEE_js.SLIDE_TEMPLATES; }
 });
 Object.defineProperty(exports, "THEME_CATALOG", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.THEME_CATALOG; }
+  get: function () { return chunkFJDZ7AEE_js.THEME_CATALOG; }
 });
 Object.defineProperty(exports, "VIEWER_PREFS_STORAGE_KEY", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.VIEWER_PREFS_STORAGE_KEY; }
+  get: function () { return chunkFJDZ7AEE_js.VIEWER_PREFS_STORAGE_KEY; }
 });
 Object.defineProperty(exports, "buildSlideTemplateContent", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.buildSlideTemplateContent; }
+  get: function () { return chunkFJDZ7AEE_js.buildSlideTemplateContent; }
 });
 Object.defineProperty(exports, "buildSlideTemplateSlide", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.buildSlideTemplateSlide; }
+  get: function () { return chunkFJDZ7AEE_js.buildSlideTemplateSlide; }
 });
 Object.defineProperty(exports, "clearAllLocalViewerData", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.clearAllLocalViewerData; }
+  get: function () { return chunkFJDZ7AEE_js.clearAllLocalViewerData; }
 });
 Object.defineProperty(exports, "clearStoredViewerPrefs", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.clearStoredViewerPrefs; }
+  get: function () { return chunkFJDZ7AEE_js.clearStoredViewerPrefs; }
 });
 Object.defineProperty(exports, "defaultCssVars", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.defaultCssVars; }
+  get: function () { return chunkFJDZ7AEE_js.defaultCssVars; }
 });
 Object.defineProperty(exports, "defaultRadius", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.defaultRadius; }
+  get: function () { return chunkFJDZ7AEE_js.defaultRadius; }
 });
 Object.defineProperty(exports, "defaultThemeColors", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.defaultThemeColors; }
+  get: function () { return chunkFJDZ7AEE_js.defaultThemeColors; }
 });
 Object.defineProperty(exports, "getLocalStorageUsageSummary", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.getLocalStorageUsageSummary; }
+  get: function () { return chunkFJDZ7AEE_js.getLocalStorageUsageSummary; }
 });
 Object.defineProperty(exports, "isLegacyBinaryPresentation", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.isLegacyBinaryPresentation; }
+  get: function () { return chunkFJDZ7AEE_js.isLegacyBinaryPresentation; }
 });
 Object.defineProperty(exports, "isSupportedPresentationFile", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.isSupportedPresentationFile; }
+  get: function () { return chunkFJDZ7AEE_js.isSupportedPresentationFile; }
 });
 Object.defineProperty(exports, "presentationBaseName", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.presentationBaseName; }
+  get: function () { return chunkFJDZ7AEE_js.presentationBaseName; }
 });
 Object.defineProperty(exports, "readStoredViewerPrefs", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.readStoredViewerPrefs; }
+  get: function () { return chunkFJDZ7AEE_js.readStoredViewerPrefs; }
 });
 Object.defineProperty(exports, "resolveProfileInitial", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.resolveProfileInitial; }
+  get: function () { return chunkFJDZ7AEE_js.resolveProfileInitial; }
 });
 Object.defineProperty(exports, "resolveThemeCatalogEntry", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.resolveThemeCatalogEntry; }
+  get: function () { return chunkFJDZ7AEE_js.resolveThemeCatalogEntry; }
 });
 Object.defineProperty(exports, "saveViewerProfile", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.saveViewerProfile; }
+  get: function () { return chunkFJDZ7AEE_js.saveViewerProfile; }
 });
 Object.defineProperty(exports, "savedPresentationFileName", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.savedPresentationFileName; }
+  get: function () { return chunkFJDZ7AEE_js.savedPresentationFileName; }
 });
 Object.defineProperty(exports, "themeToCssVars", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.themeToCssVars; }
+  get: function () { return chunkFJDZ7AEE_js.themeToCssVars; }
 });
 Object.defineProperty(exports, "vermilionDarkColors", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.vermilionDarkColors; }
+  get: function () { return chunkFJDZ7AEE_js.vermilionDarkColors; }
 });
 Object.defineProperty(exports, "vermilionDarkTheme", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.vermilionDarkTheme; }
+  get: function () { return chunkFJDZ7AEE_js.vermilionDarkTheme; }
 });
 Object.defineProperty(exports, "vermilionLightColors", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.vermilionLightColors; }
+  get: function () { return chunkFJDZ7AEE_js.vermilionLightColors; }
 });
 Object.defineProperty(exports, "vermilionLightTheme", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.vermilionLightTheme; }
+  get: function () { return chunkFJDZ7AEE_js.vermilionLightTheme; }
 });
 Object.defineProperty(exports, "vermilionRadius", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.vermilionRadius; }
+  get: function () { return chunkFJDZ7AEE_js.vermilionRadius; }
 });
 Object.defineProperty(exports, "writeStoredViewerPrefs", {
   enumerable: true,
-  get: function () { return chunkYDEEINER_js.writeStoredViewerPrefs; }
+  get: function () { return chunkFJDZ7AEE_js.writeStoredViewerPrefs; }
 });
 Object.defineProperty(exports, "LOCALE_CATALOG", {
   enumerable: true,
-  get: function () { return chunkSWRY3SI5_js.LOCALE_CATALOG; }
+  get: function () { return chunkALO4ZOHQ_js.LOCALE_CATALOG; }
 });

package/dist/index.mjs

@@ -1,7 +1,7 @@
-export { PowerPointViewer, SlideCanvas, SlideTemplateGalleryDialog, SlideTemplatePreview, Toolbar, ViewerThemeProvider, useViewerTheme } from './chunk-P3VXXUZM.mjs';
-import './chunk-QOLYY7E3.mjs';
-export { renderToCanvas, useViewerBuildingBlocks } from './chunk-A2UAUSJM.mjs';
-export { getAnimationInitialStyle } from './chunk-BPWSJLLG.mjs';
-export { AVATAR_COLOR_SWATCHES, DEFAULT_VIEWER_PROFILE, PPTX_OPEN_ACCEPT, PRESENTATION_OPEN_EXTENSIONS, SLIDE_TEMPLATES, THEME_CATALOG, VIEWER_PREFS_STORAGE_KEY, buildSlideTemplateContent, buildSlideTemplateSlide, clearAllLocalViewerData, clearStoredViewerPrefs, defaultCssVars, defaultRadius, defaultThemeColors, getLocalStorageUsageSummary, isLegacyBinaryPresentation, isSupportedPresentationFile, presentationBaseName, readStoredViewerPrefs, resolveProfileInitial, resolveThemeCatalogEntry, saveViewerProfile, savedPresentationFileName, themeToCssVars, vermilionDarkColors, vermilionDarkTheme, vermilionLightColors, vermilionLightTheme, vermilionRadius, writeStoredViewerPrefs } from './chunk-XIHK52SB.mjs';
-export { LOCALE_CATALOG } from './chunk-ARJE3V6V.mjs';
+export { PowerPointViewer, SlideCanvas, SlideTemplateGalleryDialog, SlideTemplatePreview, Toolbar, ViewerThemeProvider, useViewerTheme } from './chunk-PPNXPEEZ.mjs';
+import './chunk-RX6FE24O.mjs';
+export { renderToCanvas, useViewerBuildingBlocks } from './chunk-UHR7EYFM.mjs';
+export { getAnimationInitialStyle } from './chunk-FMEEIS6L.mjs';
+export { AVATAR_COLOR_SWATCHES, DEFAULT_VIEWER_PROFILE, PPTX_OPEN_ACCEPT, PRESENTATION_OPEN_EXTENSIONS, SLIDE_TEMPLATES, THEME_CATALOG, VIEWER_PREFS_STORAGE_KEY, buildSlideTemplateContent, buildSlideTemplateSlide, clearAllLocalViewerData, clearStoredViewerPrefs, defaultCssVars, defaultRadius, defaultThemeColors, getLocalStorageUsageSummary, isLegacyBinaryPresentation, isSupportedPresentationFile, presentationBaseName, readStoredViewerPrefs, resolveProfileInitial, resolveThemeCatalogEntry, saveViewerProfile, savedPresentationFileName, themeToCssVars, vermilionDarkColors, vermilionDarkTheme, vermilionLightColors, vermilionLightTheme, vermilionRadius, writeStoredViewerPrefs } from './chunk-G7UBIKAG.mjs';
+export { LOCALE_CATALOG } from './chunk-RHSA5BW5.mjs';
 import './chunk-XGB3TDIC.mjs';

package/dist/internals.d.ts

@@ -221,6 +221,12 @@ interface PptxShapeLocks {
    * `a:spLocks` / `a:picLocks` / `a:cxnSpLocks` / `a:grpSpLocks`.
    */
   noDrilldown?: boolean;
+  /**
+   * `a:picLocks/@noCrop`: forbids cropping the picture. Declared ONLY by
+   * `CT_PictureLocking`, so it is written for pictures (and media authored as
+   * a `p:pic`) and never onto the other lock elements.
+   */
+  noCrop?: boolean;
   /**
    * Text-box flag from `p:cNvSpPr/@txBox`. Not a lock in the strict sense,
    * but it lives on the same non-visual-properties node as `a:spLocks`, so
@@ -2162,13 +2168,32 @@ interface PlaceholderTextLevelStyle {
   bulletSizePercent?: number;
   /** Bullet colour from `a:buClr` as hex string. */
   bulletColor?: string;
+  /**
+   * The colour-choice node inside `a:buClr` this level's {@link bulletColor}
+   * resolved from (`a:schemeClr` / `a:sysClr` / `a:prstClr` / `a:srgbClr`,
+   * transforms included), mirroring `BulletInfo.colorXml`. Re-emitted
+   * verbatim on save so a themed bullet is not downgraded to a literal
+   * `a:srgbClr`. Absent when the level declares no bullet colour.
+   */
+  bulletColorXml?: XmlObject;
   /** Bullet size in points from `a:buSzPts`. */
   bulletSizePts?: number;
   /** True when `a:buNone` is present at this level. */
   bulletNone?: boolean;
   marginLeft?: number;
+  /** Paragraph right margin in px (from `@_marR` EMU). */
+  marginRight?: number;
   indent?: number;
+  /**
+   * Paragraph alignment as a `TextStyle['align']` token (`left`, `center`,
+   * `right`, `justify`, `justLow`, `dist`, `thaiDist`), never the raw OOXML
+   * `@algn` value.
+   */
   alignment?: string;
+  /** Right-to-left paragraph direction (`@rtl`). */
+  rtl?: boolean;
+  /** Tab stops from `a:tabLst/a:tab` (positions in px). */
+  tabStops?: TextStyle['tabStops'];
   lineSpacing?: number;
   lineSpacingExactPt?: number;
   spaceBefore?: number;
@@ -2394,6 +2419,20 @@ type PptxChartType = 'bar' | 'line' | 'pie' | 'ofPie' | 'doughnut' | 'area' | 's
  * ```
  */
 type PptxChartBarDirection = 'col' | 'bar';
+/**
+ * 3-D bar/column shape (OOXML `ST_Shape`, `c:bar3DChart/c:shape/@val` or a
+ * per-series `c:ser/c:shape` override). `coneToMax` / `pyramidToMax` scale
+ * the cone/pyramid so it reaches full height at the value axis maximum,
+ * appearing truncated below it; the plain `cone`/`pyramid` always come to a
+ * full point at the bar's own value.
+ *
+ * @example
+ * ```ts
+ * const shape: PptxBar3DShape = "cylinder";
+ * // => "cylinder", one of: "box" | "cone" | "coneToMax" | "cylinder" | "pyramid" | "pyramidToMax"
+ * ```
+ */
+type PptxBar3DShape = 'box' | 'cone' | 'coneToMax' | 'cylinder' | 'pyramid' | 'pyramidToMax';
 /**
  * Supported trendline regression types.
  *
@@ -2822,6 +2861,12 @@ interface PptxChartSeries {
    * series.
    */
   seriesChartType?: PptxChartType;
+  /**
+   * Per-series 3-D bar/column shape override (`c:ser/c:shape`), legal only
+   * inside a bar3D chart-type container. Overrides {@link PptxChartData.barShape}
+   * for this series alone.
+   */
+  shape?: PptxBar3DShape;
   boxWhiskerOptions?: PptxChartBoxWhiskerOptions;
   histogramOptions?: PptxChartHistogramOptions;
   waterfallOptions?: PptxChartWaterfallOptions;
@@ -3123,6 +3168,28 @@ interface PptxChartData {
    * default), so only horizontal bar charts need to carry the field.
    */
   barDirection?: PptxChartBarDirection;
+  /**
+   * 3-D bar/column shape (`c:bar3DChart/c:shape/@val`). Bar3D only; a plain
+   * bar chart has no `c:shape` element. A per-series `c:ser/c:shape`
+   * ({@link PptxChartSeries.shape}) overrides this for that series.
+   */
+  barShape?: PptxBar3DShape;
+  /**
+   * Radar chart drawing style (`c:radarChart/c:radarStyle/@val`). `standard`
+   * draws an outline only, `marker` adds markers at each vertex (PowerPoint's
+   * own default for every radar chart it authors), and `filled` paints the
+   * enclosed polygon with the series fill and omits markers. Radar only.
+   */
+  radarStyle?: 'standard' | 'marker' | 'filled';
+  /**
+   * Whether a surface chart renders as a wireframe grid rather than a solid
+   * coloured surface (`c:surfaceChart/c:wireframe/@val` or
+   * `c:surface3DChart/c:wireframe/@val`, both modeled as chart type
+   * `"surface"`). A `CT_Boolean` element: absent from the source XML
+   * defaults to `true` per schema, so `undefined` here means "not present in
+   * the source" and callers should treat it as `true`. Surface only.
+   */
+  wireframe?: boolean;
   /**
    * Scatter presentation mode (`c:scatterChart/c:scatterStyle/@val`).
    *
@@ -3320,6 +3387,26 @@ interface PptxBackgroundRemovalMark {
  * // => retains the middle of the image; the marks list stays empty
  * ```
  */
+/**
+ * Snapshot of the a14 Corrections / Color panel values as they were read from
+ * the file, kept on {@link PptxImageEffects.prerenderedCorrections} so a
+ * renderer can tell a baked-in value from one changed in this library.
+ */
+interface PptxImagePrerenderedCorrections {
+  sharpenSoften?: {
+    amount: number;
+  };
+  brightnessContrast?: {
+    bright?: number;
+    contrast?: number;
+  };
+  colorTemperature?: {
+    colorTemp: number;
+  };
+  colorSaturation?: {
+    sat: number;
+  };
+}
 interface PptxBackgroundRemoval {
   /** Top edge of the retained rectangle (0..1 fraction of the image height). */
   top: number;
@@ -3386,18 +3473,71 @@ interface PptxImageEffects {
    */
   backgroundRemoval?: PptxBackgroundRemoval;
   /**
-   * `a14:imgLayer/@r:embed` — relationship id of the PRISTINE original image
+   * `a14:imgLayer/@r:embed`: relationship id of the PRISTINE original image
    * the baked effects were derived from (PowerPoint stores it as an HD Photo
    * `.wdp` part, which browsers cannot decode).
    */
   originalImageRelId?: string;
+  /**
+   * PowerPoint 2010+ Corrections panel "Sharpen/Soften"
+   * (`a14:sharpenSoften/@amount`). Raw as the XML carries it: 1/1000ths of a
+   * percent, `-100000` (fully softened) .. `100000` (fully sharpened).
+   * Edit-time metadata like the artistic effects: PowerPoint bakes the result
+   * into the stored bitmap.
+   */
+  sharpenSoften?: {
+    amount: number;
+  };
+  /**
+   * PowerPoint 2010+ Corrections panel "Brightness/Contrast"
+   * (`a14:brightnessContrast/@bright`, `@contrast`). Raw 1/1000ths of a
+   * percent, `-100000` .. `100000`. Distinct from the legacy `a:blip/@bright`
+   * + `@contrast` pair in {@link PptxImageEffects.brightness} /
+   * {@link PptxImageEffects.contrast}, which PowerPoint 2007 wrote and which
+   * a renderer still applies.
+   */
+  brightnessContrast?: {
+    bright?: number;
+    contrast?: number;
+  };
+  /**
+   * PowerPoint 2010+ Color panel "Color Tone"
+   * (`a14:colorTemperature/@colorTemp`). Raw Kelvin value, `1500` .. `11500`;
+   * `6500` is neutral.
+   */
+  colorTemperature?: {
+    colorTemp: number;
+  };
+  /**
+   * PowerPoint 2010+ Color panel "Color Saturation" (`a14:saturation/@sat`).
+   * Raw 1/1000ths of a percent: `100000` is unchanged, `0` is grayscale,
+   * `400000` the maximum. Named `colorSaturation` because
+   * {@link PptxImageEffects.saturation} is the viewer-side -100..100 knob
+   * that has no OOXML counterpart.
+   */
+  colorSaturation?: {
+    sat: number;
+  };
+  /**
+   * The Corrections / Color panel values ALREADY baked into the image data,
+   * which a renderer must not apply a second time. The a14 counterpart of
+   * {@link PptxImageEffects.artisticPrerenderedEffect}: PowerPoint writes the
+   * corrected bitmap to the main `a:blip` and keeps the pristine original in
+   * `a14:imgLayer` (measured on a real deck: the stored PNG is a monotone tonal
+   * transform of the `.wdp` original, slope 0.7 for `contrast="-40000"`).
+   *
+   * Holds the VALUES rather than a boolean so that changing one of the four
+   * fields in this library's inspector still renders: a field that differs
+   * from its snapshot is applied, one that matches is skipped.
+   */
+  prerenderedCorrections?: PptxImagePrerenderedCorrections;
   /** Alpha modulation fixed: non-negative percentage (100 means unchanged opacity). */
   alphaModFix?: number;
   /** Original alpha modulation fixed node, including foreign attributes. */
   alphaModFixRawXml?: XmlObject;
-  /** Bi-level threshold — converts to 1-bit black/white (0-100). */
+  /** Bi-level threshold: converts to 1-bit black/white (0-100). */
   biLevel?: number;
-  /** Colour change — swap one colour range for another (used for transparency keying). */
+  /** Colour change: swap one colour range for another (used for transparency keying). */
   clrChange?: {
     clrFrom: string;
     clrTo: string;
@@ -3420,11 +3560,11 @@ interface PptxImageEffects {
     /** Original effect XML, including colour transforms and foreign attributes. */
     rawXml?: XmlObject;
   };
-  /** Alpha ceiling (`a:alphaCeiling`) — clamps any non-zero alpha to fully opaque. Boolean flag. */
+  /** Alpha ceiling (`a:alphaCeiling`): clamps any non-zero alpha to fully opaque. Boolean flag. */
   alphaCeiling?: boolean;
   /** Original alpha ceiling node, including foreign attributes. */
   alphaCeilingRawXml?: XmlObject;
-  /** Alpha floor (`a:alphaFloor`) — clamps any non-fully-opaque alpha to fully transparent. Boolean flag. */
+  /** Alpha floor (`a:alphaFloor`): clamps any non-fully-opaque alpha to fully transparent. Boolean flag. */
   alphaFloor?: boolean;
   /** Original alpha floor node, including foreign attributes. */
   alphaFloorRawXml?: XmlObject;
@@ -3448,16 +3588,16 @@ interface PptxImageEffects {
      */
     amt?: number;
   };
-  /** Alpha replace (`a:alphaRepl`) — replaces alpha with the given fixed-percent value (0..100). */
+  /** Alpha replace (`a:alphaRepl`): replaces alpha with the given fixed-percent value (0..100). */
   alphaRepl?: number;
   /** Original alpha replace node, including foreign attributes. */
   alphaReplRawXml?: XmlObject;
-  /** Alpha bi-level (`a:alphaBiLevel`) — threshold (0..100) above which alpha becomes fully opaque. */
+  /** Alpha bi-level (`a:alphaBiLevel`): threshold (0..100) above which alpha becomes fully opaque. */
   alphaBiLevel?: number;
   /** Original alpha bi-level node, including foreign attributes. */
   alphaBiLevelRawXml?: XmlObject;
   /**
-   * Colour replace (`a:clrRepl`) — replaces all colour information in an image
+   * Colour replace (`a:clrRepl`): replaces all colour information in an image
    * with the given solid colour. Stores the raw colour child to preserve scheme
    * colour references and modifiers.
    */
@@ -3467,24 +3607,24 @@ interface PptxImageEffects {
     /** Raw opaque colour XML for round-trip. */
     rawXml?: Record<string, unknown>;
   };
-  /** Luminance modulation (`a:lum`) — bright/contrast as fixed percentages (0..100). */
+  /** Luminance modulation (`a:lum`): bright/contrast as fixed percentages (0..100). */
   lum?: {
     bright?: number;
     contrast?: number;
   };
-  /** HSL modulation (`a:hsl`) — hue (0..360 degrees), saturation/luminance (-100..100). */
+  /** HSL modulation (`a:hsl`): hue (0..360 degrees), saturation/luminance (-100..100). */
   hsl?: {
     hue?: number;
     sat?: number;
     lum?: number;
   };
-  /** Image-effect tint (`a:tint` inside blip) — hue (0..360), amount (-100..100). */
+  /** Image-effect tint (`a:tint` inside blip): hue (0..360), amount (-100..100). */
   tint?: {
     hue?: number;
     amt?: number;
   };
   /**
-   * Fill overlay (`a:fillOverlay`) — overlays a fill on top of the blip.
+   * Fill overlay (`a:fillOverlay`): overlays a fill on top of the blip.
    * Stores blend mode and the raw inner fill XML for round-trip.
    */
   fillOverlay?: {
@@ -3526,7 +3666,7 @@ interface PptxImageEffects {
       background?: string;
     };
   };
-  /** Blur (`a:blur`) — radius in EMU and grow flag. */
+  /** Blur (`a:blur`): radius in EMU and grow flag. */
   blur?: {
     rad?: number;
     grow?: boolean;
@@ -3538,12 +3678,12 @@ interface PptxImageEffects {
  * @example
  * ```ts
  * const shape: PptxCropShape = "ellipse";
- * // => "ellipse" — one of: none | ellipse | roundedRect | triangle | diamond | pentagon | hexagon | star
+ * // => "ellipse": one of: none | ellipse | roundedRect | triangle | diamond | pentagon | hexagon | star
  * ```
  */
 type PptxCropShape = 'none' | 'ellipse' | 'roundedRect' | 'triangle' | 'diamond' | 'pentagon' | 'hexagon' | 'star';
 /**
- * Image content mixin — present on image and picture elements.
+ * Image content mixin: present on image and picture elements.
  *
  * Contains the decoded image data (base64 data URL or archive path),
  * alt text, crop insets, tiling settings, and image effects.
@@ -3613,7 +3753,16 @@ interface PptxImageProperties {
   dpi?: number;
   /** Image recolour/artistic effect properties. */
   imageEffects?: PptxImageEffects;
-  /** Crop-to-shape — CSS clip-path shape name. */
+  /**
+   * Crop-to-shape (CSS clip-path shape name).
+   *
+   * PowerPoint implements "Crop to Shape" by writing the picture's own
+   * `a:prstGeom`, so this is a typed view over `shapeType`: on load it is
+   * derived from the preset (`ellipse` -> `'ellipse'`, `roundRect` ->
+   * `'roundedRect'`, `star5` -> `'star'`, ...; see
+   * `utils/crop-shape-geometry`), and on save a changed value rewrites the
+   * preset. `'none'` / `undefined` leaves the geometry alone.
+   */
   cropShape?: PptxCropShape;
 }
 //#endregion
@@ -7540,7 +7689,11 @@ interface PptxSlide {
    */
   slideId?: string;
   sourceSlideId?: string;
-  /** Optional author-supplied slide name (set via `SlideBuilder.setName`). */
+  /**
+   * The slide name, `p:cSld/@name`: loaded from the part, written back on
+   * save (an empty string clears the attribute), and settable via
+   * `SlideBuilder.setName`.
+   */
   name?: string;
   layoutPath?: string;
   layoutName?: string;