@openpresentation/opf-pptx 0.11.9 → 0.12.1

package/dist/content-topology.js

@@ -19,14 +19,26 @@
 //            | {form: 'blocks', blocks: Node[]}
 //            | {form: 'regions', regions: {[key]: Node}}   // key = promoted region key
 //   Node     = {t: 'group', id?, ext?, comp?, typed?, blocks: Node[]}
-//            | {t: 'leaf', k, id?, ext?, typed?, box?, lines?}   // box = [x, y, w, h] reference px, 1 decimal
+//            | {t: 'leaf', k, id?, ext?, typed?, bullets?, box?, lines?, wrap?}   // box = [x, y, w, h] reference px, 1 decimal
 //   typed = true when the authored block spelled out its `type`
+//   bullets = true when the authored list block used the `bullets` key (import names every list `items`), also under `type: 'text'`
 //   lines = N (>= 2) when a rich-text `text` payload exported as N native line
 //           shapes that are soft wraps of one paragraph (no hard break between
 //           them); import joins those N imported lines back into the one payload
+//   wrap  = {lines: N, gaps} instead of `lines` when any line break was a hard
+//           break (RR-09; an importer before RR-09 ignores `wrap` and keeps the
+//           flat blocks rather than join lines without their separators). The
+//           N native line shapes rebuild the authored runs exactly once joined
+//           with gaps, the N - 1 separators between them: '' for a soft wrap
+//           (nothing deleted), otherwise the whitespace the break held ("\n",
+//           "\r\n", "\n\n" for a blank line, trimmed spaces); [whitespace, k]
+//           when the first k characters end the previous line's last run (the
+//           rest start the next one)
 //
-// Native line shapes of rich text carry no names or tags, so the soft wraps are
-// recorded here as a count; a wrapped payload with any hard break is not marked.
+// Native line shapes of rich text carry no names or tags, so the lines are
+// recorded here as a count and the separators as whitespace only: never a word.
+// A payload whose runs cannot be shown to rebuild from the lines and separators
+// exactly is not marked, and import keeps the flat blocks and its diagnostic.
 //
 // Tags are untrusted input: every field is type-, count- and depth-checked
 // before use, and the rebuilt slide still has to validate with the document.
@@ -55,37 +67,154 @@ const kindOfField = field => field === 'items' || field === 'bullets' ? 'list' :
 const isGroup = block => object(block) && (block.type === 'group' || (block.type === undefined && Array.isArray(block.blocks)));
 const round1 = value => Math.round(value * 10) / 10;
 export const MAX_WRAPPED_LINES = 1000;
+// A break between two native lines holds only spaces, tabs and line endings: never words.
+export const MAX_GAP_LENGTH = 256;
+const GAP_CHARACTER = /^[ \t\r\n]$/;
+const GAP_TEXT = /^[ \t\r\n]*$/;
+
+const styleKey = run => JSON.stringify(Object.keys(run).filter(key => key !== 'text').sort().map(key => [key, run[key]]));
+const sameRunStyle = (a, b) => styleKey(a) === styleKey(b);
+// Adjacent runs that differ only in text are one run: a wrap or a break cut them apart, nothing else did.
+function normalizeRuns(runs) {
+  const merged = [];
+  for (const run of runs) {
+    if (!run.text) continue;
+    const last = merged.at(-1);
+    if (last && sameRunStyle(last, run)) last.text += run.text;
+    else merged.push({...run});
+  }
+  return merged;
+}
+const gapParts = gap => Array.isArray(gap) ? {text: gap[0], keep: gap[1]} : {text: gap ?? '', keep: 0};
 
 /**
- * The number of native line shapes a rich-text `text` item exported as, when
- * those lines are consecutive soft wraps of the authored runs: the line
- * fragments, concatenated in order, are exactly the concatenated run text, so
- * no line boundary stands for a hard break (a newline, a blank line, collapsed
- * or dropped characters). Undefined for a single line or when that cannot be
- * shown: nothing then marks the leaf and import keeps the separate blocks.
+ * The lines' text joined in order. `gaps[i]` is what separates line i from line
+ * i + 1: '' for a soft wrap, the whitespace a hard break held otherwise. A gap
+ * is a string (it starts the next line's first run) or [text, keep] (its first
+ * `keep` characters end the previous line's last run). Runs are never invented
+ * or dropped; at a seam the last run of one line and the first of the next
+ * merge when they differ only in text (a run the wrap cut in two), the same
+ * way a rejoined list does.
  */
