@openpresentation/opf-pptx 0.14.0 → 0.15.0

package/dist/image-provenance.js

@@ -0,0 +1,273 @@
+import {XMLParser} from 'fast-xml-parser';
+import {normalizeCrop, withoutSvgBlip} from './svg-image.js';
+import {attachTextTags, decodeTextTag} from './code-provenance.js';
+
+// FA-23 (OPF 0.15): image blocks and image backgrounds as native pictures.
+//
+// Every image block (core ComposedItem.image) exports as one native picture at core's frame. Its fit and focus are an
+// a:srcRect; its treatments keep the DrawingML mapping 0.14's slide image used: the mask is a:prstGeom with core's guide
+// values, the border an a:ln centered on the outline with a miter join, and the recolor and opacity a:grayscl or
+// a:duotone then a:alphaModFix on the blip. An overlay is one native shape directly above its picture.
+//
+// An image background (core SlideComposition.backgroundImage) with alt text is a full-slide picture at the back of the
+// slide (screen readers read its descr); without alt it is the native slide background fill (src/background.js), and its
+// overlay is the first shape of the slide.
+//
+// OPF_IMAGE_V1 binds a picture to the image block's (or background's) own authored fields and the exact native geometry it
+// was written with, so an unchanged picture imports back with its treatments and placement while an edited one stays an
+// ordinary picture. OPF_IMAGE_OVERLAY_V1 does the same for an overlay shape: an edited overlay drops only the overlay.
+export const IMAGE_TAG = 'OPF_IMAGE_V1', IMAGE_OVERLAY_TAG = 'OPF_IMAGE_OVERLAY_V1';
+const REL = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/tags';
+const EMUS_PER_INCH = 914400;
+const parser = new XMLParser({ignoreAttributes:false, attributeNamePrefix:'', parseTagValue:false, trimValues:false});
+const decoder = new TextDecoder('utf-8', {fatal:true}), encoder = new TextEncoder();
+const array = value => value === undefined ? [] : Array.isArray(value) ? value : [value];
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+// Whitespace-only text between elements is not identity: the vendored writer indents, PowerPoint drops it on save.
+const canonical = value => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+  ? Object.fromEntries(Object.keys(item).sort().filter(key => !(key === '#text' && typeof item[key] === 'string' && !item[key].trim())).map(key => [key, item[key]])) : item);
+
+/** An image block's own fields (everything but its type, asset, id, caption and extensions). */
+export const IMAGE_TREATMENT_KEYS = Object.freeze(['fit', 'focus', 'shape', 'cornerRadius', 'border', 'opacity', 'recolor', 'overlay', 'aspectRatio', 'placement']);
+/** An image background's own fields besides its source. */
+export const BACKGROUND_IMAGE_KEYS = Object.freeze(['alt', 'fit', 'focus', 'opacity', 'recolor', 'overlay']);
+
+export const imageName = number => `OPF image ${number}`;
+export const imageOverlayName = pictureName => `${pictureName} overlay`;
+export const backgroundImageName = slide => `OPF background ${slide}`;
+export const backgroundOverlayName = slide => `OPF background overlay ${slide}`;
+
+// DrawingML for the shared treatment: preset geometry (core guide values), a centered solid line, and blip
+// recolor/alpha effects applied in that order.
+const presetXml = shape => `<a:prstGeom prst="${shape?.preset ?? 'rect'}"><a:avLst>${Object.entries(shape?.adjust ?? {}).map(([name, value]) => `<a:gd name="${name}" fmla="val ${value}"/>`).join('')}</a:avLst></a:prstGeom>`;
+const colorXml = ({hex, alpha}, extraAlpha = 1) => {
+  const value = Math.round(alpha * extraAlpha * 100000);
+  return `<a:srgbClr val="${hex}">${value < 100000 ? `<a:alpha val="${value}"/>` : ''}</a:srgbClr>`;
+};
+const lineXml = border => border ? `<a:ln w="${Math.round(border.width / 96 * EMUS_PER_INCH)}" algn="ctr"><a:solidFill>${colorXml(border)}</a:solidFill><a:miter lim="800000"/></a:ln>` : '';
+function blipEffects(effects) {
+  let xml = '';
+  if (effects?.recolor?.type === 'grayscale') xml += '<a:grayscl/>';
+  if (effects?.recolor?.type === 'duotone') xml += `<a:duotone>${colorXml({...effects.recolor.dark, alpha: 1})}${colorXml({...effects.recolor.light, alpha: 1})}</a:duotone>`;
+  if (typeof effects?.opacity === 'number') xml += `<a:alphaModFix amt="${Math.round(effects.opacity * 100000)}"/>`;
+  return xml;
+}
+
+// Native blip fill without its package-local relationship id.
+function blipFillIdentity(blipFill) {
+  const {['a:blip']: blip, ...rest} = normalizeCrop(blipFill) ?? {};
+  const {['r:embed']: _embed, ...blipRest} = withoutSvgBlip(blip) ?? {};
+  return {...rest, 'a:blip': blipRest};
+}
+
+// The focus point in the stored picture's own axes. DrawingML crops (a:srcRect) the picture before it flips and turns it
+// (the EXIF orientation is written as the frame's rot/flipH/flipV), so a point the author placed on the displayed
+// picture maps back through that orientation.
+function storedFocus({x, y}, orientation) {
+  switch (orientation) {
+    case 2: return {x: 1 - x, y};
+    case 3: return {x: 1 - x, y: 1 - y};
+    case 4: return {x, y: 1 - y};
+    case 5: return {x: y, y: x};
+    case 6: return {x: y, y: 1 - x};
+    case 7: return {x: 1 - y, y: 1 - x};
+    case 8: return {x: 1 - y, y: x};
+    default: return {x, y};
+  }
+}
+
+const srcRectValue = value => Math.round(value * 100000) || 0;
+
+/**
+ * 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
+ * fit math. A plain contain picture (`shrink`: a rectangle with no line or overlay) is framed by the picture itself, as
+ * 0.14 content images were; every other picture keeps the frame and pads with negative a:srcRect insets, so the mask,
+ * line and overlay apply to core's frame.
+ */
+export function pictureFrame(metadata, {box, fit, focus = {x: .5, y: .5}, shrink = false}, fitImage) {
+  const orientation = metadata.orientation ?? 1;
+  const target = orientation >= 5 ? {x: box.x + (box.w - box.h) / 2, y: box.y + (box.h - box.w) / 2, w: box.h, h: box.w} : box;
+  const rotation = [0, 0, 0, 180, 0, 90, 90, 90, 270][orientation];
+  const transform = {rotation, flipH: orientation === 2 || orientation === 7, flipV: orientation === 4 || orientation === 5};
+  // A tiled picture fills its frame with the picture at its intrinsic size; nothing is cropped.
+  if (fit === 'tile') return {...target, crop: null, ...transform};
+  const placed = fitImage({x: target.x, y: target.y, width: target.w, height: target.h}, fit, metadata.width / metadata.height, storedFocus(focus, orientation));
+  if (shrink && fit === 'contain') return {x: placed.image.x, y: placed.image.y, w: placed.image.width, h: placed.image.height, crop: null, ...transform};
+  const crop = {l: srcRectValue(placed.crop.left), t: srcRectValue(placed.crop.top), r: srcRectValue(placed.crop.right), b: srcRectValue(placed.crop.bottom)};
+  return {...target, crop: Object.values(crop).some(Boolean) ? crop : null, ...transform};
+}
+
+/**
+ * Place each generated image picture at its frame, write its treatment, place its overlay shape, then bind the tagged
+ * ones to their manifests. Runs after PptxGenJS embedded the bytes (the frame needs the raster's own size).
+ * images: Map<objectName, {slide, role: 'block' | 'background', path, box (inches), fit, focus, shrink, effects, treatment}>;
+ * `treatment` (the authored fields) is stored in OPF_IMAGE_V1 when present.
+ * overlays: Map<objectName, {slide, owner, box (reference px), shape, hex, alpha, opacity, overlay}>; `owner` is the
+ * 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}) {
+  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))) {
+    const xml = decoder.decode(entries[part]);
+    let next = xml.replace(/<p:pic>[\s\S]*?<\/p:pic>/g, picture => {
+      const name = picture.match(/<p:cNvPr\b[^>]*\bname="([^"]+)"/)?.[1];
+      const image = images.get(name);
+      if (!image) return picture;
+      const embed = picture.match(/<a:blip\b[^>]*r:embed="([^"]+)"/)?.[1];
+      const metadata = metadataFor(part, embed);
+      if (!metadata) fail(image.path);
+      const frame = pictureFrame(metadata, image, fitImage);
+      const emu = value => Math.round(value * EMUS_PER_INCH);
+      const attributes = `${frame.rotation ? ` rot="${frame.rotation * 60000}"` : ''}${frame.flipH ? ' flipH="1"' : ''}${frame.flipV ? ' flipV="1"' : ''}`;
+      picture = picture.replace(/<a:xfrm\b[^>]*>[\s\S]*?<\/a:xfrm>/, `<a:xfrm${attributes}><a:off x="${emu(frame.x)}" y="${emu(frame.y)}"/><a:ext cx="${emu(frame.w)}" cy="${emu(frame.h)}"/></a:xfrm>`);
+      picture = picture.replace(/<a:srcRect\b[^>]*\/>/, '');
+      if (frame.crop) picture = picture.replace('<a:stretch>', `<a:srcRect l="${frame.crop.l}" t="${frame.crop.t}" r="${frame.crop.r}" b="${frame.crop.b}"/><a:stretch>`);
+      if (image.fit === 'tile') picture = picture.replace(/<a:stretch>[\s\S]*?<\/a:stretch>|<a:stretch\/>/, `<a:tile tx="0" ty="0" sx="${srcRectValue((metadata.dpiX ?? 96) / 96)}" sy="${srcRectValue((metadata.dpiY ?? 96) / 96)}" flip="none" algn="tl"/>`);
+      const effects = image.effects;
+      if (effects) {
+        picture = picture.replace(/<a:prstGeom\b[\s\S]*?<\/a:prstGeom>/, presetXml(effects.shape) + lineXml(effects.border));
+        const blip = blipEffects(effects);
+        if (blip) picture = picture.replace(/<a:blip\b([^>]*?)(?:\/>|>([\s\S]*?)<\/a:blip>)/, (_, attributes, inner = '') => `<a:blip${attributes}>${blip}${inner}</a:blip>`);
+      }
+      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'])});
+      }
+      return picture;
+    });
+    next = next.replace(/<p:sp>[\s\S]*?<\/p:sp>/g, shape => {
+      const name = shape.match(/<p:cNvPr\b[^>]*\bname="([^"]+)"/)?.[1];
+      const overlay = overlays.get(name);
+      if (!overlay) return shape;
+      const emu = value => Math.round(value / 96 * EMUS_PER_INCH);
+      shape = shape.replace(/<p:spPr>[\s\S]*?<\/p:spPr>/, `<p:spPr><a:xfrm><a:off x="${emu(overlay.box.x)}" y="${emu(overlay.box.y)}"/><a:ext cx="${emu(overlay.box.width)}" cy="${emu(overlay.box.height)}"/></a:xfrm>${presetXml(overlay.shape)}<a:solidFill>${colorXml(overlay, overlay.opacity)}</a:solidFill><a:ln><a:noFill/></a:ln></p:spPr>`);
+      const node = parser.parse(shape)['p:sp'];
+      overlayManifests.set(name, {v: 1, slide: overlay.slide, owner: overlay.owner, overlay: overlay.overlay, properties: node['p:spPr']});
+      shaped.add(name);
+      return shape;
+    });
+    if (next !== xml) entries[part] = encoder.encode(next);
+  }
+  if (placed.size !== images.size) throw new Error('Missing generated image picture.');
+  if (shaped.size !== overlays.size) throw new Error('Missing generated image overlay.');
+  attachTextTags(entries, manifests, IMAGE_TAG, 'opfImage', 'image', {pictures: true});
+  attachTextTags(entries, overlayManifests, IMAGE_OVERLAY_TAG, 'opfImageOverlay', 'image overlay');
+}
+
+// ---------------------------------------------------------------------------
+// Import
+
+function readTags(container, relationships, entries) {
+  const tags = [];
+  let unreadable = false;
+  for (const link of array(container?.['p:tags'])) {
+    const rel = relationships.get(link['r:id']);
+    if (rel?.type !== REL || rel.targetMode === 'External' || !entries[rel.path]) { unreadable = true; continue; }
+    try { tags.push(...array(parser.parse(decoder.decode(entries[rel.path]))['p:tagLst']?.['p:tag'])); } catch { unreadable = true; }
+  }
+  return {tags, unreadable};
+}
+
+// The one tag of `name` on a shape, decoded, or null (absent); throws when it is ambiguous or sits beside another OPF tag.
+function ownTag(container, relationships, entries, name) {
+  const {tags, unreadable} = readTags(container, relationships, entries);
+  const own = tags.filter(tag => tag.name?.toUpperCase() === name);
+  if (!own.length) return null;
+  if (unreadable || own.length !== 1 || tags.some(tag => /^OPF_/i.test(tag.name) && tag.name.toUpperCase() !== name)) throw Error('Ambiguous image identity.');
+  return decodeTextTag(own[0].val);
+}
+
+const pick = (value, keys) => Object.fromEntries(keys.filter(key => Object.hasOwn(value, key)).map(key => [key, value[key]]));
+
+/**
+ * Recover image blocks and an image background from unchanged tagged pictures and overlays of one slide.
+ * - `blocks`: Map<picture index, fields> to merge into the ordinary image block read from that picture;
+ * - `background`: the slide's image background from its tagged back picture, with the picture's index in `consumed`;
+ * - `backgroundOverlay`: the authored overlay of a native slide background fill;
+ * - `consumedShapes`: the overlay shapes recovered (they are no content).
+ * 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}) {
+  const slide = `slides.${slideIndex}`;
+  const blocks = 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.
+  const overlays = new Map();
+  for (const [index, shape] of shapes.entries()) {
+    let manifest;
+    try { manifest = ownTag(shape['p:nvSpPr']?.['p:nvPr']?.['p:custDataLst'], relationships, entries, IMAGE_OVERLAY_TAG); }
+    catch { invalid(slide, 'A tagged OPF image overlay is ambiguous; it was imported as an ordinary shape.'); continue; }
+    if (manifest === null) continue;
+    const name = shape['p:nvSpPr']?.['p:cNvPr']?.name;
+    const expected = manifest?.owner === 'background' ? backgroundOverlayName(slide) : typeof manifest?.owner === 'string' ? imageOverlayName(manifest.owner) : undefined;
+    if (manifest?.v !== 1 || manifest.slide !== slide || name !== expected || !object(manifest.overlay) || canonical(shape['p:spPr']) !== canonical(manifest.properties)) {
+      overlays.set(manifest?.owner, {index, edited: true});
+      continue;
+    }
+    if (overlays.has(manifest.owner)) { overlays.set(manifest.owner, {index, edited: true}); continue; }
+    overlays.set(manifest.owner, {index, overlay: manifest.overlay});
+  }
+  const takeOverlay = (owner, path) => {
+    const found = overlays.get(owner);
+    if (!found) return undefined;
+    if (found.edited) {
+      invalid(path, 'The tagged OPF image overlay is missing, edited or ambiguous, so the image is recovered without its overlay; the remaining native shape is imported as ordinary content.');
+      return undefined;
+    }
+    consumedShapes.add(found.index);
+    return found.overlay;
+  };
+  const edges = new Set();
+  for (const [index, picture] of pictures.entries()) {
+    let manifest;
+    try { manifest = ownTag(picture['p:nvPicPr']?.['p:nvPr']?.['p:custDataLst'], relationships, entries, IMAGE_TAG); }
+    catch { invalid(slide, 'A tagged OPF image is ambiguous; it was imported as an ordinary picture.'); continue; }
+    if (manifest === null) continue;
+    const name = picture['p:nvPicPr']?.['p:cNvPr']?.name;
+    const role = manifest?.role;
+    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 {
+      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;
+      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} : {})};
+      if (typeof src !== 'string' || background || !valid('background', value)) { invalid(path, 'A tagged OPF background picture does not form a valid image background; it was imported as an ordinary picture.'); continue; }
+      background = value;
+      consumed.add(index);
+      continue;
+    }
+    const fields = pick(manifest.treatment, IMAGE_TREATMENT_KEYS.filter(key => key !== 'overlay'));
+    const overlay = takeOverlay(name, `${path}.overlay`);
+    if (overlay) fields.overlay = overlay;
+    // At most one placed block per edge: a copied tagged picture keeps its other fields and flows.
+    const edge = fields.placement?.edge;
+    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};
+    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);
+  }
+  // The overlay of a native slide background fill.
+  backgroundOverlay = takeOverlay('background', `${slide}.design.background.overlay`);
+  const backgroundOverlayShape = backgroundOverlay ? overlays.get('background').index : undefined;
+  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};
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { Finding, FontSchemeDiagnostic, Fonts, LayoutDiagnostic, SlideContextReferenceDiagnostic } from "@openpresentation/opf";
+import type { Catalog, Finding, Fonts, LayoutDiagnostic, UnresolvedReferenceDiagnostic } from "@openpresentation/opf";
 export declare const packageName = "@openpresentation/opf-pptx";
 
 export declare const releaseLane: Readonly<{
@@ -50,7 +50,7 @@ export interface ContentPlaceholderDiagnostic { code: "content-placeholder"; pat
 export interface UnresolvedAssetDiagnostic { code: "unresolved-asset"; path: string; message: string; reason?: "unsupported-format" | "svg-malformed" | "svg-no-size" | "svg-too-large" | "svg-unsafe" | "svg-rasterizer-unavailable" | "svg-render-failed" | "svg-unreadable" }
 /** An SVG picture had scripts, `foreignObject`, event handlers, references outside the file, `@import` rules or a DOCTYPE; they were removed from the embedded SVG (on import too). Nothing in an SVG is run or fetched. */
 export interface SvgSanitizedDiagnostic { code: "svg-sanitized"; path: string; message: string }
