@openpresentation/opf-pptx 0.11.8 → 0.12.0

package/dist/logo-provenance.js

@@ -1,4 +1,5 @@
 import {XMLParser} from 'fast-xml-parser';
+import {normalizeCrop, withoutSvgBlip} from './svg-image.js';
 import {decodeTextTag, encodeTextTag} from './code-provenance.js';
 import {pictureTransform} from './image-geometry.js';
 
@@ -25,8 +26,8 @@ export const LOGO_TAG = TAG;
 export const logoName = () => 'OPF logo';
 
 function blipFillIdentity(blipFill) {
-  const {['a:blip']: blip, ...rest} = blipFill ?? {};
-  const {['r:embed']: _embed, ...blipRest} = blip ?? {};
+  const {['a:blip']: blip, ...rest} = normalizeCrop(blipFill) ?? {};
+  const {['r:embed']: _embed, ...blipRest} = withoutSvgBlip(blip) ?? {};
   return {...rest, 'a:blip': blipRest};
 }
 
@@ -35,10 +36,11 @@ function blipFillIdentity(blipFill) {
  * left edge and vertically centered. A 90 degree EXIF orientation swaps the
  * frame's axes, so its visual width is the stored height.
  */
-export function logoFrame(metadata, box) {
+export function logoFrame(metadata, box, anchor = 'left') {
   const placed = pictureTransform(metadata, box, 'fit');
   const visualWidth = (metadata.orientation ?? 1) >= 5 ? placed.h : placed.w;
-  return {...placed, x: placed.x - (box.w - visualWidth) / 2};
+  // Right to left (RR-05): a cover logo sits at the top right, anchored to the box's right edge.
+  return {...placed, x: placed.x + (anchor === 'right' ? 1 : -1) * (box.w - visualWidth) / 2};
 }
 
 /**
@@ -60,7 +62,7 @@ export function placeLogos(entries, logos, metadataFor, fail) {
       const embed = picture.match(/<a:blip\b[^>]*r:embed="([^"]+)"/)?.[1];
       const metadata = metadataFor(part, embed);
       if (!metadata) fail(logo.path);
-      const placed = logoFrame(metadata, logo.box);
+      const placed = logoFrame(metadata, logo.box, logo.anchor);
       const attributes = `${placed.rotation ? ` rot="${placed.rotation * 60000}"` : ''}${placed.flipH ? ' flipH="1"' : ''}${placed.flipV ? ' flipV="1"' : ''}`;
       picture = picture.replace(/<a:xfrm\b[^>]*>[\s\S]*?<\/a:xfrm>/, `<a:xfrm${attributes}><a:off x="${emu(placed.x)}" y="${emu(placed.y)}"/><a:ext cx="${emu(placed.w)}" cy="${emu(placed.h)}"/></a:xfrm>`);
       picture = picture.replace(/<a:srcRect\b[^>]*\/>/, '');
@@ -162,7 +164,7 @@ export function importLogo(pictures, relationships, entries, slideIndex, readPic
     const manifest = decodeTextTag(own[0].val);
     if (manifest?.v !== 1 || manifest.slide !== `slides.${slideIndex}` || typeof manifest.path !== 'string' || !LOGO_PATH.test(manifest.path) || typeof manifest.variant !== 'string' || manifest.variant.length > 32) throw Error('Invalid logo manifest.');
     if (picture['p:nvPicPr']?.['p:cNvPr']?.name !== logoName()) throw Error('Logo identity changed.');
-    if (canonical(picture['p:spPr']) !== canonical(manifest.properties) || canonical(blipFillIdentity(picture['p:blipFill'])) !== canonical(manifest.blipFill)) throw Error('Logo geometry changed.');
+    if (canonical(picture['p:spPr']) !== canonical(manifest.properties) || canonical(blipFillIdentity(picture['p:blipFill'])) !== canonical(normalizeCrop(manifest.blipFill))) throw Error('Logo geometry changed.');
     const image = readPicture(picture)?.payload?.image;
     consumed.add(index);
     return {consumed, ...(typeof image?.src === 'string' ? {fallback: {path: manifest.path, image: {src: image.src, ...(typeof image.alt === 'string' ? {alt: image.alt} : {})}}} : {})};

package/dist/metric-provenance.js

@@ -14,7 +14,7 @@ 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');}
+export function attachMetricTags(entries,records,descriptions) {return attachTextTags(entries,records,TAG,'opfMetric','metric',{descriptions});}
 
 function validateManifest(manifest) {
   if (!validatePresentation({slides:[{metric:manifest.value}]}).valid) throw new Error('Invalid metric source.');
@@ -59,10 +59,13 @@ export function importMetricGroups(shapes,paragraphs,relationships,entries,repor
     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);
+    // RR-07: the trend arrow (role 'mark') is generated decoration: at most one, consumed with the group, never source text.
+    const marks=group.filter(item=>item.data.role==='mark'),members=group.filter(item=>item.data.role!=='mark');
+    if (marks.length>1) throw new Error('Duplicated metric trend mark.');
     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.');
+    if (members.length!==expected||new Set(members.map(item=>item.shape)).size!==expected) throw new Error('Incomplete or duplicated metric shapes.');
     const nativeLines=new Map();
-    for (const item of group) {
+    for (const item of members) {
       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);

package/dist/native-furniture.js

@@ -0,0 +1,297 @@
+// Native PowerPoint Header & Footer objects (RR-11, docs/native-header-footer.md).
+//
+// PowerPoint's Insert > Header & Footer owns three slide placeholders: a date
+// (`dt`), a footer text (`ftr`) and a slide number (`sldNum`). OPF footer parts
+// that map onto one of those become real placeholders on the slide, with matching
+// placeholders on the slide master and layouts and `p:hf` flags that say which of
+// them the deck uses, so the dialog shows the right state and "Apply to All"
+// works. Everything PowerPoint has no object for (header zones, organization,
+// section, socials, images, a second text/date/number part, multi-line text)
+// stays an ordinary tagged OPF furniture shape.
+//
+// Geometry never moves: a native slide placeholder carries the explicit `a:xfrm`
+// core composed (exactly the box the tagged shape had), so preview, export and the
+// parity harness agree. The master and layout placeholders are the defaults for
+// footers a user adds natively; they sit where the first slide's native part sits,
+// or where core would draw a default footer when no slide has one.
+
+import {XMLParser} from 'fast-xml-parser';
+import {DEFAULT_DATE_FORMAT, NATIVE_DATE_FIELDS, formatDate} from './furniture-fields.js';
+
+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 EMU = 9525;
+
+// idx values are PowerPoint's own: layouts number the three footer placeholders
+// 10, 11, 12 and the master 2, 3, 4; a slide placeholder points at its layout by idx.
+export const NATIVE_PLACEHOLDERS = Object.freeze({
+  dt: {field: 'date', name: 'Date Placeholder', sz: 'half', idx: 10, masterIdx: 2, zone: 'left', align: 'l'},
+  ftr: {field: 'text', name: 'Footer Placeholder', sz: 'quarter', idx: 11, masterIdx: 3, zone: 'center', align: 'ctr'},
+  sldNum: {field: 'slideNumber', name: 'Slide Number Placeholder', sz: 'quarter', idx: 12, masterIdx: 4, zone: 'right', align: 'r'},
+});
+const ORDER = ['dt', 'ftr', 'sldNum'];
+const phByField = {date: 'dt', text: 'ftr', slideNumber: 'sldNum'};
+export const isNativePlaceholderType = value => Object.hasOwn(NATIVE_PLACEHOLDERS, value);
+export const nativePlaceholderForField = field => phByField[field];
+const ZONES = ['left', 'center', 'right'];
+const ALIGN = {left: 'l', center: 'ctr', right: 'r'};
+
+/**
+ * Which accepted core parts of one slide become native placeholders: the first
+ * footer text, the first footer date and the first footer slide number whose
+ * text fits one accepted line. Returns Map<partIndex, 'dt'|'ftr'|'sldNum'>.
+ */
+export function nativeFurnitureParts(layout) {
+  const chosen = new Map(), taken = new Set();
+  for (const [index, part] of (layout?.parts ?? []).entries()) {
+    const ph = phByField[part.field];
+    if (part.kind !== 'footer' || part.type !== 'text' || !ph || taken.has(ph)) continue;
+    // One native shape holds one line; a part that wraps or breaks stays tagged shapes.
+    if (part.fit?.sourceLines?.length !== 1 || part.fit.lines?.length !== 1 || !part.text || part.links?.length) continue;
+    taken.add(ph);
+    chosen.set(index, ph);
+  }
+  return chosen;
+}
+
+/** Geometry of a default footer part for the master and layouts: its box and alignment in EMU. */
+export function defaultPlaceholderGeometry(part) {
+  if (!part?.box) return undefined;
+  return {x: Math.round(part.box.x * EMU), y: Math.round(part.box.y * EMU), cx: Math.round(part.box.width * EMU),
+    cy: Math.round((part.fit?.lineHeight ?? part.box.height) * EMU), algn: ALIGN[part.alignment] ?? 'l', sz: Math.round((part.fit?.fontSize ?? 16) * .75 * 100)};
+}
+
+const xmlEscape = value => String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const guid = (kind, n) => `{0F0F2701-${kind}-4000-8000-${n.toString(16).toUpperCase().padStart(12, '0')}}`;
+
+/**
+ * Turn the recorded generated shapes of each slide into placeholders. `records`
+ * maps a generated object name to its placeholder type. Runs after the tags are
+ * attached: the shape keeps its name, geometry, runs, fields and tags, and gains
+ * `p:ph` (a placeholder is a text shape the layout can supply defaults for).
+ * Returns the placeholders in use and the first geometry/alignment seen per type.
+ */
+export function attachNativePlaceholders(entries, records) {
+  const used = new Set(), first = new Map(), seen = new Set();
+  if (!records.size) return {used, first};
+  const slides = Object.keys(entries).filter(path => /^ppt\/slides\/slide\d+\.xml$/.test(path)).sort((a, b) => Number(a.match(/\d+/)[0]) - Number(b.match(/\d+/)[0]));
+  for (const path of slides) {
+    let changed = false;
+    const xml = dec.decode(entries[path]).replace(/<p:sp>[\s\S]*?<\/p:sp>/g, shape => {
+      const name = shape.match(/<p:cNvPr\b[^>]*\bname="([^"]+)"/)?.[1];
+      const ph = records.get(name);
+      if (!ph) return shape;
+      if (seen.has(name)) throw new Error('Duplicate generated native furniture shape.');
+      seen.add(name);
+      const properties = NATIVE_PLACEHOLDERS[ph];
+      if (!/<p:cNvSpPr\b[^>]*\/>/.test(shape)) throw new Error('Generated furniture shape has no plain shape properties.');
+      shape = shape.replace(/<p:cNvSpPr\b([^>]*)\/>/, '<p:cNvSpPr$1><a:spLocks noGrp="1"/></p:cNvSpPr>').replace(/<p:nvPr\s*\/>/, '<p:nvPr></p:nvPr>');
+      if (!shape.includes('<p:nvPr>')) throw new Error('Generated furniture shape has no native application properties.');
+      shape = shape.replace('<p:nvPr>', `<p:nvPr><p:ph type="${ph}" sz="${properties.sz}" idx="${properties.idx}"/>`);
+      used.add(ph);
+      if (!first.has(ph)) {
+        const geometry = shape.match(/<a:off x="(-?\d+)" y="(-?\d+)"\/><a:ext cx="(\d+)" cy="(\d+)"\/>/);
+        const algn = shape.match(/<a:pPr\b[^>]*\balgn="(\w+)"/)?.[1] ?? 'l';
+        if (geometry) first.set(ph, {x: Number(geometry[1]), y: Number(geometry[2]), cx: Number(geometry[3]), cy: Number(geometry[4]), algn});
+      }
+      changed = true;
+      return shape;
+    });
+    if (changed) entries[path] = enc.encode(xml);
+  }
+  if (seen.size !== records.size) throw new Error('Missing generated native furniture shapes.');
+  return {used, first};
+}
+
+// The text style a footer placeholder defaults to: the run properties of the deck's
+// first native footer shape (else its first furniture shape), read from the finished
+// slide (colors already theme references), so a footer added natively matches the
+// exported ones. A hyperlink belongs to one slide's relationships and is dropped.
+function furnitureRunStyle(slideXmls, names) {
+  for (const native of [true, false]) for (const xml of slideXmls) for (const [shape] of xml.matchAll(/<p:sp>[\s\S]*?<\/p:sp>/g)) {
+    const name = shape.match(/<p:cNvPr\b[^>]*\bname="(OPF furniture \d+ part \d+ line \d+)"/)?.[1];
+    if (!name || names.has(name) !== native) continue;
+    const run = shape.match(/<a:(?:r|fld)\b[^>]*>(<a:rPr\b[^>]*\/>|<a:rPr\b[^>]*>[\s\S]*?<\/a:rPr>)/)?.[1];
+    if (!run) continue;
+    const sz = run.match(/\bsz="(\d+)"/)?.[1];
+    const inner = (run.match(/^<a:rPr\b[^>]*>([\s\S]*)<\/a:rPr>$/)?.[1] ?? '')
+      .replace(/<a:hlink(Click|MouseOver)\b[^>]*\/>|<a:hlink(Click|MouseOver)\b[^>]*>[\s\S]*?<\/a:hlink(?:Click|MouseOver)>/g, '');
+    return {sz: sz ? Number(sz) : undefined, inner};
+  }
+  return undefined;
+}
+
+function placeholderGeometry(ph, info) {
+  const native = info.first.get(ph);
+  if (native) return native;
+  const fallback = info.defaults?.get(ph);
+  if (fallback) return fallback;
+  // No core geometry at all: PowerPoint's own proportions for a footer band.
+  const {width, height} = info.slideSize;
+  const band = Math.round(height * .0534), zone = Math.round(width * .26), left = Math.round(width * .07);
+  const at = {dt: left, ftr: Math.round(width * .37), sldNum: Math.round(width * .67)}[ph];
+  return {x: at, y: Math.round(height * .9), cx: zone, cy: band, algn: NATIVE_PLACEHOLDERS[ph].align};
+}
+
+function defRunProperties(style, geometry, extra) {
+  const sz = style?.sz ?? geometry.sz ?? 1200;
+  return `<a:defRPr sz="${sz}"${extra}>${style?.inner ?? ''}</a:defRPr>`;
+}
+
+function fieldRun(ph, id, text) {
+  if (ph === 'ftr') return '<a:endParaRPr lang="en-US"/>';
+  return `<a:fld id="${id}" type="${ph === 'dt' ? 'datetimeFigureOut' : 'slidenum'}"><a:rPr lang="en-US"/><a:t>${xmlEscape(text)}</a:t></a:fld><a:endParaRPr lang="en-US"/>`;
+}
+
+function masterShape(ph, order, info, style) {
+  const properties = NATIVE_PLACEHOLDERS[ph], geometry = placeholderGeometry(ph, info), id = order + 2;
+  return `<p:sp><p:nvSpPr><p:cNvPr id="${id}" name="${properties.name} ${id - 1}"/><p:cNvSpPr><a:spLocks noGrp="1"/></p:cNvSpPr>` +
+    `<p:nvPr><p:ph type="${ph}" sz="${properties.sz}" idx="${properties.masterIdx}"/></p:nvPr></p:nvSpPr>` +
+    `<p:spPr><a:xfrm><a:off x="${geometry.x}" y="${geometry.y}"/><a:ext cx="${geometry.cx}" cy="${geometry.cy}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></p:spPr>` +
+    `<p:txBody><a:bodyPr vert="horz" lIns="0" tIns="0" rIns="0" bIns="0" rtlCol="0" anchor="t"/>` +
+    `<a:lstStyle><a:lvl1pPr algn="${geometry.algn}">${defRunProperties(style, geometry, '')}</a:lvl1pPr></a:lstStyle>` +
+    `<a:p>${fieldRun(ph, guid('0001', order + 1), ph === 'dt' ? info.dateText : '‹#›')}</a:p></p:txBody></p:sp>`;
+}
+
+function layoutShape(ph, order, info) {
+  const properties = NATIVE_PLACEHOLDERS[ph], id = order + 2;
+  return `<p:sp><p:nvSpPr><p:cNvPr id="${id}" name="${properties.name} ${id - 1}"/><p:cNvSpPr><a:spLocks noGrp="1"/></p:cNvSpPr>` +
+    `<p:nvPr><p:ph type="${ph}" sz="${properties.sz}" idx="${properties.idx}"/></p:nvPr></p:nvSpPr><p:spPr/>` +
+    `<p:txBody><a:bodyPr/><a:lstStyle/><a:p>${fieldRun(ph, guid('0002', order + 1), ph === 'dt' ? info.dateText : '‹#›')}</a:p></p:txBody></p:sp>`;
+}
+
+const flag = value => value ? '1' : '0';
+const headerFooterFlags = used => `<p:hf sldNum="${flag(used.has('sldNum'))}" hdr="0" ftr="${flag(used.has('ftr'))}" dt="${flag(used.has('dt'))}"/>`;
+
+function insertPlaceholders(xml, shapes, part) {
+  if (/<p:ph\b[^>]*\btype="(?:dt|ftr|sldNum)"/.test(xml)) throw new Error(`${part} already has footer placeholders.`);
+  const end = xml.indexOf('</p:spTree>');
+  if (end < 0) throw new Error(`${part} has no shape tree.`);
+  return xml.slice(0, end) + shapes + xml.slice(end);
+}
+
+/**
+ * The master, layout and notes master half of the native header/footer, written
+ * into the finished package. `read`/`write` access parts by path.
+ *
+ * - Slide master and layouts: `dt`, `ftr` and `sldNum` placeholders and a
+ *   `p:hf` whose flags say which the deck uses (`hdr` is 0: slides have no
+ *   header placeholder).
+ * - Notes master: PowerPoint's own placeholders stay; `p:hf` records that the
+ *   notes pages carry a page number only, as the generated notes slides do.
+ */
+export function writeNativeMasters(paths, read, write, info) {
+  const slideXmls = paths.filter(path => /^ppt\/slides\/slide\d+\.xml$/.test(path)).sort((a, b) => Number(a.match(/\d+/)[0]) - Number(b.match(/\d+/)[0])).map(path => dec.decode(read(path)));
+  const style = furnitureRunStyle(slideXmls, info.names);
+  const flags = headerFooterFlags(info.used);
+  for (const path of paths.filter(path => /^ppt\/slideMasters\/slideMaster\d+\.xml$/.test(path))) {
+    let xml = dec.decode(read(path));
+    xml = insertPlaceholders(xml, ORDER.map((ph, order) => masterShape(ph, order, info, style)).join(''), path);
+    xml = /<p:hf\b[^>]*\/>/.test(xml) ? xml.replace(/<p:hf\b[^>]*\/>/, flags) : xml.replace(/<p:txStyles\b/, `${flags}<p:txStyles`);
+    if (!xml.includes(flags)) throw new Error('Slide master header/footer flags could not be written.');
+    write(path, enc.encode(xml));
+  }
+  for (const path of paths.filter(path => /^ppt\/slideLayouts\/slideLayout\d+\.xml$/.test(path))) {
+    let xml = dec.decode(read(path));
+    xml = insertPlaceholders(xml, ORDER.map((ph, order) => layoutShape(ph, order, info)).join(''), path);
+    if (!xml.includes('</p:clrMapOvr>')) throw new Error('Slide layout has no color map override.');
+    xml = /<p:hf\b[^>]*\/>/.test(xml) ? xml.replace(/<p:hf\b[^>]*\/>/, flags) : xml.replace('</p:clrMapOvr>', `</p:clrMapOvr>${flags}`);
+    write(path, enc.encode(xml));
+  }
+  for (const path of paths.filter(path => /^ppt\/notesMasters\/notesMaster\d+\.xml$/.test(path))) {
+    let xml = dec.decode(read(path));
+    const notes = '<p:hf hdr="0" ftr="0" dt="0"/>';
+    xml = /<p:hf\b[^>]*\/>/.test(xml) ? xml.replace(/<p:hf\b[^>]*\/>/, notes) : xml.replace(/(<p:clrMap\b[^>]*\/>)/, `$1${notes}`);
+    if (!xml.includes(notes)) throw new Error('Notes master header/footer flags could not be written.');
+    write(path, enc.encode(xml));
+  }
+}
+
+export const nativeDateText = date => formatDate(date ?? '', DEFAULT_DATE_FORMAT) ?? formatDate('2026-01-01', DEFAULT_DATE_FORMAT);
+
+// ---------------------------------------------------------------------------
+// Import
+// ---------------------------------------------------------------------------
+
+const dateFormatForField = Object.fromEntries(Object.entries(NATIVE_DATE_FIELDS).map(([format, type]) => [type, format]));
+const REL_LAYOUT = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout';
+const REL_MASTER = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideMaster';
+
+function xfrmBounds(xfrm) {
+  const x = Number(xfrm?.['a:off']?.x), y = Number(xfrm?.['a:off']?.y), cx = Number(xfrm?.['a:ext']?.cx), cy = Number(xfrm?.['a:ext']?.cy);
+  return [x, y, cx, cy].every(Number.isFinite) && cx > 0 ? {x, y, cx, cy} : undefined;
+}
+
+// A placeholder without its own xfrm inherits it: slide -> layout (same idx, else same
+// type) -> master (same type). Parsed layout/master trees are cached per package read.
+function inheritedBounds(shape, ph, slidePath, relationships, readPart) {
+  const own = xfrmBounds(shape['p:spPr']?.['a:xfrm']);
+  if (own) return own;
+  const index = shape['p:nvSpPr']?.['p:nvPr']?.['p:ph']?.idx;
+  const find = (path, byIdx) => {
+    const tree = readPart(path)?.[path.includes('slideMaster') ? 'p:sldMaster' : 'p:sldLayout']?.['p:cSld']?.['p:spTree'];
+    const candidates = array(tree?.['p:sp']).filter(candidate => candidate['p:nvSpPr']?.['p:nvPr']?.['p:ph']?.type === ph);
+    const match = (byIdx && index !== undefined ? candidates.find(candidate => candidate['p:nvSpPr']['p:nvPr']['p:ph'].idx === index) : undefined) ?? candidates[0];
+    return match ? xfrmBounds(match['p:spPr']?.['a:xfrm']) : undefined;
+  };
+  const layout = [...relationships(slidePath).values()].find(relationship => relationship.type === REL_LAYOUT)?.path;
+  if (!layout) return undefined;
+  const fromLayout = find(layout, true);
+  if (fromLayout) return fromLayout;
+  const master = [...relationships(layout).values()].find(relationship => relationship.type === REL_MASTER)?.path;
+  return master ? find(master, false) : undefined;
+}
+
+function zoneOf(bounds, slideWidth, fallback) {
+  if (!bounds || !(slideWidth > 0)) return fallback;
+  const center = (bounds.x + bounds.cx / 2) / slideWidth;
+  return center < 1 / 3 ? 'left' : center > 2 / 3 ? 'right' : 'center';
+}
+
+/**
+ * The footer one slide's native placeholders describe. `claimed` is the set of
+ * shape indexes OPF provenance already consumed or reserved. Returns
+ * {fields: [{zone, field, value, settings, index}], skipped: [index]} where `value`
+ * is the OPF field value and `settings` the zone's `dateFormat`/`slideNumberFormat`.
+ */
+export function readNativePlaceholders(context, claimed, relationships, readPart) {
+  const fields = [];
+  for (const [index, shape] of context.shapes.entries()) {
+    const ph = shape['p:nvSpPr']?.['p:nvPr']?.['p:ph']?.type;
+    if (!isNativePlaceholderType(ph) || claimed.has(index)) continue;
+    const paragraphs = context.paragraphs[index] ?? [];
+    const text = paragraphs.map(paragraph => paragraph.text).join('\n');
+    const nativeFields = paragraphs.flatMap(paragraph => paragraph.fields ?? []);
+    const zone = zoneOf(inheritedBounds(shape, ph, context.path, relationships, readPart), context.slideWidth, NATIVE_PLACEHOLDERS[ph].zone);
+    const properties = NATIVE_PLACEHOLDERS[ph];
+    if (ph === 'sldNum') {
+      const live = nativeFields.filter(field => field.type === 'slidenum');
+      if (live.length !== 1) continue;
+      const at = text.indexOf(live[0].text);
+      const format = at < 0 ? undefined : text.slice(0, at) + '{current}' + text.slice(at + live[0].text.length);
+      fields.push({index, zone, field: properties.field, value: true, settings: format && format !== '{current}' ? {slideNumberFormat: format} : {}});
+    } else if (ph === 'dt') {
+      if (!text.trim()) continue;
+      const pattern = nativeFields.length === 1 && nativeFields[0].text === text ? dateFormatForField[nativeFields[0].type] : undefined;
+      if (pattern) fields.push({index, zone, field: properties.field, value: true, settings: pattern === DEFAULT_DATE_FORMAT ? {} : {dateFormat: pattern}});
+      // A fixed date, or a field with no OPF pattern (a time, the master's datetimeFigureOut), keeps its current words.
+      else fields.push({index, zone, field: properties.field, value: text, settings: {}});
+    } else {
+      if (!text.trim()) continue;
+      fields.push({index, zone, field: properties.field, value: text, settings: {}});
+    }
+  }
+  return fields;
+}
+
+/** The OPF footer value for native placeholder fields: zones keyed left/center/right. */
+export function footerValue(fields) {
+  const value = {};
+  for (const item of fields) {
+    value[item.zone] ??= {};
+    value[item.zone][item.field] = item.value;
+    Object.assign(value[item.zone], item.settings);
+  }
+  return Object.fromEntries(ZONES.filter(zone => value[zone]).map(zone => [zone, value[zone]]));
+}

package/dist/native-text-style.js

@@ -5,6 +5,18 @@ const boolean = value => ['1','true','on'].includes(value) ? true : ['0','false'
 
 const themeFamilies = context => ['a:majorFont', 'a:minorFont'].map(key => context.fonts?.[key]?.['a:latin']?.typeface?.trim().toLowerCase()).filter(Boolean);
 
+// A run painted with a bare theme slot (a:schemeClr, no color transform) remembers the slot as the OPF color name: the
+// transient `_opfScheme` marker is read, and always removed, by restoreRunColors (run-colors.js) once the document's own
+// colour scheme can confirm the slot holds that colour.
+const OPF_SLOTS = {dk1: 'dark1', lt1: 'light1', dk2: 'dark2', lt2: 'light2', hlink: 'hyperlink', folHlink: 'followedHyperlink', accent1: 'accent1', accent2: 'accent2', accent3: 'accent3', accent4: 'accent4', accent5: 'accent5', accent6: 'accent6'};
+function nativeSchemeSlot(fill, context) {
+  const node = fill?.['a:schemeClr'];
+  if (!node || Array.isArray(node) || Object.keys(fill).length !== 1 || Object.keys(node).some(key => key !== 'val') || typeof node.val !== 'string') return undefined;
+  // Own keys only: a slot name from the package (`__proto__`, `constructor`) must never reach an inherited property.
+  const mapping = context?.mapping, slot = mapping && Object.hasOwn(mapping, node.val) ? mapping[node.val] : node.val;
+  return typeof slot === 'string' && Object.hasOwn(OPF_SLOTS, slot) ? OPF_SLOTS[slot] : undefined;
+}
+
 export function nativeRunStyle(properties, context, relationships, report, kind = 'table') {
   const result = {};
   for (const [native, opf] of [['b','bold'], ['i','italic']]) {
@@ -42,7 +54,11 @@ export function nativeRunStyle(properties, context, relationships, report, kind
   }
   if (properties['a:solidFill']) {
     const color = readBackgroundColor(properties['a:solidFill'], context);
-    if (color) result.color = color.hex + (color.alpha < 1 ? Math.round(color.alpha * 255).toString(16).padStart(2, '0').toUpperCase() : '');
+    if (color) {
+      result.color = color.hex + (color.alpha < 1 ? Math.round(color.alpha * 255).toString(16).padStart(2, '0').toUpperCase() : '');
+      const slot = color.alpha === 1 ? nativeSchemeSlot(properties['a:solidFill'], context) : undefined;
+      if (slot) result._opfScheme = slot;
+    }
     else report(`unsupported-${kind}-text-color`, 'The native text color or its transforms could not be resolved.');
   } else if (properties['a:noFill']) {
     result.color = '#00000000';

package/dist/numbered-list.js

@@ -0,0 +1,114 @@
+// RR-33: numbered lists. OPF `numbering` (a style, a start and a suffix per list level) is written as native
+// `a:buAutoNum` and read back from it.
+//
+// Export: every marker line of a measured list is its own text box (see addMeasuredList), so each carries the number
+// core counted as `startAt`; there is nothing for PowerPoint to count across boxes.
+// Import: `a:buAutoNum` of a native paragraph is read with PowerPoint's own counting (consecutive paragraphs of one
+// level and one scheme count up from `startAt`; a paragraph of another scheme or start begins a new sequence; a
+// shallower or unnumbered paragraph ends the deeper sequences), then the numbers of the whole list are expressed as the
+// shortest `numbering` plus per-entry `start` values that reproduce them.
+
+const STYLES = ['arabic', 'roman-upper', 'roman-lower', 'alpha-upper', 'alpha-lower'];
+const STYLE_STEMS = {arabic: 'arabic', 'roman-upper': 'romanUc', 'roman-lower': 'romanLc', 'alpha-upper': 'alphaUc', 'alpha-lower': 'alphaLc'};
+const SUFFIX_TAILS = {period: 'Period', paren: 'ParenR', 'paren-both': 'ParenBoth'};
+
+/** The `a:buAutoNum@type` scheme of an OPF style and suffix. */
+export const autoNumScheme = (style, suffix = 'period') => `${STYLE_STEMS[style]}${SUFFIX_TAILS[suffix]}`;
+
+const SCHEMES = new Map(STYLES.flatMap(style => Object.keys(SUFFIX_TAILS).map(suffix => [autoNumScheme(style, suffix), {style, suffix}])));
+/** OPF style and suffix of a native scheme, or `undefined` for a scheme OPF has no equivalent for. */
+export const schemeNumbering = type => SCHEMES.get(type);
+
+/** `startAt` of a native auto-number: an integer from 1 to 32767, default 1. */
+export function autoNumStart(value) {
+  if (value === undefined || value === '') return 1;
+  const number = Number(value);
+  return Number.isInteger(number) && number >= 1 && number <= 32767 ? number : undefined;
+}
+
+/**
+ * The number each paragraph of one native shape displays, by PowerPoint's counting. `paragraphs` are
+ * `{level, autoNum?: {type, startAt}}`; returns the displayed numbers (`undefined` for an unnumbered paragraph).
+ */
+export function displayedNumbers(paragraphs) {
+  const sequences = [];
+  return paragraphs.map(paragraph => {
+    const level = Number.isInteger(paragraph.level) && paragraph.level >= 0 ? paragraph.level : 0;
+    if (!paragraph.autoNum) { sequences.length = Math.min(sequences.length, level); return undefined; }
+    const start = autoNumStart(paragraph.autoNum.startAt) ?? 1, type = paragraph.autoNum.type ?? 'arabicPeriod';
+    const current = sequences[level];
+    const value = current && current.type === type && current.start === start ? current.value + 1 : start;
+    sequences[level] = {type, start, value};
+    sequences.length = level + 1;
+    return value;
+  });
+}
+
+const entryOf = ({style, start, suffix}) => {
+  const fields = {...(style !== 'arabic' ? {style} : {}), ...(start !== 1 ? {start} : {}), ...(suffix !== 'period' ? {suffix} : {})};
+  const names = Object.keys(fields);
+  if (!names.length) return 'arabic';
+  return names.length === 1 && names[0] === 'style' ? style : fields;
+};
+
+/**
+ * The OPF numbering of a native list: `paragraphs` are `{level, number?: {type, value}}` in reading order (`number` is the
+ * displayed number and its scheme). Returns `{numbering, starts, diagnostics}`: `numbering` is the shortest authored form
+ * (`undefined` when the list is not numbered), `starts` maps a paragraph index to the entry `start` that restores its
+ * number, and `diagnostics` lists what could not be represented.
+ */
+export function deriveListNumbering(paragraphs) {
+  const diagnostics = [];
+  const numbered = paragraphs.filter(paragraph => paragraph.number);
+  if (!numbered.length) return {numbering: undefined, starts: new Map(), diagnostics};
+  if (numbered.length !== paragraphs.length) {
+    diagnostics.push({code: 'numbering-mixed', message: 'A list that mixes numbered and bulleted or plain paragraphs has no OPF equivalent (numbering applies to the whole list); it imports as bullets.'});
+    return {numbering: undefined, starts: new Map(), diagnostics};
+  }
+  const levels = [];
+  let unknown = false, mixedStyles = false;
+  for (const paragraph of numbered) {
+    const level = paragraph.level ?? 0;
+    const known = schemeNumbering(paragraph.number.type);
+    if (!known) { unknown = true; }
+    const resolved = known ?? {style: 'arabic', suffix: 'period'};
+    if (!levels[level]) levels[level] = {...resolved, start: paragraph.number.value};
+    else if (levels[level].style !== resolved.style || levels[level].suffix !== resolved.suffix) mixedStyles = true;
+  }
+  if (unknown) diagnostics.push({code: 'numbering-scheme-adapted', message: 'A native numbering scheme OPF has no equivalent for (an East Asian, Hebrew or Arabic scheme, or a bullet-only scheme) imports as arabic with a period.'});
+  if (mixedStyles) diagnostics.push({code: 'numbering-style-adapted', message: 'Entries of one list level use different native numbering schemes; OPF numbers a level in one style, so the first entry\'s style is used for the level.'});
+  const filled = [];
+  for (let level = 0; level < levels.length; level++) filled[level] = levels[level] ?? {...(filled[level - 1] ?? {style: 'arabic', suffix: 'period'}), start: 1};
+  // Per-entry starts: restart wherever the displayed number is not what counting gives.
+  const counters = [], starts = new Map();
+  paragraphs.forEach((paragraph, index) => {
+    const level = paragraph.level ?? 0, value = paragraph.number.value;
+    const natural = counters[level] === undefined ? filled[level].start : counters[level] + 1;
+    if (natural !== value) starts.set(index, value);
+    counters[level] = value;
+    counters.length = level + 1;
+  });
+  // The last entry repeats for deeper levels, so trailing equal entries are redundant.
+  const same = (a, b) => a.style === b.style && a.suffix === b.suffix && a.start === b.start;
+  while (filled.length > 1 && same(filled.at(-1), filled.at(-2))) filled.pop();
+  const entries = filled.map(entryOf);
+  return {numbering: entries.length === 1 ? entries[0] : entries, starts, diagnostics};
+}
+
+/** A canonical form of an authored `numbering`, for comparing two spellings of the same numbering. */
+export function canonicalNumbering(numbering) {
+  const list = Array.isArray(numbering) ? numbering : [numbering];
+  const resolved = list.map(entry => typeof entry === 'string' ? {style: entry, start: 1, suffix: 'period'} : {style: entry?.style ?? 'arabic', start: entry?.start ?? 1, suffix: entry?.suffix ?? 'period'});
+  while (resolved.length > 1 && JSON.stringify(resolved.at(-1)) === JSON.stringify(resolved.at(-2))) resolved.pop();
+  return JSON.stringify(resolved);
+}
+
+/**
+ * Add `autoNum` (the paragraph's `a:buAutoNum` attributes) and the displayed `number` ({type, value}) to the numbered
+ * paragraphs of one native shape. Paragraphs without a native auto-number are returned unchanged.
+ */
+export function withDisplayedNumbers(paragraphs) {
+  if (!paragraphs.some(paragraph => paragraph.autoNum)) return paragraphs;
+  const numbers = displayedNumbers(paragraphs);
+  return paragraphs.map((paragraph, index) => numbers[index] === undefined ? paragraph : {...paragraph, number: {type: paragraph.autoNum.type ?? 'arabicPeriod', value: numbers[index]}});
+}

package/dist/run-colors.js

@@ -0,0 +1,118 @@
+// Run colours named by a reference (RR-08).
+//
+// A TextRun colour may be a ColorRef: a `var:` variable, a colour-scheme slot ('accent2') or a role ('primary'). The
+// export resolves it (or writes the theme slot that holds the same colour) and PowerPoint has no field for the name, so
+// import used to return only the resolved hex. Two sources can name the reference again, and both are gated by the
+// imported document's own colour resolution: a name is restored only while it still resolves to the run's current colour,
+// so a colour edited in PowerPoint keeps its edited value and nothing is invented.
+//
+// 1. Provenance (full mode): OPF_SLIDE_V1 `colors` = {n, at: [[slot, reference], ...]}. The slots are the text runs of the
+//    slide's content in a fixed order (slideRunSlots: text runs, list item and description runs; regions by name, then
+//    blocks and groups in order, or the root payload). `n` is how many slots the authored slide had; the record is used only
+//    when the imported slide has exactly that many, so a run can never be matched to another. It holds reference names
+//    only, never words.
+// 2. A slide with no OPF record (plain PPTX): a run painted with a bare a:schemeClr (no colour transform) names that
+//    theme slot ('accent2', 'dark1', 'hyperlink'), restored when the document's colour scheme holds that exact colour for
+//    the slot. The exporter writes schemeClr only where the theme holds the colour, so this is the same convention.
+
+import {ROOT_PAYLOAD_FIELDS, REGION_KEYS} from './content-topology.js';
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const REGION_KEY_SET = new Set(REGION_KEYS);
+const isGroup = block => object(block) && (block.type === 'group' || (block.type === undefined && Array.isArray(block.blocks)));
+export const MAX_COLOR_SLOTS = 100000;
+
+// A reference name: the schema's ColorRef forms other than a hex literal.
+const REFERENCE = /^(?:var:[a-z][a-z0-9-]*|accent[1-6]|dark[12]|light[12]|hyperlink|followedHyperlink|primary|secondary|accent|background|surface|text|textSecondary)$/;
+export const isColorReference = value => typeof value === 'string' && REFERENCE.test(value);
+
+/** The payload objects of a slide in the fixed traversal order: regions (by name), else blocks (groups depth first), else the slide's root payload. */
+function* leaves(slide) {
+  const walk = function* (block) {
+    if (!object(block)) return;
+    if (isGroup(block)) { for (const child of Array.isArray(block.blocks) ? block.blocks : []) yield* walk(child); return; }
+    yield block;
+  };
+  const regions = Object.keys(slide).filter(key => REGION_KEY_SET.has(key) && object(slide[key])).sort();
+  if (regions.length) { for (const key of regions) yield* walk(slide[key]); return; }
+  if (Array.isArray(slide.blocks)) { for (const block of slide.blocks) yield* walk(block); return; }
+  yield slide;
+}
+
+/** The text runs of the slide's text and list payloads, in order: an object (a run) or null (a plain string). */
+export function slideRunSlots(slide) {
+  const slots = [];
+  const runs = value => {
+    if (Array.isArray(value)) for (const run of value) slots.push(object(run) ? run : null);
+    else if (typeof value === 'string') slots.push(null);
+  };
+  for (const leaf of leaves(slide)) {
+    for (const field of ROOT_PAYLOAD_FIELDS) {
+      const value = leaf[field];
+      if (field === 'text') { if (Array.isArray(value)) runs(value); }
+      else if ((field === 'items' || field === 'bullets') && Array.isArray(value)) {
+        for (const item of value) {
+          if (Array.isArray(item) || typeof item === 'string') runs(item);
+          else if (object(item)) { runs(item.text); runs(item.description); }
+        }
+      }
+    }
+  }
+  return slots;
+}
+
+/** The record stored for an authored slide, or undefined when no run names a reference. */
+export function runColorRecord(slide) {
+  const slots = slideRunSlots(slide);
+  if (slots.length > MAX_COLOR_SLOTS) return undefined;
+  const at = [];
+  slots.forEach((run, index) => { if (run && isColorReference(run.color)) at.push([index, run.color]); });
+  return at.length ? {n: slots.length, at} : undefined;
+}
+
+/** Throws when `value` is not a well-formed colours record. */
+export function validateRunColors(value) {
+  if (!object(value) || !Number.isSafeInteger(value.n) || value.n < 1 || value.n > MAX_COLOR_SLOTS || !Array.isArray(value.at) || !value.at.length || value.at.length > value.n) throw Error('Invalid run colours record.');
+  let previous = -1;
+  for (const entry of value.at) {
+    if (!Array.isArray(entry) || entry.length !== 2 || !Number.isSafeInteger(entry[0]) || entry[0] <= previous || entry[0] >= value.n || !isColorReference(entry[1])) throw Error('Invalid run colour entry.');
+    previous = entry[0];
+  }
+  return value;
+}
+
+function* markedRuns(value) {
+  if (Array.isArray(value)) { for (const item of value) yield* markedRuns(item); return; }
+  if (!object(value)) return;
+  if (Object.hasOwn(value, '_opfScheme')) yield value;
+  for (const item of Object.values(value)) if (item !== null && typeof item === 'object') yield* markedRuns(item);
+}
+
+/**
+ * Restore run colour references on `slides` (the imported document's slides). `info[i]` is
+ * {record, structure, content}: the stored OPF_SLIDE_V1 value, whether the slide's arrangement matches it and whether its
+ * content structure was restored from it, or undefined for an untagged slide. `resolve(slide, name)` returns the '#RRGGBB'
+ * the name resolves to in the document (or undefined). Every transient `_opfScheme` marker is removed.
+ */
+export function restoreRunColors(slides, info, resolve, report) {
+  slides.forEach((slide, index) => {
+    const tag = info[index];
+    const marked = [...markedRuns(slide)];
+    const restoreName = (run, name) => {
+      const hex = typeof run.color === 'string' && /^#[0-9a-f]{6}$/i.test(run.color) ? run.color.toUpperCase() : undefined;
+      if (hex && resolve(slide, name)?.toUpperCase() === hex) run.color = name;
+    };
+    if (tag?.record?.colors) {
+      const {n, at} = tag.record.colors;
+      // When the content form was not restored its own diagnostic says why, and the slots cannot be aligned.
+      if (tag.structure && tag.content) {
+        const slots = slideRunSlots(slide);
+        if (slots.length !== n) report({code: 'color-reference-changed', path: `slides.${index}`, message: `The slide's text runs no longer match the stored colour references (${slots.length} runs now, ${n} at export), so the named run colours of slides.${index} (variables, scheme slots and roles) were not restored; the runs keep their resolved colours.`});
+        else for (const [slot, name] of at) if (slots[slot]) restoreName(slots[slot], name);
+      }
+    } else if (!tag?.record) {
+      for (const run of marked) if (typeof run._opfScheme === 'string') restoreName(run, run._opfScheme);
+    }
+    for (const run of marked) delete run._opfScheme;
+  });
+}