@openpresentation/opf-pptx 0.11.9 → 0.12.1

package/dist/logo-provenance.js

@@ -36,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};
 }
 
 /**
@@ -61,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[^>]*\/>/, '');

package/dist/master-themes.js

@@ -0,0 +1,49 @@
+const decoder = new TextDecoder(), encoder = new TextEncoder();
+const text = bytes => decoder.decode(bytes);
+
+const THEME_TYPE = 'application/vnd.openxmlformats-officedocument.theme+xml';
+const THEME_TARGET = /Target="\.\.\/theme\/(theme\d+\.xml)"/;
+const NOTES_MASTER = /^ppt\/notesMasters\/notesMaster\d+\.xml$/;
+const SLIDE_MASTER = /^ppt\/slideMasters\/slideMaster\d+\.xml$/;
+
+const relsOf = path => path.replace(/([^/]+)$/, '_rels/$1.rels');
+
+/**
+ * FF-05 (font-fidelity-everywhere). PptxGenJS 4.0.1 points the notes master at the slide master's theme part
+ * (`ppt/theme/theme1.xml`). Every master owns its theme part in a PowerPoint package (theme1 for the slide master,
+ * theme2 for the notes master, theme3 for a handout master), and PowerPoint refuses to read a package whose notes
+ * master it recognises when that master shares the slide theme ("The file or directory is corrupted and unreadable",
+ * 0x80070570). The vendored `p:notesMasterIdLst` sits after `p:sldIdLst` (see presentationInSchemaOrder in index.js),
+ * which PowerPoint ignored; it then synthesised a default notes master with the default Office theme, and that
+ * made the default font (Aptos) appear in Presentation.Fonts although no part names it.
+ *
+ * Each notes master that shares a theme part with another master gets its own copy of that theme, with the same
+ * fonts, colours and format scheme, a relationship to it and a content-type override. The copy is taken after
+ * every theme rewrite, so it carries the deck's final fonts. Copies are numbered after the existing themes.
+ */
+export function giveNotesMastersOwnThemes(output) {
+  const types = output['[Content_Types].xml'];
+  if (!types) return;
+  const used = new Set();
+  const themeOf = master => THEME_TARGET.exec(text(output[relsOf(master)]?.[0] ?? new Uint8Array()))?.[1];
+  for (const master of Object.keys(output).filter(path => SLIDE_MASTER.test(path))) {
+    const theme = themeOf(master);
+    if (theme) used.add(theme);
+  }
+  let next = Math.max(0, ...Object.keys(output).map(path => Number(/^ppt\/theme\/theme(\d+)\.xml$/.exec(path)?.[1] ?? 0))) + 1;
+  let overrides = '';
+  for (const master of Object.keys(output).filter(path => NOTES_MASTER.test(path)).sort()) {
+    const theme = themeOf(master);
+    if (!theme) continue;
+    if (!used.has(theme)) { used.add(theme); continue; }
+    const source = output[`ppt/theme/${theme}`];
+    if (!source) continue;
+    const name = `theme${next++}.xml`;
+    output[`ppt/theme/${name}`] = [source[0], source[1]];
+    const rels = relsOf(master);
+    output[rels] = [encoder.encode(text(output[rels][0]).replace(THEME_TARGET, `Target="../theme/${name}"`)), output[rels][1]];
+    overrides += `<Override PartName="/ppt/theme/${name}" ContentType="${THEME_TYPE}"/>`;
+    used.add(name);
+  }
+  if (overrides) output['[Content_Types].xml'] = [encoder.encode(text(types[0]).replace('</Types>', `${overrides}</Types>`)), types[1]];
+}

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-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/package-fonts.js

