@openpresentation/opf-pptx 0.6.0 → 0.8.0

package/dist/index.js

@@ -1,10 +1,17 @@
 import {importTableFrames} from './table-import.js';
+import {readChartCategoryHeading,writeChartCategoryHeading} from './chart-workbook.js';
+import {attachCodeTags, codeManifest, importCodeGroups, nativeShapeParagraphs, nativeTextShapes} from './code-provenance.js';
+import {attachMetricTags,metricManifest,importMetricGroups} from './metric-provenance.js';
+import {attachCardTags,importCardFrames} from './card-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 {importImageOrientation} from './image-import.js';
 import {nativeBackgroundFill} from './background.js';
 import {importBackground} from './background-import.js';
 import { webpToPng } from '#image-fallback';
 import { rasterMetadata, pictureTransform, normalizeImageOrientation } from './image-geometry.js';
-import { layoutTable, composeSlide, fitText, fitRichText, textWidthMeasurer, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle } from "@openpresentation/opf/composition";
+import { layoutTable, composeSlide, fitText, fitRichText, textWidthMeasurer, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, textColorForFill, chartColorForFill } from "@openpresentation/opf/composition";
 import PptxGenJS from "../vendor/pptxgenjs/pptxgen.es.js";
 import { unzipSync, zipSync } from "fflate";
 import { XMLParser } from "fast-xml-parser";
