@openpresentation/opf-pptx 0.9.0 → 0.10.0

package/DEPENDENCY-NOTES.md

@@ -2,7 +2,7 @@
 
 ## Coordinated `@openpresentation/opf` pin
 
-PPTX 0.9.0 depends on published [`@openpresentation/opf@^0.11.0`](https://www.npmjs.com/package/@openpresentation/opf) (reference layer: ColorRef, document `variables`, exported `resolveColorRef()`). CI checks out OPF [`b8a1faf`](https://github.com/OpenPresentation/opf/commit/b8a1faf24203635bd36b09ea19f44bcd53781f16) (`opf-v0.11.0`) for coordinated source linking. Named content colors resolve through core `resolveColorRef()`; eight-digit hex alpha stays a local export concern because core `normalizeHexColor` drops the alpha byte. Native `schemeClr` / theme `clrScheme` writes remain follow-up work.
+PPTX 0.10.0 depends on published [`@openpresentation/opf@^0.11.1`](https://www.npmjs.com/package/@openpresentation/opf) (reference layer: ColorRef, document `variables`, exported `resolveColorRef()`). The optional renderer peer is [`@openpresentation/opf-render@^0.10.0`](https://www.npmjs.com/package/@openpresentation/opf-render) so editor 0.9.0 + render 0.10.0 + pptx 0.10.0 install together. CI checks out OPF [`b8a1faf`](https://github.com/OpenPresentation/opf/commit/b8a1faf24203635bd36b09ea19f44bcd53781f16) (`opf-v0.11.0`) for coordinated source linking. Named content colors resolve through core `resolveColorRef()`; eight-digit hex alpha stays a local export concern because core `normalizeHexColor` drops the alpha byte. Native `schemeClr` / theme `clrScheme` writes remain follow-up work.
 
 OPF PPTX 0.5.1 ships the exact, unmodified PptxGenJS 4.0.1 ESM distribution in `vendor/pptxgenjs`, with its MIT license, upstream archive integrity and per-file SHA-256 hashes. Its actual JSZip dependency is declared directly. Ordinary npm installations therefore omit the unused image-size parser without requiring consumer overrides. This removes the affected dependency; it does not patch the parser. Published OPF PPTX 0.5.0 retains the older graph.
 

package/README.md

@@ -1,6 +1,8 @@
 # OPF PPTX
 
-Version 0.9.0 requires core 0.11.0, including ColorRef / `variables` on content colors. It hex-resolves named colors 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.
+Version 0.10.0 requires core `^0.11.1` and the optional `@openpresentation/opf-render` 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.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.
 
 Unfinished prepared shaping work is preserved in the [September 15 roadmap](docs/roadmap-shaping-20260915.md); it is not part of the published runtime.
 
@@ -66,34 +68,88 @@ await fs.promises.writeFile("round-trip.pptx", roundTripBytes);
 
 The importer reads core properties, slide order, text boxes, speaker notes, embedded images, tables, and basic cached chart data from the OOXML parts. Slides or objects that do not map cleanly fall back to editable `blocks[]` payloads; OOXML positions are used for deterministic ordering and title/subtitle detection while keeping the emitted OPF schema-valid.
 
+### New in 0.10.0: native notes and property whitespace
+
+Current source preserves spaces, tabs, NBSP and authored CR/LF/CRLF in speaker notes and scalar presentation `name`, `description` and `author`; published npm `0.9.1` does not contain this repair (0.10.0 does). Import reads current native notes body paragraphs in run/field/line-break order, retaining blank paragraphs. Explicit paragraph and line-break boundaries import as LF. XML character references decode once, so literal text such as `
` remains literal. Export writes authored CR as character references in native text, without adding source-recovery tags; ordinary exports with no authored CR remain byte-identical.
+
+Native edits, cleared/deleted note bodies or parts, core-property edits/deletions and slide relationship order remain authoritative in all provenance modes. Empty notes and absent notes still both import absent; an empty or absent title uses the existing fallback, and empty description/author import absent. Author arrays still export as a joined scalar. External literal XML line endings follow XML normalization; exact CR requires character references. These are portable XML conversion controls, not native Office or visual acceptance.
+
 ## v1 Placeholder and OOXML Mapping
 
 The first exporter keeps the public API stable while using `pptxgenjs` internally:
 
 - `Slide.title`, `Slide.subtitle`, and `Slide.tag` become editable text boxes, not PowerPoint master placeholders.
 - Root payloads, `blocks[]`, and promoted region keys become editable slide objects in deterministic regions. Promoted keys use the OPF 3x3 region vocabulary (`top`, `middle`, `bottom`, `left`, `center`, `right`).
-- Text, lists, metrics, quotes, timelines, code, tables, and inline-data charts are emitted as editable PowerPoint text, table, and chart objects. Content ColorRef values (hex, scheme slots/roles, and `var:<id>`) flatten to `a:srgbClr` via core `resolveColorRef()`; this is hex-resolve, not native `schemeClr` / theme write.
+- Text, lists, metrics, quotes, timelines, code, tables, and inline-data charts are emitted as editable PowerPoint text, table, and chart objects. Content ColorRef values (hex, scheme slots/roles, and `var:<id>`) resolve through core `resolveColorRef()`. Slot and role names become native `a:schemeClr` references when the exported theme holds that exact color; hex, `var:<id>` and slide-override colors stay `a:srgbClr` (see [Theme color scheme](#theme-color-scheme)).
+- A chart whose data is one column of values (a histogram or dot plot) has no category column. It exports as a native chart and reports `chart-data-adapted`: a histogram is binned into equal-width bins (Sturges' count, at most 50) and written as a column chart of the counts, and any other chart type plots the values against their row numbers. PowerPoint's own histogram chart is not exported (histogram is a column chart at this engine). Cells parse as in every chart ("12%", "$5" and "1,234" count) and cells that hold no number are skipped, not plotted as 0. Binned counts do not round-trip: re-importing the file gives a `Bin`/`Frequency` column chart, not the raw values. Chart data that cannot be plotted (no numbers, no rows, or an external data source), an empty table and unsupported content keep a placeholder frame with a plain-language description (never a dump of the source data or URLs) and report `chart-data-unplottable` or `content-placeholder` with a `reason`; content is never dropped without a diagnostic.
 - Image assets are embedded only when supplied as data URIs, local paths, or host-resolved bytes/paths. Remote asset URLs are never fetched by the runtime path.
-- ZIP entries, generated chart/workbook part names, core-property timestamps, and nested chart workbook timestamps are normalized for reproducible bytes.
+- ZIP entries, generated chart/workbook part names, core-property timestamps, and nested chart workbook timestamps are normalized for reproducible bytes. [Export determinism](docs/export-determinism.md) lists the tested time zone, locale, clock and host-font controls and each known variance (WebP conversion, font registries, ICU segmentation, timestamps).
+- The package names only the document's chosen fonts. Chart text (data labels, axes, legend, titles) uses the chart slide's body font in `latin`/`ea`/`cs`; each embedded chart workbook uses the same fonts in its styles and theme; run `pitchFamily` follows the font scheme type (monospace is fixed pitch, serif is roman); and `docProps/app.xml` "Fonts Used" lists the fonts the package actually uses. The theme keeps PptxGenJS's per-script supplements (`THEME_SCRIPT_SUPPLEMENTS`) and empty `ea`/`cs` slots.
+- `checkPptxTypefaces(bytes, {fonts, monospace})` inventories every `typeface`, workbook font name and "Fonts Used" entry in every XML part, including nested packages, and reports each font outside that policy. `inventoryPptxTypefaces()` returns the raw inventory.
 
 This pass did not require an OPF schema change. The deferred full OOXML placeholder mapping from `docs/plans/layout-placeholders.md` remains a later hand-written OOXML emitter concern.
 
+### New in 0.10.0: explicit ZIP dates
+
+The following behavior is in current source; the published npm `0.9.1` package does not contain this repair or tightened option contract; `0.10.0` does.
+
+Omitting `zipDate` (or passing `undefined`) keeps the established fixed 1980 ZIP bytes. Explicit `zipDate` values now encode **UTC calendar fields** in both the PPTX and embedded workbook ZIPs, independently of the host timezone. This option changes ZIP metadata; the separate `timestamp` option controls core-property XML.
+
+Accepted values are a valid `Date`, finite epoch milliseconds, `YYYY-MM-DD` (UTC midnight), or `YYYY-MM-DDTHH:mm[:ss[.fraction]]` ending in `Z` or `±HH:mm`. Calendar components must be valid and the resulting UTC year must be **1980–2099**, matching the existing ZIP writer's supported range. ZIP timestamps have two-second resolution: fractional and odd seconds are truncated.
+
+This intentionally tightens the previous host-dependent `Date` parsing contract. Datetimes without a timezone, legacy date strings, invalid dates, and values outside that range throw `OPFPptxError` with code `invalid-zip-date` and path `options.zipDate`. Explicit `null`, `''` and `0` no longer silently use the default (`0` is a 1970 epoch date). Existing successful UTC output and default output remain byte-identical; explicit dates on other timezones change to the canonical UTC result.
+
 ## v1 Import Mapping
 
+### New in 0.10.0: current native body formatting
+
+Current source imports supported formatting from ordinary untagged native body text and list items. A value that previously imported as a string can now be a rich-run array containing the same current characters with explicit native properties. Unstyled values remain strings; title/subtitle selection and tagged recovery stay separate. Run, field and break order, blank paragraphs, significant whitespace, explicit normal overrides, paragraph/list defaults, point sizes, Latin font families, supported colors/alpha, hyperlinks and script direction come from the current PPTX. Edits, clears and deletion remain authoritative in every provenance mode.
+
+This does not reconstruct original source run identities or boundaries between native shapes, infer master/layout text styles, or recover cached authored content. Native paragraph/break boundaries become LF; character-reference CR remains explicit. Unsupported properties report body-path diagnostics rather than claim exact formatting. Reading order still uses current native positions. Published npm `0.9.1` does not contain this representation change; portable conversion checks do not establish Office rendering or general rich-text round-trip fidelity.
+
 The first importer is mechanical and schema-compatible:
 
 - Presentation core properties map to OPF `name`, `description`, and `author`.
+- The first slide master's theme `clrScheme` maps to `design.colorScheme`: a catalog id on an exact twelve-slot match, otherwise inline slots. A theme named like a catalog theme maps to `design.theme` when its colors or heading/body fonts corroborate it (see [Theme color scheme](#theme-color-scheme)).
 - Native title/subtitle placeholders retain their roles. On slides without complete OPF heading tags, recognizable text-box positions and sizes provide a fallback. If any complete OPF heading role is recovered, untagged body text stays in `blocks[]` instead of being promoted into an absent heading role. Damaged tags retain visible text through ordinary import and diagnostics.
 - Remaining text boxes map to `blocks[]` as text or list payloads, sorted by OOXML position.
 - PowerPoint tables map to OPF table blocks, embedded images map to data URI image blocks, and cached chart series map to basic OPF chart blocks.
+- Chart cache points are placed by their native `c:pt@idx`, with `c:ptCount` retaining trailing gaps. Missing labels and values become `null`; explicitly empty labels and series names stay empty strings, and an actual numeric zero stays zero. Empty numeric cache values remain missing. Malformed or duplicate indices, contradictory counts, competing caches and allocation limits reject with `invalid-chart-cache` and the chart-part/cache path; hierarchical category caches reject with `unsupported-chart-cache` instead of flattening labels. Each cache is limited to 100,000 positions, and combined caches and the emitted table each to 1,000,000 cells. Complete decimal scientific notation in numeric caches is read as a number; exponent overflow or nonzero underflow to zero rejects with `unsupported-chart-cache` and the chart part, series, cache and logical point path. Zero coefficients remain zero. This finite-number boundary does not classify rejected text as invalid OOXML. Malformed exponent strings and other nonblank numeric text retain the existing legacy conversion policy. This cache-only import does not repair embedded worksheets, restore unsupported scatter X/point labels, change exporter/workbook parsing or export/re-export missing-data handling, or establish native chart fidelity.
 - Table imports retain empty rows. A native `firstRow` flag of `1` or `true` maps the first row to column labels; absent/false flags retain every row as data. New exports set this flag from OPF columns. Older exports without the flag retain their labels as the first data row rather than inferring headers.
 - 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.
 - 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.
 
 There is no AI classification pass in the OSS runtime. Hosts can run optional cleanup or semantic remapping after `fromPptx` returns.
 
+## Languages, right-to-left text and script fonts
+
+The exporter reads the presentation `language` through core `resolveScriptFonts()` (FF-07; the model is core `docs/programs/font-fidelity-everywhere/script-font-model.md`):
+
+- Every run, end-of-paragraph and default run property carries `lang` set to the resolved OOXML tag instead of a fixed `en-US`. That tag is the catalog's curated `ooxmlLang` (for example `ja-JP` or `ar-SA`) or an authored region tag such as `en-NZ`. `altLang` is not written: it names the editing-UI language, which OPF does not model.
+- For a language that uses an East Asian or complex-script slot (CJK, Arabic, Hebrew, Indic, Thai and others), theme major/minor `a:ea`/`a:cs` name the resolved heading/body fonts instead of the vendored empty values. For a language written in the latin slot (Latin, Cyrillic, Greek and others) they stay empty unless the design font scheme sets `eastAsian`/`complexScript` explicitly. Filling them with the latin family is gated on FF-05: native evidence shows it does not remove the nameless and Aptos entries PowerPoint lists at open, and empty slots keep PowerPoint's per-script theme fallback for CJK or Arabic text typed later. So en-US decks export byte-identically.
+- 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`.
+- 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.
+
+When the package carries an FF-32 stored `language` ([document round trip](docs/document-roundtrip.md)), that reference is restored while the runs still carry its OOXML tag (or none); if the runs now use another tag, the observed language below is kept and `metadata-reference-changed` is reported once. Otherwise `fromPptx` sets `language` from the most common run `lang`. It uses a catalog id when that record exports the same tag (`ja-JP` imports as `japanese`, `en-US` as `english-us`). Otherwise it keeps the tag itself (`en-NZ`), which still resolves to its catalog record. `english` (`en`) exports `en-US`, so it imports as `english-us`. Diagnostics:
+
+- `mixed-run-languages`: runs use several tags; the most common one is imported.
+- `language-ambiguous`: records share one curated tag and none has it as its own tag (`bn-BD` is Bengali and Chittagonian, `fil-PH` Filipino and Tagalog); the record of the same primary language is imported.
+- `language-uncatalogued`: no catalog record matches; the tag is imported.
+- `rtl-language-mismatch`: right-to-left paragraphs under a left-to-right language.
+- `script-font-not-imported`: theme `ea`/`cs` name a font that neither repeats latin nor matches the language default. Imported OPF does not yet carry explicit font-scheme script slots.
+
+Exports report `language-unresolved` when the document's language cannot be resolved locally (a URL, `pkg:` reference or unknown id) and `en-US` is used.
+
+**Core without the resolver.** Core `@openpresentation/opf` 0.11.0 and earlier have no `resolveScriptFonts` (this release requires ^0.11.1, 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.
+
 ## Runtime Policy
 
 The package runtime must stay local and deterministic:
@@ -121,15 +177,11 @@ LibreOffice is not a runtime dependency. When it is installed in CI or a local v
 
 ## Release Lane
 
-Public npm package publication is handled by `.github/workflows/release.yml` with npm provenance.
-
-Required first-publish setup:
-
-1. An npm owner for the `@openpresentation` scope must run the first publish or reserve/grant the `@openpresentation/opf-pptx` package.
-2. Configure npm Trusted Publishing for GitHub repository `OpenPresentation/opf-pptx` and workflow `.github/workflows/release.yml`.
-3. Publish by creating a GitHub Release or manually running the Release workflow after CI passes.
+Public npm package publication is handled by `.github/workflows/release.yml` through npm Trusted Publishing (GitHub Actions OIDC) with npm provenance; no npm token is stored. The owner authorized agents to prepare and publish npm releases whenever a release is required (2026-09-29). This authorization does not waive any gate.
 
-This repo does not require an npm automation token when Trusted Publishing is configured.
+1. Open a release-prep PR containing only the version bump, `CHANGELOG.md`, dependency ranges, lockfile and current-instruction docs. Publish in dependency order (core, then renderer, then PPTX, then editor): refresh this repo's lockfile only after the required `@openpresentation/opf` and `@openpresentation/opf-render` versions are on the registry (`npm install --package-lock-only`), then run `npm run test:packed` against them.
+2. Merge after CI is green, then publish by pushing the git tag `opf-pptx-v<version>` (or `@openpresentation/opf-pptx@v<version>`) at the merge commit. The workflow verifies that the tag matches `package.json` and reruns audit, typecheck, validate, tests, packed and browser checks before `npm publish --access public --provenance`. A manual `workflow_dispatch` runs the same job without the tag check and is a fallback only.
+3. Verify with `npm view @openpresentation/opf-pptx@<version> version gitHead dist.attestations` and, from the core repo, `node scripts/test-pptx-publication.mjs <version> <release-commit> <this-checkout>`. Never republish an existing version.
 
 ## Shared dynamic composition
 
@@ -139,7 +191,9 @@ Version 0.4.0 requires published `@openpresentation/opf@^0.6.0`. The optional re
 
 For crowded drafts, run `paginatePresentation` from `@openpresentation/opf/pagination` first, then pass its returned presentation to both preview and `toPptx`. Native table row sizing now follows shared reference geometry; the exporter does not add hidden table continuation slides.
 
-Pass the same `textMeasurement` provider used by preview and pagination to `toPptx`. Plain text and headings retain the measured line breaks and resolved font family in editable PowerPoint shapes. Font binaries are not yet embedded in PPTX; native viewers still need the resolved font installed.
+Pass the same `textMeasurement` provider used by preview and pagination to `toPptx`. Plain text and headings retain the measured line breaks in editable PowerPoint shapes.
+
+The PPTX always names the font family the document chose (for example `typeface="Aptos"`), so PowerPoint opens the file and shows the actual font, installed or as a Microsoft 365 cloud font. This is the [OPF font policy](https://github.com/OpenPresentation/opf/blob/main/docs/font-fidelity.md#font-policy-ff-31): the user's selection is the source of truth, licensed fonts are never bundled or embedded, and previews draw an open look-alike instead. A provider may preview that family with another face: a metric-compatible substitute (Carlito for Calibri, the goal), a visual-only one (Roboto or Carlito for Aptos, a documented fallback and known layout-fidelity gap until a metric-compatible replacement exists), a caller alias or a generic fallback. That face changes measurement and drawing only. It never reaches the theme, runs, bullets or chart parts. Faces of the chosen family itself, such as Roboto Medium for Roboto at weight 500, keep their native style-link names. `test/export-chosen-fonts.mjs` checks this for every renderer Office-pack substitute. The exporter does not embed font binaries. Viewers resolve the named family themselves. When the preview used a non-metric substitute, PowerPoint can break lines differently from the preview.
 
 Since 0.5.1, the exact PptxGenJS 4.0.1 ESM distribution is shipped with its MIT license and verified upstream hashes. Its unused `image-size` dependency is not installed; JSZip is declared directly. See [dependency provenance and regression coverage](DEPENDENCY-NOTES.md). The published 0.5.0 package retains the older dependency graph.
 
@@ -149,7 +203,7 @@ Version 0.4.0 imports and exports supported rich table cells and headers as edit
 
 The exporter measures every cell with the same `textMeasurement` provider, font roles and effective nested `minFontSize` used by the SVG preview. Native table cells retain the original strings and values as text, with matching fitted sizes, line spacing, alignment, margins and row/column geometry. Uneven rows receive empty cells for missing columns. Theme border colors now use the same slot as the preview.
 
-`npm test` compares exported OOXML against the published SVG renderer across 168 cells, including 24 cases that require taller rows, Roboto and Calibri-to-Carlito substitution, two canvas sizes, headers and all three alignments. PowerPoint still performs its own natural wrapping and needs the resolved fonts installed. These document-property checks do not establish native raster parity or lossless typed-cell import.
+`npm test` compares exported OOXML against the published SVG renderer across 168 cells, including 24 cases that require taller rows, Roboto, and Calibri measured with its metric-compatible Carlito substitute (the cells still name Calibri), two canvas sizes, headers and all three alignments. PowerPoint still performs its own natural wrapping and needs the named fonts installed. These document-property checks do not establish native raster parity or lossless typed-cell import.
 
 A local macOS Quick Look check opened both Roboto and system-Arial specimens. Quick Look substituted a serif font for uninstalled Roboto; the Arial specimen used a sans-serif face but still differed in table wrapping and row proportions. This is evidence of remaining viewer differences, not a passing PowerPoint raster comparison.
 
@@ -159,6 +213,17 @@ Native image exports now follow the browser's `design.imageFill`: `fit` (the def
 
 JPEG EXIF orientations 1–8 are represented by native picture rotation and mirroring. The embedded copy's orientation tag is normalized to 1 to avoid viewer-dependent double rotation. Compressed pixels and other metadata remain unchanged; input data is not mutated. EXIF orientation in other containers, animated playback, SVG/vector assets, effects and lossless crop/orientation import are not covered by this change.
 
+A slide-level image (`design.slideImage`, composed by core as `geometry.slideImage`) exports as one native picture named `OPF slide image slides.N`. It sits beneath the slide's other shapes. Its frame is the shared composition frame for both fills: `crop` writes positive `a:srcRect` insets and `fit` writes negative insets that pad the centered image. The frame therefore matches the preview's `<image>` box exactly. An `OPF_SLIDE_IMAGE_V1` shape tag records the placement and the native picture geometry. On import, an unchanged tagged picture becomes the slide's `design.slideImage` again, with the embedded bytes as its data URI source and `imageFill: "fit"` when the frame was fitted. An edited, duplicated or ambiguous tagged picture is imported as an ordinary image block and reports `invalid-slide-image-provenance` at `slides.N.design.slideImage`. Native PowerPoint raster parity for negative `a:srcRect` insets has not been checked with Office yet.
+
+Slide-image treatments export from core's normalized geometry as native DrawingML:
+
+- `shape` becomes the picture's `a:prstGeom` (`rect`, `roundRect`, `ellipse` or `hexagon`) with core's guide values.
+- `border` becomes a centered solid `a:ln` with a miter join.
+- `recolor` becomes `a:grayscl` or `a:duotone`, followed by `a:alphaModFix` for `opacity`, on the blip only.
+- `overlay` becomes one tagged `OPF slide image overlay slides.N` shape directly above the picture.
+
+An unchanged export imports every treatment field back. An edited overlay drops only the overlay and reports `invalid-slide-image-provenance`. An edited picture or effect drops the slide image. See core `docs/image-treatments.md` for the vocabulary and the unsupported effects: blur, shadows, soft edges and background removal. PowerPoint's luminance weights for grayscale and duotone are unverified natively.
+
 Tests compare SVG/native fit and crop geometry across nine synthetic raster fixtures and cover all eight JPEG orientations. Keynote 14.4 visually preserves proportions for wide/tall fit/crop and displays all eight orientations correctly. This does not establish Microsoft PowerPoint raster parity or WebP support in every Office version.
 
 The structural export/import corpus gate covers every installed core example (126 decks / 805 slides for core 0.4.0). It explicitly substitutes a bundled fallback font and synthetic images, then checks slide XML, unique native object IDs, finite geometry, table grids and imported slide counts. It does not establish original-asset, typography or viewer fidelity. The focused table and image tests separately exercise measured geometry and real fixture bytes.
@@ -186,8 +251,30 @@ Diagonal gradients require a coordinate conversion: the preview uses an SVG obje
 
 Import reads supported native RGB solid/linear fills directly; it uses no hidden source copy. Uniform alpha becomes OPF background opacity, and differing stop alpha uses eight-bit RGBA colors (which can round alpha). Native path gradients, color transforms outside the supported luminance/alpha set, non-default tile/flip geometry and stop intervals outside OPF's fixed-endpoint representation are not imported. Pass `fromPptx(bytes, {onDiagnostic: issue => ...})` to observe `unsupported-background-gradient` with a slide path.
 
-Node 20/24 tests and the 126-deck / 805-slide structural corpus pass. This proves serialization and the mathematical mapping, not native viewer pixels. Keynote 14.4 recognizes the editable native gradients. Twelve captured native PNGs now support 18 comparisons, including a Keynote-generated PPTX import: opaque differences are at most 4/255 per channel (mean below 0.38), and transparent portrait alpha differs by at most 1/255. The checked-in references run in ordinary Node tests without Keynote. Quick Look still renders these specimens as a flat average color, so its thumbnails are not evidence of their native appearance. Microsoft PowerPoint remains unavailable and unverified. Pattern/image backgrounds, theme-aware native fills, and other design decorations remain separate fidelity work.
+Node 20/24 tests and the 126-deck / 805-slide structural corpus pass. This proves serialization and the mathematical mapping, not native viewer pixels. Keynote 14.4 recognizes the editable native gradients. Twelve captured native PNGs now support 18 comparisons, including a Keynote-generated PPTX import: opaque differences are at most 4/255 per channel (mean below 0.38), and transparent portrait alpha differs by at most 1/255. The checked-in references run in ordinary Node tests without Keynote. Quick Look still renders these specimens as a flat average color, so its thumbnails are not evidence of their native appearance. Microsoft PowerPoint remains unavailable and unverified. Theme-aware native fills and other design decorations remain separate fidelity work.
+
+### 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.
 
+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`.
+
+Import reads `a:pattFill` with a DrawingML preset and resolvable foreground/background colors, including slide/layout/master inheritance and theme references, as an OPF pattern background. Import does not guess undefined default colors. Import also reads embedded `a:blipFill` pictures as an image background with the exact image bytes as a `data:` URI. Tiles become `tile`. If the tile scale, offset, alignment, flip or source insets differ from the geometry OPF `tile` exports (contained cells at the raster's resolution), the import reports `approximate-background-image`. A centered crop matching the slide aspect becomes `cover`, and centered fill insets matching the image aspect become `contain`. Off-center, distorted or effect-bearing fills become the closest `cover` and report `approximate-background-image`. Linked or unreadable pictures report `unsupported-background-image`. `test/background-fills.mjs` covers export, import, native edits, inheritance and diagnostics. Microsoft PowerPoint rendering of these fills, especially its resolution-based tile scale and negative tile insets, has not been verified.
+
+
+## Theme color scheme
+
+Export writes the deck's resolved color scheme into `ppt/theme/theme1.xml` `a:clrScheme`, named after the scheme. The OPF slots map one to one: `dark1`/`light1`/`dark2`/`light2` to `dk1`/`lt1`/`dk2`/`lt2`, `accent1`-`accent6` to themselves, and `hyperlink`/`followedHyperlink` to `hlink`/`folHlink`. An abstract role fills a slot only when the scheme leaves that slot unset. Previously every export carried the vendored Office palette (`accent1` `4472C4`). When the deck names a catalog `design.theme`, `a:theme` and its `thm15:themeFamily` take that theme's name. The rewrite happens during package normalization; the vendored PptxGenJS bytes are unchanged.
+
+Document colors that name a slot or role (`accent2`, `textSecondary`, `surface`, ...) become `a:schemeClr` in runs, table cell fills and text, and table borders. Theme-slot backgrounds (`{type:'theme', slot}` or a slot name) do the same. Slide content reaches the theme through the master color map, so `dark1`, `light1`, `dark2` and `light2` are written as `tx1`, `bg1`, `tx2` and `bg2`. A reference becomes `schemeClr` only when the deck theme slot holds exactly the color the slide resolved. PowerPoint has one theme per master, so a slide-level `design.colorScheme` that changes a slot keeps that color literal. These stay `a:srgbClr`:
+
+- literal hex colors, even when they equal a scheme slot;
+- `var:<id>` variables;
+- translucent colors;
+- engine-derived chrome: default text, headings, list markers, muted text, card and chart panels, chart series, and default table header fill. These colors are contrast-selected per slide, not named by the document.
+- `hyperlink` and `followedHyperlink` run and cell colors, because PptxGenJS 4.0.1 cannot emit `hlink`/`folHlink`. Borders and backgrounds can.
+
+Import reads the first slide master's theme. An exact twelve-slot match with a bundled catalog scheme returns its id; the `clrScheme` name breaks ties. Otherwise the importer returns inline slots, relative to the catalog scheme the `clrScheme` is named after when there is one (`{id:'boost', accent1:'#123456'}`). A theme whose name equals a catalog theme's name maps to `design.theme` only if the package's color scheme or heading/body fonts match that theme; otherwise `theme-unverified` is reported. A missing theme, or slots that are not opaque sRGB/system colors, report `unsupported-theme-colors` on `design.colorScheme`. Slide colors are still imported as resolved hex. Role overrides such as `primary` have no theme slot and are not recovered. `test/theme-colors.mjs` covers all 14 catalog schemes and 4 catalog themes, override, foreign and damaged themes, and the literal-color boundaries. This establishes package structure and round-trip, not PowerPoint rendering.
 
 ## JPEG orientation on import
 
@@ -203,7 +290,7 @@ Since 0.2.1, the importer follows slide → layout → master background inherit
 
 The 0.2.1 importer applies `lum`, `lumMod`, `lumOff`, `alpha`, `alphaMod` and `alphaOff` in XML order, including repeated/interleaved transforms in theme definitions, style placeholders and gradient stops. Following DrawingML’s [luminance modulation](https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.drawing.luminancemodulation?view=openxml-3.0.1) and [luminance offset](https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.drawing.luminanceoffset?view=openxml-3.0.1) semantics, luminance adjustments retain hue and saturation, and opacity operations clamp after each step. Colors are rounded to RGB only after the full reference/transform chain. Tint/shade, saturation/hue, gamma and other transforms still produce diagnostics. The regression suite covers 70 inheritance, transform and diagnostic cases; these mathematical tests do not establish native viewer pixel parity.
 
-These colors become explicit editable OPF RGB fills. Import does not preserve a live link to the original PowerPoint master/theme. No external theme URL is fetched. Missing themes, unknown colors, unsupported color transforms, and unsupported image/pattern fills report `unsupported-background-fill` (or `unsupported-background-gradient` for gradients) at the slide background path.
+These colors become explicit editable OPF RGB fills. Import does not preserve a live link to the original PowerPoint master/theme. No external theme URL is fetched. Missing themes, unknown colors, unsupported color transforms, and unsupported fills (including patterns without a DrawingML preset or explicit colors) report `unsupported-background-fill` (or `unsupported-background-gradient` for gradients) at the slide background path.
 
 The regression fixtures cover inheritance, overrides, interleaved style lists, repeated export/import, source preservation and observable failures. The style indexes follow the [Open XML background-reference definition](https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.presentation.backgroundstylereference?view=openxml-3.0.1). They prove conversion semantics, not universal native appearance. Keynote displayed a fixture referencing `fillStyleLst` index 2 as white; native comparison of other reference forms is still incomplete. Microsoft PowerPoint remains unverified. This work is not included in npm 0.2.0.
 
@@ -237,6 +324,10 @@ Version 0.5.0 requires core 0.7.0 and renderer 0.5.0 for coordinated previews. `
 
 Version 0.8.0 exports editable native lines with explicit four-space tab stops. Boundary tags contain no original source words, so native edits and deletions remain authoritative. XML-unrepresentable scalar controls reject with an actionable path rather than silently losing characters. Twenty wide/portrait measured/estimated export cases, current-text mutation controls and damaged-tag fallbacks pass; native Office acceptance remains separate. The coordinated core browser workflow also verifies editing, undo and exact reimport.
 
-The unpublished furniture candidate exports core's accepted header/footer text and picture geometry. Dedicated `OPF_FURNITURE_V1` tags describe roles, line boundaries, inactive flags and global/local scope. A slide manifest represents empty or disabled definitions without adding a visible shape. Tags contain no original text, image bytes or alt text. Reimport reads those values from current native shapes; complete groups recover literal dates, section/organization metadata and page-number intent when the current number matches the current slide position.
+Version 0.9.1 exports core's accepted header/footer text and picture geometry as editable tagged slide shapes. Native Office Header/Footer objects (`p:hf` / notes master) remain deferred [core issue87](https://github.com/OpenPresentation/opf/issues/87) work. Dedicated `OPF_FURNITURE_V1` tags describe roles, line boundaries, inactive flags and global/local scope. A slide manifest represents empty or disabled definitions without adding a visible shape. Tags contain no original text, image bytes or alt text. Reimport reads those values from current native shapes; complete groups recover literal dates, section/organization metadata and page-number intent when the current number matches the current slide position.
+
+Slide numbers inside those shapes are native PowerPoint slide-number fields (`<a:fld type="slidenum">`), so PowerPoint renumbers them when slides move. A `slideNumberFormat` such as `"A-{current}"` or `"{current} / {total}"` keeps its literal text and `{total}` (the exported slide count) as fixed runs around the field; PowerPoint has no slide-count field. A current date (`date: true`) needs the host's `date` option (ISO `YYYY-MM-DD`); it becomes a native `datetime1`–`datetime7` field when its `dateFormat` matches that en-US field type, and otherwise fixed text with a `furniture-date-fixed` diagnostic. An eligible date or number range that spans accepted text lines stays static and reports `furniture-field-fixed` at its source path; no native field is created by merging shapes. A string date with `dateFormat` is fixed text. The slide manifest records `slideNumberFormat`/`dateFormat` settings, never their rendered words: reimport keeps a format only while the current native text still matches it (a slide number at its current position, a fixed date that parses back to the same ISO date), and a live date keeps the pattern of its current field type. Otherwise the current words import as literal text. Hiding furniture on a title slide is a slide-level `design.footer: false`/`design.header: false`, which round-trips as before.
+
+When a supported current-date field wraps across lines, full provenance records a versioned static-date reason, its format and exact line fingerprints, without cached date words. Complete unchanged soft-wrapped lines can then recover `date: true` and the authored format on reimport, so a later OPF export can use a new host date. The original PPTX date remains static: this does not establish native refresh or Office compatibility. Actual current native date fields take precedence. Edited or cleared text, damaged evidence, older unmarked exports, `references-only` and `provenance: false` remain literal/current-content fallbacks. Fingerprints detect changed text; writable tags are not authentication. Native formatting and geometry are not reconstructed.
 
-Missing, duplicated or inconsistent furniture tags fall back to current native content with an `invalid-furniture-provenance` diagnostic. Conflicting organization or section values also fall back. Inherited definitions become global only when every slide has a valid definition/override and all inherited values agree; otherwise recovered definitions stay local. Reordering slides with unchanged visible page numbers preserves those numbers as ordinary text instead of silently renumbering them. Native typography, positioning, crop and unrelated metadata are not reconstructed; `furniture-import-reflow` requests review. `npm run test:furniture` exercises XML conversion and mutation controls. Native Office, visual corpus and clean installed-package acceptance remain separate gates; this behavior is not yet published.
+Missing, duplicated or inconsistent furniture tags fall back to current native content with an `invalid-furniture-provenance` diagnostic. Conflicting organization or section values also fall back. Inherited definitions become global only when every slide has a valid definition/override and all inherited values agree; otherwise recovered definitions stay local. Reordering slides with unchanged visible page numbers preserves those numbers as ordinary text instead of silently renumbering them. Native typography, positioning, crop and unrelated metadata are not reconstructed; `furniture-import-reflow` requests review. `npm run test:furniture` exercises XML conversion and mutation controls. Native Office, visual corpus and clean installed-package acceptance remain separate gates; published tagged-shape furniture does not establish native Header/Footer support.

package/dist/background-import.js

@@ -1,5 +1,6 @@
 import {XMLParser} from 'fast-xml-parser';
-import {readNativeBackground, readBackgroundColor, colorTransforms} from './background.js';
+import {readNativeBackground, readBackgroundColor, colorTransforms, nativeTileScale, nativeTileAlignment} from './background.js';
+import {rasterMetadata} from './image-geometry.js';
 
 const orderedParser = new XMLParser({ignoreAttributes: false, attributeNamePrefix: '', preserveOrder: true, parseAttributeValue: false, parseTagValue: false, trimValues: false});
 const defaultMapping = {bg1:'lt1',tx1:'dk1',bg2:'lt2',tx2:'dk2'};
@@ -66,13 +67,15 @@ export function readSlideTheme(slidePath, {part, relationships, bytes}) {
 
 export function importBackground(slidePath, dimensions, archive, report) {
   const {chain, colors, mapping, format, formatPath, parsedPart} = readSlideTheme(slidePath, archive);
-  const background = chain.map(item => item.root?.['p:cSld']?.['p:bg']).find(value => value !== undefined);
+  const owner = chain.find(item => item.root?.['p:cSld']?.['p:bg'] !== undefined);
+  const background = owner?.root['p:cSld']['p:bg'];
   if (!background) return undefined;
   const unsupported = () => {
     report({code:'unsupported-background-fill',message:'The native background style reference or its theme color could not be resolved from this PPTX archive.'});
     return undefined;
   };
-  const context = {colors, mapping};
+  // Picture relationships belong to the part that holds the fill.
+  const context = {colors, mapping, image: fill => readImageBackground(fill, owner.path, archive, dimensions, report)};
   if (background['p:bgPr']) return readNativeBackground(background['p:bgPr'], dimensions, report, context);
   const reference = background['p:bgRef'];
   if (!/^\d+$/.test(reference?.idx ?? '')) return unsupported();
@@ -90,5 +93,58 @@ export function importBackground(slidePath, dimensions, archive, report) {
   const style = styles?.[index < 1000 ? index - 1 : index - 1001];
   if (!style) return unsupported();
   context.placeholder = readBackgroundColor(reference, context);
+  context.image = fill => readImageBackground(fill, formatPath, archive, dimensions, report);
   return readNativeBackground(drawingObject([style]), dimensions, report, context);
 }
+
+const imageEffects = new Set(['r:embed', 'r:link', 'cstate', 'a:alphaModFix', 'a:lum', 'a:extLst']);
+const inset = (rect, key) => Number(rect?.[key] ?? 0) / 100000;
+const near = (a, b) => Math.abs(a - b) <= .005;
+
+// Import an embedded raster picture fill as an OPF image background. OPF's
+// cover/contain/tile fits are recovered from the stretch/tile geometry; any
+// other stretch (off-center crop, distortion) or unsupported picture effect is
+// imported as the closest centered cover and reported.
+function readImageBackground(fill, partPath, {relationships, bytes}, dimensions, report) {
+  const blip = fill['a:blip'] ?? {};
+  const relationship = blip['r:embed'] && relationships(partPath).get(blip['r:embed']);
+  const data = relationship && relationship.targetMode !== 'External' ? bytes(relationship.path) : undefined;
+  const metadata = data && rasterMetadata(data);
+  if (!metadata) {
+    report({code: 'unsupported-background-image', message: 'The native background picture is linked, missing, or not an embedded PNG, JPEG, GIF or WebP raster; its background was not imported.'});
+    return undefined;
+  }
+  const approximate = reason => report({code: 'approximate-background-image', message: `The native background picture ${reason}; it was imported as the closest OPF image background.`});
+  const lum = blip['a:lum'];
+  if (Object.keys(blip).some(key => !imageEffects.has(key)) || (lum && Object.keys(lum).length)) approximate('uses picture effects outside OPF opacity');
+  const amount = blip['a:alphaModFix'] ? Number(blip['a:alphaModFix'].amt ?? 100000) / 100000 : 1;
+  const opacity = Number.isFinite(amount) ? Math.max(0, Math.min(1, amount)) : 1;
+  let fit = 'cover';
+  if (fill['a:tile']) {
+    fit = 'tile';
+    // OPF tile has one geometry: top-left min(w,h)/4 cells holding the whole
+    // image (the default contain imageFill), at the raster's own resolution.
+    const tile = fill['a:tile'], crop = fill['a:srcRect'];
+    const expected = nativeTileScale(metadata, dimensions);
+    const x = (1 - expected.cell / (metadata.width * expected.scale)) / 2, y = (1 - expected.cell / (metadata.height * expected.scale)) / 2;
+    const value = (raw, fallback) => raw === undefined ? fallback : Number(raw);
+    const scaled = (raw, target) => Math.abs(value(raw, 100000) - target) <= Math.max(2, target * .005);
+    const matches = scaled(tile.sx, expected.sx) && scaled(tile.sy, expected.sy)
+      && Object.entries(nativeTileAlignment).every(([key, native]) => String(tile[key] ?? native) === native)
+      && near(inset(crop, 'l'), x) && near(inset(crop, 'r'), x) && near(inset(crop, 't'), y) && near(inset(crop, 'b'), y);
+    if (!matches) approximate('tiles with a scale, offset, alignment, flip or crop that the OPF tile fit does not express');
+  } else {
+    const crop = fill['a:srcRect'], box = fill['a:stretch']?.['a:fillRect'];
+    const [l, t, r, b] = ['l', 't', 'r', 'b'].map(key => inset(crop, key));
+    const [fl, ft, fr, fb] = ['l', 't', 'r', 'b'].map(key => inset(box, key));
+    const source = metadata.width * (1 - l - r) / (metadata.height * (1 - t - b));
+    const target = dimensions.width * (1 - fl - fr) / (dimensions.height * (1 - ft - fb));
+    const aspect = Number.isFinite(source) && Number.isFinite(target) && source > 0 && target > 0 && Math.abs(source / target - 1) <= .005;
+    const noCrop = [l, t, r, b].every(value => near(value, 0)), noInset = [fl, ft, fr, fb].every(value => near(value, 0));
+    if (aspect && noInset && near(l, r) && near(t, b) && Math.min(l, t) >= 0) fit = 'cover';
+    else if (aspect && noCrop && near(fl, fr) && near(ft, fb) && Math.min(fl, ft) >= 0) fit = 'contain';
+    else approximate('is cropped off-center, distorted or offset');
+  }
+  const binary = typeof Buffer !== 'undefined' ? Buffer.from(data).toString('base64') : btoa(Array.from(data, byte => String.fromCharCode(byte)).join(''));
+  return {type: 'image', image: {src: `data:${metadata.mediaType};base64,${binary}`, fit}, ...(opacity === 1 ? {} : {opacity})};
+}

package/dist/background.js

@@ -16,11 +16,43 @@ function colorXml(value, opacity, fallback) {
   return `<a:srgbClr val="${c.hex}">${alpha === 100000 ? '' : `<a:alpha val="${alpha}"/>`}</a:srgbClr>`;
 }
 
-export function nativeBackgroundFill(background, {width, height}, fallback = 'FFFFFF') {
+// ECMA-376 Part 1, 20.1.10.51 ST_PresetPatternVal. OPF pattern presets with
+// these names are DrawingML presets; any other id is engine-defined.
+export const presetPatterns = new Set(['pct5', 'pct10', 'pct20', 'pct25', 'pct30', 'pct40', 'pct50', 'pct60', 'pct70', 'pct75', 'pct80', 'pct90',
+  'horz', 'vert', 'ltHorz', 'ltVert', 'dkHorz', 'dkVert', 'narHorz', 'narVert', 'dashHorz', 'dashVert', 'cross',
+  'dnDiag', 'upDiag', 'ltDnDiag', 'ltUpDiag', 'dkDnDiag', 'dkUpDiag', 'wdDnDiag', 'wdUpDiag', 'dashDnDiag', 'dashUpDiag', 'diagCross',
+  'smCheck', 'lgCheck', 'smGrid', 'lgGrid', 'dotGrid', 'smConfetti', 'lgConfetti', 'horzBrick', 'diagBrick',
+  'solidDmnd', 'openDmnd', 'dotDmnd', 'plaid', 'sphere', 'weave', 'divot', 'shingle', 'wave', 'trellis', 'zigZag']);
+
+// Engine-defined presets drawn by the SVG preview, with their closest DrawingML
+// preset. diagStripe is a 2px rising diagonal on an 8px cell, as wdUpDiag.
+// Import reports the native preset name; it does not guess the OPF alias.
+const patternAliases = {diagStripe: 'wdUpDiag'};
+export const nativePatternPreset = preset => presetPatterns.has(preset) ? preset : Object.hasOwn(patternAliases, preset) ? patternAliases[preset] : undefined;
+
+// The SVG preview paints the pattern background color and foreground marks,
+// defaulting to white and the slide text color. Other engine-defined presets
+// have no DrawingML equivalent; like the preview, only their background color remains.
+// `scheme(reference, hex)` names the theme color for an authored slot/role
+// reference whose drawn color the deck theme holds exactly (FF-24); pattern
+// colors then become a:schemeClr, keeping any background opacity as alpha.
+export function nativeBackgroundFill(background, {width, height}, fallback = 'FFFFFF', foreground = '000000', scheme = () => undefined) {
   if (typeof background === 'string' && /^#[\da-f]{3}(?:[\da-f]{3}(?:[\da-f]{2})?)?$/i.test(background)) background = {type: 'solid', color: background};
   if (!background || typeof background !== 'object') return null;
   const opacity = background.opacity ?? 1;
   if (background.type === 'solid' || background.type === 'theme') return `<a:solidFill>${colorXml(background.type === 'theme' ? fallback : background.color, opacity, fallback)}</a:solidFill>`;
+  if (background.type === 'pattern') {
+    const paint = (value, base) => {
+      const c = color(value, base), themeValue = c.alpha === 1 ? scheme(value, c.hex) : undefined;
+      if (!themeValue) return colorXml(value, opacity, base);
+      const alpha = Math.round(clamp(opacity) * 100000);
+      return `<a:schemeClr val="${themeValue}">${alpha === 100000 ? '' : `<a:alpha val="${alpha}"/>`}</a:schemeClr>`;
+    };
+    const pattern = background.pattern ?? {}, back = paint(pattern.backgroundColor, 'FFFFFF');
+    const preset = nativePatternPreset(pattern.preset);
+    if (!preset) return `<a:solidFill>${back}</a:solidFill>`;
+    return `<a:pattFill prst="${preset}"><a:fgClr>${paint(pattern.foregroundColor, foreground)}</a:fgClr><a:bgClr>${back}</a:bgClr></a:pattFill>`;
+  }
   if (background.type !== 'gradient') return null;
   const stops = background.gradient?.stops ?? [];
   if (!stops.length) return '<a:noFill/>';
@@ -38,6 +70,42 @@ export function nativeBackgroundFill(background, {width, height}, fallback = 'FF
   return `<a:gradFill rotWithShape="0"><a:gsLst>${nativeStops}</a:gsLst><a:lin ang="${angle}" scaled="0"/></a:gradFill>`;
 }
 
+const rectXml = (name, rect = {}) => `<a:${name}${['l', 't', 'r', 'b'].filter(key => rect[key]).map(key => ` ${key}="${rect[key]}"`).join('')}/>`;
+const percent = value => Math.round(value * 100000);
+
+// Picture fill for an OPF image background, following the SVG preview:
+// cover crops the centered source to the slide aspect, contain letterboxes it
+// with fill-rectangle insets, and tile repeats square cells of min(w,h)/4
+// from the top-left corner. Each cell holds the image by the deck imageFill
+// (crop = cover, otherwise contain; negative source insets are transparent
+// padding). With dpi="0", DrawingML sizes a tile from the raster's own
+// resolution (PNG pHYs, JPEG JFIF or EXIF; 96 dpi when absent), while the
+// preview draws CSS pixels, so the tile scale compensates on each axis.
+export const nativeTileAlignment = {tx: '0', ty: '0', flip: 'none', algn: 'tl'};
+export function nativeTileScale(image, {width, height, imageFill = 'fit'}) {
+  const cell = Math.min(width, height) / 4;
+  const scale = (imageFill === 'crop' ? Math.max : Math.min)(cell / image.width, cell / image.height);
+  return {cell, scale, sx: percent(scale * (image.dpiX ?? 96) / 96), sy: percent(scale * (image.dpiY ?? 96) / 96)};
+}
+export function nativeImageBackgroundFill(relationshipId, image, {fit = 'cover', opacity = 1, width, height, imageFill = 'fit'}) {
+  const alpha = clamp(opacity);
+  const blip = `<a:blip r:embed="${relationshipId}">${alpha === 1 ? '' : `<a:alphaModFix amt="${percent(alpha)}"/>`}</a:blip>`;
+  if (fit === 'tile') {
+    const {cell, scale, sx, sy} = nativeTileScale(image, {width, height, imageFill});
+    const x = percent((1 - cell / (image.width * scale)) / 2), y = percent((1 - cell / (image.height * scale)) / 2);
+    const {tx, ty, flip, algn} = nativeTileAlignment;
+    return `<a:blipFill dpi="0" rotWithShape="1">${blip}${rectXml('srcRect', {l: x, t: y, r: x, b: y})}<a:tile tx="${tx}" ty="${ty}" sx="${sx}" sy="${sy}" flip="${flip}" algn="${algn}"/></a:blipFill>`;
+  }
+  if (fit === 'contain') {
+    const scale = Math.min(width / image.width, height / image.height);
+    const x = percent((1 - image.width * scale / width) / 2), y = percent((1 - image.height * scale / height) / 2);
+    return `<a:blipFill dpi="0" rotWithShape="1">${blip}<a:srcRect/><a:stretch>${rectXml('fillRect', {l: x, t: y, r: x, b: y})}</a:stretch></a:blipFill>`;
+  }
+  const scale = Math.max(width / image.width, height / image.height);
+  const x = percent((1 - width / (image.width * scale)) / 2), y = percent((1 - height / (image.height * scale)) / 2);
+  return `<a:blipFill dpi="0" rotWithShape="1">${blip}${rectXml('srcRect', {l: x, t: y, r: x, b: y})}<a:stretch><a:fillRect/></a:stretch></a:blipFill>`;
+}
+
 // Internal metadata supplied by the ordered XML reader. A Symbol cannot collide
 // with a document attribute, and repeated transforms keep their original order.
 export const colorTransforms = Symbol('DrawingML color transforms');
@@ -98,11 +166,28 @@ export function readBackgroundColor(node, context = {}, seen = new Set()) {
   return {hex: luminanceHex(luminance), alpha, luminance};
 }
 
+// A preset pattern with explicit foreground and background colors. ECMA-376
+// defines no default colors, so a pattern missing either one is not guessed.
+function readNativePattern(pattern, report, context) {
+  const foreground = pattern['a:fgClr'] && readBackgroundColor(pattern['a:fgClr'], context);
+  const background = pattern['a:bgClr'] && readBackgroundColor(pattern['a:bgClr'], context);
+  if (!presetPatterns.has(pattern.prst) || !foreground || !background) {
+    report({code: 'unsupported-background-fill', message: 'This native pattern needs a DrawingML preset with resolvable foreground and background colors to become an OPF pattern background.'});
+    return undefined;
+  }
+  const uniform = foreground.alpha === background.alpha;
+  const hex = c => c.hex + (!uniform && c.alpha !== 1 ? Math.round(c.alpha * 255).toString(16).padStart(2, '0').toUpperCase() : '');
+  return {type: 'pattern', pattern: {preset: pattern.prst, foregroundColor: hex(foreground), backgroundColor: hex(background)},
+    ...(uniform && foreground.alpha !== 1 ? {opacity: foreground.alpha} : {})};
+}
+
 export function readNativeBackground(properties, {width, height}, report = () => {}, context = {}) {
   if (!properties) return undefined;
   if (Object.hasOwn(properties, 'a:noFill')) return {type: 'solid', color: '#FFFFFF', opacity: 0};
   const solid = readBackgroundColor(properties['a:solidFill'], context);
   if (solid) return {type: 'solid', color: solid.hex, ...(solid.alpha === 1 ? {} : {opacity: solid.alpha})};
+  if (properties['a:pattFill']) return readNativePattern(properties['a:pattFill'], report, context);
+  if (properties['a:blipFill'] && context.image) return context.image(properties['a:blipFill']);
   const gradient = properties['a:gradFill'];
   if (!gradient) {
     report({code: 'unsupported-background-fill', message: 'This native background fill or color cannot be represented by the OPF background importer.'});

package/dist/body-text-import.js

@@ -0,0 +1,86 @@
+// Current ordinary native body text only. This reader never reads OPF tags or
+// recovers authoring boundaries across separate native text shapes.
+import {XMLParser} from 'fast-xml-parser';
+import {drawingObject, readSlideTheme} from './background-import.js';
+import {nativeRunStyle, mergeNativeRunProperties} from './native-text-style.js';
+
+const parser = new XMLParser({ignoreAttributes:false, attributeNamePrefix:'', preserveOrder:true, parseAttributeValue:false, parseTagValue:false, trimValues:false, htmlEntities:true});
+const nodes = (tree, tag) => (tree ?? []).filter(node => Object.hasOwn(node, tag));
+const child = (tree, tag) => nodes(tree, tag)[0]?.[tag];
+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 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])
+]));
+
+function bodyRunStyle(properties, context, relationships, report) {
+  const supported = {...properties};
+  for (const key of ['b', 'i']) if (properties[key] !== undefined && !['1','0','true','false','on','off'].includes(properties[key])) {
+    report('unsupported-body-text-style', `The native ${key} value is not a supported boolean; current text was retained.`);
+    delete supported[key];
+  }
+  for (const [key, allowed] of [['u', ['none','sng']], ['strike', ['noStrike','sngStrike']]]) if (properties[key] !== undefined && !allowed.includes(properties[key])) {
+    report('unsupported-body-text-style', `The native ${key} variant is not represented by an OPF boolean; current text was retained.`);
+    delete supported[key];
+  }
+  if (properties.sz !== undefined && (!Number.isFinite(Number(properties.sz)) || Number(properties.sz) <= 0)) {
+    report('unsupported-body-text-style', 'The native font size is not a positive finite value; current text was retained.');
+    delete supported.sz;
+  }
+  if (properties.baseline !== undefined) {
+    const baseline = Number(properties.baseline);
+    if (!Number.isFinite(baseline)) {
+      report('unsupported-body-text-style', 'The native baseline is not finite; current text was retained.');
+      delete supported.baseline;
+    } else if (![0,30000,-30000].includes(baseline)) {
+      report('approximate-body-text-baseline', 'OPF retains the native baseline direction, but cannot represent its exact offset.');
+    }
+  }
+  for (const key of ['a:latin','a:solidFill','a:hlinkClick']) if (Array.isArray(properties[key])) {
+    report('unsupported-body-text-style', `Repeated native ${key} properties are ambiguous; current text was retained.`);
+    delete supported[key];
+  }
+  for (const key of ['a:ea','a:cs','a:sym']) if (properties[key]?.typeface && properties[key].typeface !== properties['a:latin']?.typeface) {
+    report('unsupported-body-font', 'Script-specific native faces cannot be represented by one OPF run font family; the Latin face and current text were retained.');
+  }
+  if (properties['a:hlinkMouseOver']) report('unsupported-body-link', 'A native mouse-over action cannot be represented by an OPF run URL.');
+  if (['a:uLn', 'a:uFill', 'a:highlight', 'a:effectLst', 'a:effectDag', 'a:ln'].some(key => properties[key]) ||
+    (properties.cap !== undefined && properties.cap !== 'none') || (properties.spc !== undefined && Number(properties.spc) !== 0)) {
+    report('unsupported-body-text-style', 'Native text effects, capitalization, spacing or underline decoration are not represented by OPF run properties; current text was retained.');
+  }
+  return nativeRunStyle(supported, context, relationships, report, 'body');
+}
+
+export function nativeBodyReader(slidePath, archive, relationships, report) {
+  let bodies, context;
+  return index => {
+    if (!bodies) {
+      const tree = archive.part(slidePath, parser);
+      bodies = shapes(child(child(child(tree, 'p:sld'), 'p:cSld'), 'p:spTree')).map(shape => child(shape, 'p:txBody'));
+      context = readSlideTheme(slidePath, archive);
+    }
+    const body = bodies[index];
+    if (!body) return undefined;
+    const listStyle = drawingObject(child(body, 'a:lstStyle'));
+    return nodes(body, 'a:p').map((paragraph, paragraphIndex) => {
+      const content = paragraph['a:p'], pPr = drawingObject(child(content, 'a:pPr'));
+      const level = Number(nodes(content, 'a:pPr')[0]?.[':@']?.lvl ?? 0) + 1;
+      const defaults = mergeNativeRunProperties(listStyle['a:defPPr']?.['a:defRPr'], listStyle[`a:lvl${level}pPr`]?.['a:defRPr'], pPr['a:defRPr']);
+      const runs = [];
+      let runIndex = 0;
+      for (const node of content) {
+        const tag = ['a:r','a:fld','a:br'].find(name => Object.hasOwn(node, name));
+        if (!tag) continue;
+        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}));
+        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)};
+    });
+  };
+}