@openpresentation/opf-pptx 0.17.0 → 0.18.1

package/dist/index.js

@@ -10,7 +10,7 @@ import {applyChartNumberFormats,chartNumber,excelCode,formattedColumns,inlineCha
 import {attachDataProvenance,chartDataRecord,chartEvidence,readDataTag,readDatasetsTag,restoreChartData,restoreTableData,tableDataRecord,tableCellEvidence,tableEnvironmentEvidence} from './data-provenance.js';
 import {CHARTEX_FALLBACK,resolveChartType,chartTypeFromNative,applyChartConstruct,comboFromNative,NATIVE_CHART_ELEMENTS} from './chart-types.js';
 import {attachChartexParts,chartFromChartex,CHARTEX_GRAPHIC_DATA_URI} from './chartex.js';
-import {applyFrameAlt,readFrameAlt} from './frame-alt.js';
+import {applyFrameAlt,readFrameAlt,writeFrameAlt} from './frame-alt.js';
 import {applyDataLabels,chartOptionsFromClassic,chartTargetFor,classicChartOptions,reportChartOptionDiagnostics,resolveChartOptionsFor} from './chart-options.js';
 import {attachCodeTags, attachTextTags, codeManifest, importCodeGroups, nativeShapeParagraphs, nativeTextShapes} from './code-provenance.js';
 import {attachMetricTags,metricManifest,importMetricGroups} from './metric-provenance.js';
@@ -20,26 +20,28 @@ import {attachMediaTags,importMediaGroups,mediaCaption,mediaFrameRecord,mediaTex
 import {addCaption, addFootnotes} from './annotation-export.js';
 import {attachAnnotationTags, captionValue, importAnnotations, restoreCitations} from './annotation-provenance.js';
 import {attachHeadingTags,importHeadingGroups} from './heading-provenance.js';
-import {headingValue,joinRichLines} from './rich-heading.js';
+import {cleanBase,headingValue,joinRichLines} from './rich-heading.js';
 import {attachPlainTextTags,importPlainTextGroups} from './text-provenance.js';
 import {attachTimelineTags,timelineManifest,importTimelineGroups} from './timeline-provenance.js';
 import {attachQuoteTags,quoteManifest,importQuoteGroups,quotePhotoName} from './quote-provenance.js';
-import {attachFurnitureTags, furnitureManifest, importFurniture, manifestPartIndex, staticDateFallback} from './furniture-provenance.js';
+import {attachFurnitureTags, furnitureManifest, importFurniture, logoShape, staticDateFallback, stampFurnitureImageKeys} from './furniture-provenance.js';
 import {restoreRunColors} from './run-colors.js';
 import {joinWrappedText} from './content-topology.js';
-import {applyDocumentProvenance, attachDocumentProvenance, documentProvenance, recordContentTopology, restoreDocumentProvenance, joinAuthors, splitAuthors, slideListBreaks, storedMetadata, DEFAULT_AUTHOR, DEFAULT_TITLE} from './document-provenance.js';
+import {applyDocumentProvenance, attachDocumentProvenance, documentProvenance, recordContentTopology, recordListRuns, restoreDocumentProvenance, joinAuthors, splitAuthors, slideListRecord, storedMetadata, DEFAULT_AUTHOR, DEFAULT_TITLE} from './document-provenance.js';
 import {INVALID_XML_CHARACTER, nativeSections, writeSectionList} from './sections.js';
 import {attachFurnitureFields, furniturePartFields, lineFields, nativeFieldType} from './furniture-fields.js';
 import {attachNativePlaceholders, defaultPlaceholderGeometry, nativeDateText, nativeFurnitureParts, nativePlaceholderForPart, writeNativeMasters} from './native-furniture.js';
+import {liftMasterFurniture} from './master-furniture.js';
 import {importImageOrientation} from './image-import.js';
 import {extractSignals, normalizeSignalOptions, themeFactsFor} from './import-signals.js';
-import {placeImages, importImages, imageName, imageOverlayName, backgroundImageName, backgroundOverlayName, IMAGE_TREATMENT_KEYS, BACKGROUND_IMAGE_KEYS} from './image-provenance.js';
+import {placeImages, importImages, importImagePlaceholders, isImagePlaceholderGroup, imageName, imageOverlayName, imagePlaceholderGroupName, backgroundImageName, backgroundOverlayName, IMAGE_TREATMENT_KEYS, BACKGROUND_IMAGE_KEYS, IMAGE_PLACEHOLDER_TAG} from './image-provenance.js';
 import {dedupeMedia} from './media-dedupe.js';
 import {placeWatermarks, importWatermark, importTextWatermark, tagTextWatermarks, watermarkName, watermarkTextName, watermarkBox, watermarkOpacity} from './watermark-provenance.js';
 import {placeLogos, importLogo, importLogoPlaceholders, logoName, LOGO_TAG} from './logo-provenance.js';
 import {nativeBackgroundFill, nativeImageBackgroundFill, nativePatternPreset} from './background.js';
 import {importBackground} from './background-import.js';
 import {chartHighlightPlan, applyChartHighlight} from './chart-highlight.js';
+import {orderChartSeries} from './chart-order.js';
 import {themeSlotColors, writeThemeColors, schemeColorValue, schemeBackgroundFill, schemeBackgroundValue, defaultTextSchemeValues, tableTextSchemeValue, solidColorXml, writeMasterBackground, inheritLayoutBackground, readThemeSlotColors, recoverColorScheme, recoverTheme, presentationThemePath} from './theme-colors.js';
 import {languageDiagnostics, observeLanguage, observedRtl, partScriptFonts, physicalAlignment, planScriptFonts, planSlideThemes, reconcileLanguage, reportPerSlideNotesScriptFonts, runLanguageFonts, runLanguageTag, stripRunScriptFonts, themeEastAsianFromLatin} from './script-fonts.js';
 import { webpToPng, svgToPng, readLocalFile, localFileReadable } from '#image-fallback';
@@ -254,6 +256,9 @@ export async function toPptx(input, options = {}) {
   const context = resolvePresentationContext(presentation, {...options,textMeasurement:undefined});
   context.listMarkers = new Map();
   context.imagePlaceholders = new Map();
+  // opf-pptx#221: the placeholder panels written as one native group, and the OPF_IMAGE_PLACEHOLDER_V1 records of image blocks.
+  context.imagePlaceholderGroups = new Set();
+  context.imagePlaceholderTags = new Map();
   context.tableHeaders = new Map();
   context.tableCells = new Map();
   // FA-23: every exported image picture (image blocks, the alt-text form of an image background, timeline pictures) and
@@ -278,10 +283,13 @@ export async function toPptx(input, options = {}) {
   context.quoteTags = new Map();
   context.quotePhotos = new Map();
   context.furnitureTags = new Map();
-  context.furnitureLogoTags = new Map();
+  context.furnitureImages = new Map();
   context.furnitureFields = new Map();
   context.furnitureManifests = new Map();
   context.nativeFurniture = new Map();
+  context.nativeFurnitureBands = new Map();
+  // RR-72: each slide's furniture parts and the object names of their shapes, for the slide master and layouts.
+  context.furnitureParts = [];
   context.hostDate = options.date;
   context.authored = authored;
   context.codeTags = new Map();
@@ -408,6 +416,19 @@ export async function fromPptx(input, options = {}) {
   // Layouts and the master are read once however many slides inherit a placeholder from them (RR-11).
   const cached = read => { const memo = new Map(); return path => { if (!memo.has(path)) memo.set(path, read(path)); return memo.get(path); }; };
   const cachedRelationships = cached(path => parseRelationships(entries, path)), cachedPart = cached(path => parseOptionalXml(entries, path));
+  // RR-72: the furniture a slide shows from its layout and slide master (src/master-furniture.js), read once per part.
+  const inheritedParts = new Map();
+  const inheritedPart = path => {
+    if (!path) return undefined;
+    if (!inheritedParts.has(path)) {
+      const element = /slideMaster/.test(path) ? 'p:sldMaster' : 'p:sldLayout', root = cachedPart(path)?.[element];
+      const tree = root?.['p:cSld']?.['p:spTree'];
+      inheritedParts.set(path, root ? {path, root, relationships: cachedRelationships(path), shapes: nativeTextShapes(tree), pictures: nativePictures(tree),
+        paragraphs: nativeShapeParagraphs(decodeText(entries[path]), element)} : undefined);
+    }
+    return inheritedParts.get(path);
+  };
+  const relatedPath = (path, type) => path ? [...cachedRelationships(path).values()].find(rel => rel.type === `http://schemas.openxmlformats.org/officeDocument/2006/relationships/${type}` && rel.targetMode !== 'External' && entries[rel.path])?.path : undefined;
   const furnitureContexts = slidePaths.map((slidePath, index) => {
     const root = parseRequiredXml(entries, slidePath)['p:sld'];
     if (!root) throw new OPFPptxError('invalid-pptx', `PPTX slide is not a PresentationML slide: ${slidePath}.`, {path: slidePath});
@@ -417,7 +438,12 @@ export async function fromPptx(input, options = {}) {
       path: slidePath, slideWidth: Number(presentationRoot['p:sldSz']?.cx), relationshipsOf: cachedRelationships, readPart: cachedPart,
       paragraphs: nativeShapeParagraphs(decodeText(entries[slidePath])),
       readPicture: picture => importPicture(entries, picture, slidePath, relationships,
-        diagnostic => options.onDiagnostic?.({...diagnostic, path: `slides.${index}.design`}))};
+        diagnostic => options.onDiagnostic?.({...diagnostic, path: `slides.${index}.design`})),
+      inherited: () => {
+        const layout = relatedPath(slidePath, 'slideLayout'), master = relatedPath(layout, 'slideMaster');
+        return Object.fromEntries([['layout', inheritedPart(layout)], ['master', inheritedPart(master)]].filter(([, part]) => part).map(([on, part]) => [on, {...part,
+          readPicture: picture => importPicture(entries, picture, part.path, part.relationships, diagnostic => options.onDiagnostic?.({...diagnostic, path: `slides.${index}.design`}))}]));
+      }};
   });
   // Native sections (PowerPoint's own section list, `Default Section` = none) name each slide's `{{slide.section}}` for the footer text check
   // and, after the slides, are reconciled with the stored value in restoreDocumentProvenance.
@@ -432,7 +458,7 @@ export async function fromPptx(input, options = {}) {
     ...(stored.organization !== undefined ? {organization: stored.organization} : {}),
     ...(stored.speaker !== undefined ? {speaker: stored.speaker} : {}),
   };
-  const furniture = importFurniture(furnitureContexts, entries, options.onDiagnostic, {sections: slideSections ?? [], organizations: asArray(stored.organization).filter(item => isPlainObject(item) && typeof item.id === 'string' && typeof item.name === 'string').map(item => ({id: item.id, name: item.name})),
+  const furniture = importFurniture(furnitureContexts, entries, options.onDiagnostic, {sections: slideSections ?? [], organizations: asArray(stored.organization).filter(item => isPlainObject(item) && typeof item.id === 'string' && typeof item.name === 'string').map(item => ({id: item.id, name: item.name, ...(typeof item.role === 'string' ? {role: item.role} : {}), ...(logoShape(item.logo) !== undefined ? {logo: logoShape(item.logo)} : {})})),
     draw: (template, {index, count, section}) => drawFurnitureText(template, {index, count, section}, importedMetadata)});
   if (Object.keys(furniture.design).length) imported.design = {...imported.design, ...furniture.design};
   if (furniture.organization) imported.organization = furniture.organization;
@@ -530,21 +556,19 @@ function applyRunColors(imported, slideProvenance, restoredGroups, report, optio
   restoreRunColors(imported.slides, info, resolve, report);
 }
 
-// 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.
+// A consumed logo picture (OPF_LOGO_V1) never becomes content. Its own image restores the organization's logo only when the
+// stored document did not (RR-71: logos live on the organization), so a package exported without provenance still keeps its
+// logo: on the primary organization, else on a new one named after the deck. The picture is one drawn asset, so it becomes the
+// organization's single logo for every shape.
 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};
-  });
+  if (organizations.some(item => item?.logo !== undefined)) return;
+  const image = contexts.map(context => context.logoFallback?.image).find(Boolean);
+  if (!image) return;
+  const primary = organizations.find(item => item?.role === 'primary') ?? organizations[0];
+  if (!primary) { imported.organization = {id: 'brand', name: imported.name ?? 'Brand', logo: image}; return; }
+  const index = organizations.indexOf(primary), withLogo = {...primary, logo: image};
+  imported.organization = Array.isArray(imported.organization) ? imported.organization.map((item, at) => at === index ? withLogo : item) : withLogo;
 }
 
 function readPptxZip(input) {
@@ -752,7 +776,7 @@ 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).
+  // The generated cover logo picture is not content; the logo returns from the stored organization (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 => {
@@ -795,8 +819,8 @@ function importSlide(entries, slidePath, slideIndex, presentationDimensions, opt
       item.text = current.map(paragraph => paragraph.text).join('\n');
     }
   }