@@ -170,6 +177,13 @@ export async function toPptx(input, options = {}) {
   context.tableCells = new Map();
   context.imagePlacements = new Map();
   context.backgroundFills = new Map();
+  context.cardTags = new Map();
+  context.headingTags = new Map();
+  context.plainTextTags = new Map();
+  context.timelineTags = new Map();
+  context.codeTags = new Map();
+  context.metricTags = new Map();
+  context.chartHeadings = new Map();
   context.imageFormat = options.imageFormat ?? "compatible";
   const pptx = new PptxGenJS();
   configurePresentation(pptx, presentation, {...context,fonts:resolveSlideContext(presentation,presentation.slides[0],context,options).fonts});
@@ -382,10 +396,16 @@ function importSlide(entries, slidePath, slideIndex, presentationDimensions, opt
 
   const items = collectSlideItems(entries, slideRoot, slidePath, relationships, dimensions, options, slideIndex)
     .sort(comparePositionedItems);
-  const titleItem = takeTitleItem(items, dimensions);
-  if (titleItem) slide.title = firstLine(titleItem.text);
-  const subtitleItem = takeSubtitleItem(items, titleItem, dimensions);
-  if (subtitleItem) slide.subtitle = firstLine(subtitleItem.text);
+  // Complete OPF heading roles are authoritative. Nearby body lines must not
+  // fill an absent role by geometry; explicit native placeholders still apply.
+  const inferHeadings = !items.some(item => item.heading||item.sourceText);
+  const heading = field => {const index=items.findIndex(item=>item.heading===field);return index<0?null:items.splice(index,1)[0];};
+  const tagItem=heading('tag');
+  if(tagItem)slide.tag=tagItem.text;
+  const titleItem = heading('title')??takeTitleItem(items, dimensions, inferHeadings);
+  if (titleItem) slide.title = titleItem.text;
+  const subtitleItem = heading('subtitle')??takeSubtitleItem(items, titleItem, dimensions, inferHeadings);
+  if (subtitleItem) slide.subtitle = subtitleItem.text;
 
   const blocks = mergeAdjacentBulletShapes(items)
     .map((item) => payloadFromSlideItem(item))
@@ -401,9 +421,33 @@ function importSlide(entries, slidePath, slideIndex, presentationDimensions, opt
 function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensions, options, slideIndex) {
   const tree = slideRoot["p:cSld"]?.["p:spTree"];
   const items = [];
-
-  for (const shape of asArray(tree?.["p:sp"])) {
-    const item = importShape(shape, dimensions);
+  const shapes = nativeTextShapes(tree);
+  if (tree?.['p:grpSp']) options.onDiagnostic?.({code:'grouped-text-reflow',path:`slides.${slideIndex}`,message:'Grouped native text is retained, but group transforms and non-text group members are not reconstructed; review the reflowed OPF.'});
+  const paragraphs = nativeShapeParagraphs(decodeText(entries[slidePath]));
+  const code = importCodeGroups(shapes, paragraphs, relationships, entries, diagnostic => options.onDiagnostic?.({...diagnostic,path:`slides.${slideIndex}.code`}));
+  const metric = importMetricGroups(shapes, paragraphs, relationships, entries, diagnostic => options.onDiagnostic?.({...diagnostic,path:`slides.${slideIndex}.metric`}));
+  const cards = importCardFrames(shapes, paragraphs, relationships, entries, diagnostic => options.onDiagnostic?.({...diagnostic,path:`slides.${slideIndex}`}));
+  const headings=importHeadingGroups(shapes,paragraphs,relationships,entries,diagnostic=>options.onDiagnostic?.({...diagnostic,path:`slides.${slideIndex}`}));
+  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}`}));
+  for(const group of [...headings.items,...plainText.items]) {
+    const item=importShape(group.shapes[0],dimensions,group.paragraphs,true);
+    if(item){
+      const bounds=group.shapes.map(shape=>shapeBounds(shape['p:spPr']?.['a:xfrm'])).filter(Boolean);
+      if(bounds.length){const x=Math.min(...bounds.map(b=>b.x)),y=Math.min(...bounds.map(b=>b.y));item.bounds={x,y,w:Math.max(...bounds.map(b=>b.x+b.w))-x,h:Math.max(...bounds.map(b=>b.y+b.h))-y};}
+      items.push({...item,heading:group.field,sourceText:!group.field});
+    }
+  }
+  for(const group of timelines.items){
+    const bounds=group.shapes.map(shape=>shapeBounds(shape['p:spPr']?.['a:xfrm'])).filter(Boolean);
+    let union;for(const bound of bounds){if(!union)union={...bound};else{const x=Math.min(union.x,bound.x),y=Math.min(union.y,bound.y);union={x,y,w:Math.max(union.x+union.w,bound.x+bound.w)-x,h:Math.max(union.y+union.h,bound.y+bound.h)-y};}}
+    items.push({kind:'timeline',sourceText:true,bounds:union,payload:group.payload});
+  }
+  for (const item of code.items) items.push({kind:'code',bounds:shapeBounds(item.shape['p:spPr']?.['a:xfrm']),payload:item.payload});
+  for (const item of metric.items) items.push({kind:'metric',bounds:shapeBounds(item.shape['p:spPr']?.['a:xfrm']),payload:item.payload});
+  for (const [index,shape] of shapes.entries()) {
+    if (code.consumed.has(shape)||metric.consumed.has(shape)||cards.has(shape)||headings.consumed.has(shape)||plainText.consumed.has(shape)||timelines.consumed.has(shape)) continue;
+    const item = importShape(shape, dimensions, paragraphs[index]);
     if (item) items.push(item);
   }
 
@@ -426,14 +470,13 @@ function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensi
   return items;
 }
 
-function importShape(shape, dimensions) {
-  const paragraphs = readParagraphs(shape["p:txBody"]);
-  const text = paragraphs.map((paragraph) => paragraph.text).filter(Boolean).join("\n").trim();
+function importShape(shape, dimensions, paragraphs = readParagraphs(shape["p:txBody"]), allowEmptyText = false) {
+  const text = paragraphs.map((paragraph) => paragraph.text).join("\n");
   const placeholder = shapePlaceholderType(shape);
   const bounds = shapeBounds(shape["p:spPr"]?.["a:xfrm"]);
   const name = scalarText(shape["p:nvSpPr"]?.["p:cNvPr"]?.name).trim();
 
-  if (text) {
+  if (text || allowEmptyText) {
     return {
       kind: "text",
       text,
@@ -544,13 +587,12 @@ function readParagraphs(txBody) {
         if (Number.isFinite(size)) sizes.push(size / 100);
       }
       return {
-        text: texts.join("").trim(),
+        text: texts.join(""),
         bullet: asArray(paragraph?.["a:pPr"]).some(props => props?.["a:buChar"] !== undefined || props?.["a:buAutoNum"] !== undefined),
         level: Number(asArray(paragraph?.["a:pPr"])[0]?.lvl ?? 0),
         maxFontSize: sizes.length > 0 ? Math.max(...sizes) : 0
       };
-    })
-    .filter((paragraph) => paragraph.text);
+    });
 }
 
 function shapePlaceholderType(shape) {
@@ -567,13 +609,14 @@ function shapeBounds(xfrm) {
   return { x, y, w, h };
 }
 
-function takeTitleItem(items, dimensions) {
+function takeTitleItem(items, dimensions, inferHeadings) {
   const explicitIndex = items.findIndex((item) => ["title", "ctrTitle"].includes(item.placeholder));
   if (explicitIndex >= 0) return items.splice(explicitIndex, 1)[0];
+  if (!inferHeadings) return null;
 
   const titleLimit = dimensions.heightInches * 0.28;
   const candidateIndex = items.findIndex((item) => {
-    if (item.kind !== "text" || !item.text || item.paragraphs.some(p=>p.bullet)) return false;
+    if (item.heading || item.kind !== "text" || !item.text || item.paragraphs.some(p=>p.bullet)) return false;
     const y = item.bounds?.y ?? 0;
     return y <= titleLimit && (item.maxFontSize >= 20 || /^title\b/i.test(item.name ?? ""));
   });
@@ -581,15 +624,15 @@ function takeTitleItem(items, dimensions) {
   return null;
 }
 
-function takeSubtitleItem(items, titleItem, dimensions) {
+function takeSubtitleItem(items, titleItem, dimensions, inferHeadings) {
   const explicitIndex = items.findIndex((item) => item.placeholder === "subTitle");
   if (explicitIndex >= 0) return items.splice(explicitIndex, 1)[0];
-  if (!titleItem) return null;
+  if (!inferHeadings || !titleItem) return null;
 
   const titleBottom = (titleItem.bounds?.y ?? 0) + (titleItem.bounds?.h ?? 0);
   const subtitleLimit = Math.min(dimensions.heightInches * 0.34, 1.45);
   const candidateIndex = items.findIndex((item) => {
-    if (item.kind !== "text" || !item.text || item.paragraphs.some(p=>p.bullet)) return false;
+    if (item.heading || item.kind !== "text" || !item.text || item.paragraphs.some(p=>p.bullet)) return false;
     const y = item.bounds?.y ?? 0;
     const h = item.bounds?.h ?? 0;
     return y >= titleBottom - 0.05
@@ -624,7 +667,7 @@ function mergeAdjacentBulletShapes(items) {
 function payloadFromSlideItem(item) {
   if (item.payload) return item.payload;
   if (item.kind === "text") {
-    if (item.paragraphs.length > 1 || item.paragraphs.some(p=>p.bullet)) {
+    if (item.paragraphs.some(p=>p.bullet)) {
       return {
         type: "list",
         items: item.paragraphs.map((paragraph) => (
@@ -669,7 +712,7 @@ function chartFromRelationship(entries, slidePath, relationships, relId) {
   return {
     type: chartNode.type,
     data: {
-      columns: ["Category", ...names],
+      columns: [readChartCategoryHeading(entries,relationship.path) ?? "Category", ...names],
       rows
     }
   };
@@ -883,31 +926,47 @@ async function addSlide(pptx, presentation, opfSlide, slideIndex, context, optio
   const { widthInches, heightInches } = slideContext.dimensions;
   const layout = resolveCatalogRecord(presentation, "layouts", opfSlide.layout, "blank") ?? {};
   if (opfSlide.layout && layout.id !== opfSlide.layout) throw new OPFPptxError("catalog-resolution-failed", `Layout '${opfSlide.layout}' needs an inline or bundled catalog record.`, { path: `slides.${slideIndex}.layout` });
-  const geometry = composeSlide(opfSlide, { width: widthInches * 96, height: heightInches * 96, layout, slideIndex, fonts: slideContext.fonts, textMeasurement: options.textMeasurement });
+  const geometry = composeSlide(opfSlide, { width: widthInches * 96, height: heightInches * 96, layout, slideIndex, fonts: slideContext.fonts, contentAlignment:opfSlide.design?.contentAlignment??presentation.design?.contentAlignment, titleAlignment:opfSlide.design?.titleAlignment??presentation.design?.titleAlignment, textRasterPadding:options.textRasterPadding, contentBox:opfSlide.design?.contentBox??presentation.design?.contentBox, textMeasurement: options.textMeasurement });
   for (const diagnostic of geometry.diagnostics) options.onDiagnostic?.(diagnostic);
   for (const item of geometry.items) {
     const region = { x: item.box.x / 96, y: item.box.y / 96, w: item.box.width / 96, h: item.box.height / 96 };
-    if (["title", "subtitle", "tag"].includes(item.field)) {
+    if (item.frameBox) {
+      const frame=item.frameBox;
+      context.cardTags.set(`OPF card ${item.path}`,item.path);
+      const paint=value=>({color:normalizeHex(value),transparency:/^#[0-9a-f]{8}$/i.test(value)?(1-parseInt(value.slice(7),16)/255)*100:0});
+      const surface=slideContext.colorScheme[isDarkHex(slideContext.colors.background)?'dark2':'light2']??`#${slideContext.colors.surface}`;
+      slide.addShape('roundRect',{x:frame.x/96,y:frame.y/96,w:frame.width/96,h:frame.height/96,
+        rectRadius:8*Math.min(widthInches,heightInches)/720,
+        fill:paint(surface),line:{...paint(slideContext.colorScheme.accent5??`#${slideContext.colors.border}`),pt:.75},objectName:`OPF card ${item.path}`});
+    }
+    if(['text','title','subtitle','tag'].includes(item.field)&&(item.text?.placement||item.text?.sourceLines)&&!item.text.richLines) {
+      addMeasuredPayloadText(slide,item.value,item.box,slideContext,options,{path:item.path,fit:item.text,textStyle:item.textStyle,sourceText:item.field==='text'&&!!item.text.sourceLines,diagnosticsHandled:true,heading:['title','subtitle','tag'].includes(item.field)?item.field:undefined,color:item.field==='tag'?slideContext.colors.accent:slideContext.colors.text});
+    } else if (["title", "subtitle", "tag"].includes(item.field)) {
+      // Estimated-font headings use one native text box, which still needs a
+      // role tag. Role recovery must not depend on outline measurement support.
+      const objectName = `OPF heading ${item.path} line 0`;
+      context.headingTags.set(objectName,{v:1,group:item.path,field:item.field,line:0,count:1});
       slide.addText(item.text.lines.join("\n"), {
         ...textBoxOptions(region, slideContext, item.text.fontSize * 0.75),
-        fontFace: item.textStyle.fontFamily,
-        bold: item.textStyle.fontWeight >= 600,
-        italic: item.textStyle.italic,
+        ...nativeFontOptions(item.textStyle),
         color: item.field === "tag" ? slideContext.colors.accent : slideContext.colors.text,
+        objectName,
         breakLine: false
       });
     } else if ((item.field === "items" || item.field === "bullets") && item.text?.listEntries) {
       addMeasuredList(slide,item.text,slideContext);
     } else if (item.field === "text" && item.text?.richLines) {
-      const alignment=opfSlide.design?.contentAlignment??presentation.design?.contentAlignment??'left';
-      for(const line of item.text.richLines){
-        const runs=line.fragments.map(fragment=>({text:fragment.text,options:{fontFace:fragment.style.fontFamily,fontSize:fragment.fontSize*.75,bold:fragment.style.fontWeight>=600,italic:fragment.style.italic,color:normalizeHex(fragment.run.color??slideContext.colors.text),underline:fragment.run.underline?{color:normalizeHex(fragment.run.color??slideContext.colors.text)}: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}}));
-        if(runs.length)slide.addText(runs,{...textBoxOptions({...region,y:region.y+line.y/96,h:line.height/96},slideContext,item.text.fontSize*.75),align:alignment,fit:'none',wrap:false,lineSpacingMultiple:1});
+      const alignment=item.text.placement?.alignment??opfSlide.design?.contentAlignment??presentation.design?.contentAlignment??'left';
+      for(const [index,line] of item.text.richLines.entries()){
+        const runs=line.fragments.map(fragment=>({text:fragment.text,options:{...nativeFontOptions(fragment.style),fontSize:fragment.fontSize*.75,color:normalizeHex(fragment.run.color??slideContext.colors.text),underline:fragment.run.underline?{color:normalizeHex(fragment.run.color??slideContext.colors.text)}: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}}));
+        const placed=item.text.placement?.lines[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};
+        if(runs.length)slide.addText(runs,{...textBoxOptions(area,slideContext,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, slideContext, item.text.fontSize * 0.75),fontFace:item.textStyle.fontFamily,bold:item.textStyle.fontWeight>=600,italic:item.textStyle.italic});
+      slide.addText(item.text.lines.join("\n"), {...textBoxOptions(region, slideContext, item.text.fontSize * 0.75),...nativeFontOptions(item.textStyle)});
     } else {
-      await addPayload(slide, presentation, item.payload, region, item.path, { ...slideContext, composition: item.composition, contentAlignment: opfSlide.design?.contentAlignment ?? presentation.design?.contentAlignment ?? "left" }, options, item.quoteLayout);
+      await addPayload(slide, presentation, item.payload, region, item.path, { ...slideContext, composition: item.composition, contentAlignment: opfSlide.design?.contentAlignment ?? presentation.design?.contentAlignment ?? "left" }, options, item.quoteLayout, item.codeLayout,item.metricLayout,item.timelineLayout);
     }
   }
 
@@ -928,7 +987,7 @@ function fieldToType(field) {
   return field === "items" || field === "bullets" ? "list" : field;
 }
 
-async function addPayload(slide, presentation, payload, region, path, context, options, quoteLayout) {
+async function addPayload(slide, presentation, payload, region, path, context, options, quoteLayout, codeLayout,metricLayout,timelineLayout) {
   const kind = inferPayloadKind(payload);
   switch (kind) {
     case "text":
@@ -950,16 +1009,16 @@ 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, region, context, options, path);
+      addCodePayload(slide, payload.code, codeLayout, region, context, path);
       break;
     case "metric":
-      addMetricPayload(slide, payload.metric, region, context, options, path);
+      addMetricPayload(slide, payload.metric,metricLayout,context,path);
       break;
     case "quote":
       addQuotePayload(slide, quoteLayout, context, options, path);
       break;
     case "timeline":
-      addTimelinePayload(slide, payload.timeline, region, context, options, path);
+      addTimelinePayload(slide, payload.timeline, timelineLayout, context, options, path);
       break;
     default:
       addPlaceholderPayload(slide, "Unsupported OPF payload", payload, region, context);
@@ -989,7 +1048,7 @@ function addTextPayload(slide, value, region, context) {
 }
 
 function richLineRuns(line,color) {
-  return line.fragments.map(fragment=>({text:fragment.text,options:{fontFace:fragment.style.fontFamily,fontSize:fragment.fontSize*.75,bold:fragment.style.fontWeight>=600,italic:fragment.style.italic,color:normalizeHex(fragment.run.color??color),underline:fragment.run.underline?{color:normalizeHex(fragment.run.color??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 line.fragments.map(fragment=>({text:fragment.text,options:{...nativeFontOptions(fragment.style),fontSize:fragment.fontSize*.75,color:normalizeHex(fragment.run.color??color),underline:fragment.run.underline?{color:normalizeHex(fragment.run.color??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}}));
 }
 function addMeasuredList(slide,fit,context) {
   for(const entry of fit.listEntries){
@@ -1005,7 +1064,7 @@ function addMeasuredList(slide,fit,context) {
         // 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:entry.marker.style.fontFamily,objectName,align:'left',fit:'none',wrap:false,lineSpacingMultiple:1,...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});
       });
     };
     addLines(entry.text,entry.textBox,context.colors.text,true);
@@ -1078,21 +1137,36 @@ function addChartPayload(slide, chart, region, context) {
     return;
   }
 
+  // Keep the resolved palette surface (including alpha) explicit in native
+  // chart/plot areas, so inherited labels are assessed against their own panel.
+  const panelFill = context.colorScheme.surface ?? context.colorScheme[isDarkHex(context.colors.background) ? 'dark2' : 'light2'] ?? `#${context.colors.surface}`;
+  const labelColor = normalizeHex(textColorForFill(panelFill, `#${context.colors.text}`));
+  const transparency = /^#[0-9a-f]{8}$/i.test(panelFill) ? (1 - parseInt(panelFill.slice(7), 16) / 255) * 100 : 0;
+  const fill = {color:normalizeHex(panelFill),transparency};
+  const objectName = `OPF chart ${context.chartHeadings.size + 1}`;
+  const circular = chartData.type === 'pie' || chartData.type === 'doughnut';
+  context.chartHeadings.set(objectName,{heading:chartData.type === 'scatter' ? undefined : chart.data.columns[0],labelColor});
   slide.addChart(chartData.type, chartData.series, {
+    objectName,
     x: region.x,
     y: region.y,
     w: region.w,
     h: region.h,
-    showLegend: chartData.series.length > 1,
+    showLegend: circular || chartData.series.length > 1,
     showTitle: false,
-    chartColors: CHART_COLORS,
+    chartColors: CHART_COLORS.map(color=>normalizeHex(chartColorForFill(panelFill,`#${color}`))),
+    chartArea: {fill:{...fill},roundedCorners:false},
+    // Paint alpha once in the chart area, rather than stacking two alpha fills.
+    plotArea: {fill:{color:null}},
     catAxisLabelFontFace: context.fonts.body,
     catAxisLabelFontSize: 9,
-    catAxisLabelColor: context.colors.text,
+    catAxisLabelColor: labelColor,
     valAxisLabelFontFace: context.fonts.body,
     valAxisLabelFontSize: 9,
-    valAxisLabelColor: context.colors.text,
-    legendColor: context.colors.text,
+    valAxisLabelColor: labelColor,
+    legendColor: labelColor,
+    legendFontFace: context.fonts.body,
+    dataLabelColor: labelColor,
     showValue: false,
     valGridLine: { color: context.colors.border, transparency: 30, size: 1 },
     barDir: chartData.barDir,
@@ -1116,8 +1190,8 @@ function addTablePayload(slide, table, region, context, options, path) {
   const rows = layout.rows.map(row => row.cells.map(cell => {
     const {header,rich,fit} = cell;
     const cellStyle = cell.style ?? {};
-    const baseColor = (cellStyle.color ?? (header ? '#FFFFFF' : '#' + context.colors.text)).replace(/^#/, '');
     const baseFill = (cellStyle.fill ?? (header ? '#' + context.colors.accent : '#' + context.colors.surface)).replace(/^#/, '');
+    const baseColor = (cellStyle.color ?? textColorForFill('#' + baseFill, header ? '#FFFFFF' : '#' + context.colors.text)).replace(/^#/, '');
     const alpha = value => value.length === 8 ? (1 - parseInt(value.slice(6), 16) / 255) * 100 : 0;
     const text = stringifyText(cell.value), style = cell.textStyle;
     const fragments = rich ? fit.richLines.flatMap(line => line.fragments) : [];
@@ -1128,8 +1202,7 @@ function addTablePayload(slide, table, region, context, options, path) {
       const rawColor = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(run.color ?? '') ? run.color.slice(1) : baseColor;
       const color = normalizeHex(rawColor), transparency = rawColor.length === 8 ? (1 - parseInt(rawColor.slice(6), 16) / 255) * 100 : 0;
       const runOptions = {
-        fontFace:runStyle.fontFamily,fontSize:fragment ? fragment.fontSize * .75 : fit.fontSize * .75,
-        bold:runStyle.fontWeight >= 600,italic:runStyle.italic,
+        ...nativeFontOptions(runStyle),fontSize:fragment ? fragment.fontSize * .75 : fit.fontSize * .75,
         underline:run.underline ? {color} : undefined,strike:run.strikethrough ? 'sngStrike' : undefined,
         color,transparency,baseline:fragment?.baselineShift ? -fragment.baselineShift / fragment.fontSize * 2000 : undefined,
         hyperlink:run.link && /^(https?:|mailto:)/i.test(run.link) ? {url:run.link} : undefined,
@@ -1145,13 +1218,12 @@ function addTablePayload(slide, table, region, context, options, path) {
       // soft wraps into the text would change a later import or copy operation.
       text: rich ? runs : text,
       options: {
-        fontFace: style.fontFamily,
+        ...nativeFontOptions(style),
         fontSize: fit.fontSize * 0.75,
         // PptxGenJS fills falsy run options from cell defaults. Rich runs
         // carry their resolved weight, so a bold header default must not turn
         // an explicit bold:false run back on.
-        bold: rich ? false : style.fontWeight >= 600,
-        italic: rich ? false : style.italic,
+        ...(rich ? {bold:false,italic:false} : {}),
         lineSpacing: fit.lineHeight * 0.75,
         paraSpaceAfter: 0,
         align: cellStyle.align ?? context.contentAlignment,
@@ -1194,6 +1266,8 @@ function pixelBox(region) {
 // Match the published renderer's payload geometry and shared core text fitting.
 // Each fitted line remains native editable text, without PowerPoint rewrapping it.
 function addMeasuredPayloadText(slide, text, box, context, options, config) {
+  const invalid=/[\u0000-\u0008\u000B\u000C\u000E-\u001F\uD800-\uDFFF\uFFFE\uFFFF]/u.exec(String(text??''));
+  if(invalid)throw new OPFPptxError('invalid-text',`Text contains U+${invalid[0].codePointAt(0).toString(16).toUpperCase().padStart(4,'0')} at UTF-16 offset ${invalid.index}, which DrawingML XML cannot represent.`,{path:config.path});
   const scale = Math.min(context.dimensions.widthInches, context.dimensions.heightInches) * 96 / 720;
   const style = config.textStyle ?? resolveTextStyle({fontFamily: config.fontFamily ?? context.fonts.body, fontWeight: config.fontWeight ?? 400, path: config.path}, options.textMeasurement);
   const fit = config.fit ?? fitText(String(text ?? ''), box, config.fontSize * scale, (context.composition?.minFontSize ?? 16) * scale, textWidthMeasurer(style, options.textMeasurement));
@@ -1203,32 +1277,78 @@ function addMeasuredPayloadText(slide, text, box, context, options, config) {
     if (context.composition?.overflow === 'error') throw new OPFPptxError('layout-overflow', diagnostic.message, {path: config.path, issues: [diagnostic]});
   }
   for (const [index, line] of fit.lines.entries()) {
-    if (!line) continue;
+    if (!line&&!config.heading&&!config.sourceText&&!config.timeline) continue;
+    const alignment=fit.placement?.alignment??config.align??context.contentAlignment??'left',placed=fit.placement?.lines[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.sourceText?`OPF text ${config.path} 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});
+    else if(config.timeline)context.timelineTags.set(objectName,{v:1,role:'text',group:config.timeline.group,part:config.timeline.part,line:index,count:fit.lines.length,...boundary,...(config.timeline.part===0&&index===0?{anchor:config.timeline.anchor}:{})});
+    else if(config.sourceText)context.plainTextTags.set(objectName,{v:1,group:config.path,line:index,count:fit.lines.length,...boundary});
+    const area=placed?{x:(placed.x+placed.width*factor-box.width*factor)/96,y:(placed.baseline-fit.fontSize)/96,w:box.width/96,h:placed.height/96}:{x:box.x/96,y:(box.y+index*fit.lineHeight)/96,w:box.width/96,h:fit.lineHeight/96};
     slide.addText(line, {
-      ...textBoxOptions({x: box.x / 96, y: (box.y + index * fit.lineHeight) / 96, w: box.width / 96, h: fit.lineHeight / 96}, context, fit.fontSize * .75),
-      fontFace: style.fontFamily, bold: style.fontWeight >= 600, italic: style.italic,
-      color: normalizeHex(config.color ?? context.colors.text), align: config.align ?? context.contentAlignment ?? 'left',
+      ...textBoxOptions(area, context, fit.fontSize * .75),
+      ...nativeFontOptions(style),
+      color: normalizeHex(config.color ?? context.colors.text), align: alignment,
+      tabStops:sourceLine?.segments.filter(segment=>segment.kind==='tab').map(segment=>({position:(segment.x+segment.width)/96,alignment:'l'})),
+      objectName,
       fit: 'none', wrap: false, lineSpacingMultiple: 1,
     });
   }
 }
 
-function addCodePayload(slide, value, region, context, options, path) {
-  const box = pixelBox(region), code = typeof value === 'string' ? value : value?.source ?? JSON.stringify(value);
-  const label = typeof value === 'object' && value?.language ? String(value.language) : 'code';
-  slide.addShape('rect', {...region, fill: {color: '111827'}, line: {color: '334155', pt: .75}});
-  // The label has a fixed baseline in the SVG renderer; it does not participate in fitting.
-  slide.addText(label.toUpperCase(), {
-    ...textBoxOptions({x: (box.x + 18) / 96, y: (box.y + 14) / 96, w: Math.max(1, box.width - 36) / 96, h: 20 / 96}, context, 14 * .75),
-    fontFace: context.fonts.code, bold: true, color: '93C5FD', fit: 'none', wrap: false,
-  });
-  addMeasuredPayloadText(slide, code, {x: box.x + 18, y: box.y + 46, width: box.width - 36, height: box.height - 64}, context, options, {path, fontSize: 18, fontFamily: context.fonts.code, color: 'E5E7EB'});
+function addCodePayload(slide, value, layout, region, context, path) {
+  if (!layout) throw new OPFPptxError('missing-code-layout', 'Code export requires a coordinated core build with shared code geometry.', {path});
+  for (const part of layout.parts) {
+    // XML 1.0 Char excludes controls and unpaired UTF-16 surrogates. The u flag
+    // keeps valid supplementary characters (surrogate pairs) accepted.
+    const invalid = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uD800-\uDFFF\uFFFE\uFFFF]/u.exec(part.text);
+    if (invalid) throw new OPFPptxError('invalid-code-text', `Code 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});
+  }
+  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));
+  slide.addShape('rect', {...region, fill: {color: '111827'}, line: {color: '334155', pt: .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});
+    for (const [index,line] of part.fit.sourceLines.entries()) {
+      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),{
+        ...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,
+      });
+    }
+  }
 }
 
-function addMetricPayload(slide, value, region, context, options, path) {
-  const metric = isPlainObject(value) ? value : {value}, box = pixelBox(region);
-  addMeasuredPayloadText(slide, metric.value, {...box, height: box.height * .45}, context, options, {path: path + '.value', fontSize: Math.min(76, box.height * .28), fontFamily: context.fonts.heading, fontWeight: 800, color: context.colors.accent});
-  addMeasuredPayloadText(slide, [metric.label, metric.description, metric.delta].filter(Boolean).join('\n'), {x: box.x, y: box.y + box.height * .45, width: box.width, height: box.height * .55}, context, options, {path, fontSize: 23, fontWeight: 500});
+function addMetricPayload(slide,value,layout,context,path) {
+  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);
+  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});
+    if (!part.visible) continue;
+    if (!part.fit||part.linePositions?.length!==part.fit.sourceLines.length) throw new OPFPptxError('layout-overflow','Metric content has no accepted internal line positions; increase its cell size or coordinate package versions.',{path:part.path,issues:layout.diagnostics});
+    for (const [index,line] of part.fit.sourceLines.entries()) {
+      const origin=part.linePositions[index],objectName=`OPF metric ${group} ${part.role} line ${index+1}`;
+      context.metricTags.set(objectName,partIndex===0&&index===0?manifest:{v:1,group,role:'line',part:partIndex,line:index});
+      const tabStops=line.segments.filter(segment=>segment.kind==='tab').map(segment=>({position:(segment.x+segment.width)/96,alignment:'l'}));
+      // Anchor the native paragraph to the same accepted left/center/right point.
+      // Left-aligning at a measured glyph origin loses the intended edge when the
+      // native shaper has a slightly different advance. No re-fitting is needed.
+      const factor=layout.alignment==='right'?1:layout.alignment==='center'?.5:0;
+      const anchor=origin.x+line.width*factor;
+      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.colors.text,align:layout.alignment,fit:'none',wrap:false,lineSpacingMultiple:1,
+        tabStops:tabStops.length?tabStops:undefined,objectName,
+      });
+    }
+  }
 }
 
 function addQuotePayload(slide, layout, context, options, path) {
@@ -1242,20 +1362,23 @@ function addQuotePayload(slide, layout, context, options, path) {
   }
 }
 
-function addTimelinePayload(slide, value, region, context, options, path) {
-  const timeline = Array.isArray(value) ? {events: value} : value;
-  const events = Array.isArray(timeline?.events) ? timeline.events : [];
-  if (!events.length) return;
-  const box = pixelBox(region), labelWidth = box.width / Math.max(2, events.length);
-  const gap = (box.width - labelWidth) / Math.max(1, events.length - 1);
-  const start = events.length === 1 ? box.x + box.width / 2 : box.x + labelWidth / 2;
-  const end = events.length === 1 ? start : box.x + box.width - labelWidth / 2;
-  const y = box.y + box.height * .46, radius = Math.min(9, labelWidth / 5, box.height * .04);
-  slide.addShape('line', {x: start / 96, y: y / 96, w: (end - start) / 96, h: 0, line: {color: context.colors.border, pt: 3 * .75}});
-  for (const [index, event] of events.entries()) {
-    const x = start + index * gap;
-    slide.addShape('ellipse', {x: (x - radius) / 96, y: (y - radius) / 96, w: radius * 2 / 96, h: radius * 2 / 96, fill: {color: context.colors.accent}, line: {transparency: 100}});
-    addMeasuredPayloadText(slide, [event.when, event.what, event.description].filter(Boolean).join('\n'), {x: x - labelWidth / 2, y: index % 2 === 0 ? box.y : y + 24, width: labelWidth, height: box.height * .38}, context, options, {path: `${path}.events.${index}`, fontSize: 16, fontWeight: 500, align: 'center'});
+function addTimelinePayload(slide, value, layout, context, options, path) {
+  if(!layout)throw new OPFPptxError('missing-timeline-layout','Timeline export requires a coordinated core build with shared timeline geometry.',{path});
+  // Validate optional field fits before the provenance manifest dereferences
+  // source lines or any drawing/tag mutation is performed.
+  for(const part of layout.parts)if(!part.fit)throw new OPFPptxError('layout-overflow','Timeline field has no usable space; change the arrangement or paginate events.',{path:part.path,issues:layout.diagnostics});
+  const scale=Math.min(context.dimensions.widthInches,context.dimensions.heightInches)*96/720;
+  const group=String(context.timelineTags.size),anchor=timelineManifest(value,layout),connectorName=`OPF timeline ${group} connector`;
+  const {x1,y1,x2,y2}=layout.connector;
+  slide.addShape('line',{objectName:connectorName,x:x1/96,y:y1/96,w:(x2-x1)/96,h:(y2-y1)/96,line:{color:context.colors.border,pt:3*scale*.75}});
+  context.timelineTags.set(connectorName,{v:1,group,role:'connector'});
+  for(const marker of layout.markers){
+    const objectName=`OPF timeline ${group} marker ${marker.eventIndex}`;
+    slide.addShape('ellipse',{objectName,x:(marker.x-marker.radius)/96,y:(marker.y-marker.radius)/96,w:marker.radius*2/96,h:marker.radius*2/96,fill:{color:context.colors.accent},line:{transparency:100}});
+    context.timelineTags.set(objectName,{v:1,group,role:'marker',eventIndex:marker.eventIndex});
+  }
+  for(const [index,part]of layout.parts.entries()){
+    addMeasuredPayloadText(slide,part.text,part.box,context,options,{path:part.path,fit:part.fit,textStyle:part.style,align:part.alignment,diagnosticsHandled:true,timeline:{group,part:index,anchor}});
   }
 }
 
@@ -1283,6 +1406,16 @@ function addPlaceholderPayload(slide, label, value, region, context) {
   });
 }
 
+function nativeFontOptions(style) {
+  const face=style.fontFace;
+  if(face!==undefined) {
+    if(!face || typeof face.family!=='string' || !face.family.trim() || typeof face.bold!=='boolean' || typeof face.italic!=='boolean')
+      throw new OPFPptxError('invalid-font-selection','The font provider must supply a family and explicit bold/italic style-link flags.',{path:style.path});
+    return {fontFace:face.family,bold:face.bold,italic:face.italic};
+  }
+  return {fontFace:style.fontFamily,bold:style.fontWeight>=600,italic:style.italic};
+}
+
 function textBoxOptions(region, context, fontSize) {
   return {
     x: region.x,
@@ -1553,6 +1686,27 @@ async function normalizePptxZip(raw, context) {
     });
   }
 
+  attachCodeTags(entries, context.codeTags);
+  attachMetricTags(entries,context.metricTags);
+  attachCardTags(entries,context.cardTags);
+  attachHeadingTags(entries,context.headingTags);
+  attachPlainTextTags(entries,context.plainTextTags);
+  attachTimelineTags(entries,context.timelineTags);
+  for(const [part,bytes]of Object.entries(entries)){
+    if(!/^ppt\/slides\/slide\d+\.xml$/.test(part))continue;
+    const relationships=parseRelationships(entries,part);
+    for(const [frame]of decodeText(bytes).matchAll(/<p:graphicFrame>[\s\S]*?<\/p:graphicFrame>/g)){
+      const name=frame.match(/<p:cNvPr\b[^>]*\bname="([^"]+)"/)?.[1];
+      if(!context.chartHeadings.has(name))continue;
+      const id=frame.match(/<c:chart\b[^>]*\br:id="([^"]+)"/)?.[1],chartPart=relationships.get(id)?.path;
+      if(!chartPart)throw new OPFPptxError('packaging-failed','Generated chart relationship is missing.');
+      const {heading,labelColor}=context.chartHeadings.get(name);
+      if(heading!==undefined)writeChartCategoryHeading(entries,chartPart,heading);
+      // PptxGenJS hardcodes a black fallback in pie/doughnut label properties.
+      // Normalize only our generated chart text styles; point/series fills stay intact.
+      entries[chartPart]=encodeText(decodeText(entries[chartPart]).replace(/<c:txPr>[\s\S]*?<\/c:txPr>/g,properties=>properties.replace(/<a:solidFill>[\s\S]*?<\/a:solidFill>/g,()=>`<a:solidFill><a:srgbClr val="${labelColor}"/></a:solidFill>`)));
+    }
+  }
   const imageSources = new Map();
   for (const [part, bytes] of Object.entries(entries)) {
     if (!/^ppt\/slides\/slide\d+\.xml$/.test(part)) continue;
@@ -1628,6 +1782,11 @@ function normalizePartBytes(path, bytes, context, renameMaps, entries, imageMeta
   if (isXmlPart(path)) {
     let xml=decodeText(bytes);
     if (path === '[Content_Types].xml') {
+      // PptxGenJS 4.0.1 emits one slide-master override per slide even
+      // though it creates only the actual master parts. Omit phantom master
+      // declarations without changing any existing part or relationship.
+      xml = xml.replace(/<Override PartName="\/(ppt\/slideMasters\/slideMaster\d+\.xml)"[^>]*\/>/g,
+        (override, part) => Object.hasOwn(entries, part) ? override : '');
       // Explicit per-part types also correct PptxGenJS's image/jpg default.
       const overrides = [...imageMetadata].filter(([, metadata]) => metadata).map(([part, metadata]) =>
         `<Override PartName="/${part}" ContentType="${metadata.mediaType}"/>`).join('');