-/** An SVG slide image with a duotone recolor or a non-rectangular shape exports as its PNG raster, not as a native SVG picture, so the effect applies as in the preview (PowerPoint applies opacity, grayscale and a border to an SVG picture, and those stay native). */
+/** An SVG image block with a duotone recolor or a non-rectangular shape (or an SVG image background with the tile fit) exports as its PNG raster, not as a native SVG picture, so the effect applies as in the preview (PowerPoint applies opacity, grayscale and a border to an SVG picture, and those stay native). */
 export interface SvgImageRasterizedDiagnostic { code: "svg-image-rasterized"; path: string; message: string }
 /**
  * The chart data was reshaped to export a native chart: a single value column was plotted against row numbers; a one-series construct
@@ -119,8 +119,8 @@ export interface ToPptxOptions {
   fonts?: Fonts;
   /** 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, and, from core's slide context, `unresolved-theme`, `unresolved-color-scheme` and `unresolved-layout` (once per reference path) when an id matches no record: the default theme (`minimal`) and colour scheme (`cool-horizon`) are used, and a slide whose layout is unknown, like one with no layout, is composed with no layout record. None of them refuses the export. */
-  onDiagnostic?: (diagnostic: LayoutDiagnostic | FontSchemeDiagnostic | SlideContextReferenceDiagnostic | MediaProvenanceDiagnostic | ChartDataUnplottableDiagnostic | ChartDataAdaptedDiagnostic | ChartMapGeodataDiagnostic | ChartValueNotNumericDiagnostic | ChartMappingAdaptedDiagnostic | DataProvenanceOmittedDiagnostic | ContentPlaceholderDiagnostic | UnresolvedAssetDiagnostic | SvgSanitizedDiagnostic | SvgImageRasterizedDiagnostic | VariableExampleUsedDiagnostic) => void;
+  /** 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;
   baseDir?: string;
   compressionLevel?: number;
   imageResolver?: (src: string, context: ImageResolverContext) => ImageResolverResult | Promise<ImageResolverResult | null | undefined> | null | undefined;
@@ -134,6 +134,13 @@ export interface ToPptxOptions {
   svgRasterizer?: (svg: string, size: { width: number; height: number; scale: number; text: boolean }) => Uint8Array | Promise<Uint8Array>;
   seed?: number;
   strictAssets?: boolean;
+  /**
+   * Strict reference policy (OPF 0.15). When true, a layout, theme, colour-scheme or font-scheme reference that resolves
+   * nowhere throws `OPFPptxError` with code `unresolved-reference` (its `path` is the first reference's, its `diagnostics`
+   * core's `unresolved-reference` diagnostics) instead of composing automatically or drawing with the engine default.
+   * Default: the value of `strictAssets`.
+   */
+  strictReferences?: boolean;
   timestamp?: string;
   /**
    * ZIP calendar timestamps, including embedded workbooks, use UTC fields at
@@ -150,21 +157,28 @@ export interface ToPptxOptions {
    * PowerPoint updates on open. Without it a current date is reported as unresolved content.
    */
   date?: string;