@@ -122,7 +122,7 @@ export function applyPitchFamilies(entries, pitch) {
 // docProps/app.xml: regenerate the "Fonts Used" group of HeadingPairs and
 // TitlesOfParts from the fonts the finished package uses, and name the theme
 // the way the theme part does. Other groups (slide titles) are kept.
-export function writeFontsUsed(appXml, fonts, themeName) {
+export function writeFontsUsed(appXml, fonts, themeNames) {
   const pairs = headingPairs(appXml), titles = titlesOfParts(appXml);
   if (!pairs || !titles) return appXml;
   const groups = [];
@@ -135,7 +135,8 @@ export function writeFontsUsed(appXml, fonts, themeName) {
   if (fontsGroup) fontsGroup[1] = fonts;
   else groups.unshift(['Fonts Used', fonts]);
   const themeGroup = groups.find(([name]) => name === 'Theme');
-  if (themeGroup && themeName && themeGroup[1].length === 1) themeGroup[1] = [themeName];
+  const names = [themeNames ?? []].flat();
+  if (themeGroup && names.length) themeGroup[1] = names;
   const kept = groups.filter(([, items]) => items.length);
   const variants = kept.map(([name, items]) => `<vt:variant><vt:lpstr>${escapeXml(name)}</vt:lpstr></vt:variant><vt:variant><vt:i4>${items.length}</vt:i4></vt:variant>`).join('');
   const items = kept.flatMap(([, list]) => list).map(item => `<vt:lpstr>${escapeXml(item)}</vt:lpstr>`).join('');
@@ -152,8 +153,9 @@ export function finalizeFontsUsed(output) {
   const parts = {};
   for (const [path, [bytes]] of Object.entries(output)) if (/^ppt\/.*\.xml$/.test(path)) parts[path] = bytes;
   const fonts = packageFontsUsed(inventoryPptxTypefaces(parts, {nested: false}));
-  const themeName = /<a:theme\b[^>]*\bname="([^"]*)"/.exec(parts['ppt/theme/theme1.xml'] ? text(parts['ppt/theme/theme1.xml']) : '')?.[1];
-  output['docProps/app.xml'] = [encoder.encode(writeFontsUsed(text(app[0]), fonts, themeName === undefined ? undefined : unescapeFace(themeName))), app[1]];
+  const themeNames = Object.keys(parts).filter(path => /^ppt\/theme\/theme\d+\.xml$/.test(path)).sort((a, b) => Number(a.match(/\d+/)[0]) - Number(b.match(/\d+/)[0]))
+    .map(path => /<a:theme\b[^>]*\bname="([^"]*)"/.exec(text(parts[path]))?.[1]).filter(name => name !== undefined).map(unescapeFace);
+  output['docProps/app.xml'] = [encoder.encode(writeFontsUsed(text(app[0]), fonts, themeNames)), app[1]];
 }
 
 function unescapeFace(value) {

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;
+  });
+}

package/dist/script-fonts.js

@@ -13,6 +13,9 @@
 import * as opfCore from "@openpresentation/opf";
 
 const resolver = typeof opfCore.resolveScriptFonts === "function" ? opfCore.resolveScriptFonts : null;
+// RR-05: authored alignment is logical for right-to-left text (`left` is the start edge). Core owns the rule; a core without it
+// reports no line directions either, so the fallback never has anything to flip.
+export const physicalAlignment = typeof opfCore.physicalAlignment === "function" ? opfCore.physicalAlignment : alignment => alignment;
 // The one paragraph-direction rule shared with the renderer (core FF-07).
 const paragraphDirection = typeof opfCore.paragraphDirection === "function" ? opfCore.paragraphDirection : null;
 
@@ -54,7 +57,37 @@ export function planScriptFonts(presentation, report) {
     report?.({code: "paragraph-direction-unavailable", path: "language",
       message: "The installed @openpresentation/opf has no paragraphDirection, so right-to-left paragraphs are not marked; the preview and export must share that rule. Use a core release that exports it."});
   }
