@openpresentation/opf-pptx 0.11.9 → 0.12.0

package/dist/index.js

@@ -1,20 +1,27 @@
 import {nativeBodyReader, joinNativeParagraphs} from './body-text-import.js';
+import {autoNumScheme, deriveListNumbering, withDisplayedNumbers} from './numbered-list.js';
 import {isFaceStyleSuffix} from './font-weights.js';
 import {importTableFrames} from './table-import.js';
 import {applyChartFonts, applyPitchFamilies, finalizeFontsUsed, fontPitchFamilies} from './package-fonts.js';
 import {readChartCategoryHeading,writeChartCategoryHeading} from './chart-workbook.js';
 import {CHARTEX_FALLBACK,resolveChartType,chartTypeFromNative,applyChartConstruct,NATIVE_CHART_ELEMENTS} from './chart-types.js';
 import {attachChartexParts,chartFromChartex,CHARTEX_GRAPHIC_DATA_URI} from './chartex.js';
+import {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';
 import {attachCardTags,importCardFrames} from './card-provenance.js';
 import {attachMediaTags,importMediaGroups,mediaCaption,mediaFrameRecord,mediaTextFingerprint} from './media-provenance.js';
+// RR-34: captions and footnote areas as tagged text boxes; citation markers round-trip through the tags and the marker runs.
+import {addCaption, addFootnotes} from './annotation-export.js';
+import {attachAnnotationTags, captionValue, importAnnotations, restoreCitations} from './annotation-provenance.js';
 import {attachHeadingTags,importHeadingGroups} from './heading-provenance.js';
 import {attachPlainTextTags,importPlainTextGroups} from './text-provenance.js';
 import {attachTimelineTags,timelineManifest,importTimelineGroups} from './timeline-provenance.js';
 import {attachQuoteTags,quoteManifest,importQuoteGroups} from './quote-provenance.js';
 import {attachFurnitureTags, furnitureManifest, importFurniture, manifestPartIndex, staticDateFallback} from './furniture-provenance.js';
-import {applyDocumentProvenance, attachDocumentProvenance, documentProvenance, recordContentTopology, restoreDocumentProvenance} from './document-provenance.js';
+import {restoreRunColors} from './run-colors.js';
+import {joinWrappedText} from './content-topology.js';
+import {applyDocumentProvenance, attachDocumentProvenance, documentProvenance, recordContentTopology, restoreDocumentProvenance, joinAuthors, splitAuthors, slideListBreaks, DEFAULT_AUTHOR} 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, writeNativeMasters} from './native-furniture.js';
@@ -27,11 +34,13 @@ import {placeLogos, importLogo, importLogoPlaceholders, logoName, LOGO_TAG} from
 import {nativeBackgroundFill, nativeImageBackgroundFill, nativePatternPreset} from './background.js';
 import {importBackground} from './background-import.js';
 import {themeSlotColors, writeThemeColors, schemeColorValue, schemeBackgroundFill, schemeBackgroundValue, defaultTextSchemeValues, tableTextSchemeValue, solidColorXml, writeMasterBackground, inheritLayoutBackground, readThemeSlotColors, recoverColorScheme, recoverTheme, presentationThemePath} from './theme-colors.js';
-import {languageDiagnostics, observeLanguage, partScriptFonts, planScriptFonts, reconcileLanguage} from './script-fonts.js';
+import {languageDiagnostics, observeLanguage, observedRtl, partScriptFonts, physicalAlignment, planScriptFonts, reconcileLanguage} from './script-fonts.js';
 import { webpToPng, svgToPng, readLocalFile } from '#image-fallback';
 import { prepareSvg, svgDataUriBytes, svgRasterScale, svgBlipRelationship, attachSvgPictures } from './svg-image.js';
 import { rasterMetadata, pictureTransform, normalizeImageOrientation } from './image-geometry.js';
 import { layoutTable, composeSlide, fitText, fitRichText, textWidthMeasurer, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, textColorForFill, chartColorForFill } from "@openpresentation/opf/composition";
+// chartPaletteForFill ships with core RR-29 (opf#270); an older published core still loads and clamps each colour on its own.
+import * as opfComposition from "@openpresentation/opf/composition";
 import { colorContext, resolveColorRefValue, resolveExportColor, resolveVariableColors } from "./color-ref.js";
 import PptxGenJS from "../vendor/pptxgenjs/pptxgen.es.js";
 import { unzipSync, zipSync } from "fflate";
@@ -40,6 +49,11 @@ import {
   catalogs as bundledCatalogs,
   validatePresentation
 } from "@openpresentation/opf";
+// Optional core exports (RR-07 syntax colours, trend marks) are read from the namespace so an older published core still loads.
+
+// Optional core exports are read from the namespace so an older published core still loads;
+// resolveVariables ships with core RR-32.
+import * as opfCore from "@openpresentation/opf";
 
 export {checkPptxTypefaces, inventoryPptxTypefaces, packageFontsUsed, THEME_SCRIPT_SUPPLEMENTS} from './typeface-inventory.js';
 export {DEFAULT_SIGNAL_LIMITS, SIGNALS_VERSION, isMonospaceFamily} from './import-signals.js';