-  const listBreaks = slideListBreaks(entries, slidePath, slideRoot, relationships);
-  const content = mergeAdjacentBulletShapes(mergeOpfListShapes(items, listBreaks, diagnostic => options.onDiagnostic?.({...diagnostic, path: `slides.${slideIndex}`})))
+  const listRecord = slideListRecord(entries, slidePath, slideRoot, relationships);
+  const content = mergeAdjacentBulletShapes(mergeOpfListShapes(items, listRecord.breaks, diagnostic => options.onDiagnostic?.({...diagnostic, path: `slides.${slideIndex}`}), listRecord.runs))
     .map((item) => ({payload: payloadFromSlideItem(item, diagnostic => options.onDiagnostic?.({...diagnostic, path: `slides.${slideIndex}`})), bounds: item.visualBounds ?? item.bounds, sources: item.sources ?? []}))
     .filter((entry) => entry.payload);
   const blocks = content.map((entry) => entry.payload);
@@ -840,7 +864,8 @@ function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensi
   const tree = slideRoot["p:cSld"]?.["p:spTree"];
   const items = [];
   const shapes = nativeContext.shapes;
-  if (tree?.['p:grpSp']) options.onDiagnostic?.({code:'grouped-text-reflow',path:`slides.${slideIndex}`,message:'Grouped native text and pictures are retained, but group transforms and unsupported group members are not reconstructed; review the reflowed OPF.'});
+  // opf-pptx#221: an exported image placeholder group (identity transform) is not a reflow risk.
+  if (asArray(tree?.['p:grpSp']).some(group => !isImagePlaceholderGroup(group))) options.onDiagnostic?.({code:'grouped-text-reflow',path:`slides.${slideIndex}`,message:'Grouped native text and pictures are retained, but group transforms and unsupported group members are not reconstructed; review the reflowed OPF.'});
   const paragraphs = nativeContext.paragraphs;
   // FF-45: OMML equations (a14:m math zones) have no OPF model. Their fallback text is imported as plain text; the equation
   // layout (fractions, radicals, limits, matrices) is lost, and that loss is diagnosed per shape instead of passing silently.