-  /** Host-supplied catalog records, as in opf-render. Currently consulted for socialPlatforms (generated socials furniture). */
-  catalogs?: Record<string, { records?: unknown[] } | unknown[]>;
-  /** Records for presentation `catalogs.<kind>.source` URLs (a single source or each entry of an ordered search path), as in opf-render. Currently consulted for socialPlatforms. */
-  catalogSources?: Record<string, { records?: unknown[] } | unknown[]>;
+  /**
+   * The catalogs the host registered (core `Catalog[]`, as for opf-render and core's `resolveSlideContext`): each is matched
+   * against a document group's `catalogs.<group>.source`, and the first is the host default that bare ids use when the document
+   * omits `catalogs.default`. Never fetched. Every reference (slide layouts, themes, colour and font schemes) resolves in the
+   * document's embedded records first, then here; omitted or `[]`, only embedded records resolve. Register the gallery snapshot
+   * explicitly with `catalogs: [defaultCatalog]` from `@openpresentation/opf/catalog`.
+   */
+  catalogs?: readonly Catalog[];
 }
 
 export interface FromPptxOptions {
-  /** Reports native details that import cannot preserve, including code provenance fallback/reflow and grouped text transforms. Table paths identify native frame and row/cell indexes (including headers). Stored catalog references that no longer match the package report `design-reference-changed` / `layout-reference-changed` at the reference path; a slide layout id that resolves to no inline or bundled record reports `unresolved-layout-reference`; a slide whose imported blocks no longer fit the stored content structure reports `content-structure-changed` at `slides.N`, a block id repeated by a duplicated slide `duplicate-block-id`, and a footer section text that disagrees with PowerPoint's section list `section-reference-changed` (docs/document-roundtrip.md). */
+  /** Reports native details that import cannot preserve, including code provenance fallback/reflow and grouped text transforms. Table paths identify native frame and row/cell indexes (including headers). Stored catalog references that no longer match the package report `design-reference-changed` / `layout-reference-changed` at the reference path; a stored slide layout reference that resolves neither in the stored document catalogs, nor in the slide's own stored record, nor in `catalogs` reports `unresolved-reference`; a slide whose imported blocks no longer fit the stored content structure reports `content-structure-changed` at `slides.N`, a block id repeated by a duplicated slide `duplicate-block-id`, and a footer section text that disagrees with PowerPoint's section list `section-reference-changed` (docs/document-roundtrip.md). */
   onDiagnostic?: (diagnostic: {code: string; path: string; message: string}) => void;
   fallbackName?: string;
   schema?: string;
-  /** The export's host catalog records (as in ToPptxOptions). Currently used to recognize unedited socials lines, so authored handles return. */
-  catalogs?: Record<string, { records?: unknown[] } | unknown[]>;
-  /** The export's records for presentation `catalogs.<kind>.source` URLs (as in ToPptxOptions). Currently used for socialPlatforms. */
-  catalogSources?: Record<string, { records?: unknown[] } | unknown[]>;
+  /**
+   * The catalogs the host registered (core `Catalog[]`, as in ToPptxOptions; never fetched). Theme and colour-scheme recovery
+   * (FF-24) matches the package's theme against the first one, the host default: an exact colour-scheme match imports as its
+   * bare id and a corroborated theme name as `design.theme`. Without catalogs the colour scheme imports as an inline object and
+   * no theme id is recovered. A stored slide layout reference also resolves here.
+   */
+  catalogs?: readonly Catalog[];
   /**
    * Opt in to raw per-shape signals (see PptxSignals). `true` uses the default limits; an object lowers or raises them.
    * With it, `fromPptx` resolves to `{presentation, signals}`; without it (the default, also `false`/`null`) it resolves
@@ -178,8 +192,8 @@ export declare class OPFPptxError extends Error {
   readonly details: Record<string, unknown>;
   /** The `error` findings of the `format` check that refused the input or the imported presentation (`invalid-opf`, `invalid-import-opf`), or the variable errors (`unfilled-variables`, `invalid-variables`). */
   readonly findings?: Finding[];
-  /** The layout diagnostics behind a `layout-overflow` error. */
-  readonly diagnostics?: LayoutDiagnostic[];
+  /** The layout diagnostics behind a `layout-overflow` error, or core's `unresolved-reference` diagnostics behind a strict-export `unresolved-reference` error. */
+  readonly diagnostics?: LayoutDiagnostic[] | UnresolvedReferenceDiagnostic[];
   readonly path?: string;
   constructor(code: string, message: string, details?: Record<string, unknown>);
 }
@@ -390,7 +404,8 @@ export interface PptxOutlineSignal extends PptxColor {
 export interface PptxOpfLink {
   /**
    * "block" fed a block (`path`, `blockType`); "title", "subtitle" and "tag" fed that slide field. Other roles name a shape the
-   * importer consumed without a block of its own: "furniture" (footer, date, number, section), "slide-image", "watermark", "logo",
+   * importer consumed without a block of its own: "furniture" (footer, date, number, section), "background" (the picture of an image background),
+   * "image-overlay" (the overlay shape of an image background or image block), "watermark", "logo",
    * and the members of an OPF-tagged group ("code", "metric", "quote", "timeline", "media", "card-frame").
    */
   role: string;
@@ -489,7 +504,7 @@ export type ThemeScriptSelection = Partial<Record<"major" | "minor", Partial<Rec
 export type TypefaceViolationReason =
   | "foreign-typeface"
   | "foreign-theme-reference"
-  | "unresolved-theme-reference"
+  | "theme-reference-unresolved"
   | "empty-theme-reference"
   | "empty-typeface"
   | "foreign-script-supplement"