@openpresentation/opf-pptx 0.11.6 → 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();
@@ -245,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();
@@ -326,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]))) {
@@ -352,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);
@@ -361,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);
 
@@ -375,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) {
@@ -473,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);
 }
@@ -535,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);
@@ -558,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;
@@ -611,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));
@@ -642,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);
@@ -719,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;
@@ -744,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 } : {})
       }
     }
   };
@@ -772,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
       };
@@ -829,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) {
@@ -856,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)
         ))
       };
     }
@@ -1159,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);
@@ -1185,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
   };
 }
 
@@ -1208,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);
 }
 
@@ -1314,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.
@@ -1330,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.'});
     }
   }
@@ -1350,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;
@@ -1384,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()){
@@ -1522,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)=>{
@@ -1530,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:{}});
@@ -1592,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,
@@ -1619,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;
@@ -1631,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) {
@@ -1660,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;
@@ -1668,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) {
@@ -1686,14 +1892,15 @@ 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 (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.`});
     }
@@ -1712,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,
@@ -1893,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}
@@ -1913,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) {
@@ -2055,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}`;
@@ -2089,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.
@@ -2296,7 +2512,9 @@ function toPptxChartData(chart, chartexMode = 'auto') {
   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) {
@@ -2340,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) {
@@ -2411,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)) {
@@ -2450,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)];
 }
 
@@ -2481,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);
@@ -2550,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);
@@ -2559,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);
@@ -2575,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);
     }
@@ -2614,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.
@@ -2817,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];
@@ -2838,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}"/>`);
       });
@@ -2926,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
@@ -3055,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;
 }