@openpresentation/opf-pptx 0.0.1 → 0.2.0

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.
@@ -106,3 +108,73 @@ Required first-publish setup:
 3. Publish by creating a GitHub Release or manually running the Release workflow after CI passes.
 
 This repo does not require an npm automation token when Trusted Publishing is configured.
+
+## Shared dynamic composition (local development)
+
+The current checkout uses `@openpresentation/opf/composition` for portable geometry. Slides can select `auto`, `row`, `column`, or `grid`, set weighted tracks, and request path-specific overflow diagnostics. See the sibling OPF repo's `docs/dynamic-composition.md` for the complete contract.
+
+Version 0.1.0 requires published `@openpresentation/opf@^0.4.0`. The optional renderer peer requires `@openpresentation/opf-render@^0.1.0`. Clean registry installs support the new composition APIs without sibling checkouts. For coordinated source development, build OPF and run `node scripts/link-ecosystem.mjs` there; `pnpm test:ecosystem` verifies shared geometry and import/export behavior.
+
+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.
+
+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, transformed/theme stop colors, 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.
+
+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.js

@@ -0,0 +1,81 @@
+// 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') return `<a:solidFill>${colorXml(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>`;
+}
+
+function readColor(node) {
+  const c = node?.['a:srgbClr'];
+  if (!c || !/^[\da-f]{6}$/i.test(c.val) || Object.keys(c).some(k => k !== 'val' && k !== 'a:alpha')) return null;
+  const alpha = Number(c['a:alpha']?.val ?? 100000) / 100000;
+  if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1) return null;
+  return {hex: '#' + c.val.toUpperCase(), alpha};
+}
+
+export function readNativeBackground(properties, {width, height}, report = () => {}) {
+  if (!properties) return undefined;
+  if (Object.hasOwn(properties, 'a:noFill')) return {type: 'solid', color: '#FFFFFF', opacity: 0};
+  const solid = readColor(properties['a:solidFill']);
+  if (solid) return {type: 'solid', color: solid.hex, ...(solid.alpha === 1 ? {} : {opacity: solid.alpha})};
+  const gradient = properties['a:gradFill'];
+  if (!gradient) 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 = readColor(stop), 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

@@ -1,3 +1,4 @@
+import type { LayoutDiagnostic, TextMeasurement } from "@openpresentation/opf/composition";
 export declare const packageName = "@openpresentation/opf-pptx";
 
 export declare const releaseLane: Readonly<{
@@ -33,6 +34,10 @@ 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;
   compressionLevel?: number;
   imageResolver?: (src: string, context: ImageResolverContext) => ImageResolverResult | Promise<ImageResolverResult | null | undefined> | null | undefined;
@@ -43,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;
 }