@openpresentation/opf-pptx 0.11.5 → 0.11.7

package/dist/index.js

@@ -5,7 +5,7 @@ import {applyChartFonts, applyPitchFamilies, finalizeFontsUsed, fontPitchFamilie
 import {readChartCategoryHeading,writeChartCategoryHeading} from './chart-workbook.js';
 import {CHARTEX_FALLBACK,resolveChartType,chartTypeFromNative,applyChartConstruct,NATIVE_CHART_ELEMENTS} from './chart-types.js';
 import {attachChartexParts,chartFromChartex,CHARTEX_GRAPHIC_DATA_URI} from './chartex.js';
-import {attachCodeTags, codeManifest, importCodeGroups, nativeShapeParagraphs, nativeTextShapes} from './code-provenance.js';
+import {attachCodeTags, attachTextTags, codeManifest, importCodeGroups, nativeShapeParagraphs, nativeTextShapes} from './code-provenance.js';
 import {attachMetricTags,metricManifest,importMetricGroups} from './metric-provenance.js';
 import {attachCardTags,importCardFrames} from './card-provenance.js';
 import {attachMediaTags,importMediaGroups,mediaCaption,mediaFrameRecord,mediaTextFingerprint} from './media-provenance.js';
@@ -13,13 +13,15 @@ import {attachHeadingTags,importHeadingGroups} from './heading-provenance.js';
 import {attachPlainTextTags,importPlainTextGroups} from './text-provenance.js';
 import {attachTimelineTags,timelineManifest,importTimelineGroups} from './timeline-provenance.js';
 import {attachQuoteTags,quoteManifest,importQuoteGroups} from './quote-provenance.js';
-import {attachFurnitureTags, furnitureManifest, importFurniture, staticDateFallback} from './furniture-provenance.js';
-import {applyDocumentProvenance, attachDocumentProvenance, documentProvenance, restoreDocumentProvenance} from './document-provenance.js';
+import {attachFurnitureTags, furnitureManifest, importFurniture, manifestPartIndex, staticDateFallback} from './furniture-provenance.js';
+import {applyDocumentProvenance, attachDocumentProvenance, documentProvenance, recordContentTopology, restoreDocumentProvenance} from './document-provenance.js';
+import {INVALID_XML_CHARACTER, nativeSections, writeSectionList} from './sections.js';
 import {attachFurnitureFields, furniturePartFields, lineFields, nativeFieldType} from './furniture-fields.js';
 import {importImageOrientation} from './image-import.js';
 import {placeSlideImages, importSlideImage, slideImageName, slideImageOverlayName} from './slide-image-provenance.js';
 import {dedupeMedia} from './media-dedupe.js';
 import {placeWatermarks, importWatermark, watermarkName, watermarkBox, watermarkOpacity} from './watermark-provenance.js';
+import {placeLogos, importLogo, importLogoPlaceholders, logoName, LOGO_TAG} from './logo-provenance.js';
 import {nativeBackgroundFill, nativeImageBackgroundFill, nativePatternPreset} from './background.js';
 import {importBackground} from './background-import.js';
 import {themeSlotColors, writeThemeColors, schemeColorValue, schemeBackgroundFill, schemeBackgroundValue, defaultTextSchemeValues, tableTextSchemeValue, solidColorXml, writeMasterBackground, inheritLayoutBackground, readThemeSlotColors, recoverColorScheme, recoverTheme, presentationThemePath} from './theme-colors.js';
@@ -27,7 +29,7 @@ import {languageDiagnostics, observeLanguage, partScriptFonts, planScriptFonts,
 import { webpToPng } from '#image-fallback';
 import { rasterMetadata, pictureTransform, normalizeImageOrientation } from './image-geometry.js';
 import { layoutTable, composeSlide, fitText, fitRichText, textWidthMeasurer, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, textColorForFill, chartColorForFill } from "@openpresentation/opf/composition";
-import { colorContext, resolveExportColor, resolveVariableColors } from "./color-ref.js";
+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";
@@ -209,8 +211,12 @@ export async function toPptx(input, options = {}) {
   context.tableHeaders = new Map();
   context.tableCells = new Map();
   context.imagePlacements = new Map();
+  context.pictureText = new Map();
   context.slideImages = new Map();
   context.watermarks = new Map();
+  context.logos = new Map();
+  context.logoPlaceholderTags = new Map();
+  context.bulletImages = new Map();
   context.backgroundFills = new Map();
   context.notesWithCarriageReturns = new Map();
   context.cardTags = new Map();
@@ -221,6 +227,7 @@ export async function toPptx(input, options = {}) {
   context.timelineTags = new Map();
   context.quoteTags = new Map();
   context.furnitureTags = new Map();
+  context.furnitureLogoTags = new Map();
   context.furnitureFields = new Map();
   context.furnitureManifests = new Map();
   context.codeTags = new Map();
@@ -229,12 +236,13 @@ export async function toPptx(input, options = {}) {
   context.chartFonts = new Map();
   context.chartex = new Map();
   context.imageFormat = options.imageFormat ?? "compatible";
-  // Native chartex parts are opt-in until the native PowerPoint check confirms them (FF-22b); the default keeps the
-  // clustered column export of the chartex chart types.
-  if (options.chartex !== undefined && !['native', 'fallback'].includes(options.chartex)) {
-    throw new OPFPptxError('invalid-chartex-mode', 'chartex must be native or fallback.', {path: 'options.chartex'});
+  // Chartex export mode (FF-22b): 'auto' (default) writes native chartex parts for the constructs the native PowerPoint
+  // check confirmed (treemap, histogram, pareto, box-and-whisker, waterfall, funnel) and the clustered column fallback
+  // for the unconfirmed map; 'native' writes every chartex part; 'fallback' writes clustered columns only.
+  if (options.chartex !== undefined && !['auto', 'native', 'fallback'].includes(options.chartex)) {
+    throw new OPFPptxError('invalid-chartex-mode', 'chartex must be auto, native or fallback.', {path: 'options.chartex'});
   }
-  context.chartexMode = options.chartex ?? 'fallback';
+  context.chartexMode = options.chartex ?? 'auto';
   Object.assign(context, exportTheme(presentation, context));
   context.reportedFontSchemes = new Set();
   // Document references and metadata tags (FF-32, docs/document-roundtrip.md).
@@ -244,6 +252,14 @@ export async function toPptx(input, options = {}) {
     report: diagnostic => options.onDiagnostic?.(diagnostic)
   });
   context.scriptFonts = planScriptFonts(presentation, options.onDiagnostic);
+  // 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) => {
+    if (typeof slide.section !== 'string') return undefined;
+    const invalid = INVALID_XML_CHARACTER.exec(slide.section);
+    if (invalid) throw new OPFPptxError('invalid-text', `Text contains U+${invalid[0].codePointAt(0).toString(16).toUpperCase().padStart(4, '0')} at UTF-16 offset ${invalid.index}, which DrawingML XML cannot represent.`, {path: `slides.${index}.section`});
+    return slide.section;
+  });
   context.masterBackground = masterBackground(context);
   context.linkSentinels = linkSentinels(presentation);
   const pptx = new PptxGenJS();
@@ -325,6 +341,9 @@ export async function fromPptx(input, options = {}) {
     furnitureContexts[index].mediaRegistry = mediaRegistry;
     imported.slides.push(importSlide(entries, slidePaths[index], index, dimensions, options, furniture.slides[index], furnitureContexts[index]));
   }
+  // Native sections (PowerPoint's own section list, `Default Section` = none)
+  // are reconciled with the footer text and the stored value in restoreDocumentProvenance.
+  const slideSections = nativeSections(presentationRoot, slideIdsInOrder(presentationRoot, presentationRels, entries, slidePaths));
   // A watermark carried identically by every slide is the deck's design.watermark.
   const carried = imported.slides.map(slide => slide.design?.watermark);
   if (carried.length && carried[0] && carried.every(value => JSON.stringify(value) === JSON.stringify(carried[0]))) {
@@ -351,7 +370,8 @@ export async function fromPptx(input, options = {}) {
     const restored = restoreDocumentProvenance(imported, {entries, presentationRoot, presentationRels, organizationConflict: furniture.organizationConflict === true,
       // Host catalogs format stored socials exactly as export did (FF-34).
       socialPlatformRecords: catalogs => socialPlatformRecords({catalogs}, options),
-      slides: slidePaths.map((path, index) => ({path, root: furnitureContexts[index].root, relationships: furnitureContexts[index].relationships}))}, report);
+      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).
     restored.groups = reconcileLanguage(restored.groups, observedLanguage, report);
     imported = applyDocumentProvenance(imported, restored, validatePresentation, report);
@@ -360,6 +380,7 @@ export async function fromPptx(input, options = {}) {
     report({code: "invalid-document-provenance", path: "", message: `${errorMessage(error)} Ordinary import keeps the values observed in the PPTX.`});
   }
   if (slideProvenance.length !== imported.slides.length) throw new OPFPptxError("invalid-import-opf", "Slide provenance does not match the imported slides.");
+  restoreLogoFallback(imported, furnitureContexts);
   if (imported.design?.theme === undefined) for (const diagnostic of themeDesign.diagnostics) if (diagnostic.code === "theme-unverified") report(diagnostic);
   languageDiagnostics(imported, observedLanguage, options.onDiagnostic && report);
 
@@ -374,6 +395,23 @@ export async function fromPptx(input, options = {}) {
   return imported;
 }
 
+// A consumed logo picture (OPF_LOGO_V1) never becomes content. Its own image restores the logo only when nothing else
+// did: the stored document and slide design (or the organization) win and carry LogoSet variants, so a package exported
+// without provenance still keeps its logo. A slide-level logo path restores slide design; every other path the deck's.
+function restoreLogoFallback(imported, contexts) {
+  const organizations = asArray(imported.organization);
+  contexts.forEach((context, index) => {
+    const fallback = context.logoFallback;
+    if (!fallback) return;
+    const slide = imported.slides[index];
+    const image = fallback.image;
+    // A slide's own logo restores whenever the slide states none, whatever the deck logo is; the deck logo only
+    // when neither it nor the organization has one.
+    if (fallback.path.startsWith('slides.')) { if (slide.design?.logo === undefined) slide.design = {...slide.design, logo: image}; }
+    else if (imported.design?.logo === undefined && !organizations.some(item => item?.logo !== undefined)) imported.design = {...imported.design, logo: image};
+  });
+}
+
 function readPptxZip(input) {
   let bytes;
   if (input instanceof Uint8Array) {
@@ -472,6 +510,17 @@ function resolveSlidePaths(entries, presentationRoot, relationships) {
     .sort(compareSlidePaths);
 }
 
+// The `p:sldId` ids of the imported slides, aligned with `slidePaths`; empty
+// when the slides were listed from the package rather than `p:sldIdLst`.
+function slideIdsInOrder(presentationRoot, relationships, entries, slidePaths) {
+  const ids = [];
+  for (const slideId of asArray(presentationRoot["p:sldIdLst"]?.["p:sldId"])) {
+    const relationship = relationships.get(slideId?.["r:id"]);
+    if (relationship?.type.endsWith("/slide") && entries[relationship.path]) ids.push(String(slideId?.id ?? ""));
+  }
+  return ids.length === slidePaths.length ? ids : slidePaths.map(() => "");
+}
+
 function compareSlidePaths(left, right) {
   return slideNumber(left) - slideNumber(right) || (left < right ? -1 : left > right ? 1 : 0);
 }
@@ -534,6 +583,16 @@ function importSlide(entries, slidePath, slideIndex, presentationDimensions, opt
     diagnostic => options.onDiagnostic?.({...diagnostic, path: watermarkPath}));
   if (watermark.design) slide.design = {...slide.design, ...watermark.design};
   nativeContext.watermarkPictures = watermark.consumed;
+  // The generated deck logo picture is not content; its value returns from the stored design (or, without one, from the picture).
+  const logoPath = `slides.${slideIndex}.design.logo`;
+  const logo = importLogo(nativeContext.pictures, relationships, entries, slideIndex,
+    picture => importPicture(entries, picture, slidePath, relationships, diagnostic => {
+      if (diagnostic.code !== 'unsupported-image-crop') options.onDiagnostic?.({...diagnostic, path: logoPath});
+    }),
+    diagnostic => options.onDiagnostic?.({...diagnostic, path: logoPath}));
+  nativeContext.logoPictures = logo.consumed;
+  nativeContext.logoPlaceholderShapes = importLogoPlaceholders(nativeContext.shapes, relationships, entries, slideIndex);
+  nativeContext.logoFallback = logo.fallback;
 
   const items = collectSlideItems(entries, slideRoot, slidePath, relationships, dimensions, options, slideIndex, furniture, nativeContext)
     .sort(comparePositionedItems);
@@ -557,10 +616,13 @@ function importSlide(entries, slidePath, slideIndex, presentationDimensions, opt
       item.text = current.map(paragraph => paragraph.text).join('\n');
     }
   }
-  const blocks = mergeAdjacentBulletShapes(items)
-    .map((item) => payloadFromSlideItem(item))
-    .filter(Boolean);
+  const content = mergeAdjacentBulletShapes(mergeOpfListShapes(items))
+    .map((item) => ({payload: payloadFromSlideItem(item), bounds: item.visualBounds ?? item.bounds}))
+    .filter((entry) => entry.payload);
+  const blocks = content.map((entry) => entry.payload);
   if (blocks.length > 0) slide.blocks = blocks;
+  // Native bounds of each block in reference px, for content topology matching (document provenance).
+  nativeContext.contentBounds = content.map((entry) => entry.bounds ? {x: entry.bounds.x * 96, y: entry.bounds.y * 96, width: entry.bounds.w * 96, height: entry.bounds.h * 96} : null);
 
   const notes = readSlideNotes(entries, relationships);
   if (notes) slide.notes = notes;
@@ -610,7 +672,7 @@ 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});
   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});
   for (const [index,shape] of shapes.entries()) {
-    if (furniture.text.has(index) || nativeContext.slideImageShapes?.has(index)) continue;
+    if (furniture.text.has(index) || nativeContext.slideImageShapes?.has(index) || nativeContext.logoPlaceholderShapes?.has(index)) 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'];
     const item = importShape(shape, dimensions, paragraphs[index], ordinaryBody || furniture.taggedText.has(index) || media.captionShapes.has(shape));
@@ -641,7 +703,7 @@ function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensi
   }
 
   for (const [index, picture] of nativeContext.pictures.entries()) {
-    if (furniture.pictures.has(index) || nativeContext.slideImagePictures?.has(index) || nativeContext.watermarkPictures?.has(index)) continue;
+    if (furniture.pictures.has(index) || nativeContext.slideImagePictures?.has(index) || nativeContext.watermarkPictures?.has(index) || nativeContext.logoPictures?.has(index)) continue;
     const report = diagnostic => options.onDiagnostic?.({...diagnostic, path: `slides.${slideIndex}.pictures.${index}`});
     const item = importPicture(entries, picture, slidePath, relationships, report);
     if (item) items.push(item);
@@ -718,10 +780,23 @@ function importGraphicFrame(entries, frame, slidePath, relationships, importedTa
   };
 }
 
+// The box a quarter-turned picture occupies on the slide: `a:xfrm` describes the
+// frame before rotation, so a 90 or 270 degree turn swaps its width and height
+// around the same centre. Content topology matching compares this visual box.
+function visualBounds(xfrm) {
+  const bounds = shapeBounds(xfrm);
+  const rotation = Number(xfrm?.rot ?? 0);
+  if (!bounds || !Number.isFinite(rotation) || ((rotation % 10800000) + 10800000) % 10800000 !== 5400000) return bounds;
+  return { x: bounds.x + bounds.w / 2 - bounds.h / 2, y: bounds.y + bounds.h / 2 - bounds.w / 2, w: bounds.h, h: bounds.w };
+}
+
 function importPicture(entries, picture, slidePath, relationships, report) {
   const bounds = shapeBounds(picture["p:spPr"]?.["a:xfrm"]);
   const name = scalarText(picture["p:nvPicPr"]?.["p:cNvPr"]?.name).trim();
-  const alt = scalarText(picture["p:nvPicPr"]?.["p:cNvPr"]?.descr);
+  // PptxGenJS (and so exports before this fix) wrote `preencoded.<ext>` for a picture with no alt text; that is no authored description.
+  const authoredAlt = scalarText(picture["p:nvPicPr"]?.["p:cNvPr"]?.descr);
+  const alt = /^preencoded\.[a-z0-9]+$/i.test(authoredAlt.trim()) ? "" : authoredAlt;
+  const title = scalarText(picture["p:nvPicPr"]?.["p:cNvPr"]?.title);
   const relId = picture["p:blipFill"]?.["a:blip"]?.["r:embed"];
   const relationship = relationships.get(relId);
   let bytes = relationship?.path ? entries[relationship.path] : null;
@@ -743,12 +818,14 @@ function importPicture(entries, picture, slidePath, relationships, report) {
   return {
     kind: "image",
     bounds,
+    visualBounds: visualBounds(picture["p:spPr"]?.["a:xfrm"]),
     name,
     payload: {
       type: "image",
       image: {
         src: `data:${rasterMetadata(bytes)?.mediaType ?? mediaTypeForPath(relationship.path)};base64,${bytesToBase64(bytes)}`,
-        ...(alt ? { alt } : {})
+        ...(alt ? { alt } : {}),
+        ...(title && alt ? { title } : {})
       }
     }
   };
@@ -771,7 +848,7 @@ function readParagraphs(txBody) {
       }
       return {
         text: texts.join(""),
-        bullet: asArray(paragraph?.["a:pPr"]).some(props => props?.["a:buChar"] !== undefined || props?.["a:buAutoNum"] !== undefined),
+        bullet: asArray(paragraph?.["a:pPr"]).some(props => props?.["a:buChar"] !== undefined || props?.["a:buBlip"] !== undefined || props?.["a:buAutoNum"] !== undefined),
         level: Number(asArray(paragraph?.["a:pPr"])[0]?.lvl ?? 0),
         maxFontSize: sizes.length > 0 ? Math.max(...sizes) : 0
       };
@@ -828,6 +905,59 @@ function takeSubtitleItem(items, titleItem, dimensions, inferHeadings) {
   return null;
 }
 
+// The export writes every native line of a list as its own shape named "OPF list <path> line N". The lines of one list
+// import as one list: a bulleted line starts an entry, an unbulleted line of the entry's own size continues it (a wrapped
+// entry) and a smaller one is its description. Without a bulleted first line the shapes stay as they are.
+const richRuns = value => typeof value === 'string' ? [{text: value}] : value;
+function joinRich(a, b) {
+  if (typeof a === 'string' && typeof b === 'string') return a + b;
+  const runs = [...richRuns(a), ...richRuns(b)], joined = [];
+  for (const run of runs) {
+    const last = joined.at(-1);
+    if (last && JSON.stringify({...last, text: ''}) === JSON.stringify({...run, text: ''})) last.text += run.text;
+    else joined.push({...run});
+  }
+  return joined;
+}
+function mergeOpfListShapes(items) {
+  const lists = new Map();
+  for (const item of items) {
+    const match = /^OPF list (.+) line (\d+)$/.exec(item.name ?? '');
+    if (match && item.kind === 'text' && item.paragraphs?.length === 1) {
+      if (!lists.has(match[1])) lists.set(match[1], []);
+      lists.get(match[1]).push({item, line: Number(match[2])});
+    }
+  }
+  const merged = new Map(), consumed = new Set();
+  for (const [path, entries] of lists) {
+    entries.sort((a, b) => a.line - b.line);
+    if (!entries[0].item.paragraphs[0].bullet) continue;
+    const paragraphs = [];
+    let bounds, size = 0;
+    for (const {item} of entries) {
+      const [paragraph] = item.paragraphs, current = paragraphs.at(-1);
+      if (paragraph.bullet) { paragraphs.push({...paragraph}); size = paragraph.maxFontSize; }
+      else if (paragraph.maxFontSize < size - 0.01) {
+        const text = paragraph.richText ?? paragraph.text;
+        current.description = current.description === undefined ? text : joinRich(current.description, text);
+      } else {
+        const before = current.text;
+        current.text += paragraph.text;
+        if (current.richText !== undefined || paragraph.richText !== undefined) current.richText = joinRich(current.richText ?? before, paragraph.richText ?? paragraph.text);
+      }
+      const b = item.visualBounds ?? item.bounds;
+      if (b) {
+        const x = Math.min(bounds?.x ?? b.x, b.x), y = Math.min(bounds?.y ?? b.y, b.y);
+        bounds = {x, y, w: Math.max((bounds ? bounds.x + bounds.w : -Infinity), b.x + b.w) - x, h: Math.max((bounds ? bounds.y + bounds.h : -Infinity), b.y + b.h) - y};
+      }
+      consumed.add(item);
+    }
+    const first = entries[0].item;
+    merged.set(first, {...first, paragraphs, text: paragraphs.map(paragraph => paragraph.text).join('\n'), bounds, visualBounds: undefined});
+  }
+  return items.flatMap(item => merged.has(item) ? [merged.get(item)] : consumed.has(item) ? [] : [item]);
+}
+
 // Adjacent native bullet boxes on the same text column form one imported list.
 // This is a geometry heuristic, not a lossless reconstruction of arbitrary PPTX.
 function mergeAdjacentBulletShapes(items) {
@@ -855,8 +985,8 @@ function payloadFromSlideItem(item) {
         type: "list",
         items: item.paragraphs.map((paragraph) => (
           paragraph.level > 0
-            ? { text: paragraph.richText ?? paragraph.text, level: paragraph.level }
-            : (paragraph.richText ?? paragraph.text)
+            ? { text: paragraph.richText ?? paragraph.text, level: paragraph.level, ...(paragraph.description !== undefined ? {description: paragraph.description} : {}) }
+            : paragraph.description !== undefined ? { text: paragraph.richText ?? paragraph.text, description: paragraph.description } : (paragraph.richText ?? paragraph.text)
         ))
       };
     }
@@ -1158,7 +1288,8 @@ function resolvePresentationContext(presentation, options) {
   const fontSchemeId = referenceId(design.fontScheme ?? theme?.fontScheme);
   const unresolvedFontScheme = fontSchemeId && !findById(normalizeRecords(presentation.catalogs?.fontSchemes), fontSchemeId) && !findById(defaultCatalog("fontSchemes"), fontSchemeId) ? fontSchemeId : null;
   const dimensions = resolveDimensions(design.dimensions ?? theme?.dimensions);
-  const background = resolveBackground(design.background ?? theme?.background, colorScheme);
+  const variables = resolveVariableColors(presentation.variables);
+  const background = resolveBackground(design.background ?? theme?.background, colorScheme, variables);
   const fonts = resolveFonts(fontScheme);
   for (const role of ["heading","body","code"]) fonts[role] = resolveTextStyle({fontFamily:fonts[role],fontWeight:role === "heading" ? 700 : 400},options.textMeasurement).fontFamily;
   const textColor = readableTextColor(background, colorScheme);
@@ -1184,7 +1315,7 @@ function resolvePresentationContext(presentation, options) {
       surface: normalizeHex(colorScheme.surface ?? (darkBackground ? colorScheme.dark2 : colorScheme.light2) ?? "#F8FAFC"),
       border: normalizeHex(colorScheme.accent5 ?? "#CBD5E1")
     },
-    variables: resolveVariableColors(presentation.variables)
+    variables
   };
 }
 
@@ -1207,7 +1338,23 @@ function nativeColor(reference, hex, context, fallback) {
 
 // FF-59: the slide tag is the eyebrow label. It is written in the deck primary color, the scheme accent1 slot the
 // preview draws it from: a:schemeClr accent1 where the deck theme holds that exact color, the literal otherwise.
+// FF-61: unless that primary is under 4.5:1 (WCAG 2.x) against the slide background, in which case the tag takes the
+// slide text color, the value the title and body text get (the scheme text slot where the theme holds it). opf-render
+// applies the same rule with the same arithmetic (test/tag-colour.mjs in both repositories pins the same color pairs).
+const TAG_MIN_CONTRAST = 4.5;
+function relativeLuminance(hex) {
+  const [red, green, blue] = [0, 2, 4].map(offset => {
+    const value = Number.parseInt(normalizeHex(hex).slice(offset, offset + 2), 16) / 255;
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  });
+  return red * 0.2126 + green * 0.7152 + blue * 0.0722;
+}
+function contrastRatio(first, second) {
+  const a = relativeLuminance(first), b = relativeLuminance(second);
+  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
 function tagColor(context) {
+  if (contrastRatio(context.colors.accent, context.colors.background) < TAG_MIN_CONTRAST) return context.textColor;
   return nativeColor('primary', context.colors.accent, context);
 }
 
@@ -1313,14 +1460,15 @@ async function addSlide(pptx, presentation, opfSlide, slideIndex, context, optio
   const backgroundPath = `${opfSlide.design?.background !== undefined ? `slides.${slideIndex}.` : ''}design.background`;
   const backgroundFill = 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));
+  }, 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`;
-    const resolved = await resolveImage(backgroundDefinition.image, presentation, options, imagePath);
+    const outcome = {};
+    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.
@@ -1329,7 +1477,7 @@ async function addSlide(pptx, presentation, opfSlide, slideIndex, context, optio
         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 {
+    } 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.'});
     }
   }
@@ -1349,11 +1497,15 @@ async function addSlide(pptx, presentation, opfSlide, slideIndex, context, optio
   // Core composition resolves one alignment per composed item for every engine
   // (FF-29); the design fallback keeps cores published before item.alignment working.
   const alignmentFor=item=>item.alignment??fieldAlignment(item.field);
-  const geometry = composeSlide(opfSlide, { width: widthInches * 96, height: heightInches * 96, layout, presentation, slideIndex, fonts: slideContext.fonts, contentAlignment, titleAlignment, textRasterPadding:options.textRasterPadding, contentBox:opfSlide.design?.contentBox??presentation.design?.contentBox, textMeasurement: options.textMeasurement, date: options.date, socialPlatforms: socialPlatformRecords(presentation, options) });
+  const geometry = composeSlide(opfSlide, { width: widthInches * 96, height: heightInches * 96, layout, presentation, slideIndex, fonts: slideContext.fonts, contentAlignment, titleAlignment, textRasterPadding:options.textRasterPadding, contentBox:opfSlide.design?.contentBox??presentation.design?.contentBox, darkBackground: isDarkHex(slideContext.colors.background), textMeasurement: options.textMeasurement, date: options.date, socialPlatforms: socialPlatformRecords(presentation, options) });
   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);
   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);
   for (const item of geometry.items) {
     // Card text sits on a literal card fill, not the slide background: keep it literal.
     const itemContext = item.frameBox ? {...slideContext, textColor: slideContext.colors.text, mutedColor: slideContext.colors.mutedText} : slideContext;
@@ -1383,7 +1535,7 @@ async function addSlide(pptx, presentation, opfSlide, slideIndex, context, optio
         breakLine: false
       });
     } else if ((item.field === "items" || item.field === "bullets") && item.text?.listEntries) {
-      addMeasuredList(slide,item.text,itemContext,item.path);
+      await addMeasuredList(slide,item.text,itemContext,item.path,item.bulletImage,presentation,slideIndex,options);
     } else if (item.field === "text" && item.text?.richLines) {
       const alignment=item.text.placement?.alignment??alignmentFor(item)??'left';
       for(const [index,line] of item.text.richLines.entries()){
@@ -1521,7 +1673,25 @@ function richLineRuns(line,color,native,context) {
 // the other measured text shapes. A reader maps lines to their list by name, not
 // by geometry, so lines of an overflowing list that fall below its box still
 // belong to it.
-function addMeasuredList(slide,fit,context,path) {
+// design.listBullet: image (core's item.bulletImage, the deck's icon logo) makes every entry marker a native picture bullet.
+// PptxGenJS embeds the media and its relationship through one picture per slide (OPF bullet image); packaging removes
+// that picture and points each marker paragraph at the relationship with a:buBlip. An icon that cannot be embedded
+// keeps the character bullets, as the preview does.
+async function addMeasuredList(slide,fit,context,path,bulletImage,presentation,slideIndex,options) {
+  let picture=false;
+  if(bulletImage){
+    const part=`ppt/slides/slide${slideIndex+1}.xml`;
+    if(context.bulletImages.has(part))picture=context.bulletImages.get(part);
+    else{
+      const outcome={};
+      const resolved=await resolveImage(bulletImage.source,presentation,options,bulletImage.path,outcome);
+      if(resolved){
+        slide.addImage({...resolved,objectName:bulletImageName(),x:0,y:0,w:.1,h:.1,altText:''});
+        picture=true;
+      }else if(!outcome.reported)options.onDiagnostic?.({code:'unresolved-asset',path:bulletImage.path,message:'A picture bullet needs an embedded raster, a declared asset or a host imageResolver; the character bullets were exported instead.'});
+      context.bulletImages.set(part,picture);
+    }
+  }
   let lineNumber=0;
   for(const entry of fit.listEntries){
     const addLines=(text,box,color,native,withBullet)=>{
@@ -1529,7 +1699,7 @@ function addMeasuredList(slide,fit,context,path) {
         const first=withBullet&&index===0,level=Math.min(8,entry.level),inset=first?entry.marker.indent*(level+1):0;
         const region={x:(box.x-inset)/96,y:(box.y+line.y)/96,w:(box.width+inset)/96,h:line.height/96};
         const objectName=`OPF list ${path} line ${lineNumber++}`;
-        if(first)context.listMarkers.set(objectName,{fontFamily:entry.marker.style.fontFamily,fontSize:entry.marker.fontSize*.75,color:pptxColor(context.textColor)});
+        if(first)context.listMarkers.set(objectName,{fontFamily:entry.marker.style.fontFamily,fontSize:entry.marker.fontSize*.75,color:pptxColor(context.textColor),picture});
         const paragraph=first?{bullet:{characterCode:entry.marker.text.codePointAt(0).toString(16).padStart(4,'0'),indent:entry.marker.indent*.75},indentLevel:level}:{bullet:false};
         const runs=richLineRuns(line,color,native,context);
         if(!runs.length)runs.push({text:'',options:{}});
@@ -1591,6 +1761,7 @@ async function addImagePayload(slide, presentation, asset, region, path, context
   }
   const objectName = `OPF image ${context.imagePlacements.size + 1}`;
   context.imagePlacements.set(objectName, { region, mode: context.imageFill, path });
+  context.pictureText.set(objectName, pictureText(assetAlt(asset, presentation), asset, presentation));
   slide.addImage({
     ...resolved,
     objectName,
@@ -1618,9 +1789,10 @@ async function addWatermark(slide, presentation, opfSlide, slideIndex, slideCont
     notExported('The watermark needs an image source (a string, or an object with src); no watermark was exported for this slide.');
     return;
   }
-  const resolved = await resolveImage(asset, presentation, options, path);
+  const outcome = {};
+  const resolved = await resolveImage(asset, presentation, options, path, outcome);
   if (!resolved) {
-    options.onDiagnostic?.({code: 'unresolved-asset', path, message: 'The watermark image needs an embedded raster, a declared asset or a host imageResolver; no watermark was exported for this slide.'});
+    if (!outcome.reported) options.onDiagnostic?.({code: 'unresolved-asset', path, message: 'The watermark image needs an embedded raster, a declared asset or a host imageResolver; no watermark was exported for this slide.'});
     return;
   }
   const {widthInches, heightInches} = slideContext.dimensions;
@@ -1630,6 +1802,24 @@ async function addWatermark(slide, presentation, opfSlide, slideIndex, slideCont
   slide.addImage({...resolved, objectName: watermarkName(), ...box, altText: assetAlt(asset, presentation) ?? 'Watermark'});
 }
 
+// The deck logo (design.logo, a slide's own logo or the primary organization's) on a cover or section slide: one native
+// picture per slide at core's geometry.logo box, fitted without cropping, anchored left and vertically centered, after
+// the watermark and before content (the preview's paint order). The frame and the provenance tag are written after
+// PptxGenJS embeds the bytes. An unresolved source draws the preview's "Image unavailable" panel in the logo box.
+async function addLogo(slide, presentation, logo, slideIndex, slideContext, context, options) {
+  const region = {x: logo.box.x / 96, y: logo.box.y / 96, w: logo.box.width / 96, h: logo.box.height / 96};
+  const outcome = {};
+  const resolved = await resolveImage(logo.source, presentation, options, logo.path, outcome);
+  if (!resolved) {
+    if (!outcome.reported) options.onDiagnostic?.({code: 'unresolved-asset', path: logo.path, message: 'The logo needs an embedded raster, a declared asset or a host imageResolver; the logo panel shows "Image unavailable" instead.'});
+    const prefix = addImagePlaceholder(slide, presentation, logo.source, region, logo.path, slideContext, options, {logo: true});
+    if (prefix) context.logoPlaceholderTags.set(prefix, {v: 1, role: 'placeholder', slide: `slides.${slideIndex}`, path: logo.path});
+    return;
+  }
+  context.logos.set(`ppt/slides/slide${slideIndex + 1}.xml`, {slide: `slides.${slideIndex}`, box: region, path: logo.path, variant: logo.variant});
+  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) {
@@ -1659,7 +1849,9 @@ async function addSlideImage(slide, presentation, image, slideIndex, context, op
   // 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 });
-  slide.addImage({ ...resolved, objectName, ...box, altText: image.alt ?? assetAlt(image.value, presentation) });
+  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;
@@ -1667,6 +1859,21 @@ async function addSlideImage(slide, presentation, image, slideIndex, context, op
   }
 }
 
+// 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`).
+function chartTextSize(context) {
+  const scale = Math.min(context.dimensions.widthInches, context.dimensions.heightInches) * 96 / 720;
+  return Math.round(Math.max(14, context.composition?.minFontSize ?? 16) * scale * 75);
+}
+
+// Every c:txPr of a generated classic chart carries the chart text size: PptxGenJS writes no size on the legend (PowerPoint's
+// 18 pt default) and hardcodes 18 pt on pie and doughnut data labels. Only the size changes; faces and colours stay as written.
+function applyChartTextSize(xml, size) {
+  return xml.replace(/<c:txPr>[\s\S]*?<\/c:txPr>/g, properties => properties.replace(/<a:defRPr\b([^>]*?)(\/?)>/g, (match, attributes, close) =>
+    `<a:defRPr${/\bsz="[^"]*"/.test(attributes) ? attributes.replace(/\bsz="[^"]*"/, `sz="${size}"`) : `${attributes} sz="${size}"`}${close}>`));
+}
+
 function addChartPayload(slide, chart, region, context, options = {}, path = "chart") {
   const chartData = toPptxChartData(chart, context.chartexMode);
   if (!chartData.series) {
@@ -1685,16 +1892,17 @@ function addChartPayload(slide, chart, region, context, options = {}, path = "ch
   const fill = {color:normalizeHex(panelFill),transparency};
   const objectName = `OPF chart ${context.chartHeadings.size + 1}`;
   const circular = chartData.type === 'pie' || chartData.type === 'doughnut';
-  context.chartHeadings.set(objectName,{heading:chartData.type === 'scatter' ? undefined : chartData.heading ?? chart.data.columns[0],labelColor,spec:chartData.spec});
+  const textSize = chartTextSize(context);
+  context.chartHeadings.set(objectName,{heading:chartData.type === 'scatter' ? undefined : chartData.heading ?? chart.data.columns[0],labelColor,spec:chartData.spec,textSize});
   context.chartFonts.set(objectName,{heading:context.fonts.heading,body:context.fonts.body});
   const palette = CHART_COLORS.map(color=>normalizeHex(chartColorForFill(panelFill,`#${color}`)));
   if (chartData.chartex) {
     // The native chartex part is added when the package is normalized (attachChartexParts); the classic chart below becomes its fallback.
     // PptxGenJS rewrites the series it is given (labels become nested levels), so the chartex part keeps its own copy.
     const series = chartData.series.map((entry) => ({name: entry.name, labels: [...entry.labels], values: [...entry.values]}));
-    context.chartex.set(objectName, {spec: chartData.chartex, series, hasCategories: chartData.hasCategories, fill, labelColor, gridColor: context.colors.border, font: context.fonts.body, palette});
+    context.chartex.set(objectName, {spec: chartData.chartex, series, hasCategories: chartData.hasCategories, fill, labelColor, gridColor: context.colors.border, font: context.fonts.body, palette, textSize});
     if (chartData.chartex.layoutId === 'regionMap') {
-      options.onDiagnostic?.({code: "chart-map-geodata", path, message: `The '${stringifyText(chart.type)}' chart is exported as a native PowerPoint map (chartex regionMap) without cached geography: PowerPoint matches the category names to regions and fetches their shapes from Bing Maps when the deck is opened online, so the map shows no regions offline or where Office map data is disabled. The clustered column fallback shows the same values in other readers.`});
+      options.onDiagnostic?.({code: "chart-map-geodata", path, message: `The '${stringifyText(chart.type)}' chart is exported as a native PowerPoint map (chartex regionMap) without cached geography (no cx:geoCache; provider data is never fabricated): PowerPoint must fetch the region shapes from its online map service when the deck is opened, and until it does it shows "There was a problem getting the information for your map chart" and draws nothing. The clustered column fallback shows the same values in readers without chartex support.`});
     }
   }
   const percent = chartData.spec.grouping === 'percentStacked';
@@ -1711,14 +1919,16 @@ function addChartPayload(slide, chart, region, context, options = {}, path = "ch
     // Paint alpha once in the chart area, rather than stacking two alpha fills.
     plotArea: {fill:{color:null}},
     catAxisLabelFontFace: context.fonts.body,
-    catAxisLabelFontSize: 9,
+    catAxisLabelFontSize: textSize / 100,
     catAxisLabelColor: labelColor,
     valAxisLabelFontFace: context.fonts.body,
-    valAxisLabelFontSize: 9,
+    valAxisLabelFontSize: textSize / 100,
     valAxisLabelColor: labelColor,
     legendColor: labelColor,
     legendFontFace: context.fonts.body,
+    legendFontSize: textSize / 100,
     dataLabelColor: labelColor,
+    dataLabelFontSize: textSize / 100,
     showValue: false,
     valGridLine: { color: context.colors.border, transparency: 30, size: 1 },
     barDir: chartData.barDir,
@@ -1892,7 +2102,9 @@ async function addFurniture(slide,presentation,source,layout,context,options,sli
     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);
-      if (objectName) context.furnitureTags.set(objectName, {v:1, role:'image', group:String(slideIndex), part:index});
+      // 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)});
     }else{
       if(!part.fit?.sourceLines)throw new OPFPptxError('missing-furniture-layout','Repeated text requires accepted source lines from core.',{path:part.path});
       // Slide numbers and current dates become native PowerPoint fields; {total}
@@ -1912,13 +2124,15 @@ async function addFurniture(slide,presentation,source,layout,context,options,sli
           if(marker) staticDates.set(index,marker);
         }
       }
-      addMeasuredPayloadText(slide,part.text,part.box,context,options,{path:part.path,fit:part.fit,textStyle:part.style,align:part.alignment,diagnosticsHandled:true,color:context.mutedColor,keepEmpty:true,objectName:`OPF furniture ${slideIndex} part ${index}`,furniture:{group:String(slideIndex),part:index},liveFields,links:part.links});
+      addMeasuredPayloadText(slide,part.text,part.box,context,options,{path:part.path,fit:part.fit,textStyle:part.style,align:part.alignment,diagnosticsHandled:true,color:context.mutedColor,keepEmpty:true,objectName:`OPF furniture ${slideIndex} part ${index}`,furniture:{group:String(slideIndex),part:manifestPartIndex(layout.parts,index)},liveFields,links:part.links});
     }
   }
   const manifest = furnitureManifest(presentation, source, layout, slideIndex, staticDates);
   if (manifest) context.furnitureManifests.set(`ppt/slides/slide${slideIndex + 1}.xml`, manifest);
 }
 
+const bulletImageName = () => 'OPF bullet image';
+
 function addCodePayload(slide, value, layout, region, context, path) {
   if (!layout) throw new OPFPptxError('missing-code-layout', 'Code export requires a coordinated core build with shared code geometry.', {path});
   for (const part of layout.parts) {
@@ -2054,7 +2268,9 @@ function placeholderAsset(asset, presentation) {
 // minimum) in the readable text colour for the panel, or a cross when the label
 // cannot fit even at that minimum. The panel carries the accessible name the
 // preview gives its group, "Image unavailable: <description>".
-function addImagePlaceholder(slide, presentation, asset, region, path, context, options) {
+// {logo: true} names the panel's other shapes after its panel (OPF image placeholder N text line i / icon i) and returns the
+// panel's name, so a logo placeholder can be tagged and consumed on import.
+function addImagePlaceholder(slide, presentation, asset, region, path, context, options, {logo = false} = {}) {
   const layered = placeholderAsset(asset, presentation);
   const description = String(layered.alt ?? layered.title ?? "Image");
   const label = `Image unavailable\n${description}`;
@@ -2088,17 +2304,18 @@ function addImagePlaceholder(slide, presentation, asset, region, path, context,
     const centered = { ...inner, y: inner.y + offset };
     addMeasuredPayloadText(slide, label, centered, context, options, {
       path, fit: fitText(label, centered, 20 * scale, minimum, measurer), textStyle: style,
-      diagnosticsHandled: true, align: "center", color: textColor
+      diagnosticsHandled: true, align: "center", color: textColor, ...(logo ? {objectName: `${objectName} text`} : {})
     });
-    return;
+    return logo ? objectName : undefined;
   }
   // A status indicator, not shortened authored content: the full description stays
   // in the panel's accessible name.
   const size = Math.max(0, Math.min(inner.width, inner.height, 24 * scale));
-  if (!size) return;
+  if (!size) return logo ? objectName : undefined;
   const icon = { x: inner.x + (inner.width - size) / 2, y: inner.y + (inner.height - size) / 2 };
   const line = { color: textColor, width: Math.min(2 * scale, size / 8) * .75 };
-  for (const flipV of [false, true]) slide.addShape("line", { x: icon.x / 96, y: icon.y / 96, w: size / 96, h: size / 96, line, flipV });
+  for (const flipV of [false, true]) slide.addShape("line", { x: icon.x / 96, y: icon.y / 96, w: size / 96, h: size / 96, line, flipV, ...(logo ? {objectName: `${objectName} icon ${flipV ? 2 : 1}`} : {}) });
+  return logo ? objectName : undefined;
 }
 
 // A placeholder names what is missing in plain words. It never dumps the source value, so no data or URL lands in slide text.
@@ -2232,7 +2449,7 @@ function textRuns(value, context, fallbackFontSize) {
  * into equal-width bins and exported as a column chart of the counts, every other type plots the values against
  * their row numbers. `adapted` names that transformation so it is reported, never silent.
  */
-function toPptxChartData(chart, chartexMode = 'fallback') {
+function toPptxChartData(chart, chartexMode = 'auto') {
   const data = chart?.data;
   const unplottable = (reason, summary, message) => ({reason, summary, message: `${message} No native chart was exported; a placeholder frame stands in for it.`});
   if (!data || !Array.isArray(data.columns) || !Array.isArray(data.rows)) {
@@ -2241,17 +2458,21 @@ function toPptxChartData(chart, chartexMode = 'fallback') {
   if (data.rows.length === 0) return unplottable("no-rows", "The chart has no data rows.", "The chart data has no rows.");
   if (data.columns.length === 0) return unplottable("no-columns", "The chart has no data columns.", "The chart data has no columns.");
   const resolved = resolveChartType(chart.type).spec;
-  // A chartex type (treemap, histogram, pareto, box & whisker, waterfall, funnel, map) has no classic construct. With
-  // `chartex: 'native'` it is written as its cx:chartSpace part and the clustered column chart of the same data is its
-  // mc:Fallback (src/chartex.js); by default (pending the native PowerPoint check, FF-22b) it exports as the clustered
-  // column chart alone and reports chartex-fallback, never silently.
-  const native = chartexMode === 'native';
+  // A chartex type (treemap, histogram, pareto, box & whisker, waterfall, funnel, map) has no classic construct. Natively
+  // it is written as its cx:chartSpace part and the clustered column chart of the same data is its mc:Fallback
+  // (src/chartex.js). 'auto' (the default) does that for the constructs the native PowerPoint check confirmed and keeps
+  // the unconfirmed map on the clustered column chart alone; 'fallback' keeps every chartex id there. The fallback is
+  // reported as chartex-fallback, never silent.
+  const native = chartexMode === 'native' || (chartexMode === 'auto' && resolved.family === 'chartex' && !resolved.unconfirmed);
   const chartex = resolved.family === 'chartex' && native ? resolved : null;
   const spec = resolved.family === 'chartex' ? CHARTEX_FALLBACK : resolved;
   const typeName = stringifyText(chart.type);
   const adaptations = [];
   if (resolved.family === 'chartex' && !native) {
-    adaptations.push({adaptation: "chartex-fallback", message: `The '${typeName}' chart is a PowerPoint extension (chartex) chart that this exporter does not write; its data is exported as a native clustered column chart instead.`});
+    const reason = chartexMode === 'fallback'
+      ? 'that this exporter does not write'
+      : 'that PowerPoint has not yet accepted natively from this exporter (pass chartex: \'native\' to write its chartex part)';
+    adaptations.push({adaptation: "chartex-fallback", message: `The '${typeName}' chart is a PowerPoint extension (chartex) chart ${reason}; its data is exported as a native clustered column chart instead.`});
   }
   const mapped = {type: spec.pptx, spec, chartex, barDir: spec.barDir, barGrouping: spec.pptx === 'bar' || spec.pptx === 'area' ? spec.grouping : undefined};
   if (data.columns.length === 1) {
@@ -2291,7 +2512,9 @@ function toPptxChartData(chart, chartexMode = 'fallback') {
   let series = data.columns.slice(1).map((name, seriesIndex) => ({
     name: stringifyText(name),
     labels,
-    values: data.rows.map((row) => numericValue(row?.[seriesIndex + 1]))
+    // A cell that holds no number (null, an empty or non-numeric string, a boolean) is a gap, as in the preview and the single-column
+    // path above: it is neither plotted as a zero nor written into the cache as one.
+    values: data.rows.map((row) => parsedNumber(row?.[seriesIndex + 1]))
   }));
   const plotted = spec.family === 'circular' ? 1 : chartex ? chartex.series : Infinity;
   if (series.length > plotted) {
@@ -2335,7 +2558,42 @@ function histogramBins(values) {
   }
 }
 
-async function resolveImage(asset, presentation, options, path) {
+// Embedded bytes must be a raster the exporter can measure and PptxGenJS can embed (PNG, JPEG, GIF, WebP). An SVG, or
+// bytes that are no readable image, would otherwise fail deep inside packaging. Like an unresolved asset it is not
+// exported as a picture: the caller draws the preview's placeholder (or omits the picture) and one `unresolved-asset`
+// diagnostic names the cause; `strictAssets` keeps the `unsupported-image-dimensions` error. `outcome.reported` tells a
+// caller that the diagnostic was already emitted. Hosts that need SVG art supply a raster through `imageResolver`
+// (for example opf-render's `svgToPng`). Local paths are read by PptxGenJS and checked after embedding.
+async function resolveImage(asset, presentation, options, path, outcome = {}) {
+  const resolved = await resolveImageSource(asset, presentation, options, path);
+  if (!resolved?.data) return resolved;
+  const bytes = dataUriBytes(resolved.data);
+  if (bytes && rasterMetadata(bytes)) return resolved;
+  const message = `The image is not a readable PNG, JPEG, GIF or WebP (${dataUriMediaType(resolved.data) ?? "unknown type"}); supply a raster through imageResolver (for example opf-render svgToPng).`;
+  if (options.strictAssets) throw new OPFPptxError("unsupported-image-dimensions", `Image fitting requires readable PNG, JPEG, GIF or WebP dimensions. ${message}`, { path });
+  options.onDiagnostic?.({ code: "unresolved-asset", path, reason: "unsupported-format", message });
+  outcome.reported = true;
+  return null;
+}
+
+function dataUriMediaType(uri) {
+  return /^data:([^;,]+)/i.exec(uri)?.[1]?.toLowerCase();
+}
+
+// Only base64 data URIs carry bytes the exporter can read; any other encoding is not a readable raster.
+function dataUriBytes(uri) {
+  const match = /^data:[^,]*;base64,/i.exec(uri);
+  if (!match) return null;
+  try {
+    if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(uri.slice(match[0].length), "base64"));
+    const binary = atob(uri.slice(match[0].length));
+    return Uint8Array.from(binary, char => char.charCodeAt(0));
+  } catch {
+    return null;
+  }
+}
+
+async function resolveImageSource(asset, presentation, options, path) {
   const assetObject = dereferenceAsset(asset, presentation, path);
   const src = typeof assetObject === "string" ? assetObject : assetObject?.src;
   if (!src) {
@@ -2406,6 +2664,24 @@ function dereferenceAsset(asset, presentation, path, seen = new Set()) {
   return asset;
 }
 
+// PptxGenJS writes its own stand-in (`preencoded.png`, or the local file path) as the picture's description when it is
+// given no alt text. The package writes only what the document authored: the alt text as `descr`, and a distinct asset
+// `title` as the native `title` attribute (a picture's tooltip and Alt Text title).
+function pictureText(alt, asset, presentation) {
+  const resolved = dereferenceAsset(asset, presentation, "asset-title");
+  const title = isPlainObject(resolved) && typeof resolved.title === "string" && resolved.title && resolved.title !== alt ? resolved.title : undefined;
+  return { alt: typeof alt === "string" && alt ? alt : undefined, title: alt ? title : undefined };
+}
+
+function writePictureText(picture, text) {
+  const escapes = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;", "\r": "&#13;", "\n": "&#10;", "\t": "&#9;" };
+  const escape = value => value.replace(/[&<>"'\r\n\t]/g, char => escapes[char]);
+  return picture.replace(/<p:cNvPr\b([^>]*?)(\/?)>/, (tag, attributes, close) => {
+    attributes = attributes.replace(/\sdescr="[^"]*"/, "").replace(/\stitle="[^"]*"/, "");
+    return `<p:cNvPr${attributes}${text.alt ? ` descr="${escape(text.alt)}"` : ""}${text.title ? ` title="${escape(text.title)}"` : ""}${close}>`;
+  });
+}
+
 function assetAlt(asset, presentation) {
   const resolved = dereferenceAsset(asset, presentation, "asset-alt");
   if (resolved && typeof resolved === "object" && !Array.isArray(resolved)) {
@@ -2445,10 +2721,13 @@ const DEFAULT_SOURCE_PREFIX = "https://www.pptx.gallery/";
 // 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", source = presentation.catalogs?.[kind]?.source;
-  const bySource = typeof source === "string" ? options.catalogSources?.[source] : undefined;
-  const sourceRecords = bySource ? normalizeRecords(bySource)
-    : typeof source === "string" && (source.startsWith(DEFAULT_SOURCE_PREFIX) || source.startsWith("pkg:@openpresentation/opf/")) ? defaultCatalog(kind) : [];
+  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)];
 }
 
@@ -2476,19 +2755,26 @@ function resolveDimensions(value) {
   return { widthInches: width / 96, heightInches: height / 96 };
 }
 
-function resolveBackground(value, colorScheme) {
+// 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 = {}) {
+  return resolveColorRefValue(entry, {colorScheme, colors: {}, variables});
+}
+
+function resolveBackground(value, colorScheme, variables = {}) {
   const fallback = "FFFFFF";
+  const reference = entry => normalizeHex(resolveBackgroundColorRef(entry, colorScheme, variables) ?? entry, fallback);
   if (typeof value === "string") {
     if (value.startsWith("#")) return normalizeHex(value, fallback);
     return normalizeHex(colorScheme[value] ?? colorScheme.background ?? colorScheme.light1 ?? "#FFFFFF", fallback);
   }
   if (isPlainObject(value)) {
-    if (value.type === "solid" && value.color) return normalizeHex(value.color, fallback);
+    if (value.type === "solid" && value.color) return reference(value.color);
     if (value.type === "theme" && value.slot) {
       return normalizeHex(colorScheme[value.slot] ?? colorScheme.light1 ?? "#FFFFFF", fallback);
     }
     // Like the SVG preview, text contrast follows a pattern's background color.
-    if (value.type === "pattern") return normalizeHex(value.pattern?.backgroundColor ?? "#FFFFFF", fallback);
+    if (value.type === "pattern") return reference(value.pattern?.backgroundColor ?? "#FFFFFF");
     if (value.backgroundColor) return normalizeHex(value.backgroundColor, fallback);
   }
   return normalizeHex(colorScheme.background ?? colorScheme.light1 ?? "#FFFFFF", fallback);
@@ -2545,7 +2831,9 @@ async function normalizePptxZip(raw, context) {
   attachTimelineTags(entries,context.timelineTags);
   attachQuoteTags(entries,context.quoteTags);
   attachFurnitureFields(entries,context.furnitureFields);
-  attachFurnitureTags(entries,context.furnitureTags,context.furnitureManifests);
+  attachFurnitureTags(entries,context.furnitureTags,context.furnitureManifests,context.furnitureLogoTags);
+  // The "Image unavailable" panel of an unresolved logo: identity only, so import does not read it as content.
+  attachTextTags(entries,context.logoPlaceholderTags,LOGO_TAG,'opfLogoPlaceholder','logo placeholder');
   for(const [part,bytes]of Object.entries(entries)){
     if(!/^ppt\/slides\/slide\d+\.xml$/.test(part))continue;
     const relationships=parseRelationships(entries,part);
@@ -2554,12 +2842,13 @@ async function normalizePptxZip(raw, context) {
       if(!context.chartHeadings.has(name))continue;
       const id=frame.match(/<c:chart\b[^>]*\br:id="([^"]+)"/)?.[1],chartPart=relationships.get(id)?.path;
       if(!chartPart)throw new OPFPptxError('packaging-failed','Generated chart relationship is missing.');
-      const {heading,labelColor,spec}=context.chartHeadings.get(name);
+      const {heading,labelColor,spec,textSize}=context.chartHeadings.get(name);
       if(heading!==undefined)writeChartCategoryHeading(entries,chartPart,heading);
-      entries[chartPart]=encodeText(applyChartConstruct(decodeText(entries[chartPart]),spec));
+      entries[chartPart]=encodeText(omitEmptyNumberPoints(applyChartConstruct(decodeText(entries[chartPart]),spec)));
       // PptxGenJS hardcodes a black fallback in pie/doughnut label properties.
       // Normalize only our generated chart text styles; point/series fills stay intact.
       entries[chartPart]=encodeText(decodeText(entries[chartPart]).replace(/<c:txPr>[\s\S]*?<\/c:txPr>/g,properties=>properties.replace(/<a:solidFill>[\s\S]*?<\/a:solidFill>/g,()=>`<a:solidFill><a:srgbClr val="${labelColor}"/></a:solidFill>`)));
+      entries[chartPart]=encodeText(applyChartTextSize(decodeText(entries[chartPart]),textSize));
     }
   }
   applyChartFonts(entries,context.chartFonts,parseRelationships);
@@ -2570,13 +2859,18 @@ async function normalizePptxZip(raw, context) {
     throw new OPFPptxError('packaging-failed', `Chartex chart parts could not be attached: ${errorMessage(error)}`);
   }
   applyPitchFamilies(entries,context.fontPitch);
+  // Native PowerPoint sections (p14:sectionLst) from slide `section` labels, written whatever the provenance option.
+  if (context.sections.some(section => section !== undefined)) {
+    try { entries['ppt/presentation.xml'] = encodeText(writeSectionList(decodeText(entries['ppt/presentation.xml']), context.sections)); }
+    catch (error) { throw new OPFPptxError('packaging-failed', 'Section list could not be written.', {cause: errorMessage(error)}); }
+  }
   const imageSources = new Map();
   for (const [part, bytes] of Object.entries(entries)) {
     if (!/^ppt\/slides\/slide\d+\.xml$/.test(part)) continue;
     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.slideImages.get(name) ?? (name === watermarkName() ? context.watermarks.get(part) : undefined);
+      const placement = context.imagePlacements.get(name) ?? context.slideImages.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);
     }
@@ -2609,6 +2903,9 @@ async function normalizePptxZip(raw, context) {
   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 });
   });
+  placeLogos(entries, context.logos, (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 });
+  });
   // A picture repeated across slides embeds once (after fitting, which needs each slide's own relationship).
   dedupeMedia(entries, imageMetadata, resolveRelationshipTarget);
   // Charts and notes follow the language and fonts of the slide they belong to.
@@ -2812,7 +3109,15 @@ function normalizePartBytes(path, bytes, context, renameMaps, entries, imageMeta
       // Image data is already resolved and embedded by PptxGenJS. Read those
       // exact bytes instead of fetching or resolving the source a second time.
       const relationships = parseRelationships(entries, path);
+      let bulletRelationship;
       xml = xml.replace(/<p:pic>([\s\S]*?)<\/p:pic>/g, picture => {
+        if (picture.match(/<p:cNvPr\b[^>]*\bname="([^"]+)"/)?.[1] === bulletImageName()) {
+          // Only its media part and relationship are wanted: every picture-bullet paragraph points at them (a:buBlip).
+          bulletRelationship = picture.match(/<a:blip\b[^>]*r:embed="([^"]+)"/)?.[1];
+          return '';
+        }
+        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]);
         if (!placement) return picture;
         const id = picture.match(/<a:blip\b[^>]*r:embed="([^"]+)"/)?.[1];
@@ -2833,6 +3138,7 @@ function normalizePartBytes(path, bytes, context, renameMaps, entries, imageMeta
       xml=xml.replace(/<p:sp>([\s\S]*?)<\/p:sp>/g,(shape)=>{
         const marker=context.listMarkers.get(shape.match(/name="(OPF list [^"]* line \d+)"/)?.[1]);
         if(!marker)return shape;
+        if(marker.picture&&bulletRelationship)return shape.replace(/<a:buChar\b[^>]*\/>/g,`<a:buBlip><a:blip r:embed="${bulletRelationship}"/></a:buBlip>`);
         const family=marker.fontFamily.replace(/[&<>"']/g,char=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&apos;'}[char]));
         return shape.replace(/<a:buSzPct val="100000"\/>/g,`<a:buClr>${solidColorXml(marker.color)}</a:buClr><a:buSzPts val="${Math.round(marker.fontSize*100)}"/><a:buFont typeface="${family}"/>`);
       });
@@ -2921,9 +3227,12 @@ function normalizeNestedZip(bytes, context) {
   const entries = unzipSync(bytes);
   const output = {};
   for (const path of Object.keys(entries).sort()) {
+    // A gap in the chart data is a blank workbook cell, not a numeric cell with an empty value.
     const entryBytes = path === "docProps/core.xml"
       ? encodeText(normalizeCoreProperties(decodeText(entries[path]), context.timestamp))
-      : entries[path];
+      : /^xl\/worksheets\/sheet\d+\.xml$/.test(path)
+        ? encodeText(decodeText(entries[path]).replace(/<c ((?:r|s)="[^"]*"(?: (?:r|s)="[^"]*")*)><v><\/v><\/c>/g, "<c $1/>"))
+        : entries[path];
     output[path] = [entryBytes, {
       level: context.compressionLevel,
       mtime: context.zipDate
@@ -3050,6 +3359,12 @@ function parsedNumber(value) {
   return Number.isFinite(parsed) ? parsed : null;
 }
 
+// PptxGenJS writes a gap (null) as `<c:pt idx="n"><c:v></c:v></c:pt>`. A native gap is a numeric cache with no point at that
+// index (ptCount keeps the row count); an empty value is not a number, so drop those points, leaving the index unwritten.
+function omitEmptyNumberPoints(xml) {
+  return xml.replace(/<c:numCache>[\s\S]*?<\/c:numCache>/g, cache => cache.replace(/<c:pt idx="\d+"><c:v><\/c:v><\/c:pt>/g, ""));
+}
+
 function numericValue(value) {
   return parsedNumber(value) ?? 0;
 }