-  return {deck, slides, lang: deck.lang, rtl};
+  return {deck, slides, lang: deck.lang, rtl, contentEastAsian: contentEastAsianFonts(presentation, deck, report)};
+}
+
+// FF-05: East Asian characters in a deck whose own language has no East Asian font (an English deck with Japanese
+// text) still need a real East Asian theme font; an empty slot reads as an unresolved +mn-ea in PowerPoint. The
+// script of the text picks the language core resolves it for: kana is Japanese, hangul Korean, Han alone Simplified
+// Chinese. Returns {heading, body} families, or null when the deck language already selects one or the text has none.
+const KANA = /[\p{Script=Hiragana}\p{Script=Katakana}]/u, HANGUL = /\p{Script=Hangul}/u, HAN = /\p{Script=Han}/u;
+function contentEastAsianFonts(presentation, deck, report) {
+  if (deck.sources.eastAsian !== "latin") return null;
+  let kana = false, hangul = false, han = false;
+  const seen = new Set();
+  const walk = value => {
+    if (typeof value === "string") {
+      kana ||= KANA.test(value); hangul ||= HANGUL.test(value); han ||= HAN.test(value);
+    } else if (value && typeof value === "object" && !seen.has(value)) {
+      seen.add(value);
+      for (const item of Object.values(value)) walk(item);
+    }
+  };
+  walk(presentation.slides);
+  const language = kana ? "japanese" : hangul ? "korean" : han ? "chinese-simplified" : null;
+  if (!language) return null;
+  try {
+    const resolved = resolver({...presentation, language}, {slideIndex: 0});
+    return resolved.sources.eastAsian === "latin" ? null : {heading: resolved.heading.eastAsian, body: resolved.body.eastAsian};
+  } catch (error) {
+    report?.({code: "language-export-unavailable", path: "language",
+      message: `East Asian theme fonts for the East Asian text could not be resolved (${error instanceof Error ? error.message : String(error)}); the theme names the latin family for them.`});
+    return null;
+  }
 }
 
 const escapeAttribute = value => String(value).replace(/[&<>"']/g, char => ({"&": "&amp;", "<": "&lt;", ">": "&gt;", "\"": "&quot;", "'": "&apos;"}[char]));
