@openpresentation/opf-pptx 0.13.2 → 0.15.0

package/dist/script-fonts.js

@@ -4,43 +4,31 @@
 // reads it back on import. Design: core docs/programs/font-fidelity-everywhere/
 // script-font-model.md ("OOXML mapping").
 //
-// Core releases before the resolver (0.11.0 and earlier) export no
-// resolveScriptFonts. The exporter then writes exactly what it wrote before
-// FF-07 (lang="en-US", empty theme ea/cs, no rtl) and reports
-// `language-export-unavailable` for a document that names a language. A core
-// with the resolver but without paragraphDirection() marks no paragraph
-// direction and reports `paragraph-direction-unavailable` for an RTL deck.
-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;
+// When the resolver throws for a deck, the exporter writes what it wrote before FF-07 (lang="en-US", empty theme ea/cs, no
+// rtl) and reports `language-export-unavailable`.
+import {paragraphDirection, physicalAlignment, resolveScriptFonts as coreResolveScriptFonts} from "@openpresentation/opf/composition";
 
-const SCRIPT_SLOTS = [["ea", "eastAsian"], ["cs", "complexScript"]];
+// OPF 0.15 (FA-23): core resolves the font-scheme references a deck or a language object names against the document's
+// catalogs and the host's registered `catalogs` (Catalog[]), the same option the slide context takes. `catalogs` is passed
+// only when the host gave one, so core's own default applies otherwise.
+const resolver = (input, options = {}, catalogs = undefined) => coreResolveScriptFonts(input, catalogs === undefined ? options : {...options, catalogs});
 
-/** Whether the installed core exports the FF-18 language/script resolver. */
-export function scriptFontsAvailable() {
-  return resolver !== null;
-}
+// RR-05: authored alignment is logical for right-to-left text (`left` is the start edge). Core owns the rule, and the
+// paragraph-direction rule is the one the renderer shares (core FF-07).
+export {physicalAlignment};
+
+const SCRIPT_SLOTS = [["ea", "eastAsian"], ["cs", "complexScript"]];
 
 /**
  * Resolve the deck (slide 0, which also sets the theme) and every slide.
- * Returns null when core has no resolver.
+ * Returns null when the resolver throws for the deck.
  */
