@openpresentation/opf-pptx 0.1.0 → 0.2.1

package/README.md

@@ -66,6 +66,8 @@ The first importer is mechanical and schema-compatible:
 - Slide text placeholders and large top-of-slide text boxes map to `title` and `subtitle` when recognizable.
 - 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.
+- 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.
+- Imported table values are display strings: numeric/boolean/null types, rich cell formatting, whitespace and merged-cell semantics are not losslessly reconstructed.
 - Unknown non-text shapes and unsupported graphic frames become editable text fallback blocks instead of failing the import.
 
 There is no AI classification pass in the OSS runtime. Hosts can run optional cleanup or semantic remapping after `fromPptx` returns.
@@ -118,3 +120,71 @@ For crowded drafts, run `paginatePresentation` from `@openpresentation/opf/pagin
 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.
 
 PptxGenJS is pinned to 4.0.1. Its unused `image-size` dependency remains flagged by npm audit; tested OPF operations run with that parser blocked. See [dependency reachability and regression coverage](DEPENDENCY-NOTES.md).
+
+### Native table fitting (unreleased)
+
+The development 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 shrinking, 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.
+
+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.
+
+## Image geometry (unreleased)
+
+Native image exports now follow the browser's `design.imageFill`: `fit` (the default) centers an image without changing its aspect ratio, and `crop` fills the allocated box with a centered native crop. Slide settings override presentation settings. Geometry is calculated from the exact bytes embedded after asset resolution, so host resolvers are called once. PNG, JPEG, GIF and WebP dimension headers are supported; unsupported or unreadable dimensions produce a path-specific error rather than a distorted picture. Supply supported raster bytes through `imageResolver` for other formats.
+
+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.
+
+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.
+
+Raster media filenames and package content types are derived from the embedded PNG/JPEG/GIF/WebP bytes. A resolver may change the format without preserving an old asset MIME hint; import likewise detects these formats from their bytes. This metadata repair does not recompress images, validate every compressed pixel stream, fetch resources or establish viewer support for each format.
+
+Native viewer check: Keynote 14.4 displays the PNG/JPEG/GIF media-type specimens, but imports an unchanged WebP as an empty rectangle. The default compatible export now converts WebP to a static PNG locally. Keynote displays all six converted specimens, including alpha, EXIF orientation and the first animation frame. Microsoft PowerPoint has not been verified.
+
+### Compatible WebP pictures
+
+`toPptx` defaults to `imageFormat: "compatible"`. After resolving and embedding an image once, WebP bytes are decoded to a static PNG. Alpha and EXIF orientation are retained in the decoded pixels; animated input uses its first frame. Fit/crop is then calculated from the resulting PNG dimensions. The original OPF input and source bytes are unchanged, but the PPTX contains the PNG rather than the original WebP or its metadata.
+
+Set `imageFormat: "preserve"` to embed WebP unchanged when the receiving application supports it. Other image formats keep their existing export behavior. Conversion errors include the OPF image path; images above 40 megapixels are rejected before compatible conversion. Decoder differences can affect color/alpha rounding, so byte identity across platforms is not promised.
+
+Node conversion lazily loads the pinned open-source Sharp dependency and requires Node 20.9 or later. Normal package installation must include platform optional dependencies for its native binaries. Browser bundles select a separate browser decoder using local Blob/image/canvas APIs; Sharp and Node code are excluded. Neither path uploads images or fetches asset URLs. Source-preserving export and ordinary PNG/JPEG/GIF operations do not load Sharp.
+
+`npm test` includes the Node pixel-reference cases and verifies browser bundling. To run the browser pixel checks, run `npm run build:browser-check`, serve this repository locally, and open `/artifacts/webp-fallback/browser/index.html`. The page reports 13 checks covering embedded PNG pixels, alpha, EXIF, the first animation frame, fit/crop, resolver calls and DOM canvas fallback. These are browser export checks, separate from the recorded Keynote viewing evidence.
+
+
+## Native background fills (unreleased)
+
+Fixed solid and linear-gradient backgrounds now export as native slide fills, keeping the background editable without rasterizing slide content. Deck defaults, inline theme overrides and per-slide overrides are resolved before export. Solid opacity, gradient stop colors/positions and combined color/background alpha are preserved. Empty and single-stop gradients follow the SVG preview's transparent/solid behavior; descending stop positions clamp to the preceding stop.
+
+Diagonal gradients require a coordinate conversion: the preview uses an SVG object-bounding-box gradient, while native unscaled DrawingML angles use slide coordinates. Export converts both the physical gradient direction and stop interval. Tests compare 990 sample positions from serialized SVG/native properties across 33 gradients and three aspect ratios, plus solid opacity, inheritance, native edits and repeated imports/exports. Integer native angles/positions introduce small rounding differences. The mapping follows the [DrawingML linear-gradient angle definition](https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.drawing.lineargradientfill?view=openxml-3.0.1).
+
+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.
+
+
+## JPEG orientation on import (unreleased)
+
+`fromPptx` now preserves native quarter-turns and mirroring for JPEG pictures by writing the combined orientation into EXIF metadata. Existing embedded EXIF orientation is applied before the native transform. This requires no pixel decoder, recompression, upload or new dependency. The original PPTX remains unchanged, and alternative text survives. The eight orientations produced by this exporter restore the exact source JPEG bytes through repeated fit-mode export/import cycles.
+
+When a JPEG has no orientation tag, import either adds a minimal EXIF segment or appends an IFD0 that retains the existing metadata entries, referenced data offsets and next-IFD link. Malformed or full EXIF segments are left untouched and reported. Tests cover both byte orders, embedded metadata plus native transformations, native picture edits, exact compressed-byte retention and independently permuted pixels.
+
+This preserves image orientation, not arbitrary picture geometry. Crop windows, non-quarter-turn rotations, non-JPEG rotations/mirroring and unsupported EXIF structures retain their original image bytes and report `unsupported-image-crop` or `unsupported-image-orientation` through `FromPptxOptions.onDiagnostic`. Picture diagnostic paths identify native picture order, for example `slides.0.pictures.0`. Import still recomposes OPF layout and does not promise exact native placement, crop, effects, groups or full picture round-trip fidelity. Third-party native viewers may handle already-oriented embedded JPEGs differently; the metadata-before-native composition is the importer contract, not a cross-viewer parity claim.
+
+### Inherited native backgrounds (0.2.1)
+
+Since 0.2.1, the importer follows slide → layout → master background inheritance. An explicit slide background, including no-fill or an unsupported fill, takes precedence over inherited content. Solid and representable linear fills resolve theme slots through the master color map and layout/slide overrides; system colors use the saved `lastClr` fallback. Theme overrides can replace the color scheme or format scheme. Background style references use the original XML order in `fillStyleLst`/`bgFillStyleLst`, including placeholder colors and alpha. Theme-slot OPF exports also retain background opacity.
+
+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.
+
+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.
+
+Native dimensions retain full precision through import. Premature six-decimal inch rounding could change raster edges even on a 1280-pixel slide. With the local JPEG-aware renderer, all eight complete image-slide PNG previews now match their original OPF previews after native export/import; this remains an OPF-renderer comparison, not a native viewer pixel comparison.
+
+Background-only and empty slides now remain blank during PPTX import; the importer no longer inserts a synthetic “Slide N” title. Speaker notes remain separate from visible content. Native fixture verification covers this behavior using an actual Keynote-exported presentation.
+
+Version 0.2.0 requires Node 20.9 or later for native image decoding. Browser bundles continue using browser-safe entrypoints.

package/dist/background-import.js

@@ -0,0 +1,88 @@
+import {XMLParser} from 'fast-xml-parser';
+import {readNativeBackground, readBackgroundColor, colorTransforms} from './background.js';
+
+const orderedParser = new XMLParser({ignoreAttributes: false, attributeNamePrefix: '', preserveOrder: true, parseAttributeValue: false, parseTagValue: false});
+const defaultMapping = {bg1:'lt1',tx1:'dk1',bg2:'lt2',tx2:'dk2'};
+const children = (nodes, name) => nodes?.find(node => Object.hasOwn(node, name))?.[name];
+function object(nodes) {
+  const result = Object.create(null);
+  for (const node of nodes ?? []) for (const [name, value] of Object.entries(node)) {
+    if (name === ':@' || name === '#text') continue;
+    const child = {...(node[':@'] ?? {}), ...object(value)};
+    if (['a:srgbClr', 'a:sysClr', 'a:schemeClr'].includes(name)) {
+      child[colorTransforms] = (value ?? []).flatMap(item => Object.keys(item)
+        .filter(key => key !== ':@' && key !== '#text')
+        .map(key => [key, {...(item[':@'] ?? {}), ...object(item[key])}]));
+    }
+    if (Object.hasOwn(result, name)) result[name] = Array.isArray(result[name]) ? [...result[name], child] : [result[name], child];
+    else result[name] = child;
+  }
+  return result;
+}
+
+// Cache by archive entry identity. Weak keys release parsed themes when the
+// input archive is collected and avoid reparsing a shared master for every slide.
+const parsedParts = new WeakMap();
+function parsed(bytes, parse) {
+  if (!bytes) return undefined;
+  if (!parsedParts.has(bytes)) {
+    const tree = parse();
+    parsedParts.set(bytes, {tree, value: object(tree)});
+  }
+  return parsedParts.get(bytes);
+}
+
+// Resolve only relationships inside the input archive; never fetch theme URLs.
+export function importBackground(slidePath, dimensions, {part, relationships, bytes}, report) {
+  const parsedPart = path => parsed(bytes(path), () => part(path, orderedParser));
+  const value = path => parsedPart(path)?.value;
+  const related = (path, type) => [...relationships(path).values()].find(rel => rel.type.endsWith('/' + type) && bytes(rel.path))?.path;
+  const layoutPath = related(slidePath, 'slideLayout');
+  const masterPath = layoutPath && related(layoutPath, 'slideMaster');
+  const chain = [[slidePath, 'p:sld'], [layoutPath, 'p:sldLayout'], [masterPath, 'p:sldMaster']]
+    .filter(([path]) => path).map(([path, root]) => ({path, root:value(path)?.[root]}));
+  const master = chain.find(item => item.root?.['p:clrMap'])?.root;
+  const masterMapping = {...defaultMapping, ...master?.['p:clrMap']};
+  let mapping = masterMapping;
+  for (const {root} of [...chain].reverse()) {
+    const override = root?.['p:clrMapOvr'];
+    if (override?.['a:overrideClrMapping']) mapping = {...defaultMapping, ...override['a:overrideClrMapping']};
+    else if (override && Object.hasOwn(override, 'a:masterClrMapping')) mapping = masterMapping;
+  }
+  let colors, format, formatPath;
+  for (const {path} of [...chain].reverse()) {
+    for (const type of ['theme', 'themeOverride']) {
+      const themePath = related(path, type);
+      if (!themePath) continue;
+      const doc = value(themePath);
+      const elements = type === 'theme' ? doc?.['a:theme']?.['a:themeElements'] : doc?.['a:themeOverride'];
+      if (elements?.['a:clrScheme']) colors = elements['a:clrScheme'];
+      if (elements?.['a:fmtScheme']) {format = elements['a:fmtScheme'];formatPath = themePath;}
+    }
+  }
+  const background = chain.map(item => item.root?.['p:cSld']?.['p:bg']).find(value => value !== undefined);
+  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};
+  if (background['p:bgPr']) return readNativeBackground(background['p:bgPr'], dimensions, report, context);
+  const reference = background['p:bgRef'];
+  if (!/^\d+$/.test(reference?.idx ?? '')) return unsupported();
+  const index = Number(reference?.idx);
+  if (!Number.isInteger(index) || index < 0) return unsupported();
+  if (index === 0 || index === 1000) return {type:'solid',color:'#FFFFFF',opacity:0};
+  if (!format || !formatPath) return unsupported();
+  // Fill lists can interleave solid, gradient and image fills. Preserve XML
+  // child order when indexing them; the normal object parser groups tag names.
+  const tree = parsedPart(formatPath).tree;
+  const theme = children(tree, 'a:theme');
+  const elements = theme ? children(theme, 'a:themeElements') : children(tree, 'a:themeOverride');
+  const fmt = children(elements, 'a:fmtScheme');
+  const styles = children(fmt, index < 1000 ? 'a:fillStyleLst' : 'a:bgFillStyleLst')?.filter(node => Object.keys(node).some(k => k !== '#text' && k !== ':@'));
+  const style = styles?.[index < 1000 ? index - 1 : index - 1001];
+  if (!style) return unsupported();
+  context.placeholder = readBackgroundColor(reference, context);
+  return readNativeBackground(object([style]), dimensions, report, context);
+}

package/dist/background.js

@@ -0,0 +1,136 @@
+// SVG uses an object-bounding-box gradient. DrawingML's unscaled angle is
+// measured in slide coordinates. Convert the normal and stop interval together;
+// copying the angle alone changes diagonal gradients on non-square slides.
+const turn = angle => ((angle % 360) + 360) % 360;
+const clamp = value => Math.max(0, Math.min(1, value));
+const list = value => value === undefined ? [] : Array.isArray(value) ? value : [value];
+function color(value, fallback = 'FFFFFF') {
+  if (!/^[\da-f]{6}$/i.test(fallback)) fallback = 'FFFFFF';
+  let hex = typeof value === 'string' ? value.trim().replace(/^#/, '') : fallback;
+  if (/^[\da-f]{3}$/i.test(hex)) hex = [...hex].map(c => c + c).join('');
+  if (!/^[\da-f]{6}([\da-f]{2})?$/i.test(hex)) hex = fallback;
+  return {hex: hex.slice(0, 6).toUpperCase(), alpha: hex.length === 8 ? parseInt(hex.slice(6), 16) / 255 : 1};
+}
+function colorXml(value, opacity, fallback) {
+  const c = color(value, fallback), alpha = Math.round(c.alpha * opacity * 100000);
+  return `<a:srgbClr val="${c.hex}">${alpha === 100000 ? '' : `<a:alpha val="${alpha}"/>`}</a:srgbClr>`;
+}
+
+export function nativeBackgroundFill(background, {width, height}, fallback = 'FFFFFF') {
+  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 !== 'gradient') return null;
+  const stops = background.gradient?.stops ?? [];
+  if (!stops.length) return '<a:noFill/>';
+  if (stops.length === 1) return `<a:solidFill>${colorXml(stops[0].color, opacity, fallback)}</a:solidFill>`;
+  const radians = turn(background.gradient?.angle ?? 0) * Math.PI / 180;
+  const c = Math.cos(radians), s = Math.sin(radians), span = Math.abs(c) + Math.abs(s);
+  const angle = Math.round(turn(Math.atan2(s / height, c / width) * 180 / Math.PI) * 60000) % 21600000;
+  let prior = 0;
+  const nativeStops = stops.map(stop => {
+    // SVG clamps a descending stop to the preceding position.
+    prior = Math.max(prior, stop.position);
+    const position = Math.round(((prior - .5) / span + .5) * 100000);
+    return `<a:gs pos="${position}">${colorXml(stop.color, opacity, fallback)}</a:gs>`;
+  }).join('');
+  return `<a:gradFill rotWithShape="0"><a:gsLst>${nativeStops}</a:gsLst><a:lin ang="${angle}" scaled="0"/></a:gradFill>`;
+}
+
+// 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');
+const transformNames = new Set(['a:alpha', 'a:alphaMod', 'a:alphaOff', 'a:lum', 'a:lumMod', 'a:lumOff']);
+function luminanceColor(hex) {
+  const rgb = hex.match(/../g).map(value => parseInt(value, 16) / 255);
+  const max = Math.max(...rgb), min = Math.min(...rgb), l = (max + min) / 2, delta = max - min;
+  // Retain hue/saturation across consecutive luminance changes, even when an
+  // intermediate luminance clips to black or white.
+  return {l, saturation: delta === 0 ? 0 : delta / (1 - Math.abs(2 * l - 1)), direction: rgb.map(c => delta ? (c - l) / delta : 0)};
+}
+function luminanceHex({l, saturation, direction}) {
+  const chroma = (1 - Math.abs(2 * l - 1)) * saturation;
+  return '#' + direction.map(c => Math.round(clamp(l + c * chroma) * 255).toString(16).padStart(2, '0')).join('').toUpperCase();
+}
+export function readBackgroundColor(node, context = {}, seen = new Set()) {
+  const kinds = ['a:srgbClr', 'a:sysClr', 'a:schemeClr'].filter(k => node?.[k]);
+  if (kinds.length !== 1) return null;
+  const kind = kinds[0], c = node[kind];
+  if (Array.isArray(c) || Object.keys(c).some(k => !['val', 'lastClr'].includes(k) && !transformNames.has(k))) return null;
+  const entries = Object.entries(c).filter(([key]) => key.startsWith('a:'));
+  // The legacy object shape is safe for one transform only. Never guess the
+  // order of repeated/interleaved operations after an unordered parser.
+  const transforms = c[colorTransforms] ?? (entries.length <= 1 && entries.every(([,value]) => !Array.isArray(value)) ? entries : null);
+  if (!transforms) return null;
+  let resolved;
+  if (kind === 'a:schemeClr') {
+    if (c.val === 'phClr') resolved = context.placeholder;
+    else {
+      const slot = context.mapping?.[c.val] ?? c.val;
+      if (seen.has(slot)) return null;
+      resolved = readBackgroundColor(context.colors?.['a:' + slot], context, new Set([...seen, slot]));
+    }
+  } else {
+    const hex = kind === 'a:sysClr' ? c.lastClr : c.val;
+    if (!/^[\da-f]{6}$/i.test(hex ?? '')) return null;
+    resolved = {hex: '#' + hex.toUpperCase(), alpha: 1, luminance: luminanceColor(hex)};
+  }
+  if (!resolved) return null;
+  let alpha = resolved.alpha;
+  const luminance = {...(resolved.luminance ?? luminanceColor(resolved.hex.slice(1)))};
+  for (const [name, attributes] of transforms) {
+    if (!transformNames.has(name) || !attributes || Object.keys(attributes).some(key => key !== 'val')) return null;
+    const raw = attributes.val;
+    if (!/^[+-]?\d+$/.test(raw ?? '')) return null;
+    const value = Number(raw) / 100000;
+    if (!Number.isFinite(value)) return null;
+    if ((name === 'a:alpha' || name === 'a:lum') && (value < 0 || value > 1)) return null;
+    if (name === 'a:alphaMod' && value < 0) return null;
+    if (name === 'a:alphaOff' && Math.abs(value) > 1) return null;
+    if (name === 'a:alpha') alpha = value;
+    if (name === 'a:alphaMod') alpha = clamp(alpha * value);
+    if (name === 'a:alphaOff') alpha = clamp(alpha + value);
+    if (name === 'a:lum') luminance.l = value;
+    if (name === 'a:lumMod') luminance.l = clamp(luminance.l * value);
+    if (name === 'a:lumOff') luminance.l = clamp(luminance.l + value);
+  }
+  return {hex: luminanceHex(luminance), alpha, luminance};
+}
+
+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})};
+  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.'});
+    return undefined;
+  }
+  const unsupported = () => {
+    report({code: 'unsupported-background-gradient', message: 'This native gradient uses geometry or color transforms outside the OPF linear-gradient contract; its background was not imported.'});
+    return undefined;
+  };
+  const lin = gradient['a:lin'];
+  if (!lin || gradient['a:path'] || (gradient.flip && gradient.flip !== 'none')
+    || Object.values(gradient['a:tileRect'] ?? {}).some(value => Number(value) !== 0)) return unsupported();
+  let radians = Number(lin.ang ?? 0) / 60000 * Math.PI / 180;
+  if (!Number.isFinite(radians)) return unsupported();
+  // DrawingML scaled=true first scales the direction by the fill dimensions.
+  if (lin.scaled === '1' || lin.scaled === 'true') radians = Math.atan2(height * Math.sin(radians), width * Math.cos(radians));
+  const angle = turn(Math.atan2(height * Math.sin(radians), width * Math.cos(radians)) * 180 / Math.PI);
+  const a = angle * Math.PI / 180, span = Math.abs(Math.cos(a)) + Math.abs(Math.sin(a));
+  const stops = list(gradient['a:gsLst']?.['a:gs']).map(stop => {
+    const c = readBackgroundColor(stop, context), position = (Number(stop.pos) / 100000 - .5) * span + .5;
+    // Allow only native integer rounding, not a lossy clamping of arbitrary
+    // corner-to-corner gradients that OPF's fixed endpoints cannot represent.
+    if (!c || !Number.isFinite(position) || position < -.00002 || position > 1.00002) return null;
+    return {...c, position: clamp(position)};
+  });
+  if (!stops.length || stops.some(stop => !stop)) return unsupported();
+  const alpha = stops[0].alpha, uniform = stops.every(stop => stop.alpha === alpha);
+  return {type: 'gradient', gradient: {angle, stops: stops.map(stop => ({position: stop.position,
+    color: stop.hex + (!uniform && stop.alpha !== 1 ? Math.round(stop.alpha * 255).toString(16).padStart(2, '0').toUpperCase() : '')}))},
+    ...(uniform && alpha !== 1 ? {opacity: alpha} : {})};
+}

package/dist/image-fallback-browser.js

@@ -0,0 +1,33 @@
+// Decode only the supplied local bytes. No URL is fetched and no canvas is
+// attached to the document. Animated WebP becomes its first decoded frame.
+export async function webpToPng(bytes) {
+  const blob = new Blob([bytes], {type:'image/webp'});
+  let picture, objectUrl;
+  try {
+    if (typeof createImageBitmap === 'function') {
+      picture = await createImageBitmap(blob);
+    } else {
+      if (typeof Image === 'undefined') throw new Error('This browser has no image decoder.');
+      objectUrl = URL.createObjectURL(blob);
+      picture = new Image();
+      picture.src = objectUrl;
+      await picture.decode();
+    }
+    const width = picture.width || picture.naturalWidth;
+    const height = picture.height || picture.naturalHeight;
+    if (!width || !height || width * height > 40_000_000) throw new Error('Image dimensions exceed the 40 megapixel conversion limit.');
+    const canvas = typeof OffscreenCanvas === 'function'
+      ? new OffscreenCanvas(width, height) : document.createElement('canvas');
+    canvas.width = width; canvas.height = height;
+    const context = canvas.getContext('2d');
+    if (!context) throw new Error('This browser has no 2D canvas.');
+    context.drawImage(picture, 0, 0);
+    const png = canvas.convertToBlob
+      ? await canvas.convertToBlob({type:'image/png'})
+      : await new Promise((resolve, reject) => canvas.toBlob(value => value ? resolve(value) : reject(new Error('PNG encoding failed.')), 'image/png'));
+    return new Uint8Array(await png.arrayBuffer());
+  } finally {
+    picture?.close?.();
+    if (objectUrl) URL.revokeObjectURL(objectUrl);
+  }
+}

package/dist/image-fallback-node.js

@@ -0,0 +1,8 @@
+// Loaded only when a WebP needs a compatible static picture. Sharp receives
+// bytes, never URLs or paths, and does not fetch external resources.
+export async function webpToPng(bytes) {
+  const { default: sharp } = await import('sharp');
+  return new Uint8Array(await sharp(bytes, {limitInputPixels: 40_000_000, animated: false, failOn: 'warning'})
+    .autoOrient().toColourspace('srgb').ensureAlpha()
+    .png({compressionLevel: 9, adaptiveFiltering: false}).toBuffer());
+}

package/dist/image-geometry.js

@@ -0,0 +1,113 @@
+// Read dimensions only; never decode pixels or follow resource references.
+// PNG: https://www.w3.org/TR/PNG-Chunks.html
+// WebP: https://developers.google.com/speed/webp/docs/riff_container
+export function rasterDimensions(bytes) {
+  const info = rasterMetadata(bytes);
+  return info ? { width: info.width, height: info.height } : null;
+}
+
+export function rasterMetadata(bytes) {
+  if (!(bytes instanceof Uint8Array)) return null;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const text = (at, n) => String.fromCharCode(...bytes.subarray(at, at + n));
+  const size = (width, height, mediaType) => Number.isInteger(width) && Number.isInteger(height) && width > 0 && height > 0 ? { width, height, mediaType } : null;
+  if (bytes.length >= 33 && text(0, 8) === '\x89PNG\r\n\x1a\n' && view.getUint32(8) === 13 && text(12, 4) === 'IHDR') {
+    return size(view.getUint32(16), view.getUint32(20), "image/png");
+  }
+  if (bytes.length >= 13 && ['GIF87a', 'GIF89a'].includes(text(0, 6))) {
+    return size(view.getUint16(6, true), view.getUint16(8, true), "image/gif");
+  }
+  if (bytes.length >= 12 && text(0, 4) === 'RIFF' && text(8, 4) === 'WEBP') {
+    const end = view.getUint32(4, true) + 8;
+    if (end > bytes.length) return null;
+    for (let at = 12; at + 8 <= end;) {
+      const kind = text(at, 4), length = view.getUint32(at + 4, true), start = at + 8;
+      if (start + length > end) return null;
+      if (kind === 'VP8X' && length >= 10) {
+        const u24 = offset => bytes[offset] + bytes[offset + 1] * 256 + bytes[offset + 2] * 65536;
+        return size(u24(start + 4) + 1, u24(start + 7) + 1, "image/webp");
+      }
+      if (kind === 'VP8L' && length >= 5 && bytes[start] === 0x2f) {
+        const bits = view.getUint32(start + 1, true);
+        return size((bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1, "image/webp");
+      }
+      if (kind === 'VP8 ' && length >= 10 && text(start + 3, 3) === '\x9d\x01\x2a') {
+        return size(view.getUint16(start + 6, true) & 0x3fff, view.getUint16(start + 8, true) & 0x3fff, "image/webp");
+      }
+      at = start + length + (length & 1);
+    }
+    return null;
+  }
+  if (bytes.length >= 4 && bytes[0] === 0xff && bytes[1] === 0xd8) {
+    let dimensions = null, orientation = null;
+    // JPEG segment lengths include their two length bytes. Every iteration
+    // advances within the input, including fill bytes and standalone markers.
+    for (let at = 2; at < bytes.length;) {
+      if (bytes[at++] !== 0xff) return null;
+      while (at < bytes.length && bytes[at] === 0xff) at++;
+      if (at >= bytes.length) return null;
+      const marker = bytes[at++];
+      if (marker === 0xda || marker === 0xd9) return dimensions ? { ...dimensions, ...orientation } : null;
+      if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) continue;
+      if (at + 2 > bytes.length) return null;
+      const length = view.getUint16(at);
+      if (length < 2 || at + length > bytes.length) return null;
+      if ([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf].includes(marker)) {
+        dimensions = length >= 8 ? size(view.getUint16(at + 5), view.getUint16(at + 3), "image/jpeg") : null;
+      }
+      if (marker === 0xe1 && text(at + 2, 6) === 'Exif\x00\x00') orientation ??= exifOrientation(bytes, at + 8, at + length);
+      at += length;
+    }
+    return dimensions ? { ...dimensions, ...orientation } : null;
+  }
+  return null;
+}
+
+// Read only IFD0's inline SHORT orientation. All offsets and entry counts
+// stay within the APP1 segment; no linked IFDs or external values are followed.
+function exifOrientation(bytes, start, end) {
+  if (start + 8 > end) return null;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const littleEndian = bytes[start] === 0x49 && bytes[start + 1] === 0x49;
+  if (!littleEndian && !(bytes[start] === 0x4d && bytes[start + 1] === 0x4d)) return null;
+  if (view.getUint16(start + 2, littleEndian) !== 42) return null;
+  const directory = start + view.getUint32(start + 4, littleEndian);
+  if (directory < start + 8 || directory + 2 > end) return null;
+  const count = view.getUint16(directory, littleEndian);
+  if (directory + 2 + count * 12 > end) return null;
+  for (let i = 0; i < count; i++) {
+    const at = directory + 2 + i * 12;
+    if (view.getUint16(at, littleEndian) !== 0x112 || view.getUint16(at + 2, littleEndian) !== 3 || view.getUint32(at + 4, littleEndian) !== 1) continue;
+    const orientation = view.getUint16(at + 8, littleEndian);
+    if (orientation >= 1 && orientation <= 8) return { orientation, orientationOffset: at + 8, littleEndian };
+  }
+  return null;
+}
+
+export function fitImageBox(image, box, mode) {
+  const scale = (mode === 'crop' ? Math.max : Math.min)(box.w / image.width, box.h / image.height);
+  const width = image.width * scale, height = image.height * scale;
+  if (mode !== 'crop') return { x: box.x + (box.w - width) / 2, y: box.y + (box.h - height) / 2, w: width, h: height, crop: null };
+  const horizontal = Math.max(0, Math.round((1 - box.w / width) * 50000));
+  const vertical = Math.max(0, Math.round((1 - box.h / height) * 50000));
+  return { ...box, crop: { l: horizontal, r: horizontal, t: vertical, b: vertical } };
+}
+
+export function pictureTransform(metadata, box, mode) {
+  const orientation = metadata.orientation ?? 1;
+  const swapsAxes = orientation >= 5;
+  const target = swapsAxes
+    ? { x: box.x + (box.w - box.h) / 2, y: box.y + (box.h - box.w) / 2, w: box.h, h: box.w }
+    : box;
+  const fitted = fitImageBox(metadata, target, mode);
+  // DrawingML flips the source axes before applying clockwise rotation.
+  const rotation = [0, 0, 0, 180, 0, 90, 90, 90, 270][orientation];
+  return { ...fitted, rotation, flipH: orientation === 2 || orientation === 7, flipV: orientation === 4 || orientation === 5 };
+}
+
+export function normalizeImageOrientation(bytes, metadata) {
+  if (!metadata?.orientationOffset || metadata.orientation === 1) return bytes;
+  const output = new Uint8Array(bytes);
+  new DataView(output.buffer, output.byteOffset, output.byteLength).setUint16(metadata.orientationOffset, 1, metadata.littleEndian);
+  return output;
+}

package/dist/image-import.js

@@ -0,0 +1,92 @@
+import {rasterMetadata} from './image-geometry.js';
+
+// Centered, normalized source coordinates: [a,b,c,d] maps (x,y) to
+// (a*x+b*y,c*x+d*y). These are the eight JPEG EXIF orientation transforms.
+const orientations = [null, [1,0,0,1], [-1,0,0,1], [-1,0,0,-1], [1,0,0,-1],
+  [0,1,1,0], [0,-1,1,0], [0,-1,-1,0], [0,1,-1,0]];
+const multiply = ([a,b,c,d], [e,f,g,h]) => [a*e+b*g,a*f+b*h,c*e+d*g,c*f+d*h];
+const truth = value => value === '1' || value === 'true';
+
+export function importImageOrientation(bytes, transform, report = () => {}) {
+  const rotation = Number(transform?.rot ?? 0) / 60000;
+  const flipH = truth(transform?.flipH), flipV = truth(transform?.flipV);
+  if (Number.isFinite(rotation) && rotation % 360 === 0 && !flipH && !flipV) return bytes;
+  const unsupported = message => {report({code:'unsupported-image-orientation', message});return bytes;};
+  if (!Number.isFinite(rotation) || rotation % 90 !== 0) {
+    return unsupported('The native picture rotation/mirroring cannot be represented by JPEG EXIF metadata; its original image bytes were retained.');
+  }
+  const quarter = ((rotation / 90) % 4 + 4) % 4;
+  const rotations = [orientations[1],orientations[6],orientations[3],orientations[8]];
+  const native = multiply(rotations[quarter], [flipH ? -1 : 1,0,0,flipV ? -1 : 1]);
+  if (native.every((value,i) => value === orientations[1][i])) return bytes;
+  const metadata = rasterMetadata(bytes);
+  if (!metadata || metadata.mediaType !== 'image/jpeg') {
+    return unsupported('Native rotation/mirroring of this image format is not preserved by OPF import; its original image bytes were retained.');
+  }
+  const combined = multiply(native, orientations[metadata.orientation ?? 1]);
+  const orientation = orientations.findIndex(matrix => matrix && matrix.every((n,i) => n === combined[i]));
+  try { return withJpegOrientation(bytes, metadata, orientation); }
+  catch { return unsupported('The JPEG EXIF segment cannot safely accommodate the native picture orientation; its original image bytes were retained.'); }
+}
+
+function withJpegOrientation(bytes, metadata, orientation) {
+  if (orientation === (metadata.orientation ?? 1)) return bytes;
+  if (metadata.orientationOffset !== undefined) {
+    const output = new Uint8Array(bytes);
+    new DataView(output.buffer, output.byteOffset, output.byteLength).setUint16(metadata.orientationOffset, orientation, metadata.littleEndian);
+    return output;
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  // An existing EXIF block without orientation keeps all relative data/IFD
+  // offsets. Append a replacement IFD0, preserving its entries and next-IFD
+  // link, then point its TIFF header to the new directory.
+  for (let at = 2; at + 4 <= bytes.length;) {
+    if (bytes[at++] !== 0xff) throw new Error('Invalid JPEG marker');
+    while (bytes[at] === 0xff) at++;
+    const marker = bytes[at++];
+    if (marker === 0xda || marker === 0xd9) break;
+    if (marker === 1 || (marker >= 0xd0 && marker <= 0xd7)) continue;
+    const length = view.getUint16(at), end = at + length;
+    if (length < 2 || end > bytes.length) throw new Error('Invalid JPEG segment');
+    if (marker === 0xe1 && length >= 16 && String.fromCharCode(...bytes.subarray(at+2,at+8)) === 'Exif\0\0') {
+      const start = at + 8, little = bytes[start] === 0x49 && bytes[start+1] === 0x49;
+      if ((!little && !(bytes[start] === 0x4d && bytes[start+1] === 0x4d)) || view.getUint16(start+2,little) !== 42) throw new Error('Invalid TIFF');
+      const directory = start + view.getUint32(start+4,little);
+      if (directory < start+8 || directory+2 > end) throw new Error('Invalid IFD');
+      const count = view.getUint16(directory,little), tail = directory + 2 + count*12;
+      if (tail+4 > end || count === 65535) throw new Error('Invalid IFD entries');
+      // A malformed orientation entry cannot be duplicated into a valid one.
+      for (let i=0;i<count;i++) if (view.getUint16(directory+2+i*12,little) === 0x112) throw new Error('Malformed orientation entry');
+      const padding = (end-start) % 2, extra = padding + 2 + (count+1)*12 + 4;
+      if (length+extra > 65535) throw new Error('EXIF segment too large');
+      const output = new Uint8Array(bytes.length+extra);
+      output.set(bytes.subarray(0,end));output.set(bytes.subarray(end),end+extra);
+      const out = new DataView(output.buffer), replacement = end+padding;
+      out.setUint16(at,length+extra);out.setUint32(start+4,replacement-start,little);
+      out.setUint16(replacement,count+1,little);
+      let target=replacement+2, inserted=false;
+      for (let i=0;i<count;i++) {
+        const source=directory+2+i*12;
+        if (!inserted && view.getUint16(source,little)>0x112) {writeEntry(out,target,orientation,little);target+=12;inserted=true;}
+        output.set(bytes.subarray(source,source+12),target);target+=12;
+      }
+      if (!inserted) {writeEntry(out,target,orientation,little);target+=12;}
+      output.set(bytes.subarray(tail,tail+4),target);
+      return output;
+    }
+    at=end;
+  }
+  // Plain JPEG: insert a minimal independent APP1/IFD0 after SOI. Every
+  // original byte after SOI is retained, including compressed scan data.
+  const segment = new Uint8Array(36), out = new DataView(segment.buffer);
+  segment.set([0xff,0xe1,0,34,0x45,0x78,0x69,0x66,0,0,0x4d,0x4d,0,42,0,0,0,8,0,1]);
+  writeEntry(out,20,orientation,false);
+  const output = new Uint8Array(bytes.length+segment.length);
+  output.set(bytes.subarray(0,2));output.set(segment,2);output.set(bytes.subarray(2),2+segment.length);
+  return output;
+}
+
+function writeEntry(view, at, orientation, little) {
+  view.setUint16(at,0x112,little);view.setUint16(at+2,3,little);
+  view.setUint32(at+4,1,little);view.setUint16(at+8,orientation,little);
+}

package/dist/index.d.ts

@@ -34,6 +34,8 @@ export interface ImageResolverContext {
 }
 
 export interface ToPptxOptions {
+  /** Default compatible converts WebP to a static PNG. Preserve embeds original WebP bytes. */
+  imageFormat?: "compatible" | "preserve";
   textMeasurement?: TextMeasurement;
   onDiagnostic?: (diagnostic: LayoutDiagnostic) => void;
   baseDir?: string;
@@ -46,6 +48,8 @@ export interface ToPptxOptions {
 }
 
 export interface FromPptxOptions {
+  /** Reports native gradient or picture crop/transform details that OPF import cannot preserve. Picture paths identify the native picture index. */
+  onDiagnostic?: (diagnostic: {code: string; path: string; message: string}) => void;
   fallbackName?: string;
   schema?: string;
 }

package/dist/index.js

@@ -1,4 +1,9 @@
-import { composeSlide, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle } from "@openpresentation/opf/composition";
+import {importImageOrientation} from './image-import.js';
+import {nativeBackgroundFill} from './background.js';
+import {importBackground} from './background-import.js';
+import { webpToPng } from '#image-fallback';
+import { rasterMetadata, pictureTransform, normalizeImageOrientation } from './image-geometry.js';
+import { composeSlide, fitText, textWidthMeasurer, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle } from "@openpresentation/opf/composition";
 import PptxGenJS from "pptxgenjs";
 import { unzipSync, zipSync } from "fflate";
 import { XMLParser } from "fast-xml-parser";
@@ -152,11 +157,18 @@ const CHART_COLORS = [
 ];
 
 export async function toPptx(input, options = {}) {
+  if (options.imageFormat !== undefined && !['compatible', 'preserve'].includes(options.imageFormat)) {
+    throw new OPFPptxError('invalid-image-format', 'imageFormat must be compatible or preserve.', {path: 'options.imageFormat'});
+  }
   const presentation = parseInput(input);
   assertValidBoundary(presentation);
 
   const context = resolvePresentationContext(presentation, {...options,textMeasurement:undefined});
   context.listMarkers = new Map();
+  context.tableHeaders = new Map();
+  context.imagePlacements = new Map();
+  context.backgroundFills = new Map();
+  context.imageFormat = options.imageFormat ?? "compatible";
   const pptx = new PptxGenJS();
   configurePresentation(pptx, presentation, {...context,fonts:resolveSlideContext(presentation,presentation.slides[0],context,options).fonts});
 
@@ -206,7 +218,7 @@ export async function fromPptx(input, options = {}) {
   if (dimensions) imported.design = { dimensions };
 
   for (let index = 0; index < slidePaths.length; index += 1) {
-    imported.slides.push(importSlide(entries, slidePaths[index], index, dimensions));
+    imported.slides.push(importSlide(entries, slidePaths[index], index, dimensions, options));
   }
 
   const result = validatePresentation(imported);
@@ -239,13 +251,13 @@ function readPptxZip(input) {
   }
 }
 
-function parseRequiredXml(entries, path) {
+function parseRequiredXml(entries, path, parser = xmlParser) {
   const bytes = entries[path];
   if (!bytes) {
     throw new OPFPptxError("invalid-pptx", `PPTX is missing ${path}.`, { path });
   }
   try {
-    return xmlParser.parse(decodeText(bytes));
+    return parser.parse(decodeText(bytes));
   } catch (error) {
     throw new OPFPptxError("invalid-pptx", `PPTX XML part could not be parsed: ${path}.`, {
       path,
@@ -346,7 +358,7 @@ function dimensionsFromPresentation(presentationRoot) {
   };
 }
 
-function importSlide(entries, slidePath, slideIndex, presentationDimensions) {
+function importSlide(entries, slidePath, slideIndex, presentationDimensions, options) {
   const doc = parseRequiredXml(entries, slidePath);
   const slideRoot = doc["p:sld"];
   if (!slideRoot) {
@@ -360,17 +372,12 @@ function importSlide(entries, slidePath, slideIndex, presentationDimensions) {
   const slide = {};
   if (slideRoot.show === "0") slide.hidden = true;
 
-  const background = slideBackground(slideRoot);
-  if (background) {
-    slide.design = {
-      background: {
-        type: "solid",
-        color: background
-      }
-    };
-  }
+  const background = importBackground(slidePath, resolveCanvasDimensions(dimensions), {
+    part: (path, parser) => parseRequiredXml(entries, path, parser), relationships: path => parseRelationships(entries, path), bytes: path => entries[path]
+  }, diagnostic => options.onDiagnostic?.({...diagnostic, path: `slides.${slideIndex}.design.background`}));
+  if (background) slide.design = {background};
 
-  const items = collectSlideItems(entries, slideRoot, slidePath, relationships, dimensions)
+  const items = collectSlideItems(entries, slideRoot, slidePath, relationships, dimensions, options, slideIndex)
     .sort(comparePositionedItems);
   const titleItem = takeTitleItem(items, dimensions);
   if (titleItem) slide.title = firstLine(titleItem.text);
@@ -385,14 +392,10 @@ function importSlide(entries, slidePath, slideIndex, presentationDimensions) {
   const notes = readSlideNotes(entries, relationships);
   if (notes) slide.notes = notes;
 
-  if (!slide.title && !slide.blocks && !slide.notes) {
-    slide.title = `Slide ${slideIndex + 1}`;
-  }
-
   return slide;
 }
 
-function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensions) {
+function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensions, options, slideIndex) {
   const tree = slideRoot["p:cSld"]?.["p:spTree"];
   const items = [];
 
@@ -406,8 +409,9 @@ function collectSlideItems(entries, slideRoot, slidePath, relationships, dimensi
     if (item) items.push(item);
   }
 
-  for (const picture of asArray(tree?.["p:pic"])) {
-    const item = importPicture(entries, picture, slidePath, relationships);
+  for (const [index, picture] of asArray(tree?.["p:pic"]).entries()) {
+    const report = diagnostic => options.onDiagnostic?.({...diagnostic, path: `slides.${slideIndex}.pictures.${index}`});
+    const item = importPicture(entries, picture, slidePath, relationships, report);
     if (item) items.push(item);
   }
 
@@ -480,13 +484,13 @@ function importGraphicFrame(entries, frame, slidePath, relationships) {
   };
 }
 
-function importPicture(entries, picture, slidePath, relationships) {
+function importPicture(entries, picture, slidePath, relationships, report) {
   const bounds = shapeBounds(picture["p:spPr"]?.["a:xfrm"]);
   const name = scalarText(picture["p:nvPicPr"]?.["p:cNvPr"]?.name).trim();
   const alt = scalarText(picture["p:nvPicPr"]?.["p:cNvPr"]?.descr).trim();
   const relId = picture["p:blipFill"]?.["a:blip"]?.["r:embed"];
   const relationship = relationships.get(relId);
-  const bytes = relationship?.path ? entries[relationship.path] : null;
+  let bytes = relationship?.path ? entries[relationship.path] : null;
   if (!bytes) {
     return {
       kind: "unknown",
@@ -496,6 +500,12 @@ function importPicture(entries, picture, slidePath, relationships) {
     };
   }
 
+  const crop = picture["p:blipFill"]?.["a:srcRect"];
+  if (crop && ['l','r','t','b'].some(key => Number(crop[key] ?? 0) !== 0)) {
+    report({code: 'unsupported-image-crop', message: 'Native picture crop is not represented by the imported OPF asset; the full image was retained.'});
+  }
+  bytes = importImageOrientation(bytes, picture["p:spPr"]?.["a:xfrm"], report);
+
   return {
     kind: "image",
     bounds,
@@ -503,7 +513,7 @@ function importPicture(entries, picture, slidePath, relationships) {
     payload: {
       type: "image",
       image: {
-        src: `data:${mediaTypeForPath(relationship.path)};base64,${bytesToBase64(bytes)}`,
+        src: `data:${rasterMetadata(bytes)?.mediaType ?? mediaTypeForPath(relationship.path)};base64,${bytesToBase64(bytes)}`,
         ...(alt ? { alt } : {})
       }
     }
@@ -624,13 +634,14 @@ function payloadFromSlideItem(item) {
 
 function tableFromXml(table) {
   const rows = asArray(table["a:tr"])
-    .map((row) => asArray(row?.["a:tc"]).map((cell) => textFromTextBody(cell?.["a:txBody"])))
-    .filter((row) => row.some(Boolean));
-  if (rows.length === 0) return { rows: [] };
-  return {
-    columns: rows[0],
-    rows: rows.slice(1)
-  };
+    .map((row) => asArray(row?.["a:tc"]).map((cell) => textFromTextBody(cell?.["a:txBody"])));
+  // DrawingML's firstRow flag applies header-row formatting. Without that
+  // signal, retain all rows as data instead of guessing from their contents.
+  const firstRow = table["a:tblPr"]?.firstRow;
+  const hasHeaders = firstRow === "1" || firstRow === "true";
+  return hasHeaders && rows.length
+    ? { columns: rows[0], rows: rows.slice(1) }
+    : { rows };
 }
 
 function chartFromRelationship(entries, slidePath, relationships, relId) {
@@ -715,10 +726,6 @@ function readSlideNotes(entries, relationships) {
   return bodyNotes.join("\n").trim();
 }
 
-function slideBackground(slideRoot) {
-  const color = slideRoot["p:cSld"]?.["p:bg"]?.["p:bgPr"]?.["a:solidFill"]?.["a:srgbClr"]?.val;
-  return color ? `#${normalizeHex(color)}` : "";
-}
 
 function textFromTextBody(txBody) {
   return readParagraphs(txBody).map((paragraph) => paragraph.text).filter(Boolean).join("\n").trim();
@@ -755,7 +762,9 @@ function isFullSlide(bounds, dimensions) {
 function emuToInches(value) {
   const number = Number(value);
   if (!Number.isFinite(number)) return null;
-  return Math.round((number / EMUS_PER_INCH) * 1_000_000) / 1_000_000;
+  // Keep native precision through layout/rendering. Rounding inches to six
+  // decimals turns a 1280-pixel canvas into 1279.999968 and changes raster edges.
+  return number / EMUS_PER_INCH;
 }
 
 function asArray(value) {
@@ -805,7 +814,7 @@ function assertValidBoundary(presentation) {
 
 function resolvePresentationContext(presentation, options) {
   const design = presentation.design ?? {};
-  const theme = resolveCatalogRecord(presentation, "themes", design.theme, DEFAULTS.theme);
+  const theme = resolveDesignRecord(presentation, "themes", design.theme, DEFAULTS.theme);
   const colorScheme = resolveDesignRecord(
     presentation,
     "colorSchemes",
@@ -833,6 +842,7 @@ function resolvePresentationContext(presentation, options) {
     layoutName: "OPF_CANVAS",
     dimensions,
     colorScheme,
+    backgroundDefinition: design.background ?? theme?.background,
     fonts,
     colors: {
       background,
@@ -840,7 +850,7 @@ function resolvePresentationContext(presentation, options) {
       mutedText: normalizeHex(colorScheme.textSecondary ?? (darkBackground ? colorScheme.light2 : colorScheme.dark2) ?? "#475569"),
       accent: normalizeHex(colorScheme.primary ?? colorScheme.accent1 ?? "#2874A6"),
       surface: normalizeHex(colorScheme.surface ?? (darkBackground ? colorScheme.dark2 : colorScheme.light2) ?? "#F8FAFC"),
-      border: normalizeHex(colorScheme.accent3 ?? "#CBD5E1")
+      border: normalizeHex(colorScheme.accent5 ?? "#CBD5E1")
     }
   };
 }
@@ -867,6 +877,10 @@ async function addSlide(pptx, presentation, opfSlide, slideIndex, context, optio
   const slide = pptx.addSlide();
   const slideContext = resolveSlideContext(presentation, opfSlide, context, options);
   slide.background = { color: slideContext.colors.background };
+  const backgroundFill = nativeBackgroundFill(slideContext.backgroundDefinition, {
+    width: slideContext.dimensions.widthInches, height: slideContext.dimensions.heightInches
+  }, slideContext.colors.background);
+  if (backgroundFill) context.backgroundFills.set(`ppt/slides/slide${slideIndex + 1}.xml`, backgroundFill);
   slide.color = slideContext.colors.text;
   if (opfSlide.hidden === true) slide.hidden = true;
 
@@ -897,7 +911,7 @@ async function addSlide(pptx, presentation, opfSlide, slideIndex, context, optio
     } else if (item.field === "text" && typeof item.value === "string") {
       slide.addText(item.text.lines.join("\n"), {...textBoxOptions(region, slideContext, item.text.fontSize * 0.75),fontFace:item.textStyle.fontFamily,bold:item.textStyle.fontWeight>=600,italic:item.textStyle.italic});
     } else {
-      await addPayload(slide, presentation, item.payload, region, item.path, slideContext, options);
+      await addPayload(slide, presentation, item.payload, region, item.path, { ...slideContext, composition: item.composition, contentAlignment: opfSlide.design?.contentAlignment ?? presentation.design?.contentAlignment ?? "left" }, options);
     }
   }
 
@@ -911,7 +925,7 @@ function resolveSlideContext(presentation, slide, baseContext, options) {
     || Math.abs(resolved.dimensions.heightInches - baseContext.dimensions.heightInches) > 1e-6) {
     throw new OPFPptxError("mixed-slide-dimensions", "PowerPoint requires one canvas size per presentation. Set dimensions on the deck or export this slide separately.");
   }
-  return { ...baseContext, colorScheme: resolved.colorScheme, fonts: resolved.fonts, colors: resolved.colors };
+  return { ...baseContext, backgroundDefinition: resolved.backgroundDefinition, colorScheme: resolved.colorScheme, fonts: resolved.fonts, colors: resolved.colors, imageFill: effective.design.imageFill ?? "fit" };
 }
 
 function fieldToType(field) {
@@ -937,7 +951,7 @@ async function addPayload(slide, presentation, payload, region, path, context, o
       addChartPayload(slide, payload.chart, region, context);
       break;
     case "table":
-      addTablePayload(slide, payload.table, region, context);
+      addTablePayload(slide, payload.table, region, context, options, path);
       break;
     case "code":
       addCodePayload(slide, payload.code, region, context);
@@ -1048,8 +1062,11 @@ async function addImagePayload(slide, presentation, asset, region, path, context
     addPlaceholderPayload(slide, "Image", asset, region, context);
     return;
   }
+  const objectName = `OPF image ${context.imagePlacements.size + 1}`;
+  context.imagePlacements.set(objectName, { region, mode: context.imageFill, path });
   slide.addImage({
     ...resolved,
+    objectName,
     x: region.x,
     y: region.y,
     w: region.w,
@@ -1084,36 +1101,49 @@ function addChartPayload(slide, chart, region, context) {
   });
 }
 
-function addTablePayload(slide, table, region, context) {
+function addTablePayload(slide, table, region, context, options, path) {
   const scale = Math.min(context.dimensions.widthInches * 96, context.dimensions.heightInches * 96) / 720;
-  const rows = [];
-  if (Array.isArray(table?.columns) && table.columns.length > 0) {
-    rows.push(table.columns.map((value) => ({
-      text: stringifyText(value),
-      options: {
-        bold: true,
-        color: "FFFFFF",
-        fill: { color: context.colors.accent }
-      }
-    })));
-  }
-  if (Array.isArray(table?.rows)) {
-    for (const row of table.rows) {
-      rows.push((Array.isArray(row) ? row : [row]).map((value) => ({
-        text: stringifyText(value),
-        options: { color: context.colors.text, fill: {color:context.colors.surface} }
-      })));
-    }
-  }
-
-  if (rows.length === 0) {
+  const hasHeaders = Array.isArray(table?.columns) && table.columns.length > 0;
+  const sourceRows = [...(hasHeaders ? [table.columns] : []), ...(table?.rows ?? [])];
+  if (sourceRows.length === 0) {
     addPlaceholderPayload(slide, "Table", table, region, context);
     return;
   }
 
-  const columnCount = Math.max(1, ...rows.map(row => row.length));
-  const rowHeight = Math.min(54 * scale / 96, region.h / rows.length);
+  const columnCount = Math.max(1, ...sourceRows.map(row => row.length));
+  const rowHeight = Math.min(54 * scale / 96, region.h / sourceRows.length);
+  const cellBox = {
+    x: 0, y: 0,
+    width: Math.max(scale, region.w * 96 / columnCount - 20 * scale),
+    height: Math.max(scale, rowHeight * 96 - 12 * scale),
+  };
+  const rows = sourceRows.map((row, rowIndex) => Array.from({ length: columnCount }, (_, columnIndex) => {
+    const header = hasHeaders && rowIndex === 0;
+    const cellPath = header ? `${path}.columns.${columnIndex}` : `${path}.rows.${rowIndex - Number(hasHeaders)}.${columnIndex}`;
+    const text = stringifyText(row[columnIndex]);
+    const style = resolveTextStyle({ fontFamily: context.fonts.body, fontWeight: header ? 700 : 400, italic: false, path: cellPath }, options.textMeasurement);
+    const fit = fitText(text, cellBox, 15 * scale, (context.composition?.minFontSize ?? 16) * scale, textWidthMeasurer(style, options.textMeasurement));
+    return {
+      // Keep native wrapping and the original cell value: inserting measured
+      // soft wraps into the text would change a later import or copy operation.
+      text,
+      options: {
+        fontFace: style.fontFamily,
+        fontSize: fit.fontSize * 0.75,
+        bold: style.fontWeight >= 600,
+        italic: style.italic,
+        lineSpacing: fit.lineHeight * 0.75,
+        paraSpaceAfter: 0,
+        align: context.contentAlignment,
+        color: header ? "FFFFFF" : context.colors.text,
+        fill: { color: header ? context.colors.accent : context.colors.surface },
+      },
+    };
+  }));
+  const objectName = `OPF table ${context.tableHeaders.size + 1}`;
+  context.tableHeaders.set(objectName, hasHeaders);
   slide.addTable(rows, {
+    objectName,
     x: region.x,
     y: region.y,
     w: region.w,
@@ -1477,7 +1507,7 @@ function isDarkHex(value) {
   return (red * 299 + green * 587 + blue * 114) / 1000 < 128;
 }
 
-function normalizePptxZip(raw, context) {
+async function normalizePptxZip(raw, context) {
   let entries;
   try {
     entries = unzipSync(raw);
@@ -1487,18 +1517,59 @@ function normalizePptxZip(raw, context) {
     });
   }
 
+  const imageSources = new Map();
+  for (const [part, bytes] of Object.entries(entries)) {
+    if (!/^ppt\/slides\/slide\d+\.xml$/.test(part)) continue;
+    const relationships = parseRelationships(entries, part);
+    for (const [picture] of decodeText(bytes).matchAll(/<p:pic>[\s\S]*?<\/p:pic>/g)) {
+      const placement = context.imagePlacements.get(picture.match(/name="(OPF image \d+)"/)?.[1]);
+      const id = picture.match(/<a:blip\b[^>]*r:embed="([^"]+)"/)?.[1];
+      if (placement) imageSources.set(relationships.get(id)?.path, placement.path);
+    }
+  }
+  const imageMetadata = new Map();
+  for (const [part, bytes] of Object.entries(entries)) {
+    if (!part.startsWith('ppt/media/')) continue;
+    let metadata = rasterMetadata(bytes);
+    if (metadata?.mediaType === 'image/webp' && context.imageFormat === 'compatible') {
+      try {
+        if (metadata.width * metadata.height > 40_000_000) throw new Error('Image dimensions exceed the 40 megapixel conversion limit.');
+        const png = await webpToPng(bytes);
+        metadata = rasterMetadata(png);
+        if (metadata?.mediaType !== 'image/png') throw new Error('The local decoder did not return a PNG.');
+        entries[part] = png;
+      } catch (error) {
+        throw new OPFPptxError('image-conversion-failed', 'WebP could not be converted to a compatible PNG.', {path: imageSources.get(part) ?? part, cause: errorMessage(error)});
+      }
+    }
+    imageMetadata.set(part, metadata);
+  }
   const output = {};
   const renameMaps = buildRenameMaps(Object.keys(entries));
+  // The host may transform assets or supply a filename/MIME hint that no
+  // longer matches its bytes. Native package metadata must describe the bytes.
+  renameMaps.media = new Map();
+  for (const [path, metadata] of imageMetadata) {
+    if (!metadata) continue;
+    const extension = metadata.mediaType.slice('image/'.length);
+    const currentExtension = path.split('.').at(-1).toLowerCase();
+    if (currentExtension === extension || (extension === 'jpeg' && currentExtension === 'jpg')) continue;
+    const target = path.replace(/\.[^/.]+$/, `.${extension}`);
+    if (target !== path && Object.hasOwn(entries, target)) throw new OPFPptxError('packaging-failed', 'Normalized image paths collide.', {path, target});
+    renameMaps.media.set(path, target);
+  }
   for (const path of Object.keys(entries).sort()) {
     const normalizedPath = normalizePartPath(path, renameMaps);
-    const bytes = normalizePartBytes(path, entries[path], context, renameMaps);
+    const bytes = normalizePartBytes(path, entries[path], context, renameMaps, entries, imageMetadata);
     output[normalizedPath] = [bytes, {
       level: context.compressionLevel,
       mtime: context.zipDate
     }];
   }
 
-  return zipSync(output, {
+  // Sort after chart/worksheet renaming; source counters can cross digit widths.
+  const sortedOutput = Object.fromEntries(Object.keys(output).sort().map(path => [path, output[path]]));
+  return zipSync(sortedOutput, {
     level: context.compressionLevel,
     mtime: context.zipDate
   });
@@ -1510,7 +1581,8 @@ function normalizeCoreProperties(xml, timestamp) {
     .replace(/<dcterms:modified xsi:type="dcterms:W3CDTF">[^<]*<\/dcterms:modified>/g, `<dcterms:modified xsi:type="dcterms:W3CDTF">${timestamp}</dcterms:modified>`);
 }
 
-function normalizePartBytes(path, bytes, context, renameMaps) {
+function normalizePartBytes(path, bytes, context, renameMaps, entries, imageMetadata) {
+  if (imageMetadata.has(path)) return normalizeImageOrientation(bytes, imageMetadata.get(path));
   if (path.endsWith(".xlsx")) {
     return normalizeNestedZip(bytes, context);
   }
@@ -1519,7 +1591,53 @@ function normalizePartBytes(path, bytes, context, renameMaps) {
   }
   if (isXmlPart(path)) {
     let xml=decodeText(bytes);
+    if (path === '[Content_Types].xml') {
+      // Explicit per-part types also correct PptxGenJS's image/jpg default.
+      const overrides = [...imageMetadata].filter(([, metadata]) => metadata).map(([part, metadata]) =>
+        `<Override PartName="/${part}" ContentType="${metadata.mediaType}"/>`).join('');
+      xml = xml.replace('</Types>', `${overrides}</Types>`);
+    }
     if (/^ppt\/slides\/slide\d+\.xml$/.test(path)) {
+      const fill = context.backgroundFills.get(path);
+      if (fill) xml = xml.replace(/<p:bg>[\s\S]*?<\/p:bg>/, `<p:bg><p:bgPr>${fill}<a:effectLst/></p:bgPr></p:bg>`);
+      // PptxGenJS table IDs can collide with other objects on the same slide.
+      // Preserve existing IDs and allocate unused IDs only for duplicates. This
+      // export path creates no connector attachments or animation ID references.
+      const objectIds = [...xml.matchAll(/<p:cNvPr\b[^>]*\bid="(\d+)"/g)].map(match => Number(match[1]));
+      let nextObjectId = Math.max(0, ...objectIds) + 1;
+      const seenObjectIds = new Set();
+      xml = xml.replace(/(<p:cNvPr\b[^>]*\bid=")(\d+)(")/g, (node, before, rawId, after) => {
+        const id = Number(rawId);
+        if (seenObjectIds.has(id)) return `${before}${nextObjectId++}${after}`;
+        seenObjectIds.add(id);
+        return node;
+      });
+      // PptxGenJS 4 has no firstRow option. Set the native flag explicitly so
+      // viewers and later imports distinguish column labels from data rows.
+      xml = xml.replace(/<p:graphicFrame>([\s\S]*?)<\/p:graphicFrame>/g, frame => {
+        const name = frame.match(/name="(OPF table \d+)"/)?.[1];
+        if (!context.tableHeaders.has(name)) return frame;
+        return frame.replace('<a:tblPr/>', `<a:tblPr firstRow="${context.tableHeaders.get(name) ? 1 : 0}"/>`);
+      });
+      // Image data is already resolved and embedded by PptxGenJS. Read those
+      // exact bytes instead of fetching or resolving the source a second time.
+      const relationships = parseRelationships(entries, path);
+      xml = xml.replace(/<p:pic>([\s\S]*?)<\/p:pic>/g, picture => {
+        const placement = context.imagePlacements.get(picture.match(/name="(OPF image \d+)"/)?.[1]);
+        if (!placement) return picture;
+        const id = picture.match(/<a:blip\b[^>]*r:embed="([^"]+)"/)?.[1];
+        const dimensions = imageMetadata.get(relationships.get(id)?.path);
+        if (!dimensions) throw new OPFPptxError("unsupported-image-dimensions", "Image fitting requires readable PNG, JPEG, GIF or WebP dimensions. Supply a supported raster image through imageResolver.", { path: placement.path });
+        const fitted = pictureTransform(dimensions, placement.region, placement.mode);
+        const emu = value => Math.round(value * EMUS_PER_INCH);
+        const transformAttrs = `${fitted.rotation ? ` rot="${fitted.rotation * 60000}"` : ''}${fitted.flipH ? ' flipH="1"' : ''}${fitted.flipV ? ' flipV="1"' : ''}`;
+        picture = picture.replace(/<a:xfrm\b[^>]*>[\s\S]*?<\/a:xfrm>/, `<a:xfrm${transformAttrs}><a:off x="${emu(fitted.x)}" y="${emu(fitted.y)}"/><a:ext cx="${emu(fitted.w)}" cy="${emu(fitted.h)}"/></a:xfrm>`);
+        if (fitted.crop) {
+          const attrs = Object.entries(fitted.crop).map(([key, value]) => `${key}="${value}"`).join(' ');
+          picture = picture.replace('<a:stretch>', `<a:srcRect ${attrs}/><a:stretch>`);
+        }
+        return picture;
+      });
       // Native bullets otherwise inherit the first rich run's size, font and
       // color, which can differ from the measured list marker.
       xml=xml.replace(/<p:sp>([\s\S]*?)<\/p:sp>/g,(shape)=>{
@@ -1561,7 +1679,7 @@ function numberedFilenameMap(paths, pattern) {
 }
 
 function normalizePartPath(path, renameMaps) {
-  return normalizePartReferences(path, renameMaps);
+  return normalizePartReferences(renameMaps.media?.get(path) ?? path, renameMaps);
 }
 
 function normalizePartReferences(value, renameMaps) {
@@ -1575,6 +1693,14 @@ function normalizePartReferences(value, renameMaps) {
       `Microsoft_Excel_Worksheet${newId}.xlsx`
     );
   }
+  // Rewrite package references only, not user-visible text containing paths.
+  output = output.replace(/\b(Target|PartName)="([^"]+)"/g, (attribute, name, value) => {
+    const prefix = value.startsWith('../media/') ? '../' : value.startsWith('/ppt/media/') ? '/ppt/' : null;
+    if (!prefix) return attribute;
+    const part = 'ppt/' + value.slice(prefix.length);
+    const target = renameMaps.media?.get(part);
+    return target ? `${name}="${prefix}${target.slice('ppt/'.length)}"` : attribute;
+  });
   return output;
 }
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@openpresentation/opf-pptx",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Pure local OPF to PPTX export and PPTX to OPF import tooling.",
   "license": "MIT",
   "type": "module",
   "private": false,
   "engines": {
-    "node": ">=20"
+    "node": ">=20.9.0"
   },
   "repository": {
     "type": "git",
@@ -35,23 +35,35 @@
   "sideEffects": false,
   "scripts": {
     "build": "node scripts/build.mjs",
-    "typecheck": "node --check src/index.js && node --check scripts/build.mjs && node --check scripts/validate-package.mjs && node --check test/smoke.mjs",
-    "test": "npm run build && node test/dependency-boundary.mjs",
+    "typecheck": "node --check src/index.js && node --check scripts/build.mjs && node --check scripts/validate-package.mjs && node --check test/smoke.mjs && node --check src/image-geometry.js && node --check test/image-fit.mjs && node --check test/image-orientation.mjs && node --check test/table-layout.mjs && node --check test/table-import.mjs && node --check test/object-ids.mjs && node --check test/export-corpus.mjs && node --check test/image-media-type.mjs && node --check src/image-fallback-node.js && node --check src/image-fallback-browser.js && node --check test/webp-fallback.mjs && node --check scripts/build-browser-check.mjs && node --check test/webp-fallback-browser.js && node --check test/image-fallback-boundary.mjs && node --check src/background.js && node --check test/background.mjs && node --check src/image-import.js && node --check test/image-import.mjs && node --check test/native-background.mjs && node --check src/background-import.js && node --check test/background-inheritance.mjs",
+    "test": "npm run build && node test/dependency-boundary.mjs && npm run build:browser-check",
     "validate": "node scripts/validate-package.mjs",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "build:browser-check": "node scripts/build-browser-check.mjs"
   },
   "dependencies": {
-    "@openpresentation/opf": "^0.4.0",
+    "@openpresentation/opf": "^0.4.1",
     "fast-xml-parser": "^5.8.0",
     "fflate": "^0.8.3",
-    "pptxgenjs": "4.0.1"
+    "pptxgenjs": "4.0.1",
+    "sharp": "0.35.4"
   },
   "peerDependencies": {
-    "@openpresentation/opf-render": "^0.1.0"
+    "@openpresentation/opf-render": "^0.2.0"
   },
   "peerDependenciesMeta": {
     "@openpresentation/opf-render": {
       "optional": true
     }
+  },
+  "devDependencies": {
+    "@openpresentation/opf-render": "0.2.0",
+    "esbuild": "0.28.2"
+  },
+  "imports": {
+    "#image-fallback": {
+      "browser": "./dist/image-fallback-browser.js",
+      "default": "./dist/image-fallback-node.js"
+    }
   }
 }