@openpresentation/opf-pptx 0.11.9 → 0.12.1

package/README.md

@@ -1,6 +1,8 @@
 # OPF PPTX
 
-Version 0.11.9 exports an SVG image as a native SVG picture over a PNG fallback (rasterized in Node by the optional `@openpresentation/opf-render` peer or `options.svgRasterizer`; without one it stays the placeholder), writes a deck footer's first text, date and slide number as native PowerPoint Header & Footer placeholders (output change for decks with a footer; every export now carries the footer placeholders on its master, layout and notes master; see [native header and footer](docs/native-header-footer.md)) and adds the opt-in `fromPptx(bytes, {signals: true})`, which also returns the raw per-shape signals of every slide (see Import signals; the option leaves the default import unchanged; core floor `^0.11.4` unchanged, no API removed). Version 0.11.8 re-imports rich text that wraps over several native lines as the one authored payload instead of reporting `content-structure-changed` (the export records the line count; decks exported by earlier versions import as before; core floor `^0.11.4` unchanged, no API change). Version 0.11.7 requires `@openpresentation/opf` ^0.11.4 and exports the design fields natively (cover and section logos, header and footer logos, picture bullets, the accent font), writes every chart's text at the size the preview draws, round-trips the slide content structure, sections, extensions, assets and brand images through PPTX provenance (a fresh export of a plain deck re-imports in its authored form, so read a root payload field before `blocks[0]`), writes slide sections as PowerPoint's section list, and degrades an SVG image to the preview's placeholder instead of aborting; install it with renderer 0.11.9 and editor 0.10.6 so export and preview resolve the same core (no API removed). Version 0.11.6 exports the treemap, histogram, pareto, box-and-whisker, waterfall and funnel charts as native chartex parts by default (`toPptx({chartex: 'auto'})`; `world` stays a clustered column with `chart-data-adapted`; pass `chartex: 'fallback'` for the previous output) and gives chartex text the deck's label colour and font (no API removed). Version 0.11.5 writes the slide tag run as a theme color reference (`a:schemeClr accent1`) where the deck theme holds the primary there (no API change; the color is unchanged). Version 0.11.4 re-imports quote payloads (each native quote line carries an `OPF_QUOTE_V1` tag) and slide-image payloads from an unchanged export, writes the theme's `a:ea` and `a:cs` only for slots a script font is selected for, and requires core `^0.11.3` (the 70 legacy gallery layout ids and their geometry; install it with renderer 0.11.6 and editor 0.10.4 so export and preview resolve the same core; no API removed). Version 0.11.3 adds the opt-in `toPptx({ chartex: 'native' })` export of the seven chartex chart types and always imports chartex charts (no API removed; the default output is unchanged). Version 0.11.2 exports the classic chart types as native chart constructs and writes named and default table colours, text pairs and hyperlink colours as theme references (no API or dependency change; resolved colours are unchanged). Version 0.11.1 exports `design.watermark` as a native picture (it re-imports) and embeds byte-identical media parts once, with no API or dependency change. Version 0.11.0 requires core `^0.11.2` (cover slides are centered between header and footer furniture) and the optional `@openpresentation/opf-render` peer `^0.11.0`; install them together so export and preview resolve the same core. Version 0.10.0 required core `^0.11.1` and the peer `^0.10.0`. It adds native slide-number and date fields, socials, slide-image treatments, theme color schemes, script-slot fonts and RTL, re-import of design and metadata references, native underline and current-body formatting on import, and UTC-canonical `zipDate` (see the changelog for the intentional contract changes).
+Version 0.12.0 requires `@openpresentation/opf` ^0.12.0 (composed font sizes on PowerPoint's 0.01 pt grid, hanging wrap whitespace, promoted regions in reading order, right-to-left decks composed mirrored) and exports what that core composes, plus the export and import changes listed in the changelog; use it with opf-render 0.12.0 (optional peer ^0.12.0) and opf-editor 0.11.0 so preview and export resolve one core. Version 0.11.9 exports an SVG image as a native SVG picture over a PNG fallback (rasterized in Node by the optional `@openpresentation/opf-render` peer or `options.svgRasterizer`; without one it stays the placeholder), writes a deck footer's first text, date and slide number as native PowerPoint Header & Footer placeholders (output change for decks with a footer; every export now carries the footer placeholders on its master, layout and notes master; see [native header and footer](docs/native-header-footer.md)) and adds the opt-in `fromPptx(bytes, {signals: true})`, which also returns the raw per-shape signals of every slide (see Import signals; the option leaves the default import unchanged; core floor `^0.11.4` unchanged, no API removed). Version 0.11.8 re-imports rich text that wraps over several native lines as the one authored payload instead of reporting `content-structure-changed` (the export records the line count; decks exported by earlier versions import as before; core floor `^0.11.4` unchanged, no API change). Version 0.11.7 requires `@openpresentation/opf` ^0.11.4 and exports the design fields natively (cover and section logos, header and footer logos, picture bullets, the accent font), writes every chart's text at the size the preview draws, round-trips the slide content structure, sections, extensions, assets and brand images through PPTX provenance (a fresh export of a plain deck re-imports in its authored form, so read a root payload field before `blocks[0]`), writes slide sections as PowerPoint's section list, and degrades an SVG image to the preview's placeholder instead of aborting; install it with renderer 0.11.9 and editor 0.10.6 so export and preview resolve the same core (no API removed). Version 0.11.6 exports the treemap, histogram, pareto, box-and-whisker, waterfall and funnel charts as native chartex parts by default (`toPptx({chartex: 'auto'})`; `world` stays a clustered column with `chart-data-adapted`; pass `chartex: 'fallback'` for the previous output) and gives chartex text the deck's label colour and font (no API removed). Version 0.11.5 writes the slide tag run as a theme color reference (`a:schemeClr accent1`) where the deck theme holds the primary there (no API change; the color is unchanged). Version 0.11.4 re-imports quote payloads (each native quote line carries an `OPF_QUOTE_V1` tag) and slide-image payloads from an unchanged export, writes the theme's `a:ea` and `a:cs` only for slots a script font is selected for, and requires core `^0.11.3` (the 70 legacy gallery layout ids and their geometry; install it with renderer 0.11.6 and editor 0.10.4 so export and preview resolve the same core; no API removed). Version 0.11.3 adds the opt-in `toPptx({ chartex: 'native' })` export of the seven chartex chart types and always imports chartex charts (no API removed; the default output is unchanged). Version 0.11.2 exports the classic chart types as native chart constructs and writes named and default table colours, text pairs and hyperlink colours as theme references (no API or dependency change; resolved colours are unchanged). Version 0.11.1 exports `design.watermark` as a native picture (it re-imports) and embeds byte-identical media parts once, with no API or dependency change. Version 0.11.0 requires core `^0.11.2` (cover slides are centered between header and footer furniture) and the optional `@openpresentation/opf-render` peer `^0.11.0`; install them together so export and preview resolve the same core. Version 0.10.0 required core `^0.11.1` and the peer `^0.10.0`. It adds native slide-number and date fields, socials, slide-image treatments, theme color schemes, script-slot fonts and RTL, re-import of design and metadata references, native underline and current-body formatting on import, and UTC-canonical `zipDate` (see the changelog for the intentional contract changes).
+
+Chart options (RR-35, unreleased): `axisTitles`, `legend` and `dataLabels` on a chart export as native `c:title`, `c:legendPos` and `c:dLbls` (and `cx:title`, `cx:legend`, `cx:dataLabels` on the Office 2016 constructs) and import back; the preview draws the same options. See core `docs/chart-options.md` for the per-type support table and the `chart-option-adapted` diagnostic.
 
 Version 0.9.1 kept core `^0.11.0` and raised the optional `@openpresentation/opf-render` peer to `^0.9.0` so it coexists with editor 0.8.0. ColorRef / `variables` on content colors still hex-resolve through core `resolveColorRef()` before PptxGenJS `srgbClr` export. Unrecognized run colors such as `color:'invalid'` still validate and fall back to the theme text color. Native DrawingML `schemeClr` and theme `clrScheme` writes, and native `p:hf` headers/footers, are not in this release. Import still flattens theme colors to hex. Metric, quote and timeline layout placeholders and the corrected text-bullet contract from 0.8.1 are retained.
 
@@ -136,6 +138,7 @@ The first importer is mechanical and schema-compatible:
 - Native table text preserves run/field/break order, significant whitespace, and blank paragraphs. Cells return canonical `{value, style}` objects; `value` retains scalar text or supported rich runs. Covered merge positions are `null`. Explicit normal headers override OPF’s bold header default. Numeric/boolean/null source types cannot be reconstructed from native display text.
 - Run `lang` maps back to the presentation `language` (a catalog id when it round-trips, else the tag); see [Languages, right-to-left text and script fonts](#languages-right-to-left-text-and-script-fonts).
 - Imported runs retain bold, italic, underline, strike, point sizes, Latin font families, solid colors/alpha, external hyperlink URLs, and superscript/subscript direction. List-level and paragraph defaults apply before run overrides; supported theme fonts/colors resolve from the archive. Field values become their cached text, and underline/strike variants and baseline magnitudes reduce to OPF booleans.
+- Citations, footnotes and captions (core RR-34 fields): a marker exports as a native superscript run (`baseline="30000"`) after its run; the slide's footnote area is a line shape plus one tagged text box per listed line (`OPF_FOOTNOTES_V1`), a caption one tagged text box per line (`OPF_CAPTION_V1`) naming its media shape, both at core's geometry; `references` travel in the document record. Import re-attaches tagged captions to their media block, rebuilds `references`, `cite` and `footnote` from the footnote tags and the marker runs (removing the marker runs; an edited note keeps its edited text), and guesses nothing without tags: a superscript number stays a superscript run and a text box stays a text block.
 - Conditional table styles, merged-cell geometry, cell fills/borders/alignment, unsupported text fills/colors, and internal hyperlink actions are not fully reconstructed. `onDiagnostic` reports unsupported table style references, merges, fonts/colors/fills and links with native frame/cell paths. Table paths use the native graphic-frame and row indexes, including a header row. The shared core 0.6.0 layout sizes rows from their content and reports `text-overflow` when text cannot fit at the minimum size. These checks establish native XML conversion, not visual parity with PowerPoint.
 - Unknown non-text shapes and unsupported graphic frames become editable text fallback blocks instead of failing the import.
 - Catalog references (`design.theme`, `colorScheme`, `fontScheme`, `dimensions`, `background`, slide `layout`), slide ids and authoring metadata (`narrative`, `tone`, `audience`, `purpose`, `language`, `organization`, `speaker`, ...) are stored at export in `OPF_DOCUMENT_V1` / `OPF_SLIDE_V1` customer-data tags. Import restores a reference while the theme colors, theme fonts, slide size, background or slide arrangement it produced are unchanged. After an edit, the observed native values stay and `design-reference-changed` / `layout-reference-changed` name the reference. `toPptx` option `provenance: 'references-only' | false` limits or disables these invisible tags. Slide layout intent (layout id, type, composition, composition hints and the inline layout record) lives in each `OPF_SLIDE_V1` record, so a slide keeps its layout even without the document tag, for example when it is pasted into another deck (FF-29). See [document round trips](docs/document-roundtrip.md) for exactly what is embedded.
@@ -201,7 +204,7 @@ The exporter reads the presentation `language` through core `resolveScriptFonts(
 - Theme major/minor `a:ea`/`a:cs` are written only for a slot where a script font is actually selected (FF-49): an explicit `eastAsian`/`complexScript` on the design font scheme, the scheme's own script family, or the language's script font (a language that uses the East Asian slot, such as Japanese, writes `ea`; one that uses the complex-script slot, such as Arabic, Hebrew, Indic or Thai, writes `cs`). Every other slot keeps the vendored empty typeface, exactly as Office's own themes leave it, so PowerPoint picks its per-language default for script text typed later and the package names nothing the author did not select (owner font policy). Latin, Cyrillic, Greek, Armenian, Georgian and Ethiopic decks write neither; the other slot of a CJK or complex-script deck is empty too. The language never changes the theme's latin fonts (Model C): `design.fontScheme` alone sets them. The preview resolves the same slots (opf-render's script profile: the theme's family where it names one, the latin family where it is empty), and `test/theme-script-slots.mjs` checks preview against export for every catalog font scheme.
 - The theme's per-script entry for the language's own script (for example `Jpan`, `Hang`, `Arab` or `Deva`) names the resolver's supplement. The rest of the vendored Office per-script list is unchanged; that list is FF-08's call.
 - Run `a:ea`/`a:cs` name the resolved slot when the language or the font scheme supplies a script-specific font, for example Meiryo in `a:ea` for Japanese or Arabic Typesetting in `a:cs` for Arabic. Headings take the heading font and other text the body font. Otherwise the slots keep repeating the run's latin face, so Latin, Cyrillic and Greek decks keep their run bytes.
-- In a right-to-left deck, each slide and notes paragraph takes its direction from core `paragraphDirection(text, direction)`, the same rule the renderer uses: `rtl="1"` when its first strong character is right-to-left or it has none (digits, punctuation, empty), else an explicit `rtl="0"` (an English quote, a code line). The master, layout and presentation default paragraph levels start right-to-left only in a right-to-left deck. Left-to-right decks write no paragraph direction. Alignment is unchanged: `algn` stays the composed absolute alignment (left stays `l`), so native line placement keeps matching the renderer's geometry. Right-aligning RTL text by default is a composition decision in core; until then, set `contentAlignment` or `titleAlignment` to `right`.
+- In a right-to-left deck, each slide and notes paragraph takes its direction from core `paragraphDirection(text, direction)`, the same rule the renderer uses: `rtl="1"` when its first strong character is right-to-left or it has none (digits, punctuation, empty), else an explicit `rtl="0"` (an English quote, a code line). The master, layout and presentation default paragraph levels start right-to-left only in a right-to-left deck. Left-to-right decks write no paragraph direction. Alignment is logical (RR-05, needs the core release that composes right-to-left decks): `left` is the start edge, so a right-to-left paragraph writes `rtl="1"` with `algn="r"` (PowerPoint's `algn` is physical, and `marL`/`indent` are the start-side margin and hanging indent, so a bullet hangs at the right), and every wrapped line shares its paragraph's direction and alignment (core computes the direction once per paragraph, not per line). The composition is mirrored through core: the `left` region and the first column are drawn at the right, a right-to-left table writes `a:tblPr rtl="1"` with its columns in logical order, column, line and area charts write `c:catAx` orientation `maxMin` (first category and value axis at the right), cover logos and header/footer zones swap sides, the master, layout and notes default levels start right-aligned, and notes paragraphs start at the right. Each Latin phrase inside an Arabic or Hebrew run (letters, joining spaces and word punctuation, digits) is written as its own `en-US` run, so PowerPoint orders `v2.0` and `PowerPoint 365` left to right instead of splitting them into items; digits that touch Arabic words stay in the Arabic run. Re-import reads right alignment of a right-to-left table cell as the logical start. Left-to-right decks are written exactly as before.
 - The PPTX names the chosen fonts only and never embeds font programs. Licensed fonts are never embedded; only open fonts could be, through the explicit FF-13 embed path. Catalog names such as Meiryo must be installed where the deck is opened.
 
 Charts keep their `c:lang` and left-to-right label paragraphs. The embedded chart workbook is untouched.
@@ -218,6 +221,20 @@ Exports report `language-unresolved` when the document's language cannot be reso
 
 **Core without the resolver.** Core `@openpresentation/opf` 0.11.0 and earlier have no `resolveScriptFonts` (this release requires ^0.11.3, so this only applies to a forced older core). Export with it is byte-identical to the output before FF-07 (`lang="en-US"`, empty theme `ea`/`cs`, no `rtl`), and a document that names a language gets a `language-export-unavailable` diagnostic. A core with the resolver but without `paragraphDirection` marks no paragraph direction and reports `paragraph-direction-unavailable` for a right-to-left deck. Import then matches run tags against the installed catalog's `bcp47` and primary language. `npm run test:packed` exercises this path against the registry release. CI links core at a pinned commit that has the resolver.
 
+## Numbered lists (RR-33)
+
+A list with `numbering` (`{ "items": ["Define", "Build"], "numbering": ["arabic", { "style": "alpha-lower", "suffix": "paren" }] }`) exports as native PowerPoint auto-numbers, not typed digits. Each marker line is the text box it already was, now with `a:buAutoNum` (`arabicPeriod`, `arabicParenR`, `arabicParenBoth`, `romanUc`/`romanLc`..., `alphaUc`/`alphaLc`...) whose `startAt` is the number core counted (written only when it is not 1), the measured marker size, colour and family (`a:buClr`, `a:buSzPts`, `a:buFont`) and `marL`/`indent` from core's hanging indent, so the number and the text sit where the preview draws them. A numbered list is not renumbered by PowerPoint when an entry is inserted (each line is its own box; this is how lists export today), the numbers are core's. `fromPptx` maps `a:buAutoNum` back: the scheme to a style and suffix, `startAt` to `start`, per level to an array, and a list whose numbers are not the plain count to per-entry `start` values; native counting follows PowerPoint (consecutive paragraphs of one scheme and start count up, a shallower or unnumbered paragraph ends the deeper sequences). The authored spelling comes back in its shortest form (`"arabic"` for `{ "style": "arabic" }`). A scheme OPF has no equivalent for imports as `arabic` with `numbering-scheme-adapted`, a list that mixes numbered and bullet paragraphs imports as bullets with `numbering-mixed`, and different schemes at one level report `numbering-style-adapted`. A numbered list exported with a core that does not compose `numbering` reports `numbering-unsupported-core` and exports bullets. Lists without `numbering` export unchanged. See core's [numbered lists](https://github.com/OpenPresentation/opf/blob/main/docs/numbered-lists.md).
+
+## Templates and variables (RR-32)
+
+A deck that declares content variables, or is marked `"template": true`, is resolved by core `resolveVariables` before it is exported, so the PPTX holds exactly the text, numbers, dates and images the preview shows. Pass the values as `variables`:
+
+```js
+const pptx = await toPptx(template, { variables: { client: 'Globex', revenue: 1250000 } });
+```
+
+A template exports with each unfilled variable's `example` and reports `variable-example-used` through `onDiagnostic`; a normal deck with an unfilled required variable throws `OPFPptxError` with code `unfilled-variables`, and a value of the wrong kind throws `invalid-variables`. A template plus values exports the same bytes as the equivalent hand-written deck (`test/template-variables.mjs`). The package stores the resolved deck, not the template form: `fromPptx` returns the filled deck. Decks without content variables are untouched. Needs the core release that ships `resolveVariables` (read from the namespace, so an older core still loads and ignores the option). See [templates and variables](https://github.com/OpenPresentation/opf/blob/main/docs/templates-and-variables.md).
+
 ## Runtime Policy
 
 The package runtime must stay local and deterministic:
@@ -334,7 +351,9 @@ Node 20/24 tests and the 126-deck / 805-slide structural corpus pass. This prove
 
 ### Pattern and picture backgrounds (FF-25)
 
-Pattern backgrounds export as a native `<a:pattFill>` with explicit foreground and background colors. OPF presets named by DrawingML's 54 `ST_PresetPatternVal` values (for example `pct5`, `ltHorz`, `openDmnd`, `wave`) are written unchanged. As in the SVG preview, a missing foreground uses the slide text color and a missing background uses white; text contrast follows the pattern's background color. The preview's engine id `diagStripe` has no DrawingML name. It is still accepted and is written as the closest preset, `wdUpDiag`; new documents should use `wdUpDiag` so that re-import keeps the name. Any other engine-defined id keeps only its background color, like the preview, and reports `unsupported-pattern`. Opacity becomes alpha on both colors. Under the FF-24 theme-color rule, a pattern color authored as a scheme slot or role becomes `a:schemeClr`, with the background opacity as alpha, when the deck theme holds exactly the color the preview draws. Like the preview, pattern colors resolve only hex, so any other name is drawn as the default color and stays literal RGB. Import resolves theme pattern colors to RGB.
+Pattern backgrounds export as a native `<a:pattFill>` with explicit foreground and background colors. OPF presets named by DrawingML's 54 `ST_PresetPatternVal` values (for example `pct5`, `ltHorz`, `openDmnd`, `wave`) are written unchanged. As in the SVG preview, a missing foreground uses the slide text color and a missing background uses white; text contrast follows the pattern's background color. The preview's engine id `diagStripe` has no DrawingML name. It is still accepted and is written as the closest preset, `wdUpDiag`; new documents should use `wdUpDiag` so that re-import keeps the name. Any other engine-defined id keeps only its background color, like the preview, and reports `unsupported-pattern`. Opacity becomes alpha on both colors. Under the FF-24 theme-color rule, a pattern color authored as a scheme slot or role becomes `a:schemeClr`, with the background opacity as alpha, when the deck theme holds exactly the color the preview draws. Like the preview, pattern colors resolve only hex, so any other name is drawn as the default color and stays literal RGB. Import resolves theme pattern colors to RGB. The SVG preview draws every one of the 54 presets from core's 8 x 8 bitmaps (RR-07), so the preview and this `a:pattFill` show the same preset in the same colours (`test/rr-07-preview-polish.mjs` pins it for all 54); the tiles are the pixels measured from desktop PowerPoint (Office 365, Windows, 2026-10-01), not defined by ECMA-376.
+
+`code.language` and `metric.trend` export natively from the same core tables the preview reads (RR-07). Code keeps one text box per source line; a language adds coloured runs (theme-derived colours kept at 4.5:1 or more on the #111827 panel) whose text concatenates to the exact line, and an unknown language is exported plain. A trend adds one arrow shape (`upArrow`, `downArrow` or `rightArrow`, alt text "Trend: up") beside the trend word and colours the delta and trend text green, red or neutral; the arrow is part of the metric's provenance group, so the metric re-imports as the one authored payload. `scripts/rr07-native-set.mjs <dir>` builds the native-check decks, preview PNGs and a manifest.
 
 Image backgrounds export as a native `<a:blipFill>` for the embedded raster: `data:` sources, declared `asset:` ids and `imageResolver` results. `cover` (the default) crops the centered source to the slide aspect with `a:srcRect`. `contain` letterboxes the source with `a:fillRect` insets. `tile` repeats square cells that are min(width, height)/4 in size, from the top-left, as the preview does. The deck `imageFill` decides whether each cell is covered or contained; contained cells use negative (transparent) source insets. With `dpi="0"`, a native tile is sized from the raster's own resolution: PNG `pHYs` in metres; JPEG JFIF density in inches or centimetres, otherwise EXIF `XResolution`/`YResolution`; 96 dpi when absent. The tile scale compensates on each axis, so a cell matches the preview's CSS pixels. WebP sources become PNG parts as for pictures. Opacity becomes `a:alphaModFix`. An unresolved image keeps the background color and reports `unresolved-asset` (`strictAssets` throws). A JPEG EXIF orientation cannot rotate a background fill, so it reports `unsupported-background-image-orientation`.
 

package/dist/annotation-export.js

@@ -0,0 +1,83 @@
+// Native export of captions and footnote areas (RR-34). Core composition owns the geometry
+// (`item.caption`, `geometry.footnotes`); this module writes one editable native text box per
+// fitted line at those boxes, like every other measured text shape, and records the shape tags
+// (OPF_CAPTION_V1, OPF_FOOTNOTES_V1) that annotation-provenance.js attaches at packaging and reads
+// back at import. Citation markers need nothing here (a marker fragment carries `nominalSize`, the marked run size, which is what is written with baseline 30000; PowerPoint draws it at 2/3, measured 2026-10-01): they are `kind: "marker"` fragments of the
+// rich-text fits and export through the ordinary rich-run path as superscript runs.
+
+export const CAPTION_TAG = 'OPF_CAPTION_V1';
+export const FOOTNOTES_TAG = 'OPF_FOOTNOTES_V1';
+
+export const captionShapeName = path => `OPF caption ${path}`;
+export const footnotesRuleName = slideIndex => `OPF footnotes ${slideIndex} rule`;
+export const footnoteEntryName = (slideIndex, entry) => `OPF footnotes ${slideIndex} entry ${entry}`;
+
+const INVALID_XML = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uD800-\uDFFF￾￿]/u;
+
+/**
+ * Write a core text fit (plain `fit.lines` with optional `sourceLines`/`placement`, or a rich fit
+ * with `richLines`) as one native text box per line at `box`, named `${objectName} line N` and
+ * recorded in `tags` with `record` plus the line's position and source boundary. `helpers` are the
+ * exporter's private text helpers (textBoxOptions, nativeFontOptions, exportColor, nativeColor).
+ */
+export function addFitLines(slide, value, fit, box, context, helpers, {objectName, record, tags, align = 'left', color, fontFamily, error}) {
+  const text = typeof value === 'string' ? value : value.map(run => typeof run === 'string' ? run : run.text).join('');
+  const invalid = INVALID_XML.exec(text);
+  if (invalid) throw error('invalid-text', `Text contains U+${invalid[0].codePointAt(0).toString(16).toUpperCase().padStart(4, '0')} at UTF-16 offset ${invalid.index}, which DrawingML XML cannot represent.`);
+  const factor = align === 'right' ? 1 : align === 'center' ? .5 : 0;
+  const lineColor = (color ?? context.textColor).replace(/^#/, '');
+  // `provenance: false` writes no tags at all (like every other OPF record): the lines stay named, untagged text boxes.
+  const tagged = context.provenanceMode === false ? new Map() : tags;
+  tags = tagged;
+  if (fit.richLines) {
+    const count = fit.richLines.length;
+    fit.richLines.forEach((line, index) => {
+      const runs = line.fragments.map(fragment => {
+        const runColor = helpers.exportColor(fragment.run.color, context, lineColor), native = helpers.nativeColor(fragment.run.color, runColor, context, lineColor);
+        return {text: fragment.text, options: {...helpers.nativeFontOptions(fragment.style), fontSize: (fragment.nominalSize ?? fragment.fontSize) * .75, color: native,
+          underline: fragment.run.underline ? {style: 'sng', color: native} : undefined, strike: fragment.run.strikethrough ? 'sngStrike' : undefined,
+          baseline: fragment.baselineShift ? -fragment.baselineShift / (fragment.nominalSize ?? fragment.fontSize) * 2000 : undefined,
+          hyperlink: fragment.kind !== 'marker' && fragment.run.link && /^(https?:|mailto:)/i.test(fragment.run.link) ? {url: fragment.run.link} : undefined}};
+      });
+      if (!runs.length) runs.push({text: '', options: {}});
+      const placed = fit.placement?.lines[index];
+      const area = placed ? {x: (placed.x + line.width * factor - box.width * factor) / 96, y: placed.y / 96, w: box.width / 96, h: placed.height / 96}
+        : {x: box.x / 96, y: (box.y + line.y) / 96, w: box.width / 96, h: line.height / 96};
+      const name = `${objectName} line ${index}`;
+      tags.set(name, {...record, line: index, count, boundary: index === count - 1 ? 'end' : 'soft', separator: '', rich: true});
+      slide.addText(runs, {...helpers.textBoxOptions(area, context, fit.fontSize * .75), ...(fontFamily ? {fontFace: fontFamily} : {}), color: lineColor, align, fit: 'none', wrap: false, lineSpacingMultiple: 1, objectName: name});
+    });
+    return;
+  }
+  const count = fit.lines.length;
+  fit.lines.forEach((line, index) => {
+    const placed = fit.placement?.lines[index], sourceLine = fit.sourceLines?.[index];
+    const boundary = sourceLine ? {boundary: sourceLine.boundary, separator: text.slice(sourceLine.end, sourceLine.nextStart)} : {boundary: index === count - 1 ? 'end' : 'soft', separator: ''};
+    const area = placed ? {x: (placed.x + placed.width * factor - box.width * factor) / 96, y: (placed.baseline - fit.fontSize) / 96, w: box.width / 96, h: placed.height / 96}
+      : {x: box.x / 96, y: (box.y + index * fit.lineHeight) / 96, w: box.width / 96, h: fit.lineHeight / 96};
+    const name = `${objectName} line ${index}`;
+    tags.set(name, {...record, line: index, count, ...boundary});
+    slide.addText(line, {...helpers.textBoxOptions(area, context, fit.fontSize * .75), ...(fontFamily ? {fontFace: fontFamily} : {}), color: lineColor, align, fit: 'none', wrap: false, lineSpacingMultiple: 1,
+      tabStops: sourceLine?.segments.filter(segment => segment.kind === 'tab').map(segment => ({position: (segment.x + segment.width) / 96, alignment: 'l'})), objectName: name});
+  });
+}
+
+/** The caption band of a captioned item: one tagged text box per line, linked to the media shape by name. */
+export function addCaption(slide, item, mediaName, context, helpers, error) {
+  const caption = item.caption;
+  if (!caption) return;
+  const record = {v: 1, role: 'caption', path: item.path, field: caption.path, media: mediaName ?? null, position: caption.position, align: caption.alignment};
+  addFitLines(slide, caption.text, caption.fit, caption.box, context, helpers, {objectName: captionShapeName(item.path), record, tags: context.captionTags, align: caption.alignment, color: context.mutedColor, fontFamily: helpers.nativeFontOptions(caption.textStyle).fontFace, error});
+}
+
+/** The footnote area: a rule shape and one tagged text box per listed line, at core's geometry above the footer band. */
+export function addFootnotes(slide, footnotes, slideIndex, context, helpers, error) {
+  if (!footnotes) return;
+  const {rule} = footnotes, ruleName = footnotesRuleName(slideIndex);
+  if (context.provenanceMode !== false) context.footnoteTags.set(ruleName, {v: 1, role: 'rule', slide: slideIndex});
+  slide.addShape('line', {x: rule.x / 96, y: (rule.y + rule.thickness / 2) / 96, w: rule.width / 96, h: 0, line: {color: context.colors.border, width: rule.thickness * .75}, objectName: ruleName});
+  footnotes.entries.forEach((entry, index) => {
+    const record = {v: 1, role: 'entry', slide: slideIndex, entry: index, number: entry.number, kind: entry.kind, ...(entry.id !== undefined ? {id: entry.id} : {}), source: entry.sourcePath, ...(entry.url !== undefined ? {url: entry.url} : {})};
+    addFitLines(slide, entry.value, entry.fit, entry.box, context, helpers, {objectName: footnoteEntryName(slideIndex, index), record, tags: context.footnoteTags, align: 'left', color: context.mutedColor, fontFamily: helpers.nativeFontOptions(entry.textStyle).fontFace, error});
+  });
+}

package/dist/annotation-provenance.js

@@ -0,0 +1,246 @@
+// Round trip of captions, citations and footnotes (RR-34).
+//
+// Export writes captions and footnote lines as tagged text boxes (annotation-export.js):
+//   OPF_CAPTION_V1   {v:1, role:'caption', path, field, media, position, align, line, count, boundary, separator, rich?}
+//   OPF_FOOTNOTES_V1 {v:1, role:'rule', slide} | {v:1, role:'entry', slide, entry, number, kind, id?, source, url?, line, count, boundary, separator, rich?}
+// and the deck's `references` travel in the document record (document-provenance.js, metadata
+// supplement). Citation markers are ordinary superscript runs (`baseline="30000"`) with no tag.
+//
+// Import consumes the tagged shapes: caption lines re-attach to the block whose native media shape
+// the tag names (current native text wins, so an edited caption keeps its edit); footnote lines
+// rebuild each slide's notes (number, kind, reference id, current text); then every superscript
+// run whose text is a marker (`1`, `1,2`) directly after another run, and whose numbers all resolve
+// to this slide's notes, is removed and the run before it gets `cite` (reference ids) and/or
+// `footnote` (the note text). The references list is the stored list with the current text of every
+// note that was edited natively, plus any reference the stored list does not hold. Without tags
+// nothing is guessed: a superscript number stays a superscript run and a text box stays a text block.
+// Tags are untrusted input: every field is checked before use and the result still validates.
+import {XMLParser} from 'fast-xml-parser';
+import {attachTextTags, decodeTextTag} from './code-provenance.js';
+import {sourceLineParagraphs} from './text-provenance.js';
+import {CAPTION_TAG, FOOTNOTES_TAG} from './annotation-export.js';
+
+const 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});
+const array = value => value === undefined ? [] : Array.isArray(value) ? value : [value];
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const MAX_VALUE_CHARS = 64 * 1024;
+const MARKER = /^\d+(?:,\d+)*$/;
+const ENGINE_STYLE = new Set(['fontSize', 'fontFamily', 'color']);
+// Internal reader markers (`_opfScheme`: the scheme slot a colour resolved from) are not authored style either.
+const engineKey = key => ENGINE_STYLE.has(key) || key.startsWith('_opf');
+const name = shape => shape?.['p:nvSpPr']?.['p:cNvPr']?.name ?? shape?.['p:nvPicPr']?.['p:cNvPr']?.name ?? shape?.['p:nvGraphicFramePr']?.['p:cNvPr']?.name;
+
+export function attachAnnotationTags(entries, context) {
+  attachTextTags(entries, context.captionTags, CAPTION_TAG, 'opfCaption', 'caption');
+  attachTextTags(entries, context.footnoteTags, FOOTNOTES_TAG, 'opfFootnotes', 'footnotes');
+}
+
+function readTags(shape, relationships, entries) {
+  const tags = [];
+  let unreadable = false;
+  for (const link of array(shape['p:nvSpPr']?.['p:nvPr']?.['p:custDataLst']?.['p:tags'])) {
+    const rel = relationships.get(link['r:id']);
+    if (rel?.type !== REL || rel.targetMode === 'External' || !entries[rel.path]) { unreadable = true; continue; }
+    try { tags.push(...array(parser.parse(decoder.decode(entries[rel.path]))['p:tagLst']?.['p:tag'])); } catch { unreadable = true; }
+  }
+  return {tags, unreadable};
+}
+
+function readRecord(shape, relationships, entries, tagName) {
+  const {tags, unreadable} = readTags(shape, relationships, entries);
+  const own = tags.filter(tag => String(tag.name ?? '').toUpperCase() === tagName);
+  if (!own.length) return undefined;
+  if (unreadable || own.length !== 1 || tags.some(tag => /^OPF_/i.test(tag.name ?? '') && String(tag.name).toUpperCase() !== tagName)) return null;
+  try {
+    if (typeof own[0].val !== 'string' || own[0].val.length > MAX_VALUE_CHARS * 2) return null;
+    const record = decodeTextTag(own[0].val);
+    if (!object(record) || record.v !== 1) return null;
+    if (record.line !== undefined && (!Number.isSafeInteger(record.line) || record.line < 0 || !Number.isSafeInteger(record.count) || record.count < 1 || record.count > 1000 || record.line >= record.count)) return null;
+    if (record.boundary !== undefined && !['hard', 'soft', 'end'].includes(record.boundary)) return null;
+    if (record.separator !== undefined && (typeof record.separator !== 'string' || !/^(?:\r\n|\r|\n)?$/.test(record.separator))) return null;
+    return record;
+  } catch { return null; }
+}
+
+// Current native text of a group of line shapes, in line order: rich runs when the reader yields
+// them, else the plain paragraph text. Soft wraps insert nothing; hard boundaries keep their separator.
+function groupText(members, paragraphs, readBody) {
+  const ordered = members.sort((a, b) => a.record.line - b.record.line);
+  const rich = ordered.map(member => readBody?.(member.index));
+  if (rich.every(body => Array.isArray(body) && body.length)) {
+    const runs = [];
+    ordered.forEach((member, position) => {
+      const body = rich[position];
+      body.forEach((paragraph, paragraphIndex) => {
+        if (paragraphIndex) runs.push('\n');
+        // Caption and note lines are drawn in the engine's caption/footnote size, family and muted
+        // colour: those are not authored run styles, so only the authored emphasis comes back.
+        runs.push(...(Array.isArray(paragraph.richText) ? paragraph.richText.map(run => typeof run === 'string' ? run : Object.fromEntries(Object.entries(run).filter(([key]) => !engineKey(key)))) : [paragraph.richText ?? paragraph.text ?? '']));
+      });
+      const separator = member.record.boundary === 'hard' ? (member.record.separator || '\n') : '';
+      if (separator && position < ordered.length - 1) runs.push(separator);
+    });
+    return normalizeRuns(runs);
+  }
+  try {
+    return sourceLineParagraphs(ordered.map(member => ({index: member.index, data: {boundary: member.record.boundary ?? (member.record.line === member.record.count - 1 ? 'end' : 'soft'), separator: member.record.separator ?? (member.record.boundary === 'hard' ? '\n' : '')}})), paragraphs)[0].text;
+  } catch {
+    return ordered.map(member => (paragraphs[member.index] ?? []).map(paragraph => paragraph.text).join('\n')).join('');
+  }
+}
+
+// Merge adjacent plain strings; a run list with no styled run is a plain string.
+function normalizeRuns(runs) {
+  const merged = [];
+  for (const run of runs) {
+    const last = merged[merged.length - 1];
+    if (typeof run === 'string') { if (!run) continue; if (typeof last === 'string') merged[merged.length - 1] = last + run; else merged.push(run); }
+    else if (object(run) && typeof run.text === 'string') {
+      // A reader may leave keys with undefined values (no native value); they are not authored style.
+      const style = Object.fromEntries(Object.entries(run).filter(([key, value]) => key !== 'text' && value !== undefined));
+      if (!Object.keys(style).length) { if (typeof last === 'string') merged[merged.length - 1] = last + run.text; else merged.push(run.text); }
+      else merged.push({text: run.text, ...style});
+    }
+  }
+  return merged.every(run => typeof run === 'string') ? merged.join('') : merged;
+}
+
+const plain = value => typeof value === 'string' ? value : Array.isArray(value) ? value.map(run => typeof run === 'string' ? run : run.text).join('') : '';
+
+// Strip the `<n> ` prefix a listed note starts with.
+function withoutNumber(value, number) {
+  const prefix = `${number} `;
+  if (typeof value === 'string') return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+  if (!Array.isArray(value) || !value.length) return value;
+  const [first, ...rest] = value, text = typeof first === 'string' ? first : first.text;
+  if (!text.startsWith(prefix)) return value;
+  const remainder = text.slice(prefix.length);
+  const head = typeof first === 'string' ? (remainder ? [remainder] : []) : remainder ? [{...first, text: remainder}] : [];
+  return normalizeRuns([...head, ...rest]);
+}
+
+/**
+ * Consume the tagged caption and footnote shapes of one slide. Returns the shapes to skip, the
+ * captions keyed by the media shape name they belong to, and the slide's notes in number order.
+ */
+export function importAnnotations({shapes, paragraphs, relationships, entries, slideIndex, readBody, report}) {
+  const consumed = new Set(), captionGroups = new Map(), entryGroups = new Map();
+  for (const [index, shape] of shapes.entries()) {
+    const caption = readRecord(shape, relationships, entries, CAPTION_TAG);
+    if (caption !== undefined) {
+      consumed.add(shape);
+      if (!caption || caption.role !== 'caption' || typeof caption.path !== 'string' || typeof caption.field !== 'string' || !['below', 'above'].includes(caption.position) || !['left', 'center', 'right'].includes(caption.align) || caption.line === undefined) { report({code: 'invalid-caption-provenance', path: `slides.${slideIndex}`, message: 'A caption tag is unreadable or invalid; its text stays an ordinary text block.'}); consumed.delete(shape); continue; }
+      const key = caption.path;
+      if (!captionGroups.has(key)) captionGroups.set(key, []);
+      captionGroups.get(key).push({index, shape, record: caption});
+      continue;
+    }
+    const footnote = readRecord(shape, relationships, entries, FOOTNOTES_TAG);
+    if (footnote === undefined) continue;
+    consumed.add(shape);
+    if (!footnote || !['rule', 'entry'].includes(footnote.role)) { report({code: 'invalid-footnote-provenance', path: `slides.${slideIndex}`, message: 'A footnote tag is unreadable or invalid; its text stays an ordinary text block.'}); consumed.delete(shape); continue; }
+    if (footnote.role === 'rule') continue;
+    if (!Number.isSafeInteger(footnote.entry) || !Number.isSafeInteger(footnote.number) || footnote.number < 1 || !['reference', 'footnote'].includes(footnote.kind) || (footnote.kind === 'reference' && typeof footnote.id !== 'string') || footnote.line === undefined) { report({code: 'invalid-footnote-provenance', path: `slides.${slideIndex}`, message: 'A footnote entry tag is invalid; its text stays an ordinary text block.'}); consumed.delete(shape); continue; }
+    if (!entryGroups.has(footnote.entry)) entryGroups.set(footnote.entry, []);
+    entryGroups.get(footnote.entry).push({index, shape, record: footnote});
+  }
+  const complete = members => members.length === members[0].record.count && new Set(members.map(member => member.record.line)).size === members.length;
+  const captions = new Map();
+  for (const [path, members] of captionGroups) {
+    if (!complete(members)) { report({code: 'invalid-caption-provenance', path, message: 'Caption lines were removed or duplicated; the remaining text stays an ordinary text block.'}); for (const member of members) consumed.delete(member.shape); continue; }
+    const {record} = members[0];
+    const value = groupText(members, paragraphs, readBody);
+    captions.set(typeof record.media === 'string' ? record.media : `path:${path}`, {value, path, field: record.field, position: record.position, align: record.align});
+  }
+  const notes = [];
+  for (const members of entryGroups.values()) {
+    if (!complete(members)) { report({code: 'invalid-footnote-provenance', path: `slides.${slideIndex}`, message: 'Footnote lines were removed or duplicated; the remaining text stays an ordinary text block.'}); for (const member of members) consumed.delete(member.shape); continue; }
+    const {record} = members[0];
+    notes.push({number: record.number, kind: record.kind, ...(record.kind === 'reference' ? {id: record.id} : {}), ...(typeof record.url === 'string' ? {url: record.url} : {}), text: withoutNumber(groupText(members, paragraphs, readBody), record.number)});
+  }
+  notes.sort((a, b) => a.number - b.number);
+  return {consumed, captions, notes};
+}
+
+/** The caption value to write into a block: a string or TextRun[] with the default position and alignment, else the object form. */
+export function captionValue(caption) {
+  return caption.position === 'below' && caption.align === 'left' ? caption.value : {text: caption.value, position: caption.position, align: caption.align};
+}
+
+// Every run array of a slide payload that may carry markers, with a setter.
+function runArrays(slide) {
+  const found = [];
+  const visit = (host, path) => {
+    if (!object(host)) return;
+    if (Array.isArray(host.blocks)) { host.blocks.forEach((block, index) => visit(block, `${path}.blocks.${index}`)); return; }
+    if (Array.isArray(host.text)) found.push({path: `${path}.text`, get: () => host.text, set: value => { host.text = value; }});
+    for (const field of ['bullets', 'items']) if (Array.isArray(host[field])) host[field].forEach((item, index) => {
+      if (Array.isArray(item)) found.push({path: `${path}.${field}.${index}`, get: () => host[field][index], set: value => { host[field][index] = value; }});
+      else if (object(item)) {
+        if (Array.isArray(item.text)) found.push({path: `${path}.${field}.${index}.text`, get: () => item.text, set: value => { item.text = value; }});
+        if (Array.isArray(item.description)) found.push({path: `${path}.${field}.${index}.description`, get: () => item.description, set: value => { item.description = value; }});
+      }
+    });
+  };
+  const keys = Object.keys(slide).filter(key => /^(top|middle|bottom|left|center|right)([+:]|$)/.test(key) && object(slide[key]));
+  if (keys.length) for (const key of keys.sort()) visit(slide[key], key); else visit(slide, '');
+  return found;
+}
+
+const isMarkerRun = run => object(run) && run.superscript === true && typeof run.text === 'string' && MARKER.test(run.text);
+
+/**
+ * Replace the marker runs of `slide` by `cite`/`footnote` on the runs before them, using the slide's
+ * notes. A marker whose numbers do not all resolve, or that starts a run array, is left as it is.
+ * Returns the reference notes the slide used.
+ */
+export function restoreSlideCitations(slide, notes) {
+  const byNumber = new Map(notes.map(note => [note.number, note]));
+  for (const target of runArrays(slide)) {
+    const runs = target.get();
+    if (!runs.some(isMarkerRun)) continue;
+    const result = [];
+    for (const run of runs) {
+      const previous = result[result.length - 1];
+      if (!isMarkerRun(run) || previous === undefined || typeof previous === 'object' && previous.superscript) { result.push(run); continue; }
+      const resolved = run.text.split(',').map(Number).map(number => byNumber.get(number));
+      if (resolved.some(note => !note)) { result.push(run); continue; }
+      const marked = typeof previous === 'string' ? {text: previous} : {...previous};
+      const ids = [...new Set(resolved.filter(note => note.kind === 'reference').map(note => note.id))];
+      const footnotes = resolved.filter(note => note.kind === 'footnote');
+      if (ids.length) marked.cite = ids.length === 1 ? ids[0] : ids;
+      if (footnotes.length) marked.footnote = footnotes[0].text;
+      result[result.length - 1] = marked;
+    }
+    target.set(result);
+  }
+}
+
+/**
+ * Apply the notes of every slide to `imported` (markers become cite/footnote) and rebuild
+ * `references`: the stored list (document provenance) with the current native text of each note
+ * that was edited, plus any cited reference the stored list does not hold, in number order.
+ */
+export function restoreCitations(imported, slideNotes, report) {
+  const used = new Map();
+  imported.slides.forEach((slide, index) => {
+    const notes = slideNotes[index] ?? [];
+    if (!notes.length) return;
+    restoreSlideCitations(slide, notes);
+    for (const note of notes) if (note.kind === 'reference' && !used.has(note.id)) used.set(note.id, note);
+  });
+  const stored = Array.isArray(imported.references) ? imported.references.filter(object) : [];
+  if (!stored.length && !used.size) return;
+  const references = stored.map(reference => {
+    const note = used.get(reference.id);
+    if (!note) return reference;
+    const current = note.text;
+    if (plain(current) === plain(reference.text)) return reference;
+    report({code: 'reference-text-changed', path: `references.${stored.indexOf(reference)}`, message: `Reference '${reference.id}' shows edited text in a footnote area; the imported reference keeps the edited text.`});
+    return {...reference, text: current};
+  });
+  for (const note of used.values()) if (!references.some(reference => reference.id === note.id)) references.push({id: note.id, text: note.text, ...(note.url !== undefined ? {url: note.url} : {})});
+  imported.references = references;
+}

package/dist/body-text-import.js

@@ -11,6 +11,7 @@ const text = tree => (tree ?? []).map(node => node['#text'] ?? '').join('');
 // Match nativeTextShapes/nativeShapeParagraphs indexing; positional ordering is
 // still performed by the existing slide importer, not by this reader.
 const shapes = tree => [...nodes(tree, 'p:sp').map(node => node['p:sp']), ...nodes(tree, 'p:grpSp').flatMap(node => shapes(node['p:grpSp']))];
+const LATIN_ONLY = /^[\p{Script=Latin}\p{N}\p{P}\p{S}\p{Z}]*$/u;
 const value = runs => runs.some(run => typeof run !== 'string') ? runs : runs.join('');
 export const joinNativeParagraphs = paragraphs => value(paragraphs.flatMap((paragraph, index) => [
   ...(index ? ['\n'] : []), ...(Array.isArray(paragraph.richText) ? paragraph.richText : [paragraph.richText ?? paragraph.text])
@@ -77,7 +78,9 @@ export function nativeBodyReader(slidePath, archive, relationships, report) {
         const path = `shapes.${index}.paragraphs.${paragraphIndex}.runs.${runIndex++}`;
         const current = tag === 'a:br' ? '\n' : text(child(node[tag], 'a:t'));
         const properties = mergeNativeRunProperties(defaults, drawingObject(node[tag])['a:rPr']);
-        const style = bodyRunStyle(properties, context, relationships, (code, message) => report({code,message,path}));
+        // RR-05: a Latin phrase of a right-to-left paragraph is its own en-US run; its East Asian/complex-script slots can render nothing in it, so the face loss is not reported.
+        const phrase = nodes(content, 'a:pPr')[0]?.[':@']?.rtl === '1' && properties.lang === 'en-US' && LATIN_ONLY.test(current);
+        const style = bodyRunStyle(properties, context, relationships, (code, message) => { if (!(phrase && code === 'unsupported-body-font')) report({code,message,path}); });
         if (current) runs.push(Object.keys(style).length ? {text:current,...style} : current);
       }
       return {text:runs.map(run => typeof run === 'string' ? run : run.text).join(''), richText:value(runs)};