@openpresentation/opf-pptx 0.7.0 → 0.8.1

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,28 @@
 # OPF PPTX
 
+Version 0.8.1 requires core 0.10.1, including metric, quote and timeline layout placeholders and the corrected text-bullet contract. It retains the existing PowerPoint export APIs.
+
+Unfinished prepared shaping work is preserved in the [September 15 roadmap](docs/roadmap-shaping-20260915.md); it is not part of the published runtime.
+
+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 +83,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 +173,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 +234,9 @@ 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.
+
+The unpublished furniture candidate exports core's accepted header/footer text and picture geometry. Dedicated `OPF_FURNITURE_V1` tags describe roles, line boundaries, inactive flags and global/local scope. A slide manifest represents empty or disabled definitions without adding a visible shape. Tags contain no original text, image bytes or alt text. Reimport reads those values from current native shapes; complete groups recover literal dates, section/organization metadata and page-number intent when the current number matches the current slide position.
+
+Missing, duplicated or inconsistent furniture tags fall back to current native content with an `invalid-furniture-provenance` diagnostic. Conflicting organization or section values also fall back. Inherited definitions become global only when every slide has a valid definition/override and all inherited values agree; otherwise recovered definitions stay local. Reordering slides with unchanged visible page numbers preserves those numbers as ordinary text instead of silently renumbering them. Native typography, positioning, crop and unrelated metadata are not reconstructed; `furniture-import-reflow` requests review. `npm run test:furniture` exercises XML conversion and mutation controls. Native Office, visual corpus and clean installed-package acceptance remain separate gates; this behavior is not yet published.

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, hex as encodeTextTag};
+
+export function attachTextTags(entries, records, tagName, prefix, kind, {pictures = false} = {}) {
   if (!records.size) return;
   let count = 0;
   const seen = new Set(), types = [];
@@ -28,26 +34,27 @@ export function attachCodeTags(entries, records) {
     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 pattern = pictures ? /<p:(sp|pic)>[\s\S]*?<\/p:\1>/g : /<p:sp>[\s\S]*?<\/p:sp>/g;
+    const xml = dec.decode(entries[path]).replace(pattern, 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 +127,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/furniture-provenance.js

@@ -0,0 +1,214 @@
+import {XMLParser} from 'fast-xml-parser';
+import {attachTextTags, decodeTextTag, encodeTextTag} from './code-provenance.js';
+import {sourceLineParagraphs} from './text-provenance.js';
+
+const TAG = 'OPF_FURNITURE_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 array = value => value === undefined ? [] : Array.isArray(value) ? value : [value];
+const kinds = ['header', 'footer'], zones = ['left', 'center', 'right'];
+const fields = ['text', 'image', 'organization', 'section', 'slideNumber', 'date'];
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const key = part => `${part.kind}.${part.zone}.${part.field}`;
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const check = (condition, message) => { if (!condition) throw Error(message); };
+
+// This manifest contains topology, identities and inactive flags only. Current
+// native shapes supply all words, image bytes and alt text, even after edits.
+export function furnitureManifest(presentation, slide, layout, slideIndex) {
+  const definitions = {};
+  for (const kind of kinds) {
+    const local = slide.design?.[kind] !== undefined;
+    const source = local ? slide.design[kind] : presentation.design?.[kind];
+    if (source === undefined) continue;
+    const value = source === false ? false : {};
+    if (value !== false) for (const zone of zones) if (source[zone] !== undefined) {
+      value[zone] = {};
+      for (const field of fields) if (source[zone][field] !== undefined) {
+        const current = source[zone][field];
+        value[zone][field] = field === 'image' ? 'native' : typeof current === 'string' ? 'literal' : current;
+      }
+    }
+    definitions[kind] = {scope: local ? 'local' : 'global', value};
+  }
+  if (!Object.keys(definitions).length) return null;
+  const organizations = array(presentation.organization);
+  const organization = organizations.find(item => item.role === 'primary') ?? organizations[0];
+  return {v: 1, role: 'slide', group: String(slideIndex), definitions,
+    ...(layout.parts.some(part => part.field === 'organization') ? {organizationId: organization?.id} : {}),
+    parts: layout.parts.map(part => ({kind: part.kind, zone: part.zone, field: part.field,
+      type: part.type, count: part.type === 'image' ? 1 : part.fit.lines.length}))};
+}
+
+export function attachFurnitureTags(entries, records, manifests) {
+  attachTextTags(entries, records, TAG, 'opfFurniture', 'furniture', {pictures: true});
+  const types = [];
+  for (const [path, manifest] of manifests) {
+    const part = `ppt/tags/opfFurnitureSlide${manifest.group}.xml`;
+    const relPath = path.replace('/slides/', '/slides/_rels/') + '.rels';
+    let xml = dec.decode(entries[path]), rels = dec.decode(entries[relPath]);
+    // Common-slide customer data follows spTree, before controls/extLst.
+    // No invisible/fake shape is necessary for false or empty definitions.
+    const ids = new Set([...rels.matchAll(/\bId="([^"]+)"/g)].map(match => match[1]));
+    let id = 'rIdOpfFurnitureSlide';
+    while (ids.has(id)) id += '_';
+    check(!entries[part] && xml.includes('</p:spTree>'), 'Missing slide tree or colliding furniture tag part.');
+    xml = xml.replace('</p:spTree>', `</p:spTree><p:custDataLst><p:tags r:id="${id}"/></p:custDataLst>`);
+    rels = rels.replace('</Relationships>', `<Relationship Id="${id}" Type="${REL}" Target="../tags/opfFurnitureSlide${manifest.group}.xml"/></Relationships>`);
+    entries[part] = enc.encode(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?><p:tagLst xmlns:p="${NS}"><p:tag name="${TAG}" val="${encodeTextTag(manifest)}"/></p:tagLst>`);
+    entries[path] = enc.encode(xml);
+    entries[relPath] = enc.encode(rels);
+    types.push(`<Override PartName="/${part}" ContentType="application/vnd.openxmlformats-officedocument.presentationml.tags+xml"/>`);
+  }
+  if (types.length) entries['[Content_Types].xml'] = enc.encode(dec.decode(entries['[Content_Types].xml']).replace('</Types>', types.join('') + '</Types>'));
+}
+
+function readTags(container, relationships, entries) {
+  const tags = [];
+  let unreadable = false;
+  for (const link of array(container?.['p:tags'])) {
+    const rel = relationships.get(link['r:id']);
+    try {
+      check(rel?.type === REL && rel.targetMode !== 'External' && entries[rel.path], 'Missing tag relationship.');
+      tags.push(...array(parser.parse(dec.decode(entries[rel.path]))['p:tagLst']?.['p:tag']));
+    } catch { unreadable = true; }
+  }
+  return {tags: tags.filter(tag => tag.name?.toUpperCase() === TAG),
+    ambiguous: unreadable || tags.filter(tag => /^OPF_/i.test(tag.name)).length !== 1};
+}
+
+function validateManifest(manifest) {
+  check(manifest?.v === 1 && manifest.role === 'slide' && /^\d{1,10}$/.test(manifest.group), 'Invalid slide identity.');
+  check(object(manifest.definitions) && Object.keys(manifest.definitions).length > 0 && Object.keys(manifest.definitions).every(kind => kinds.includes(kind)), 'Invalid furniture definitions.');
+  check(Array.isArray(manifest.parts) && manifest.parts.length <= 36, 'Invalid furniture parts.');
+  const expected = new Map();
+  for (const [kind, definition] of Object.entries(manifest.definitions)) {
+    check(object(definition) && ['global', 'local'].includes(definition.scope), 'Invalid furniture scope.');
+    const value = definition.value;
+    check(value === false || object(value), 'Invalid furniture definition.');
+    if (value === false) continue;
+    check(Object.keys(value).every(zone => zones.includes(zone)), 'Invalid furniture zone.');
+    for (const [zone, content] of Object.entries(value)) {
+      check(object(content) && Object.keys(content).every(field => fields.includes(field)), 'Invalid furniture fields.');
+      for (const [field, flag] of Object.entries(content)) {
+        check(field === 'image' ? flag === 'native' : field === 'text' ? flag === 'literal' :
+          field === 'date' ? flag === false || flag === 'literal' : typeof flag === 'boolean', 'Invalid furniture field intent.');
+        if (flag !== false) expected.set(`${kind}.${zone}.${field}`, field === 'image' ? 'image' : 'text');
+      }
+    }
+  }
+  check(manifest.parts.length === expected.size, 'Incomplete furniture topology.');
+  for (const part of manifest.parts) {
+    check(object(part) && expected.get(key(part)) === part.type, 'Ambiguous furniture part.');
+    check(Number.isSafeInteger(part.count) && part.count >= 1 && part.count <= 10000 && (part.type !== 'image' || part.count === 1), 'Invalid furniture line count.');
+    expected.delete(key(part));
+  }
+  if (manifest.parts.some(part => part.field === 'organization')) check(typeof manifest.organizationId === 'string' && /^[a-zA-Z0-9_-]+$/.test(manifest.organizationId), 'Invalid organization identity.');
+}
+
+function readSlide(context, entries, slideIndex, report, taggedText) {
+  const {root, shapes, paragraphs, pictures, relationships, readPicture} = context;
+  const candidates = {};
+  const records = [];
+  let invalidRecord = false;
+  for (const [type, nodes, properties] of [['text', shapes, 'p:nvSpPr'], ['image', pictures, 'p:nvPicPr']]) {
+    for (const [index, node] of nodes.entries()) {
+      const result = readTags(node[properties]?.['p:nvPr']?.['p:custDataLst'], relationships, entries);
+      if (type === 'text' && result.tags.length) taggedText.add(index);
+      for (const tag of result.tags) try {
+        check(!result.ambiguous, 'Multiple identities on a furniture shape.');
+        records.push({type, index, data: decodeTextTag(tag.val)});
+      } catch { invalidRecord = true; }
+    }
+  }
+  const tags = readTags(root['p:cSld']?.['p:custDataLst'], relationships, entries);
+  if (!tags.tags.length && !records.length && !invalidRecord) return candidates;
+  let manifest;
+  try {
+    check(!tags.ambiguous && tags.tags.length === 1 && !invalidRecord, 'Missing or ambiguous furniture manifest/shape tags.');
+    manifest = decodeTextTag(tags.tags[0].val);
+    validateManifest(manifest);
+    for (const record of records) {
+      const data = record.data, part = manifest.parts[data?.part];
+      check(data?.v === 1 && data.group === manifest.group && Number.isSafeInteger(data.part) && part && data.role === record.type && part.type === record.type, 'Unmatched furniture identity.');
+    }
+  } catch (error) { report(slideIndex, error.message); return candidates; }
+  for (const kind of kinds) {
+    const definition = manifest.definitions[kind];
+    if (!definition) continue;
+    try {
+      const value = definition.value === false ? false : {};
+      if (value !== false) for (const zone of zones) if (definition.value[zone] !== undefined) {
+        value[zone] = Object.fromEntries(Object.entries(definition.value[zone]).filter(([, flag]) => flag === false));
+      }
+      const candidate = {scope: definition.scope, value, text: [], pictures: [], organizations: [], sections: []};
+      for (const [partIndex, part] of manifest.parts.entries()) {
+        if (part.kind !== kind) continue;
+        const group = records.filter(record => record.data.part === partIndex);
+        check(group.length === part.count, 'Incomplete or duplicated furniture part.');
+        if (part.type === 'image') {
+          const current = readPicture(pictures[group[0].index]);
+          check(current?.kind === 'image', 'Furniture image is no longer recoverable.');
+          value[part.zone].image = current.payload.image;
+          candidate.pictures.push(group[0].index);
+        } else {
+          const ordered = Array(part.count);
+          for (const record of group) {
+            const {line, count} = record.data;
+            check(count === part.count && Number.isSafeInteger(line) && line >= 0 && line < part.count && !ordered[line], 'Ambiguous furniture line.');
+            ordered[line] = record;
+          }
+          const text = sourceLineParagraphs(ordered, paragraphs)[0].text;
+          if (part.field === 'slideNumber') check(text === String(slideIndex + 1), 'Current slide number differs from its position; retain the visible number as ordinary text.');
+          if (part.field === 'section') candidate.sections.push(text);
+          if (part.field === 'organization') candidate.organizations.push({id: manifest.organizationId, name: text});
+          value[part.zone][part.field] = ['text', 'date'].includes(part.field) ? text : true;
+          candidate.text.push(...ordered.map(record => record.index));
+        }
+      }
+      check(new Set(candidate.text).size === candidate.text.length && new Set(candidate.pictures).size === candidate.pictures.length, 'Repeated furniture shape identity.');
+      candidates[kind] = candidate;
+    } catch (error) { report(slideIndex, `${kind}: ${error.message}`); }
+  }
+  return candidates;
+}
+
+// Reconcile metadata before consuming any shapes. Global inheritance is promoted
+// only when every slide has a valid definition/override and all inherited values
+// agree. A missing tag must never cause another slide's furniture to reappear.
+export function importFurniture(contexts, entries, onDiagnostic) {
+  const report = (index, message) => onDiagnostic?.({code: 'invalid-furniture-provenance', path: `slides.${index}.design`, message: `${message} Ordinary import retains current native content; no old source words are restored.`});
+  const taggedText = contexts.map(() => new Set());
+  const candidates = contexts.map((context, index) => readSlide(context, entries, index, report, taggedText[index]));
+  const organizations = candidates.flatMap(slide => Object.values(slide).flatMap(candidate => candidate.organizations));
+  if (organizations.some(item => !same(item, organizations[0]))) {
+    for (const [index, slide] of candidates.entries()) for (const kind of kinds) if (slide[kind]?.organizations.length) {
+      delete slide[kind]; report(index, `${kind}: Current organization metadata disagrees across repeated fields.`);
+    }
+  }
+  for (const [index, slide] of candidates.entries()) {
+    const sections = Object.values(slide).flatMap(candidate => candidate.sections);
+    if (sections.some(section => section !== sections[0])) for (const kind of kinds) if (slide[kind]?.sections.length) {
+      delete slide[kind]; report(index, `${kind}: Current section metadata disagrees on this slide.`);
+    }
+  }
+  const result = {design: {}, slides: candidates.map((slide, index) => {
+    const values = Object.values(slide), sections = values.flatMap(candidate => candidate.sections);
+    return {design: Object.fromEntries(Object.entries(slide).map(([kind, candidate]) => [kind, candidate.value])),
+      ...(sections.length ? {section: sections[0]} : {}),
+      text: new Set(values.flatMap(candidate => candidate.text)), pictures: new Set(values.flatMap(candidate => candidate.pictures)), taggedText: taggedText[index]};
+  })};
+  const validOrganizations = candidates.flatMap(slide => Object.values(slide).flatMap(candidate => candidate.organizations));
+  if (validOrganizations.length) result.organization = validOrganizations[0];
+  for (const kind of kinds) {
+    const inherited = candidates.map(slide => slide[kind]).filter(candidate => candidate?.scope === 'global');
+    if (inherited.length && candidates.every(slide => slide[kind]) && inherited.every(candidate => same(candidate.value, inherited[0].value))) {
+      result.design[kind] = inherited[0].value;
+      candidates.forEach((slide, index) => { if (slide[kind].scope === 'global') delete result.slides[index].design[kind]; });
+    }
+  }
+  candidates.forEach((slide, index) => { if (Object.keys(slide).length) onDiagnostic?.({code: 'furniture-import-reflow', path: `slides.${index}.design`, message: 'Complete furniture roles retain current text, source line boundaries, image content and unambiguous metadata. Native formatting, positioning, crop and other presentation metadata are not reconstructed; review the reflowed furniture.'}); });
+  return result;
+}

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;