@@ -894,11 +919,17 @@ function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensi
   for (const item of code.items) items.push({kind:'code',bounds:shapeBounds(item.shape['p:spPr']?.['a:xfrm']),payload:item.payload,sources:sourcesOf([item.shape])});
   for (const item of metric.items) items.push({kind:'metric',bounds:shapeBounds(item.shape['p:spPr']?.['a:xfrm']),payload:item.payload,sources:sourcesOf([item.shape])});
   for (const item of media.items) items.push({kind:'media',sourceText:item.payload.type==='text',bounds:shapeBounds(item.shape['p:spPr']?.['a:xfrm']),payload:item.payload,sources:sourcesOf([item.shape])});
+  // opf-pptx#221: a tagged unavailable-image placeholder is its image block again; its panel and label shapes are consumed.
+  const placeholders = importImagePlaceholders({shapes, relationships, entries, slideIndex, valid: payload => isValidFormat({slides: [{blocks: [payload]}]}), report: diagnostic => options.onDiagnostic?.(diagnostic)});
+  for (const item of placeholders.items) {
+    for (const member of item.members) roles.set(`sp:${member}`, 'image');
+    items.push({kind: 'image', bounds: shapeBounds(shapes[item.panel]['p:spPr']?.['a:xfrm']), payload: item.payload, sources: item.members.map(member => `sp:${member}`)});
+  }
   for (const [index,shape] of shapes.entries()) {
     const role = furniture.text.has(index) ? 'furniture' : nativeContext.imageShapes?.has(index) ? 'image-overlay' : nativeContext.watermarkShapes?.has(index) ? 'watermark' : nativeContext.logoPlaceholderShapes?.has(index) ? 'logo' : cards.has(shape) ? 'card-frame'
       : code.consumed.has(shape) ? 'code' : metric.consumed.has(shape) ? 'metric' : media.consumed.has(shape) ? 'media' : timelines.consumed.has(shape) ? 'timeline' : quotes.consumed.has(shape) ? 'quote' : undefined;
     if (role) roles.set(shapeKeys.get(shape), role);
-    if (furniture.text.has(index) || nativeContext.imageShapes?.has(index) || nativeContext.watermarkShapes?.has(index) || nativeContext.logoPlaceholderShapes?.has(index)) continue;
+    if (furniture.text.has(index) || nativeContext.imageShapes?.has(index) || nativeContext.watermarkShapes?.has(index) || nativeContext.logoPlaceholderShapes?.has(index) || placeholders.consumed.has(index)) continue;
     if (annotations.consumed.has(shape)) { roles.set(shapeKeys.get(shape), 'annotation'); continue; }
     if (code.consumed.has(shape)||metric.consumed.has(shape)||cards.has(shape)||media.consumed.has(shape)||headings.consumed.has(shape)||plainText.consumed.has(shape)||timelines.consumed.has(shape)||quotes.consumed.has(shape)) continue;
     const ordinaryBody = Object.hasOwn(shape, 'p:txBody') && !shape['p:nvSpPr']?.['p:nvPr']?.['p:custDataLst']?.['p:tags'];
@@ -1000,7 +1031,7 @@ function importGraphicFrame(entries, frame, slidePath, relationships, importedTa
   };
   if (table) {
     const stored = importedTable && record('table');
-    const restoredTable = stored ? restore('table', importedTable, () => restoreTableData(importedTable, stored, {evidence: tableCellEvidence(table, relationships), environment: tableEnvironmentEvidence(entries), datasets: data.datasets, report: diagnostic => data.report?.('table', diagnostic)})) : importedTable;
+    const restoredTable = stored ? restore('table', importedTable, () => restoreTableData(importedTable, stored, {evidence: tableCellEvidence(table, relationships), olderEvidence: [tableCellEvidence(table, relationships, {form: 'raw'}), tableCellEvidence(table, relationships, {form: 'saved'})], environment: tableEnvironmentEvidence(entries), datasets: data.datasets, report: diagnostic => data.report?.('table', diagnostic)})) : importedTable;
     // FA-27: the frame's descr (or PowerPoint's decorative marker) is the table's text alternative.
     const alt = restoredTable && typeof restoredTable === 'object' ? readFrameAlt(frame["p:nvGraphicFramePr"]?.["p:cNvPr"]) : undefined;
     return {
@@ -1220,10 +1251,13 @@ function joinRich(a, b) {
   }
   return joined;
 }
-// `breaks` (slideListBreaks) holds the whitespace of the hard breaks the export recorded, by list path and line number: the
+// `breaks` (slideListRecord) holds the whitespace of the hard breaks the export recorded, by list path and line number: the
 // continuation line after a break joins with it, so a newline inside an item (or a description) returns. A blank line is a
 // native shape with no text: it is never a description. Without a record the lines join without a separator, as before.
-function mergeOpfListShapes(items, breaks = null, report = () => {}) {
+// `runs` (opf-pptx#212) holds the look export wrote on every run of a list ({text, description?}): a run value still equal to
+// it is inherited formatting, not authored run style, and is removed (as for a tagged heading), so an untouched round trip
+// adds no explicit sizes, families or colours; a value edited in PowerPoint differs and is kept. Without it runs are as read.
+function mergeOpfListShapes(items, breaks = null, report = () => {}, runs = null) {
   const lists = new Map();
   for (const item of items) {
     const match = /^OPF list (.+) line (\d+)$/.exec(item.name ?? '');
@@ -1236,6 +1270,26 @@ function mergeOpfListShapes(items, breaks = null, report = () => {}) {
   for (const [path, entries] of lists) {
     entries.sort((a, b) => a.line - b.line);
     if (!entries[0].item.paragraphs[0].bullet) continue;
+    const look = runs?.get(path), textLook = cleanBase(look?.text), descriptionLook = cleanBase(look?.description);
+    // The line's runs without the inherited look, or the paragraph's own richText when there is no record for this kind of line.
+    // Each run is cleaned on its own and none merge, so the runs stay the slots the run colour record counts (src/run-colors.js);
+    // they stay run objects until the lines are joined (as before), then `plain` gives the authored form back.
+    const own = (paragraph, base) => {
+      if (!base) return paragraph.richText;
+      return richRuns(paragraph.richText ?? paragraph.text).flatMap(run => {
+        const value = headingValue([run], base);
+        const parts = value === '' ? [] : typeof value === 'string' ? [{text: value}] : value.map(part => typeof part === 'string' ? {text: part} : part);
+        // A removed colour stays known until the run colour references are restored (restoreRunColors): an authored `text`
+        // role equals the inherited colour natively.
+        if (typeof run === 'object' && typeof run.color === 'string' && parts.length === 1 && parts[0].color === undefined) parts[0]._opfInherited = run.color;
+        return parts;
+      });
+    };
+    const plain = value => {
+      if (!Array.isArray(value)) return value;
+      const runs = value.map(run => typeof run === 'object' && Object.keys(run).length === 1 ? run.text : run);
+      return runs.length === 0 ? '' : runs.length === 1 && typeof runs[0] === 'string' ? runs[0] : runs;
+    };
     const paragraphs = [];
     const recorded = breaks?.get(path), applied = new Set();
     let bounds, size = 0;
@@ -1243,16 +1297,16 @@ function mergeOpfListShapes(items, breaks = null, report = () => {}) {
       const [paragraph] = item.paragraphs, current = paragraphs.at(-1);
       const gap = recorded?.get(line);
       const join = (a, b) => gap === undefined ? joinRich(a, b) : joinWrappedText([a, b], [gap]);
-      if (paragraph.bullet) { paragraphs.push({...paragraph}); size = paragraph.maxFontSize; }
+      if (paragraph.bullet) { paragraphs.push({...paragraph, richText: own(paragraph, textLook)}); size = paragraph.maxFontSize; }
       else if (paragraph.text === '') { /* a blank line of the entry: no text, no description */ }
       else if (paragraph.maxFontSize < size - 0.01) {
-        const text = paragraph.richText ?? paragraph.text;
+        const text = own(paragraph, descriptionLook) ?? paragraph.text;
         if (current.description === undefined) current.description = text;
         else { current.description = join(current.description, text); applied.add(line); }
       } else {
-        const before = current.text;
+        const before = current.text, rich = own(paragraph, textLook);
         current.text += (gap === undefined ? '' : Array.isArray(gap) ? gap[0] : gap) + paragraph.text;
-        if (current.richText !== undefined || paragraph.richText !== undefined) current.richText = join(current.richText ?? before, paragraph.richText ?? paragraph.text);
+        if (current.richText !== undefined || rich !== undefined) current.richText = join(current.richText ?? before, rich ?? paragraph.text);
         applied.add(line);
       }
       const b = item.visualBounds ?? item.bounds;
@@ -1263,6 +1317,8 @@ function mergeOpfListShapes(items, breaks = null, report = () => {}) {
       consumed.add(item);
     }
     if (recorded && [...recorded.keys()].some(line => !applied.has(line))) report({code: 'list-line-break-changed', message: `A hard line break recorded at export inside the list ${path} no longer has the continuation line it belonged to (a line was edited away, or became an entry), so that break was not restored; the list keeps the lines it has.`});
+    if (textLook) for (const paragraph of paragraphs) paragraph.richText = plain(paragraph.richText);
+    if (descriptionLook) for (const paragraph of paragraphs) if (paragraph.description !== undefined) paragraph.description = plain(paragraph.description);
     const first = entries[0].item;
     merged.set(first, {...first, paragraphs, text: paragraphs.map(paragraph => paragraph.text).join('\n'), bounds, visualBounds: undefined, sources: entries.flatMap(({item}) => item.sources ?? [])});
   }
@@ -1948,6 +2004,7 @@ async function addSlide(pptx, presentation, authoredSlide, slideIndex, context,
   const geometry = composeSlide(opfSlide, composeOptions);
   // The default footer band (date left, text center, number right): where a footer added natively lands (RR-11).
   if (slideIndex === 0) context.defaultFooterOptions = composeOptions;
+  slideContext.zoneBand = zoneBands(composeOptions);
   slide.background = { color: slideContext.colors.background };
   // An image background is core's geometry.backgroundImage (slide, deck, then theme background); every other kind is the
   // effective design or theme background definition.
@@ -2008,6 +2065,8 @@ async function addSlide(pptx, presentation, authoredSlide, slideIndex, context,
       });
     } else if ((item.field === "items" || item.field === "bullets") && item.text?.listEntries) {
       await addMeasuredList(slide,item.text,itemContext,item.path,item.bulletImage,presentation,slideIndex,options,item.payload?.numbering!==undefined);
+      // opf-pptx#212: the look every run of the list is written with where its source states none (full provenance only).
+      if(item.textStyle)recordListRuns(context.documentProvenance,slideIndex,item.path,listRunLook(item.text,item.textStyle,itemContext));
     } else if (["text", "title", "subtitle", "tag"].includes(item.field) && item.text?.richLines) {
       // FA-10: a TextRun[] heading draws and exports like rich body text; its lines are named and tagged as a heading (the body's are not).
       const heading = item.field !== 'text';
@@ -2142,6 +2201,14 @@ function addTextPayload(slide, value, region, context) {
   slide.addText(stringifyText(value), textBoxOptions(region, context, 18));
 }
 
+// opf-pptx#212: the look (richBase) the runs of a measured list are written with where the source states none: {text,
+// description?}, or undefined when its entries do not share one (import then reads every run value as observed).
+function listRunLook(fit,style,context){
+  const looks=kind=>new Set(fit.listEntries.filter(entry=>entry[kind]).map(entry=>JSON.stringify(richBase(entry[kind],style,kind==='text'?context.colors.text:context.colors.mutedText))));
+  const text=looks('text'),description=looks('description');
+  if(text.size!==1||description.size>1)return undefined;
+  return {text:JSON.parse([...text][0]),...(description.size?{description:JSON.parse([...description][0])}:{})};
+}
 function richLineRuns(line,color,native,context) {
   const fallback=color.replace(/^#/,'');
   return line.fragments.map(fragment=>{
@@ -2245,9 +2312,10 @@ function addListPayload(slide, items, region, context) {
 }
 
 // A content picture outside an image block (a timeline event image): one native picture contained in its region.
-async function addImagePayload(slide, presentation, asset, region, path, context, options) {
+// Generated furniture is never grouped (src/master-furniture.js), so a furniture part passes {group: false}.
+async function addImagePayload(slide, presentation, asset, region, path, context, options, {group = true} = {}) {
   const name = await addImagePicture(slide, presentation, asset, region, path, context, options, {fit: 'contain'});
-  if (!name) addImagePlaceholder(slide, presentation, asset, region, path, context, options);
+  if (!name) addImagePlaceholder(slide, presentation, asset, region, path, context, options, {group});
   return name;
 }
 
@@ -2327,8 +2395,13 @@ async function addImageItem(slide, presentation, item, slideIndex, context, opti
     fit: image.fit, focus: image.focus, effects: treated ? effects : null, shrink: !treated && !image.placement, treatment: tagged ? treatment : undefined
   });
   if (!name) {
-    addImagePlaceholder(slide, presentation, item.value, box, item.path, context, options);
-    return `OPF image placeholder ${context.imagePlaceholders.size}`;
+    const panel = addImagePlaceholder(slide, presentation, item.value, box, item.path, context, options);
+    // opf-pptx#221: in full mode the panel records the authored image and the block's own fields, so import restores the block.
+    if (context.provenanceMode === 'full') {
+      const fields = Object.fromEntries(IMAGE_TREATMENT_KEYS.filter(key => block[key] !== undefined).map(key => [key, structuredClone(block[key])]));
+      context.imagePlaceholderTags.set(panel, {v: 1, slide: `slides.${slideIndex}`, path: item.path, image: structuredClone(item.value), ...(Object.keys(fields).length ? {treatment: fields} : {})});
+    }
+    return panel;
   }
   if (image.overlay) addImageOverlay(slide, image.overlay, structuredClone(block.overlay), imageOverlayName(name), name, { ...context, slidePath: `slides.${slideIndex}` }, effects);
   return name;
@@ -2809,10 +2882,19 @@ function defaultFooterParts(composeOptions) {
   }
 }
 
+// The band core gives a lone text part in a zone (x and width in pixels): where a footer added natively sits.
+function zoneBands(composeOptions) {
+  let bands;
+  return zone => (bands ??= new Map((defaultFooterParts(composeOptions) ?? []).map(part => [part.zone, {x: part.box.x, width: part.box.width}]))).get(zone);
+}
+
 // The slide and deck as given to toPptx (variables not yet resolved), for the furniture manifest's authored header and footer text.
 const authoredFurniture = (context, slideIndex) => ({presentation: context.authored, slide: context.authored?.slides?.[slideIndex]});
 
 async function addFurniture(slide,presentation,source,layout,context,options,slideIndex) {
+  // RR-72: every slide is listed, a slide without furniture too (it may need a layout that hides the master's).
+  const drawn = [];
+  context.furnitureParts[slideIndex] = {path: `ppt/slides/slide${slideIndex + 1}.xml`, parts: drawn};
   if(!layout){
     if(['header','footer'].some(kind=>(source.design?.[kind]??presentation.design?.[kind])))throw new OPFPptxError('missing-furniture-layout','Header/footer export requires coordinated core furniture geometry.',{path:`slides.${slideIndex}.design`});
     const manifest = furnitureManifest(presentation, source, {parts: []}, slideIndex, undefined, undefined, authoredFurniture(context, slideIndex));
@@ -2823,12 +2905,18 @@ async function addFurniture(slide,presentation,source,layout,context,options,sli
   // RR-11: the first footer text, date and slide number that fit one line are native placeholders (src/native-furniture.js).
   const natives = nativeFurnitureParts(layout);
   for(const [index,part]of layout.parts.entries()){
+    const entry = {index, kind: part.kind, zone: part.zone, field: part.field, type: part.type, path: part.path, native: natives.has(index), names: []};
+    drawn.push(entry);
     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,options);
-      // A generated deck logo is listed beside the manifest topology (see furnitureManifest) and tagged as a logo.
-      if (objectName && part.field === 'logo') context.furnitureLogoTags.set(objectName, {v:1, role:'furniture', group:String(slideIndex), furniture:part.kind, zone:part.zone});
-      else if (objectName) context.furnitureTags.set(objectName, {v:1, role:'image', group:String(slideIndex), part:manifestPartIndex(layout.parts, index)});
+      // A logo reference draws the organization's asset: a source that cannot be drawn is reported where the asset is written.
+      const objectName = await addImagePayload(slide,presentation,part.image,region,part.reference!==undefined?part.sourcePath:part.path,context,options,{group:false});
+      if (objectName) {
+        entry.names.push(objectName);
+        context.furnitureTags.set(objectName, {v:1, role:'image', group:String(slideIndex), part:index});
+        // RR-71: a part drawn from a logo reference (var:organization.logo.icon) records its picture, so import can tell it is unchanged.
+        if (part.reference !== undefined) context.furnitureImages.set(`ppt/slides/slide${slideIndex + 1}.xml|${part.kind}.${part.zone}`, objectName);
+      }
     }else{
       if(!part.fit?.sourceLines)throw new OPFPptxError('missing-furniture-layout','Repeated text requires accepted source lines from core.',{path:part.path});
       // Slide numbers ({{slide.number}}) and current dates become native PowerPoint fields; {{deck.slideCount}},
@@ -2848,8 +2936,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:manifestPartIndex(layout.parts,index)},liveFields,links:part.links});
-      if(natives.has(index))context.nativeFurniture.set(`OPF furniture ${slideIndex} part ${index} line 0`,natives.get(index));
+      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});
+      entry.names.push(...part.fit.lines.map((line, number) => `OPF furniture ${slideIndex} part ${index} line ${number}`));
+      if(natives.has(index)){
+        const name=`OPF furniture ${slideIndex} part ${index} line 0`;
+        context.nativeFurniture.set(name,natives.get(index));
+        // RR-71: a part in a row with other parts is as wide as its text; the master's placeholder spans the zone.
+        const band=context.zoneBand?.(part.zone);
+        if(band&&part.box.width<band.width-.5)context.nativeFurnitureBands.set(name,band);
+      }
     }
   }
   const manifest = furnitureManifest(presentation, source, layout, slideIndex, staticDates, natives, authoredFurniture(context, slideIndex));
@@ -3087,9 +3182,10 @@ 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>".
-// {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} = {}) {
+// The panel's other shapes are named after it (OPF image placeholder N text line i / icon i) and the panel's name is returned,
+// so a logo placeholder can be tagged and consumed on import. opf-pptx#221: unless it is a logo's ({logo: true}) or furniture's
+// ({group: false}) placeholder, packaging writes the panel and those shapes as one native group carrying the accessible name.
+function addImagePlaceholder(slide, presentation, asset, region, path, context, options, {logo = false, group = !logo} = {}) {
   const layered = placeholderAsset(asset, presentation);
   const description = String(layered.alt ?? layered.title ?? "Image");
   const label = `Image unavailable\n${description}`;
@@ -3110,6 +3206,8 @@ function addImagePlaceholder(slide, presentation, asset, region, path, context,
   const fit = fitText(label, inner, 20 * scale, minimum, measurer);
   const objectName = `OPF image placeholder ${context.imagePlaceholders.size + 1}`;
   context.imagePlaceholders.set(objectName, `Image unavailable: ${description}`);
+  if (group) context.imagePlaceholderGroups.add(objectName);
+  const named = logo || group;
   slide.addShape("rect", {
     x: region.x, y: region.y, w: region.w, h: region.h,
     fill: { color: surface },
@@ -3123,18 +3221,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, ...(logo ? {objectName: `${objectName} text`} : {})
+      diagnosticsHandled: true, align: "center", color: textColor, ...(named ? {objectName: `${objectName} text`} : {})
     });
-    return logo ? objectName : undefined;
+    return objectName;
   }
   // 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 logo ? objectName : undefined;
+  if (!size) return objectName;
   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, ...(logo ? {objectName: `${objectName} icon ${flipV ? 2 : 1}`} : {}) });
-  return logo ? objectName : undefined;
+  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, ...(named ? {objectName: `${objectName} icon ${flipV ? 2 : 1}`} : {}) });
+  return objectName;
 }
 
 // A placeholder names what is missing in plain words. It never dumps the source value, so no data or URL lands in slide text.
@@ -3555,7 +3653,7 @@ async function resolveImage(asset, presentation, options, path, outcome = {}) {
   if (raster) return dataUriMediaType(resolved.data) === raster.mediaType ? resolved : {...resolved, data: `data:${raster.mediaType};base64,${bytesToBase64(bytes)}`};
   const svg = svgDataUriBytes(resolved.data);
   if (svg) return resolveSvgImage(svg, options, path, outcome);
-  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).`;
+  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 toPng).`;
   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;
@@ -3799,11 +3897,13 @@ async function normalizePptxZip(raw, context) {
   attachQuoteTags(entries,context.quoteTags);
   attachAnnotationTags(entries,context);
   attachFurnitureFields(entries,context.furnitureFields);
-  attachFurnitureTags(entries,context.furnitureTags,context.furnitureManifests,context.furnitureLogoTags);
+  attachFurnitureTags(entries,context.furnitureTags,context.furnitureManifests);
   // RR-11: the recorded footer shapes become PowerPoint's date, footer and slide-number placeholders.
-  context.nativePlaceholders = attachNativePlaceholders(entries,context.nativeFurniture);
+  context.nativePlaceholders = attachNativePlaceholders(entries,context.nativeFurniture,context.nativeFurnitureBands);
   // 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');
+  // opf-pptx#221: the image block of an unavailable-image placeholder, on its panel (full provenance).
+  attachTextTags(entries,context.imagePlaceholderTags,IMAGE_PLACEHOLDER_TAG,'opfImagePlaceholder','image placeholder');
   for(const [part,bytes]of Object.entries(entries)){
     if(!/^ppt\/slides\/slide\d+\.xml$/.test(part))continue;
     const relationships=parseRelationships(entries,part);
@@ -3836,6 +3936,12 @@ async function normalizePptxZip(raw, context) {
       }
     }
   }
+  // opf-pptx#175: after every chart rewrite, each classic series in its CT_*Ser sequence (src/chart-order.js).
+  for(const part of Object.keys(entries)){
+    if(!/^ppt\/charts\/chart\d+\.xml$/.test(part))continue;
+    const xml=decodeText(entries[part]),ordered=orderChartSeries(xml);
+    if(ordered!==xml)entries[part]=encodeText(ordered);
+  }
   applyChartFonts(entries,context.chartFonts,parseRelationships);
   if (context.frameAlts.size) for (const [part, bytes] of Object.entries(entries)) if (/^ppt\/slides\/slide\d+\.xml$/.test(part)) { const xml = decodeText(bytes), next = applyFrameAlt(xml, context.frameAlts); if (next !== xml) entries[part] = encodeText(next); }
   // Chartex charts: the native cx:chartSpace part, its style parts and the mc:AlternateContent frame (the classic chart above is the fallback).
@@ -3905,6 +4011,8 @@ async function normalizePptxZip(raw, context) {
   });
   // A picture repeated across slides embeds once (after fitting, which needs each slide's own relationship).
   dedupeMedia(entries, imageMetadata, resolveRelationshipTarget);
+  // The media keys of the logo-reference pictures, now that the package holds its final media (src/furniture-provenance.js).
+  stampFurnitureImageKeys(entries, context.furnitureManifests, context.furnitureImages, parseRelationships);
   // Charts and notes follow the language and fonts of the slide they belong to.
   context.partSlides = new Map();
   for (const part of Object.keys(entries)) {
@@ -3951,6 +4059,12 @@ async function normalizePptxZip(raw, context) {
     }
     reportPerSlideNotesScriptFonts(context.scriptFonts, slideThemes);
   }
+  // RR-72: furniture drawn the same on several slides moves to the slide master or a layout (src/master-furniture.js).
+  try {
+    liftMasterFurniture(output, context.furnitureParts, diagnostic => context.reportDiagnostic?.(diagnostic));
+  } catch (error) {
+    throw new OPFPptxError('packaging-failed', 'Header and footer furniture could not be written to the slide master and layouts.', {cause: errorMessage(error)});
+  }
   finalizeFontsUsed(output);
   // Document references record evidence from the final normalized parts.
   if (context.documentProvenance) {
@@ -4172,12 +4286,18 @@ function normalizePartBytes(path, bytes, context, renameMaps, entries, imageMeta
       });
       // PptxGenJS gives shapes no alternative text. An unavailable image's panel
       // carries the accessible name the preview gives its group.
+      const escapes={'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&apos;','\r':'&#13;','\n':'&#10;','\t':'&#9;'};
+      const describe=description=>description.replace(/[&<>"'\r\n\t]/g,char=>escapes[char]);
       xml=xml.replace(/<p:cNvPr id="(\d+)" name="(OPF image placeholder \d+)"(\/?)>/g,(node,id,name,close)=>{
         const description=context.imagePlaceholders.get(name);
         if(description===undefined)return node;
-        const escapes={'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&apos;','\r':'&#13;','\n':'&#10;','\t':'&#9;'};
-        return `<p:cNvPr id="${id}" name="${name}" descr="${description.replace(/[&<>"'\r\n\t]/g,char=>escapes[char])}"${close}>`;
+        // opf-pptx#221: a grouped placeholder's accessible name is on its group (below), as the preview names its <g>. The empty panel
+        // then has no alt text of its own, so it is marked decorative (the adec:decorative extension, "Mark as decorative"), or
+        // PowerPoint's Accessibility Checker flags it. The text lines carry text and are not marked. PptxGenJS writes this cNvPr self-closing.
+        if(context.imagePlaceholderGroups.has(name))return close?writeFrameAlt(node,''):node;
+        return `<p:cNvPr id="${id}" name="${name}" descr="${describe(description)}"${close}>`;
       });
+      xml=groupImagePlaceholders(xml,context.imagePlaceholderGroups,name=>describe(context.imagePlaceholders.get(name)));
       // PptxGenJS 4.0.1 emitted pPr before each rich run (pptxgenjs-plus writes
       // one). OOXML allows one pPr, before all runs. Paragraph options belong
       // to the first run.
@@ -4205,6 +4325,34 @@ function normalizePartBytes(path, bytes, context, renameMaps, entries, imageMeta
 // their explicit per-shape buFont; only the master bodyStyle is touched.
 const VENDOR_MASTER_BULLET_FONT = '<a:buFont typeface="Arial" pitchFamily="34" charset="0"/>';
 const THEME_MINOR_BULLET_FONT = '<a:buFont typeface="+mn-lt"/>';
+// opf-pptx#221: each unavailable-image placeholder (panel, then its label lines or cross strokes, written consecutively) becomes
+// one p:grpSp (CT_GroupShape: nvGrpSpPr, grpSpPr, members) named "<panel> group" with the accessible name as its descr. Its
+// transform is the identity (chOff/chExt equal off/ext, the members' union), so every member keeps its box and stays an
+// editable shape; tags and names stay on the members.
+function groupImagePlaceholders(xml,panels,description){
+  if(!panels.size)return xml;
+  let next=Math.max(0,...[...xml.matchAll(/<p:cNvPr\b[^>]*\bid="(\d+)"/g)].map(match=>Number(match[1])))+1;
+  const nameOf=shape=>shape.match(/<p:cNvPr\b[^>]*\bname="([^"]*)"/)?.[1]??'';
+  const memberOf=(panel,name)=>name.startsWith(`${panel} `)&&/^(?:text line|icon) \d+$/.test(name.slice(panel.length+1));
+  return xml.replace(/<p:sp>[\s\S]*?<\/p:sp>(?:<p:sp>[\s\S]*?<\/p:sp>)*/g,run=>{
+    const shapes=run.match(/<p:sp>[\s\S]*?<\/p:sp>/g);
+    let out='';
+    for(let index=0;index<shapes.length;index++){
+      const panel=nameOf(shapes[index]);
+      if(!panels.has(panel)){out+=shapes[index];continue;}
+      const members=[shapes[index]];
+      while(index+1<shapes.length&&memberOf(panel,nameOf(shapes[index+1])))members.push(shapes[++index]);
+      const boxes=members.map(shape=>shape.match(/<a:off x="(-?\d+)" y="(-?\d+)"\/><a:ext cx="(\d+)" cy="(\d+)"\/>/)).filter(Boolean).map(match=>match.slice(1).map(Number));
+      if(!boxes.length){out+=members.join('');continue;}
+      const x=Math.min(...boxes.map(box=>box[0])),y=Math.min(...boxes.map(box=>box[1]));
+      const cx=Math.max(...boxes.map(box=>box[0]+box[2]))-x,cy=Math.max(...boxes.map(box=>box[1]+box[3]))-y;
+      out+=`<p:grpSp><p:nvGrpSpPr><p:cNvPr id="${next++}" name="${imagePlaceholderGroupName(panel)}" descr="${description(panel)}"/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr>`+
+        `<p:grpSpPr><a:xfrm><a:off x="${x}" y="${y}"/><a:ext cx="${cx}" cy="${cy}"/><a:chOff x="${x}" y="${y}"/><a:chExt cx="${cx}" cy="${cy}"/></a:xfrm></p:grpSpPr>${members.join('')}</p:grpSp>`;
+    }
+    return out;
+  });
+}
+
 function themeMasterBulletFonts(xml) {
   return xml.replace(/<p:bodyStyle>[\s\S]*?<\/p:bodyStyle>/, bodyStyle =>
     bodyStyle.split(VENDOR_MASTER_BULLET_FONT).join(THEME_MINOR_BULLET_FONT));

package/dist/logo-provenance.js

@@ -3,13 +3,13 @@ import {normalizeCrop, withoutSvgBlip} from './svg-image.js';
 import {decodeTextTag, encodeTextTag} from './code-provenance.js';
 import {pictureTransform} from './image-geometry.js';
 
-// The deck logo (core's `geometry.logo`: design.logo, a slide's own logo or the
-// primary organization's logo on a cover or section slide) exports as one native
+// The cover and section logo (core's `geometry.logo`: the primary organization's full logo, or the
+// organization a `design.logo` reference names, RR-71) exports as one native
 // picture per slide named `OPF logo`, after the watermark and before content. It
 // is fitted into core's box without cropping, anchored left and vertically
 // centered (the preview's `xMinYMid meet`). The native tag records the exact
 // picture, so an unchanged picture is consumed on import (the logo itself returns
-// from the document and slide design records) while an edited one stays an
+// from the document record's organization) while an edited one stays an
 // ordinary picture and reports `invalid-logo-provenance`.
 const TAG = 'OPF_LOGO_V1', REL = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/tags';
 const EMUS_PER_INCH = 914400;
@@ -19,8 +19,8 @@ const array = value => value === undefined ? [] : Array.isArray(value) ? value :
 // Whitespace-only text between elements is not identity: the vendored writer indents, PowerPoint drops it on save.
 const canonical = value => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
   ? Object.fromEntries(Object.keys(item).sort().filter(key => !(key === '#text' && typeof item[key] === 'string' && !item[key].trim())).map(key => [key, item[key]])) : item);
-// The OPF paths core reports for a logo source.
-const LOGO_PATH = /^(?:slides\.\d{1,9}\.design\.logo|design\.logo|organization(?:\.\d{1,9})?\.logo)(?:\.[A-Za-z]{1,16})?$/;
+// The OPF paths core reports for a logo source: the organization's `logo`, then a shape and a tone below it.
+const LOGO_PATH = /^organization(?:\.\d{1,9})?\.logo(?:\.[A-Za-z]{1,16}){0,2}$/;
 
 export const LOGO_TAG = TAG;
 export const logoName = () => 'OPF logo';
@@ -138,10 +138,10 @@ export function importLogoPlaceholders(shapes, relationships, entries, slideInde
 }
 
 /**
- * Consume an unchanged tagged logo picture: it is generated from design.logo (or
- * the organization's logo), never content. Returns the consumed picture indexes
+ * Consume an unchanged tagged logo picture: it is drawn from the organization's
+ * logo, never content. Returns the consumed picture indexes
  * and `fallback`, the picture's own `{path, image}`: the caller uses it for the
- * logo only when the stored document and slide design did not restore one (an
+ * organization's logo only when the stored document did not restore one (an
  * export without provenance, or one that omitted the field), so the logo is never
  * lost. An edited, ambiguous or damaged tagged picture stays an ordinary picture
  * and is reported. readPicture(picture) returns the ordinary imported payload.