@@ -79,8 +112,12 @@ export function themeScriptFonts(xml, plan) {
   for (const [tag, slots, family] of [["majorFont", heading, supplement?.heading], ["minorFont", body, supplement?.body]]) {
     xml = xml.replace(new RegExp(`<a:${tag}>[\\s\\S]*?</a:${tag}>`), block => {
       for (const [element, slot] of SCRIPT_SLOTS) {
-        if (plan.deck.sources[slot] === "latin") continue;
-        const face = escapeAttribute(slots[slot]);
+        // FF-05: the East Asian slot always names a font (a script font, a font for the East Asian text, else the latin
+        // family): PowerPoint lists an empty slot as an empty-name font through every paragraph end mark. Complex script
+        // stays empty unless a script font is selected.
+        const content = element === "ea" && plan.deck.sources[slot] === "latin" ? plan.contentEastAsian?.[tag === "majorFont" ? "heading" : "body"] : undefined;
+        if (plan.deck.sources[slot] === "latin" && element !== "ea") continue;
+        const face = escapeAttribute(content ?? slots[slot]);
         block = block.replace(new RegExp(`<a:${element}\\b[^>]*/>`), `<a:${element} typeface="${face}"/>`);
       }
       if (supplement && family) {
@@ -126,24 +163,89 @@ const decodeText = value => value.replace(/&(?:#(\d+)|#x([0-9a-f]+)|(amp|lt|gt|q
   decimal ? String.fromCodePoint(Number(decimal)) : hex ? String.fromCodePoint(parseInt(hex, 16)) : {amp: "&", lt: "<", gt: ">", quot: "\"", apos: "'"}[name.toLowerCase()]);
 
 /**
- * In a right-to-left deck every paragraph states its direction from core's
- * paragraphDirection() over its own text: rtl="1" when it is right-to-left,
- * else an explicit rtl="0", because the master default levels start
- * right-to-left. Alignment is left as composed.
+ * RR-05 bidi runs. PowerPoint treats the digits of a run tagged with a right-to-left language as numbers of that language and
+ * orders them as their own item, so "v2.0" or "PowerPoint 365" inside an Arabic or Hebrew run reads "2.0v" or "365PowerPoint".
+ * Splitting each left-to-right Latin phrase into its own run tagged en-US keeps it one item that PowerPoint orders left to right.
  */
-function paragraphRtl(xml, deckDirection) {
+const LATIN_WORD = /[0-9\p{Script=Latin}]/u, LATIN_LETTER = /\p{Script=Latin}/u, PHRASE_JOINER = /[ \u00a0.,:;&'\u2019/+*_@#=-]/;
+
+/** Ranges [start, end) of the Latin phrases of a decoded string: a Latin letter through the last Latin letter or digit joined by spaces and word punctuation. */
+export function latinPhrases(text) {
+  const ranges = [];
+  for (let index = 0; index < text.length;) {
+    const char = String.fromCodePoint(text.codePointAt(index));
+    if (!LATIN_LETTER.test(char)) { index += char.length; continue; }
+    let end = index + char.length;
+    for (let cursor = end; cursor < text.length;) {
+      const next = String.fromCodePoint(text.codePointAt(cursor));
+      if (LATIN_WORD.test(next)) { cursor += next.length; end = cursor; continue; }
+      if (!PHRASE_JOINER.test(next)) break;
+      // Joiners count only when a Latin letter or digit follows them directly.
+      let after = cursor + next.length;
+      while (after < text.length && PHRASE_JOINER.test(text[after])) after += 1;
+      if (after < text.length && LATIN_WORD.test(String.fromCodePoint(text.codePointAt(after)))) cursor = after; else break;
+    }
+    ranges.push([index, end]);
+    index = end;
+  }
+  return ranges;
+}
+
+const encodeText = value => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+const RUN = /<a:r>(<a:rPr\b[^>]*\/>|<a:rPr\b[^>]*[^/]>[\s\S]*?<\/a:rPr>)<a:t>([^<]*)<\/a:t><\/a:r>/g;
+
+/** Split the runs of a right-to-left paragraph so each Latin phrase is its own en-US run. */
+function splitLatinRuns(body) {
+  return body.replace(RUN, (run, properties, escaped) => {
+    const text = decodeText(escaped), phrases = latinPhrases(text);
+    if (!phrases.length) return run;
+    const make = (value, lang) => `<a:r>${lang ? properties.replace(/\slang="[^"]*"/, ` lang="${lang}"`) : properties}<a:t>${encodeText(value)}</a:t></a:r>`;
+    const pieces = [];
+    let cursor = 0;
+    for (const [from, to] of phrases) {
+      if (from > cursor) pieces.push(make(text.slice(cursor, from)));
+      pieces.push(make(text.slice(from, to), "en-US"));
+      cursor = to;
+    }
+    if (cursor < text.length) pieces.push(make(text.slice(cursor)));
+    return pieces.join("");
+  });
+}
+
+/**
+ * In a right-to-left deck every paragraph states its direction. The writers mark the lines of a paragraph they laid out
+ * (rtl="1", the direction core computed once for the whole paragraph, so wrapped lines never differ); any other paragraph takes
+ * core's paragraphDirection() over its own text: rtl="1" when it is right-to-left, else an explicit rtl="0", because the master
+ * default levels start right-to-left. A right-to-left paragraph with no explicit alignment starts at the right edge (logical
+ * alignment: the master default is left), and its Latin phrases become en-US runs (see splitLatinRuns). With `notes` the
+ * alignment is also set on an explicit left paragraph, because the notes writers pass no alignment of their own.
+ */
+function paragraphRtl(xml, deckDirection, {notes = false} = {}) {
   return xml.replace(/<a:p>([\s\S]*?)<\/a:p>/g, (paragraph, body) => {
     const text = [...body.matchAll(/<a:t>([^<]*)<\/a:t>|<a:br\b/g)].map(match => match[1] === undefined ? "\n" : decodeText(match[1])).join("");
-    const value = paragraphDirection(text, deckDirection) === "rtl" ? "1" : "0";
     const properties = /^(\s*)<a:pPr\b([^>]*?)(\/?)>/.exec(body);
-    if (!properties) return `<a:p><a:pPr rtl="${value}"/>${body}</a:p>`;
-    const attributes = / rtl="[^"]*"/.test(properties[2]) ? properties[2].replace(/ rtl="[^"]*"/, ` rtl="${value}"`) : `${properties[2]} rtl="${value}"`;
+    const marked = properties && / rtl="([01])"/.exec(properties[2]);
+    const rtl = marked ? marked[1] === "1" : paragraphDirection(text, deckDirection) === "rtl";
+    const value = rtl ? "1" : "0";
+    if (rtl) body = splitLatinRuns(body);
+    if (!properties) return `<a:p><a:pPr rtl="${value}"${rtl ? " algn=\"r\"" : ""}/>${body}</a:p>`;
+    let attributes = / rtl="[^"]*"/.test(properties[2]) ? properties[2].replace(/ rtl="[^"]*"/, ` rtl="${value}"`) : `${properties[2]} rtl="${value}"`;
+    if (rtl) {
+      if (!/\salgn="/.test(attributes)) attributes += " algn=\"r\"";
+      else if (notes) attributes = attributes.replace(/ algn="l"/, " algn=\"r\"");
+    }
     return `<a:p>${properties[1]}<a:pPr${attributes}${properties[3]}>${body.slice(properties[0].length)}</a:p>`;
   });
 }
 
-/** Master, layout and presentation default paragraph levels start right-to-left. */
-const levelRtl = xml => xml.replace(/(<a:(?:lvl\dpPr|defPPr)\b[^>]*?\srtl=")0(")/g, "$11$2");
+/** Tables of a right-to-left deck run right to left: the first column is the rightmost, as core's layout draws it. */
+const tableRtl = xml => xml.replace(/<a:tblPr\b([^>]*?)(\/?)>/g, (match, attributes, close) => / rtl="/.test(attributes) ? match : `<a:tblPr rtl="1"${attributes}${close}>`);
+
+/**
+ * Master, layout and presentation default paragraph levels start right-to-left, and a left-aligned level starts at the right edge
+ * (logical alignment): text typed later in an Arabic or Hebrew deck then reads and aligns as the exported slides do.
+ */
+const levelRtl = xml => xml.replace(/<a:(?:lvl\dpPr|defPPr)\b[^>]*?\srtl="0"[^>]*>/g, level => level.replace(/\srtl="0"/, " rtl=\"1\"").replace(/\salgn="l"/, " algn=\"r\""));
 
 /**
  * Apply the plan to one generated XML part. `slideIndex` names the slide a
@@ -157,10 +259,10 @@ export function partScriptFonts(path, xml, plan, slideIndex) {
   if (/^ppt\/slides\/slide\d+\.xml$/.test(path)) {
     xml = xml.replace(/<p:(sp|graphicFrame)>[\s\S]*?<\/p:\1>/g, shape =>
       runScriptFonts(shape, resolved, /<p:cNvPr\b[^>]*\bname="OPF heading /.test(shape)));
-    if (plan.rtl) xml = paragraphRtl(xml, plan.deck.direction);
+    if (plan.rtl) xml = tableRtl(paragraphRtl(xml, plan.deck.direction));
   } else if (/^ppt\/(?:charts\/chart(?:Ex)?|notesSlides\/notesSlide)\d+\.xml$/.test(path)) {
     xml = runScriptFonts(xml, resolved, false);
-    if (plan.rtl && path.startsWith("ppt/notesSlides/")) xml = paragraphRtl(xml, plan.deck.direction);
+    if (plan.rtl && path.startsWith("ppt/notesSlides/")) xml = paragraphRtl(xml, plan.deck.direction, {notes: true});
   } else if (plan.rtl && /^ppt\/(?:slideMasters\/slideMaster\d+|slideLayouts\/slideLayout\d+|notesMasters\/notesMaster\d+|presentation)\.xml$/.test(path)) {
     xml = levelRtl(xml);
   }
@@ -252,6 +354,12 @@ export function reconcileLanguage(groups, observed, report) {
  * language, and theme East Asian/complex-script fonts the document does not
  * reproduce.
  */
+/** Whether the language observed in the runs is written right to left. */
+export function observedRtl(observed) {
+  if (observed.lang === undefined) return false;
+  try { return resolver ? resolver({language: observed.language}).rtl === true : observed.match?.record.direction === "rtl"; } catch { return false; }
+}
+
 export function languageDiagnostics(imported, observed, report) {
   if (!report) return;
   const {lang, match, ranked, rtlParagraphs, theme} = observed;
@@ -259,9 +367,11 @@ export function languageDiagnostics(imported, observed, report) {
     if (rtlParagraphs) report({code: "rtl-language-mismatch", path: "language", message: `${rtlParagraphs} right-to-left paragraph(s) carry no run language, so no presentation language was imported.`});
     return;
   }
-  if (ranked.length > 1) {
+  // RR-05: a right-to-left deck's Latin phrases are their own en-US runs; they are not a second presentation language.
+  const languages = observedRtl(observed) ? ranked.filter(([tag]) => tag === lang || tag !== "en-US") : ranked;
+  if (languages.length > 1) {
     report({code: "mixed-run-languages", path: "language",
-      message: `Runs use ${ranked.length} languages (${ranked.map(([tag, count]) => `${tag} x${count}`).join(", ")}). OPF has one presentation language, so ${lang} was imported.`});
+      message: `Runs use ${languages.length} languages (${languages.map(([tag, count]) => `${tag} x${count}`).join(", ")}). OPF has one presentation language, so ${lang} was imported.`});
   }
   const kept = imported.language === observed.language;
   if (kept && !match) report({code: "language-uncatalogued", path: "language", message: `Run language ${lang} matches no languages catalog record; it was imported as a BCP-47 tag.`});
@@ -288,3 +398,26 @@ export function languageDiagnostics(imported, observed, report) {
     }
   }
 }
+
+/**
+ * FF-05: PptxGenJS writes every run's East Asian and complex-script font as a copy of the Latin face, with the
+ * charsets of other scripts (-122, -120). PowerPoint lists such a run font as an empty-name font in
+ * Presentation.Fonts and hides the real one (the charset is not the cause: a bare typeface does the same).
+ * PowerPoint's own runs name only the Latin face; East Asian and complex-script faces come from the paragraph or
+ * master style and the theme slots (+mn-ea, +mn-cs), which the exporter writes. A run keeps no explicit ea/cs
+ * typeface; theme references stay.
+ */
+export function stripRunScriptFonts(xml) {
+  return xml.replace(/<a:(?:ea|cs)\s+typeface="(?!\+)[^"]*"[^>]*\/>/g, "");
+}
+
+/**
+ * Without core's resolver the theme's East Asian slot still repeats the latin family of its font group, which keeps
+ * the paragraph end marks from reading an empty font (see themeScriptFonts).
+ */
+export function themeEastAsianFromLatin(xml) {
+  return xml.replace(/<a:(majorFont|minorFont)>[\s\S]*?<\/a:\1>/g, block => {
+    const latin = /<a:latin\b[^>]*\btypeface="([^"]+)"/.exec(block)?.[1];
+    return latin ? block.replace(/<a:ea typeface=""\/>/, `<a:ea typeface="${latin}"/>`) : block;
+  });
+}