@openpresentation/opf-pptx 0.7.0 → 0.8.0

package/DEPENDENCY-NOTES.md

@@ -8,9 +8,11 @@ The inspected PptxGenJS 4.0.1 ESM/CommonJS distributions do not import `image-si
 
 Every build checks the vendored code and license against `UPSTREAM.json`. `node scripts/vendor-pptxgenjs.mjs` is an explicit maintainer command that fetches the pinned official npm archive, verifies its SHA-512 integrity and reads only the named distribution/license entries. It is never run by builds or installations. Review the upstream source, actual imports, license and audit before changing versions; retain tests and reassess [GHSA-w3rx-r6r6-pgpr](https://github.com/advisories/GHSA-w3rx-r6r6-pgpr) and [GHSA-5p2g-fcmc-qvqq](https://github.com/advisories/GHSA-5p2g-fcmc-qvqq). Do not accept npm's incompatible PptxGenJS downgrade suggestion.
 
+Package normalization removes PptxGenJS 4.0.1 content-type declarations for generated slide-master parts that do not exist, without changing the vendor bytes or existing package parts. The smoke regression requires every override to target an actual part. This ports the independently audited correction from [commit 1363a65](https://github.com/OpenPresentation/opf-pptx/commit/1363a653c8b0e80c50d970bc30db3587bcf6f14e). Its notes-master SDK/native-order disagreement remains separate; the native ordering is unchanged.
+
 ## Compatible raster decoding
 
-Sharp 0.35.4 (Apache-2.0) is pinned for Node-only WebP-to-PNG conversion and loads lazily only when conversion is needed. Its platform packages include libvips and codec licenses; retain the upstream license files distributed by npm. Node 20.9+ and normal optional-platform dependency installation are required. Browser builds use the browser's decoder/canvas and a conditional package import; a bundling check rejects Sharp or the Node adapter in browser output. Ordinary/preserved image exports are tested with Sharp loading blocked.
+Sharp 0.35.4 (Apache-2.0) is pinned for Node-only WebP-to-PNG conversion and loads lazily only when conversion is needed. Its platform packages include libvips and codec licenses; retain the upstream license files distributed by npm. This package requires Node 24 and normal optional-platform dependency installation. Browser builds use the browser's decoder/canvas and a conditional package import; a bundling check rejects Sharp or the Node adapter in browser output. Ordinary/preserved image exports are tested with Sharp loading blocked.
 
 The candidate's complete npm audit reports no known vulnerabilities in the installed graph. npm does not audit vendored source as an installed PptxGenJS package: maintainers must also review upstream PptxGenJS advisories and releases when updating or auditing the vendor directory. The browser bundler esbuild 0.28.2 and Playwright are development-only. No hosted service, paid API or telemetry was added.
 

package/README.md

@@ -1,12 +1,24 @@
 # OPF PPTX
 
+Version 0.8.0 and this checkout require Node 24 (`24.x`). Use `.nvmrc` for local development. Earlier published versions retain their original engine declarations. Browser entrypoints remain browser-safe; native application compatibility is verified separately.
+
+Version 0.8.0 consumes shared heading/scalar/rich line placement, including `textRasterPadding`, through editable native line boxes without autofit. Complete heading tags retain title/subtitle/tag roles, line ordering and current edited text during import. Source boundary metadata also records hard-line separators, so complete scalar/heading groups recover current native text with spaces, tabs and exact authored line endings. Incomplete, duplicate, ambiguous or bulleted groups fall back to ordinary import with diagnostics. Legacy heading tags retain their prior native-line behavior; arbitrary formatting, nesting and geometry are not reconstructed. See the [source contract and limits](https://github.com/OpenPresentation/opf/blob/f94125a1ff95bf0974a055fe1c081d348dad54f2/docs/plans/text-placement.md). Native raster certification remains separate.
+
 Pure local PowerPoint conversion tooling for Open Presentation Format documents. This repo owns the Phase 3 and Phase 4 toolkit lanes: OPF to PPTX export and PPTX to OPF import.
 
 Version 0.7.0's [shared-code integration](docs/code-roundtrip.md) preserves exact source/metadata through guarded native tags and editable lines. XML-forbidden code characters reject export with `invalid-code-text`, the OPF field path and UTF-16 offset; schema validation alone does not establish XML representability. Native source recovery does not reconstruct formatting, geometry or font theme.
 
+Version 0.8.0 includes [shared metric integration](docs/metric-roundtrip.md). Native alignment and exact tested field recovery are implemented; tab-position and raster fidelity gates remain open.
+
+The [native text verifier](docs/native-text-checks.md) has completed 24 separately bounded cases on each supported Node runtime against its recorded source baseline. All 72 imports and 96 original-text ink masks per runtime pass; parent-owned temporary fonts are removed after success, failure and timeout controls. Those historical results do not cover subsequent font-selection changes, edited-text reflow, arbitrary native fidelity or the unresolved chart and metric gates.
+
+Version 0.8.0 physical-font selection consumes optional `fontFace` metadata on accepted text styles. The provider supplies the physical family and its boolean bold/italic style-link flags independently of logical numeric weight. This lets a resolved Roboto SemiBold or ExtraBold face keep its regular legacy-family style rather than requesting a second bold style. Providers without metadata retain the previous numeric-weight behavior; malformed metadata fails with `invalid-font-selection`. Use core 0.10.0 and renderer 0.8.0. [Verification and limits](docs/evidence/font-variants/README.md) distinguish native selection flags from actual Office paint.
+
+Version 0.8.0 also measures `design.contentBox` cards through core's padded interior and exports editable rounded frames at their outer allocation. Native tags identify unchanged empty generated frames on reimport, with a `content-card-reflow` diagnostic: frame appearance and placement are not reconstructed. A name alone never hides a shape; edited, untagged or ambiguous frames use ordinary native import, retaining text or an unsupported-shape description. These source checks do not establish native PowerPoint raster fidelity.
+
 ## Scope
 
-Version 0.7.0 requires core 0.9.0 and uses renderer 0.7.0 for coordinated preview/font measurement. Quotes and code export their accepted internal lines and styles without another fitting pass. [Controlled Windows PowerPoint quote evidence](docs/evidence/shared-quote-integration/comparison.json) records glyph containment, separation, save/reopen and text reimport against its exact source/font hashes. Native quote import returns editable text blocks and does not restore the original OPF quote structure, typography or readability policy. Native chart geometry and general scalar-text wrapping also remain different from preview; editability and valid reimport do not establish raster equivalence.
+Version 0.8.0 requires core 0.10.0 and uses renderer 0.8.0 for coordinated preview/font measurement. Quotes and code export their accepted internal lines and styles without another fitting pass. [Controlled Windows PowerPoint quote evidence](docs/evidence/shared-quote-integration/comparison.json) records glyph containment, separation, save/reopen and text reimport against its exact source/font hashes. Native quote import returns editable text blocks and does not restore the original OPF quote structure, typography or readability policy. Native chart geometry and general scalar-text wrapping also remain different from preview; editability and valid reimport do not establish raster equivalence.
 
 - Package: `@openpresentation/opf-pptx`
 - Repository: `OpenPresentation/opf-pptx`
@@ -67,7 +79,7 @@ This pass did not require an OPF schema change. The deferred full OOXML placehol
 The first importer is mechanical and schema-compatible:
 
 - Presentation core properties map to OPF `name`, `description`, and `author`.
-- Slide text placeholders and large top-of-slide text boxes map to `title` and `subtitle` when recognizable.
+- Native title/subtitle placeholders retain their roles. On slides without complete OPF heading tags, recognizable text-box positions and sizes provide a fallback. If any complete OPF heading role is recovered, untagged body text stays in `blocks[]` instead of being promoted into an absent heading role. Damaged tags retain visible text through ordinary import and diagnostics.
 - Remaining text boxes map to `blocks[]` as text or list payloads, sorted by OOXML position.
 - PowerPoint tables map to OPF table blocks, embedded images map to data URI image blocks, and cached chart series map to basic OPF chart blocks.
 - Table imports retain empty rows. A native `firstRow` flag of `1` or `true` maps the first row to column labels; absent/false flags retain every row as data. New exports set this flag from OPF columns. Older exports without the flag retain their labels as the first data row rather than inferring headers.
@@ -157,7 +169,7 @@ Native viewer check: Keynote 14.4 displays the PNG/JPEG/GIF media-type specimens
 
 Set `imageFormat: "preserve"` to embed WebP unchanged when the receiving application supports it. Other image formats keep their existing export behavior. Conversion errors include the OPF image path; images above 40 megapixels are rejected before compatible conversion. Decoder differences can affect color/alpha rounding, so byte identity across platforms is not promised.
 
-Node conversion lazily loads the pinned open-source Sharp dependency and requires Node 20.9 or later. Normal package installation must include platform optional dependencies for its native binaries. Browser bundles select a separate browser decoder using local Blob/image/canvas APIs; Sharp and Node code are excluded. Neither path uploads images or fetches asset URLs. Source-preserving export and ordinary PNG/JPEG/GIF operations do not load Sharp.
+Node conversion lazily loads the pinned open-source Sharp dependency and requires Node 24. Normal package installation must include platform optional dependencies for its native binaries. Browser bundles select a separate browser decoder using local Blob/image/canvas APIs; Sharp and Node code are excluded. Neither path uploads images or fetches asset URLs. Source-preserving export and ordinary PNG/JPEG/GIF operations do not load Sharp.
 
 `npm test` includes the Node pixel-reference cases and verifies browser bundling. To run the browser pixel checks, run `npm run build:browser-check`, serve this repository locally, and open `/artifacts/webp-fallback/browser/index.html`. The page reports 13 checks covering embedded PNG pixels, alpha, EXIF, the first animation frame, fit/crop, resolver calls and DOM canvas fallback. These are browser export checks, separate from the recorded Keynote viewing evidence.
 
@@ -218,3 +230,5 @@ Conditional borders keep the whole-table outer frame separate from interior hori
 Export consumes the same core geometry as SVG. It writes native merged cells and corrects PptxGenJS's padding-unit heuristic and missing dotted/transparent-border options in generated XML. Rich runs retain their own resolved opacity, including opaque overrides within a translucent cell. Tests inspect actual native XML and repeated conversions; native PowerPoint raster parity is not established.
 
 Version 0.5.0 requires core 0.7.0 and renderer 0.5.0 for coordinated previews. `npm run test:styled-table` runs export/import regressions. For local browser verification, set `OPF_CORE_ROOT` to the core repository and `OPF_RENDER_ROOT` to the coordinated renderer worktree when running `npm run build:browser-check`. Serve the repository and open `/artifacts/native-styled-table-import/browser/index.html`. Omit those variables to exercise installed package dependencies.
+
+Version 0.8.0 exports editable native lines with explicit four-space tab stops. Boundary tags contain no original source words, so native edits and deletions remain authoritative. XML-unrepresentable scalar controls reject with an actionable path rather than silently losing characters. Twenty wide/portrait measured/estimated export cases, current-text mutation controls and damaged-tag fallbacks pass; native Office acceptance remains separate. The coordinated core browser workflow also verifies editing, undo and exact reimport.

package/dist/card-provenance.js

@@ -0,0 +1,51 @@
+import {XMLParser} from 'fast-xml-parser';
+import {attachTextTags,decodeTextTag} from './code-provenance.js';
+
+const TAG='OPF_CARD_V1',REL='http://schemas.openxmlformats.org/officeDocument/2006/relationships/tags';
+const parser=new XMLParser({ignoreAttributes:false,attributeNamePrefix:'',parseTagValue:false,trimValues:false});
+const decoder=new TextDecoder('utf-8',{fatal:true}),array=v=>v===undefined?[]:Array.isArray(v)?v:[v];
+const canonical=value=>JSON.stringify(value,(_key,item)=>item&&typeof item==='object'&&!Array.isArray(item)?Object.fromEntries(Object.keys(item).sort().map(key=>[key,item[key]])):item);
+
+// A name alone is never sufficient to remove a shape during import. Bind the
+// generated empty frame to its serialized properties through native shape tags.
+export function attachCardTags(entries,names) {
+  if(!names.size)return;
+  const records=new Map();
+  for(const path of Object.keys(entries).filter(path=>/^ppt\/slides\/slide\d+\.xml$/.test(path))){
+    const tree=parser.parse(decoder.decode(entries[path]))['p:sld']['p:cSld']['p:spTree'];
+    for(const shape of array(tree['p:sp'])){
+      const name=shape['p:nvSpPr']?.['p:cNvPr']?.name;
+      if(names.has(name)){
+        if(records.has(name))throw Error('Duplicate generated card frame.');
+        records.set(name,{v:1,path:names.get(name),properties:shape['p:spPr'],style:shape['p:style']??null});
+      }
+    }
+  }
+  if(records.size!==names.size)throw Error('Missing generated card frame.');
+  attachTextTags(entries,records,TAG,'opfCard','card');
+}
+
+export function importCardFrames(shapes,paragraphs,relationships,entries,report) {
+  const consumed=new Set();
+  for(const [index,shape]of shapes.entries()){
+    const properties=shape['p:spPr'],identity=shape['p:nvSpPr']?.['p:cNvPr'],tags=[];
+    let unreadable=false;
+    for(const link of array(shape['p:nvSpPr']?.['p:nvPr']?.['p:custDataLst']?.['p:tags'])){
+      const rel=relationships.get(link['r:id']);
+      if(rel?.type!==REL||rel.targetMode==='External'||!entries[rel.path])continue;
+      try{tags.push(...array(parser.parse(decoder.decode(entries[rel.path]))['p:tagLst']?.['p:tag']));}catch{unreadable=true;}
+    }
+    const candidates=tags.filter(tag=>tag.name?.toUpperCase()===TAG);
+    if(!candidates.length)continue;
+    try{
+      if(unreadable||candidates.length!==1||tags.some(tag=>/^OPF_/i.test(tag.name)&&tag.name.toUpperCase()!==TAG))throw Error('Ambiguous frame identity.');
+      const manifest=decodeTextTag(candidates[0].val);
+      if(manifest.v!==1||typeof manifest.path!=='string'||!manifest.path.startsWith('slides.')||identity?.name!==`OPF card ${manifest.path}`)throw Error('Invalid frame identity.');
+      if((paragraphs[index]??[]).some(p=>p.text.length)||Object.keys(identity).some(key=>!['id','name'].includes(key)))throw Error('Frame has native content or metadata.');
+      if(properties?.['a:prstGeom']?.prst!=='roundRect'||canonical(properties)!==canonical(manifest.properties)||canonical(shape['p:style']??null)!==canonical(manifest.style))throw Error('Frame styling or geometry changed.');
+      consumed.add(shape);
+      report({code:'content-card-reflow',message:'An unchanged tagged OPF content card was recognized as decoration. Its native frame styling and placement are not reconstructed in the reflowed document.'});
+    }catch{report({code:'invalid-card-provenance',message:'Edited, ambiguous or invalid card frame passed to ordinary native import, which retains its text or an unsupported-shape description. Inspect the original PPTX for frame appearance and metadata.'});}
+  }
+  return consumed;
+}

package/dist/chart-workbook.js

@@ -0,0 +1,81 @@
+import {unzipSync,zipSync} from 'fflate';
+import {XMLParser} from 'fast-xml-parser';
+const parser=new XMLParser({ignoreAttributes:false,attributeNamePrefix:'',parseTagValue:false,trimValues:false,removeNSPrefix:true,htmlEntities:{amp:'&',lt:'<',gt:'>',quot:'"',apos:"'"}});
+const decoder=new TextDecoder('utf-8',{fatal:true}),encoder=new TextEncoder();
+const array=value=>value===undefined?[]:Array.isArray(value)?value:[value];
+const xml=(entries,path)=>entries[path]?parser.parse(decoder.decode(entries[path])):undefined;
+const find=(value,key)=>!value||typeof value!=='object'?[]:Array.isArray(value)?value.flatMap(item=>find(item,key)):Object.entries(value).flatMap(([name,child])=>name===key?array(child):find(child,key));
+const text=value=>typeof value==='string'?value:value&&typeof value==='object'?String(value['#text']??''):value===undefined?'':String(value);
+const richText=value=>value?.t!==undefined?text(value.t):array(value?.r).map(run=>text(run.t)).join('');
+const escape=value=>value.replace(/[&<>"'\r\n\t]/g,char=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&apos;','\r':'&#13;','\n':'&#10;','\t':'&#9;'}[char]));
+function relationship(entries,source,id){
+ if(typeof id!=='string'||!id)return undefined;
+ const slash=source.lastIndexOf('/'),part=`${source.slice(0,slash+1)}_rels/${source.slice(slash+1)}.rels`;
+ const rel=array(xml(entries,part)?.Relationships?.Relationship).find(rel=>rel.Id===id);
+ if(!rel||(rel.TargetMode!==undefined&&rel.TargetMode!=='Internal')||typeof rel.Target!=='string'||/^[a-z]+:/i.test(rel.Target)||/[\\?#]/.test(rel.Target))return undefined;
+ const pieces=[];
+ for(const component of (rel.Target.startsWith('/')?rel.Target.slice(1):source.slice(0,slash+1)+rel.Target).split('/')){
+  if(component==='..'){if(!pieces.length)return undefined;pieces.pop();}else if(component&&component!=='.')pieces.push(component);
+ }
+ return {path:pieces.join('/'),type:rel.Type};
+}
+function workbookContext(entries,chartPart){
+ const chart=xml(entries,chartPart)?.chartSpace;
+ const ref=relationship(entries,chartPart,chart?.externalData?.id);
+ if(!ref?.type?.endsWith('/package')||!entries[ref.path])return undefined;
+ // Read only bounded spreadsheet metadata. Never follow external workbook links.
+ let size=0;
+ const workbook=unzipSync(entries[ref.path],{filter:file=>{
+  if(!/^xl\/(workbook\.xml|_rels\/workbook\.xml\.rels|sharedStrings\.xml|worksheets\/[^/]+\.xml)$/.test(file.name))return false;
+  size+=file.originalSize;if(size>16*1024*1024)throw Error('Chart workbook metadata exceeds the limit.');return true;
+ }});
+ const category=find(chart,'cat')[0],formula=category?.strRef?.f??category?.multiLvlStrRef?.f??category?.numRef?.f;
+ // Infer a heading only for one contiguous vertical category range with a row
+ // above it. Other chart/workbook arrangements remain explicitly unrecovered.
+ const range=/^(?:'((?:[^']|'')+)'|([^'!]+))!\$?([A-Z]+)\$?(\d+):\$?([A-Z]+)\$?(\d+)$/i.exec(text(formula));
+ if(!range||range[3].toUpperCase()!==range[5].toUpperCase()||Number(range[4])<2||Number(range[6])<Number(range[4])||Number(range[6])>1048576)return undefined;
+ const column=range[3].toUpperCase();
+ if(column.length>3||[...column].reduce((value,letter)=>value*26+letter.charCodeAt(0)-64,0)>16384)return undefined;
+ const name=(range[1]?.replaceAll("''","'")??range[2]);
+ const sheet=array(xml(workbook,'xl/workbook.xml')?.workbook?.sheets?.sheet).find(sheet=>sheet.name===name);
+ const sheetRef=relationship(workbook,'xl/workbook.xml',sheet?.id);
+ if(!sheetRef?.type?.endsWith('/worksheet')||!workbook[sheetRef.path])return undefined;
+ const cellRef=`${column}${Number(range[4])-1}`;
+ const cell=find(xml(workbook,sheetRef.path)?.worksheet,'c').find(cell=>cell.r===cellRef);
+ return {workbookPart:ref.path,workbook,sheetPart:sheetRef.path,cellRef,cell};
+}
+export function readChartCategoryHeading(entries,chartPart){
+ try{
+  const context=workbookContext(entries,chartPart),cell=context?.cell;if(!cell||cell.f!==undefined)return undefined;
+  if(cell.t==='inlineStr')return richText(cell.is);
+  if(cell.t==='s'){
+   const value=text(cell.v);if(!/^\d+$/.test(value))return undefined;
+   const item=array(xml(context.workbook,'xl/sharedStrings.xml')?.sst?.si)[Number(value)];
+   return item===undefined?undefined:richText(item);
+  }
+  // Error, boolean, date and formula results are not literal text headings.
+  if(cell.t!==undefined&&!['str','n'].includes(cell.t))return undefined;
+  return cell.v===undefined?undefined:text(cell.v);
+ }catch{return undefined;}
+}
+export function writeChartCategoryHeading(entries,chartPart,heading){
+ const context=workbookContext(entries,chartPart);
+ if(!context?.cell||typeof heading!=='string')throw Error('Generated chart has no editable category heading cell.');
+ for(const character of heading){const point=character.codePointAt(0);if(![9,10,13].includes(point)&&(point<32||point>=0xD800&&point<=0xDFFF||point===0xFFFE||point===0xFFFF))throw Error('Chart category heading contains an XML-invalid character.');}
+ const workbook=unzipSync(entries[context.workbookPart]);
+ const source=decoder.decode(workbook[context.sheetPart]),pattern=new RegExp(`<c\\b(?=[^>]*\\br="${context.cellRef}")[^>]*(?:\\/>|>[\\s\\S]*?<\\/c>)`);
+ if(!pattern.test(source))throw Error('Generated category heading cell is missing.');
+ workbook[context.sheetPart]=encoder.encode(source.replace(pattern,()=>`<c r="${context.cellRef}" t="inlineStr"><is><t xml:space="preserve">${escape(heading)}</t></is></c>`));
+ // Update only table metadata related to this generated sheet and starting at
+ // this header. Other embedded sheets/tables are never rewritten by inference.
+ const slash=context.sheetPart.lastIndexOf('/');
+ const relationships=xml(workbook,`${context.sheetPart.slice(0,slash+1)}_rels/${context.sheetPart.slice(slash+1)}.rels`);
+ for(const rel of array(relationships?.Relationships?.Relationship)){
+  const ref=relationship(workbook,context.sheetPart,rel.Id);
+  if(!ref?.type?.endsWith('/table')||!workbook[ref.path])continue;
+  const table=decoder.decode(workbook[ref.path]);
+  if(xml(workbook,ref.path)?.table?.ref?.split(':')[0]!==context.cellRef)continue;
+  workbook[ref.path]=encoder.encode(table.replace(/(<tableColumn\b[^>]*\bid="1"[^>]*\bname=")[^"]*(")/,(_match,prefix,suffix)=>`${prefix}${escape(heading)}${suffix}`));
+ }
+ entries[context.workbookPart]=zipSync(workbook);
+}

package/dist/code-provenance.js

@@ -21,6 +21,12 @@ export function codeManifest(value, layout, group) {
 }
 
 export function attachCodeTags(entries, records) {
+  return attachTextTags(entries,records,TAG,'opfCode','code');
+}
+
+export {unhex as decodeTextTag};
+
+export function attachTextTags(entries, records, tagName, prefix, kind) {
   if (!records.size) return;
   let count = 0;
   const seen = new Set(), types = [];
@@ -31,23 +37,23 @@ export function attachCodeTags(entries, records) {
     const xml = dec.decode(entries[path]).replace(/<p:sp>[\s\S]*?<\/p:sp>/g, shape=>{
       const name = shape.match(/<p:cNvPr\b[^>]*\bname="([^"]+)"/)?.[1];
       if (!records.has(name)) return shape;
-      if (seen.has(name)) throw new Error('Duplicate generated code shape.');
+      if (seen.has(name)) throw new Error(`Duplicate generated ${kind} shape.`);
       seen.add(name);
-      const part = `ppt/tags/opfCode${++count}.xml`;
-      let id = `rIdOpfCode${count}`;
+      const part = `ppt/tags/${prefix}${++count}.xml`;
+      let id = `rId${prefix[0].toUpperCase()+prefix.slice(1)}${count}`;
       while (ids.has(id)) id += '_';
       ids.add(id);
-      entries[part] = enc.encode(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?><p:tagLst xmlns:p="${NS}"><p:tag name="${TAG}" val="${hex(records.get(name))}"/></p:tagLst>`);
+      entries[part] = enc.encode(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?><p:tagLst xmlns:p="${NS}"><p:tag name="${tagName}" val="${hex(records.get(name))}"/></p:tagLst>`);
       types.push(`<Override PartName="/${part}" ContentType="application/vnd.openxmlformats-officedocument.presentationml.tags+xml"/>`);
-      rels = rels.replace('</Relationships>',`<Relationship Id="${id}" Type="${REL}" Target="../tags/opfCode${count}.xml"/></Relationships>`);
+      rels = rels.replace('</Relationships>',`<Relationship Id="${id}" Type="${REL}" Target="../tags/${prefix}${count}.xml"/></Relationships>`);
       shape = shape.replace(/<p:nvPr\s*\/>/,'<p:nvPr></p:nvPr>');
-      if (!shape.includes('</p:nvPr>')) throw new Error('Generated code shape has no native application properties.');
+      if (!shape.includes('</p:nvPr>')) throw new Error(`Generated ${kind} shape has no native application properties.`);
       return shape.replace('</p:nvPr>',`<p:custDataLst><p:tags r:id="${id}"/></p:custDataLst></p:nvPr>`);
     });
     entries[path] = enc.encode(xml);
     entries[relPath] = enc.encode(rels);
   }
-  if (seen.size !== records.size) throw new Error('Missing generated code shapes.');
+  if (seen.size !== records.size) throw new Error(`Missing generated ${kind} shapes.`);
   entries['[Content_Types].xml'] = enc.encode(dec.decode(entries['[Content_Types].xml']).replace('</Types>',types.join('')+'</Types>'));
 }
 
@@ -120,10 +126,13 @@ export function importCodeGroups(shapes, paragraphs, relationships, entries, rep
       const rel = relationships.get(link['r:id']);
       if (rel?.type !== REL || rel.targetMode === 'External' || !rel.path || !entries[rel.path]) continue;
       let tags;
-      try { tags = array(parser.parse(dec.decode(entries[rel.path]))['p:tagLst']?.['p:tag']).filter(tag=>tag.name?.toUpperCase() === TAG); }
+      try {
+        const all=array(parser.parse(dec.decode(entries[rel.path]))['p:tagLst']?.['p:tag']);
+        tagCounts.set(shape,(tagCounts.get(shape)??0)+all.filter(tag=>/^OPF_/i.test(tag.name)).length);
+        tags=all.filter(tag=>tag.name?.toUpperCase()===TAG);
+      }
       catch { report({code:'invalid-code-provenance',message:'Unreadable code tags; visible native shapes were retained.'}); continue; }
       for (const tag of tags) {
-        tagCounts.set(shape,(tagCounts.get(shape) ?? 0)+1);
         try {
           const data = unhex(tag.val);
           if (data.v !== 1 || typeof data.group !== 'string' || !/^\d+$/.test(data.group)) throw new Error('Invalid code identity.');

package/dist/heading-provenance.js

@@ -0,0 +1,44 @@
+import {XMLParser} from 'fast-xml-parser';
+import {attachTextTags,decodeTextTag} from './code-provenance.js';
+import {sourceLineParagraphs} from './text-provenance.js';
+const TAG='OPF_HEADING_V1',REL='http://schemas.openxmlformats.org/officeDocument/2006/relationships/tags';
+const parser=new XMLParser({ignoreAttributes:false,attributeNamePrefix:'',parseTagValue:false,trimValues:false});
+const decoder=new TextDecoder('utf-8',{fatal:true}),array=value=>value===undefined?[]:Array.isArray(value)?value:[value];
+export const attachHeadingTags=(entries,records)=>attachTextTags(entries,records,TAG,'opfHeading','heading');
+
+// Tags carry only roles and line ordering. Current native text always wins;
+// neither original source text nor old geometry can be restored from these tags.
+export function importHeadingGroups(shapes,paragraphs,relationships,entries,report) {
+  const groups=new Map(),consumed=new Set(),items=[];
+  for(const [index,shape] of shapes.entries()) {
+    const tags=[];let unreadable=false;
+    for(const link of array(shape['p:nvSpPr']?.['p:nvPr']?.['p:custDataLst']?.['p:tags'])) {
+      const rel=relationships.get(link['r:id']);
+      if(rel?.type!==REL||rel.targetMode==='External'||!entries[rel.path])continue;
+      try{tags.push(...array(parser.parse(decoder.decode(entries[rel.path]))['p:tagLst']?.['p:tag']));}catch{unreadable=true;}
+    }
+    const candidates=tags.filter(tag=>tag.name?.toUpperCase()===TAG);
+    if(!candidates.length)continue;
+    for(const tag of candidates)try {
+      const data=decodeTextTag(tag.val);
+      if(data?.v!==1||!['title','subtitle','tag'].includes(data.field)||typeof data.group!=='string'||!/^slides\.\d+\.(title|subtitle|tag)$/.test(data.group)||!data.group.endsWith('.'+data.field))throw Error('Invalid heading identity.');
+      const group=groups.get(data.field)??[];
+      group.push({shape,index,data,ambiguous:unreadable||tags.filter(tag=>/^OPF_/i.test(tag.name)).length!==1});groups.set(data.field,group);
+    }catch{report({code:'invalid-heading-provenance',message:'Invalid heading tags; ordinary import retains visible native text.'});}
+  }
+  for(const group of groups.values())try {
+    const first=group[0].data,count=first.count;
+    if(!Number.isSafeInteger(count)||count<1||count>512||group.length!==count||new Set(group.map(item=>item.shape)).size!==count)throw Error('Incomplete or duplicated heading lines.');
+    const ordered=Array(count);
+    for(const item of group) {
+      const data=item.data;
+      if(item.ambiguous||data.group!==first.group||data.count!==count||!Number.isSafeInteger(data.line)||data.line<0||data.line>=count||ordered[data.line])throw Error('Ambiguous heading line.');
+      ordered[data.line]=item;
+    }
+    const restored=sourceLineParagraphs(ordered,paragraphs,{legacy:true});
+    for(const item of ordered)consumed.add(item.shape);
+    items.push({field:first.field,shapes:ordered.map(item=>item.shape),paragraphs:restored});
+    report({code:'heading-import-reflow',message:'Complete tagged heading lines retain their roles, order and current native text. New boundary tags also retain authored whitespace and line endings; legacy tags retain native line breaks. Formatting and geometry are not reconstructed.'});
+  }catch(error){report({code:'invalid-heading-provenance',message:`${error.message} Ordinary import retains visible native text.`});}
+  return {consumed,items};
+}

package/dist/index.d.ts

@@ -37,6 +37,8 @@ export interface ToPptxOptions {
   /** Default compatible converts WebP to a static PNG. Preserve embeds original WebP bytes. */
   imageFormat?: "compatible" | "preserve";
   textMeasurement?: TextMeasurement;
+  /** Match preview/pagination clearance around supplied vector text outlines; default 1. */
+  textRasterPadding?: number;
   onDiagnostic?: (diagnostic: LayoutDiagnostic) => void;
   baseDir?: string;
   compressionLevel?: number;

package/dist/index.js

@@ -1,11 +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";
@@ -171,7 +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});
@@ -384,9 +396,15 @@ function importSlide(entries, slidePath, slideIndex, presentationDimensions, opt
 
   const items = collectSlideItems(entries, slideRoot, slidePath, relationships, dimensions, options, slideIndex)
     .sort(comparePositionedItems);
-  const titleItem = takeTitleItem(items, dimensions);
+  // 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 = takeSubtitleItem(items, titleItem, dimensions);
+  const subtitleItem = heading('subtitle')??takeSubtitleItem(items, titleItem, dimensions, inferHeadings);
   if (subtitleItem) slide.subtitle = subtitleItem.text;
 
   const blocks = mergeAdjacentBulletShapes(items)
@@ -407,9 +425,28 @@ function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensi
   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)) continue;
+    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);
   }
@@ -433,13 +470,13 @@ function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensi
   return items;
 }
 
-function importShape(shape, dimensions, paragraphs = readParagraphs(shape["p:txBody"])) {
+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,
@@ -572,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 ?? ""));
   });
@@ -586,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
@@ -674,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
     }
   };
@@ -888,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, item.codeLayout);
+      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);
     }
   }
 
@@ -933,7 +987,7 @@ function fieldToType(field) {
   return field === "items" || field === "bullets" ? "list" : field;
 }
 
-async function addPayload(slide, presentation, payload, region, path, context, options, quoteLayout, codeLayout) {
+async function addPayload(slide, presentation, payload, region, path, context, options, quoteLayout, codeLayout,metricLayout,timelineLayout) {
   const kind = inferPayloadKind(payload);
   switch (kind) {
     case "text":
@@ -958,13 +1012,13 @@ async function addPayload(slide, presentation, payload, region, path, context, o
       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);
@@ -994,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){
@@ -1010,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);
@@ -1083,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,
@@ -1121,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) : [];
@@ -1133,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,
@@ -1150,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,
@@ -1199,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));
@@ -1208,11 +1277,20 @@ 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,
     });
   }
@@ -1238,7 +1316,7 @@ function addCodePayload(slide, value, layout, region, context, path) {
       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),
-        fontFace:part.style.fontFamily,bold:part.style.fontWeight>=600,italic:part.style.italic,
+        ...nativeFontOptions(part.style),
         color:part.role==='body'?'E5E7EB':'93C5FD',align:'left',fit:'none',wrap:false,lineSpacingMultiple:1,
         tabStops:tabStops.length?tabStops:undefined,objectName,
       });
@@ -1246,10 +1324,31 @@ function addCodePayload(slide, value, layout, region, context, path) {
   }
 }
 
-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) {
@@ -1263,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}});
   }
 }
 
@@ -1304,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,
@@ -1575,6 +1687,26 @@ 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;
@@ -1650,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('');

package/dist/metric-provenance.js

@@ -0,0 +1,94 @@
+import {XMLParser} from 'fast-xml-parser';
+import {validatePresentation} from '@openpresentation/opf';
+import {attachTextTags,decodeTextTag} from './code-provenance.js';
+
+const TAG='OPF_METRIC_V1',REL='http://schemas.openxmlformats.org/officeDocument/2006/relationships/tags';
+const parser=new XMLParser({ignoreAttributes:false,attributeNamePrefix:'',parseTagValue:false,trimValues:false});
+const decoder=new TextDecoder('utf-8',{fatal:true});
+const array=value=>value===undefined?[]:Array.isArray(value)?value:[value];
+const scalar=value=>typeof value==='string'||typeof value==='number';
+const sourceFor=(value,role)=>scalar(value)?value:value[role];
+
+// The first value line carries the complete manifest: no invisible panel is introduced.
+export function metricManifest(value,layout,group) {
+  return {v:1,group,role:'anchor',part:0,line:0,value,parts:layout.parts.map(part=>({role:part.role,visible:part.visible,
+    lines:part.fit?.sourceLines.map(({start,end,nextStart,boundary})=>({start,end,nextStart,boundary}))??[]}))};
+}
+export function attachMetricTags(entries,records) {return attachTextTags(entries,records,TAG,'opfMetric','metric');}
+
+function validateManifest(manifest) {
+  if (!validatePresentation({slides:[{metric:manifest.value}]}).valid) throw new Error('Invalid metric source.');
+  const roles=scalar(manifest.value)?['value']:['value','unit','label','description','delta','trend'].filter(role=>manifest.value[role]!==undefined);
+  if (!Array.isArray(manifest.parts)||manifest.parts.length!==roles.length||manifest.part!==0||manifest.line!==0) throw new Error('Invalid metric parts.');
+  for (const [index,part] of manifest.parts.entries()) {
+    const source=String(sourceFor(manifest.value,roles[index])),visible=roles[index]==='value'||source.length>0;
+    if (part.role!==roles[index]||part.visible!==visible||!Array.isArray(part.lines)||visible&&!part.lines.length||!visible&&part.lines.length) throw new Error('Invalid source part.');
+    let cursor=0;
+    for (const [i,line] of part.lines.entries()) {
+      if (![line.start,line.end,line.nextStart].every(Number.isSafeInteger)||line.start!==cursor||line.end<line.start||line.nextStart<line.end||line.nextStart>source.length) throw new Error('Invalid source range.');
+      const separator=source.slice(line.end,line.nextStart),last=i===part.lines.length-1;
+      if (/\r|\n/.test(source.slice(line.start,line.end))||(line.boundary==='hard'?!/^(?:\r\n|\r|\n)$/.test(separator)||last:separator!==''||line.boundary!==(last?'end':'soft'))) throw new Error('Invalid source boundary.');
+      cursor=line.nextStart;
+    }
+    if (cursor!==source.length) throw new Error('Incomplete source range.');
+  }
+}
+
+export function importMetricGroups(shapes,paragraphs,relationships,entries,report) {
+  const groups=new Map(),tagCounts=new Map(),consumed=new Set(),items=[];
+  for (const [index,shape] of shapes.entries()) {
+    for (const link of array(shape['p:nvSpPr']?.['p:nvPr']?.['p:custDataLst']?.['p:tags'])) {
+      const rel=relationships.get(link['r:id']);
+      if (rel?.type!==REL||rel.targetMode==='External'||!rel.path||!entries[rel.path]) continue;
+      let tags;
+      try {
+        const all=array(parser.parse(decoder.decode(entries[rel.path]))['p:tagLst']?.['p:tag']);
+        tagCounts.set(shape,(tagCounts.get(shape)??0)+all.filter(tag=>/^OPF_/i.test(tag.name)).length);
+        tags=all.filter(tag=>tag.name?.toUpperCase()===TAG);
+      } catch {report({code:'invalid-metric-provenance',message:'Unreadable metric tags; visible native shapes were retained.'});continue;}
+      for (const tag of tags) try {
+        const data=decodeTextTag(tag.val);
+        if (data.v!==1||typeof data.group!=='string'||!/^\d+$/.test(data.group)) throw new Error('Invalid metric identity.');
+        const group=groups.get(data.group)??[];
+        group.push({data,shape,text:(paragraphs[index]??[]).map(p=>p.text).join('\n')});groups.set(data.group,group);
+      } catch {report({code:'invalid-metric-provenance',message:'Invalid metric tags; visible native shapes were retained.'});}
+    }
+  }
+  for (const group of groups.values()) try {
+    if (group.some(item=>tagCounts.get(item.shape)!==1)) throw new Error('Multiple source identities on one shape.');
+    const anchors=group.filter(item=>item.data.role==='anchor');
+    if (anchors.length!==1) throw new Error('Missing or duplicated metric anchor.');
+    const anchor=anchors[0],manifest=anchor.data;validateManifest(manifest);
+    const expected=manifest.parts.reduce((sum,part)=>sum+part.lines.length,0);
+    if (group.length!==expected||new Set(group.map(item=>item.shape)).size!==expected) throw new Error('Incomplete or duplicated metric shapes.');
+    const nativeLines=new Map();
+    for (const item of group) {
+      const {role,part,line}=item.data,key=`${part}:${line}`;
+      if ((item!==anchor&&role!=='line')||!Number.isSafeInteger(part)||!Number.isSafeInteger(line)||!manifest.parts[part]?.lines[line]||nativeLines.has(key)) throw new Error('Ambiguous metric source line.');
+      nativeLines.set(key,item.text);
+    }
+    const value=scalar(manifest.value)?{value:manifest.value}:{...manifest.value},typeChanges=[];
+    for (const [partIndex,part] of manifest.parts.entries()) {
+      if (!part.visible) continue;
+      const original=sourceFor(manifest.value,part.role),source=String(original),newline=source.match(/\r\n|\r|\n/)?.[0]??'\n';
+      let rebuilt='';
+      for (const [lineIndex,line] of part.lines.entries()) {
+        const actual=nativeLines.get(`${partIndex}:${lineIndex}`);
+        if (actual===undefined) throw new Error('Missing metric source line.');
+        rebuilt+=actual.replace(/\r\n|\r|\n/g,newline)+source.slice(line.end,line.nextStart);
+      }
+      // Preserve original types for unchanged text. Canonical finite numeric edits remain
+      // numeric; other spellings become strings so no whitespace or precision is discarded.
+      value[part.role]=typeof original==='number'&&rebuilt===source?original:
+        typeof original==='number'&&Number.isFinite(Number(rebuilt))&&String(Number(rebuilt))===rebuilt?Number(rebuilt):rebuilt;
+      if (typeof original!==typeof value[part.role]) typeChanges.push(part.role);
+    }
+    const metric=scalar(manifest.value)?value.value:value;
+    if (!validatePresentation({slides:[{metric}]}).valid) throw new Error('Edited native text cannot form a valid metric.');
+    for (const item of group) consumed.add(item.shape);
+    items.push({shape:anchor.shape,payload:{type:'metric',metric}});
+    if (typeChanges.length) report({code:'metric-value-type-changed',message:`Edited numeric ${typeChanges.join(', ')} retained as literal text to avoid discarding spelling or precision.`});
+    report({code:'metric-import-reflow',message:'Metric fields, source boundaries and native text were recovered. Native formatting, positioning, alignment and font theme are not reconstructed; review the reflowed OPF.'});
+  } catch (error) {report({code:'invalid-metric-provenance',message:`${error.message} Visible native shapes were retained without restoring old source text.`});}
+  return {consumed,items};
+}

package/dist/text-provenance.js

@@ -0,0 +1,54 @@
+import {XMLParser} from 'fast-xml-parser';
+import {attachTextTags,decodeTextTag} from './code-provenance.js';
+const TAG='OPF_TEXT_V1',REL='http://schemas.openxmlformats.org/officeDocument/2006/relationships/tags';
+const parser=new XMLParser({ignoreAttributes:false,attributeNamePrefix:'',parseTagValue:false,trimValues:false});
+const decoder=new TextDecoder('utf-8',{fatal:true}),array=value=>value===undefined?[]:Array.isArray(value)?value:[value];
+export const attachPlainTextTags=(entries,records)=>attachTextTags(entries,records,TAG,'opfText','plain text');
+
+// Only boundaries are stored. Current native characters, including edits and
+// empty lines, always supply the text; tags cannot restore discarded old words.
+export function sourceLineParagraphs(ordered,paragraphs,{legacy=false}={}) {
+ const source=ordered.some(item=>item.data.boundary!==undefined||item.data.separator!==undefined);
+ if(!source&&legacy)return ordered.flatMap(item=>paragraphs[item.index]??[]);
+ let text='',maxFontSize=0;
+ for(const [index,item]of ordered.entries()) {
+  const {boundary,separator}=item.data,last=index===ordered.length-1;
+  if(typeof separator!=='string'||(boundary==='hard'?!/^(\r\n|\r|\n)$/.test(separator)||last:separator!==''||boundary!==(last?'end':'soft')))throw Error('Invalid source line boundary.');
+  const current=paragraphs[item.index]??[];
+  if(current.some(p=>p.bullet))throw Error('Tagged plain text now has native bullets.');
+  text+=current.map(p=>p.text).join('\n')+separator;
+  maxFontSize=Math.max(maxFontSize,...current.map(p=>p.maxFontSize??0));
+ }
+ return [{text,maxFontSize,bullet:false,level:0}];
+}
+
+export function importPlainTextGroups(shapes,paragraphs,relationships,entries,report) {
+ const groups=new Map(),consumed=new Set(),items=[];
+ for(const [index,shape]of shapes.entries()) {
+  const tags=[];let unreadable=false;
+  for(const link of array(shape['p:nvSpPr']?.['p:nvPr']?.['p:custDataLst']?.['p:tags'])) {
+   const rel=relationships.get(link['r:id']);if(rel?.type!==REL||rel.targetMode==='External'||!entries[rel.path])continue;
+   try{tags.push(...array(parser.parse(decoder.decode(entries[rel.path]))['p:tagLst']?.['p:tag']));}catch{unreadable=true;}
+  }
+  for(const tag of tags.filter(tag=>tag.name?.toUpperCase()===TAG))try {
+   const data=decodeTextTag(tag.val);
+   if(data?.v!==1||typeof data.group!=='string'||data.group.length>4096||!/^slides\.\d+(?:\.[A-Za-z0-9_:+-]+)*\.text$/.test(data.group))throw Error('Invalid plain text identity.');
+   const group=groups.get(data.group)??[];group.push({shape,index,data,ambiguous:unreadable||tags.filter(tag=>/^OPF_/i.test(tag.name)).length!==1});groups.set(data.group,group);
+  }catch{report({code:'invalid-text-provenance',message:'Invalid plain text tags; ordinary import retains current native text.'});}
+ }
+ for(const group of groups.values())try {
+  const count=group[0].data.count;
+  if(!Number.isSafeInteger(count)||count<1||count>10000||group.length!==count||new Set(group.map(item=>item.shape)).size!==count)throw Error('Incomplete or duplicated plain text lines.');
+  const ordered=Array(count);
+  for(const item of group) {
+   const data=item.data;
+   if(item.ambiguous||data.count!==count||!Number.isSafeInteger(data.line)||data.line<0||data.line>=count||ordered[data.line])throw Error('Ambiguous plain text line.');
+   ordered[data.line]=item;
+  }
+  const restored=sourceLineParagraphs(ordered,paragraphs);
+  for(const item of ordered)consumed.add(item.shape);
+  items.push({shapes:ordered.map(item=>item.shape),paragraphs:restored});
+  report({code:'text-import-reflow',message:'Complete tagged lines retain current native text, whitespace and authored line boundaries. Native formatting, geometry and OPF nesting are not reconstructed; review the reflowed text.'});
+ }catch(error){report({code:'invalid-text-provenance',message:`${error.message} Ordinary import retains current native text without restoring old source words.`});}
+ return {consumed,items};
+}

package/dist/timeline-provenance.js

@@ -0,0 +1,81 @@
+import {XMLParser} from 'fast-xml-parser';
+import {validatePresentation} from '@openpresentation/opf';
+import {attachTextTags,decodeTextTag} from './code-provenance.js';
+import {sourceLineParagraphs} from './text-provenance.js';
+
+const TAG='OPF_TIMELINE_V1',REL='http://schemas.openxmlformats.org/officeDocument/2006/relationships/tags';
+const parser=new XMLParser({ignoreAttributes:false,attributeNamePrefix:'',parseTagValue:false,trimValues:false});
+const decoder=new TextDecoder('utf-8',{fatal:true}),array=value=>value===undefined?[]:Array.isArray(value)?value:[value];
+export const attachTimelineTags=(entries,records)=>attachTextTags(entries,records,TAG,'opfTimeline','timeline');
+
+// Only topology and line boundaries are retained. Every field value comes from
+// current native text; clearing or editing a field cannot restore old words.
+export function timelineManifest(value,layout) {
+  return {shorthand:Array.isArray(value),eventCount:(Array.isArray(value)?value:value.events).length,
+    parts:layout.parts.map(part=>({eventIndex:part.eventIndex,field:part.role==='event-description'?'description':part.role,lines:part.fit.sourceLines.length}))};
+}
+function validateManifest(manifest) {
+  if(!manifest||typeof manifest.shorthand!=='boolean'||!Number.isSafeInteger(manifest.eventCount)||manifest.eventCount<1||manifest.eventCount>10000||!Array.isArray(manifest.parts)||manifest.parts.length>10000)throw Error('Invalid timeline topology.');
+  const keys=[],fields=new Set();let count=0;
+  for(const part of manifest.parts){
+    if(!part||!Number.isSafeInteger(part.lines)||part.lines<1||part.lines>10000)throw Error('Invalid timeline line count.');
+    if(part.eventIndex===undefined){if(manifest.shorthand||!['name','description'].includes(part.field))throw Error('Invalid timeline metadata field.');}
+    else if(!Number.isSafeInteger(part.eventIndex)||part.eventIndex<0||part.eventIndex>=manifest.eventCount||!['when','what','description'].includes(part.field))throw Error('Invalid timeline event field.');
+    const key=`${part.eventIndex??'metadata'}:${part.field}`;if(fields.has(key))throw Error('Duplicated timeline field.');fields.add(key);keys.push(key);count+=part.lines;
+  }
+  if(count>10000)throw Error('Too many timeline source lines.');
+  const expected=['name','description'].map(field=>`metadata:${field}`).filter(key=>fields.has(key));
+  for(let index=0;index<manifest.eventCount;index++){
+    if(!fields.has(`${index}:what`))throw Error('Missing timeline event label.');
+    for(const field of ['when','what','description'])if(fields.has(`${index}:${field}`))expected.push(`${index}:${field}`);
+  }
+  if(JSON.stringify(keys)!==JSON.stringify(expected))throw Error('Invalid timeline source order.');
+  return count;
+}
+
+export function importTimelineGroups(shapes,paragraphs,relationships,entries,report) {
+  const groups=new Map(),consumed=new Set(),items=[];
+  for(const [index,shape]of shapes.entries()){
+    const tags=[];let unreadable=false;
+    for(const link of array(shape['p:nvSpPr']?.['p:nvPr']?.['p:custDataLst']?.['p:tags'])){
+      const rel=relationships.get(link['r:id']);if(rel?.type!==REL||rel.targetMode==='External'||!entries[rel.path])continue;
+      try{tags.push(...array(parser.parse(decoder.decode(entries[rel.path]))['p:tagLst']?.['p:tag']));}catch{unreadable=true;}
+    }
+    for(const tag of tags.filter(tag=>tag.name?.toUpperCase()===TAG))try{
+      const data=decodeTextTag(tag.val);if(data?.v!==1||typeof data.group!=='string'||!/^\d{1,12}$/.test(data.group))throw Error('Invalid timeline identity.');
+      const group=groups.get(data.group)??[];group.push({shape,index,data,ambiguous:unreadable||tags.filter(tag=>/^OPF_/i.test(tag.name)).length!==1});groups.set(data.group,group);
+    }catch{report({code:'invalid-timeline-provenance',message:'Invalid timeline tags; ordinary import retains current native text.'});}
+  }
+  for(const group of groups.values())try{
+    const anchors=group.filter(item=>item.data.anchor!==undefined);if(anchors.length!==1)throw Error('Missing or duplicated timeline anchor.');
+    const anchor=anchors[0],manifest=anchor.data.anchor,count=validateManifest(manifest);
+    const total=count+manifest.eventCount+1;
+    if(anchor.data.role!=='text'||anchor.data.part!==0||anchor.data.line!==0||group.length!==total||new Set(group.map(item=>item.shape)).size!==total)throw Error('Incomplete or duplicated timeline elements.');
+    const ordered=manifest.parts.map(part=>Array(part.lines)),markers=new Set();let connectors=0;
+    for(const item of group){
+      if(item.ambiguous)throw Error('Multiple source identities on one timeline shape.');
+      if(item.data.role==='connector'||item.data.role==='marker'){
+        const expected=item.data.role==='connector'?'line':'ellipse';
+        if(item.shape['p:spPr']?.['a:prstGeom']?.prst!==expected||(paragraphs[item.index]??[]).some(paragraph=>paragraph.text||paragraph.bullet))throw Error('Timeline graphic now contains different geometry or native text.');
+        if(item.data.role==='connector'){if(++connectors>1)throw Error('Duplicated timeline connector.');}
+        else{const index=item.data.eventIndex;if(!Number.isSafeInteger(index)||index<0||index>=manifest.eventCount||markers.has(index))throw Error('Ambiguous timeline marker.');markers.add(index);}
+        continue;
+      }
+      const {part,line}=item.data;
+      if(item.data.role!=='text'||!Number.isSafeInteger(part)||!Number.isSafeInteger(line)||part<0||line<0||!manifest.parts[part]||line>=manifest.parts[part].lines||item.data.count!==manifest.parts[part].lines||ordered[part][line])throw Error('Ambiguous timeline source line.');
+      ordered[part][line]=item;
+    }
+    if(connectors!==1||markers.size!==manifest.eventCount)throw Error('Incomplete timeline graphics.');
+    const result={events:Array.from({length:manifest.eventCount},()=>({}))};
+    for(const [index,part]of manifest.parts.entries()){
+      const text=sourceLineParagraphs(ordered[index],paragraphs)[0].text;
+      if(part.eventIndex===undefined)result[part.field]=text;else result.events[part.eventIndex][part.field]=text;
+    }
+    const timeline=manifest.shorthand?result.events:result;
+    if(!validatePresentation({slides:[{timeline}]}).valid)throw Error('Current native text does not form a valid timeline.');
+    for(const item of group)consumed.add(item.shape);
+    items.push({shapes:group.map(item=>item.shape),payload:{type:'timeline',timeline}});
+    report({code:'timeline-import-reflow',message:'Timeline field order, source boundaries and current native text were recovered. Native formatting, positions, marker styling and font theme are not reconstructed; review the reflowed timeline.'});
+  }catch(error){report({code:'invalid-timeline-provenance',message:`${error.message} Ordinary import retains current native text without restoring old source words.`});}
+  return {consumed,items};
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@openpresentation/opf-pptx",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Pure local OPF to PPTX export and PPTX to OPF import tooling.",
   "license": "MIT",
   "type": "module",
   "private": false,
   "engines": {
-    "node": ">=20.9.0"
+    "node": "24.x"
   },
   "repository": {
     "type": "git",
@@ -37,8 +37,8 @@
   "sideEffects": false,
   "scripts": {
     "build": "node scripts/build.mjs",
-    "typecheck": "node --check src/index.js && node --check scripts/build.mjs && node --check scripts/validate-package.mjs && node --check test/smoke.mjs && node --check src/image-geometry.js && node --check test/image-fit.mjs && node --check test/image-orientation.mjs && node --check test/table-layout.mjs && node --check test/table-import.mjs && node --check test/object-ids.mjs && node --check test/export-corpus.mjs && node --check test/image-media-type.mjs && node --check src/image-fallback-node.js && node --check src/image-fallback-browser.js && node --check test/webp-fallback.mjs && node --check scripts/build-browser-check.mjs && node --check test/webp-fallback-browser.js && node --check test/image-fallback-boundary.mjs && node --check src/background.js && node --check test/background.mjs && node --check src/image-import.js && node --check test/image-import.mjs && node --check test/native-background.mjs && node --check src/background-import.js && node --check test/background-inheritance.mjs && node --check test/rich-table.mjs && node --check src/table-import.js && node --check test/rich-table-import.mjs && node --check test/rich-table-import-browser.js && node --check test/table-row-sizing.mjs && node --check test/table-styles.mjs && node --check test/table-styles-browser.js && node --check test/styled-table.mjs && node --check src/table-cell-import.js && node --check test/styled-table-import.mjs && node --check test/styled-table-import-browser.js && node --check src/table-border-import.js && node --check test/table-border-styles.mjs",
-    "test": "npm run build && node test/dependency-boundary.mjs && npm run build:browser-check && npm run test:styled-table && node test/content-layout.mjs && node test/shared-quote.mjs",
+    "typecheck": "node --check src/index.js && node --check scripts/build.mjs && node --check scripts/validate-package.mjs && node --check test/smoke.mjs && node --check src/image-geometry.js && node --check test/image-fit.mjs && node --check test/image-orientation.mjs && node --check test/table-layout.mjs && node --check test/table-import.mjs && node --check test/object-ids.mjs && node --check test/export-corpus.mjs && node --check test/image-media-type.mjs && node --check src/image-fallback-node.js && node --check src/image-fallback-browser.js && node --check test/webp-fallback.mjs && node --check scripts/build-browser-check.mjs && node --check test/webp-fallback-browser.js && node --check test/image-fallback-boundary.mjs && node --check src/background.js && node --check test/background.mjs && node --check src/image-import.js && node --check test/image-import.mjs && node --check test/native-background.mjs && node --check src/background-import.js && node --check test/background-inheritance.mjs && node --check test/rich-table.mjs && node --check src/table-import.js && node --check test/rich-table-import.mjs && node --check test/rich-table-import-browser.js && node --check test/table-row-sizing.mjs && node --check test/table-styles.mjs && node --check test/table-styles-browser.js && node --check test/styled-table.mjs && node --check src/table-cell-import.js && node --check test/styled-table-import.mjs && node --check test/styled-table-import-browser.js && node --check src/table-border-import.js && node --check test/table-border-styles.mjs && node --check src/card-provenance.js && node --check test/content-cards.mjs && node --check src/chart-workbook.js && node --check test/chart-colors.mjs && node --check test/chart-workbook.mjs && node --check test/native-chart-colors.mjs && node --check src/heading-provenance.js && node --check test/accepted-text.mjs && node --check test/heading-provenance.mjs && node --check src/text-provenance.js && node --check test/plain-whitespace.mjs && node --check src/timeline-provenance.js && node --check test/shared-timeline.mjs",
+    "test": "npm run build && node test/plain-whitespace.mjs && node test/accepted-text.mjs && node test/heading-provenance.mjs && node test/chart-colors.mjs && node test/content-cards.mjs && node test/chart-workbook.mjs && node test/dependency-boundary.mjs && npm run build:browser-check && npm run test:styled-table && node test/content-layout.mjs && node test/shared-quote.mjs && npm run test:timeline",
     "validate": "node scripts/validate-package.mjs",
     "test:packed": "node test/packed-install.mjs",
     "test:compare-published": "node test/compare-published.mjs",
@@ -46,17 +46,20 @@
     "prepack": "npm run build",
     "build:browser-check": "node scripts/build-browser-check.mjs",
     "test:styled-table": "node test/styled-table.mjs && node test/styled-table-import.mjs",
-    "test:code": "node test/shared-code.mjs && node test/code-provenance.mjs"
+    "test:code": "node test/shared-code.mjs && node test/code-provenance.mjs",
+    "test:metric": "node test/shared-metric.mjs && node test/metric-provenance.mjs",
+    "test:font-variants": "node test/font-variants.mjs",
+    "test:timeline": "node test/shared-timeline.mjs"
   },
   "dependencies": {
-    "@openpresentation/opf": "^0.9.0",
+    "@openpresentation/opf": "^0.10.0",
     "fast-xml-parser": "^5.8.0",
     "fflate": "^0.8.3",
     "jszip": "3.10.1",
     "sharp": "0.35.4"
   },
   "peerDependencies": {
-    "@openpresentation/opf-render": "^0.7.0"
+    "@openpresentation/opf-render": "^0.8.0"
   },
   "peerDependenciesMeta": {
     "@openpresentation/opf-render": {
@@ -64,7 +67,7 @@
     }
   },
   "devDependencies": {
-    "@openpresentation/opf-render": "0.7.0",
+    "@openpresentation/opf-render": "0.8.0",
     "esbuild": "0.28.2",
     "playwright": "1.63.0"
   },