@openpresentation/opf-pptx 0.6.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,10 +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.6.0 requires core 0.8.0 and uses renderer 0.6.0 for coordinated preview/font measurement. Quotes export their accepted body/source lines and styles without another fitting pass. [Controlled Windows PowerPoint 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`
@@ -65,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.
@@ -155,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.
 
@@ -216,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

@@ -0,0 +1,180 @@
+import { XMLParser } from 'fast-xml-parser';
+
+// Native shape tags are standard PresentationML customer data. Uppercase hex
+// protects case-sensitive source from PowerPoint's case-insensitive Tags API.
+const TAG = 'OPF_CODE_V1';
+const REL = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/tags';
+const NS = 'http://schemas.openxmlformats.org/presentationml/2006/main';
+const enc = new TextEncoder(), dec = new TextDecoder('utf-8', {fatal:true});
+const parser = new XMLParser({ignoreAttributes:false, attributeNamePrefix:'', parseTagValue:false, trimValues:false});
+const ordered = new XMLParser({ignoreAttributes:false, attributeNamePrefix:'', parseTagValue:false, trimValues:false, preserveOrder:true});
+const array = value => value === undefined ? [] : Array.isArray(value) ? value : [value];
+const hex = value => [...enc.encode(JSON.stringify(value))].map(byte=>byte.toString(16).padStart(2,'0')).join('').toUpperCase();
+function unhex(value) {
+  if (typeof value !== 'string' || !/^(?:[0-9A-Fa-f]{2})+$/.test(value)) throw new Error('Invalid code tag encoding.');
+  return JSON.parse(dec.decode(Uint8Array.from(value.match(/../g),byte=>parseInt(byte,16))));
+}
+
+export function codeManifest(value, layout, group) {
+  return {v:1, group, role:'panel', value, parts:layout.parts.map(part=>({role:part.role, generated:part.generated === true,
+    lines:part.fit.sourceLines.map(({start,end,nextStart,boundary})=>({start,end,nextStart,boundary}))}))};
+}
+
+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 = [];
+  for (const path of Object.keys(entries).filter(path=>/^ppt\/slides\/slide\d+\.xml$/.test(path)).sort()) {
+    const relPath = path.replace('/slides/','/slides/_rels/') + '.rels';
+    let rels = dec.decode(entries[relPath]);
+    const ids = new Set([...rels.matchAll(/\bId="([^"]+)"/g)].map(match=>match[1]));
+    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 ${kind} shape.`);
+      seen.add(name);
+      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="${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/${prefix}${count}.xml"/></Relationships>`);
+      shape = shape.replace(/<p:nvPr\s*\/>/,'<p:nvPr></p:nvPr>');
+      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 ${kind} shapes.`);
+  entries['[Content_Types].xml'] = enc.encode(dec.decode(entries['[Content_Types].xml']).replace('</Types>',types.join('')+'</Types>'));
+}
+
+const children = (nodes, name) => array(nodes).flatMap(node=>node[name] === undefined ? [] : [node[name]]);
+const plainText = nodes => array(nodes).map(node=>node['#text'] ?? '').join('');
+export const nativeTextShapes = tree => [...array(tree?.['p:sp']),...array(tree?.['p:grpSp']).flatMap(nativeTextShapes)];
+const orderedShapes = tree => [...children(tree,'p:sp'),...children(tree,'p:grpSp').flatMap(orderedShapes)];
+// Preserve the order of runs, fields and explicit line breaks. A keyed XML
+// object groups all a:r before a:fld and cannot represent their original order.
+export function nativeShapeParagraphs(xml) {
+  const root = children(ordered.parse(xml),'p:sld')[0];
+  const tree = children(children(root,'p:cSld')[0],'p:spTree')[0];
+  return orderedShapes(tree).map(shape=>children(children(shape,'p:txBody')[0],'a:p').map(paragraph=>{
+    let text = '', maxFontSize = 0, bullet = false, level = 0;
+    for (const child of paragraph) {
+      if (child['a:br'] !== undefined) text += '\n';
+      for (const key of ['a:r','a:fld']) if (child[key] !== undefined) {
+        text += children(child[key],'a:t').map(plainText).join('');
+        for (const run of child[key]) {
+          const size = Number(run[':@']?.sz);
+          if (run['a:rPr'] !== undefined && Number.isFinite(size)) maxFontSize = Math.max(maxFontSize,size/100);
+        }
+      }
+      if (child['a:pPr'] !== undefined) {
+        level = Number(child[':@']?.lvl ?? 0);
+        bullet = child['a:pPr'].some(node=>node['a:buChar'] !== undefined || node['a:buAutoNum'] !== undefined);
+      }
+    }
+    return {text,maxFontSize,bullet,level};
+  }));
+}
+
+function sourceFor(value, role, generated) {
+  if (generated) return 'code';
+  if (role === 'body') return typeof value === 'string' ? value : value.source;
+  return value[role];
+}
+
+function validateManifest(manifest) {
+  const {value,parts} = manifest;
+  const object = value && typeof value === 'object' && !Array.isArray(value);
+  if (typeof value !== 'string' && (!object || typeof value.source !== 'string' || Object.keys(value).some(key=>!['source','filename','language'].includes(key)) || ['filename','language'].some(key=>value[key] !== undefined && typeof value[key] !== 'string'))) throw new Error('Invalid source value.');
+  // Empty metadata is preserved in the manifest but does not produce a label.
+  const roles = [...(object && value.filename ? ['filename'] : []), ...(object && value.language ? ['language'] : []), 'body'];
+  if (roles.length === 1) roles.unshift('language');
+  if (!Array.isArray(parts) || parts.length !== roles.length) throw new Error('Invalid code parts.');
+  parts.forEach((part,i)=>{
+    const generated = roles.length === 2 && roles[0] === 'language' && !(object && (value.filename || value.language)) && i === 0;
+    if (part.role !== roles[i] || part.generated !== generated || !Array.isArray(part.lines) || !part.lines.length) throw new Error('Invalid source part.');
+    const source = sourceFor(value,part.role,generated);
+    let cursor = 0;
+    part.lines.forEach((line,index)=>{
+      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);
+      const last = index === 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.');
+  });
+}
+
+// Only complete, unambiguous sets are coalesced. Visible text always wins over
+// old source text; metadata supplies only source boundaries and payload roles.
+export function importCodeGroups(shapes, paragraphs, relationships, entries, report) {
+  const groups = new Map(), consumed = new Set(), items = [], tagCounts = new Map();
+  for (const [index,shape] of shapes.entries()) {
+    const links = array(shape['p:nvSpPr']?.['p:nvPr']?.['p:custDataLst']?.['p:tags']);
+    for (const link of links) {
+      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(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) {
+        try {
+          const data = unhex(tag.val);
+          if (data.v !== 1 || typeof data.group !== 'string' || !/^\d+$/.test(data.group)) throw new Error('Invalid code identity.');
+          const group = groups.get(data.group) ?? [];
+          group.push({data,shape,index,text:paragraphs[index].map(p=>p.text).join('\n')});groups.set(data.group,group);
+        } catch { report({code:'invalid-code-provenance',message:'Invalid code 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 panels = group.filter(item=>item.data.role === 'panel');
+      if (panels.length !== 1 || panels[0].text !== '') throw new Error('Missing, duplicated or edited panel.');
+      const panel = panels[0], manifest = panel.data;
+      validateManifest(manifest);
+      const expectedCount = 1 + manifest.parts.reduce((sum,part)=>sum+part.lines.length,0);
+      if (group.length !== expectedCount || new Set(group.map(item=>item.shape)).size !== group.length) throw new Error('Incomplete or duplicated code shapes.');
+      const nativeLines = new Map();
+      for (const item of group) if (item !== panel) {
+        const {role,part,line} = item.data, key = `${part}:${line}`;
+        if (role !== 'line' || !Number.isSafeInteger(part) || !Number.isSafeInteger(line) || !manifest.parts[part]?.lines[line] || nativeLines.has(key)) throw new Error('Ambiguous source line.');
+        nativeLines.set(key,item.text);
+      }
+      const value = typeof manifest.value === 'string' ? {source:manifest.value} : {...manifest.value};
+      for (const [partIndex,part] of manifest.parts.entries()) {
+        const source = sourceFor(manifest.value,part.role,part.generated), 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 source line.');
+          if (part.generated && actual !== source.slice(line.start,line.end)) throw new Error('Generated label was edited.');
+          rebuilt += actual.replace(/\r\n|\r|\n/g,newline) + source.slice(line.end,line.nextStart);
+        }
+        if (!part.generated) value[part.role === 'body' ? 'source' : part.role] = rebuilt;
+      }
+      for (const item of group) consumed.add(item.shape);
+      items.push({shape:panel.shape,payload:{type:'code',code:typeof manifest.value === 'string' ? value.source : value}});
+      report({code:'code-import-reflow',message:'Code source boundaries and native text were recovered. Native positioning, formatting and font theme are not reconstructed; review the reflowed OPF.'});
+    } catch (error) {
+      report({code:'invalid-code-provenance',message:`${error.message} Visible native shapes were retained without restoring old source text.`});
+    }
+  }
+  return {consumed,items};
+}

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;
@@ -48,7 +50,7 @@ export interface ToPptxOptions {
 }
 
 export interface FromPptxOptions {
-  /** Reports native background, picture and table details that OPF import cannot preserve. Table paths identify the native graphic-frame and row/cell indexes (including headers). */
+  /** Reports native details that import cannot preserve, including code provenance fallback/reflow and grouped text transforms. Table paths identify native frame and row/cell indexes (including headers). */
   onDiagnostic?: (diagnostic: {code: string; path: string; message: string}) => void;
   fallbackName?: string;
   schema?: string;