@openpresentation/opf-pptx 0.14.0 → 0.15.0

package/dist/index.js

@@ -33,7 +33,7 @@ import {attachFurnitureFields, furniturePartFields, lineFields, nativeFieldType}
 import {attachNativePlaceholders, defaultPlaceholderGeometry, nativeDateText, nativeFurnitureParts, writeNativeMasters} from './native-furniture.js';
 import {importImageOrientation} from './image-import.js';
 import {extractSignals, normalizeSignalOptions, themeFactsFor} from './import-signals.js';
-import {placeSlideImages, importSlideImage, slideImageName, slideImageOverlayName} from './slide-image-provenance.js';
+import {placeImages, importImages, imageName, imageOverlayName, backgroundImageName, backgroundOverlayName, IMAGE_TREATMENT_KEYS, BACKGROUND_IMAGE_KEYS} from './image-provenance.js';
 import {dedupeMedia} from './media-dedupe.js';
 import {placeWatermarks, importWatermark, importTextWatermark, tagTextWatermarks, watermarkName, watermarkTextName, watermarkBox, watermarkOpacity} from './watermark-provenance.js';
 import {placeLogos, importLogo, importLogoPlaceholders, logoName, LOGO_TAG} from './logo-provenance.js';
@@ -46,18 +46,18 @@ import { webpToPng, svgToPng, readLocalFile } from '#image-fallback';
 import { prepareSvg, svgDataUriBytes, svgRasterScale, svgBlipRelationship, attachSvgPictures } from './svg-image.js';
 import { rasterMetadata, pictureTransform, normalizeImageOrientation } from './image-geometry.js';
 import {
-  chartPaletteForFill, codeHighlightBands, codeHighlightColors, codeHighlightLines, codeLineNumbers, codeLineRuns, codeSyntaxPaletteForScheme, composeSlide,
-  DEFAULT_FONT_SCHEME, defaultSlideBackground, fitText, layoutTable, layoutWatermark, metricTrendMark, resolveCanvasDimensions, resolveColorRoles, resolveFontFamilies,
-  resolveTextStyle, textColorForFill, textWidthMeasurer, timelineMarkerShapes, timelineTextColor, tokenizeCode
+  catalogRecords, chartPaletteForFill, codeHighlightBands, codeHighlightColors, codeHighlightLines, codeLineNumbers, codeLineRuns, codeSyntaxPaletteForScheme, composeSlide,
+  ENGINE_DEFAULT_FONT_SCHEME, defaultSlideBackground, fitImage, fitText, layoutTable, layoutWatermark, metricTrendMark, resolveCanvasDimensions, resolveColorRoles, resolveFontFamilies,
+  resolveReference, resolveTextStyle, textColorForFill, textWidthMeasurer, timelineMarkerShapes, timelineTextColor, tokenizeCode
 } from "@openpresentation/opf/composition";
 import { colorContext, resolveColorRefValue, resolveExportColor, resolveVariableColors } from "./color-ref.js";
 import PptxGenJS from "../vendor/pptxgenjs/pptxgen.es.js";
 import { unzipSync, zipSync } from "fflate";
 import { XMLParser } from "fast-xml-parser";
 import {
-  catalogs as bundledCatalogs,
   hasContentVariables,
   isTemplate,
+  OPFCatalogsOptionError,
   resolveSlideContext as resolveCoreSlideContext,
   resolveVariables,
   validate
@@ -218,6 +218,12 @@ const CHART_COLORS = [
   "64748B"
 ];
 
+// The `catalogs` option is core's registered catalogs (`Catalog[]`). A value that is no array is core's
+// OPFCatalogsOptionError (code `invalid-catalogs`) up front; core checks each entry where it resolves a reference.
+function checkCatalogs(entry, catalogs) {
+  if (catalogs !== undefined && !Array.isArray(catalogs)) throw new OPFCatalogsOptionError(entry, `got ${catalogs === null ? 'null' : typeof catalogs}`);
+}
+
 export async function toPptx(input, options = {}) {
   if (options.imageFormat !== undefined && !['compatible', 'preserve'].includes(options.imageFormat)) {
     throw new OPFPptxError('invalid-image-format', 'imageFormat must be compatible or preserve.', {path: 'options.imageFormat'});
@@ -225,6 +231,11 @@ export async function toPptx(input, options = {}) {
   if (options.provenance !== undefined && !['full', 'references-only', false].includes(options.provenance)) {
     throw new OPFPptxError('invalid-provenance-option', "provenance must be 'full', 'references-only' or false.", {path: 'options.provenance'});
   }
+  // OPF 0.15 (FA-23): the host's registered catalogs (core `Catalog[]`, matched by `source`, never fetched) reach every core
+  // call that resolves a reference. Strict export (`strictReferences`, default `strictAssets`) fails on a reference that
+  // resolves nowhere instead of composing automatically or drawing with the engine default.
+  checkCatalogs('toPptx', options.catalogs);
+  options = {...options, strictReferences: options.strictReferences ?? options.strictAssets === true};
   const presentation = resolveTemplateInput(parseInput(input), options);
   assertValidBoundary(presentation);
   // `options.fonts` is the fonts handle (the renderer's loadFonts()); the exporter reads its measurement, wrapped so the package names the
@@ -236,10 +247,12 @@ export async function toPptx(input, options = {}) {
   context.imagePlaceholders = new Map();
   context.tableHeaders = new Map();
   context.tableCells = new Map();
-  context.imagePlacements = new Map();
+  // FA-23: every exported image picture (image blocks, the alt-text form of an image background, timeline pictures) and
+  // every image overlay shape, by object name (src/image-provenance.js).
+  context.images = new Map();
+  context.imageOverlays = new Map();
   context.svgPictures = new Map();
   context.pictureText = new Map();
-  context.slideImages = new Map();
   context.watermarks = new Map();
   context.textWatermarks = new Map();
   context.logos = new Map();
@@ -284,15 +297,19 @@ export async function toPptx(input, options = {}) {
     throw new OPFPptxError('invalid-chartex-mode', 'chartex must be auto, native or fallback.', {path: 'options.chartex'});
   }
   context.chartexMode = options.chartex ?? 'auto';
-  Object.assign(context, exportTheme(presentation, context));
+  Object.assign(context, exportTheme(presentation, context, options));
   context.reportedReferences = new Set();
   // Document references and metadata tags (FF-32, docs/document-roundtrip.md).
   context.documentProvenance = options.provenance === false ? null : documentProvenance(presentation, {
     mode: options.provenance ?? "full",
-    isCatalogId: (kind, id) => !!(findById(normalizeRecords(presentation.catalogs?.[kind]), id) ?? findById(defaultCatalog(kind), id)),
+    // Core's provenance of each slide's resolved layout (resolveSlideContext().resolved.provenance.layout) with its record.
+    layoutOf: index => {
+      const {resolved} = coreContext(presentation, index, options);
+      return resolved.provenance?.layout && resolved.layout ? {...resolved.provenance.layout, record: resolved.layout} : undefined;
+    },
     report: diagnostic => options.onDiagnostic?.(diagnostic)
   });
-  context.scriptFonts = planScriptFonts(presentation, options.onDiagnostic);
+  context.scriptFonts = planScriptFonts(presentation, options.onDiagnostic, {catalogs: options.catalogs});
   // Slide section labels become PowerPoint's native section list (src/sections.js).
   // A label is an XML attribute: the characters text runs reject are rejected here too.
   context.sections = presentation.slides.map((slide, index) => {
@@ -310,9 +327,10 @@ export async function toPptx(input, options = {}) {
     await addSlide(pptx, presentation, presentation.slides[index], index, context, options);
   }
 
-  // FF-08: pitchFamily per exported family, from each slide's resolved scheme.
+  // FF-08: pitchFamily per exported family, from each slide's resolved scheme, then the font schemes the document embeds
+  // and the registered catalogs its groups name (core catalogRecords).
   context.fontPitch = fontPitchFamilies(presentation.slides.map((slide, index) => exportSlideContext(presentation, index, context, options).fonts),
-    [...normalizeRecords(presentation.catalogs?.fontSchemes), ...defaultCatalog("fontSchemes")]);
+    catalogRecords(presentation, "fontSchemes", {catalogs: options.catalogs}).map(entry => entry.record));
 
   let raw;
   try {
@@ -332,6 +350,9 @@ export async function toPptx(input, options = {}) {
 export async function fromPptx(input, options = {}) {
   // Opt-in raw shape signals (import-signals.js). Validated first so a bad option fails before any work.
   const signalLimits = normalizeSignalOptions(options.signals, (code, message, details) => new OPFPptxError(code, message, details));
+  // OPF 0.15 (FA-23): catalogs the host registered (core `Catalog[]`, never fetched). Theme and colour-scheme recovery and
+  // stored layout ids resolve against them; with none, a colour scheme imports inline and no theme id is recovered.
+  checkCatalogs('fromPptx', options.catalogs);
   const entries = readPptxZip(input);
   const presentationDoc = parseRequiredXml(entries, "ppt/presentation.xml");
   const presentationRoot = presentationDoc["p:presentation"];
@@ -365,12 +386,12 @@ export async function fromPptx(input, options = {}) {
       const theme = relatedPart(relatedPart(relatedPart(path, 'slideLayout'), 'slideMaster'), 'theme');
       return theme ? {path: theme, xml: decodeText(entries[theme])} : null;
     }),
-    catalogs: bundledCatalogs
+    catalogs: options.catalogs
   });
   if (observedLanguage.language !== undefined) imported.language = observedLanguage.language;
   if (core.description) imported.description = core.description;
   if (core.author) imported.author = splitAuthors(core.author);
-  const themeDesign = importThemeDesign(entries, presentationRoot, presentationRels);
+  const themeDesign = importThemeDesign(entries, presentationRoot, presentationRels, options.catalogs);
   const design = {...themeDesign.design, ...(dimensions ? {dimensions} : {})};
   if (Object.keys(design).length) imported.design = design;
 
@@ -399,7 +420,7 @@ export async function fromPptx(input, options = {}) {
   const mediaRegistry = Object.create(null);
   for (let index = 0; index < slidePaths.length; index += 1) {
     furnitureContexts[index].mediaRegistry = mediaRegistry;
-    imported.slides.push(importSlide(entries, slidePaths[index], index, dimensions, {...options, rtlDeck: observedRtl(observedLanguage), deckLang: observedLanguage.lang, codeFamily: Object.keys(entries).some(path => /^ppt\/tags\/opf/i.test(path)) ? importedCodeFamily(imported.design) : undefined, dataProvenance: {datasets}}, furniture.slides[index], furnitureContexts[index]));
+    imported.slides.push(importSlide(entries, slidePaths[index], index, dimensions, {...options, rtlDeck: observedRtl(observedLanguage), deckLang: observedLanguage.lang, codeFamily: Object.keys(entries).some(path => /^ppt\/tags\/opf/i.test(path)) ? importedCodeFamily(imported, options.catalogs) : undefined, dataProvenance: {datasets}}, furniture.slides[index], furnitureContexts[index]));
   }
   if (datasets) imported.datasets = datasets;
   // Native sections (PowerPoint's own section list, `Default Section` = none)
@@ -430,8 +451,8 @@ export async function fromPptx(input, options = {}) {
   let restoredGroups = [];
   try {
     const restored = restoreDocumentProvenance(imported, {entries, presentationRoot, presentationRels, organizationConflict: furniture.organizationConflict === true, speakerConflict: furniture.speakerConflict === true,
-      // Host catalogs format stored socials exactly as export did (FF-34).
-      socialPlatformRecords: catalogs => socialPlatformRecords({catalogs}, options),
+      // Stored layout ids also resolve in the host's registered catalogs (FA-23).
+      catalogs: options.catalogs,
       nativeSections: slideSections,
       slides: slidePaths.map((path, index) => ({path, root: furnitureContexts[index].root, relationships: furnitureContexts[index].relationships, contentBounds: furnitureContexts[index].contentBounds}))}, report);
     // The stored language wins while the runs still carry its tag (FF-07).
@@ -632,13 +653,14 @@ function readCoreProperties(entries) {
 }
 
 // FA-13: the code family of the imported design's font scheme (a run in it is an inline code run). The scheme's own `code` role,
-// else the bundled record's, else the shared fallback; heading and body families are never code. Only a package the exporter
-// wrote (it carries OPF tag parts) is read this way; a deck from another tool keeps its runs' font families as they are.
-function importedCodeFamily(design) {
-  const reference = design?.fontScheme;
+// else that of the record the reference resolves to (in the imported document or the host's registered catalogs), else the
+// engine default's; heading and body families are never code. Only a package the exporter wrote (it carries OPF tag parts) is
+// read this way; a deck from another tool keeps its runs' font families as they are.
+function importedCodeFamily(imported, catalogs) {
+  const reference = imported.design?.fontScheme;
   const id = referenceId(reference);
-  const base = (id && findById(defaultCatalog("fontSchemes"), id)) || findById(defaultCatalog("fontSchemes"), DEFAULT_FONT_SCHEME);
-  return resolveFontFamilies({...base, ...(isPlainObject(reference) ? reference : {})}).code;
+  const found = id ? resolveReference(imported, "fontSchemes", id, {catalogs: catalogs ?? []}) : undefined;
+  return resolveFontFamilies({...(found ? found.record : ENGINE_DEFAULT_FONT_SCHEME), ...(isPlainObject(reference) ? reference : {})}).code;
 }
 
 function dimensionsFromPresentation(presentationRoot) {
@@ -662,20 +684,28 @@ function importSlide(entries, slidePath, slideIndex, presentationDimensions, opt
   const background = importBackground(slidePath, resolveCanvasDimensions(dimensions), {
     part: (path, parser) => parseRequiredXml(entries, path, parser), relationships: path => parseRelationships(entries, path), bytes: path => entries[path]
   }, diagnostic => options.onDiagnostic?.({...diagnostic, path: `slides.${slideIndex}.design.background`}));
-  if (background) slide.design = {background};
+  // FA-23: tagged image pictures and overlays (OPF_IMAGE_V1, OPF_IMAGE_OVERLAY_V1). An unchanged full-slide back picture is
+  // the slide's image background (its native fill is then only the canvas colour); an unchanged overlay of a native image
+  // background fill joins that background; an unchanged image block picture returns its treatment and placement.
+  const images = importImages({pictures: nativeContext.pictures, shapes: nativeContext.shapes, relationships, entries, slideIndex,
+    readPicture: picture => importPicture(entries, picture, slidePath, relationships, diagnostic => {
+      // The recorded crop, fit and focus are re-derived from the restored background.
+      if (diagnostic.code !== 'unsupported-image-crop') options.onDiagnostic?.({...diagnostic, path: `slides.${slideIndex}.design.background`});
+    }),
+    valid: (kind, value) => isValidFormat({slides: [kind === 'background' ? {design: {background: value}} : {blocks: [value]}]}),
+    report: diagnostic => options.onDiagnostic?.(diagnostic)});
+  const imageBackground = images.background ?? (background?.type === 'image' && images.backgroundOverlay ? {...background, overlay: images.backgroundOverlay} : background);
+  if (images.backgroundOverlay && imageBackground === background) {
+    images.consumedShapes.delete(images.backgroundOverlayShape);
+    options.onDiagnostic?.({code: 'invalid-image-provenance', path: `slides.${slideIndex}.design.background.overlay`, message: 'The tagged OPF background overlay no longer sits on an image background; it was imported as an ordinary shape.'});
+  }
+  if (imageBackground) slide.design = {background: imageBackground};
   if (Object.keys(furniture.design).length) slide.design = {...slide.design, ...furniture.design};
   if (furniture.section !== undefined) slide.section = furniture.section;
-  const slideImagePath = `slides.${slideIndex}.design.slideImage`;
-  const slideImage = importSlideImage(nativeContext.pictures, nativeContext.shapes, relationships, entries, slideIndex,
-    picture => importPicture(entries, picture, slidePath, relationships, diagnostic => {
-      // The recorded crop/fit is re-derived from design.slideImage.
-      if (diagnostic.code !== 'unsupported-image-crop') options.onDiagnostic?.({...diagnostic, path: slideImagePath});
-    }),
-    diagnostic => options.onDiagnostic?.({...diagnostic, path: slideImagePath}));
-  if (slideImage.design) slide.design = {...slide.design, ...slideImage.design};
-  if (slideImage.image) slide.image = slideImage.image;
-  nativeContext.slideImagePictures = slideImage.consumed;
-  nativeContext.slideImageShapes = slideImage.consumedShapes;
+  nativeContext.imageBlocks = images.blocks;
+  nativeContext.imagePictures = images.consumed;
+  // An overlay of a background that was not recovered stays an ordinary shape.
+  nativeContext.imageShapes = images.consumedShapes;
   const watermarkPath = `slides.${slideIndex}.design.watermark`;
   // FA-13: a text watermark is a tagged native text box; it is not content and never imports as a text block.
   const textWatermark = importTextWatermark(nativeContext.shapes, nativeContext.paragraphs.map(shapeParagraphs => shapeParagraphs.map(paragraph => ({text: paragraph.text}))), relationships, entries, slideIndex,
@@ -833,10 +863,10 @@ function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensi
   for (const item of metric.items) items.push({kind:'metric',bounds:shapeBounds(item.shape['p:spPr']?.['a:xfrm']),payload:item.payload,sources:sourcesOf([item.shape])});
   for (const item of media.items) items.push({kind:'media',sourceText:item.payload.type==='text',bounds:shapeBounds(item.shape['p:spPr']?.['a:xfrm']),payload:item.payload,sources:sourcesOf([item.shape])});
   for (const [index,shape] of shapes.entries()) {
-    const role = furniture.text.has(index) ? 'furniture' : nativeContext.slideImageShapes?.has(index) ? 'slide-image' : nativeContext.watermarkShapes?.has(index) ? 'watermark' : nativeContext.logoPlaceholderShapes?.has(index) ? 'logo' : cards.has(shape) ? 'card-frame'
+    const role = furniture.text.has(index) ? 'furniture' : nativeContext.imageShapes?.has(index) ? 'image-overlay' : nativeContext.watermarkShapes?.has(index) ? 'watermark' : nativeContext.logoPlaceholderShapes?.has(index) ? 'logo' : cards.has(shape) ? 'card-frame'
       : code.consumed.has(shape) ? 'code' : metric.consumed.has(shape) ? 'metric' : media.consumed.has(shape) ? 'media' : timelines.consumed.has(shape) ? 'timeline' : quotes.consumed.has(shape) ? 'quote' : undefined;
     if (role) roles.set(shapeKeys.get(shape), role);
-    if (furniture.text.has(index) || nativeContext.slideImageShapes?.has(index) || nativeContext.watermarkShapes?.has(index) || nativeContext.logoPlaceholderShapes?.has(index)) continue;
+    if (furniture.text.has(index) || nativeContext.imageShapes?.has(index) || nativeContext.watermarkShapes?.has(index) || nativeContext.logoPlaceholderShapes?.has(index)) continue;
     if (annotations.consumed.has(shape)) { roles.set(shapeKeys.get(shape), 'annotation'); continue; }
     if (code.consumed.has(shape)||metric.consumed.has(shape)||cards.has(shape)||media.consumed.has(shape)||headings.consumed.has(shape)||plainText.consumed.has(shape)||timelines.consumed.has(shape)||quotes.consumed.has(shape)) continue;
     const ordinaryBody = Object.hasOwn(shape, 'p:txBody') && !shape['p:nvSpPr']?.['p:nvPr']?.['p:custDataLst']?.['p:tags'];
@@ -872,10 +902,13 @@ function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensi
   }
 
   for (const [index, picture] of nativeContext.pictures.entries()) {
-    const pictureRole = furniture.pictures.has(index) ? 'furniture' : nativeContext.slideImagePictures?.has(index) ? 'slide-image' : nativeContext.watermarkPictures?.has(index) ? 'watermark' : nativeContext.logoPictures?.has(index) ? 'logo' : quotes.consumedPictures.has(picture) ? 'quote' : undefined;
+    const pictureRole = furniture.pictures.has(index) ? 'furniture' : nativeContext.imagePictures?.has(index) ? 'background' : nativeContext.watermarkPictures?.has(index) ? 'watermark' : nativeContext.logoPictures?.has(index) ? 'logo' : quotes.consumedPictures.has(picture) ? 'quote' : undefined;
     if (pictureRole) { roles.set(`pic:${index}`, pictureRole); continue; }
-    const report = diagnostic => options.onDiagnostic?.({...diagnostic, path: `slides.${slideIndex}.pictures.${index}`});
+    // A tagged, unchanged image block brings back its own fields (fit, focus, treatment, placement); its crop is theirs.
+    const treatment = nativeContext.imageBlocks?.get(index);
+    const report = diagnostic => { if (!(treatment && diagnostic.code === 'unsupported-image-crop')) options.onDiagnostic?.({...diagnostic, path: `slides.${slideIndex}.pictures.${index}`}); };
     const item = importPicture(entries, picture, slidePath, relationships, report);
+    if (item?.payload && treatment) item.payload = {...item.payload, ...structuredClone(treatment)};
     if (item) items.push({...item, sources: [`pic:${index}`]});
   }
 
@@ -1628,8 +1661,17 @@ function assertValidBoundary(presentation) {
 // RR-55: what a slide (or, for the deck level, an empty slide) resolves to in core, the one chain every engine shares: canvas,
 // layout, font families, alignment and content box as composeSlide's options, plus the theme, colour scheme and font scheme
 // records they came from. `diagnostics` names references that matched no record.
+// Core's slide context with the host's registered catalogs. Under strict export core throws OPFUnresolvedReferenceError for a
+// reference that resolves nowhere; the export fails with `unresolved-reference` naming the first one (its path and every diagnostic).
 function coreContext(presentation, index, options) {
-  return resolveCoreSlideContext(presentation, index, {fonts: options.textMeasurement ? {textMeasurement: options.textMeasurement} : undefined, date: options.date});
+  try {
+    return resolveCoreSlideContext(presentation, index, {fonts: options.textMeasurement ? {textMeasurement: options.textMeasurement} : undefined, date: options.date,
+      ...(options.catalogs !== undefined ? {catalogs: options.catalogs} : {}), strictReferences: options.strictReferences === true});
+  } catch (error) {
+    if (error?.name !== "OPFUnresolvedReferenceError" || !Array.isArray(error.diagnostics)) throw error;
+    const [first] = error.diagnostics;
+    throw new OPFPptxError("unresolved-reference", `Strict export: ${error.message}`, {path: first?.path, diagnostics: error.diagnostics});
+  }
 }
 
 // The families composition and the package use: core's, with the measurement provider's own resolution of the chosen family
@@ -1644,8 +1686,8 @@ function exportFonts(core, textMeasurement) {
 function resolvePresentationContext(presentation, options, core = coreContext({...presentation, slides: [{}]}, 0, {...options, textMeasurement: undefined})) {
   const design = presentation.design ?? {};
   // `core` defaults to the deck level: the resolution of a slide that sets nothing of its own.
-  // The theme and colour scheme records come from core, which falls back to the default records (reporting unresolved-theme and
-  // unresolved-color-scheme) for a reference that matches no record.
+  // The theme and colour scheme records come from core, which falls back to the engine defaults (reporting unresolved-reference)
+  // for a reference that resolves nowhere.
   const {theme, colorScheme} = core.resolved;
   const dimensions = {widthInches: core.options.width / 96, heightInches: core.options.height / 96};
   const variables = resolveVariableColors(presentation.variables);
@@ -1776,20 +1818,28 @@ function masterBackground(context) {
 }
 
 // The theme part carries the deck-level scheme (slide overrides stay literal)
-// and, for an explicit catalog theme, that theme's name.
-function exportTheme(presentation, context) {
+// and, for a theme reference that resolves (embedded or in a registered catalog), that theme's name, which import
+// recovery matches against the registered catalogs (FF-24).
+function exportTheme(presentation, context, options) {
   const reference = presentation.design?.theme;
-  const id = referenceId(reference);
-  const theme = id ? context.theme : null;
+  const theme = typeof reference === "string" ? resolveReference(presentation, "themes", reference, {catalogs: options.catalogs}) : undefined;
   const scheme = context.colorScheme;
   return {
     themeColors: themeSlotColors(scheme),
     schemeName: scheme.name ?? scheme.id ?? "OpenPresentation",
-    themeName: theme?.id === id ? theme.name ?? theme.id : undefined
+    themeName: theme ? theme.record.name ?? theme.id : undefined
   };
 }
 
-function importThemeDesign(entries, presentationRoot, presentationRels) {
+// FF-24 recovery against the host's registered catalogs (FA-23). Only the first registered catalog, the host default, can be
+// named by a bare id in a document that declares no catalogs, so only its records are matched: an exact match imports as
+// that bare id. Everything else (no catalog registered, a scheme from another registered catalog, no exact match) imports
+// as an inline colour scheme, and no theme id is recovered.
+function hostDefaultRecords(kind, catalogs) {
+  return catalogRecords({}, kind, {catalogs: catalogs ?? []}).filter(entry => entry.group === "default").map(entry => ({...entry.record, id: entry.id}));
+}
+
+function importThemeDesign(entries, presentationRoot, presentationRels, catalogs) {
   const diagnostics = [], design = {};
   const report = (code, path, message) => diagnostics.push({code, path, message});
   const themePath = presentationThemePath(presentationRoot, presentationRels, path => parseRelationships(entries, path), entries);
@@ -1801,16 +1851,22 @@ function importThemeDesign(entries, presentationRoot, presentationRels) {
     return {design, diagnostics};
   }
   const {colors, unreadable} = readThemeSlotColors(clrScheme);
-  const records = defaultCatalog("colorSchemes");
+  const records = hostDefaultRecords("colorSchemes", catalogs);
   if (Object.keys(colors).length) design.colorScheme = recoverColorScheme({colors, unreadable, name: scalarText(clrScheme.name)}, records).value;
   if (unreadable.length) report("unsupported-theme-colors", "design.colorScheme", `Theme color slot(s) ${unreadable.join(", ")} do not resolve to an opaque sRGB color and were not imported.`);
   const latin = font => scalarText(elements?.["a:fontScheme"]?.[font]?.["a:latin"]?.typeface);
+  // A theme's own colour and font scheme references resolve in the theme's group first (core resolveReference).
+  const themeReference = (kind, reference) => {
+    const id = referenceId(reference);
+    const found = id ? resolveReference({}, kind, id, {catalogs: catalogs ?? [], group: "default"}) : undefined;
+    return found ? {...found.record, ...(isPlainObject(reference) ? reference : {})} : null;
+  };
   const recoveredTheme = recoverTheme({themeName: scalarText(theme?.name), colors, majorFont: latin("a:majorFont"), minorFont: latin("a:minorFont")}, {
-    themes: defaultCatalog("themes"),
-    colorSchemes: records,
-    fontFamilies: id => {
-      const record = findById(defaultCatalog("fontSchemes"), id);
-      return record ? resolveFontFamilies(record) : null;
+    themes: hostDefaultRecords("themes", catalogs),
+    colorScheme: record => themeReference("colorSchemes", record.colorScheme),
+    fontFamilies: record => {
+      const scheme = themeReference("fontSchemes", record.fontScheme);
+      return scheme ? resolveFontFamilies(scheme) : null;
     }
   });
   if (recoveredTheme.unverified) report("theme-unverified", "design.theme", `The native theme has the name of OPF catalog theme '${recoveredTheme.unverified}', but neither its color scheme nor its heading/body fonts match that theme, so design.theme was not set.`);
@@ -1839,52 +1895,43 @@ async function addSlide(pptx, presentation, opfSlide, slideIndex, context, optio
   const slide = pptx.addSlide();
   const slideContext = exportSlideContext(presentation, slideIndex, context, options);
   const { widthInches, heightInches } = slideContext.dimensions;
-  // A slide with no layout, or one that names a layout no catalog defines, is composed with no layout record (automatic composition),
-  // as in the preview; core reports the unknown id as unresolved-layout.
+  // A slide with no layout, or one whose layout resolves nowhere, is composed with no layout record (automatic composition),
+  // as in the preview; core reports the reference as unresolved-reference.
   // Core's resolved options (canvas, layout, families, alignment, content box, darkBackground), with the exporter's own additions:
-  // the families after the measurement provider's resolution of the chosen family, the raster padding and the host's social platform records.
-  const composeOptions = { ...slideContext.core.options, fontFamilies: slideContext.composeFonts, textRasterPadding:options.textRasterPadding, socialPlatforms: socialPlatformRecords(presentation, options) };
+  // the families after the measurement provider's resolution of the chosen family and the raster padding. Core formats socials
+  // handles from its own SOCIAL_PLATFORMS vocabulary.
+  const composeOptions = { ...slideContext.core.options, fontFamilies: slideContext.composeFonts, textRasterPadding:options.textRasterPadding };
   // Core resolves every shared design key once (slide design, deck design, then the layout record's design): the text alignment of
-  // each item (item.alignment), and the imageFill that backgrounds and picture placements use (SlideComposition.design).
+  // each item (item.alignment), and each image item's own fit and treatment (item.image).
   const geometry = composeSlide(opfSlide, composeOptions);
-  slideContext.imageFill = geometry.design.imageFill ?? "fit";
   // The default footer band (date left, text center, number right): where a footer added natively lands (RR-11).
   if (slideIndex === 0) context.defaultFooterOptions = composeOptions;
   slide.background = { color: slideContext.colors.background };
-  const backgroundDefinition = slideContext.backgroundDefinition;
+  // An image background is core's geometry.backgroundImage (slide, deck, then theme background); every other kind is the
+  // effective design or theme background definition.
+  const backgroundDefinition = geometry.backgroundImage ? undefined : slideContext.backgroundDefinition;
   const backgroundPath = `${opfSlide.design?.background !== undefined ? `slides.${slideIndex}.` : ''}design.background`;
-  const backgroundFill = schemeBackgroundFill(backgroundDefinition, slideContext) ?? nativeBackgroundFill(backgroundDefinition, {
+  const backgroundFill = backgroundDefinition === undefined ? null : schemeBackgroundFill(backgroundDefinition, slideContext) ?? nativeBackgroundFill(backgroundDefinition, {
     width: slideContext.dimensions.widthInches, height: slideContext.dimensions.heightInches
   }, slideContext.colors.background, slideContext.colors.text, (reference, hex) => schemeColorValue(reference, hex, slideContext), reference => resolveBackgroundColorRef(reference, slideContext.colorScheme, slideContext.variables));
   if (backgroundFill) context.backgroundFills.set(`ppt/slides/slide${slideIndex + 1}.xml`, backgroundFill);
   if (backgroundDefinition?.type === 'pattern' && !nativePatternPreset(backgroundDefinition.pattern?.preset)) {
     options.onDiagnostic?.({code: 'unsupported-pattern', path: `${backgroundPath}.pattern.preset`, message: `Pattern ${backgroundDefinition.pattern?.preset} has no DrawingML preset; only its background color was exported.`});
   }
-  if (backgroundDefinition?.type === 'image') {
-    const imagePath = `${backgroundPath}.image`;
-    // An SVG background is its PNG raster at the slide's size: a slide background picture fill carries no SVG.
-    const outcome = { box: { w: slideContext.dimensions.widthInches, h: slideContext.dimensions.heightInches }, cover: (backgroundDefinition.image?.fit ?? 'cover') !== 'contain' };
-    const resolved = await resolveImage(backgroundDefinition.image, presentation, options, imagePath, outcome);
-    if (resolved) {
-      // PptxGenJS embeds the raster and its relationship; packaging replaces
-      // its stretched fill with the fitted native picture fill.
-      slide.background = { ...resolved };
-      context.backgroundFills.set(`ppt/slides/slide${slideIndex + 1}.xml`, { image: {
-        fit: backgroundDefinition.image?.fit ?? 'cover', opacity: backgroundDefinition.opacity ?? 1, imageFill: slideContext.imageFill, path: imagePath,
-        width: slideContext.dimensions.widthInches * 96, height: slideContext.dimensions.heightInches * 96, report: options.onDiagnostic
-      } });
-    } else if (!outcome.reported) {
-      options.onDiagnostic?.({code: 'unresolved-asset', path: imagePath, message: 'The background image needs an embedded raster, a declared asset or a host imageResolver; the slide background color was exported instead.'});
-    }
-  }
   slide.color = slideContext.textColor;
   if (opfSlide.hidden === true) slide.hidden = true;
 
   for (const diagnostic of geometry.diagnostics) options.onDiagnostic?.(diagnostic);
   // The content topology (groups, regions, root form, block ids) with the leaf boxes this geometry draws.
   recordContentTopology(context.documentProvenance, opfSlide, slideIndex, geometry.items);
-  // The preview paints background, slide image (and its overlay), then design.watermark, then content.
-  if (geometry.slideImage) await addSlideImage(slide, presentation, geometry.slideImage, slideIndex, slideContext, options);
+  // Paint order, as in the preview (FA-22 contract): canvas colour, the background picture and its overlay, design.watermark,
+  // the logo, then the items in core's order: the headings, the placed image blocks at their bands, then the flowed body.
+  if (geometry.backgroundImage) await addBackgroundImage(slide, presentation, geometry.backgroundImage, slideIndex, slideContext, context, options);
+  // RR-34: a captioned image's caption band follows its picture as tagged text boxes linked to the picture by name.
+  const drawImage = async (item, itemContext) => {
+    const name = await addImageItem(slide, presentation, item, slideIndex, itemContext, options);
+    if (item.caption) addCaption(slide, item, name, itemContext, exportHelpers, (code, message) => new OPFPptxError(code, message, {path: item.caption.path}));
+  };
   await addWatermark(slide, presentation, opfSlide, slideIndex, slideContext, context, options);
   // Cover and section slides: the deck logo core composed at the top-left of the free area, after the watermark and before content.
   if (geometry.logo) await addLogo(slide, presentation, geometry.logo, slideIndex, slideContext, context, options);
@@ -1932,12 +1979,14 @@ async function addSlide(pptx, presentation, opfSlide, slideIndex, context, optio
       });
     } else if (item.field === "text" && typeof item.value === "string") {
       slide.addText(item.text.lines.join("\n"), {...textBoxOptions(region, itemContext, item.text.fontSize * 0.75),...nativeFontOptions(item.textStyle),align:physicalAlignment(item.alignment, item.text.directions?.[0])});
+    } else if (item.field === "image" && item.image) {
+      await drawImage(item, itemContext);
     } else {
       // RR-34: a captioned item draws its media in item.box; the caption band follows as tagged text boxes linked to the media shape by name.
-      const mediaNames = item.caption ? new Set([...context.imagePlacements.keys(), ...context.imagePlaceholders.keys(), ...context.chartHeadings.keys(), ...context.tableHeaders.keys()]) : undefined;
+      const mediaNames = item.caption ? new Set([...context.images.keys(), ...context.imagePlaceholders.keys(), ...context.chartHeadings.keys(), ...context.tableHeaders.keys()]) : undefined;
       await addPayload(slide, presentation, item.payload, region, item.path, { ...itemContext, composition: item.composition, contentAlignment: item.alignment ?? "left", direction: geometry.direction }, options, item.quoteLayout, item.codeLayout,item.metricLayout,item.timelineLayout);
       if (item.caption) {
-        const mediaName = item.field === 'video' ? `OPF media ${item.path} frame` : [...context.imagePlacements.keys(), ...context.imagePlaceholders.keys(), ...context.chartHeadings.keys(), ...context.tableHeaders.keys()].find(name => !mediaNames.has(name));
+        const mediaName = item.field === 'video' ? `OPF media ${item.path} frame` : [...context.images.keys(), ...context.imagePlaceholders.keys(), ...context.chartHeadings.keys(), ...context.tableHeaders.keys()].find(name => !mediaNames.has(name));
         addCaption(slide, item, mediaName, itemContext, exportHelpers, (code, message) => new OPFPptxError(code, message, {path: item.caption.path}));
       }
     }
@@ -2153,27 +2202,131 @@ function addListPayload(slide, items, region, context) {
   slide.addText(runs, textBoxOptions(region, context, 15));
 }
 
+// A content picture outside an image block (a timeline event image): one native picture contained in its region.
 async function addImagePayload(slide, presentation, asset, region, path, context, options) {
-  const outcome = { box: region, cover: context.imageFill === 'crop' };
+  const name = await addImagePicture(slide, presentation, asset, region, path, context, options, {fit: 'contain'});
+  if (!name) addImagePlaceholder(slide, presentation, asset, region, path, context, options);
+  return name;
+}
+
+// One native image picture at `box` (inches), fitted at packaging (src/image-provenance.js placeImages). `treatment` is
+// what OPF_IMAGE_V1 stores (the authored block fields); without it the picture is untagged. Returns the picture's object
+// name, or undefined when the source could not be embedded (the caller draws the unavailable-image panel).
+async function addImagePicture(slide, presentation, asset, box, path, context, options, {fit, focus, effects = null, shrink = true, treatment, alt, role = 'block', objectName} = {}) {
+  const outcome = { box, cover: fit === 'cover' };
   const resolved = await resolveImage(asset, presentation, options, path, outcome);
-  if (!resolved) {
-    addImagePlaceholder(slide, presentation, asset, region, path, context, options);
-    return;
+  if (!resolved) return undefined;
+  const name = objectName ?? imageName(1 + [...context.images.keys()].filter(key => /^OPF image \d+$/.test(key)).length);
+  // PowerPoint applies opacity (a:alphaModFix), grayscale (a:grayscl) and the border (a:ln) to an SVG picture (native check
+  // 2026-10-01). A duotone recolor and a non-rectangular mask are not confirmed on an SVG picture, and a tiled picture fill
+  // cannot carry an SVG: with any of them the SVG stays its PNG raster, so the effect applies as in the preview.
+  if (outcome.svg) {
+    const treated = [effects?.recolor?.type === 'duotone' && 'duotone recolor', effects?.shape && effects.shape.preset !== 'rect' && 'shape', fit === 'tile' && 'tile fit'].filter(Boolean);
+    if (treated.length) options.onDiagnostic?.({ code: 'svg-image-rasterized', path, message: `An SVG image with ${treated.join(', ')} exports as its PNG raster, so the effect applies as in the preview; PowerPoint has not been confirmed to apply it to an SVG picture.` });
+    else context.svgPictures.set(name, outcome.svg);
   }
-  const objectName = `OPF image ${context.imagePlacements.size + 1}`;
-  context.imagePlacements.set(objectName, { region, mode: context.imageFill, path });
-  if (outcome.svg) context.svgPictures.set(objectName, outcome.svg);
-  context.pictureText.set(objectName, pictureText(assetAlt(asset, presentation), asset, presentation));
-  slide.addImage({
-    ...resolved,
-    objectName,
-    x: region.x,
-    y: region.y,
-    w: region.w,
-    h: region.h,
-    altText: assetAlt(asset, presentation)
+  const text = alt !== undefined ? alt : assetAlt(asset, presentation);
+  context.images.set(name, { slide: context.slidePath, role, path, box, fit, focus, shrink, effects, ...(treatment !== undefined ? {treatment} : {}) });
+  context.pictureText.set(name, pictureText(text, asset, presentation));
+  slide.addImage({ ...resolved, objectName: name, x: box.x, y: box.y, w: box.w, h: box.h, altText: text });
+  return name;
+}
+
+// The native effects of an image treatment, resolved in the slide's colour context: core's mask (item.image.shape), the
+// border line, opacity and recolor.
+function imageEffects(image, context) {
+  const paint = (entry, fallback) => {
+    const raw = exportColor(entry, context, fallback).replace(/^#/, '');
+    return { hex: normalizeHex(raw, fallback), alpha: /^[0-9a-f]{8}$/i.test(raw) ? parseInt(raw.slice(6), 16) / 255 : 1 };
+  };
+  return {
+    shape: image.shape ?? null,
+    border: image.border ? { ...paint(image.border.color, context.colors.border), width: image.border.width } : null,
+    opacity: image.opacity ?? null,
+    recolor: image.recolor?.type === 'grayscale' ? { type: 'grayscale' }
+      : image.recolor?.type === 'duotone' ? { type: 'duotone', dark: paint(image.recolor.dark, '000000'), light: paint(image.recolor.light, 'FFFFFF') } : null,
+    paint
+  };
+}
+
+// An overlay (core ComposedOverlay) as one native shape directly above its picture: the frame's shape, or an edge band.
+function addImageOverlay(slide, overlay, authored, name, owner, context, effects) {
+  const {hex, alpha} = effects.paint(overlay.color, context.colors.text);
+  context.imageOverlays.set(name, { slide: context.slidePath, owner, box: overlay.box, shape: overlay.shape, hex, alpha, opacity: overlay.opacity, overlay: authored });
+  slide.addShape('rect', { x: overlay.box.x / 96, y: overlay.box.y / 96, w: overlay.box.width / 96, h: overlay.box.height / 96, objectName: name, fill: { color: hex } });
+}
+
+// The authored value at an OPF path the composition names (`slides.N.blocks.I`, `slides.N.design.background`,
+// `design.background`); `theme` is the resolved theme record's background.
+function authoredAt(presentation, path, slideContext) {
+  if (path === 'theme') return slideContext.core?.resolved?.theme?.background;
+  let value = presentation;
+  for (const key of path.split('.')) value = value?.[/^\d+$/.test(key) ? Number(key) : key];
+  return value;
+}
+
+// An image block (core ComposedItem.image): the picture at core's frame with its fit, focus and treatment, then its
+// overlay directly above. An unchanged picture and overlay import back as the same block (OPF_IMAGE_V1).
+async function addImageItem(slide, presentation, item, slideIndex, context, options) {
+  const image = item.image;
+  const box = { x: image.box.x / 96, y: image.box.y / 96, w: image.box.width / 96, h: image.box.height / 96 };
+  const block = isPlainObject(item.payload) ? item.payload : {};
+  const treatment = Object.fromEntries(IMAGE_TREATMENT_KEYS.filter(key => key !== 'overlay' && block[key] !== undefined).map(key => [key, structuredClone(block[key])]));
+  const effects = imageEffects(image, context);
+  const treated = Boolean(effects.border || effects.opacity !== null || effects.recolor || image.overlay || (effects.shape && effects.shape.preset !== 'rect'));
+  const tagged = Object.keys(treatment).length > 0 || block.overlay !== undefined;
+  // A plain contained picture in the flow is framed by the picture itself (0.14 content images); a treated or placed one
+  // keeps core's frame (0.14 slide images), so its mask, line and overlay apply to that frame.
+  const name = await addImagePicture(slide, presentation, item.value, box, item.path, { ...context, slidePath: `slides.${slideIndex}` }, options, {
+    fit: image.fit, focus: image.focus, effects: treated ? effects : null, shrink: !treated && !image.placement, treatment: tagged ? treatment : undefined
   });
-  return objectName;
+  if (!name) {
+    addImagePlaceholder(slide, presentation, item.value, box, item.path, context, options);
+    return `OPF image placeholder ${context.imagePlaceholders.size}`;
+  }
+  if (image.overlay) addImageOverlay(slide, image.overlay, structuredClone(block.overlay), imageOverlayName(name), name, { ...context, slidePath: `slides.${slideIndex}` }, effects);
+  return name;
+}
+
+// An image background (core SlideComposition.backgroundImage). With alt text it is a full-slide picture at the back of
+// the slide over the canvas colour, carrying the alt text as its descr; without alt it is the native slide background
+// fill (written at packaging). Its overlay is one shape directly above the picture.
+async function addBackgroundImage(slide, presentation, background, slideIndex, slideContext, context, options) {
+  const slidePath = `slides.${slideIndex}`, part = `ppt/slides/slide${slideIndex + 1}.xml`;
+  const box = { x: 0, y: 0, w: slideContext.dimensions.widthInches, h: slideContext.dimensions.heightInches };
+  const authored = authoredAt(presentation, background.path, slideContext);
+  const effects = imageEffects({ opacity: background.opacity, recolor: background.recolor }, slideContext);
+  let owner = 'background', overlayName = backgroundOverlayName(slidePath);
+  // Only the background's own alt text makes it meaningful (FA-22): a referenced asset's alt does not count.
+  const alt = background.alt;
+  if (typeof alt === 'string' && alt) {
+    const treatment = isPlainObject(authored) ? Object.fromEntries(BACKGROUND_IMAGE_KEYS.filter(key => key !== 'overlay' && authored[key] !== undefined).map(key => [key, structuredClone(authored[key])])) : {};
+    const name = await addImagePicture(slide, presentation, background.src, box, background.path, { ...slideContext, slidePath }, options, {
+      fit: background.fit, focus: background.focus, effects: background.opacity === undefined && !background.recolor ? null : effects, shrink: false,
+      treatment, alt, role: 'background', objectName: backgroundImageName(slidePath)
+    });
+    if (!name) {
+      options.onDiagnostic?.({code: 'unresolved-asset', path: background.path, message: 'The background image needs an embedded raster, a declared asset or a host imageResolver; the slide background color was exported instead.'});
+      return;
+    }
+    owner = name;
+    overlayName = imageOverlayName(name);
+  } else {
+    // An SVG background is its PNG raster at the slide's size: a slide background picture fill carries no SVG.
+    const outcome = { box, cover: background.fit === 'cover' };
+    const resolved = await resolveImage(background.src, presentation, options, background.path, outcome);
+    if (!resolved) {
+      if (!outcome.reported) options.onDiagnostic?.({code: 'unresolved-asset', path: background.path, message: 'The background image needs an embedded raster, a declared asset or a host imageResolver; the slide background color was exported instead.'});
+      return;
+    }
+    // PptxGenJS embeds the raster and its relationship; packaging replaces its stretched fill with the fitted native fill.
+    slide.background = { ...resolved };
+    context.backgroundFills.set(part, { image: {
+      fit: background.fit, focus: background.focus, opacity: background.opacity ?? 1, recolor: effects.recolor, path: background.path,
+      width: box.w * 96, height: box.h * 96, report: options.onDiagnostic
+    } });
+  }
+  if (background.overlay) addImageOverlay(slide, background.overlay, structuredClone(isPlainObject(authored) ? authored.overlay : undefined) ?? {color: background.overlay.color, opacity: background.overlay.opacity}, overlayName, owner, { ...slideContext, slidePath }, effects);
 }
 
 // design.watermark: one native picture per slide, added after the slide image
@@ -2243,54 +2396,6 @@ async function addLogo(slide, presentation, logo, slideIndex, slideContext, cont
   slide.addImage({...resolved, objectName: logoName(), ...region, altText: assetAlt(logo.source, presentation) ?? 'Logo'});
 }
 
-// design.slideImage: one native picture at the shared frame, beneath content.
-// Crop/fit and treatments are written after PptxGenJS embeds the bytes.
-async function addSlideImage(slide, presentation, image, slideIndex, context, options) {
-  const box = { x: image.box.x / 96, y: image.box.y / 96, w: image.box.width / 96, h: image.box.height / 96 };
-  const outcome = { box, cover: image.fill === 'crop' };
-  const resolved = await resolveImage(image.value, presentation, options, image.sourcePath, outcome);
-  if (!resolved) {
-    addImagePlaceholder(slide, presentation, image.value, box, image.sourcePath, context, options);
-    return;
-  }
-  const objectName = slideImageName(`slides.${slideIndex}`);
-  const configured = image.path === 'design.slideImage' ? presentation.design?.slideImage : presentation.slides[slideIndex].design?.slideImage;
-  const { src: _source, ...treatment } = isPlainObject(configured) && 'position' in configured ? configured : {};
-  const paint = (entry, fallback) => {
-    const hex = normalizeHex(exportColor(entry, context, fallback), fallback);
-    const raw = exportColor(entry, context, fallback).replace(/^#/, '');
-    return { hex, alpha: /^[0-9a-f]{8}$/i.test(raw) ? parseInt(raw.slice(6), 16) / 255 : 1 };
-  };
-  // Native effects are resolved here, in the slide's color context.
-  const effects = {
-    shape: image.shape ?? null,
-    border: image.border ? { ...paint(image.border.color, context.colors.border), width: image.border.width } : null,
-    opacity: image.opacity ?? null,
-    recolor: image.recolor?.type === 'grayscale' ? { type: 'grayscale' }
-      : image.recolor?.type === 'duotone' ? { type: 'duotone', dark: paint(image.recolor.dark, '000000'), light: paint(image.recolor.light, 'FFFFFF') } : null,
-    overlay: image.overlay ? { ...paint(image.overlay.color, context.colors.text), opacity: image.overlay.opacity, box: image.overlay.box, shape: image.overlay.shape } : null,
-  };
-  // FF-53: a root `image` with the slide image's source is the slide image (core `replacesContent`); the
-  // manifest records that so an unchanged picture imports back as both design.slideImage and slide.image.
-  context.slideImages.set(objectName, { slide: `slides.${slideIndex}`, box, fill: image.fill, path: image.sourcePath, treatment: { ...treatment, position: image.position }, effects, content: image.replacesContent === true });
-  // PowerPoint applies opacity (a:alphaModFix), grayscale (a:grayscl) and the border (a:ln) to an SVG picture (native check
-  // 2026-10-01). A duotone recolor and a non-rectangular mask are not confirmed on an SVG picture: with either the SVG stays its
-  // PNG raster, so the effect applies as in the preview.
-  if (outcome.svg) {
-    const treated = [effects.recolor?.type === 'duotone' && 'duotone recolor', effects.shape && effects.shape.preset !== 'rect' && 'shape'].filter(Boolean);
-    if (treated.length) options.onDiagnostic?.({ code: 'svg-image-rasterized', path: image.sourcePath, message: `An SVG slide image with ${treated.join(', ')} exports as its PNG raster, so the effect applies as in the preview; PowerPoint has not been confirmed to apply it to an SVG picture.` });
-    else context.svgPictures.set(objectName, outcome.svg);
-  }
-  const slideImageAlt = image.alt ?? assetAlt(image.value, presentation);
-  context.pictureText.set(objectName, pictureText(slideImageAlt, image.value, presentation));
-  slide.addImage({ ...resolved, objectName, ...box, altText: slideImageAlt });
-  // The overlay scrim is a separate native shape directly above the picture.
-  if (effects.overlay) {
-    const overlay = effects.overlay.box;
-    slide.addShape('rect', { x: overlay.x / 96, y: overlay.y / 96, w: overlay.width / 96, h: overlay.height / 96, objectName: slideImageOverlayName(`slides.${slideIndex}`), fill: { color: effects.overlay.hex } });
-  }
-}
-
 // FF-62: chart text is one size. The preview draws every chart label (axis, legend, data label) at
 // max(14, composition.minFontSize ?? 16) px scaled by the slide's shorter side over 720 px (renderer charts.js, `fontPx`),
 // the readability floor: 12 pt on a 13.33 x 7.5 in slide. The export writes that size, in hundredths of a point (DrawingML `sz`).
@@ -2669,7 +2774,7 @@ async function addFurniture(slide,presentation,source,layout,context,options,sli
   for(const [index,part]of layout.parts.entries()){
     if(part.type==='image'){
       const region={x:part.box.x/96,y:part.box.y/96,w:part.box.width/96,h:part.box.height/96};
-      const objectName = await addImagePayload(slide,presentation,part.image,region,part.path,{...context,imageFill:'fit'},options);
+      const objectName = await addImagePayload(slide,presentation,part.image,region,part.path,context,options);
       // A generated deck logo is listed beside the manifest topology (see furnitureManifest) and tagged as a logo.
       if (objectName && part.field === 'logo') context.furnitureLogoTags.set(objectName, {v:1, role:'furniture', group:String(slideIndex), furniture:part.kind, zone:part.zone});
       else if (objectName) context.furnitureTags.set(objectName, {v:1, role:'image', group:String(slideIndex), part:manifestPartIndex(layout.parts, index)});
@@ -3481,39 +3586,6 @@ function referenceId(reference) {
   return null;
 }
 
-const DEFAULT_SOURCE_PREFIX = "https://www.pptx.gallery/";
-
-// Same order as opf-render's socialPlatformRecords so preview and export format
-// socials identically. Core applies inline document records first; then the
-// document catalog source (host-supplied options.catalogSources, or the bundled
-// catalog for pptx.gallery/pkg sources), injected options.catalogs, and the
-// bundled catalog (the engine default source also resolves to it).
-function socialPlatformRecords(presentation, options) {
-  const kind = "socialPlatforms", declared = presentation.catalogs?.[kind]?.source;
-  // `source` is one source or an ordered search path (an array): records of each source in order, first match wins.
-  const sourceRecords = (Array.isArray(declared) ? declared : [declared]).filter(source => typeof source === "string").flatMap(source => {
-    const bySource = options.catalogSources?.[source];
-    return bySource ? normalizeRecords(bySource)
-      : source.startsWith(DEFAULT_SOURCE_PREFIX) || source.startsWith("pkg:@openpresentation/opf/") ? defaultCatalog(kind) : [];
-  });
-  return [...sourceRecords, ...normalizeRecords(options.catalogs?.[kind]), ...defaultCatalog(kind)];
-}
-
-function defaultCatalog(kind) {
-  return Array.isArray(bundledCatalogs[kind]) ? bundledCatalogs[kind] : [];
-}
-
-function normalizeRecords(catalog) {
-  if (!catalog) return [];
-  if (Array.isArray(catalog)) return catalog;
-  if (Array.isArray(catalog.records)) return catalog.records;
-  return [];
-}
-
-function findById(records, id) {
-  return records.find((record) => record?.id === id) ?? null;
-}
-
 // A solid color or pattern background color is a ColorRef (hex, `var:` variable, colour-scheme slot or role), resolved
 // as for table fills and run colours. Roles resolve through the colour scheme alone: the background cannot depend on itself.
 function resolveBackgroundColorRef(entry, colorScheme, variables = {}) {
@@ -3650,7 +3722,7 @@ async function normalizePptxZip(raw, context) {
     const relationships = parseRelationships(entries, part);
     for (const [picture] of decodeText(bytes).matchAll(/<p:pic>[\s\S]*?<\/p:pic>/g)) {
       const name = picture.match(/<p:cNvPr\b[^>]*\bname="([^"]+)"/)?.[1];
-      const placement = context.imagePlacements.get(name) ?? context.quotePhotos.get(name) ?? context.slideImages.get(name) ?? (name === watermarkName() ? context.watermarks.get(part) : name === logoName() ? context.logos.get(part) : undefined);
+      const placement = context.images.get(name) ?? context.quotePhotos.get(name) ?? (name === watermarkName() ? context.watermarks.get(part) : name === logoName() ? context.logos.get(part) : undefined);
       const id = picture.match(/<a:blip\b[^>]*r:embed="([^"]+)"/)?.[1];
       if (placement) imageSources.set(relationships.get(id)?.path, placement.path);
     }
@@ -3679,11 +3751,17 @@ async function normalizePptxZip(raw, context) {
     }
     imageMetadata.set(part, metadata);
   }
-  // Slide images need the embedded dimensions; document provenance (FF-32)
+  // Image pictures need the embedded dimensions (core's fitImage crops and pads them); document provenance (FF-32)
   // later records the placed frames as slide geometry evidence.
-  placeSlideImages(entries, context.slideImages, (part, id) => imageMetadata.get(parseRelationships(entries, part).get(id)?.path), path => {
-    throw new OPFPptxError("unsupported-image-dimensions", "Image fitting requires readable PNG, JPEG, GIF or WebP dimensions. Supply a supported raster image through imageResolver.", { path });
-  });
+  try {
+    placeImages(entries, context.images, context.imageOverlays, {
+      metadataFor: (part, id) => imageMetadata.get(parseRelationships(entries, part).get(id)?.path), fitImage,
+      fail: path => { throw new OPFPptxError("unsupported-image-dimensions", "Image fitting requires readable PNG, JPEG, GIF or WebP dimensions. Supply a supported raster image through imageResolver.", { path }); }
+    });
+  } catch (error) {
+    if (error instanceof OPFPptxError) throw error;
+    throw new OPFPptxError("packaging-failed", `Image pictures could not be placed: ${errorMessage(error)}`);
+  }
   tagTextWatermarks(entries, context.textWatermarks);
   placeWatermarks(entries, context.watermarks, (part, id) => imageMetadata.get(parseRelationships(entries, part).get(id)?.path), path => {
     throw new OPFPptxError("unsupported-image-dimensions", "Image fitting requires readable PNG, JPEG, GIF or WebP dimensions. Supply a supported raster image through imageResolver.", { path });
@@ -3842,7 +3920,7 @@ function normalizePartBytes(path, bytes, context, renameMaps, entries, imageMeta
           const metadata = imageMetadata.get(backgroundRelationships.get(id)?.path);
           if (!id || !metadata) throw new OPFPptxError("unsupported-image-dimensions", "Background image fitting requires readable PNG, JPEG, GIF or WebP dimensions. Supply a supported raster image through imageResolver.", { path: fill.image.path });
           if ((metadata.orientation ?? 1) !== 1) fill.image.report?.({code: 'unsupported-background-image-orientation', path: fill.image.path, message: 'A slide background picture fill cannot rotate or mirror its image; the JPEG EXIF orientation is not applied in the native background.'});
-          return `<p:bg><p:bgPr>${nativeImageBackgroundFill(id, metadata, fill.image)}<a:effectLst/></p:bgPr></p:bg>`;
+          return `<p:bg><p:bgPr>${nativeImageBackgroundFill(id, metadata, {...fill.image, fitImage})}<a:effectLst/></p:bgPr></p:bg>`;
         });
       }
       // PptxGenJS table IDs can collide with other objects on the same slide.
@@ -3928,7 +4006,8 @@ function normalizePartBytes(path, bytes, context, renameMaps, entries, imageMeta
         }
         const text = context.pictureText.get(picture.match(/<p:cNvPr\b[^>]*\bname="([^"]+)"/)?.[1]);
         if (text) picture = writePictureText(picture, text);
-        const placement = context.imagePlacements.get(picture.match(/name="(OPF image \d+)"/)?.[1]) ?? context.quotePhotos.get(picture.match(/name="(OPF quote photo \d+)"/)?.[1]);
+        // Image pictures were placed with the slide's other pictures (placeImages); quote photos are fitted here.
+        const placement = context.quotePhotos.get(picture.match(/name="(OPF quote photo \d+)"/)?.[1]);
         if (!placement) return picture;
         const id = picture.match(/<a:blip\b[^>]*r:embed="([^"]+)"/)?.[1];
         const dimensions = imageMetadata.get(relationships.get(id)?.path);