@@ -205,7 +219,7 @@ export async function toPptx(input, options = {}) {
   if (options.provenance !== undefined && !['full', 'references-only', false].includes(options.provenance)) {
     throw new OPFPptxError('invalid-provenance-option', "provenance must be 'full', 'references-only' or false.", {path: 'options.provenance'});
   }
-  const presentation = parseInput(input);
+  const presentation = resolveTemplateInput(parseInput(input), options);
   assertValidBoundary(presentation);
   options = {...options, textMeasurement: chosenFamilyMeasurement(options.textMeasurement), svgRasters: new Map()};
 
@@ -238,9 +252,13 @@ export async function toPptx(input, options = {}) {
   context.nativeFurniture = new Map();
   context.hostDate = options.date;
   context.codeTags = new Map();
+  context.captionTags = new Map();
+  context.footnoteTags = new Map();
   context.metricTags = new Map();
+  context.metricDescriptions = new Map();
   context.chartHeadings = new Map();
   context.chartFonts = new Map();
+  context.chartPalettes = new Map();
   context.chartex = new Map();
   context.imageFormat = options.imageFormat ?? "compatible";
   // Chartex export mode (FF-22b): 'auto' (default) writes native chartex parts for the constructs the native PowerPoint
@@ -327,7 +345,7 @@ export async function fromPptx(input, options = {}) {
   });
   if (observedLanguage.language !== undefined) imported.language = observedLanguage.language;
   if (core.description) imported.description = core.description;
-  if (core.author) imported.author = core.author;
+  if (core.author) imported.author = splitAuthors(core.author);
   const themeDesign = importThemeDesign(entries, presentationRoot, presentationRels);
   const design = {...themeDesign.design, ...(dimensions ? {dimensions} : {})};
   if (Object.keys(design).length) imported.design = design;
@@ -353,7 +371,7 @@ export async function fromPptx(input, options = {}) {
   const mediaRegistry = Object.create(null);
   for (let index = 0; index < slidePaths.length; index += 1) {
     furnitureContexts[index].mediaRegistry = mediaRegistry;
-    imported.slides.push(importSlide(entries, slidePaths[index], index, dimensions, options, furniture.slides[index], furnitureContexts[index]));
+    imported.slides.push(importSlide(entries, slidePaths[index], index, dimensions, {...options, rtlDeck: observedRtl(observedLanguage)}, furniture.slides[index], furnitureContexts[index]));
   }
   // Native sections (PowerPoint's own section list, `Default Section` = none)
   // are reconciled with the footer text and the stored value in restoreDocumentProvenance.
@@ -396,7 +414,11 @@ export async function fromPptx(input, options = {}) {
     report({code: "invalid-document-provenance", path: "", message: `${errorMessage(error)} Ordinary import keeps the values observed in the PPTX.`});
   }
   if (slideProvenance.length !== imported.slides.length) throw new OPFPptxError("invalid-import-opf", "Slide provenance does not match the imported slides.");
+  // RR-34: marker runs become cite/footnote on the runs before them, and the references list is rebuilt
+  // from the stored record and the footnote boxes (an edited note keeps its edited text).
+  restoreCitations(imported, furnitureContexts.map(context => context.annotations?.notes ?? []), report);
   restoreLogoFallback(imported, furnitureContexts);
+  applyRunColors(imported, slideProvenance, restoredGroups, report, options);
   if (imported.design?.theme === undefined) for (const diagnostic of themeDesign.diagnostics) if (diagnostic.code === "theme-unverified") report(diagnostic);
   languageDiagnostics(imported, observedLanguage, options.onDiagnostic && report);
 
@@ -418,6 +440,24 @@ export async function fromPptx(input, options = {}) {
   return {document: imported, signals};
 }
 
+// RR-08: run colours named by a ColorRef (variable, scheme slot, role) come back as that name where the document's own
+// colour resolution still gives the run's colour; see run-colors.js.
+function applyRunColors(imported, slideProvenance, restoredGroups, report, options) {
+  const restoredContent = new Set(restoredGroups.filter(group => group.applied && group.contentPaths).map(group => group.contentPaths.slide));
+  const info = slideProvenance.map((entry, index) => entry.structure === "untagged" ? undefined : {record: entry.record, structure: entry.structure === "match", content: restoredContent.has(index)});
+  const contexts = new Map();
+  const resolve = (slide, name) => {
+    try {
+      const key = slide.design ?? imported.design ?? null;
+      if (!contexts.has(key)) contexts.set(key, resolvePresentationContext(slide.design ? {...imported, design: {...imported.design, ...slide.design}} : imported, options));
+      return resolveColorRefValue(name, colorContext(contexts.get(key)));
+    } catch {
+      return undefined;
+    }
+  };
+  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.
@@ -639,10 +679,32 @@ function importSlide(entries, slidePath, slideIndex, presentationDimensions, opt
       item.text = current.map(paragraph => paragraph.text).join('\n');
     }
   }
-  const content = mergeAdjacentBulletShapes(mergeOpfListShapes(items))
-    .map((item) => ({payload: payloadFromSlideItem(item), bounds: item.visualBounds ?? item.bounds, sources: item.sources ?? []}))
+  const listBreaks = slideListBreaks(entries, slidePath, slideRoot, relationships);
+  const content = mergeAdjacentBulletShapes(mergeOpfListShapes(items, listBreaks, diagnostic => options.onDiagnostic?.({...diagnostic, path: `slides.${slideIndex}`})))
+    .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);
+  // RR-34: a tagged caption re-attaches to the block whose native media shape it names (never by position).
+  const annotations = nativeContext.annotations;
+  if (annotations?.captions.size) {
+    const tree = slideRoot['p:cSld']?.['p:spTree'];
+    const shapeName = node => scalarText(node?.['p:nvSpPr']?.['p:cNvPr']?.name ?? node?.['p:nvPicPr']?.['p:cNvPr']?.name ?? node?.['p:nvGraphicFramePr']?.['p:cNvPr']?.name).trim();
+    const keyByName = new Map();
+    nativeContext.shapes.forEach((shape, index) => keyByName.set(shapeName(shape), `sp:${index}`));
+    nativeContext.pictures.forEach((picture, index) => keyByName.set(shapeName(picture), `pic:${index}`));
+    asArray(tree?.['p:graphicFrame']).forEach((frame, index) => keyByName.set(shapeName(frame), `frame:${index}`));
+    asArray(tree?.['mc:AlternateContent']).forEach((alternate, index) => { for (const node of [...asArray(alternate?.['mc:Choice']), ...asArray(alternate?.['mc:Fallback'])]) if (node?.['p:graphicFrame']) keyByName.set(shapeName(node['p:graphicFrame']), `alt:${index}`); });
+    for (const [mediaName, caption] of annotations.captions) {
+      const key = keyByName.get(mediaName);
+      const entry = key === undefined ? undefined : content.find(item => item.sources.includes(key));
+      if (!entry || !['image', 'chart', 'table', 'video'].includes(inferPayloadKind(entry.payload))) {
+        options.onDiagnostic?.({code: 'caption-detached', path: `slides.${slideIndex}`, message: `The caption of ${caption.path} no longer has its media shape (${mediaName}); its text is imported as an ordinary text block.`});
+        blocks.push({type: 'text', text: caption.value});
+        continue;
+      }
+      entry.payload.caption = captionValue(caption);
+    }
+  }
   if (blocks.length > 0) slide.blocks = blocks;
   // Native bounds of each block in reference px, for content topology matching (document provenance).
   // Which native shapes fed each field and block (import signals); never part of the document.
@@ -664,6 +726,12 @@ function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensi
   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.'});
   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.
+  paragraphs.forEach((list, index) => {
+    const zones = list.reduce((count, paragraph) => count + (paragraph.math?.zones ?? 0), 0);
+    if (zones) options.onDiagnostic?.({code: 'math-equation-flattened', path: `slides.${slideIndex}`, message: `Native shape ${index} holds ${zones} OMML equation${zones === 1 ? '' : 's'} (a14:m); OPF has no equation model, so its fallback text is imported as plain text and the equation layout is not represented.`});
+  });
   // Native shape keys (indexes in nativeTextShapes / nativePictures / frame order) for import signals.
   const shapeKeys = new Map(shapes.map((shape, index) => [shape, `sp:${index}`]));
   const sourcesOf = group => group.flatMap(shape => shapeKeys.has(shape) ? [shapeKeys.get(shape)] : []);
@@ -681,6 +749,9 @@ function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensi
   const plainText=importPlainTextGroups(shapes,paragraphs,relationships,entries,diagnostic=>options.onDiagnostic?.({...diagnostic,path:`slides.${slideIndex}`}));
   const timelines=importTimelineGroups(shapes,paragraphs,relationships,entries,diagnostic=>options.onDiagnostic?.({...diagnostic,path:`slides.${slideIndex}`}));
   const quotes=importQuoteGroups(shapes,paragraphs,relationships,entries,diagnostic=>options.onDiagnostic?.({...diagnostic,path:`slides.${slideIndex}.quote`}));
+  // RR-34: tagged caption and footnote lines are not content; captions re-attach to their media block and notes rebuild cite/footnote.
+  const annotations=importAnnotations({shapes,paragraphs,relationships,entries,slideIndex,readBody,report:diagnostic=>options.onDiagnostic?.(diagnostic)});
+  nativeContext.annotations=annotations;
   for(const group of [...headings.items,...plainText.items]) {
     const item=importShape(group.shapes[0],dimensions,group.paragraphs,true);
     if(item){
@@ -707,6 +778,7 @@ function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensi
       : code.consumed.has(shape) ? 'code' : metric.consumed.has(shape) ? 'metric' : media.consumed.has(shape) ? 'media' : timelines.consumed.has(shape) ? 'timeline' : quotes.consumed.has(shape) ? 'quote' : undefined;
     if (role) roles.set(shapeKeys.get(shape), role);
     if (furniture.text.has(index) || nativeContext.slideImageShapes?.has(index) || nativeContext.logoPlaceholderShapes?.has(index)) continue;
+    if (annotations.consumed.has(shape)) { roles.set(shapeKeys.get(shape), 'annotation'); continue; }
     if (code.consumed.has(shape)||metric.consumed.has(shape)||cards.has(shape)||media.consumed.has(shape)||headings.consumed.has(shape)||plainText.consumed.has(shape)||timelines.consumed.has(shape)||quotes.consumed.has(shape)) continue;
     const ordinaryBody = Object.hasOwn(shape, 'p:txBody') && !shape['p:nvSpPr']?.['p:nvPr']?.['p:custDataLst']?.['p:tags'];
     const item = importShape(shape, dimensions, paragraphs[index], ordinaryBody || furniture.taggedText.has(index) || media.captionShapes.has(shape));
@@ -718,12 +790,14 @@ function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensi
   }
 
   const frames = asArray(tree?.["p:graphicFrame"]);
+  // RR-35: what a chart's axis titles, legend and data labels cannot express in OPF is reported on the chart's path.
+  const chartReport = label => diagnostic => options.onDiagnostic?.({code: 'chart-option-adapted', ...diagnostic, path: `slides.${slideIndex}.${label}.${diagnostic.option}`});
   const tables = frames.some(frame => frame['a:graphic']?.['a:graphicData']?.['a:tbl'])
     ? importTableFrames(slidePath, {
       part: (path, parser) => parseRequiredXml(entries, path, parser), relationships: path => parseRelationships(entries, path), bytes: path => entries[path]
-    }, relationships, (frame, cell, code, message) => options.onDiagnostic?.({code, message, path: `slides.${slideIndex}.tables.${frame}${cell ? '.' + cell : ''}`}), dimensions) : [];
+    }, relationships, (frame, cell, code, message) => options.onDiagnostic?.({code, message, path: `slides.${slideIndex}.tables.${frame}${cell ? '.' + cell : ''}`}), dimensions, {rtlDeck: options.rtlDeck === true}) : [];
   for (const [index, frame] of frames.entries()) {
-    const item = importGraphicFrame(entries, frame, slidePath, relationships, tables[index]);
+    const item = importGraphicFrame(entries, frame, slidePath, relationships, tables[index], chartReport(`charts.${index}`));
     if (item) items.push({...item, sources: [`frame:${index}`]});
   }
   // A chartex chart is an mc:AlternateContent: the choice frame references the cx:chartSpace part; the fallback is a classic chart frame