-export function planScriptFonts(presentation, report) {
-  if (!resolver) {
-    if (presentation.language !== undefined) report?.({code: "language-export-unavailable", path: "language",
-      message: "The installed @openpresentation/opf has no resolveScriptFonts, so the PPTX keeps lang=\"en-US\", empty theme East Asian/complex-script fonts and left-to-right paragraphs. Use a core release with the FF-18 language model."});
-    return null;
-  }
+export function planScriptFonts(presentation, report, {catalogs} = {}) {
   const count = Array.isArray(presentation.slides) ? presentation.slides.length : 0;
   let slides, deck;
   try {
-    slides = Array.from({length: count}, (_, slideIndex) => resolver(presentation, {slideIndex}));
-    deck = slides[0] ?? resolver(presentation);
+    slides = Array.from({length: count}, (_, slideIndex) => resolver(presentation, {slideIndex}, catalogs));
+    deck = slides[0] ?? resolver(presentation, {}, catalogs);
   } catch (error) {
     // Keep exporting as before FF-07 rather than failing on the language model.
     report?.({code: "language-export-unavailable", path: "language",
@@ -49,17 +37,65 @@ export function planScriptFonts(presentation, report) {
   }
   if (presentation.language !== undefined && deck.languageSource === "default") {
     report?.({code: "language-unresolved", path: "language",
-      message: `The presentation language could not be resolved locally (a URL, pkg: reference or unknown id), so the PPTX uses ${deck.lang}.`});
-  }
-  let rtl = deck.rtl;
-  if (rtl && !paragraphDirection) {
-    rtl = false;
-    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."});
+      message: `The presentation language could not be resolved (a BCP-47 tag whose script core does not know), so the PPTX uses ${deck.lang}.`});
   }
   // opf-pptx#168: which slides have notes (a presentation has one notes master; see reportPerSlideNotesScriptFonts).
   const notes = (presentation.slides ?? []).map(slide => typeof slide?.notes === "string" ? slide.notes.trim() !== "" : Boolean(slide?.notes));
-  return {deck, slides, notes, report, lang: deck.lang, rtl, contentEastAsian: contentEastAsianFonts(presentation, deck, report)};
+  return {deck, slides, notes, report, lang: deck.lang, rtl: deck.rtl, presentation, catalogs, contentEastAsian: contentEastAsianFonts(presentation, deck, report, catalogs)};
+}
+
+/**
+ * FA-13: the OOXML tag a run's own `lang` (TextRun.lang) is written with: core's curated tag for the language (fr becomes
+ * fr-FR), or undefined when it is the deck language (the run then follows the deck). Without a plan the tag is written as given.
+ */
+export function runLanguageTag(plan, tag) {
+  if (typeof tag !== "string" || !tag) return undefined;
+  if (!plan) return tag.toLowerCase() === "en-us" ? undefined : tag;
+  const cache = plan.runLanguages ??= new Map();
+  if (!cache.has(tag)) {
+    let lang = tag;
+    try {
+      const resolved = resolver(plan.presentation, {language: tag}, plan.catalogs);
+      if (resolved.languageSource !== "default") lang = resolved.lang;
+    } catch { /* an unresolvable tag is written as given */ }
+    cache.set(tag, lang.toLowerCase() === String(plan.lang).toLowerCase() ? undefined : lang);
+  }
+  return cache.get(tag);
+}
+
+/**
+ * FA-13: a run with its own language (TextRun.lang) names the East Asian and complex-script faces of that language, so a Han
+ * run tagged ja-JP draws in the Japanese face and one tagged zh-CN in the Simplified Chinese face, as the preview does. Only a
+ * slot with a script-specific font for the run's language is written; every other run keeps following the theme. Runs the
+ * exporter writes carry no ea/cs of their own (stripRunScriptFonts), so this runs after that strip. `xml` is a slide part.
+ */
+export function runLanguageFonts(xml, plan, slideIndex) {
+  if (!plan || !xml.includes(' altLang="en-US"')) return xml;
+  return xml.replace(/<p:(sp|graphicFrame)>[\s\S]*?<\/p:\1>/g, shape => {
+    const heading = /<p:cNvPr\b[^>]*\bname="OPF heading /.test(shape);
+    return shape.replace(OWN_LANGUAGE_RUN, (run, lang) => {
+      const resolved = runScriptPlan(plan, slideIndex, lang);
+      if (!resolved) return run;
+      const slots = heading ? resolved.heading : resolved.body;
+      const latin = /<a:latin typeface="([^"]*)"/.exec(run)?.[1];
+      const insert = SCRIPT_SLOTS.map(([element, slot]) => {
+        const face = slots?.[slot];
+        return resolved.sources?.[slot] !== "latin" && face && escapeAttribute(face) !== latin && !new RegExp(`<a:${element}\\b`).test(run) ? `<a:${element} typeface="${escapeAttribute(face)}"/>` : "";
+      }).join("");
+      return insert ? run.replace(/(<a:latin\b[^>]*\/>)/, `$1${insert}`) : run;
+    });
+  });
+}
+
+/** The script fonts of one slide for a run language (FA-13), memoized; undefined when the language cannot be resolved. */
+function runScriptPlan(plan, slideIndex, lang) {
+  const cache = plan.runScripts ??= new Map(), key = `${slideIndex}|${lang}`;
+  if (!cache.has(key)) {
+    let resolved;
+    try { resolved = resolver(plan.presentation, {slideIndex, language: lang}, plan.catalogs); } catch { resolved = undefined; }
+    cache.set(key, resolved && resolved.languageSource !== "default" ? resolved : undefined);
+  }
+  return cache.get(key);
 }
 
 // ---------------------------------------------------------------------------
