@openpresentation/opf-pptx 0.20.3 → 0.22.0

package/dist/image-provenance.js

@@ -32,6 +32,19 @@ export const IMAGE_TREATMENT_KEYS = Object.freeze(['fit', 'focus', 'shape', 'cor
 /** An image background's own fields besides its source. */
 export const BACKGROUND_IMAGE_KEYS = Object.freeze(['alt', 'fit', 'focus', 'opacity', 'recolor', 'overlay']);
 
+/**
+ * RR-94: the authored `src` an image block records so a re-import can give it back instead of a data: URI: a relative path
+ * (no scheme, not absolute, no `..` segment) or an http(s) URL, as authored. Anything else (a data: URI, an `asset:` reference,
+ * a file: URL, an absolute or parent-relative path, which could name any file of the machine that re-exports it) is not recorded.
+ */
+export function recordableImageSource(value) {
+  const src = typeof value === 'string' ? value : object(value) && typeof value.src === 'string' ? value.src : undefined;
+  if (src === undefined || src.length === 0 || src.length > 2048 || /[\u0000-\u001f\u007f]/.test(src)) return undefined;
+  if (/^https?:\/\/[^/\s]+/i.test(src)) return src;
+  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(src) || /^[\\/]/.test(src) || src.split(/[\\/]/).includes('..')) return undefined;
+  return src;
+}
+
 export const imageName = number => `OPF image ${number}`;
 export const imageOverlayName = pictureName => `${pictureName} overlay`;
 export const backgroundImageName = slide => `OPF background ${slide}`;
@@ -78,6 +91,37 @@ function storedFocus({x, y}, orientation) {
 
 const srcRectValue = value => Math.round(value * 100000) || 0;
 
+/** Whether native dimensions can represent the raster's unchanged aspect. */
+export function samePictureAspect(cx, cy, width, height) {
+  if (![cx, cy, width, height].every(value => Number.isSafeInteger(value) && value > 0)) return false;
+  // Native writers may round an aspect-preserving frame directly to EMUs.
+  if (Math.round(cx * height / width) === cy || Math.round(cy * width / height) === cx) return true;
+  // pictureFrame passes inches to core fitImage, whose roundBox rounds each
+  // dimension to 1e-6 input units, before placeImages rounds to whole EMUs.
+  // Invert that actual serialization, rather than allowing a visual tolerance.
+  const microinches = extent => {
+    // 914400 / 1e6 = 1143 / 1250. A rounded EMU k covers
+    // [1250*k-625, 1250*k+625) / 1143 integer microinches.
+    const scaled = BigInt(extent) * 1250n;
+    const lower = (scaled - 625n + 1142n) / 1143n;
+    const upper = (scaled + 625n + 1142n) / 1143n;
+    const result = [];
+    // Include adjacent integers for a floating-point half-EMU tie, then keep
+    // only dimensions that reproduce the writer's actual numeric operation.
+    for (let value = lower - 1n; value <= upper; value++) {
+      const numeric = Number(value);
+      if (numeric > 0 && Number.isSafeInteger(numeric) && Math.round(numeric / 1e6 * EMUS_PER_INCH) === extent) result.push(value);
+    }
+    return result;
+  };
+  const w = BigInt(width), h = BigInt(height);
+  // q=round(x*1e6) represents [q-.5,q+.5). These two half-open
+  // intervals must overlap at the raster's exact rational aspect. Strict
+  // overlap excludes a boundary where only one rounding cell contains it.
+  return microinches(cx).some(x => microinches(cy).some(y =>
+    (2n * x - 1n) * h < (2n * y + 1n) * w && (2n * y - 1n) * w < (2n * x + 1n) * h));
+}
+
 /**
  * The native frame and crop of a picture: `box` (inches) is core's picture frame, `fit` cover | contain | stretch,
  * `focus` core's focus point, `metadata` the embedded raster (width, height, orientation). `fitImage` is core's shared
@@ -107,7 +151,7 @@ export function pictureFrame(metadata, {box, fit, focus = {x: .5, y: .5}, shrink
  * picture's objectName, or 'background' for the overlay of a native slide background fill; `overlay` (the authored value)
  * is stored in OPF_IMAGE_OVERLAY_V1.
  */
-export function placeImages(entries, images, overlays, {metadataFor, fail, fitImage}) {
+export function placeImages(entries, images, overlays, {metadataFor, fail, fitImage, mediaKeyFor}) {
   if (!images.size && !overlays.size) return;
   const manifests = new Map(), overlayManifests = new Map(), placed = new Set(), shaped = new Set();
   for (const part of Object.keys(entries).filter(path => /^ppt\/slides\/slide\d+\.xml$/.test(path))) {
@@ -135,7 +179,9 @@ export function placeImages(entries, images, overlays, {metadataFor, fail, fitIm
       placed.add(name);
       if (image.treatment !== undefined) {
         const node = parser.parse(picture)['p:pic'];
-        manifests.set(name, {v: 1, role: image.role, slide: image.slide, path: image.path, treatment: image.treatment, properties: node['p:spPr'], blipFill: blipFillIdentity(node['p:blipFill'])});
+        const media = mediaKeyFor ? mediaKeyFor(part, embed) : undefined;
+        manifests.set(name, {v: 1, role: image.role, slide: image.slide, path: image.path, treatment: image.treatment, properties: node['p:spPr'], blipFill: blipFillIdentity(node['p:blipFill']),
+          ...(media !== undefined ? {media} : {}), ...(media !== undefined && image.src !== undefined ? {src: image.src} : {})});
       }
       return picture;
     });
@@ -192,9 +238,9 @@ const pick = (value, keys) => Object.fromEntries(keys.filter(key => Object.hasOw
  * readPicture(picture) returns the ordinary imported image payload; `valid(kind, value)` checks a recovered image block
  * (`kind` 'block') or background (`kind` 'background') against the OPF format.
  */
-export function importImages({pictures, shapes, relationships, entries, slideIndex, readPicture, valid, report}) {
+export function importImages({pictures, shapes, relationships, entries, slideIndex, readPicture, valid, report, mediaKeyOf = () => undefined}) {
   const slide = `slides.${slideIndex}`;
-  const blocks = new Map(), consumed = new Set(), consumedShapes = new Set();
+  const blocks = new Map(), sources = new Map(), consumed = new Set(), consumedShapes = new Set();
   let background, backgroundOverlay;
   const invalid = (path, message) => report({code: 'invalid-image-provenance', path, message});
   // Overlay shapes first: each names the picture (or the slide background) it belongs to.
@@ -223,6 +269,10 @@ export function importImages({pictures, shapes, relationships, entries, slideInd
     consumedShapes.add(found.index);
     return found.overlay;
   };
+  const restoredSource = (manifest, picture) => {
+    const key = typeof manifest.media === 'string' ? mediaKeyOf(picture) : undefined;
+    return key !== undefined && key === manifest.media && recordableImageSource(manifest.src) === manifest.src ? manifest.src : undefined;
+  };
   const edges = new Set();
   for (const [index, picture] of pictures.entries()) {
     let manifest;
@@ -231,18 +281,24 @@ export function importImages({pictures, shapes, relationships, entries, slideInd
     if (manifest === null) continue;
     const name = picture['p:nvPicPr']?.['p:cNvPr']?.name;
     const role = manifest?.role;
+    // RR-94: a plain block (no treatment) carries a tag only for its source and its crop to stay quiet. Once its bytes are another
+    // picture's (Change Picture), or it was moved or resized, the tag has nothing to give back: it reads as the ordinary picture.
+    const plain = role === 'block' && object(manifest?.treatment) && Object.keys(manifest.treatment).length === 0;
+    if (plain && typeof manifest.media === 'string' && mediaKeyOf(picture) !== manifest.media) continue;
     const path = role === 'background' ? `${slide}.design.background` : slide;
     try {
       if (manifest?.v !== 1 || manifest.slide !== slide || !['block', 'background'].includes(role) || !object(manifest.treatment)) throw Error('Invalid image manifest.');
       if (role === 'block' ? !/^OPF image \d+$/.test(name ?? '') : name !== backgroundImageName(slide)) throw Error('Image identity changed.');
       if (canonical(picture['p:spPr']) !== canonical(manifest.properties) || canonical(blipFillIdentity(picture['p:blipFill'])) !== canonical(normalizeCrop(manifest.blipFill))) throw Error('Image geometry or effects changed.');
     } catch {
+      if (plain) continue;
       invalid(path, `An edited, ambiguous or invalid tagged OPF ${role === 'background' ? 'background picture' : 'image'} was imported as an ordinary picture; its OPF ${role === 'background' ? 'background' : 'treatment and placement'} are not reconstructed.`);
       continue;
     }
     if (role === 'background') {
       const item = readPicture(picture);
-      const src = item?.payload?.image?.src;
+      // RR-94: an unchanged picture (its bytes still hash as exported) gives back the authored relative path or URL.
+      const src = restoredSource(manifest, picture) ?? item?.payload?.image?.src;
       const fields = pick(manifest.treatment, BACKGROUND_IMAGE_KEYS.filter(key => key !== 'overlay'));
       const overlay = takeOverlay(name, `${path}.overlay`);
       const value = {type: 'image', src, ...fields, ...(overlay ? {overlay} : {})};
@@ -259,9 +315,11 @@ export function importImages({pictures, shapes, relationships, entries, slideInd
     if (edge !== undefined && edges.has(edge)) { delete fields.placement; invalid(path, `Two tagged OPF images are placed on the ${edge} edge; the second imports without its placement.`); }
     else if (edge !== undefined) edges.add(edge);
     const item = readPicture(picture);
-    const candidate = {...item?.payload, ...fields};
+    const source = restoredSource(manifest, picture);
+    const candidate = {...item?.payload, ...fields, ...(source !== undefined && object(item?.payload?.image) ? {image: {...item.payload.image, src: source}} : {})};
     if (!item?.payload || !valid('block', candidate)) { invalid(path, 'A tagged OPF image does not form a valid image block; it was imported as an ordinary picture.'); if (edge !== undefined) edges.delete(edge); continue; }
     blocks.set(index, fields);
+    if (source !== undefined && object(item.payload.image)) sources.set(index, source);
   }
   // The overlay of a native slide background fill.
   backgroundOverlay = takeOverlay('background', `${slide}.design.background.overlay`);
@@ -269,7 +327,7 @@ export function importImages({pictures, shapes, relationships, entries, slideInd
   for (const [owner, found] of overlays) if (!found.edited && !consumedShapes.has(found.index) && owner !== 'background') {
     invalid(`${slide}`, 'A tagged OPF image overlay no longer has its picture; it was imported as an ordinary shape.');
   }
-  return {blocks, background, backgroundOverlay, backgroundOverlayShape, consumed, consumedShapes};
+  return {blocks, sources, background, backgroundOverlay, backgroundOverlayShape, consumed, consumedShapes};
 }
 
 // opf-pptx#221: the "Image unavailable" placeholder of an image block whose source could not be embedded (a remote URL is never

package/dist/index.d.ts

@@ -34,6 +34,13 @@ export interface ImageResolverContext {
 }
 
 export interface MediaProvenanceDiagnostic { code: "media-provenance-omitted"; path: string; message: string }
+/** An opt-in native body could not represent this payload; current measured shapes were retained. */
+export interface NativeBodyFallbackDiagnostic {
+  code: "native-body-fallback";
+  path: string;
+  reason: "complex-composition" | "multi-column" | "unsupported-list" | "annotated-text" | "unsupported-text" | "overflow";
+  message: string;
+}
 /** The chart data cannot be plotted, so a placeholder frame stands in for the chart. */
 export interface ChartDataUnplottableDiagnostic { code: "chart-data-unplottable"; path: string; message: string; reason: "dataset-unknown" | "no-rows" | "no-columns" | "single-column-not-numeric" }
 /** Content with no PowerPoint export (an empty table, an unsupported payload) is replaced by a plain-language placeholder frame. */
@@ -81,6 +88,27 @@ export interface VariableExampleUsedDiagnostic {
 }
 
 export interface ToPptxOptions {
+  /**
+   * How a footer or header text with words around `{{slide.number}}` (`{{slide.number}} / {{deck.slideCount}}`, `Page {{slide.number}}`)
+   * writes its number. "static" (default) writes the number as fixed text in an ordinary shape, so PowerPoint and Keynote both show
+   * `2 / 6`; the total is fixed either way (PowerPoint has no slide-count field). "live" keeps PowerPoint's slide-number field (in the
+   * Slide Number placeholder for the first footer one) with the words as fixed runs: Keynote replaces the whole paragraph that holds a
+   * slide-number field with the number alone, so it shows only `2`. A text that is only `{{slide.number}}` keeps its live field and
+   * placeholder in both modes. A fixed number does not follow slides moved or deleted in PowerPoint; the authored text returns on import (RR-91).
+   */
+  slideNumberFields?: "static" | "live";
+  /**
+   * Prototype: "native" exports each supported paragraph or flat-bullet body (since 0.22.0 also a one-sequence numbered list) as
+   * one native body with native wrapping and no autofit: the first body of a slide is the Body placeholder, a further body region (since 0.22.0) is an
+   * ordinary native text box at its region. It retains selected fonts, effective alignment and region anchor,
+   * but native applications can choose different wraps and baselines from the measured preview. Unsupported groups,
+   * shared body regions, nested/description/restarted-numbered/multicolumn lists, annotations and complex text retain
+   * measured shapes with native-body-fallback diagnostics. Native paragraph separators normalize to LF on import.
+   * A plain-string title that wraps over several lines (no hard break, no overflow, no rich runs) is also one native text box
+   * with native wrap and no autofit, bound to the Title placeholder (since 0.22.0); an unwrapped title binds as before.
+   * Omitted or "measured" preserves the current measured-line export. No native application qualification is implied (Keynote 15.1.1 was checked for Title/Body controls and reflow, PowerPoint was not).
+   */
+  bodyText?: "measured" | "native";
   /** Default compatible converts WebP to a static PNG. Preserve embeds original WebP bytes. */
   imageFormat?: "compatible" | "preserve";
   /**
@@ -108,6 +136,14 @@ export interface ToPptxOptions {
    * also written as PowerPoint's native section list whatever this option says.
    */
   provenance?: "full" | "references-only" | false;
+  /**
+   * Literal footer text: "native" (default) keeps the first eligible one-line footer text bound to PowerPoint's Footer
+   * placeholder. "shape" omits only that slide-local ftr binding, retaining its measured editable text shape, locks,
+   * formatting, geometry, paint order and provenance. It stays on the slide, including when repeated. Live slide-number
+   * and date fields/placeholders, master/layout footer placeholders and flags remain unchanged. The literal shape then
+   * has no native Footer-dialog ownership; this does not guarantee viewer parity or restore tags another application strips.
+   */
+  footerText?: "native" | "shape";
   /**
    * Values for the deck's template variables, keyed by variable id (core `resolveVariables`). A deck that uses content
    * variables, or is marked `template: true`, is resolved to a concrete deck first; the PPTX holds the resolved text.
@@ -126,7 +162,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, and, from core's slide context, `unresolved-reference` (once per reference path) when a layout, theme, colour-scheme or font-scheme reference resolves nowhere (not embedded in the document's `catalogs` and not in a registered catalog): core's engine defaults are drawn instead, and a slide whose layout resolves nowhere, like one with no layout, composes automatically. None of them refuses the export unless `strictReferences` is set. */
-  onDiagnostic?: (diagnostic: LayoutDiagnostic | UnresolvedReferenceDiagnostic | MediaProvenanceDiagnostic | ChartDataUnplottableDiagnostic | ChartDataAdaptedDiagnostic | ChartMapGeodataDiagnostic | ChartValueNotNumericDiagnostic | ChartMappingAdaptedDiagnostic | DataProvenanceOmittedDiagnostic | ContentPlaceholderDiagnostic | UnresolvedAssetDiagnostic | SvgSanitizedDiagnostic | SvgImageRasterizedDiagnostic | VariableExampleUsedDiagnostic) => void;
+  onDiagnostic?: (diagnostic: LayoutDiagnostic | UnresolvedReferenceDiagnostic | MediaProvenanceDiagnostic | NativeBodyFallbackDiagnostic | ChartDataUnplottableDiagnostic | ChartDataAdaptedDiagnostic | ChartMapGeodataDiagnostic | ChartValueNotNumericDiagnostic | ChartMappingAdaptedDiagnostic | DataProvenanceOmittedDiagnostic | ContentPlaceholderDiagnostic | UnresolvedAssetDiagnostic | SvgSanitizedDiagnostic | SvgImageRasterizedDiagnostic | VariableExampleUsedDiagnostic) => void;
   baseDir?: string;
   compressionLevel?: number;
   imageResolver?: (src: string, context: ImageResolverContext) => ImageResolverResult | Promise<ImageResolverResult | null | undefined> | null | undefined;