@openpresentation/opf-pptx 0.11.0 → 0.11.2

package/DEPENDENCY-NOTES.md

@@ -2,7 +2,7 @@
 
 ## Coordinated `@openpresentation/opf` pin
 
-PPTX 0.11.0 depends on published [`@openpresentation/opf@^0.11.2`](https://www.npmjs.com/package/@openpresentation/opf) (reference layer: ColorRef, document `variables`, exported `resolveColorRef()`). The optional renderer peer is [`@openpresentation/opf-render@^0.11.0`](https://www.npmjs.com/package/@openpresentation/opf-render) so editor 0.10.0 + render 0.11.0 + pptx 0.11.0 install together. CI checks out OPF [`b8a1faf`](https://github.com/OpenPresentation/opf/commit/b8a1faf24203635bd36b09ea19f44bcd53781f16) (`opf-v0.11.0`) for coordinated source linking. Named content colors resolve through core `resolveColorRef()`; eight-digit hex alpha stays a local export concern because core `normalizeHexColor` drops the alpha byte. Native `schemeClr` / theme `clrScheme` writes remain follow-up work.
+PPTX 0.11.2 depends on published [`@openpresentation/opf@^0.11.2`](https://www.npmjs.com/package/@openpresentation/opf) (reference layer: ColorRef, document `variables`, exported `resolveColorRef()`). The optional renderer peer is [`@openpresentation/opf-render@^0.11.0`](https://www.npmjs.com/package/@openpresentation/opf-render) so editor 0.10.0 + render 0.11.0 + pptx 0.11.0 install together. CI checks out OPF [`b8a1faf`](https://github.com/OpenPresentation/opf/commit/b8a1faf24203635bd36b09ea19f44bcd53781f16) (`opf-v0.11.0`) for coordinated source linking. Named content colors resolve through core `resolveColorRef()`; eight-digit hex alpha stays a local export concern because core `normalizeHexColor` drops the alpha byte. Native `schemeClr` / theme `clrScheme` writes remain follow-up work.
 
 OPF PPTX 0.5.1 ships the exact, unmodified PptxGenJS 4.0.1 ESM distribution in `vendor/pptxgenjs`, with its MIT license, upstream archive integrity and per-file SHA-256 hashes. Its actual JSZip dependency is declared directly. Ordinary npm installations therefore omit the unused image-size parser without requiring consumer overrides. This removes the affected dependency; it does not patch the parser. Published OPF PPTX 0.5.0 retains the older graph.
 

package/README.md

@@ -1,6 +1,6 @@
 # OPF PPTX
 
-Version 0.11.0 requires core `^0.11.2` (cover slides are centered between header and footer furniture) and the optional `@openpresentation/opf-render` peer `^0.11.0`; install them together so export and preview resolve the same core. Version 0.10.0 required core `^0.11.1` and the peer `^0.10.0`. It adds native slide-number and date fields, socials, slide-image treatments, theme color schemes, script-slot fonts and RTL, re-import of design and metadata references, native underline and current-body formatting on import, and UTC-canonical `zipDate` (see the changelog for the intentional contract changes).
+Version 0.11.2 exports the classic chart types as native chart constructs and writes named and default table colours, text pairs and hyperlink colours as theme references (no API or dependency change; resolved colours are unchanged). Version 0.11.1 exports `design.watermark` as a native picture (it re-imports) and embeds byte-identical media parts once, with no API or dependency change. Version 0.11.0 requires core `^0.11.2` (cover slides are centered between header and footer furniture) and the optional `@openpresentation/opf-render` peer `^0.11.0`; install them together so export and preview resolve the same core. Version 0.10.0 required core `^0.11.1` and the peer `^0.10.0`. It adds native slide-number and date fields, socials, slide-image treatments, theme color schemes, script-slot fonts and RTL, re-import of design and metadata references, native underline and current-body formatting on import, and UTC-canonical `zipDate` (see the changelog for the intentional contract changes).
 
 Version 0.9.1 kept core `^0.11.0` and raised the optional `@openpresentation/opf-render` peer to `^0.9.0` so it coexists with editor 0.8.0. ColorRef / `variables` on content colors still hex-resolve through core `resolveColorRef()` before PptxGenJS `srgbClr` export. Unrecognized run colors such as `color:'invalid'` still validate and fall back to the theme text color. Native DrawingML `schemeClr` and theme `clrScheme` writes, and native `p:hf` headers/footers, are not in this release. Import still flattens theme colors to hex. Metric, quote and timeline layout placeholders and the corrected text-bullet contract from 0.8.1 are retained.
 
@@ -80,7 +80,7 @@ The first exporter keeps the public API stable while using `pptxgenjs` internall
 
 - `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. Content ColorRef values (hex, scheme slots/roles, and `var:<id>`) resolve through core `resolveColorRef()`. Slot and role names become native `a:schemeClr` references when the exported theme holds that exact color; hex, `var:<id>` and slide-override colors stay `a:srgbClr` (see [Theme color scheme](#theme-color-scheme)).
+- Text, lists, metrics, quotes, timelines, code, tables, and inline-data charts are emitted as editable PowerPoint text, table, and chart objects. Content ColorRef values (hex, scheme slots/roles, and `var:<id>`) resolve through core `resolveColorRef()`. Slot and role names become native `a:schemeClr` references when the exported theme holds that exact color; hex, `var:<id>` and slide-override colors stay `a:srgbClr` (see [Theme color scheme](#theme-color-scheme)). Each classic chart type the core catalog keeps (one per Aspose.Slides `ChartType`: clustered/stacked/100% stacked column and bar, line and stacked line with or without markers, area/stacked/100% area, pie, doughnut, scatter with markers, radar/radar with markers/filled radar) is written as its exact native construct; deprecated core ids export as their replacement; other ids keep the previous best-effort mapping. Chartex types (treemap, histogram, pareto, box & whisker, waterfall, funnel, map) still export as clustered columns and report `chart-data-adapted` (`chartex-fallback`); a pie or doughnut chart plots only its first series and reports `chart-data-adapted` (`series-dropped`) when it has more.
 - A chart whose data is one column of values (a histogram or dot plot) has no category column. It exports as a native chart and reports `chart-data-adapted`: a histogram is binned into equal-width bins (Sturges' count, at most 50) and written as a column chart of the counts, and any other chart type plots the values against their row numbers. PowerPoint's own histogram chart is not exported (histogram is a column chart at this engine). Cells parse as in every chart ("12%", "$5" and "1,234" count) and cells that hold no number are skipped, not plotted as 0. Binned counts do not round-trip: re-importing the file gives a `Bin`/`Frequency` column chart, not the raw values. Chart data that cannot be plotted (no numbers, no rows, or an external data source), an empty table and unsupported content keep a placeholder frame with a plain-language description (never a dump of the source data or URLs) and report `chart-data-unplottable` or `content-placeholder` with a `reason`; content is never dropped without a diagnostic.
 - 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. [Export determinism](docs/export-determinism.md) lists the tested time zone, locale, clock and host-font controls and each known variance (WebP conversion, font registries, ICU segmentation, timestamps).
@@ -113,7 +113,7 @@ The first importer is mechanical and schema-compatible:
 - The first slide master's theme `clrScheme` maps to `design.colorScheme`: a catalog id on an exact twelve-slot match, otherwise inline slots. A theme named like a catalog theme maps to `design.theme` when its colors or heading/body fonts corroborate it (see [Theme color scheme](#theme-color-scheme)).
 - Native title/subtitle placeholders retain their roles. On slides without complete OPF heading tags, recognizable text-box positions and sizes provide a fallback. If any complete OPF heading role is recovered, untagged body text stays in `blocks[]` instead of being promoted into an absent heading role. Damaged tags retain visible text through ordinary import and diagnostics.
 - 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.
+- PowerPoint tables map to OPF table blocks, embedded images map to data URI image blocks, and cached chart series map to OPF chart blocks whose `type` is the core chart type id for the native construct (for example a `percentStacked` column chart imports as `100pct-stacked-column-3x`, a filled radar as `filled-radar`; a scatter chart imports as `[Point, X, ...series]`).
 - Chart cache points are placed by their native `c:pt@idx`, with `c:ptCount` retaining trailing gaps. Missing labels and values become `null`; explicitly empty labels and series names stay empty strings, and an actual numeric zero stays zero. Empty numeric cache values remain missing. Malformed or duplicate indices, contradictory counts, competing caches and allocation limits reject with `invalid-chart-cache` and the chart-part/cache path; hierarchical category caches reject with `unsupported-chart-cache` instead of flattening labels. Each cache is limited to 100,000 positions, and combined caches and the emitted table each to 1,000,000 cells. Complete decimal scientific notation in numeric caches is read as a number; exponent overflow or nonzero underflow to zero rejects with `unsupported-chart-cache` and the chart part, series, cache and logical point path. Zero coefficients remain zero. This finite-number boundary does not classify rejected text as invalid OOXML. Malformed exponent strings and other nonblank numeric text retain the existing legacy conversion policy. This cache-only import does not repair embedded worksheets, restore unsupported scatter X/point labels, change exporter/workbook parsing or export/re-export missing-data handling, or establish native chart fidelity.
 - Table imports retain empty rows. A native `firstRow` flag of `1` or `true` maps the first row to column labels; absent/false flags retain every row as data. New exports set this flag from OPF columns. Older exports without the flag retain their labels as the first data row rather than inferring headers.
 - Native table text preserves run/field/break order, significant whitespace, and blank paragraphs. Cells return canonical `{value, style}` objects; `value` retains scalar text or supported rich runs. Covered merge positions are `null`. Explicit normal headers override OPF’s bold header default. Numeric/boolean/null source types cannot be reconstructed from native display text.
@@ -222,6 +222,8 @@ Slide-image treatments export from core's normalized geometry as native DrawingM
 - `recolor` becomes `a:grayscl` or `a:duotone`, followed by `a:alphaModFix` for `opacity`, on the blip only.
 - `overlay` becomes one tagged `OPF slide image overlay slides.N` shape directly above the picture.
 
+A deck or slide watermark (`design.watermark`) exports as one native picture named `OPF watermark` per slide, after the slide image and its overlay, if any, and before all content (the preview's paint order, so a background slide image lies beneath the watermark), at the preview's frame: the centered 40% by 40% box at 30%/30% of the slide, fitted without cropping. Its opacity is `a:alphaModFix` (the object form's `opacity`, otherwise the preview default 0.08), and its alt text is the asset's `alt`, otherwise `Watermark`. `design.watermark = false` on a slide exports none. An unchanged export imports back as `design.watermark` (at deck level when every slide carries the same one); an edited picture stays ordinary content and reports `invalid-watermark-provenance`. An unresolved image reports `unresolved-asset` and an object with no `src` reports `watermark-not-exported`.
+
 An unchanged export imports every treatment field back. An edited overlay drops only the overlay and reports `invalid-slide-image-provenance`. An edited picture or effect drops the slide image. See core `docs/image-treatments.md` for the vocabulary and the unsupported effects: blur, shadows, soft edges and background removal. PowerPoint's luminance weights for grayscale and duotone are unverified natively.
 
 Tests compare SVG/native fit and crop geometry across nine synthetic raster fixtures and cover all eight JPEG orientations. Keynote 14.4 visually preserves proportions for wide/tall fit/crop and displays all eight orientations correctly. This does not establish Microsoft PowerPoint raster parity or WebP support in every Office version.
@@ -266,15 +268,22 @@ Import reads `a:pattFill` with a DrawingML preset and resolvable foreground/back
 
 Export writes the deck's resolved color scheme into `ppt/theme/theme1.xml` `a:clrScheme`, named after the scheme. The OPF slots map one to one: `dark1`/`light1`/`dark2`/`light2` to `dk1`/`lt1`/`dk2`/`lt2`, `accent1`-`accent6` to themselves, and `hyperlink`/`followedHyperlink` to `hlink`/`folHlink`. An abstract role fills a slot only when the scheme leaves that slot unset. Previously every export carried the vendored Office palette (`accent1` `4472C4`). When the deck names a catalog `design.theme`, `a:theme` and its `thm15:themeFamily` take that theme's name. The rewrite happens during package normalization; the vendored PptxGenJS bytes are unchanged.
 
-Document colors that name a slot or role (`accent2`, `textSecondary`, `surface`, ...) become `a:schemeClr` in runs, table cell fills and text, and table borders. Theme-slot backgrounds (`{type:'theme', slot}` or a slot name) do the same. Slide content reaches the theme through the master color map, so `dark1`, `light1`, `dark2` and `light2` are written as `tx1`, `bg1`, `tx2` and `bg2`. A reference becomes `schemeClr` only when the deck theme slot holds exactly the color the slide resolved. PowerPoint has one theme per master, so a slide-level `design.colorScheme` that changes a slot keeps that color literal. These stay `a:srgbClr`:
+Document colors that name a slot or role (`accent2`, `textSecondary`, `surface`, ...) become `a:schemeClr` in runs, table cell fills and text, and table borders. Theme-slot backgrounds (`{type:'theme', slot}` or a slot name) do the same. Slide content reaches the theme through the master color map, so `dark1`, `light1`, `dark2` and `light2` are written as `tx1`, `bg1`, `tx2` and `bg2`. A reference becomes `schemeClr` only when the deck theme slot holds exactly the color the slide resolved. PowerPoint has one theme per master, so a slide with its own `design.colorScheme` (or a slide theme that changes any slot) keeps **every** color literal, including values that happen to equal the deck theme, so a theme edit never partially recolors it.
+
+Default text follows the theme only where the background does. When a slide's background is an opaque theme reference (`light1`/`light2` or `dark1`/`dark2`, the only slots a theme background accepts), the exporter's default and muted text are written as the paired slot: `tx1`/`tx2` on `bg1`/`bg2`, and `bg1`/`bg2` on `tx1`/`tx2`. This applies only when the resolved color is exactly that deck slot, so a PowerPoint theme switch moves text and background together. It covers headings, body and list text, list markers, metric labels, quote text and footers, header/footer text and placeholders. Text on a literal background, text on a card fill and override slides stay literal.
+
+Table chrome follows the theme too (FF-24c). With no theme override on the slide, the default header fill is `accent1`, the body fill is the `surface` slot (`bg2`, or `tx2` on a dark deck), and every cell border is `accent5`. Each is written as `a:schemeClr` when the deck theme slot holds exactly that color. Default cell text pairs with its fill: `tx1` on a `bg2` fill, `bg1` on a `tx2` fill, and light1 or dark1 (`bg1`/`tx1`) on an accent fill, again only when the contrast-selected color is exactly that slot. A named `fill`, `color` or border color on a cell (`accent2`, `surface`, `light2`, `textSecondary`, ...) is a scheme reference, `hyperlink` and `followedHyperlink` included, and a literal on the cell stays literal (default text on a literal fill included). PptxGenJS 4.0.1 cannot write `hlink`/`folHlink`, so those two are written as a reserved literal (`FE01A0`/`FE01A1`, or the next free pair) and rewritten to `a:schemeClr` in the finished slide part; a document that itself uses every reserved value keeps its link colors literal.
+
+When the deck background is a theme slot other than `light1`, the slide master gets that background and its title/body/other text styles use the paired text slot. The layout drops its own `bg1` background and inherits the master, so slides added in PowerPoint match the theme. `light1` decks keep the vendored master.
+
+These stay `a:srgbClr`:
 
 - literal hex colors, even when they equal a scheme slot;
 - `var:<id>` variables;
 - translucent colors;
-- engine-derived chrome: default text, headings, list markers, muted text, card and chart panels, chart series, and default table header fill. These colors are contrast-selected per slide, not named by the document.
-- `hyperlink` and `followedHyperlink` run and cell colors, because PptxGenJS 4.0.1 cannot emit `hlink`/`folHlink`. Borders and backgrounds can.
+- other engine-derived chrome: card fills and borders, chart panels, series and labels, timeline connectors and markers, and image and media placeholders, plus default text on a card or a literal background. These colors are contrast-selected or derived from roles, not named by the document, and are not yet theme references.
 
-Import reads the first slide master's theme. An exact twelve-slot match with a bundled catalog scheme returns its id; the `clrScheme` name breaks ties. Otherwise the importer returns inline slots, relative to the catalog scheme the `clrScheme` is named after when there is one (`{id:'boost', accent1:'#123456'}`). A theme whose name equals a catalog theme's name maps to `design.theme` only if the package's color scheme or heading/body fonts match that theme; otherwise `theme-unverified` is reported. A missing theme, or slots that are not opaque sRGB/system colors, report `unsupported-theme-colors` on `design.colorScheme`. Slide colors are still imported as resolved hex. Role overrides such as `primary` have no theme slot and are not recovered. `test/theme-colors.mjs` covers all 14 catalog schemes and 4 catalog themes, override, foreign and damaged themes, and the literal-color boundaries. This establishes package structure and round-trip, not PowerPoint rendering.
+Import reads the first slide master's theme. An exact twelve-slot match with a bundled catalog scheme returns its id; the `clrScheme` name breaks ties. Otherwise the importer returns inline slots, relative to the catalog scheme the `clrScheme` is named after when there is one (`{id:'boost', accent1:'#123456'}`). A theme whose name equals a catalog theme's name maps to `design.theme` only if the package's color scheme or heading/body fonts match that theme; otherwise `theme-unverified` is reported. A missing theme, or slots that are not opaque sRGB/system colors, report `unsupported-theme-colors` on `design.colorScheme`. Slide colors are still imported as resolved hex. Role overrides such as `primary` have no theme slot and are not recovered. `test/theme-colors.mjs` covers all 14 catalog schemes and 4 catalog themes, override, foreign and damaged themes, and the literal-color boundaries. `test/table-theme-colors.mjs` covers named and default table chrome on all 14 schemes and four backgrounds, literals, override slides, the link colors, re-import and a theme switch in the package. This establishes package structure and round-trip, not PowerPoint rendering.
 
 ## JPEG orientation on import
 

package/dist/chart-types.js

@@ -0,0 +1,183 @@
+// OPF chart type ids -> native PowerPoint chart constructs (FF-22).
+//
+// The core catalog keeps one chart type per Aspose.Slides ChartType
+// (spec/catalogs/chart-types, OpenPresentation/opf#121) and deprecates the
+// rest with a replacement id. The published core package this exporter
+// depends on predates that metadata, so the mapping is carried here. Kept ids
+// map to the exact Office construct; deprecated ids resolve to their
+// replacement; any other id keeps the legacy substring heuristic.
+
+const category = (pptx, extra = {}) => ({ family: 'category', pptx, ...extra });
+
+export const CHART_TYPES = Object.freeze({
+  column: category('bar', { aspose: 'ClusteredColumn', barDir: 'col', grouping: 'clustered' }),
+  'stacked-column-3x': category('bar', { aspose: 'StackedColumn', barDir: 'col', grouping: 'stacked' }),
+  '100pct-stacked-column-3x': category('bar', { aspose: 'PercentsStackedColumn', barDir: 'col', grouping: 'percentStacked' }),
+  bar: category('bar', { aspose: 'ClusteredBar', barDir: 'bar', grouping: 'clustered' }),
+  'stacked-bar-3x': category('bar', { aspose: 'StackedBar', barDir: 'bar', grouping: 'stacked' }),
+  '100pct-stacked-bar-3x': category('bar', { aspose: 'PercentsStackedBar', barDir: 'bar', grouping: 'percentStacked' }),
+  line: category('line', { aspose: 'Line', grouping: 'standard', markers: false }),
+  'line-with-markers': category('line', { aspose: 'LineWithMarkers', grouping: 'standard', markers: true }),
+  'stacked-line-3x': category('line', { aspose: 'StackedLine', grouping: 'stacked', markers: false }),
+  'stacked-line-with-markers-3x': category('line', { aspose: 'StackedLineWithMarkers', grouping: 'stacked', markers: true }),
+  area: category('area', { aspose: 'Area', grouping: 'standard' }),
+  'stacked-area-3x': category('area', { aspose: 'StackedArea', grouping: 'stacked' }),
+  '100pct-stacked-area-3x': category('area', { aspose: 'PercentsStackedArea', grouping: 'percentStacked' }),
+  pie: { family: 'circular', pptx: 'pie', aspose: 'Pie' },
+  doughnut: { family: 'circular', pptx: 'doughnut', aspose: 'Doughnut' },
+  scatter: { family: 'xy', pptx: 'scatter', aspose: 'ScatterWithMarkers' },
+  radar: category('radar', { aspose: 'Radar', radarStyle: 'standard', markers: false }),
+  'radar-with-markers': category('radar', { aspose: 'RadarWithMarkers', radarStyle: 'marker', markers: true }),
+  'filled-radar': category('radar', { aspose: 'FilledRadar', radarStyle: 'filled', markers: false }),
+  treemap: { family: 'chartex', layoutId: 'treemap', aspose: 'Treemap' },
+  histogram: { family: 'chartex', layoutId: 'clusteredColumn', aspose: 'Histogram' },
+  pareto: { family: 'chartex', layoutId: 'clusteredColumn', aspose: 'ParetoLine' },
+  'box-and-whisker': { family: 'chartex', layoutId: 'boxWhisker', aspose: 'BoxAndWhisker' },
+  waterfall: { family: 'chartex', layoutId: 'waterfall', aspose: 'Waterfall' },
+  funnel: { family: 'chartex', layoutId: 'funnel', aspose: 'Funnel' },
+  world: { family: 'chartex', layoutId: 'regionMap', aspose: 'Map' },
+});
+
+// A chartex id (treemap, histogram, ...) has no classic construct; the exporter
+// writes it as a clustered column chart and reports chart-data-adapted.
+export const CHARTEX_FALLBACK = CHART_TYPES.column;
+
+const variants = (base, target) => Object.fromEntries([base, `${base}-2x`, `${base}-3x`].map((id) => [id, target]));
+
+// Deprecated core ids (opf 0.12.0 removes them) -> replacement id.
+export const DEPRECATED_CHART_TYPES = Object.freeze({
+  ...variants('100pct-bullet-bar', '100pct-stacked-bar-3x'),
+  '100pct-progress-bar': '100pct-stacked-bar-3x',
+  '100pct-stacked-bar-2x': '100pct-stacked-bar-3x',
+  ...variants('100pct-bullet-column', '100pct-stacked-column-3x'),
+  '100pct-stacked-column-2x': '100pct-stacked-column-3x',
+  '100pct-stacked-area-2x': '100pct-stacked-area-3x',
+  australia: 'world',
+  canada: 'world',
+  'united-kingdom': 'world',
+  'united-states': 'world',
+  'box-and-whisker-2x': 'box-and-whisker',
+  'box-and-whisker-3x': 'box-and-whisker',
+  ...variants('bullet-bar', 'bar'),
+  'clustered-bar-2x': 'bar',
+  ...variants('bullet-column', 'column'),
+  'clustered-column': 'column',
+  ...Object.fromEntries(['', '-2x', '-3x', '-4x', '-5x', '-6x'].map((suffix) => [`dot-plot${suffix}`, 'scatter'])),
+  dumbbell: 'scatter',
+  'line-2x': 'line',
+  'line-3x': 'line',
+  'line-with-high-low': 'line',
+  ...Object.fromEntries(['', '-2x', '-3x', '-4x', '-5x', '-6x'].map((suffix) => [`sparkline${suffix}`, 'line'])),
+  'line-with-high-low-and-markers': 'line-with-markers',
+  'line-with-markers-2x': 'line-with-markers',
+  'line-with-markers-3x': 'line-with-markers',
+  'stacked-area-2x': 'stacked-area-3x',
+  'stacked-bar-2x': 'stacked-bar-3x',
+  'stacked-column-2x': 'stacked-column-3x',
+  'stacked-line-2x': 'stacked-line-3x',
+  'stacked-line-with-markers-2x': 'stacked-line-with-markers-3x',
+  'treemap-2x': 'treemap',
+  'treemap-3x': 'treemap',
+});
+
+const ALIASES = Object.freeze({ donut: 'doughnut' });
+
+// Resolve an OPF chart type id to {id, spec}. Kept and deprecated ids resolve
+// to a kept id; anything else returns the legacy heuristic with id: null.
+export function resolveChartType(type) {
+  const raw = String(type ?? '').trim().toLowerCase();
+  const id = ALIASES[raw] ?? DEPRECATED_CHART_TYPES[raw] ?? raw;
+  if (Object.hasOwn(CHART_TYPES, id)) return { id, spec: CHART_TYPES[id] };
+  return { id: null, spec: legacyChartType(raw) };
+}
+
+// The pre-FF-22 heuristic for ids outside the core catalog.
+function legacyChartType(normalized) {
+  if (normalized.includes('pie')) return CHART_TYPES.pie;
+  if (normalized.includes('doughnut') || normalized.includes('donut')) return CHART_TYPES.doughnut;
+  if (normalized.includes('area')) return { ...CHART_TYPES.area, legacy: true };
+  if (normalized.includes('line')) return { ...CHART_TYPES['line-with-markers'], legacy: true };
+  if (normalized.includes('scatter')) return CHART_TYPES.scatter;
+  if (normalized.includes('radar')) return { ...CHART_TYPES.radar, legacy: true };
+  const grouping = normalized.includes('stacked') ? 'stacked' : 'clustered';
+  return category('bar', { barDir: normalized.includes('bar') ? 'bar' : 'col', grouping, legacy: true });
+}
+
+// Native construct -> kept OPF id, for import. `node` is the parsed chart-type
+// element (fast-xml-parser, attributes as plain keys).
+export function chartTypeFromNative(element, node) {
+  const attr = (name) => node?.[`c:${name}`]?.val;
+  const series = asArray(node?.['c:ser']);
+  const markers = !series.length || series.some((ser) => ser?.['c:marker']?.['c:symbol']?.val !== 'none');
+  const grouping = attr('grouping') ?? 'standard';
+  const stacked = grouping === 'stacked' || grouping === 'percentStacked';
+  const percent = grouping === 'percentStacked';
+  switch (element) {
+    case 'barChart':
+    case 'bar3DChart': {
+      const direction = attr('barDir') === 'bar' ? 'bar' : 'column';
+      if (percent) return `100pct-stacked-${direction}-3x`;
+      if (stacked) return `stacked-${direction}-3x`;
+      return direction;
+    }
+    case 'lineChart':
+    case 'line3DChart':
+      if (stacked) return markers ? 'stacked-line-with-markers-3x' : 'stacked-line-3x';
+      return markers ? 'line-with-markers' : 'line';
+    case 'areaChart':
+    case 'area3DChart':
+      return percent ? '100pct-stacked-area-3x' : stacked ? 'stacked-area-3x' : 'area';
+    case 'pieChart':
+    case 'pie3DChart':
+    case 'ofPieChart':
+      return 'pie';
+    case 'doughnutChart':
+      return 'doughnut';
+    case 'scatterChart':
+      return 'scatter';
+    case 'radarChart': {
+      const style = attr('radarStyle');
+      if (style === 'filled') return 'filled-radar';
+      if (style === 'marker' && markers) return 'radar-with-markers';
+      return 'radar';
+    }
+    default:
+      return null;
+  }
+}
+
+export const NATIVE_CHART_ELEMENTS = Object.freeze([
+  'barChart', 'bar3DChart', 'lineChart', 'line3DChart', 'pieChart', 'pie3DChart', 'ofPieChart',
+  'doughnutChart', 'areaChart', 'area3DChart', 'scatterChart', 'radarChart',
+]);
+
+function asArray(value) {
+  return value === undefined ? [] : Array.isArray(value) ? value : [value];
+}
+
+// PptxGenJS omits or cannot express parts of these constructs. Rewrite only
+// the generated chart-type element so the part states the exact grouping.
+export function applyChartConstruct(xml, spec) {
+  // ScatterWithMarkers: the core catalog records scatterStyle "marker" (markers, no connecting line). PptxGenJS writes lineMarker and relies on the series line being noFill.
+  if (spec?.family === 'xy') return xml.replace(/<c:scatterStyle val="[^"]*"\/>/, '<c:scatterStyle val="marker"/>');
+  if (!spec || spec.family !== 'category') return xml;
+  const element = { bar: 'barChart', line: 'lineChart', area: 'areaChart', radar: 'radarChart' }[spec.pptx];
+  if (!element || element === 'radarChart') return xml;
+  const open = `<c:${element}>`;
+  const start = xml.indexOf(open);
+  if (start < 0) return xml;
+  const end = xml.indexOf(`</c:${element}>`, start);
+  let body = xml.slice(start + open.length, end);
+  const grouping = `<c:grouping val="${spec.grouping}"/>`;
+  if (element === 'barChart') {
+    body = body.replace(/<c:grouping val="[^"]*"\/>/, grouping);
+  } else {
+    body = grouping + body.replace(/<c:grouping val="[^"]*"\/>/g, '');
+    // CT_LineSer/CT_AreaSer have no invertIfNegative (bar series only).
+    body = body.replace(/<c:invertIfNegative val="[^"]*"\/>/g, '');
+  }
+  if (spec.grouping === 'stacked' || spec.grouping === 'percentStacked') {
+    body = body.replace(/<c:overlap val="[^"]*"\/>/, '<c:overlap val="100"/>');
+  }
+  return xml.slice(0, start) + open + body + xml.slice(end);
+}

package/dist/chart-workbook.js

@@ -29,7 +29,7 @@ function workbookContext(entries,chartPart){
   if(!/^xl\/(workbook\.xml|_rels\/workbook\.xml\.rels|sharedStrings\.xml|worksheets\/[^/]+\.xml)$/.test(file.name))return false;
   size+=file.originalSize;if(size>16*1024*1024)throw Error('Chart workbook metadata exceeds the limit.');return true;
  }});
- const category=find(chart,'cat')[0],formula=category?.strRef?.f??category?.multiLvlStrRef?.f??category?.numRef?.f;
+ const category=find(chart,'cat')[0]??find(chart,'xVal')[0],formula=category?.strRef?.f??category?.multiLvlStrRef?.f??category?.numRef?.f;
  // Infer a heading only for one contiguous vertical category range with a row
  // above it. Other chart/workbook arrangements remain explicitly unrecovered.
  const range=/^(?:'((?:[^']|'')+)'|([^'!]+))!\$?([A-Z]+)\$?(\d+):\$?([A-Z]+)\$?(\d+)$/i.exec(text(formula));

package/dist/index.d.ts

@@ -40,6 +40,7 @@ export interface ChartDataUnplottableDiagnostic { code: "chart-data-unplottable"
 /** Content with no PowerPoint export (an empty table, an unsupported payload) is replaced by a plain-language placeholder frame. */
 export interface ContentPlaceholderDiagnostic { code: "content-placeholder"; path: string; message: string; reason: "table-has-no-rows" | "unsupported-payload" }
 /** The chart data was reshaped to export a native chart: a histogram's values were binned, or a single value column was plotted against row numbers. */
+export interface WatermarkNotExportedDiagnostic { code: "watermark-not-exported"; path: string; message: string }
 export interface ChartDataAdaptedDiagnostic { code: "chart-data-adapted"; path: string; message: string; adaptation: "histogram-binned" | "row-numbers" }
 
 export interface ToPptxOptions {
@@ -57,7 +58,7 @@ export interface ToPptxOptions {
   /** Match preview/pagination clearance around supplied vector text outlines; default 1. */
   textRasterPadding?: number;
   /** Layout diagnostics, `media-provenance-omitted` when video data cannot be stored, plus `unresolved-font-scheme` (once per reference path) when a font-scheme id matches no record and the default `aptos` scheme is used as the base. */
-  onDiagnostic?: (diagnostic: LayoutDiagnostic | FontSchemeDiagnostic | MediaProvenanceDiagnostic | ChartDataUnplottableDiagnostic | ChartDataAdaptedDiagnostic | ContentPlaceholderDiagnostic) => void;
+  onDiagnostic?: (diagnostic: LayoutDiagnostic | FontSchemeDiagnostic | MediaProvenanceDiagnostic | ChartDataUnplottableDiagnostic | ChartDataAdaptedDiagnostic | ContentPlaceholderDiagnostic | WatermarkNotExportedDiagnostic) => void;
   baseDir?: string;
   compressionLevel?: number;
   imageResolver?: (src: string, context: ImageResolverContext) => ImageResolverResult | Promise<ImageResolverResult | null | undefined> | null | undefined;