-export function softWrappedLines(item) {
-  const lines = item?.text?.richLines;
-  if (item?.field !== 'text' || !Array.isArray(lines) || lines.length < 2 || lines.length > MAX_WRAPPED_LINES) return undefined;
-  const runs = Array.isArray(item.value) ? item.value : typeof item.value === 'string' ? [item.value] : null;
-  if (!runs) return undefined;
-  let source = '';
-  for (const run of runs) {
+export function joinWrappedText(parts, gaps = []) {
+  if (parts.every(part => typeof part === 'string')) return parts.reduce((text, part, index) => text + (index ? gapParts(gaps[index - 1]).text : '') + part, '');
+  const joined = [];
+  parts.forEach((part, index) => {
+    const runs = (typeof part === 'string' ? [{text: part}] : part).map(run => ({...run}));
+    if (index) {
+      const {text, keep} = gapParts(gaps[index - 1]);
+      const last = joined.at(-1);
+      if (last && keep) last.text += text.slice(0, keep);
+      if (text.length > keep && runs.length) runs[0].text = text.slice(keep) + runs[0].text;
+    }
+    runs.forEach((run, position) => {
+      const last = joined.at(-1);
+      if (position === 0 && last && sameRunStyle(last, run)) last.text += run.text;
+      else joined.push(run);
+    });
+  });
+  return joined;
+}
+
+/**
+ * Walk the native line fragments of `value` (a string or authored runs): the character range each non-empty line covers
+ * and the whitespace each break deleted. Undefined when the lines do not account for the source exactly (leading or
+ * trailing whitespace outside the lines, dropped or changed characters, fragments of one line not contiguous, a break
+ * that is not whitespace or is too long). `gaps` is the separator list that rebuilds the authored runs from the lines
+ * (plain strings, or split [text, keep] entries when a break straddles two styles) and is undefined when no form of it
+ * can be shown to; `breaks` are the plain whitespace strings. `indexes` are the positions in `lines` of the non-empty ones.
+ */
+function analyzeLines(value, lines) {
+  if (!Array.isArray(lines) || lines.length > MAX_WRAPPED_LINES) return undefined;
+  const authored = Array.isArray(value) ? value : typeof value === 'string' ? [value] : null;
+  if (!authored) return undefined;
+  const runs = [];
+  for (const run of authored) {
     const text = typeof run === 'string' ? run : object(run) ? run.text : undefined;
     if (typeof text !== 'string') return undefined;
-    source += text;
+    runs.push(typeof run === 'string' ? {text} : run);
   }
+  const source = runs.map(run => run.text).join('');
   let position = 0;
-  for (const line of lines) {
-    if (!Array.isArray(line?.fragments) || !line.fragments.length) return undefined;
-    for (const fragment of line.fragments) {
-      if (typeof fragment?.text !== 'string' || !source.startsWith(fragment.text, position)) return undefined;
-      position += fragment.text.length;
+  const spans = [], breaks = [], indexes = [];
+  for (const [lineIndex, line] of lines.entries()) {
+    if (!Array.isArray(line?.fragments)) return undefined;
+    if (!line.fragments.length) continue;
+    const span = {start: position, end: position};
+    for (const [index, fragment] of line.fragments.entries()) {
+      // RR-34: a citation/footnote marker is generated text with no source range; it never starts a line.
+      if (fragment?.kind === 'marker') continue;
+      const text = fragment?.text;
+      if (typeof text !== 'string' || !text) return undefined;
+      let at = position;
+      // The first fragment of a line after the first may follow whitespace the break deleted.
+      if (index === 0 && spans.length) {
+        while (!source.startsWith(text, at)) {
+          if (at - position >= MAX_GAP_LENGTH || !GAP_CHARACTER.test(source[at] ?? '')) return undefined;
+          at += 1;
+        }
+        breaks.push(source.slice(position, at));
+      } else if (!source.startsWith(text, at)) return undefined;
+      if (index === 0) span.start = at;
+      position = at + text.length;
     }
+    span.end = position;
+    spans.push(span);
+    indexes.push(lineIndex);
   }
-  return position === source.length ? lines.length : undefined;
+  if (!spans.length || spans[0].start !== 0 || position !== source.length) return undefined;
+  // The offset at which each authored run starts.
+  const starts = [];
+  let offset = 0;
+  for (const run of runs) { starts.push(offset); offset += run.text.length; }
+  // The leading part of a break that the previous line's last run (and any run after it of the same style) holds.
+  const kept = breaks.map((text, index) => {
+    const from = spans[index].end, to = from + text.length;
+    const owner = starts.findLastIndex((start, run) => start < from && runs[run].text);
+    let keep = 0;
+    for (let run = owner; run >= 0 && run < runs.length && starts[run] < to; run += 1) {
+      if (run !== owner && runs[run].text && !sameRunStyle(runs[run], runs[owner])) break;
+      keep = Math.max(0, Math.min(text.length, starts[run] + runs[run].text.length - from));
+    }
+    return keep ? [text, keep] : text;
+  });
+  const pieces = spans.map(span => runs.flatMap((run, index) => {
+    const from = Math.max(span.start, starts[index]), to = Math.min(span.end, starts[index] + run.text.length);
+    return from < to ? [{...run, text: run.text.slice(from - starts[index], to - starts[index])}] : [];
+  }));
+  const signature = list => JSON.stringify(normalizeRuns(list).map(run => [styleKey(run), run.text]));
+  const authoredSignature = signature(runs);
+  // Plain strings (a break belongs to the next line's first run) when that already rebuilds the runs; the split form otherwise.
+  const gaps = [breaks, kept].find(candidate => signature(joinWrappedText(pieces, candidate)) === authoredSignature);
+  return {spans, breaks, gaps, indexes};
+}
+
+/**
+ * How a rich-text `text` item exported as native line shapes, when the authored
+ * runs can be rebuilt from those lines exactly: `{lines, gaps?}`. `lines` is
+ * the number of native line shapes (blank lines have none). Each line break
+ * either deleted no characters (a soft wrap: gap '') or deleted whitespace
+ * only (a hard break: a newline, a blank line, trimmed spaces); `gaps` lists
+ * the N - 1 separators when any is not '' (see joinWrappedText) and is absent
+ * for pure soft wraps. Only whitespace is ever stored, never a word. Undefined
+ * for a single line or when the runs cannot be proven to rebuild (leading or
+ * trailing whitespace outside the lines, dropped or changed characters, a gap
+ * that spans a differently styled run): nothing then marks the leaf and import
+ * keeps the separate blocks.
+ */
+export function wrappedLines(item) {
+  if (item?.field !== 'text' || !Array.isArray(item.text?.richLines) || item.text.richLines.length < 2) return undefined;
+  const analysis = analyzeLines(item.value, item.text.richLines);
+  if (!analysis?.gaps || analysis.spans.length < 2) return undefined;
+  return {lines: analysis.spans.length, ...(analysis.breaks.some(Boolean) ? {gaps: analysis.gaps} : {})};
 }
 
+/** The number of native line shapes when the lines are consecutive soft wraps only (no hard break between them). */
+export const softWrappedLines = item => {
+  const wrapped = wrappedLines(item);
+  return wrapped && !wrapped.gaps ? wrapped.lines : undefined;
+};
+
 function blockKind(block) {
   if (typeof block.type === 'string' && block.type !== 'group') return CONTENT_KINDS.includes(block.type) ? block.type : null;
   for (const field of ROOT_PAYLOAD_FIELDS) if (block[field] !== undefined) return kindOfField(field);
@@ -107,8 +236,8 @@ export function contentTopology(slide, items, slideIndex, report = () => {}) {
   const boxes = new Map(), wrapped = new Map();
   for (const item of items ?? []) if (typeof item?.path === 'string' && object(item.box)) {
     boxes.set(item.path, item.box);
-    const lines = softWrappedLines(item);
-    if (lines) wrapped.set(item.path, lines);
+    const lines = wrappedLines(item);
+    if (lines) wrapped.set(item.path, wrapRecord(lines));
   }
   const base = `slides.${slideIndex}`;
   let nodes = 0;
@@ -144,7 +273,8 @@ export function contentTopology(slide, items, slideIndex, report = () => {}) {
     const leaf = identity(block, {t: 'leaf', k: kind}, path);
     const box = leafBox(path);
     if (box) leaf.box = box;
-    if (kind === 'text' && wrapped.has(`${path}.text`)) leaf.lines = wrapped.get(`${path}.text`);
+    if (block.bullets !== undefined && block.items === undefined && ['list', 'text'].includes(kind)) leaf.bullets = true;
+    if (kind === 'text' && wrapped.has(`${path}.text`)) Object.assign(leaf, wrapped.get(`${path}.text`));
     return leaf;
   };
   try {
@@ -160,7 +290,7 @@ export function contentTopology(slide, items, slideIndex, report = () => {}) {
     const fields = ROOT_PAYLOAD_FIELDS.filter(name => slide[name] !== undefined).map(field => {
       const box = boxes.get(`${base}.${field}`);
       const lines = field === 'text' ? wrapped.get(`${base}.text`) : undefined;
-      return box ? {field, box: [box.x, box.y, box.width, box.height].map(round1), ...(lines ? {lines} : {})} : {field};
+      return box ? {field, box: [box.x, box.y, box.width, box.height].map(round1), ...lines} : {field};
     });
     if (!fields.length) return undefined;
     if (fields.length === 1) return {form: 'root', ...fields[0]};
@@ -174,15 +304,97 @@ export function contentTopology(slide, items, slideIndex, report = () => {}) {
 
 class TopologyError extends Error {}
 
+// ---------------------------------------------------------------------------
+// Hard line breaks inside list items
+//
+// A list exports one native shape per line of every entry: `OPF list <path> line N`, the entry's text lines (the first
+// bulleted), then its description lines, numbered in that order. Import joins an entry's continuation lines without a
+// separator (a soft wrap deletes no character) and tells description lines from text lines by size, so a newline inside an
+// item was dropped and a blank line became an empty description. The slide record's `lists` stores, per list path, the
+// whitespace each hard break deleted, keyed by the number of the line that follows the break:
+//
+//   lists = [[path, [[line, gap], ...]], ...]    // gap as in `wrap`: whitespace, or [whitespace, keep]
+
+export const MAX_LIST_PATHS = 256;
+export const MAX_LIST_BREAKS = 20000;
+const LIST_PATH = /^slides\.\d+(?:\.[A-Za-z0-9_:+-]{1,64}){1,32}$/;
+
+/**
+ * The `lists` record of a slide from its composed geometry `items`, or undefined when no list item holds a hard break.
+ * `omit(path, reason)` names a list whose breaks could not be accounted for exactly (the characters of an item do not
+ * equal its native lines plus whitespace, leading or trailing whitespace outside the lines): import then joins that
+ * list's lines as before, and the export reports the omission.
+ */
+export function listLineBreaks(items, omit = () => {}) {
+  const lists = [];
+  for (const item of items ?? []) {
+    const entries = item?.text?.listEntries;
+    if ((item?.field !== 'items' && item?.field !== 'bullets') || !Array.isArray(entries) || typeof item.path !== 'string') continue;
+    const recorded = [];
+    let line = 0, failed = false;
+    for (const entry of entries) {
+      for (const [value, rich] of [[entry?.value, entry?.text?.richLines], [entry?.descriptionValue, entry?.description?.richLines]]) {
+        if (!Array.isArray(rich)) continue;
+        const first = line;
+        line += rich.length;
+        if (rich.filter(part => part?.fragments?.length).length < 2) continue;
+        const analysis = analyzeLines(value, rich);
+        if (!analysis) {
+          const source = (Array.isArray(value) ? value.map(run => typeof run === 'string' ? run : run?.text ?? '') : [typeof value === 'string' ? value : '']).join('');
+          if (/[\r\n]/.test(source)) failed = true;
+          continue;
+        }
+        const gaps = analysis.gaps ?? analysis.breaks;
+        gaps.forEach((gap, index) => { if (Array.isArray(gap) || gap) recorded.push([first + analysis.indexes[index + 1], gap]); });
+      }
+    }
+    if (failed) omit(item.path, 'a line break inside a list item could not be recorded exactly');
+    if (recorded.length) lists.push([item.path, recorded]);
+  }
+  const total = lists.reduce((sum, [, entries]) => sum + entries.length, 0);
+  return lists.length && lists.length <= MAX_LIST_PATHS && total <= MAX_LIST_BREAKS ? lists : undefined;
+}
+
+/** Throws when `value` is not a well-formed `lists` record (untrusted input). Returns it otherwise. */
+export function validateListBreaks(value) {
+  if (!Array.isArray(value) || !value.length || value.length > MAX_LIST_PATHS) throw Error('Invalid list breaks record.');
+  let total = 0;
+  const paths = new Set();
+  for (const entry of value) {
+    if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== 'string' || !LIST_PATH.test(entry[0]) || paths.has(entry[0]) || !Array.isArray(entry[1]) || !entry[1].length) throw Error('Invalid list breaks entry.');
+    paths.add(entry[0]);
+    let previous = -1;
+    for (const item of entry[1]) {
+      if (!Array.isArray(item) || item.length !== 2 || !Number.isSafeInteger(item[0]) || item[0] <= previous || item[0] > MAX_LIST_BREAKS || !validGap(item[1]) || (item[1] === '')) throw Error('Invalid list break.');
+      previous = item[0];
+      if (++total > MAX_LIST_BREAKS) throw Error('Too many list breaks.');
+    }
+  }
+  return value;
+}
+
 // ---------------------------------------------------------------------------
 // Import: validation
 
 const validBox = value => value === undefined || (Array.isArray(value) && value.length === 4 && value.every(number => typeof number === 'number' && Number.isFinite(number) && Math.abs(number) < 1e7));
 const validId = value => value === undefined || (typeof value === 'string' && value.length <= MAX_ID_LENGTH);
 const validLines = value => value === undefined || (Number.isSafeInteger(value) && value >= 2 && value <= MAX_WRAPPED_LINES);
-const validField = value => object(value) && ROOT_PAYLOAD_FIELDS.includes(value.field) && validBox(value.box) && validLines(value.lines) && (value.lines === undefined || value.field === 'text');
+// gaps: one entry per line break, a whitespace string or [whitespace, characters kept by the previous line's last run].
+const validGap = gap => (typeof gap === 'string' && gap.length <= MAX_GAP_LENGTH && GAP_TEXT.test(gap))
+  || (Array.isArray(gap) && gap.length === 2 && typeof gap[0] === 'string' && gap[0].length <= MAX_GAP_LENGTH && GAP_TEXT.test(gap[0]) && Number.isSafeInteger(gap[1]) && gap[1] > 0 && gap[1] <= gap[0].length);
+const validGaps = (gaps, lines) => gaps === undefined || (lines !== undefined && Array.isArray(gaps) && gaps.length === lines - 1 && gaps.every(validGap));
+// `wrap` = {lines, gaps?} (RR-09) is the general record; `lines` alone (a count of pure soft wraps) is the form importers
+// before RR-09 read, and the only one written for pure soft wraps. A leaf with a hard break stores `wrap` alone, so an
+// older importer, which ignores the unknown key, keeps the flat blocks instead of joining lines without their separators.
+const validWrap = wrap => wrap === undefined || (object(wrap) && Number.isSafeInteger(wrap.lines) && validLines(wrap.lines) && validGaps(wrap.gaps, wrap.lines));
+const validWrapOf = value => validLines(value.lines) && validWrap(value.wrap) && ((value.lines === undefined && value.wrap === undefined) || value.k === 'text' || value.field === 'text');
+/** The wrapped-line record of a stored leaf: {lines, gaps?}, or undefined. */
+export const wrapOf = node => node.wrap ?? (node.lines === undefined ? undefined : {lines: node.lines});
+/** The leaf fields that record `wrapped` ({lines, gaps?} from wrappedLines). */
+const wrapRecord = wrapped => wrapped.gaps ? {wrap: wrapped} : {lines: wrapped.lines};
+const validField = value => object(value) && ROOT_PAYLOAD_FIELDS.includes(value.field) && validBox(value.box) && validWrapOf(value);
 /** The root payload leaves of a root-form record: [{field, box?}]. */
-export const rootFields = topology => topology.fields ?? [{field: topology.field, box: topology.box, lines: topology.lines}];
+export const rootFields = topology => topology.fields ?? [{field: topology.field, box: topology.box, lines: topology.lines, wrap: topology.wrap}];
 
 /** Throws when `value` is not a well-formed topology record. Returns it otherwise. */
 export function validateTopology(value) {
@@ -205,7 +417,8 @@ export function validateTopology(value) {
     if (!CONTENT_KINDS.includes(item.k)) throw Error('Unknown content kind.');
     if (item.comp !== undefined) throw Error('A content leaf has no composition.');
     if (!validBox(item.box)) throw Error('Invalid content box.');
-    if (!validLines(item.lines) || (item.lines !== undefined && item.k !== 'text')) throw Error('Invalid wrapped line count.');
+    if (item.bullets !== undefined && (item.bullets !== true || !['list', 'text'].includes(item.k))) throw Error('Invalid bullets flag.');
+    if (!validWrapOf(item)) throw Error('Invalid wrapped line record.');
   };
   switch (value.form) {
     case 'root': {
@@ -217,7 +430,7 @@ export function validateTopology(value) {
       }
       if (!ROOT_PAYLOAD_FIELDS.includes(value.field)) throw Error('Unknown root payload field.');
       if (!validBox(value.box)) throw Error('Invalid content box.');
-      if (!validLines(value.lines) || (value.lines !== undefined && value.field !== 'text')) throw Error('Invalid wrapped line count.');
+      if (!validWrapOf(value)) throw Error('Invalid wrapped line record.');
       return value;
     }
     case 'blocks':
@@ -248,25 +461,16 @@ const containsOrigin = (box, bounds) => bounds.x >= box[0] - BOX_TOLERANCE && bo
 const contains = (box, bounds) => containsOrigin(box, bounds)
   && bounds.x + bounds.width <= box[0] + box[2] + BOX_TOLERANCE && bounds.y + bounds.height <= box[1] + box[3] + BOX_TOLERANCE;
 
-const textRuns = value => typeof value === 'string' || (Array.isArray(value) && value.length > 0 && value.every(run => object(run) && typeof run.text === 'string'));
-const sameRunStyle = (a, b) => JSON.stringify({...a, text: ''}) === JSON.stringify({...b, text: ''});
-// The lines' text joined in order. Runs are never invented or dropped; at a seam the
-// last run of one line and the first of the next merge when they differ only in text
-// (a run the wrap cut in two), the same way a rejoined list does.
-function joinWrappedText(parts) {
-  if (parts.every(part => typeof part === 'string')) return parts.join('');
-  const joined = [];
-  for (const part of parts) {
-    const runs = typeof part === 'string' ? [{text: part}] : part;
-    runs.forEach((run, position) => {
-      const last = joined.at(-1);
-      if (position === 0 && last && sameRunStyle(last, run)) last.text += run.text;
-      else joined.push({...run});
-    });
-  }
-  return joined;
+// Rename an imported list payload's `items` to `bullets`, unless an item holds a description (only list items may).
+// `bullets` is valid beside type 'text' only, so an authored `type` comes back as 'text'.
+function bulletsKey(payload, typed) {
+  if (payload.items === undefined || payload.bullets !== undefined || !Array.isArray(payload.items)) return;
+  if (payload.items.some(item => object(item) && !Array.isArray(item) && item.description !== undefined)) return;
+  payload.bullets = payload.items;
+  delete payload.items;
+  if (typed) payload.type = 'text';
 }
-
+const textRuns = value => typeof value === 'string' || (Array.isArray(value) && value.length > 0 && value.every(run => object(run) && typeof run.text === 'string'));
 /**
  * Rebuild the authored content form from the imported flat `blocks` and their
  * native `bounds` (reference px, one entry per block, null when unknown).
@@ -316,9 +520,10 @@ export function rebuildContent(topology, blocks, bounds, placed) {
     // (the structure hash was checked before this rebuild), so exactly that many
     // text blocks in the leaf are its consecutive lines: they rejoin in reading
     // order, with no separator, because a soft wrap deletes no characters.
-    if (leaf.kind === 'text' && leaf.node.lines === leaf.matches.length && leaf.matches.every(index => blocks[index]?.type === 'text' && textRuns(blocks[index].text))) {
+    const wrap = wrapOf(leaf.node);
+    if (leaf.kind === 'text' && wrap?.lines === leaf.matches.length && leaf.matches.every(index => blocks[index]?.type === 'text' && textRuns(blocks[index].text))) {
       const ordered = leaf.matches.map((index, position) => ({index, y: bounds[index].y, position})).sort((a, b) => a.y - b.y || a.position - b.position).map(entry => entry.index);
-      leaf.payload = {...blocks[ordered[0]], text: joinWrappedText(ordered.map(index => blocks[index].text))};
+      leaf.payload = {...blocks[ordered[0]], text: joinWrappedText(ordered.map(index => blocks[index].text), wrap.gaps)};
       leaf.matches = [ordered[0]];
       continue;
     }
@@ -330,6 +535,8 @@ export function rebuildContent(topology, blocks, bounds, placed) {
     const payload = clone(leaf.payload ?? blocks[leaf.matches[0]]);
     // The imported block always names its type; the authored one may have left it implicit.
     if (!leaf.node.typed) delete payload.type;
+    // The imported block names every list `items`; a payload authored as `bullets` takes its key back (a bullet has no description).
+    if (leaf.node.bullets === true) bulletsKey(payload, leaf.node.typed);
     if (leaf.node.id !== undefined) { payload.id = leaf.node.id; ids.push(leaf.node.id); }
     if (leaf.node.ext !== undefined) payload.extensions = clone(leaf.node.ext);
     return payload;
@@ -371,7 +578,7 @@ export function rebuildContent(topology, blocks, bounds, placed) {
       // The slide `type` is restored separately; the imported block names any
       // list by `items`, so an authored `bullets` payload takes its key back.
       const {type: _type, ...rest} = payload;
-      if (leaf.field === 'bullets' && rest.items !== undefined && rest.bullets === undefined) { rest.bullets = rest.items; delete rest.items; }
+      if (leaf.field === 'bullets') bulletsKey(rest);
       Object.assign(fields, rest);
     }
     placed?.(paths);

package/dist/document-provenance.js

@@ -1,6 +1,7 @@
 import {XMLParser} from 'fast-xml-parser';
 import {decodeTextTag, encodeTextTag} from './code-provenance.js';
-import {contentTopology, rebuildContent, validateTopology} from './content-topology.js';
+import {contentTopology, rebuildContent, validateTopology, listLineBreaks, validateListBreaks} from './content-topology.js';
+import {runColorRecord, validateRunColors} from './run-colors.js';
 // Namespace import: cores before FF-34 do not export resolveSocialProfile.
 import * as opfCore from '@openpresentation/opf';
 
@@ -45,6 +46,7 @@ const REL_TAGS = 'http://schemas.openxmlformats.org/officeDocument/2006/relation
 const NS = 'http://schemas.openxmlformats.org/presentationml/2006/main';
 const TAGS_TYPE = 'application/vnd.openxmlformats-officedocument.presentationml.tags+xml';
 const MAX_OMITTED = 256;
+const MAX_AUTHOR_LENGTH = 4096;
 const MAX_FIELD_BYTES = 256 * 1024, MAX_CATALOG_BYTES = 1024 * 1024, MAX_TAG_CHARS = 16 * 1024 * 1024;
 
 const enc = new TextEncoder(), dec = new TextDecoder('utf-8', {fatal: true});
@@ -73,7 +75,26 @@ function authoredSocials(stored, observed, records) {
 // native PowerPoint counterpart and round-trips from the stored value.
 export const DESIGN_REFERENCES = Object.freeze(['theme', 'colorScheme', 'fontScheme', 'dimensions', 'background']);
 export const COMPOSITION_HINTS = Object.freeze(['titleAlignment', 'contentAlignment', 'contentBox', 'contentDirection', 'chartPrimary', 'imageFill', 'listBullet']);
-export const METADATA = Object.freeze(['narrative', 'tone', 'audience', 'purpose', 'language', 'organization', 'speaker', 'takeaway', 'duration', 'tags', 'variables', 'filename', 'extensions']);
+// `references` (RR-34): the deck's cited sources. Like `author`, stored as a top-level key of OPF_DOCUMENT_V1 (importers up to
+// 0.11.9 drop a tag with an unknown `supplement` field but ignore an unknown top-level key) and read back into metadata.
+export const METADATA = Object.freeze(['narrative', 'tone', 'audience', 'purpose', 'language', 'organization', 'speaker', 'takeaway', 'duration', 'tags', 'variables', 'filename', 'extensions', 'author', 'references']);
+
+// `author` is native (docProps/core.xml dc:creator), where several authors share one field joined by "; " (the join the
+// schema documents). Import splits a creator on exactly that separator, and only when every part is a non-empty name
+// with no outer whitespace (so the split joins back to the identical text); a single name is never cut. The authored form (an array, or a string that itself holds a "; ") returns from the stored record
+// while the creator still equals it; plain PPTX has no record and gets the split. The record is the top-level `author`
+// of OPF_DOCUMENT_V1: importers up to 0.11.8 reject an unknown key inside `supplement` (dropping the whole tag) but ignore
+// an unknown top-level key.
+export const joinAuthors = author => Array.isArray(author) ? author.join('; ') : author;
+export function splitAuthors(creator) {
+  if (typeof creator !== 'string') return creator;
+  const parts = creator.split('; ');
+  return parts.length > 1 && parts.every(part => part && part === part.trim()) ? parts : creator;
+}
+// The creator the package gets when the document names no author. An imported default is not an authored value.
+export const DEFAULT_AUTHOR = 'OpenPresentation';
+// Stored only when the native creator cannot carry the authored form by itself (or would read as the default).
+const authorNeedsRecord = author => Array.isArray(author) || (typeof author === 'string' && (author === DEFAULT_AUTHOR || Array.isArray(splitAuthors(author))));
 // Brand images have no native gate: they return from the stored value once
 // their media and asset references resolve. The P2 logo picture (`OPF_LOGO_V1`)
 // consumes the drawn logo; `design.logo` itself always returns from here.
@@ -399,6 +420,7 @@ export function documentProvenance(presentation, {mode = 'full', isCatalogId = (
   for (const key of METADATA) {
     if (!own(presentation, key)) continue;
     const value = presentation[key];
+    if (key === 'author' && (referencesOnly || !authorNeedsRecord(value))) continue;
     if (referencesOnly) {
       const kind = METADATA_CATALOGS[key];
       const ids = typeof value === 'string' ? [value] : key === 'audience' && Array.isArray(value) && value.every(item => typeof item === 'string') ? value : null;
@@ -447,7 +469,16 @@ export function recordContentTopology(provenance, slide, index, items) {
   if (!provenance || provenance.mode !== 'full' || !provenance.slides[index]) return;
   // An unstorable structure is reported with the other omissions (storable) and recorded in the tag.
   const topology = contentTopology(slide, items, index, reason => { provenance.slides[index].omittedContent = reason; });
-  if (topology) provenance.slides[index].content = topology;
+  if (!topology) return;
+  provenance.slides[index].content = topology;
+  // Variable, scheme-slot and role names of text runs (the native colour holds only what they resolve to).
+  const colors = runColorRecord(slide);
+  if (colors) provenance.slides[index].colors = colors;
+  // Whitespace of the hard line breaks inside list items (their native lines carry no tag).
+  const omittedLists = [];
+  const lists = listLineBreaks(items, (path, reason) => omittedLists.push([path, reason]));
+  if (lists) provenance.slides[index].lists = lists;
+  if (omittedLists.length) provenance.slides[index].omittedLists = omittedLists;
 }
 
 function base64ToBytes(value) {
@@ -578,6 +609,11 @@ function storable(entries, provenance) {
     const fields = {};
     for (const [key, value] of Object.entries(source[section] ?? {})) {
       const path = section === 'design' ? `design.${key}` : key;
+      if (section === 'metadata' && (key === 'author' || key === 'references')) {
+        const prepared = prepare(path, value);
+        if (prepared !== undefined) document[key] = prepared;
+        continue;
+      }
       // A design reference is only restorable together with its asset.
       if (section === 'design' && unstoredAsset(value)) { omit(path, 'the asset it references could not be stored'); continue; }
       const prepared = prepare(path, value);
@@ -593,7 +629,8 @@ function storable(entries, provenance) {
   const slides = provenance.slides.map((record, index) => {
     const result = {v: 1, slide: index};
     if (record.omittedContent) omit(`slides.${index}.content`, record.omittedContent);
-    for (const key of ['id', 'beat', ...SLIDE_STRUCTURE, ...SLIDE_METADATA, 'content']) {
+    for (const [path, reason] of record.omittedLists ?? []) omit(path, reason);
+    for (const key of ['id', 'beat', ...SLIDE_STRUCTURE, ...SLIDE_METADATA, 'content', 'colors', 'lists']) {
       if (record[key] === undefined) continue;
       const value = prepare(`slides.${index}.${key}`, record[key]);
       if (value !== undefined) result[key] = value;
@@ -630,7 +667,7 @@ function storable(entries, provenance) {
   }
   for (const [index, record] of slides.entries()) {
     while (tagChars(record) > budget) {
-      const candidates = [...['id', 'beat', ...SLIDE_STRUCTURE, ...SLIDE_METADATA, 'content', 'layoutRecord'].filter(key => record[key] !== undefined).map(key => ({key, size: sizeOf(record[key])})),
+      const candidates = [...['id', 'beat', ...SLIDE_STRUCTURE, ...SLIDE_METADATA, 'content', 'colors', 'lists', 'layoutRecord'].filter(key => record[key] !== undefined).map(key => ({key, size: sizeOf(record[key])})),
         ...Object.keys(record.design ?? {}).map(key => ({key, design: true, size: sizeOf(record.design[key])}))];
       if (!candidates.length) break;
       const largest = candidates.sort((a, b) => b.size - a.size)[0];
@@ -738,7 +775,15 @@ function validateDocument(stored) {
   for (const key of Object.keys(value.metadata ?? {})) if (!METADATA.includes(key)) throw Error(`Unknown metadata field ${key}.`);
   if (value.metadata?.filename !== undefined && typeof value.metadata.filename !== 'string') throw Error('Invalid filename record.');
   if (value.metadata?.extensions !== undefined && !object(value.metadata.extensions)) throw Error('Invalid extensions record.');
+  const author = stored.author;
+  if (author !== undefined && !((typeof author === 'string' && author.length <= MAX_AUTHOR_LENGTH * 256) || (Array.isArray(author) && author.length > 0 && author.length <= 256 && author.every(name => typeof name === 'string' && name.length <= MAX_AUTHOR_LENGTH)))) throw Error('Invalid author record.');
+  const references = stored.references;
+  if (references !== undefined && (!Array.isArray(references) || references.length > 4096 || !references.every(object))) throw Error('Invalid references record.');
   validateOmitted(value.omitted);
+  if (author !== undefined || references !== undefined) {
+    const {author: _author, references: _references, ...rest} = value;
+    return {...rest, metadata: {...rest.metadata, ...(author !== undefined ? {author} : {}), ...(references !== undefined ? {references} : {})}};
+  }
   return value;
 }
 
@@ -753,6 +798,8 @@ function validateSlide(stored) {
   if (value.section !== undefined && typeof value.section !== 'string') throw Error('Invalid slide section record.');
   if (value.extensions !== undefined && !object(value.extensions)) throw Error('Invalid slide extensions record.');
   if (value.content !== undefined) validateTopology(value.content);
+  if (value.colors !== undefined) validateRunColors(value.colors);
+  if (value.lists !== undefined) validateListBreaks(value.lists);
   validateOmitted(value.omitted);
   return value;
 }
@@ -792,6 +839,23 @@ function pruneDangling(value, dangling, path, removed) {
   return Object.fromEntries(Object.entries(value).flatMap(([key, item]) => isDangling(item) ? (removed.push(`${path}.${key}`), []) : [[key, pruneDangling(item, dangling, `${path}.${key}`, removed)]]));
 }
 
+/**
+ * The hard line breaks stored for the lists of one slide: Map(list path -> Map(line number -> gap)), or null when the slide
+ * carries none, its record is unreadable, or its arrangement changed since export (the lines are then no longer the exported
+ * ones). Read before the slide's shapes are merged into list blocks; any damage is reported later by restoreDocumentProvenance.
+ */
+export function slideListBreaks(entries, path, root, rels) {
+  try {
+    const found = readTag(entries, root?.['p:cSld']?.['p:custDataLst'], rels, SLIDE_TAG);
+    if (found.missing) return null;
+    const record = validateSlide(found.value);
+    if (record.lists === undefined || record.native.structure !== nativeSlide(entries, path).structure) return null;
+    return new Map(record.lists.map(([list, lines]) => [list, new Map(lines)]));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Read OPF_DOCUMENT_V1 / OPF_SLIDE_V1 and decide what still matches the
  * package. Nothing is modified here: the result lists restore groups (one per
@@ -1037,12 +1101,20 @@ export function restoreDocumentProvenance(imported, {entries, presentationRoot,
   // content (the furniture organization name, linked socials) win over their
   // stored values; stored-only fields (logo, role ...) return.
   const metadata = document.metadata ?? {};
+  // The exporter writes the default creator when no author was authored: with the document record present, that default is not the author.
+  if (metadata.author === undefined && imported.author === DEFAULT_AUTHOR) group('author', [remove(['author'])]);
   for (const key of METADATA) {
     if (metadata[key] === undefined) continue;
     if (key === 'organization' && organizationConflict) {
       report({code: 'metadata-reference-changed', path: 'organization', message: 'Slides now show different organization names in their furniture, so the stored organization was not restored; each slide keeps its visible text.'});
       continue;
     }
+    if (key === 'author') {
+      // Native evidence: the stored authored form only stands for the creator it was joined into.
+      if (joinAuthors(imported.author) === joinAuthors(metadata.author)) group('author', [set(['author'], clone(metadata.author))]);
+      else report({code: 'metadata-reference-changed', path: 'author', message: 'The PowerPoint author field no longer matches the stored author, so the stored author was not restored; the current field is kept.'});
+      continue;
+    }
     let value = restorable(key, metadata[key], {prune: true});
     if (value === undefined) continue;
     if (key === 'organization' && object(imported.organization)) {

package/dist/index.d.ts

@@ -64,6 +64,15 @@ export interface ChartDataAdaptedDiagnostic { code: "chart-data-adapted"; path:
 /** With `chartex: "native"`, a map chart (`world`) is exported as a chartex regionMap (`Requires="cx4"`) without cached geography: PowerPoint must fetch the region shapes from its online map service and shows "There was a problem getting the information for your map chart" with an empty chart until it does. */
 export interface ChartMapGeodataDiagnostic { code: "chart-map-geodata"; path: string; message: string }
 
+/** A template variable was unfilled and its `example` was used (template export only). */
+export interface VariableExampleUsedDiagnostic {
+  code: "variable-example-used";
+  /** JSON pointer of the variable's declaration. */
+  path: string;
+  message: string;
+  id: string;
+}
+
 export interface ToPptxOptions {
   /** Default compatible converts WebP to a static PNG. Preserve embeds original WebP bytes. */
   imageFormat?: "compatible" | "preserve";
@@ -90,11 +99,18 @@ export interface ToPptxOptions {
    * also written as PowerPoint's native section list whatever this option says.
    */
   provenance?: "full" | "references-only" | false;
+  /**
+   * Values for the deck's template variables, keyed by variable id (core `resolveVariables`). A deck that uses content
+   * variables, or is marked `template: true`, is resolved to a concrete deck first; the PPTX holds the resolved text.
+   * A template exports with each unfilled variable's example (diagnostic `variable-example-used`); a normal deck with an
+   * unfilled required variable throws `unfilled-variables`, and a value of the wrong kind throws `invalid-variables`.
+   */
+  variables?: Record<string, unknown>;
   textMeasurement?: TextMeasurement;
   /** Match preview/pagination clearance around supplied vector text outlines; default 1. */
   textRasterPadding?: number;
   /** Layout diagnostics, `media-provenance-omitted` when video data cannot be stored, plus `unresolved-font-scheme` (once per reference path) when a font-scheme id matches no record and the default `aptos` scheme is used as the base. */
-  onDiagnostic?: (diagnostic: LayoutDiagnostic | FontSchemeDiagnostic | MediaProvenanceDiagnostic | ChartDataUnplottableDiagnostic | ChartDataAdaptedDiagnostic | ChartMapGeodataDiagnostic | ContentPlaceholderDiagnostic | UnresolvedAssetDiagnostic | WatermarkNotExportedDiagnostic | SvgSanitizedDiagnostic | SvgImageRasterizedDiagnostic) => void;
+  onDiagnostic?: (diagnostic: LayoutDiagnostic | FontSchemeDiagnostic | MediaProvenanceDiagnostic | ChartDataUnplottableDiagnostic | ChartDataAdaptedDiagnostic | ChartMapGeodataDiagnostic | ContentPlaceholderDiagnostic | UnresolvedAssetDiagnostic | WatermarkNotExportedDiagnostic | SvgSanitizedDiagnostic | SvgImageRasterizedDiagnostic | VariableExampleUsedDiagnostic) => void;
   baseDir?: string;
   compressionLevel?: number;
   imageResolver?: (src: string, context: ImageResolverContext) => ImageResolverResult | Promise<ImageResolverResult | null | undefined> | null | undefined;