@@ -731,8 +805,8 @@ function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensi
   for (const [alternateIndex, alternate] of asArray(tree?.["mc:AlternateContent"]).entries()) {
     const choice = asArray(alternate?.["mc:Choice"]).map((node) => node?.["p:graphicFrame"]).find(Boolean);
     const fallback = asArray(alternate?.["mc:Fallback"]).map((node) => node?.["p:graphicFrame"]).find(Boolean);
-    const chosen = choice ? importGraphicFrame(entries, choice, slidePath, relationships) : null;
-    const item = chosen?.payload?.type === "chart" ? chosen : fallback ? importGraphicFrame(entries, fallback, slidePath, relationships) : chosen;
+    const chosen = choice ? importGraphicFrame(entries, choice, slidePath, relationships, undefined, chartReport(`charts.alt${alternateIndex}`)) : null;
+    const item = chosen?.payload?.type === "chart" ? chosen : fallback ? importGraphicFrame(entries, fallback, slidePath, relationships, undefined, chartReport(`charts.alt${alternateIndex}`)) : chosen;
     if (item && item.kind !== "unknown") items.push({...item, sources: [`alt:${alternateIndex}`]});
   }
 
@@ -774,7 +848,7 @@ function importShape(shape, dimensions, paragraphs = readParagraphs(shape["p:txB
   };
 }
 
-function importGraphicFrame(entries, frame, slidePath, relationships, importedTable) {
+function importGraphicFrame(entries, frame, slidePath, relationships, importedTable, report) {
   const bounds = shapeBounds(frame["p:xfrm"]);
   const name = scalarText(frame["p:nvGraphicFramePr"]?.["p:cNvPr"]?.name).trim();
   const graphicData = frame["a:graphic"]?.["a:graphicData"];
@@ -795,8 +869,8 @@ function importGraphicFrame(entries, frame, slidePath, relationships, importedTa
   const chartRelId = graphicData?.["c:chart"]?.["r:id"] ?? chartExRelId;
   if (chartRelId) {
     const chart = chartExRelId
-      ? chartexFromRelationship(entries, relationships, chartExRelId)
-      : chartFromRelationship(entries, slidePath, relationships, chartRelId);
+      ? chartexFromRelationship(entries, relationships, chartExRelId, report)
+      : chartFromRelationship(entries, slidePath, relationships, chartRelId, report);
     return {
       kind: "chart",
       bounds,
@@ -879,11 +953,17 @@ function importPicture(entries, picture, slidePath, relationships, report) {
 }
 
 function readParagraphs(txBody) {
-  return asArray(txBody?.["a:p"])
+  return withDisplayedNumbers(asArray(txBody?.["a:p"])
     .map((paragraph) => {
+      // FF-45: an a14:m math zone (OMML equation) inside mc:AlternateContent has no OPF model; its mc:Fallback runs are read as
+      // text (or, without them, the equation's m:t text), and `math` records the zones so the importer can diagnose the loss.
+      const alternates = asArray(paragraph?.["mc:AlternateContent"]);
+      const zones = alternates.flatMap(alternate => asArray(alternate?.["mc:Choice"])).filter(choice => choice?.["a14:m"] !== undefined);
+      const fallbackRuns = alternates.flatMap(alternate => asArray(alternate?.["mc:Fallback"])).flatMap(fallback => [...asArray(fallback?.["a:r"]), ...asArray(fallback?.["a:fld"])]);
       const runs = [
         ...asArray(paragraph?.["a:r"]),
-        ...asArray(paragraph?.["a:fld"])
+        ...asArray(paragraph?.["a:fld"]),
+        ...fallbackRuns
       ];
       const texts = [];
       const sizes = [];
@@ -893,13 +973,29 @@ function readParagraphs(txBody) {
         const size = Number(run?.["a:rPr"]?.sz);
         if (Number.isFinite(size)) sizes.push(size / 100);
       }
+      const linear = zones.map(choice => keyedMathText(choice["a14:m"])).join("");
+      if (zones.length && !fallbackRuns.some(run => scalarText(run?.["a:t"]))) texts.push(linear);
       return {
         text: texts.join(""),
         bullet: asArray(paragraph?.["a:pPr"]).some(props => props?.["a:buChar"] !== undefined || props?.["a:buBlip"] !== undefined || props?.["a:buAutoNum"] !== undefined),
         level: Number(asArray(paragraph?.["a:pPr"])[0]?.lvl ?? 0),
-        maxFontSize: sizes.length > 0 ? Math.max(...sizes) : 0
+        maxFontSize: sizes.length > 0 ? Math.max(...sizes) : 0,
+        ...(zones.length ? {math: {zones: zones.length, text: linear}} : {}),
+        ...autoNumberOf(asArray(paragraph?.["a:pPr"])[0])
       };
-    });
+    }));
+}
+// RR-33: the native auto-number of a paragraph's properties, when its last bullet element is one.
+function autoNumberOf(properties) {
+  if (properties?.["a:buAutoNum"] === undefined) return {};
+  const attributes = asArray(properties["a:buAutoNum"])[0] ?? {};
+  return {autoNum: {type: attributes.type, startAt: attributes.startAt}};
+}
+/** The m:t text of a keyed OMML tree (an a14:m zone) in document order: the equation's linear reading without its layout. */
+function keyedMathText(node) {
+  if (Array.isArray(node)) return node.map(keyedMathText).join("");
+  if (!node || typeof node !== "object") return "";
+  return Object.entries(node).map(([key, value]) => key === "m:t" ? asArray(value).map(scalarText).join("") : keyedMathText(value)).join("");
 }
 
 function shapePlaceholderType(shape) {
@@ -966,7 +1062,10 @@ function joinRich(a, b) {
   }
   return joined;
 }
-function mergeOpfListShapes(items) {
+// `breaks` (slideListBreaks) 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 = () => {}) {
   const lists = new Map();
   for (const item of items) {
     const match = /^OPF list (.+) line (\d+)$/.exec(item.name ?? '');
@@ -980,17 +1079,23 @@ function mergeOpfListShapes(items) {
     entries.sort((a, b) => a.line - b.line);
     if (!entries[0].item.paragraphs[0].bullet) continue;
     const paragraphs = [];
+    const recorded = breaks?.get(path), applied = new Set();
     let bounds, size = 0;
-    for (const {item} of entries) {
+    for (const {item, line} of entries) {
       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; }
+      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;
-        current.description = current.description === undefined ? text : joinRich(current.description, text);
+        if (current.description === undefined) current.description = text;
+        else { current.description = join(current.description, text); applied.add(line); }
       } else {
         const before = current.text;
-        current.text += paragraph.text;
-        if (current.richText !== undefined || paragraph.richText !== undefined) current.richText = joinRich(current.richText ?? before, paragraph.richText ?? paragraph.text);
+        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);
+        applied.add(line);
       }
       const b = item.visualBounds ?? item.bounds;
       if (b) {
@@ -999,6 +1104,7 @@ function mergeOpfListShapes(items) {
       }
       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.`});
     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 ?? [])});
   }
@@ -1025,17 +1131,23 @@ function mergeAdjacentBulletShapes(items) {
   return result;
 }
 
-function payloadFromSlideItem(item) {
+function payloadFromSlideItem(item, report) {
   if (item.payload) return item.payload;
   if (item.kind === "text") {
     if (item.paragraphs.some(p=>p.bullet)) {
+      // RR-33: native auto-numbers come back as `numbering` and the entry `start` values that restore their numbers.
+      const {numbering, starts, diagnostics} = deriveListNumbering(item.paragraphs);
+      for (const diagnostic of diagnostics) report?.(diagnostic);
       return {
         type: "list",
-        items: item.paragraphs.map((paragraph) => (
-          paragraph.level > 0
-            ? { text: paragraph.richText ?? paragraph.text, level: paragraph.level, ...(paragraph.description !== undefined ? {description: paragraph.description} : {}) }
-            : paragraph.description !== undefined ? { text: paragraph.richText ?? paragraph.text, description: paragraph.description } : (paragraph.richText ?? paragraph.text)
-        ))
+        items: item.paragraphs.map((paragraph, index) => {
+          const start = starts.get(index) === undefined ? {} : {start: starts.get(index)};
+          return paragraph.level > 0
+            ? { text: paragraph.richText ?? paragraph.text, level: paragraph.level, ...(paragraph.description !== undefined ? {description: paragraph.description} : {}), ...start }
+            : paragraph.description !== undefined ? { text: paragraph.richText ?? paragraph.text, description: paragraph.description, ...start }
+            : start.start !== undefined ? { text: paragraph.richText ?? paragraph.text, ...start } : (paragraph.richText ?? paragraph.text);
+        }),
+        ...(numbering !== undefined ? {numbering} : {})
       };
     }
     return { type: "text", text: joinNativeParagraphs(item.paragraphs) };
@@ -1044,7 +1156,7 @@ function payloadFromSlideItem(item) {
   return null;
 }
 
-function chartFromRelationship(entries, slidePath, relationships, relId) {
+function chartFromRelationship(entries, slidePath, relationships, relId, report) {
   const relationship = relationships.get(relId);
   if (!relationship?.path || !entries[relationship.path]) return null;
   const doc = parseRequiredXml(entries, relationship.path);
@@ -1061,7 +1173,13 @@ function chartFromRelationship(entries, slidePath, relationships, relId) {
 
   const budget = { cells: 0 };
   const cachePath = (index, role) => `${relationship.path}#c:ser[${index}]/${role}`;
-  if (chartNode.type === 'scatter') return scatterFromSeries(entries, relationship.path, series, budget, cachePath);
+  // RR-35: axis titles, legend position and data labels read back into the chart's option fields.
+  const withOptions = chart => {
+    const {options, notes} = chartOptionsFromClassic(doc["c:chartSpace"], {chartNode: chartNode.node, target: chartTargetFor(chartNode.type), seriesCount: series.length, circular: chartNode.type === 'pie' || chartNode.type === 'doughnut', scatter: chartNode.type === 'scatter'});
+    for (const note of notes) report?.(note);
+    return chart && Object.keys(options).length ? {...chart, ...options} : chart;
+  };
+  if (chartNode.type === 'scatter') return withOptions(scatterFromSeries(entries, relationship.path, series, budget, cachePath));
   const labels = cachedValues(series[0]?.["c:cat"], cachePath(0, 'c:cat'), budget);
   const names = series.map((entry, index) => firstCachedValue(entry?.["c:tx"], cachePath(index, 'c:tx'), budget) ?? `Series ${index + 1}`);
   const values = series.map((entry, index) => {
@@ -1082,13 +1200,13 @@ function chartFromRelationship(entries, slidePath, relationships, relId) {
     ]);
   }
 
-  return {
+  return withOptions({
     type: chartNode.type,
     data: {
       columns: [readChartCategoryHeading(entries,relationship.path) ?? "Category", ...names],
       rows
     }
-  };
+  });
 }
 
 // Scatter charts share X values (c:xVal) across Y series (c:yVal). OPF keeps
@@ -1114,7 +1232,7 @@ function scatterFromSeries(entries, chartPart, series, budget, cachePath) {
 // A chartex part (cx:chartSpace): the series layoutIds name the kept OPF chart
 // type and the cached dimensions restore the category-major data, under the
 // same bounds as the classic chart cache.
-function chartexFromRelationship(entries, relationships, relId) {
+function chartexFromRelationship(entries, relationships, relId, report) {
   const relationship = relationships.get(relId);
   if (!relationship?.path || !entries[relationship.path]) return null;
   const doc = parseRequiredXml(entries, relationship.path);
@@ -1122,6 +1240,7 @@ function chartexFromRelationship(entries, relationships, relId) {
     heading: readChartCategoryHeading(entries, relationship.path),
     limits: {points: MAX_CHART_CACHE_POINTS, cells: MAX_CHART_CACHE_CELLS},
     path: relationship.path,
+    report,
     invalid: (message, location) => {
       throw new OPFPptxError('invalid-chart-cache', `Invalid chart cache: ${message}. Repair the chart data before importing.`, {path: location ?? relationship.path});
     }
@@ -1306,6 +1425,30 @@ function parseInput(input) {
   throw new OPFPptxError("invalid-input", "OPF input must be a parsed object, JSON string, or Uint8Array.");
 }
 
+// Template variables (core resolveVariables, RR-32): a deck that uses content variables, or a template, is resolved to a
+// concrete deck before export, so the PPTX holds exactly the text, numbers, dates and images the preview shows. A template
+// exports with each unfilled variable's example (reported as variable-example-used); a normal deck with an unfilled
+// required variable is refused. Decks without content variables are returned untouched. The package stores the resolved
+// deck, not the template form, so fromPptx returns the filled deck.
+function resolveTemplateInput(presentation, options) {
+  if (typeof opfCore.resolveVariables !== "function" || !isPlainObject(presentation)) return presentation;
+  const values = options.variables;
+  if (values !== undefined && !isPlainObject(values)) {
+    throw new OPFPptxError("invalid-variables", "The variables option must be an object keyed by variable id.", {path: "options.variables"});
+  }
+  const template = opfCore.isTemplate(presentation);
+  if (!template && !opfCore.hasContentVariables(presentation) && !(values && Object.keys(values).length)) return presentation;
+  const result = opfCore.resolveVariables(presentation, values ?? {}, {examples: template});
+  const errors = result.diagnostics.filter(entry => entry.severity === "error");
+  if (errors.length) {
+    throw new OPFPptxError(errors.some(entry => entry.code === "variable-unfilled") ? "unfilled-variables" : "invalid-variables", errors[0].message, {issues: errors, path: errors[0].path});
+  }
+  for (const entry of result.diagnostics) {
+    if (entry.code === "variable-example-used") options.onDiagnostic?.({code: "variable-example-used", path: entry.path, message: entry.message, id: entry.id});
+  }
+  return result.presentation;
+}
+
 function assertValidBoundary(presentation) {
   const result = validatePresentation(presentation);
   if (!result.valid) {
@@ -1489,7 +1632,7 @@ function configurePresentation(pptx, presentation, context) {
     height: context.dimensions.heightInches
   });
   pptx.layout = context.layoutName;
-  pptx.author = normalizeAuthor(presentation.author) ?? "OpenPresentation";
+  pptx.author = normalizeAuthor(presentation.author) ?? DEFAULT_AUTHOR;
   pptx.company = "OpenPresentation";
   pptx.subject = presentation.description ?? "";
   pptx.title = presentation.name ?? presentation.filename ?? "OPF Presentation";
@@ -1582,30 +1725,42 @@ async function addSlide(pptx, presentation, opfSlide, slideIndex, context, optio
         ...textBoxOptions(region, itemContext, item.text.fontSize * 0.75),
         ...nativeFontOptions(item.textStyle),
         color: item.field === "tag" ? tagColor(itemContext) : itemContext.textColor,
-        align: alignmentFor(item),
+        align: physicalAlignment(alignmentFor(item), item.text.directions?.[0]),
+        ...(item.text.directions?.[0] === 'rtl' ? {rtlMode: true} : {}),
         objectName,
         breakLine: false
       });
     } else if ((item.field === "items" || item.field === "bullets") && item.text?.listEntries) {
-      await addMeasuredList(slide,item.text,itemContext,item.path,item.bulletImage,presentation,slideIndex,options);
+      await addMeasuredList(slide,item.text,itemContext,item.path,item.bulletImage,presentation,slideIndex,options,item.payload?.numbering!==undefined);
     } else if (item.field === "text" && item.text?.richLines) {
-      const alignment=item.text.placement?.alignment??alignmentFor(item)??'left';
+      const logicalAlignment=item.text.placement?.alignment??alignmentFor(item)??'left';
       for(const [index,line] of item.text.richLines.entries()){
         const runs=line.fragments.map(fragment=>{
           const runColor=exportColor(fragment.run.color,itemContext,itemContext.colors.text);
           const color=nativeColor(fragment.run.color,runColor,itemContext,itemContext.textColor);
-          return {text:fragment.text,options:{...nativeFontOptions(fragment.style),fontSize:fragment.fontSize*.75,color,underline:fragment.run.underline?{style:'sng',color}:undefined,strike:fragment.run.strikethrough?'sngStrike':undefined,baseline:fragment.baselineShift?-fragment.baselineShift/fragment.fontSize*2000:undefined,hyperlink:fragment.run.link&&/^(https?:|mailto:)/i.test(fragment.run.link)?{url:fragment.run.link}:undefined}};
+          return {text:fragment.text,options:{...nativeFontOptions(fragment.style),fontSize:(fragment.nominalSize??fragment.fontSize)*.75,color,underline:fragment.run.underline?{style:'sng',color}:undefined,strike:fragment.run.strikethrough?'sngStrike':undefined,baseline:fragment.baselineShift?-fragment.baselineShift/(fragment.nominalSize??fragment.fontSize)*2000:undefined,hyperlink:fragment.run.link&&/^(https?:|mailto:)/i.test(fragment.run.link)?{url:fragment.run.link}:undefined}};
         });
-        const placed=item.text.placement?.lines[index],factor=alignment==='right'?1:alignment==='center'?.5:0;
+        // Logical alignment (RR-05): a right-to-left paragraph starts at the right edge; every wrapped line shares its paragraph's direction.
+        const placed=item.text.placement?.lines[index],alignment=placed?.alignment??physicalAlignment(logicalAlignment,item.text.directions?.[index]),factor=alignment==='right'?1:alignment==='center'?.5:0;
         const area=placed?{...region,x:(placed.x+line.width*factor-item.box.width*factor)/96,y:placed.y/96,h:placed.height/96}:{...region,y:region.y+line.y/96,h:line.height/96};
+        // PptxGenJS reads the paragraph direction from the first run's options, not from the shape options.
+        if(item.text.directions?.[index]==='rtl')for(const run of runs)run.options.rtlMode=true;
         if(runs.length)slide.addText(runs,{...textBoxOptions(area,itemContext,item.text.fontSize*.75),align:alignment,fit:'none',wrap:false,lineSpacingMultiple:1});
       }
     } else if (item.field === "text" && typeof item.value === "string") {
-      slide.addText(item.text.lines.join("\n"), {...textBoxOptions(region, itemContext, item.text.fontSize * 0.75),...nativeFontOptions(item.textStyle),align:alignmentFor(item)});
+      slide.addText(item.text.lines.join("\n"), {...textBoxOptions(region, itemContext, item.text.fontSize * 0.75),...nativeFontOptions(item.textStyle),align:physicalAlignment(alignmentFor(item), item.text.directions?.[0])});
     } else {
-      await addPayload(slide, presentation, item.payload, region, item.path, { ...itemContext, composition: item.composition, contentAlignment: alignmentFor(item) ?? "left" }, options, item.quoteLayout, item.codeLayout,item.metricLayout,item.timelineLayout);
+      // RR-34: a captioned item draws its media in item.box; the caption band follows as tagged text boxes linked to the media shape by name.
+      const mediaNames = item.caption ? new Set([...context.imagePlacements.keys(), ...context.imagePlaceholders.keys(), ...context.chartHeadings.keys(), ...context.tableHeaders.keys()]) : undefined;
+      await addPayload(slide, presentation, item.payload, region, item.path, { ...itemContext, composition: item.composition, contentAlignment: alignmentFor(item) ?? "left", direction: geometry.direction }, options, item.quoteLayout, item.codeLayout,item.metricLayout,item.timelineLayout);
+      if (item.caption) {
+        const mediaName = item.field === 'video' ? `OPF media ${item.path} frame` : [...context.imagePlacements.keys(), ...context.imagePlaceholders.keys(), ...context.chartHeadings.keys(), ...context.tableHeaders.keys()].find(name => !mediaNames.has(name));
+        addCaption(slide, item, mediaName, itemContext, exportHelpers, (code, message) => new OPFPptxError(code, message, {path: item.caption.path}));
+      }
     }
   }
+  // RR-34: the footnote area core reserved above the footer band (rule plus one tagged text box per listed line).
+  addFootnotes(slide, geometry.footnotes, slideIndex, slideContext, exportHelpers, (code, message) => new OPFPptxError(code, message, {path: `slides.${slideIndex}`}));
   // Core composes furniture above all content and opf-render paints it last, so
   // spTree order (PowerPoint's z-order) matches: header/footer parts come after
   // every content item, and an overlapping footer stays visible over content.
@@ -1674,10 +1829,10 @@ async function addPayload(slide, presentation, payload, region, path, context, o
       addTablePayload(slide, payload.table, region, context, options, path);
       break;
     case "code":
-      addCodePayload(slide, payload.code, codeLayout, region, context, path);
+      addCodePayload(slide, payload.code, codeLayout, region, context, path, options);
       break;
     case "metric":
-      addMetricPayload(slide, payload.metric,metricLayout,context,path);
+      addMetricPayload(slide, payload.metric,metricLayout,context,path,options);
       break;
     case "quote":
       addQuotePayload(slide, payload.quote, quoteLayout, context, options, path);
@@ -1717,7 +1872,7 @@ function richLineRuns(line,color,native,context) {
   const fallback=color.replace(/^#/,'');
   return line.fragments.map(fragment=>{
     const runColor=exportColor(fragment.run.color,context,fallback),color=nativeColor(fragment.run.color,runColor,context,native);
-    return {text:fragment.text,options:{...nativeFontOptions(fragment.style),fontSize:fragment.fontSize*.75,color,underline:fragment.run.underline?{style:'sng',color}:undefined,strike:fragment.run.strikethrough?'sngStrike':undefined,baseline:fragment.baselineShift?-fragment.baselineShift/fragment.fontSize*2000:undefined,hyperlink:fragment.run.link&&/^(https?:|mailto:)/i.test(fragment.run.link)?{url:fragment.run.link}:undefined}};
+    return {text:fragment.text,options:{...nativeFontOptions(fragment.style),fontSize:(fragment.nominalSize??fragment.fontSize)*.75,color,underline:fragment.run.underline?{style:'sng',color}:undefined,strike:fragment.run.strikethrough?'sngStrike':undefined,baseline:fragment.baselineShift?-fragment.baselineShift/(fragment.nominalSize??fragment.fontSize)*2000:undefined,hyperlink:fragment.run.link&&/^(https?:|mailto:)/i.test(fragment.run.link)?{url:fragment.run.link}:undefined}};
   });
 }
 // Every native line of a list, marker paragraph or not, is named for the list's
@@ -1729,7 +1884,10 @@ function richLineRuns(line,color,native,context) {
 // PptxGenJS embeds the media and its relationship through one picture per slide (OPF bullet image); packaging removes
 // that picture and points each marker paragraph at the relationship with a:buBlip. An icon that cannot be embedded
 // keeps the character bullets, as the preview does.
-async function addMeasuredList(slide,fit,context,path,bulletImage,presentation,slideIndex,options) {
+async function addMeasuredList(slide,fit,context,path,bulletImage,presentation,slideIndex,options,numbered=false) {
+  // RR-33: a numbered list writes native auto-numbers (a:buAutoNum) at core's marker geometry. Core older than the numbering
+  // release composes bullet markers, so nothing numbered can be written; say so instead of exporting bullets silently.
+  if(numbered&&!fit.listEntries.some(entry=>entry.marker.number))options.onDiagnostic?.({code:'numbering-unsupported-core',path,message:'The installed @openpresentation/opf does not compose numbered lists (numbering), so the list is exported with bullets. Use a core release that supports numbering.'});
   let picture=false;
   if(bulletImage){
     const part=`ppt/slides/slide${slideIndex+1}.xml`;
@@ -1750,16 +1908,22 @@ async function addMeasuredList(slide,fit,context,path,bulletImage,presentation,s
     const addLines=(text,box,color,native,withBullet)=>{
       text.richLines.forEach((line,index)=>{
         const first=withBullet&&index===0,level=Math.min(8,entry.level),inset=first?entry.marker.indent*(level+1):0;
-        const region={x:(box.x-inset)/96,y:(box.y+line.y)/96,w:(box.width+inset)/96,h:line.height/96};
+        // Right to left (RR-05): the bullet column is at the right, so the first line's box extends right to hold it and the paragraph
+        // is rtl with its text aligned to the right; marL/indent are the start-side margin and hanging indent in PowerPoint.
+        const entryRtl=entry.direction==='rtl';
+        const region={x:(entryRtl?box.x:box.x-inset)/96,y:(box.y+line.y)/96,w:(box.width+inset)/96,h:line.height/96};
+        const lineDirection=(text.directions?.[index])??entry.direction;
+        const lineAlign=physicalAlignment('left',lineDirection);
         const objectName=`OPF list ${path} line ${lineNumber++}`;
-        if(first)context.listMarkers.set(objectName,{fontFamily:entry.marker.style.fontFamily,fontSize:entry.marker.fontSize*.75,color:pptxColor(context.textColor),picture});
-        const paragraph=first?{bullet:{characterCode:entry.marker.text.codePointAt(0).toString(16).padStart(4,'0'),indent:entry.marker.indent*.75},indentLevel:level}:{bullet:false};
+        const number=first?entry.marker.number:undefined;
+        if(first)context.listMarkers.set(objectName,{fontFamily:entry.marker.style.fontFamily,fontSize:entry.marker.fontSize*.75,color:pptxColor(context.textColor),picture:number?false:picture});
+        const paragraph=first?{bullet:number?{type:'number',style:autoNumScheme(number.style,number.suffix),startAt:number.value,indent:entry.marker.indent*.75}:{characterCode:entry.marker.text.codePointAt(0).toString(16).padStart(4,'0'),indent:entry.marker.indent*.75},indentLevel:level}:{bullet:false};
         const runs=richLineRuns(line,color,native,context);
         if(!runs.length)runs.push({text:'',options:{}});
         // Keep paragraph intent identical across runs. ZIP normalization below
         // removes the duplicate paragraph-property nodes emitted by PptxGenJS.
-        for(const run of runs)Object.assign(run.options,paragraph);
-        slide.addText(runs,{...textBoxOptions(region,context,text.fontSize*.75),fontFace:nativeFontOptions(entry.marker.style).fontFace,objectName,align:'left',fit:'none',wrap:false,lineSpacingMultiple:1,...paragraph});
+        for(const run of runs)Object.assign(run.options,paragraph,lineDirection==='rtl'?{rtlMode:true}:{});
+        slide.addText(runs,{...textBoxOptions(region,context,text.fontSize*.75),fontFace:nativeFontOptions(entry.marker.style).fontFace,objectName,align:lineAlign,fit:'none',wrap:false,lineSpacingMultiple:1,...paragraph});
       });
     };
     addLines(entry.text,entry.textBox,context.colors.text,context.textColor,true);
@@ -1873,7 +2037,7 @@ async function addLogo(slide, presentation, logo, slideIndex, slideContext, cont
     if (prefix) context.logoPlaceholderTags.set(prefix, {v: 1, role: 'placeholder', slide: `slides.${slideIndex}`, path: logo.path});
     return;
   }
-  context.logos.set(`ppt/slides/slide${slideIndex + 1}.xml`, {slide: `slides.${slideIndex}`, box: region, path: logo.path, variant: logo.variant});
+  context.logos.set(`ppt/slides/slide${slideIndex + 1}.xml`, {slide: `slides.${slideIndex}`, box: region, path: logo.path, variant: logo.variant, anchor: logo.anchor ?? 'left'});
   if (outcome.svg) context.svgPictures.set(`ppt/slides/slide${slideIndex + 1}.xml|${logoName()}`, outcome.svg);
   slide.addImage({...resolved, objectName: logoName(), ...region, altText: assetAlt(logo.source, presentation) ?? 'Logo'});
 }
@@ -1929,9 +2093,14 @@ async function addSlideImage(slide, presentation, image, slideIndex, context, op
 // FF-62: chart text is one size. The preview draws every chart label (axis, legend, data label) at
 // max(14, composition.minFontSize ?? 16) px scaled by the slide's shorter side over 720 px (renderer charts.js, `fontPx`),
 // the readability floor: 12 pt on a 13.33 x 7.5 in slide. The export writes that size, in hundredths of a point (DrawingML `sz`).
+// RR-16: core composes every font size on PowerPoint's 0.01 pt grid (1/75 px), so the preview draws the grid size, not the raw
+// product: the floor rounds up (core `snapFontSizeUp`) and an unfloored request of 14 px rounds down (`snapFontSizeDown`).
+// Math.round differed from the preview by 0.01 pt on slide sizes whose scale is not a whole number (A4, Letter, 16:10).
 function chartTextSize(context) {
   const scale = Math.min(context.dimensions.widthInches, context.dimensions.heightInches) * 96 / 720;
-  return Math.round(Math.max(14, context.composition?.minFontSize ?? 16) * scale * 75);
+  const floor = context.composition?.minFontSize ?? 16;
+  const hundredths = Math.max(14, floor) * scale * 75;
+  return floor >= 14 ? Math.ceil(hundredths - 1e-6) : Math.floor(hundredths + 1e-6);
 }
 
 // Every c:txPr of a generated classic chart carries the chart text size: PptxGenJS writes no size on the legend (PowerPoint's
@@ -1950,6 +2119,9 @@ function addChartPayload(slide, chart, region, context, options = {}, path = "ch
     return;
   }
   for (const {adaptation, message} of chartData.adaptations ?? []) options.onDiagnostic?.({code: "chart-data-adapted", path, message, adaptation});
+  // RR-35: axis titles, legend position and data labels (core resolves them against what the chart type can show).
+  const chartOptions = resolveChartOptionsFor(chart);
+  reportChartOptionDiagnostics(chartOptions, path, options.onDiagnostic);
 
   // Keep the resolved palette surface (including alpha) explicit in native
   // chart/plot areas, so inherited labels are assessed against their own panel.
@@ -1960,19 +2132,27 @@ function addChartPayload(slide, chart, region, context, options = {}, path = "ch
   const objectName = `OPF chart ${context.chartHeadings.size + 1}`;
   const circular = chartData.type === 'pie' || chartData.type === 'doughnut';
   const textSize = chartTextSize(context);
-  context.chartHeadings.set(objectName,{heading:chartData.type === 'scatter' ? undefined : chartData.heading ?? chart.data.columns[0],labelColor,spec:chartData.spec,textSize});
+  context.chartHeadings.set(objectName,{heading:chartData.type === 'scatter' ? undefined : chartData.heading ?? chart.data.columns[0],labelColor,spec:chartData.spec,textSize,
+    options:chartOptions,kind:chartTargetFor(chart.type)?.kind,pointCount:chart.data.rows.length});
   context.chartFonts.set(objectName,{heading:context.fonts.heading,body:context.fonts.body});
-  const palette = CHART_COLORS.map(color=>normalizeHex(chartColorForFill(panelFill,`#${color}`)));
+  const preferredPalette = CHART_COLORS.map(color=>`#${color}`);
+  const palette = (typeof opfComposition.chartPaletteForFill === "function" ? opfComposition.chartPaletteForFill(panelFill, preferredPalette) : preferredPalette.map(color=>chartColorForFill(panelFill,color))).map(color=>normalizeHex(color));
+  context.chartPalettes.set(objectName,palette);
   if (chartData.chartex) {
     // The native chartex part is added when the package is normalized (attachChartexParts); the classic chart below becomes its fallback.
     // PptxGenJS rewrites the series it is given (labels become nested levels), so the chartex part keeps its own copy.
     const series = chartData.series.map((entry) => ({name: entry.name, labels: [...entry.labels], values: [...entry.values]}));
-    context.chartex.set(objectName, {spec: chartData.chartex, series, hasCategories: chartData.hasCategories, fill, labelColor, gridColor: context.colors.border, font: context.fonts.body, palette, textSize});
+    context.chartex.set(objectName, {spec: chartData.chartex, series, hasCategories: chartData.hasCategories, fill, labelColor, gridColor: context.colors.border, font: context.fonts.body, palette, textSize, options: chartOptions});
     if (chartData.chartex.layoutId === 'regionMap') {
       options.onDiagnostic?.({code: "chart-map-geodata", path, message: `The '${stringifyText(chart.type)}' chart is exported as a native PowerPoint map (chartex regionMap) without cached geography (no cx:geoCache; provider data is never fabricated): PowerPoint must fetch the region shapes from its online map service when the deck is opened, and until it does it shows "There was a problem getting the information for your map chart" and draws nothing. The clustered column fallback shows the same values in readers without chartex support.`});
     }
   }
   const percent = chartData.spec.grouping === 'percentStacked';
+  // RR-36: a series has one colour, as the preview draws it (opf-render paints series j with palette colour j; only pie,
+  // doughnut and treemap slices take a colour per category). PptxGenJS writes a c:dPt per point, cycling the palette, for a
+  // bar chart with one series whenever chartColors is a custom array of more than one colour, so PowerPoint drew each
+  // column of a single-series column or bar chart in a different colour. One colour for that series writes no c:dPt.
+  const chartColors = chartData.type === 'bar' && chartData.series.length === 1 ? palette.slice(0, 1) : palette;
   slide.addChart(chartData.type, chartData.series, {
     objectName,
     x: region.x,
@@ -1980,8 +2160,9 @@ function addChartPayload(slide, chart, region, context, options = {}, path = "ch
     w: region.w,
     h: region.h,
     showLegend: circular || chartData.series.length > (chartData.type === 'scatter' ? 2 : 1),
+    ...classicChartOptions(chartOptions, {labelColor, font: context.fonts.body, textSize}),
     showTitle: false,
-    chartColors: palette,
+    chartColors,
     chartArea: {fill:{...fill},roundedCorners:false},
     // Paint alpha once in the chart area, rather than stacking two alpha fills.
     plotArea: {fill:{color:null}},
@@ -2000,6 +2181,9 @@ function addChartPayload(slide, chart, region, context, options = {}, path = "ch
     valGridLine: { color: context.colors.border, transparency: 30, size: 1 },
     barDir: chartData.barDir,
     barGrouping: chartData.barGrouping,
+    // Right to left (RR-05): column, line and area charts reverse their categories (c:catAx orientation maxMin), which also moves the
+    // value axis to the right, as the preview draws them. Bar charts keep their vertical category axis.
+    ...(context.direction === 'rtl' && ((chartData.type === 'bar' && chartData.barDir === 'col') || chartData.type === 'line' || chartData.type === 'area') ? { catAxisOrientation: 'maxMin' } : {}),
     ...(percent ? { valAxisLabelFormatCode: '0%' } : {}),
     ...(chartData.spec.markers === undefined ? {} : { lineDataSymbol: chartData.spec.markers ? 'circle' : 'none' }),
     ...(chartData.spec.radarStyle ? { radarStyle: chartData.spec.radarStyle } : {}),
@@ -2019,7 +2203,8 @@ function addTablePayload(slide, table, region, context, options, path) {
   }
 
   const layout = layoutTable(table, {x:region.x*96,y:region.y*96,width:region.w*96,height:region.h*96}, {
-    scale, minFontSize:context.composition?.minFontSize, fontFamily:context.fonts.body, textMeasurement:options.textMeasurement, path
+    scale, minFontSize:context.composition?.minFontSize, fontFamily:context.fonts.body, textMeasurement:options.textMeasurement, path,
+    ...(context.direction === 'rtl' ? {direction: 'rtl'} : {})
   });
   const columnCount = layout.columnCount;
   const rows = layout.rows.map(row => row.cells.map(cell => {
@@ -2068,7 +2253,7 @@ function addTablePayload(slide, table, region, context, options, path) {
         ...(rich ? {bold:false,italic:false} : {}),
         lineSpacing: fit.lineHeight * 0.75,
         paraSpaceAfter: 0,
-        align: cellStyle.align ?? context.contentAlignment,
+        align: physicalAlignment(cellStyle.align ?? context.contentAlignment, cell.direction),
         valign: cellStyle.verticalAlign ?? 'top',
         ...(cell.colSpan > 1 ? {colspan:cell.colSpan} : {}),
         ...(cell.rowSpan > 1 ? {rowspan:cell.rowSpan} : {}),
@@ -2127,7 +2312,8 @@ function addMeasuredPayloadText(slide, text, box, context, options, config) {
     const link = config.links?.[sourceLineIndex];
     if (fit.sourceLines?.[index]?.boundary === 'hard') sourceLineIndex += 1;
     if (!line&&!config.heading&&!config.sourceText&&!config.timeline&&!config.quote&&!config.keepEmpty) continue;
-    const alignment=fit.placement?.alignment??config.align??context.contentAlignment??'left',placed=fit.placement?.lines[index],factor=alignment==='right'?1:alignment==='center'?.5:0;
+    // Logical alignment (RR-05): a right-to-left line starts at the right edge; furniture and metrics pass physical alignments and report no line directions.
+    const placed=fit.placement?.lines[index],alignment=placed?.alignment??physicalAlignment(fit.placement?.alignment??config.align??context.contentAlignment??'left',fit.directions?.[index]),factor=alignment==='right'?1:alignment==='center'?.5:0;
     const sourceLine=fit.sourceLines?.[index],boundary=sourceLine?{boundary:sourceLine.boundary,separator:String(text).slice(sourceLine.end,sourceLine.nextStart)}:{};
     const objectName=config.heading?`OPF heading ${config.path} line ${index}`:config.timeline?`OPF timeline ${config.timeline.group} part ${config.timeline.part} line ${index}`:config.quote?`OPF quote ${config.quote.group} part ${config.quote.part} line ${index}`:config.sourceText?`OPF text ${config.path} line ${index}`:config.objectName?`${config.objectName} line ${index}`:undefined;
     if(config.heading)context.headingTags.set(objectName,{v:1,group:config.path,field:config.heading,line:index,count:fit.lines.length,...boundary});
@@ -2146,6 +2332,7 @@ function addMeasuredPayloadText(slide, text, box, context, options, config) {
       ...textBoxOptions(area, context, fit.fontSize * .75),
       ...nativeFontOptions(style),
       color: lineColor, align: alignment,
+      ...(fit.directions?.[index]==='rtl'?{rtlMode:true}:{}),
       // Reuse the frame's existing relationship to cover blank caption boxes.
       // PptxGenJS also inherits it into runs; keep their native text styling.
       hyperlink: config.hyperlink,
@@ -2214,7 +2401,7 @@ async function addFurniture(slide,presentation,source,layout,context,options,sli
 
 const bulletImageName = () => 'OPF bullet image';
 
-function addCodePayload(slide, value, layout, region, context, path) {
+function addCodePayload(slide, value, layout, region, context, path, options) {
   if (!layout) throw new OPFPptxError('missing-code-layout', 'Code export requires a coordinated core build with shared code geometry.', {path});
   for (const part of layout.parts) {
     // XML 1.0 Char excludes controls and unpaired UTF-16 surrogates. The u flag
@@ -2225,6 +2412,7 @@ function addCodePayload(slide, value, layout, region, context, path) {
   const group = String(context.codeTags.size + 1), panelName = `OPF code ${group} panel`;
   for (const part of layout.parts) if (!part.fit) throw new OPFPptxError('layout-overflow', 'Code content has no usable internal space; increase its cell size before exporting.', {path:part.path,issues:layout.diagnostics});
   context.codeTags.set(panelName,codeManifest(value,layout,group));
+  const syntax = codeSyntax(value, layout, context, path, options);
   slide.addShape('rect', {...region, fill: {color: '111827'}, line: {color: '334155', width: .75}, objectName:panelName});
   for (const [partIndex,part] of layout.parts.entries()) {
     if (!part.fit) throw new OPFPptxError('layout-overflow', 'Code content has no usable internal space; increase its cell size before exporting.', {path:part.path,issues:layout.diagnostics});
@@ -2232,19 +2420,37 @@ function addCodePayload(slide, value, layout, region, context, path) {
       const tabStops=line.segments.filter(segment=>segment.kind==='tab').map(segment=>({position:(segment.x+segment.width)/96,alignment:'l'}));
       const objectName = `OPF code ${group} ${part.role} line ${index+1}`;
       context.codeTags.set(objectName,{v:1,group,role:'line',part:partIndex,line:index});
-      slide.addText(part.text.slice(line.start,line.end),{
+      // RR-07: the same token ranges and palette the preview paints; the text of the runs is the line text, unchanged.
+      const runs = syntax && part.role==='body' ? opfCore.codeLineRuns(syntax.tokens,line.start,line.end,part.text) : undefined;
+      const lineText = part.text.slice(line.start,line.end);
+      const lineOptions = {
         ...textBoxOptions({x:part.box.x/96,y:(part.box.y+index*part.fit.lineHeight)/96,w:part.box.width/96,h:part.fit.lineHeight/96},context,part.fit.fontSize*.75),
         ...nativeFontOptions(part.style),
         color:part.role==='body'?'E5E7EB':'93C5FD',align:'left',fit:'none',wrap:false,lineSpacingMultiple:1,
         tabStops:tabStops.length?tabStops:undefined,objectName,
-      });
+      };
+      // A run's own options replace the line's, so every run repeats the font, size, alignment and tab stops and differs only in colour.
+      slide.addText(runs?.some(run=>run.kind) ? runs.map(run=>({text:part.text.slice(run.start,run.end),options:{...lineOptions,color:syntax.palette[run.kind??'plain'].slice(1)}})) : lineText,lineOptions);
     }
   }
 }
 
-function addMetricPayload(slide,value,layout,context,path) {
+// Token ranges and palette for the code body, from core (the preview calls the same functions); undefined for plain code.
+function codeSyntax(value, layout, context, path, options) {
+  const body = layout.parts.find(part => part.role === 'body');
+  const language = typeof value?.language === 'string' ? value.language : layout.parts.find(part => part.role === 'language')?.text;
+  if (!body || !language) return undefined;
+  if (typeof opfCore.tokenizeCode !== 'function') return undefined;
+  const tokens = opfCore.tokenizeCode(body.text, language);
+  return tokens.length ? {tokens, palette: opfCore.codeSyntaxPaletteForScheme(context.colorScheme)} : undefined;
+}
+
+function addMetricPayload(slide,value,layout,context,path,options) {
   if (!layout) throw new OPFPptxError('missing-metric-layout','Metric export requires coordinated core metric geometry.',{path});
   const group=String(context.metricTags.size+1),manifest=metricManifest(value,layout,group);
+  // RR-07: a trend colours the trend and delta text and adds one native arrow shape, from core's accepted geometry.
+  const trendMark=typeof opfCore.metricTrendMark==='function'?opfCore.metricTrendMark(layout,{background:`#${normalizeHex(context.colors.background)}`}):undefined;
+  const partColor=part=>trendMark&&(part.role==='trend'||part.role==='delta')?trendMark.color.slice(1):part.role==='value'?context.colors.accent:context.textColor;
   for (const [partIndex,part] of layout.parts.entries()) {
     const invalid=/[\u0000-\u0008\u000B\u000C\u000E-\u001F\uD800-\uDFFF\uFFFE\uFFFF]/u.exec(part.text);
     if (invalid) throw new OPFPptxError('invalid-metric-text',`Metric text contains U+${invalid[0].codePointAt(0).toString(16).toUpperCase().padStart(4,'0')} at UTF-16 offset ${invalid.index}, which XML cannot represent; edit that character before exporting.`,{path:part.path});
@@ -2262,11 +2468,17 @@ function addMetricPayload(slide,value,layout,context,path) {
       slide.addText(part.text.slice(line.start,line.end),{
         ...textBoxOptions({x:(anchor-part.box.width*factor)/96,y:(origin.baseline-part.fit.fontSize)/96,w:part.box.width/96,h:part.fit.lineHeight/96},context,part.fit.fontSize*.75),
         ...nativeFontOptions(part.style),
-        color:part.role==='value'?context.colors.accent:context.textColor,align:layout.alignment,fit:'none',wrap:false,lineSpacingMultiple:1,
+        color:partColor(part),align:layout.alignment,...(part.fit.directions?.[index]==='rtl'?{rtlMode:true}:{}),fit:'none',wrap:false,lineSpacingMultiple:1,
         tabStops:tabStops.length?tabStops:undefined,objectName,
       });
     }
   }
+  if(trendMark) {
+    const objectName=`OPF metric ${group} trend mark`;
+    context.metricTags.set(objectName,{v:1,group,role:'mark'});
+    context.metricDescriptions.set(objectName,trendMark.ariaLabel);
+    slide.addShape(trendMark.shape,{objectName,x:trendMark.box.x/96,y:trendMark.box.y/96,w:trendMark.box.width/96,h:trendMark.box.height/96,fill:{color:trendMark.color.slice(1)},line:{transparency:100},altText:trendMark.ariaLabel});
+  }
 }
 
 function addQuotePayload(slide, value, layout, context, options, path) {
@@ -2492,6 +2704,9 @@ function textBoxOptions(region, context, fontSize) {
   };
 }
 
+// The private text helpers annotation-export.js writes captions and footnote lines with (RR-34).
+const exportHelpers = {textBoxOptions, nativeFontOptions, exportColor, nativeColor};
+
 function textRuns(value, context, fallbackFontSize) {
   const runs = Array.isArray(value) ? value : [value];
   return runs.map((run) => {
@@ -2978,13 +3193,14 @@ async function normalizePptxZip(raw, context) {
   }
 
   attachCodeTags(entries, context.codeTags);
-  attachMetricTags(entries,context.metricTags);
+  attachMetricTags(entries,context.metricTags,context.metricDescriptions);
   attachCardTags(entries,context.cardTags);
   attachMediaTags(entries,context.mediaTags);
   attachHeadingTags(entries,context.headingTags);
   attachPlainTextTags(entries,context.plainTextTags);
   attachTimelineTags(entries,context.timelineTags);
   attachQuoteTags(entries,context.quoteTags);
+  attachAnnotationTags(entries,context);
   attachFurnitureFields(entries,context.furnitureFields);
   attachFurnitureTags(entries,context.furnitureTags,context.furnitureManifests,context.furnitureLogoTags);
   // RR-11: the recorded footer shapes become PowerPoint's date, footer and slide-number placeholders.
@@ -3006,6 +3222,9 @@ async function normalizePptxZip(raw, context) {
       // Normalize only our generated chart text styles; point/series fills stay intact.
       entries[chartPart]=encodeText(decodeText(entries[chartPart]).replace(/<c:txPr>[\s\S]*?<\/c:txPr>/g,properties=>properties.replace(/<a:solidFill>[\s\S]*?<\/a:solidFill>/g,()=>`<a:solidFill><a:srgbClr val="${labelColor}"/></a:solidFill>`)));
       entries[chartPart]=encodeText(applyChartTextSize(decodeText(entries[chartPart]),textSize));
+      // RR-35: data labels last, so their own text colours (contrast inside a mark) are not normalized away.
+      const {options:chartOptions,kind:optionKind,pointCount}=context.chartHeadings.get(name);
+      if(chartOptions?.dataLabels)entries[chartPart]=encodeText(applyDataLabels(decodeText(entries[chartPart]),{resolved:chartOptions,kind:optionKind,palette:context.chartPalettes.get(name),labelColor,font:context.chartFonts.get(name)?.body??'Arial',textSize,pointCount}));
     }
   }
   applyChartFonts(entries,context.chartFonts,parseRelationships);
@@ -3302,6 +3521,9 @@ function normalizePartBytes(path, bytes, context, renameMaps, entries, imageMeta
         if(!marker)return shape;
         if(marker.picture&&bulletRelationship)return shape.replace(/<a:buChar\b[^>]*\/>/g,`<a:buBlip><a:blip r:embed="${bulletRelationship}"/></a:buBlip>`);
         const family=marker.fontFamily.replace(/[&<>"']/g,char=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&apos;'}[char]));
+        // RR-33: an auto-number takes the measured size, colour and family like a character bullet, and startAt only when it is not 1.
+        const autoNumber=/<a:buSzPct val="100000"\/><a:buFont typeface="\+mj-lt"\/><a:buAutoNum type="([A-Za-z]+)" startAt="(\d+)"\/>/;
+        if(autoNumber.test(shape))return shape.replace(autoNumber,(_,type,startAt)=>`<a:buClr>${solidColorXml(marker.color)}</a:buClr><a:buSzPts val="${Math.round(marker.fontSize*100)}"/><a:buFont typeface="${family}"/><a:buAutoNum type="${type}"${startAt==='1'?'':` startAt="${startAt}"`}/>`);
         return shape.replace(/<a:buSzPct val="100000"\/>/g,`<a:buClr>${solidColorXml(marker.color)}</a:buClr><a:buSzPts val="${Math.round(marker.fontSize*100)}"/><a:buFont typeface="${family}"/>`);
       });
       // PptxGenJS gives shapes no alternative text. An unavailable image's panel
@@ -3533,7 +3755,7 @@ function numericValue(value) {
 
 function normalizeAuthor(author) {
   if (typeof author === "string") return author;
-  if (Array.isArray(author)) return author.join("; ");
+  if (Array.isArray(author)) return joinAuthors(author);
   return null;
 }