@openpresentation/opf-pptx 0.13.1 → 0.14.0

package/dist/data-provenance.js

@@ -1,7 +1,7 @@
 import {XMLParser} from 'fast-xml-parser';
-import {validatePresentation} from '@openpresentation/opf';
+import {checkFormat, isValidFormat} from './format-check.js';
 import {decodeTextTag, encodeTextTag} from './code-provenance.js';
-import {chartUsesDataFields, isDatasetRef, numberFormatFromExcel, resolveTableData, tableCellDisplayValue, tableUsesDataFields} from './chart-data.js';
+import {chartUsesDataFields, isDatasetRef, fromExcelNumberFormat, resolveTableData, tableCellDisplayValue, tableUsesDataFields} from './chart-data.js';
 
 // RR-54: chart and table data survive a PPTX round trip (core docs/chart-table-data.md).
 //
@@ -13,11 +13,13 @@ import {chartUsesDataFields, isDatasetRef, numberFormatFromExcel, resolveTableDa
 //
 //   OPF_DATASETS_V1  on p:presentation (beside OPF_DOCUMENT_V1): the whole `datasets` map, unused datasets included.
 //   OPF_DATA_V1      on each chart or table graphic frame that uses one of the fields above:
-//     chart  {v: 1, kind: 'chart', data, mapping?, dataset?: hash, evidence: [hash]}   `data` is the authored
+//     chart  {v: 1, kind: 'chart', data, mapping?, highlight?, dataset?: hash, evidence: [hash]}   `data` is the authored
 //            chart.data (a dataset reference, or inline columns with DataColumn objects and `source`); `evidence`
 //            hashes the native caches (series names, categories, values and format codes) of the chart part(s) the frame
 //            shows (the chartex part and its classic fallback); `dataset` hashes the referenced dataset, so a slide
-//            pasted into a deck whose dataset of the same id holds other data keeps its values inline.
+//            pasted into a deck whose dataset of the same id holds other data keeps its values inline. `highlight` (FA-14) is
+//            the authored chart.highlight: the native chart carries only the accent and muted colours it produced, which no
+//            exact inference turns back into series and category names, and a chart with only a highlight records its inline `data`.
 //     table  {v: 1, kind: 'table', table}                                a dataset-backed table, as authored
 //            {v: 1, kind: 'table', headers: [[column, header, text]], cells: [[row, column, value, format, text]]}
 //                                                                         an inline table: the DataColumn or formatted
@@ -79,13 +81,13 @@ const canonicalValue = text => NUMBER.test(text.trim()) && Number.isFinite(Numbe
 // A General format code is left out: on a plain save PowerPoint writes <c:formatCode>General</c:formatCode> into every
 // cache that has none (PptxGenJS writes none on pie and doughnut series), so General and no code are the same evidence.
 const generalCode = code => /^\s*general\s*$/i.test(code);
-// A format code is hashed in core's canonical form (numberFormatFromExcel), because a plain PowerPoint save re-spells codes
+// A format code is hashed in core's canonical form (fromExcelNumberFormat), because a plain PowerPoint save re-spells codes
 // without changing what they show: `$#,##0.0` becomes `\$#,##0.0` and `#,##0 "units"` becomes `#,##0\ "units"` (native
 // check opf#385). Core reads quoted and backslash-escaped literals and literal-safe characters to the same NumberFormat, so
 // both spellings hash equal, while a real change (another number of decimals, another unit) still changes the hash. A code
 // core cannot map is hashed as written; the `opf:` prefix keeps a mapped form apart from a verbatim code of the same text.
 const formatEvidence = code => {
-  const format = numberFormatFromExcel(code);
+  const format = fromExcelNumberFormat(code);
   return typeof format === 'string' ? `format:opf:${format}` : `format:${code}`;
 };
 function hash(text) {
@@ -119,9 +121,9 @@ const datasetHash = (datasets, id) => own(datasets, id) ? hash(canonical(dataset
 
 /** The record of a chart that uses an RR-54 data field, or undefined (the frame then carries no tag). */
 export function chartDataRecord(chart, datasets) {
-  if (!chartUsesDataFields(chart)) return undefined;
+  if (!chartUsesDataFields(chart) && !object(chart?.highlight)) return undefined;
   const dataset = isDatasetRef(chart.data) ? datasetHash(datasets, chart.data.dataset) : undefined;
-  return {v: 1, kind: 'chart', data: clone(chart.data), ...(chart.mapping !== undefined ? {mapping: clone(chart.mapping)} : {}), ...(dataset ? {dataset} : {})};
+  return {v: 1, kind: 'chart', data: clone(chart.data), ...(chart.mapping !== undefined ? {mapping: clone(chart.mapping)} : {}), ...(object(chart.highlight) ? {highlight: clone(chart.highlight)} : {}), ...(dataset ? {dataset} : {})};
 }
 
 /** The record of a table that is dataset-backed or formats numbers, or undefined. `layout` is the exported table layout. */
@@ -281,8 +283,9 @@ export function readDatasetsTag(entries, presentationRoot, relationships, report
     const datasets = readTags(entries, presentationRoot?.['p:custDataLst'], relationships, DATASETS_TAG);
     if (datasets === undefined) return undefined;
     if (!object(datasets) || !Object.keys(datasets).length) throw Error('Invalid datasets record.');
-    const result = validatePresentation({slides: [{title: 'Datasets'}], datasets});
-    if (!result.valid) throw Error(`The stored datasets do not validate (${result.errors[0]?.path ?? ''} ${result.errors[0]?.message ?? ''}).`);
+    const report = checkFormat({slides: [{title: 'Datasets'}], datasets});
+    const [first] = report.findings.filter(finding => finding.severity === 'error');
+    if (!report.valid) throw Error(`The stored datasets do not validate (${first?.path ?? ''} ${first?.message ?? ''}).`);
     return datasets;
   } catch (error) {
     report?.({code: 'invalid-data-provenance', path: 'datasets', message: `${error instanceof Error ? error.message : String(error)} The datasets recorded at export were not restored.`});
@@ -297,6 +300,7 @@ export function readDataTag(entries, frame, relationships) {
   if (!object(record) || record.v !== 1 || !['chart', 'table'].includes(record.kind)) throw Error('Unsupported data provenance version.');
   if (record.kind === 'chart' && (!object(record.data) || !Array.isArray(record.evidence) || !record.evidence.every(item => typeof item === 'string'))) throw Error('Invalid chart data record.');
   if (record.kind === 'chart' && record.dataset !== undefined && typeof record.dataset !== 'string') throw Error('Invalid chart data record.');
+  if (record.kind === 'chart' && record.highlight !== undefined && !object(record.highlight)) throw Error('Invalid chart data record.');
   if (record.kind === 'table' && !(object(record.table) || (Array.isArray(record.headers) && Array.isArray(record.cells)))) throw Error('Invalid table data record.');
   // Inline table entries are [column, header, text] and [row, column, value, format, text]; their indices are array
   // indices (non-negative integers), never a key such as "__proto__" or "length".
@@ -309,7 +313,7 @@ export function readDataTag(entries, frame, relationships) {
   return record;
 }
 
-const validWith = (payload, datasets) => validatePresentation({slides: [{title: 'Data', ...payload}], ...(datasets ? {datasets} : {})}).valid;
+const validWith = (payload, datasets) => isValidFormat({slides: [{title: 'Data', ...payload}], ...(datasets ? {datasets} : {})});
 
 /**
  * The authored chart data while the native caches are unchanged: the imported chart (type and options) with the recorded
@@ -317,7 +321,7 @@ const validWith = (payload, datasets) => validatePresentation({slides: [{title:
  */
 export function restoreChartData(chart, record, evidence, {datasets, report}) {
   if (!record.evidence.includes(evidence)) {
-    report({code: 'chart-data-provenance-changed', message: 'The chart\'s cached data or number formats changed after export (for example in Edit Data), so the dataset reference, column mapping, column formats and data source recorded at export were not restored; the chart imports the values and formats it now shows.'});
+    report({code: 'chart-data-provenance-changed', message: 'The chart\'s cached data or number formats changed after export (for example in Edit Data), so the dataset reference, column mapping, column formats and data source recorded at export were not restored; the chart imports the values and formats it now shows.' + (record.highlight ? ' The chart highlight (series and categories named at export) was not restored either: its names refer to the data as exported.' : '')});
     return chart;
   }
   if (isDatasetRef(record.data) && !own(datasets, record.data.dataset)) {
@@ -328,8 +332,8 @@ export function restoreChartData(chart, record, evidence, {datasets, report}) {
     report({code: 'chart-dataset-unavailable', message: `The chart referenced dataset '${record.data.dataset}', but this package's dataset of that id holds other data than at export (a slide pasted from another deck); the chart imports its values inline.`});
     return chart;
   }
-  const {mapping: _mapping, ...rest} = chart;
-  const restored = {...rest, data: clone(record.data), ...(record.mapping !== undefined ? {mapping: clone(record.mapping)} : {})};
+  const {mapping: _mapping, highlight: _highlight, ...rest} = chart;
+  const restored = {...rest, data: clone(record.data), ...(record.mapping !== undefined ? {mapping: clone(record.mapping)} : {}), ...(record.highlight !== undefined ? {highlight: clone(record.highlight)} : {})};
   if (!validWith({chart: restored}, isDatasetRef(record.data) ? datasets : undefined)) {
     report({code: 'invalid-data-provenance', message: 'The chart data recorded at export does not form a valid chart; the chart imports the values it shows.'});
     return chart;

package/dist/document-provenance.js

@@ -2,8 +2,8 @@ import {XMLParser} from 'fast-xml-parser';
 import {decodeTextTag, encodeTextTag} from './code-provenance.js';
 import {contentTopology, rebuildContent, validateTopology, listLineBreaks, validateListBreaks} from './content-topology.js';
 import {runColorRecord, validateRunColors} from './run-colors.js';
-// Namespace import: cores before FF-34 do not export resolveSocialProfile.
-import * as opfCore from '@openpresentation/opf';
+import {catalogs as bundledCatalogs, validateCatalogRecord} from '@openpresentation/opf';
+import {resolveSocialProfile} from '@openpresentation/opf/composition';
 
 // FF-32: document and slide references survive a PPTX round trip.
 //
@@ -61,11 +61,11 @@ const own = (value, key) => object(value) && Object.hasOwn(value, key) && value[
 // still shows exactly what the stored authored value formats to, keep the
 // authored form (a handle stays a handle); an edited line keeps its new URL.
 function authoredSocials(stored, observed, records) {
-  if (!object(stored) || !object(observed) || typeof opfCore.resolveSocialProfile !== 'function') return observed;
+  if (!object(stored) || !object(observed)) return observed;
   return Object.fromEntries(Object.entries(observed).map(([platform, value]) => {
     const authored = stored[platform];
     if (typeof authored !== 'string') return [platform, value];
-    const profile = opfCore.resolveSocialProfile(platform, authored, records, 'organization');
+    const profile = resolveSocialProfile(platform, authored, records, 'organization');
     const shown = profile.href && !/^[a-z][a-z0-9+.-]*:/i.test(profile.text) ? `https://${profile.text}` : profile.text;
     return [platform, shown === value ? authored : value];
   }));
@@ -370,7 +370,7 @@ const layoutRecords = catalogs => array(Array.isArray(catalogs?.layouts) ? catal
 function validLayoutRecord(value) {
   // Inline catalogs already identify the kind. Supply only an omitted
   // standalone identifier for validation; never change the authored record.
-  try { return object(value) && opfCore.validateCatalogRecord('layouts', {$schema: 'https://openpresentation.org/schema/opf-layout/v1', ...value}).valid; }
+  try { return object(value) && validateCatalogRecord('layouts', {$schema: 'https://openpresentation.org/schema/opf-layout/v1', ...value}).valid; }
   catch { return false; }
 }
 
@@ -872,7 +872,7 @@ export function slideListBreaks(entries, path, root, rels) {
  * `nativeSections` is the package's native section list as one name (or
  * undefined) per slide, or null when the package has no list.
  */
-export function restoreDocumentProvenance(imported, {entries, presentationRoot, presentationRels, slides, organizationConflict = false, socialPlatformRecords, nativeSections = null}, report) {
+export function restoreDocumentProvenance(imported, {entries, presentationRoot, presentationRels, slides, organizationConflict = false, speakerConflict = false, socialPlatformRecords, nativeSections = null}, report) {
   const invalid = message => report({code: 'invalid-document-provenance', path: '', message: `${message} Ordinary import keeps the values observed in the PPTX.`});
   let document;
   try {
@@ -1109,6 +1109,10 @@ export function restoreDocumentProvenance(imported, {entries, presentationRoot,
       report({code: 'metadata-reference-changed', path: 'organization', message: 'Slides now show different organization names in their furniture, so the stored organization was not restored; each slide keeps its visible text.'});
       continue;
     }
+    if (key === 'speaker' && speakerConflict) {
+      report({code: 'metadata-reference-changed', path: 'speaker', message: 'Slides now show different speaker names in their furniture, so the stored speaker was not restored; each slide keeps its visible text.'});
+      continue;
+    }
     if (key === 'author') {
       // Native evidence: the stored authored form only stands for the creator it was joined into.
       if (joinAuthors(imported.author) === joinAuthors(metadata.author)) group('author', [set(['author'], clone(metadata.author))]);
@@ -1120,7 +1124,7 @@ export function restoreDocumentProvenance(imported, {entries, presentationRoot,
     if (key === 'organization' && object(imported.organization)) {
       const observed = imported.organization;
       // Same order as export: inline records, then the document source, host catalogs and bundled records.
-      const hostRecords = typeof socialPlatformRecords === 'function' ? socialPlatformRecords(document.catalogs) : (opfCore.catalogs?.socialPlatforms ?? []);
+      const hostRecords = typeof socialPlatformRecords === 'function' ? socialPlatformRecords(document.catalogs) : bundledCatalogs.socialPlatforms;
       const records = [...array(document.catalogs?.socialPlatforms?.records ?? document.catalogs?.socialPlatforms), ...hostRecords].filter(object);
       const merge = (stored, current) => object(current.socials) && object(stored?.socials) ? {...current, socials: authoredSocials(stored.socials, current.socials, records)} : current;
       const list = array(value);
@@ -1129,6 +1133,14 @@ export function restoreDocumentProvenance(imported, {entries, presentationRoot,
       else if (Array.isArray(value)) value[index] = {...list[index], ...merge(list[index], clone(observed))};
       else value = {...value, ...merge(value, clone(observed))};
     }
+    if (key === 'speaker' && object(imported.speaker)) {
+      // The furniture speaker line (name and title) is native content and wins over the stored speaker with the same id.
+      const observed = imported.speaker, list = array(value), index = list.findIndex(item => object(item) && item.id === observed.id);
+      const merged = stored => { const {title: _title, ...rest} = stored; return {...rest, ...clone(observed)}; };
+      if (index < 0) value = clone(observed);
+      else if (Array.isArray(value)) value[index] = merged(list[index]);
+      else value = merged(value);
+    }
     group(key, [set([key], value)]);
   }
 
@@ -1167,7 +1179,7 @@ export function restoreDocumentProvenance(imported, {entries, presentationRoot,
  * that the imported document references.
  */
 function layoutIntent(documentRecords, hasDocument, slideRecords, entries, group, report, rejectedDocumentIds) {
-  const bundled = id => array(opfCore.catalogs?.layouts).find(item => item?.id === id);
+  const bundled = id => array(bundledCatalogs.layouts).find(item => item?.id === id);
   const owns = slideRecords.map(entry => {
     if (!entry) return null;
     const {record, native: observed} = entry;

package/dist/format-check.js

@@ -0,0 +1,10 @@
+// The one question the provenance and import code asks core: does this value satisfy the OPF format (the schema, and the
+// checks that make a deck structurally usable)? It is core's cheap `format` category: no layout is built, so it is safe on
+// every import and export path.
+import {validate} from '@openpresentation/opf';
+
+/** Core's `format` report for a deck or a fragment (`findings`, `valid`). */
+export const checkFormat = value => validate(value, {only: ['format']});
+
+/** True when the value has no `format` error. */
+export const isValidFormat = value => checkFormat(value).valid;

package/dist/furniture-provenance.js

@@ -15,7 +15,7 @@ const enc = new TextEncoder(), dec = new TextDecoder('utf-8', {fatal: true});
 const parser = new XMLParser({ignoreAttributes: false, attributeNamePrefix: '', parseTagValue: false, trimValues: false});
 const array = value => value === undefined ? [] : Array.isArray(value) ? value : [value];
 const kinds = ['header', 'footer'], zones = ['left', 'center', 'right'];
-const fields = ['text', 'image', 'organization', 'socials', 'section', 'slideNumber', 'date'];
+const fields = ['text', 'image', 'organization', 'speaker', 'socials', 'section', 'slideNumber', 'date'];
 const settings = ['slideNumberFormat', 'dateFormat'];
 const dateFormatForField = Object.fromEntries(Object.entries(NATIVE_DATE_FIELDS).map(([format, type]) => [type, format]));
 // Platform keys follow the Socials schema's propertyNames pattern exactly, so
@@ -97,6 +97,7 @@ export function furnitureManifest(presentation, slide, layout, slideIndex, stati
   if (!Object.keys(definitions).length) return null;
   const organizations = array(presentation.organization);
   const organization = organizations.find(item => item.role === 'primary') ?? organizations[0];
+  const speaker = array(presentation.speaker)[0];
   // Generated deck logos (logo: true) are listed beside the topology, never inside it: the part list and the field
   // definitions are validated strictly by every released importer (0.11.6 and earlier reject an unknown field there),
   // so they keep describing only what those importers know. `drawn` is false when no logo resolved at export.
@@ -109,9 +110,12 @@ export function furnitureManifest(presentation, slide, layout, slideIndex, stati
   }
   return {v: 1, role: 'slide', group: String(slideIndex), definitions, ...(Object.keys(formats).length ? {formats} : {}),
     ...(layout.parts.some(part => part.field === 'organization' || part.field === 'socials') ? {organizationId: organization?.id} : {}),
+    ...(layout.parts.some(part => part.field === 'speaker') ? {speakerId: speaker?.id} : {}),
     parts: layout.parts.flatMap((part, index) => part.field === 'logo' ? [] : [{kind: part.kind, zone: part.zone, field: part.field,
       type: part.type, count: part.type === 'image' ? 1 : part.fit.lines.length,
       ...(part.field === 'socials' ? {socials: socialLines(part)} : {}),
+      // The speaker part is one line, "Name, Title" or "Name": the name's length lets import split it again (lengths, never words).
+      ...(part.field === 'speaker' ? {nameLength: speaker.name.length} : {}),
       ...(staticDates.has(index) ? {staticDate: staticDates.get(index)} : {}),
       // RR-11: this part is a native PowerPoint placeholder (dt, ftr or sldNum); deleting it in PowerPoint's dialog is then intent.
       ...(natives.has(index) ? {ph: natives.get(index)} : {})}]),
@@ -209,8 +213,12 @@ function validateManifest(manifest) {
       && part.socials.every(line => object(line) && platformId.test(line.platform) && schemes.includes(line.scheme))
       && new Set(part.socials.map(line => line.platform)).size === part.socials.length, 'Invalid social profile lines.');
     else check(part.socials === undefined, 'Unexpected social profile lines.');
+    if (part.field === 'speaker') check(Number.isSafeInteger(part.nameLength) && part.nameLength >= 1 && part.nameLength <= 100000, 'Invalid speaker name length.');
+    else check(part.nameLength === undefined, 'Unexpected speaker name length.');
     expected.delete(key(part));
   }
+  if (manifest.parts.some(part => part.field === 'speaker')) check(typeof manifest.speakerId === 'string' && /^[a-zA-Z0-9_-]+$/.test(manifest.speakerId), 'Invalid speaker identity.');
+  else check(manifest.speakerId === undefined, 'Unexpected speaker identity.');
   if (manifest.parts.some(part => part.field === 'organization' || part.field === 'socials')) check(typeof manifest.organizationId === 'string' && /^[a-zA-Z0-9_-]+$/.test(manifest.organizationId), 'Invalid organization identity.');
 }
 
@@ -269,7 +277,7 @@ function readSlide(context, entries, slideIndex, slideCount, report, taggedText)
       if (value !== false) for (const zone of zones) if (definition.value[zone] !== undefined) {
         value[zone] = Object.fromEntries(Object.entries(definition.value[zone]).filter(([, flag]) => flag === false));
       }
-      const candidate = {scope: definition.scope, value, text: [], pictures: [], organizations: [], socials: [], sections: []};
+      const candidate = {scope: definition.scope, value, text: [], pictures: [], organizations: [], speakers: [], socials: [], sections: []};
       // logo: true returns as its flag; the generated picture is consumed, never content or an image field.
       for (const logo of (manifest.logos ?? []).filter(item => item.kind === kind)) {
         const found = logoPictures.filter(item => item.data.v === 1 && item.data.group === manifest.group && item.data.furniture === kind && item.data.zone === logo.zone);
@@ -305,6 +313,7 @@ function readSlide(context, entries, slideIndex, slideCount, report, taggedText)
           }
           if (part.field === 'section') candidate.sections.push(text);
           if (part.field === 'organization') candidate.organizations.push({id: manifest.organizationId, name: text});
+          if (part.field === 'speaker') candidate.speakers.push(importedSpeaker(manifest.speakerId, text, part.nameLength));
           if (part.field === 'socials') {
             const lines = text.split('\n');
             check(lines.length === part.socials.length && lines.every(line => line.trim()), 'Current social profile lines no longer match their platforms.');
@@ -330,6 +339,14 @@ function readSlide(context, entries, slideIndex, slideCount, report, taggedText)
   return candidates;
 }
 
+// The generated speaker line is "Name, Title" (or "Name"). The recorded name length splits it again; a line edited in
+// PowerPoint that no longer has the separator at that position is the visible text as the name, with no title.
+function importedSpeaker(id, text, nameLength) {
+  const rest = text.slice(nameLength);
+  if (text.length > nameLength && rest.startsWith(', ') && rest.length > 2) return {id, name: text.slice(0, nameLength), title: rest.slice(2)};
+  return {id, name: text};
+}
+
 // A current native date field wins. Full-mode static-wrap evidence can recover
 // generated OPF intent without turning the existing PPTX text into a live field. A fixed
 // date keeps its ISO value and pattern only when the current text round-trips.
@@ -368,6 +385,13 @@ export function importFurniture(contexts, entries, onDiagnostic) {
       delete slide[kind]; report(index, `${kind}: Current organization metadata disagrees across repeated fields.`);
     }
   }
+  const speakers = candidates.flatMap(slide => Object.values(slide).flatMap(candidate => candidate.speakers));
+  const speakerConflict = speakers.some(item => !same(item, speakers[0]));
+  if (speakerConflict) {
+    for (const [index, slide] of candidates.entries()) for (const kind of kinds) if (slide[kind]?.speakers.length) {
+      delete slide[kind]; report(index, `${kind}: Current speaker metadata disagrees across repeated fields.`);
+    }
+  }
   for (const [index, slide] of candidates.entries()) {
     const sections = Object.values(slide).flatMap(candidate => candidate.sections);
     if (sections.some(section => section !== sections[0])) for (const kind of kinds) if (slide[kind]?.sections.length) {
@@ -398,7 +422,7 @@ export function importFurniture(contexts, entries, onDiagnostic) {
     }
     if (!accepted.length) return;
     const merged = footerValue(accepted), indexes = accepted.map(item => item.index);
-    if (!existing) slide.footer = {scope: 'native', value: merged, text: indexes, pictures: [], organizations: [], socials: [], sections: []};
+    if (!existing) slide.footer = {scope: 'native', value: merged, text: indexes, pictures: [], organizations: [], speakers: [], socials: [], sections: []};
     else {
       if (existing.value === false) existing.value = {};
       for (const zone of Object.keys(merged)) existing.value[zone] = {...existing.value[zone], ...merged[zone]};
@@ -417,6 +441,9 @@ export function importFurniture(contexts, entries, onDiagnostic) {
   if (result.organization && validSocials.length) result.organization = {...result.organization, socials: validSocials[0].socials};
   // Stored document metadata (FF-32) must not override disagreeing visible names.
   if (organizationConflict) result.organizationConflict = true;
+  const validSpeakers = candidates.flatMap(slide => Object.values(slide).flatMap(candidate => candidate.speakers));
+  if (validSpeakers.length) result.speaker = validSpeakers[0];
+  if (speakerConflict) result.speakerConflict = true;
   for (const kind of kinds) {
     const inherited = candidates.map(slide => slide[kind]).filter(candidate => candidate?.scope === 'global');
     if (inherited.length && candidates.every(slide => slide[kind]) && inherited.every(candidate => same(candidate.value, inherited[0].value))) {

package/dist/heading-provenance.js

@@ -1,6 +1,7 @@
 import {XMLParser} from 'fast-xml-parser';
 import {attachTextTags,decodeTextTag} from './code-provenance.js';
 import {sourceLineParagraphs} from './text-provenance.js';
+import {cleanBase,headingValue,joinRichLines} from './rich-heading.js';
 const TAG='OPF_HEADING_V1',REL='http://schemas.openxmlformats.org/officeDocument/2006/relationships/tags';
 const parser=new XMLParser({ignoreAttributes:false,attributeNamePrefix:'',parseTagValue:false,trimValues:false});
 const decoder=new TextDecoder('utf-8',{fatal:true}),array=value=>value===undefined?[]:Array.isArray(value)?value:[value];
@@ -8,7 +9,8 @@ export const attachHeadingTags=(entries,records)=>attachTextTags(entries,records
 
 // Tags carry only roles and line ordering. Current native text always wins;
 // neither original source text nor old geometry can be restored from these tags.
-export function importHeadingGroups(shapes,paragraphs,relationships,entries,report) {
+// `readBody` (optional) is the native body reader: with it a group also returns `richText`, the heading as string | TextRun[] (FA-10).
+export function importHeadingGroups(shapes,paragraphs,relationships,entries,report,readBody) {
   const groups=new Map(),consumed=new Set(),items=[];
   for(const [index,shape] of shapes.entries()) {
     const tags=[];let unreadable=false;
@@ -37,8 +39,13 @@ export function importHeadingGroups(shapes,paragraphs,relationships,entries,repo
     }
     const restored=sourceLineParagraphs(ordered,paragraphs,{legacy:true});
     for(const item of ordered)consumed.add(item.shape);
-    items.push({field:first.field,shapes:ordered.map(item=>item.shape),paragraphs:restored});
-    report({code:'heading-import-reflow',message:'Complete tagged heading lines retain their roles, order and current native text. New boundary tags also retain authored whitespace and line endings; legacy tags retain native line breaks. Formatting and geometry are not reconstructed.'});
+    // The same boundaries as the plain text: a new tag's separator, or a native line break between legacy-tagged lines.
+    const source=ordered.some(item=>item.data.boundary!==undefined||item.data.separator!==undefined);
+    // Only a rich export records the heading's own look (tag.base); a heading exported as a plain string stays one.
+    const base=cleanBase(ordered[0].data.base);
+    const parts=base?joinRichLines(ordered,readBody,(item,last)=>source?item.data.separator:last?'':'\n'):undefined;
+    items.push({field:first.field,shapes:ordered.map(item=>item.shape),paragraphs:restored,...(parts?{richText:headingValue(parts,base)}:{})});
+    report({code:'heading-import-reflow',message:'Complete tagged heading lines retain their roles, order and current native text. New boundary tags also retain authored whitespace and line endings; legacy tags retain native line breaks. Run formatting that differs between words is read back as TextRun[]; geometry is not reconstructed.'});
   }catch(error){report({code:'invalid-heading-provenance',message:`${error.message} Ordinary import retains visible native text.`});}
   return {consumed,items};
 }

package/dist/image-fallback-node.js

@@ -11,6 +11,9 @@ export async function webpToPng(bytes) {
 // is deterministic (no system fonts, no network or file access for the SVG's own references). `text` selects the
 // bundled fonts; an SVG with no text needs none. Rejects with code `svg-rasterizer-unavailable` when opf-render is
 // not installed.
+//
+// This is the one place the exporter calls the renderer. opf-render's svgToPng(svg, {fonts, scale, background}) takes the
+// fonts handle for the faces it may draw with: here only the bundled ones, never the system's.
 export async function svgToPng(svg, {scale, text}) {
   let render;
   try {
@@ -20,7 +23,7 @@ export async function svgToPng(svg, {scale, text}) {
     unavailable.code = 'svg-rasterizer-unavailable';
     throw unavailable;
   }
-  return new Uint8Array(await render(svg, {scale, background: 'rgba(0, 0, 0, 0)', useBundledFonts: text === true, loadSystemFonts: false}));
+  return new Uint8Array(await render(svg, {fonts: {useBundledFonts: text === true, loadSystemFonts: false}, scale, background: 'rgba(0, 0, 0, 0)'}));
 }
 
 // A local SVG file (a path source), read as bytes; PptxGenJS reads raster paths itself.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { LayoutDiagnostic, TextMeasurement } from "@openpresentation/opf/composition";
+import type { Finding, FontSchemeDiagnostic, Fonts, LayoutDiagnostic, SlideContextReferenceDiagnostic } from "@openpresentation/opf";
 export declare const packageName = "@openpresentation/opf-pptx";
 
 export declare const releaseLane: Readonly<{
@@ -33,10 +33,9 @@ export interface ImageResolverContext {
   path: string;
 }
 
-export interface FontSchemeDiagnostic { code: "unresolved-font-scheme"; path: string; message: string; id: string; fallback: string }
 export interface MediaProvenanceDiagnostic { code: "media-provenance-omitted"; path: string; message: string }
 /** The chart data cannot be plotted, so a placeholder frame stands in for the chart. */
-export interface ChartDataUnplottableDiagnostic { code: "chart-data-unplottable"; path: string; message: string; reason: "data-not-inline" | "dataset-unknown" | "no-rows" | "no-columns" | "single-column-not-numeric" }
+export interface ChartDataUnplottableDiagnostic { code: "chart-data-unplottable"; path: string; message: string; reason: "dataset-unknown" | "no-rows" | "no-columns" | "single-column-not-numeric" }
 /** Content with no PowerPoint export (an empty table, an unsupported payload) is replaced by a plain-language placeholder frame. */
 export interface ContentPlaceholderDiagnostic { code: "content-placeholder"; path: string; message: string; reason: "table-has-no-rows" | "unsupported-payload" }
 /**
@@ -53,7 +52,6 @@ export interface UnresolvedAssetDiagnostic { code: "unresolved-asset"; path: str
 export interface SvgSanitizedDiagnostic { code: "svg-sanitized"; path: string; message: string }
 /** An SVG slide image with a duotone recolor or a non-rectangular shape exports as its PNG raster, not as a native SVG picture, so the effect applies as in the preview (PowerPoint applies opacity, grayscale and a border to an SVG picture, and those stay native). */
 export interface SvgImageRasterizedDiagnostic { code: "svg-image-rasterized"; path: string; message: string }
-export interface WatermarkNotExportedDiagnostic { code: "watermark-not-exported"; path: string; message: string }
 /**
  * The chart data was reshaped to export a native chart: a single value column was plotted against row numbers; a one-series construct
  * (pie, doughnut, and with `chartex: "native"` treemap, histogram, pareto, waterfall, funnel, map) kept only its first series; by default
@@ -70,9 +68,9 @@ export interface ChartMappingAdaptedDiagnostic { code: "chart-mapping-adapted";
 /** RR-54 (`full` provenance): a chart or table data record, or the datasets map (`path: "datasets"`), is over the 16 MiB tag limit and is not stored; the native values still export. */
 export interface DataProvenanceOmittedDiagnostic { code: "data-provenance-omitted"; path: string; message: string }
 
-/** A template variable was unfilled and its `example` was used (template export only). */
+/** A template variable was unfilled and its `example` was used (template export only), or a built-in variable such as `{{speaker.name}}` has no source value in the document (`variable-builtin-missing`; it exports as nothing). */
 export interface VariableExampleUsedDiagnostic {
-  code: "variable-example-used";
+  code: "variable-example-used" | "variable-builtin-missing";
   /** JSON pointer of the variable's declaration. */
   path: string;
   message: string;
@@ -112,11 +110,17 @@ export interface ToPptxOptions {
    * unfilled required variable throws `unfilled-variables`, and a value of the wrong kind throws `invalid-variables`.
    */
   variables?: Record<string, unknown>;
-  textMeasurement?: TextMeasurement;
+  /**
+   * The fonts handle: what the renderer's `loadFonts()` returns (`@openpresentation/opf-render/fonts-node`), or any object with a
+   * `textMeasurement` (core's `Fonts`). The exporter lays text out with `fonts.textMeasurement` and always names the chosen
+   * families, never a substitute face. Without it, layout uses core's portable estimate. This is the only way to pass a measurement:
+   * a top-level `textMeasurement` option is not read.
+   */
+  fonts?: Fonts;
   /** Match preview/pagination clearance around supplied vector text outlines; default 1. */
   textRasterPadding?: number;
-  /** Layout diagnostics, `media-provenance-omitted` when video data cannot be stored, plus `unresolved-font-scheme` (once per reference path) when a font-scheme id matches no record and the default `aptos` scheme is used as the base. */
-  onDiagnostic?: (diagnostic: LayoutDiagnostic | FontSchemeDiagnostic | MediaProvenanceDiagnostic | ChartDataUnplottableDiagnostic | ChartDataAdaptedDiagnostic | ChartMapGeodataDiagnostic | ChartValueNotNumericDiagnostic | ChartMappingAdaptedDiagnostic | DataProvenanceOmittedDiagnostic | ContentPlaceholderDiagnostic | UnresolvedAssetDiagnostic | WatermarkNotExportedDiagnostic | SvgSanitizedDiagnostic | SvgImageRasterizedDiagnostic | VariableExampleUsedDiagnostic) => void;
+  /** Layout diagnostics, `media-provenance-omitted` when video data cannot be stored, plus `unresolved-font-scheme` (once per reference path) when a font-scheme id matches no record and the default `aptos` scheme is used as the base, and, from core's slide context, `unresolved-theme`, `unresolved-color-scheme` and `unresolved-layout` (once per reference path) when an id matches no record: the default theme (`minimal`) and colour scheme (`cool-horizon`) are used, and a slide whose layout is unknown, like one with no layout, is composed with no layout record. None of them refuses the export. */
+  onDiagnostic?: (diagnostic: LayoutDiagnostic | FontSchemeDiagnostic | SlideContextReferenceDiagnostic | MediaProvenanceDiagnostic | ChartDataUnplottableDiagnostic | ChartDataAdaptedDiagnostic | ChartMapGeodataDiagnostic | ChartValueNotNumericDiagnostic | ChartMappingAdaptedDiagnostic | DataProvenanceOmittedDiagnostic | ContentPlaceholderDiagnostic | UnresolvedAssetDiagnostic | SvgSanitizedDiagnostic | SvgImageRasterizedDiagnostic | VariableExampleUsedDiagnostic) => void;
   baseDir?: string;
   compressionLevel?: number;
   imageResolver?: (src: string, context: ImageResolverContext) => ImageResolverResult | Promise<ImageResolverResult | null | undefined> | null | undefined;
@@ -148,7 +152,7 @@ export interface ToPptxOptions {
   date?: string;
   /** Host-supplied catalog records, as in opf-render. Currently consulted for socialPlatforms (generated socials furniture). */
   catalogs?: Record<string, { records?: unknown[] } | unknown[]>;
-  /** Records for document `catalogs.<kind>.source` URLs (a single source or each entry of an ordered search path), as in opf-render. Currently consulted for socialPlatforms. */
+  /** Records for presentation `catalogs.<kind>.source` URLs (a single source or each entry of an ordered search path), as in opf-render. Currently consulted for socialPlatforms. */
   catalogSources?: Record<string, { records?: unknown[] } | unknown[]>;
 }
 
@@ -159,12 +163,12 @@ export interface FromPptxOptions {
   schema?: string;
   /** The export's host catalog records (as in ToPptxOptions). Currently used to recognize unedited socials lines, so authored handles return. */
   catalogs?: Record<string, { records?: unknown[] } | unknown[]>;
-  /** The export's records for document `catalogs.<kind>.source` URLs (as in ToPptxOptions). Currently used for socialPlatforms. */
+  /** The export's records for presentation `catalogs.<kind>.source` URLs (as in ToPptxOptions). Currently used for socialPlatforms. */
   catalogSources?: Record<string, { records?: unknown[] } | unknown[]>;
   /**
    * Opt in to raw per-shape signals (see PptxSignals). `true` uses the default limits; an object lowers or raises them.
-   * With it, `fromPptx` resolves to `{document, signals}`; without it (the default, also `false`/`null`) it resolves
-   * to the OPF document exactly as before. The document is the same either way.
+   * With it, `fromPptx` resolves to `{presentation, signals}`; without it (the default, also `false`/`null`) it resolves
+   * to the presentation alone. The presentation is the same either way.
    */
   signals?: boolean | PptxSignalOptions | null;
 }
@@ -172,7 +176,10 @@ export interface FromPptxOptions {
 export declare class OPFPptxError extends Error {
   readonly code: string;
   readonly details: Record<string, unknown>;
-  readonly issues?: unknown[];
+  /** The `error` findings of the `format` check that refused the input or the imported presentation (`invalid-opf`, `invalid-import-opf`), or the variable errors (`unfilled-variables`, `invalid-variables`). */
+  readonly findings?: Finding[];
+  /** The layout diagnostics behind a `layout-overflow` error. */
+  readonly diagnostics?: LayoutDiagnostic[];
   readonly path?: string;
   constructor(code: string, message: string, details?: Record<string, unknown>);
 }
@@ -195,7 +202,7 @@ export declare function fromPptx(input: Uint8Array | ArrayBuffer, options?: From
 
 /** Bounds on the signals. Each is an integer from 1 up to the cap in parentheses; the defaults are DEFAULT_SIGNAL_LIMITS. */
 export interface PptxSignalOptions {
-  /** Slides reported (5000). The document always has every slide. Default 300. */
+  /** Slides reported (5000). The presentation always has every slide. Default 300. */
   maxSlides?: number;
   /** Shapes reported per slide, groups and their members each counting one (5000). Default 300. */
   maxShapesPerSlide?: number;
@@ -221,8 +228,8 @@ export declare const SIGNALS_VERSION: 1;
 export declare function isMonospaceFamily(family: string | undefined): boolean;
 
 export interface PptxImportWithSignals {
-  /** The same OPF document `fromPptx` returns without the option. */
-  document: Record<string, unknown>;
+  /** The same presentation `fromPptx` returns without the option. */
+  presentation: Record<string, unknown>;
   signals: PptxSignals;
 }
 
@@ -252,7 +259,7 @@ export interface PptxSignals {
 }
 
 export interface PptxSlideSignals {
-  /** Slide position, the same index as `document.slides`. */
+  /** Slide position, the same index as `presentation.slides`. */
   index: number;
   /** Package part, for example "ppt/slides/slide1.xml". */
   part: string;
@@ -379,7 +386,7 @@ export interface PptxOutlineSignal extends PptxColor {
   tailArrow?: string;
 }
 
-/** Where a shape went in the OPF document `fromPptx` returned. */
+/** Where a shape went in the presentation `fromPptx` returned. */
 export interface PptxOpfLink {
   /**
    * "block" fed a block (`path`, `blockType`); "title", "subtitle" and "tag" fed that slide field. Other roles name a shape the
@@ -387,7 +394,7 @@ export interface PptxOpfLink {
    * and the members of an OPF-tagged group ("code", "metric", "quote", "timeline", "media", "card-frame").
    */
   role: string;
-  /** Path in the document, for example "slides.2.blocks.1", "slides.0.title", or "slides.1.left" after a tagged round trip. */
+  /** Path in the presentation, for example "slides.2.blocks.1", "slides.0.title", or "slides.1.left" after a tagged round trip. */
   path?: string;
   blockType?: string;
 }
@@ -462,9 +469,9 @@ export interface TypefaceInventory {
   fontsUsed: string[] | null;
 }
 
-export interface CheckPptxTypefacesOptions {
-  /** Family names the document chose (heading, body, code, run fonts). Required. */
-  fonts: string[];
+export interface CheckTypefacesOptions {
+  /** Family names the presentation chose (heading, body, code, run fonts). Required. */
+  families: string[];
   /** Chosen families that are monospace; their pitchFamily must be fixed pitch, and only theirs. */
   monospace?: string[];
   /** Allow empty theme ea/cs slots and references to them (FF-05). Default true. */
@@ -504,11 +511,11 @@ export interface TypefaceViolation {
 
 export declare const THEME_SCRIPT_SUPPLEMENTS: Readonly<Record<"major" | "minor", Readonly<Record<string, string>>>>;
 
-export declare function inventoryPptxTypefaces(input: Uint8Array | ArrayBuffer | Record<string, Uint8Array>, options?: {nested?: boolean}): TypefaceInventory;
+export declare function inventoryTypefaces(input: Uint8Array | ArrayBuffer | Record<string, Uint8Array>, options?: {nested?: boolean}): TypefaceInventory;
 
 export declare function packageFontsUsed(inventory: TypefaceInventory): string[];
 
-export declare function checkPptxTypefaces(input: Uint8Array | ArrayBuffer | Record<string, Uint8Array>, options: CheckPptxTypefacesOptions): {
+export declare function checkTypefaces(input: Uint8Array | ArrayBuffer | Record<string, Uint8Array>, options: CheckTypefacesOptions): {
   ok: boolean;
   violations: TypefaceViolation[];
   inventory: TypefaceInventory;