@@ -162,7 +198,7 @@ export function reportPerSlideNotesScriptFonts(plan, {themes, assignment}) {
 // 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) {
+function contentEastAsianFonts(presentation, deck, report, catalogs) {
   if (deck.sources.eastAsian !== "latin") return null;
   let kana = false, hangul = false, han = false;
   const seen = new Set();
@@ -175,10 +211,10 @@ function contentEastAsianFonts(presentation, deck, report) {
     }
   };
   walk(presentation.slides);
-  const language = kana ? "japanese" : hangul ? "korean" : han ? "chinese-simplified" : null;
+  const language = kana ? "ja" : hangul ? "ko" : han ? "zh-Hans" : null;
   if (!language) return null;
   try {
-    const resolved = resolver({...presentation, language}, {slideIndex: 0});
+    const resolved = resolver({...presentation, language}, {slideIndex: 0}, catalogs);
     return resolved.sources.eastAsian === "latin" ? null : {heading: resolved.heading.eastAsian, body: resolved.body.eastAsian};
   } catch (error) {
     report?.({code: "language-export-unavailable", path: "language",
@@ -274,7 +310,9 @@ function runScriptFonts(xml, resolved, headingShape) {
   });
 }
 
-const RUN_LANGUAGE = /(<a:(?:rPr|endParaRPr|defRPr)\b[^>]*?\slang=")en-US(")/g;
+// A run with its own language (TextRun.lang, FA-13) is written with an altLang attribute; the deck language never replaces it.
+const RUN_LANGUAGE = /(<a:(?:rPr|endParaRPr|defRPr)\b[^>]*?\slang=")en-US("(?! altLang="))/g;
+const OWN_LANGUAGE_RUN = /<a:rPr\b[^>]*?\slang="([^"]+)" altLang="en-US"[^>]*[^/]>[\s\S]*?<\/a:rPr>/g;
 
 const decodeText = value => value.replace(/&(?:#(\d+)|#x([0-9a-f]+)|(amp|lt|gt|quot|apos));/gi, (entity, decimal, hex, name) =>
   decimal ? String.fromCodePoint(Number(decimal)) : hex ? String.fromCodePoint(parseInt(hex, 16)) : {amp: "&", lt: "<", gt: ">", quot: "\"", apos: "'"}[name.toLowerCase()]);
@@ -392,41 +430,14 @@ export function partScriptFonts(path, xml, plan, slideIndex) {
 const LANGUAGE_TAG = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/;
 const attribute = (xml, name) => new RegExp(`\\s${name}="([^"]*)"`).exec(xml)?.[1];
 
-/**
- * Match an OOXML run language to the OPF language to import. A catalog id is
- * used when that record exports exactly this tag again: an exact BCP-47 tag,
- * then a curated `ooxmlLang` (preferring the same primary language). A tag
- * that core still resolves to a catalog record (for example en-NZ to English)
- * is imported as the tag itself, so it round-trips. Without core's resolver,
- * a record whose tag is the primary language alone is accepted too.
- * Returns {language, record, shared} or null when nothing matches.
- */
-export function matchCatalogLanguage(lang, catalogs) {
-  const records = Array.isArray(catalogs?.languages) ? catalogs.languages : [];
-  const key = lang.toLowerCase(), primary = key.split("-")[0];
-  const lower = value => typeof value === "string" ? value.toLowerCase() : undefined;
-  const shared = records.filter(record => lower(record.bcp47) === key || lower(record.ooxmlLang) === key);
-  const exports = record => !resolver || resolver({language: record.id}).lang.toLowerCase() === key;
-  const record = shared.find(record => lower(record.bcp47) === key && exports(record))
-    ?? shared.find(record => lower(record.bcp47)?.split("-")[0] === primary && exports(record))
-    ?? shared.find(exports);
-  if (record) return {language: record.id, record, shared};
-  if (resolver) {
-    const resolved = resolver({language: lang});
-    // A tag core cannot resolve falls back to its default language; that is no match.
-    const matched = resolved.languageSource !== "default" && resolved.languageId && records.find(candidate => candidate.id === resolved.languageId);
-    return matched ? {language: lang, record: matched, shared: []} : null;
-  }
-  const byPrimary = records.find(candidate => lower(candidate.bcp47) === primary);
-  return byPrimary ? {language: byPrimary.id, record: byPrimary, shared: []} : null;
-}
-
 /**
  * Observe the presentation language in run `lang`. `slides` and `theme` are
- * XML strings. `language` is a catalog id, the run's tag when no catalog
- * record matches, or undefined when the runs carry no language; `lang` is the
- * dominant run tag itself. Nothing is reported here: languageDiagnostics()
- * reports against the final imported document, after FF-32 provenance.
+ * XML strings. `language` is the dominant run tag, imported as a BCP-47 tag
+ * string (OPF 0.15: language is an engine vocabulary, not a catalog), or
+ * undefined when the runs carry no language; `lang` is the same tag.
+ * `catalogs` are the host's registered catalogs, for the font schemes core
+ * resolves. Nothing is reported here: languageDiagnostics() reports against
+ * the final imported document, after FF-32 provenance.
  */
 export function observeLanguage({slides, theme, themePath, slideThemes, catalogs}) {
   const counts = new Map();
@@ -441,8 +452,7 @@ export function observeLanguage({slides, theme, themePath, slideThemes, catalogs
   }
   const ranked = [...counts].sort((left, right) => right[1] - left[1] || (left[0] < right[0] ? -1 : left[0] > right[0] ? 1 : 0));
   const lang = ranked[0]?.[0];
-  const match = lang === undefined ? null : matchCatalogLanguage(lang, catalogs);
-  return {lang, language: lang === undefined ? undefined : match?.language ?? lang, match, ranked, rtlParagraphs, theme, themePath, slideThemes};
+  return {lang, language: lang, ranked, rtlParagraphs, theme, themePath, slideThemes, catalogs};
 }
 
 /**
@@ -454,32 +464,30 @@ export function observeLanguage({slides, theme, themePath, slideThemes, catalogs
  */
 export function reconcileLanguage(groups, observed, report) {
   const index = groups.findIndex(item => item.field === "language");
-  if (index < 0 || observed.lang === undefined || !resolver) return groups;
+  if (index < 0 || observed.lang === undefined) return groups;
   const stored = groups[index].ops.find(op => op.path?.length === 1 && op.path[0] === "language")?.value;
   if (stored === undefined) return groups;
-  const resolved = resolver({language: stored});
+  const resolved = resolver({language: stored}, {}, observed.catalogs);
   if (resolved.languageSource === "default" || resolved.lang.toLowerCase() === observed.lang.toLowerCase()) return groups;
   report?.({code: "metadata-reference-changed", path: "language",
     message: `Runs now use ${observed.lang}, not ${resolved.lang} of the stored language, so the stored language was not restored; the imported language follows the runs.`});
   return groups.filter((_, position) => position !== index);
 }
 
-/**
- * Diagnostics for the final imported document: several run languages, a run
- * tag that maps ambiguously or to no catalog record (only when that observed
- * language was kept), right-to-left paragraphs under a left-to-right
- * 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; }
+  try { return resolver({language: observed.language}, {}, observed.catalogs).rtl === true; } catch { return false; }
 }
 
+/**
+ * Diagnostics for the final imported document: several run languages,
+ * right-to-left paragraphs under a left-to-right language, and theme East
+ * Asian/complex-script fonts the document does not reproduce.
+ */
 export function languageDiagnostics(imported, observed, report) {
   if (!report) return;
-  const {lang, match, ranked, rtlParagraphs, theme} = observed;
+  const {lang, ranked, rtlParagraphs, theme, catalogs} = observed;
   if (lang === undefined) {
     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;
@@ -488,22 +496,15 @@ export function languageDiagnostics(imported, observed, report) {
   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 ${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.`});
-  else if (kept && match.shared.length > 1 && !match.shared.some(record => record.bcp47?.toLowerCase() === lang.toLowerCase())) {
-    report({code: "language-ambiguous", path: "language",
-      message: `Run language ${lang} is the OOXML tag of ${match.shared.map(record => record.id).join(", ")}; ${match.language} 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; a run in another language keeps it as its own lang where the text imports as rich text.`});
   }
-  const resolved = resolver ? resolver(imported) : null;
-  const rtl = resolved ? resolved.rtl : match?.record.direction === "rtl";
-  if (rtlParagraphs && !rtl) {
+  const resolved = resolver(imported, {}, catalogs);
+  if (rtlParagraphs && !resolved.rtl) {
     report({code: "rtl-language-mismatch", path: "language", message: `${rtlParagraphs} right-to-left paragraph(s) do not match the left-to-right language ${typeof imported.language === "string" ? imported.language : lang}; paragraph direction is not imported separately.`});
   }
   // The presentation theme carries the first slide's script fonts (planScriptFonts), so it is compared with that slide.
   let themeResolved = resolved;
-  if (resolver && imported.slides?.length) { try { themeResolved = resolver(imported, {slideIndex: 0}); } catch { themeResolved = resolved; } }
+  if (imported.slides?.length) { try { themeResolved = resolver(imported, {slideIndex: 0}, catalogs); } catch { themeResolved = resolved; } }
   if (theme && themeResolved) {
     for (const {tag, slot, face} of themeScriptMismatches(theme, themeResolved)) {
       report({code: "script-font-not-imported", path: "design.fontScheme",
@@ -511,11 +512,11 @@ export function languageDiagnostics(imported, observed, report) {
     }
   }
   // opf-pptx#168: a slide on another slide master carries its own script fonts in that master's theme.
-  if (resolver && Array.isArray(observed.slideThemes)) {
+  if (Array.isArray(observed.slideThemes)) {
     observed.slideThemes.forEach((slideTheme, index) => {
       if (!slideTheme || slideTheme.path === observed.themePath) return;
       let slideResolved;
-      try { slideResolved = resolver(imported, {slideIndex: index}); } catch { return; }
+      try { slideResolved = resolver(imported, {slideIndex: index}, catalogs); } catch { return; }
       for (const {tag, slot, face} of themeScriptMismatches(slideTheme.xml, slideResolved)) {
         report({code: "script-font-not-imported", path: `slides.${index}.design.fontScheme`,
           message: `Slide ${index + 1}'s master theme ${tag} ${slot} font "${face}" differs from both its latin font and what the imported slide resolves, and is not represented in the imported OPF.`});
@@ -553,8 +554,8 @@ export function stripRunScriptFonts(xml) {
 }
 
 /**
- * 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).
+ * When the resolver throws for a deck (see planScriptFonts) 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 => {

package/dist/theme-colors.js

@@ -36,7 +36,7 @@ const VENDOR_VALUES = new Set(['tx1', 'tx2', 'bg1', 'bg2', 'accent1', 'accent2',
 const ROLE_SLOTS = Object.freeze({
   primary: ['accent1'],
   secondary: ['accent2'],
-  accent: ['accent1', 'accent3'],
+  accent: ['accent3'],
   text: ['dark1', 'light1'],
   textSecondary: ['dark2', 'light2'],
   surface: ['light2', 'dark2'],
@@ -213,9 +213,11 @@ function recordColors(record) {
 
 /**
  * Recover design.colorScheme from theme clrScheme colors.
- * An exact twelve-slot match with a catalog record yields its id (the clrScheme
- * name breaks ties). Otherwise the colors are inline: relative to the record
- * whose name the clrScheme carries, or as all readable slots.
+ * `records` are the colour schemes a bare id can name in the imported document
+ * (FA-23: the host default catalog's, each with its key as `id`; none when the
+ * host registers no catalog). An exact twelve-slot match yields that bare id
+ * (the clrScheme name breaks ties). Otherwise the colors are inline: relative
+ * to the record whose name the clrScheme carries, or as all readable slots.
  */
 export function recoverColorScheme({colors, unreadable, name}, records) {
   const complete = unreadable.length === 0;
@@ -245,19 +247,22 @@ export function presentationThemePath(presentationRoot, presentationRels, relati
 }
 
 /**
- * Identify a catalog theme from the native theme name. The name must equal a
- * catalog theme name, and the package must corroborate it with that theme's
- * color scheme or its heading/body font pair, so a foreign deck that happens to
- * use a theme called "Bold" is not bound to the OPF theme.
+ * Identify a catalog theme from the native theme name. `themes` are the theme
+ * records a bare id can name (as for recoverColorScheme, each with its key as
+ * `id`); `colorScheme(theme)` and `fontFamilies(theme)` resolve the theme's own
+ * references (null when they resolve nowhere). The name must equal a theme
+ * name, and the package must corroborate it with that theme's color scheme or
+ * its heading/body font pair, so a foreign deck that happens to use a theme
+ * called "Bold" is not bound to the OPF theme.
  */
-export function recoverTheme({themeName, colors, majorFont, minorFont}, {themes, colorSchemes, fontFamilies}) {
+export function recoverTheme({themeName, colors, majorFont, minorFont}, {themes, colorScheme, fontFamilies}) {
   if (!themeName) return {};
   const theme = themes.find(record => record.name === themeName);
   if (!theme) return {};
-  const scheme = colorSchemes.find(record => record.id === theme.colorScheme);
+  const scheme = colorScheme(theme);
   const schemeColors = scheme ? recordColors(scheme) : null;
   const colorMatch = !!schemeColors && THEME_SLOTS.every(([slot]) => schemeColors[slot] === colors[slot]);
-  const fonts = fontFamilies(theme.fontScheme);
+  const fonts = fontFamilies(theme);
   const fontMatch = !!fonts && fonts.heading === majorFont && fonts.body === minorFont;
   return colorMatch || fontMatch ? {id: theme.id} : {unverified: theme.id};
 }

package/dist/timeline-provenance.js

@@ -1,8 +1,9 @@
 import {XMLParser} from 'fast-xml-parser';
-import {validatePresentation} from '@openpresentation/opf';
+import {isValidFormat} from './format-check.js';
 import {attachTextTags,decodeTextTag} from './code-provenance.js';
 import {sourceLineParagraphs} from './text-provenance.js';
 
+const STATUSES=['done','current','planned'];
 const TAG='OPF_TIMELINE_V1',REL='http://schemas.openxmlformats.org/officeDocument/2006/relationships/tags';
 const parser=new XMLParser({ignoreAttributes:false,attributeNamePrefix:'',parseTagValue:false,trimValues:false});
 const decoder=new TextDecoder('utf-8',{fatal:true}),array=value=>value===undefined?[]:Array.isArray(value)?value:[value];
@@ -49,16 +50,22 @@ export function importTimelineGroups(shapes,paragraphs,relationships,entries,rep
   for(const group of groups.values())try{
     const anchors=group.filter(item=>item.data.anchor!==undefined);if(anchors.length!==1)throw Error('Missing or duplicated timeline anchor.');
     const anchor=anchors[0],manifest=anchor.data.anchor,count=validateManifest(manifest);
-    const total=count+manifest.eventCount+1;
+    // A current event's ring is a second native ellipse with its own tag, so the group has one more shape per ring.
+    const total=count+manifest.eventCount+1+group.filter(item=>item.data.role==='ring').length;
     if(anchor.data.role!=='text'||anchor.data.part!==0||anchor.data.line!==0||group.length!==total||new Set(group.map(item=>item.shape)).size!==total)throw Error('Incomplete or duplicated timeline elements.');
-    const ordered=manifest.parts.map(part=>Array(part.lines)),markers=new Set();let connectors=0;
+    const ordered=manifest.parts.map(part=>Array(part.lines)),markers=new Set(),rings=new Set(),statuses=new Map();let connectors=0;
     for(const item of group){
       if(item.ambiguous)throw Error('Multiple source identities on one timeline shape.');
-      if(item.data.role==='connector'||item.data.role==='marker'){
+      if(item.data.role==='connector'||item.data.role==='marker'||item.data.role==='ring'){
         const expected=item.data.role==='connector'?'line':'ellipse';
         if(item.shape['p:spPr']?.['a:prstGeom']?.prst!==expected||(paragraphs[item.index]??[]).some(paragraph=>paragraph.text||paragraph.bullet))throw Error('Timeline graphic now contains different geometry or native text.');
         if(item.data.role==='connector'){if(++connectors>1)throw Error('Duplicated timeline connector.');}
-        else{const index=item.data.eventIndex;if(!Number.isSafeInteger(index)||index<0||index>=manifest.eventCount||markers.has(index))throw Error('Ambiguous timeline marker.');markers.add(index);}
+        else{
+          const index=item.data.eventIndex,known=item.data.role==='marker'?markers:rings;
+          if(!Number.isSafeInteger(index)||index<0||index>=manifest.eventCount||known.has(index))throw Error('Ambiguous timeline marker.');
+          known.add(index);
+          if(item.data.role==='marker'&&item.data.status!==undefined){if(!STATUSES.includes(item.data.status))throw Error('Invalid timeline event status.');statuses.set(index,item.data.status);}
+        }
         continue;
       }
       const {part,line}=item.data;
@@ -66,13 +73,17 @@ export function importTimelineGroups(shapes,paragraphs,relationships,entries,rep
       ordered[part][line]=item;
     }
     if(connectors!==1||markers.size!==manifest.eventCount)throw Error('Incomplete timeline graphics.');
+    // Only a current event has a ring, and every current event has one.
+    for(const index of rings)if(statuses.get(index)!=='current')throw Error('Timeline ring without a current event.');
+    for(const [index,status] of statuses)if(status==='current'&&!rings.has(index))throw Error('Current timeline event without its ring.');
     const result={events:Array.from({length:manifest.eventCount},()=>({}))};
     for(const [index,part]of manifest.parts.entries()){
       const text=sourceLineParagraphs(ordered[index],paragraphs)[0].text;
       if(part.eventIndex===undefined)result[part.field]=text;else result.events[part.eventIndex][part.field]=text;
     }
+    for(const [index,status] of statuses)result.events[index].status=status;
     const timeline=manifest.shorthand?result.events:result;
-    if(!validatePresentation({slides:[{timeline}]}).valid)throw Error('Current native text does not form a valid timeline.');
+    if(!isValidFormat({slides:[{timeline}]}))throw Error('Current native text does not form a valid timeline.');
     for(const item of group)consumed.add(item.shape);
     items.push({shapes:group.map(item=>item.shape),payload:{type:'timeline',timeline}});
     report({code:'timeline-import-reflow',message:'Timeline field order, source boundaries and current native text were recovered. Native formatting, positions, marker styling and font theme are not reconstructed; review the reflowed timeline.'});

package/dist/typeface-inventory.js

@@ -7,7 +7,7 @@ import {unzipSync} from 'fflate';
 // DrawingML `typeface` attributes (latin, ea, cs, sym, buFont, theme script
 // supplements, embedded-font lists), SpreadsheetML font names (styles `name`,
 // rich-text `rFont`) and the docProps/app.xml "Fonts Used" list.
-// checkPptxTypefaces() then applies the owner font policy: a package names only
+// checkTypefaces() then applies the owner font policy: a package names only
 // the fonts its author chose, plus theme references that resolve to them, empty
 // theme script slots when no script font was selected (as in Office's themes; FF-49 checks a selected slot through options.themeScripts) and the documented theme script supplements.
 
@@ -33,7 +33,7 @@ export const THEME_SCRIPT_SUPPLEMENTS = Object.freeze({
   minor: supplement(`Jpan=游ゴシック|Hans=等线|Arab=Arial|Hebr=Arial|Thai=Cordia New|Khmr=DaunPenh|Viet=Arial|${SHARED_SCRIPTS}`)
 });
 
-export function inventoryPptxTypefaces(input, options = {}) {
+export function inventoryTypefaces(input, options = {}) {
   const typefaces = [];
   const themes = {};
   // Every theme part's fonts, and the theme each part of the presentation package resolves its references against.
@@ -90,15 +90,15 @@ export function packageFontsUsed(inventory) {
   return [...used].sort(compareFontNames);
 }
 
-export function checkPptxTypefaces(input, options = {}) {
-  if (!Array.isArray(options.fonts) || options.fonts.some(font => typeof font !== 'string' || !font)) {
-    throw new TypeError('checkPptxTypefaces requires options.fonts, the non-empty family names the author chose.');
+export function checkTypefaces(input, options = {}) {
+  if (!Array.isArray(options.families) || options.families.some(family => typeof family !== 'string' || !family)) {
+    throw new TypeError('checkTypefaces requires options.families, the non-empty family names the author chose.');
   }
-  const chosen = new Set(options.fonts);
+  const chosen = new Set(options.families);
   const monospace = new Set(options.monospace ?? []);
   const allowEmpty = options.allowEmptyThemeScripts ?? true;
   const supplements = options.scriptSupplements ?? THEME_SCRIPT_SUPPLEMENTS;
-  const inventory = inventoryPptxTypefaces(input);
+  const inventory = inventoryTypefaces(input);
   const violations = [];
   const fail = (entry, reason, details = {}) => violations.push({reason, part: entry.part, element: entry.element, typeface: entry.typeface, ...details});
   const emptyAllowed = entry => allowEmpty && entry.theme && (entry.element === 'ea' || entry.element === 'cs');
@@ -117,7 +117,7 @@ export function checkPptxTypefaces(input, options = {}) {
     }
     const reference = THEME_REFERENCE.exec(entry.typeface);
     if (reference) {
-      if (entry.resolved === null) fail(entry, 'unresolved-theme-reference');
+      if (entry.resolved === null) fail(entry, 'theme-reference-unresolved');
       else if (entry.resolved === '') { if (!allowEmpty || reference[2] === 'lt') fail(entry, 'empty-theme-reference'); }
       else if (!chosen.has(entry.resolved)) fail(entry, 'foreign-theme-reference', {resolved: entry.resolved});
       continue;

package/dist/watermark-provenance.js

@@ -19,6 +19,8 @@ const canonical = value => JSON.stringify(value, (_key, item) => item && typeof
   ? Object.fromEntries(Object.keys(item).sort().filter(key => !(key === '#text' && typeof item[key] === 'string' && !item[key].trim())).map(key => [key, item[key]])) : item);
 
 export const watermarkName = () => 'OPF watermark';
+// FA-13: a text watermark is one native text box (a p:sp), not a picture.
+export const watermarkTextName = () => 'OPF watermark text';
 
 // The preview's frame: x/y at 30% and a 40% by 40% box, in the slide's units.
 export const watermarkBox = (width, height) => ({x: width * .3, y: height * .3, w: width * .4, h: height * .4});
@@ -80,6 +82,7 @@ function attachTags(entries, manifests) {
   const NS = 'http://schemas.openxmlformats.org/presentationml/2006/main', types = [];
   let count = 0;
   for (const [part, manifest] of manifests) {
+    const element = manifest.kind === 'text' ? 'sp' : 'pic', name = manifest.kind === 'text' ? watermarkTextName() : watermarkName();
     const relPath = part.replace('/slides/', '/slides/_rels/') + '.rels';
     const rels = decoder.decode(entries[relPath]);
     const ids = new Set([...rels.matchAll(/\bId="([^"]+)"/g)].map(match => match[1]));
@@ -90,11 +93,11 @@ function attachTags(entries, manifests) {
     types.push(`<Override PartName="/${tagPart}" ContentType="application/vnd.openxmlformats-officedocument.presentationml.tags+xml"/>`);
     entries[relPath] = encoder.encode(rels.replace('</Relationships>', `<Relationship Id="${id}" Type="${REL}" Target="../tags/opfWatermark${count}.xml"/></Relationships>`));
     let attached = false;
-    const xml = decoder.decode(entries[part]).replace(/<p:pic>[\s\S]*?<\/p:pic>/g, picture => {
-      if (attached || picture.match(/<p:cNvPr\b[^>]*\bname="([^"]+)"/)?.[1] !== watermarkName()) return picture;
+    const xml = decoder.decode(entries[part]).replace(new RegExp(`<p:${element}>[\\s\\S]*?</p:${element}>`, 'g'), picture => {
+      if (attached || picture.match(/<p:cNvPr\b[^>]*\bname="([^"]+)"/)?.[1] !== name) return picture;
       attached = true;
       picture = picture.replace(/<p:nvPr\s*\/>/, '<p:nvPr></p:nvPr>');
-      if (!picture.includes('</p:nvPr>')) throw new Error('Generated watermark picture has no native application properties.');
+      if (!picture.includes('</p:nvPr>')) throw new Error('Generated watermark shape has no native application properties.');
       return picture.replace('</p:nvPr>', `<p:custDataLst><p:tags r:id="${id}"/></p:custDataLst></p:nvPr>`);
     });
     entries[part] = encoder.encode(xml);
@@ -102,6 +105,28 @@ function attachTags(entries, manifests) {
   entries['[Content_Types].xml'] = encoder.encode(decoder.decode(entries['[Content_Types].xml']).replace('</Types>', types.join('') + '</Types>'));
 }
 
+/**
+ * Bind each generated text watermark box to its manifest with a native tag.
+ * marks: Map<slidePart, {slide, text, opacity}>. The manifest records the text and the exact native geometry
+ * (position, size and rotation), so an unchanged box imports back as design.watermark.
+ */
+export function tagTextWatermarks(entries, marks) {
+  if (!marks.size) return;
+  const manifests = new Map();
+  for (const part of Object.keys(entries).filter(path => /^ppt\/slides\/slide\d+\.xml$/.test(path))) {
+    const mark = marks.get(part);
+    if (!mark) continue;
+    let found = 0;
+    for (const shape of decoder.decode(entries[part]).match(/<p:sp>[\s\S]*?<\/p:sp>/g) ?? []) {
+      if (shape.match(/<p:cNvPr\b[^>]*\bname="([^"]+)"/)?.[1] !== watermarkTextName()) continue;
+      found++;
+      manifests.set(part, {v: 1, kind: 'text', slide: mark.slide, text: mark.text, opacity: mark.opacity, properties: parser.parse(shape)['p:sp']['p:spPr']});
+    }
+    if (found !== 1) throw new Error('Missing generated watermark text box.');
+  }
+  attachTags(entries, manifests);
+}
+
 function readTags(container, relationships, entries) {
   const tags = [];
   let unreadable = false;
@@ -113,6 +138,43 @@ function readTags(container, relationships, entries) {
   return {tags, unreadable};
 }
 
+/**
+ * Recover a text design.watermark from an unchanged tagged text box. paragraphs[index] are the native paragraphs of
+ * shapes[index]. Returns the consumed shape indexes and the slide design fields to restore. A box whose text, position,
+ * size or rotation changed stays an ordinary text box and is reported.
+ */
+export function importTextWatermark(shapes, paragraphs, relationships, entries, slideIndex, report) {
+  const consumed = new Set(), found = [];
+  for (const [index, shape] of shapes.entries()) {
+    const {tags, unreadable} = readTags(shape['p:nvSpPr']?.['p:nvPr']?.['p:custDataLst'], relationships, entries);
+    const own = tags.filter(tag => tag.name?.toUpperCase() === TAG);
+    if (!own.length) continue;
+    // The picture watermark has the same tag name; a picture's manifest has no kind and is read by importWatermark.
+    let kind;
+    try { kind = decodeTextTag(own[0].val)?.kind; } catch { kind = undefined; }
+    if (kind !== 'text') continue;
+    found.push({index, shape, own, unreadable, others: tags.some(tag => /^OPF_/i.test(tag.name) && tag.name.toUpperCase() !== TAG)});
+  }
+  if (!found.length) return {consumed};
+  const invalid = () => report({code: 'invalid-watermark-provenance', message: 'An edited, ambiguous or invalid tagged OPF watermark was imported as ordinary text. It is not reconstructed as design.watermark.'});
+  if (found.length > 1) { invalid(); return {consumed}; }
+  const [{index, shape, own, unreadable, others}] = found;
+  try {
+    if (unreadable || others || own.length !== 1) throw Error('Ambiguous watermark identity.');
+    const manifest = decodeTextTag(own[0].val);
+    if (manifest?.v !== 1 || manifest.kind !== 'text' || manifest.slide !== `slides.${slideIndex}` || typeof manifest.text !== 'string' || !manifest.text
+      || typeof manifest.opacity !== 'number' || !(manifest.opacity >= 0 && manifest.opacity <= 1)) throw Error('Invalid watermark manifest.');
+    if (shape['p:nvSpPr']?.['p:cNvPr']?.name !== watermarkTextName()) throw Error('Watermark identity changed.');
+    if (canonical(shape['p:spPr']) !== canonical(manifest.properties)) throw Error('Watermark geometry changed.');
+    if ((paragraphs[index] ?? []).map(paragraph => paragraph.text).join('\n') !== manifest.text) throw Error('Watermark text changed.');
+    consumed.add(index);
+    return {consumed, design: {watermark: {text: manifest.text, opacity: manifest.opacity}}};
+  } catch {
+    invalid();
+    return {consumed};
+  }
+}
+
 /**
  * Recover design.watermark from an unchanged tagged picture. Returns the
  * consumed picture indexes and the slide design fields to restore.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpresentation/opf-pptx",
-  "version": "0.13.2",
+  "version": "0.15.0",
   "description": "Pure local OPF to PPTX export and PPTX to OPF import tooling.",
   "license": "MIT",
   "type": "module",
@@ -65,7 +65,7 @@
   },
   "dependencies": {
     "@node-projects/jszip": "4.3.0",
-    "@openpresentation/opf": "^0.13.0",
+    "@openpresentation/opf": "^0.15.1",
     "@rgrove/parse-xml": "4.2.3",
     "fast-xml-parser": "^5.8.0",
     "fflate": "^0.8.3",
@@ -73,7 +73,7 @@
     "sharp": "0.35.5"
   },
   "peerDependencies": {
-    "@openpresentation/opf-render": "^0.13.1"
+    "@openpresentation/opf-render": "^0.15.0"
   },
   "peerDependenciesMeta": {
     "@openpresentation/opf-render": {
@@ -82,7 +82,7 @@
   },
   "devDependencies": {
     "@expo-google-fonts/carlito": "0.4.1",
-    "@openpresentation/opf-render": "0.13.1",
+    "@openpresentation/opf-render": "0.15.0",
     "esbuild": "0.28.2",
     "playwright": "1.63.0"
   },