@juspay/neurolink 12.28.1 → 12.28.2

package/CHANGELOG.md

@@ -1,8 +1,8 @@
-## [12.28.1](https://github.com/juspay/neurolink/compare/v12.28.0...v12.28.1) (2026-09-26)
+## [12.28.2](https://github.com/juspay/neurolink/compare/v12.28.1...v12.28.2) (2026-09-26)
 
 ### Bug Fixes
 
-- **(multimodal):** keep input.content text items on the text-only path ([a341481](https://github.com/juspay/neurolink/commit/a341481619c536ce97a2773ecb3f8155d0ff69aa)), closes [#289](https://github.com/juspay/neurolink/issues/289)
+- **(images):** honour EXIF orientation before sending an image to a provider ([8fc9088](https://github.com/juspay/neurolink/commit/8fc908837a5b85b1c2dcfc2e3d4c39577ec0abd0))
 
 ## [11.2.3](https://github.com/juspay/neurolink/compare/v11.2.2...v11.2.3) (2026-08-19)
 

package/dist/adapters/imageFormatSupport.d.ts

@@ -19,7 +19,7 @@
  *
  * @module adapters/imageFormatSupport
  */
-import type { ImageWithAltText, VisionImageConversion, VisionImageOutputFormat } from "../types/index.js";
+import type { ExifOrientationProbe, ImageOrientationNormalization, ImageWithAltText, VisionImageConversion, VisionTranscodeOptions } from "../types/index.js";
 /**
  * MIME types every vision-capable provider accepts as-is.
  *
@@ -45,6 +45,53 @@ export declare const SUPPORTED_INPUT_IMAGE_MIME_TYPES: ReadonlySet<string>;
  * reading a file off disk that would not have been converted anyway.
  */
 export declare function needsVisionTranscode(mimeType: string): boolean;
+/**
+ * True when a MIME type's format can carry an orientation tag at all. Cheap
+ * enough to call on every image; callers use it to skip reading a file off
+ * disk (or invoking sharp) for a format that structurally cannot need it.
+ */
+export declare function mayCarryExifOrientation(mimeType: string): boolean;
+/**
+ * Leading bytes {@link probeExifOrientation} needs to reach a verdict on the
+ * containers it parses.
+ *
+ * A JPEG's EXIF block lives in an APP1 segment whose length field is 16 bits
+ * wide, so the segment cannot exceed 64 KiB — and IFD0, which holds the
+ * orientation tag, sits at the very front of it. One window this size
+ * therefore spans the entire tag block of any file written EXIF-first, which
+ * is every file a camera or phone produces. WebP settles in 21 bytes; PNG
+ * walks complete chunks through the first IDAT and falls back if this window
+ * ends first.
+ *
+ * Sized deliberately in terms of what the format guarantees rather than what
+ * a sample of files happens to need: a window chosen by measurement would
+ * turn an unusual-but-legal layout into a silent wrong answer, whereas
+ * running out of this one returns `"inconclusive"` and costs only the read it
+ * was trying to avoid.
+ */
+export declare const EXIF_PROBE_PREFIX_BYTES: number;
+/**
+ * Decide from a bounded header prefix whether an image carries an EXIF
+ * orientation worth acting on — without decoding it, and without needing all
+ * of its bytes.
+ *
+ * This exists because the orientation question is asked of every JPEG, PNG
+ * and WebP a caller supplies, while the answer is "no" for almost all of them.
+ * Answering it with a decoder means reading the whole file into memory and
+ * loading sharp to look at a header; answering it here costs
+ * {@link EXIF_PROBE_PREFIX_BYTES} at most, and usually far less.
+ *
+ * The verdict is deliberately three-valued. `"absent"` is a promise — the
+ * container was parsed far enough to rule an actionable tag out — and callers
+ * may skip the expensive path on it. Everything else, including every
+ * container this probe does not parse (HEIC, HEIF, AVIF: ISOBMFF, where
+ * orientation is an item property rather than a header field), comes back
+ * `"inconclusive"` and must fall through to the decoder.
+ *
+ * @param prefix - Leading bytes of the image; the whole image is also fine.
+ * @param mimeType - Detected MIME type of the image `prefix` came from.
+ */
+export declare function probeExifOrientation(prefix: Buffer, mimeType: string): ExifOrientationProbe;
 /**
  * Return image bytes every vision provider can read, transcoding to PNG when
  * the source format is one no provider accepts.
@@ -55,13 +102,76 @@ export declare function needsVisionTranscode(mimeType: string): boolean;
  * compatibility step becoming a new way for a previously working request to
  * break.
  *
+ * `options.autoOrient` folds an EXIF orientation correction into the same
+ * decode, for a format that needs both (HEIC, HEIF, TIFF, AVIF are in both
+ * sets). The sharp backend honours it explicitly, via `.rotate()`.
+ *
+ * The ffmpeg backends take no flag for it, and `-autorotate` would only
+ * restate a default rather than fix anything — but that is established for
+ * one orientation mechanism only, so read the scope before relying on it.
+ *
+ * **Measured — EXIF-IFD orientation.** A 300x150 JPEG tagged `Orientation=6`
+ * came back 150x300 with the tag consumed on system ffmpeg 8.1.1 and on the
+ * bundled `ffmpeg-static` 6.0, and stayed 300x150 on both only when
+ * `-noautorotate` was forced, which is the control showing the default did
+ * the work. TIFF stores orientation the same way.
+ *
+ * ⚠️ **Not measured — ISOBMFF `irot`/`imir`.** HEIC, HEIF and AVIF carry
+ * orientation as item properties, a structurally different mechanism the
+ * EXIF result says nothing about. That gap matters more than its size
+ * suggests: HEVC-coded HEIC is the main reason this fallback exists at all,
+ * since sharp cannot decode it, whereas the JPEG used above never reaches
+ * ffmpeg in production — JPEG is universal and is never transcoded, so the
+ * fixture demonstrates the binaries' behaviour rather than a path a request
+ * takes. Whether an `irot`-bearing HEIC is corrected here is untested in
+ * both directions; treat it as unknown rather than working.
+ *
+ * `autoOrient` is in any case a request rather than a guarantee, exactly like
+ * `converted`: a source no backend can decode is returned untouched.
+ *
+ * ⚠️ Two further things would quietly break the measured case, and neither
+ * fails a test, because the fused path reports `converted: true` either way.
+ * Passing `-noautorotate`, or an ffmpeg build defaulting it off, drops the
+ * rotation. And the sharp-first ordering in {@link transcodeBackends} is what
+ * keeps the two backends' orientation behaviour equivalent rather than merely
+ * similar — sharp strips the tag while ffmpeg's PNG output carries none to
+ * begin with.
+ *
+ * @param buffer - Raw image bytes.
+ * @param mimeType - Detected MIME type of `buffer`.
+ * @param options - See {@link VisionTranscodeOptions}. `outputFormat`
+ *   defaults to `"png"` — see the module header for why that stays the
+ *   default for every caller who doesn't opt into `"jpeg"` explicitly.
+ */
+export declare function toVisionCompatibleImage(buffer: Buffer, mimeType: string, options?: VisionTranscodeOptions): Promise<VisionImageConversion>;
+/**
+ * Auto-orient an image from its EXIF/XMP tag and strip the tag, so a photo
+ * that was stored rotated (the common case for phone cameras, since the
+ * sensor is read in one fixed orientation and rotation is recorded as a flag
+ * rather than baked into the pixels) is sent upright instead of sideways.
+ *
+ * Three costs are guarded deliberately, matching how `toVisionCompatibleImage`
+ * guards its own:
+ * - **Cost**: `mayCarryExifOrientation` skips formats that cannot carry the
+ *   tag; `probeExifOrientation` then settles the formats that can from their
+ *   own header bytes, so the overwhelmingly common orientation-less JPEG or
+ *   WebP never loads sharp at all. Only a container the probe cannot rule
+ *   out reaches a `metadata()` call, and only a tag that is present and not
+ *   the already-upright value `1` reaches the decode-and-re-encode.
+ * - **Availability**: sharp is an optional dependency (the ffmpeg fallback
+ *   path above exists precisely because it can be absent). Any failure —
+ *   missing package, malformed pixels, a timeout — is caught here and
+ *   degrades to returning the original bytes unchanged, never throwing.
+ * - **Size**: re-encoding changes byte length. This function only returns the
+ *   new bytes; it does not itself re-validate size limits. Callers that
+ *   re-encode must re-run their size guard on the returned buffer.
+ *
+ * Never throws for image reasons — mirrors `toVisionCompatibleImage`.
+ *
  * @param buffer - Raw image bytes.
  * @param mimeType - Detected MIME type of `buffer`.
- * @param outputFormat - Transcode target. Defaults to `"png"` — see the
- *   module header for why that stays the default for every caller who
- *   doesn't opt into `"jpeg"` explicitly.
  */
-export declare function toVisionCompatibleImage(buffer: Buffer, mimeType: string, outputFormat?: VisionImageOutputFormat): Promise<VisionImageConversion>;
+export declare function normalizeImageOrientation(buffer: Buffer, mimeType: string): Promise<ImageOrientationNormalization>;
 /**
  * Unwrap an `input.images` entry to its payload.
  *

package/dist/adapters/imageFormatSupport.js

@@ -102,6 +102,295 @@ export function needsVisionTranscode(mimeType) {
     return (!UNIVERSAL_VISION_IMAGE_MIME_TYPES.has(normalized) &&
         TRANSCODABLE_IMAGE_MIME_TYPES.has(normalized));
 }
+/**
+ * Formats whose spec allows an EXIF/XMP orientation tag.
+ *
+ * GIF has no such field, so it is deliberately absent. PNG 1.5 added the
+ * `eXIf` chunk and is included; the bounded chunk walk below keeps ordinary
+ * PNGs off sharp's metadata path just as the JPEG/WebP probes do.
+ */
+const EXIF_ORIENTABLE_MIME_TYPES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/tiff",
+    "image/x-tiff",
+    "image/webp",
+    "image/avif",
+    "image/heic",
+    "image/heic-sequence",
+    "image/heif",
+    "image/heif-sequence",
+]);
+/**
+ * True when a MIME type's format can carry an orientation tag at all. Cheap
+ * enough to call on every image; callers use it to skip reading a file off
+ * disk (or invoking sharp) for a format that structurally cannot need it.
+ */
+export function mayCarryExifOrientation(mimeType) {
+    const normalized = mimeType.split(";")[0].trim().toLowerCase();
+    return EXIF_ORIENTABLE_MIME_TYPES.has(normalized);
+}
+/**
+ * Leading bytes {@link probeExifOrientation} needs to reach a verdict on the
+ * containers it parses.
+ *
+ * A JPEG's EXIF block lives in an APP1 segment whose length field is 16 bits
+ * wide, so the segment cannot exceed 64 KiB — and IFD0, which holds the
+ * orientation tag, sits at the very front of it. One window this size
+ * therefore spans the entire tag block of any file written EXIF-first, which
+ * is every file a camera or phone produces. WebP settles in 21 bytes; PNG
+ * walks complete chunks through the first IDAT and falls back if this window
+ * ends first.
+ *
+ * Sized deliberately in terms of what the format guarantees rather than what
+ * a sample of files happens to need: a window chosen by measurement would
+ * turn an unusual-but-legal layout into a silent wrong answer, whereas
+ * running out of this one returns `"inconclusive"` and costs only the read it
+ * was trying to avoid.
+ */
+export const EXIF_PROBE_PREFIX_BYTES = 64 * 1024;
+/** Orientation, tag 0x0112 of TIFF/EXIF IFD0. */
+const EXIF_TAG_ORIENTATION = 0x0112;
+/** TIFF field types this probe knows how to read a scalar out of. */
+const TIFF_TYPE_SHORT = 3;
+const TIFF_TYPE_LONG = 4;
+function readUint16(buffer, offset, littleEndian) {
+    if (offset < 0 || offset + 2 > buffer.length) {
+        return undefined;
+    }
+    return littleEndian
+        ? buffer.readUInt16LE(offset)
+        : buffer.readUInt16BE(offset);
+}
+function readUint32(buffer, offset, littleEndian) {
+    if (offset < 0 || offset + 4 > buffer.length) {
+        return undefined;
+    }
+    return littleEndian
+        ? buffer.readUInt32LE(offset)
+        : buffer.readUInt32BE(offset);
+}
+/**
+ * Read the orientation tag out of a TIFF header block — the payload of a JPEG
+ * APP1 segment past its `Exif\0\0` signature, or a `.tif` file's own opening
+ * bytes, which are the same structure.
+ *
+ * Only IFD0 is walked. That is where every writer puts orientation, and it is
+ * also the only IFD libvips reads it from, so a deeper walk would find tags
+ * that the decoder this probe is standing in for would itself ignore.
+ */
+function probeTiffBlockOrientation(tiff) {
+    const byteOrder = readUint16(tiff, 0, false);
+    const littleEndian = byteOrder === 0x4949; // "II"
+    if (!littleEndian && byteOrder !== 0x4d4d /* "MM" */) {
+        return "inconclusive";
+    }
+    if (readUint16(tiff, 2, littleEndian) !== 42) {
+        return "inconclusive";
+    }
+    const ifdOffset = readUint32(tiff, 4, littleEndian);
+    if (ifdOffset === undefined) {
+        return "inconclusive";
+    }
+    const entryCount = readUint16(tiff, ifdOffset, littleEndian);
+    if (entryCount === undefined) {
+        return "inconclusive";
+    }
+    // Every entry must be inside the window before "no orientation tag here"
+    // can mean anything — a half-read IFD is a question, not an answer.
+    if (ifdOffset + 2 + entryCount * 12 > tiff.length) {
+        return "inconclusive";
+    }
+    for (let i = 0; i < entryCount; i++) {
+        const entry = ifdOffset + 2 + i * 12;
+        if (readUint16(tiff, entry, littleEndian) !== EXIF_TAG_ORIENTATION) {
+            continue;
+        }
+        const fieldType = readUint16(tiff, entry + 2, littleEndian);
+        // A scalar that fits in four bytes is stored left-justified in the value
+        // field, so both widths start at the same place. An exotic field type is
+        // left to the decoder rather than guessed at.
+        const value = fieldType === TIFF_TYPE_SHORT
+            ? readUint16(tiff, entry + 8, littleEndian)
+            : fieldType === TIFF_TYPE_LONG
+                ? readUint32(tiff, entry + 8, littleEndian)
+                : undefined;
+        if (value === undefined) {
+            return "inconclusive";
+        }
+        // Matches `normalizeImageOrientation`'s own condition: 1 is upright and 0
+        // is the absent/invalid encoding, and neither is worth a re-encode.
+        return value <= 1 ? "absent" : "present";
+    }
+    return "absent";
+}
+/**
+ * Walk a JPEG's marker segments looking for the EXIF APP1.
+ *
+ * Reaching SOS or EOI is a conclusive "absent": metadata segments are
+ * required to precede the entropy-coded scan, so nothing past that point can
+ * introduce one. Running off the end of the window is not conclusive and says
+ * so.
+ */
+function probeJpegOrientation(prefix) {
+    if (prefix.length < 4 || prefix.readUInt16BE(0) !== 0xffd8 /* SOI */) {
+        // The extension claimed JPEG and the bytes disagree. Whatever this is,
+        // the decoder gets to say so.
+        return "inconclusive";
+    }
+    let offset = 2;
+    while (offset + 4 <= prefix.length) {
+        if (prefix[offset] !== 0xff) {
+            return "inconclusive";
+        }
+        // Any run of 0xFF ahead of the marker id is legal fill.
+        let markerAt = offset + 1;
+        while (markerAt < prefix.length && prefix[markerAt] === 0xff) {
+            markerAt++;
+        }
+        if (markerAt >= prefix.length) {
+            return "inconclusive";
+        }
+        const marker = prefix[markerAt];
+        if (marker === 0xd9 /* EOI */ || marker === 0xda /* SOS */) {
+            return "absent";
+        }
+        // Standalone markers carry no length field to skip over.
+        if (marker === 0x01 ||
+            marker === 0xd8 ||
+            (marker >= 0xd0 && marker <= 0xd7)) {
+            offset = markerAt + 1;
+            continue;
+        }
+        const length = readUint16(prefix, markerAt + 1, false);
+        if (length === undefined || length < 2) {
+            return "inconclusive";
+        }
+        const payloadStart = markerAt + 3;
+        const segmentEnd = markerAt + 1 + length;
+        if (marker === 0xe1 /* APP1 */) {
+            if (segmentEnd > prefix.length) {
+                return "inconclusive";
+            }
+            const payload = prefix.subarray(payloadStart, segmentEnd);
+            if (payload.length > 6 &&
+                payload.subarray(0, 4).toString("latin1") === "Exif" &&
+                payload[4] === 0x00 &&
+                payload[5] === 0x00) {
+                return probeTiffBlockOrientation(payload.subarray(6));
+            }
+            // Some other APP1 — an XMP packet, most often. Keep walking; the EXIF
+            // one may still be ahead.
+        }
+        offset = segmentEnd;
+    }
+    return "inconclusive";
+}
+/**
+ * Read the VP8X feature flags of a WebP container.
+ *
+ * A simple-format file (`VP8 ` / `VP8L` as its only chunk) has nowhere to put
+ * metadata, which settles it outright. An extended file advertises whether an
+ * EXIF chunk exists anywhere in the file, and that flag alone is enough to
+ * clear the common case — the chunk itself is conventionally written after
+ * the image data, so a set flag is where a header prefix stops being able to
+ * answer.
+ */
+function probeWebpOrientation(prefix) {
+    if (prefix.length < 16 ||
+        prefix.subarray(0, 4).toString("latin1") !== "RIFF" ||
+        prefix.subarray(8, 12).toString("latin1") !== "WEBP") {
+        return "inconclusive";
+    }
+    const firstChunk = prefix.subarray(12, 16).toString("latin1");
+    if (firstChunk === "VP8 " || firstChunk === "VP8L") {
+        return "absent";
+    }
+    // fourCC (4) + chunk length (4) puts the flags byte at 20.
+    if (firstChunk !== "VP8X" || prefix.length < 21) {
+        return "inconclusive";
+    }
+    const EXIF_CHUNK_FLAG = 0x08;
+    return (prefix[20] & EXIF_CHUNK_FLAG) === 0 ? "absent" : "inconclusive";
+}
+/**
+ * Walk complete PNG chunks through the first IDAT looking for `eXIf`.
+ *
+ * PNG requires metadata chunks to precede image data, so reaching IDAT is a
+ * conclusive absence. Running out inside any preceding chunk is not: the next
+ * complete chunk might be `eXIf`, and treating a bounded read as the whole
+ * file would turn the performance probe into a correctness bug.
+ */
+function probePngOrientation(prefix) {
+    const signature = Buffer.from([
+        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+    ]);
+    if (prefix.length < signature.length ||
+        !prefix.subarray(0, 8).equals(signature)) {
+        return "inconclusive";
+    }
+    let offset = signature.length;
+    let sawHeader = false;
+    while (offset + 12 <= prefix.length) {
+        const length = prefix.readUInt32BE(offset);
+        const type = prefix.subarray(offset + 4, offset + 8).toString("latin1");
+        const end = offset + 12 + length;
+        if (end > prefix.length) {
+            return "inconclusive";
+        }
+        if (!sawHeader) {
+            if (type !== "IHDR") {
+                return "inconclusive";
+            }
+            sawHeader = true;
+        }
+        else if (type === "eXIf") {
+            return probeTiffBlockOrientation(prefix.subarray(offset + 8, offset + 8 + length));
+        }
+        else if (type === "IDAT" || type === "IEND") {
+            return "absent";
+        }
+        offset = end;
+    }
+    return "inconclusive";
+}
+/**
+ * Decide from a bounded header prefix whether an image carries an EXIF
+ * orientation worth acting on — without decoding it, and without needing all
+ * of its bytes.
+ *
+ * This exists because the orientation question is asked of every JPEG, PNG
+ * and WebP a caller supplies, while the answer is "no" for almost all of them.
+ * Answering it with a decoder means reading the whole file into memory and
+ * loading sharp to look at a header; answering it here costs
+ * {@link EXIF_PROBE_PREFIX_BYTES} at most, and usually far less.
+ *
+ * The verdict is deliberately three-valued. `"absent"` is a promise — the
+ * container was parsed far enough to rule an actionable tag out — and callers
+ * may skip the expensive path on it. Everything else, including every
+ * container this probe does not parse (HEIC, HEIF, AVIF: ISOBMFF, where
+ * orientation is an item property rather than a header field), comes back
+ * `"inconclusive"` and must fall through to the decoder.
+ *
+ * @param prefix - Leading bytes of the image; the whole image is also fine.
+ * @param mimeType - Detected MIME type of the image `prefix` came from.
+ */
+export function probeExifOrientation(prefix, mimeType) {
+    const normalized = mimeType.split(";")[0].trim().toLowerCase();
+    switch (normalized) {
+        case "image/png":
+            return probePngOrientation(prefix);
+        case "image/jpeg":
+            return probeJpegOrientation(prefix);
+        case "image/webp":
+            return probeWebpOrientation(prefix);
+        case "image/tiff":
+        case "image/x-tiff":
+            return probeTiffBlockOrientation(prefix);
+        default:
+            return "inconclusive";
+    }
+}
 /**
  * Decode with sharp. Covers TIFF, AVIF, GIF and SVG in-process with no temp
  * files, which is the fast path.
@@ -111,7 +400,7 @@ export function needsVisionTranscode(mimeType) {
  * only — actual HEVC-coded HEIC fails inside libheif, and BMP, ICO and
  * JPEG 2000 are not compiled in at all. Those fall through to ffmpeg below.
  */
-async function transcodeWithSharp(buffer, outputFormat) {
+async function transcodeWithSharp(buffer, outputFormat, autoOrient) {
     const sharpModule = await tryImport("sharp", "Image format conversion for vision providers");
     // A shape guard, not a crash guard: an absent or malformed sharp already
     // fails safely, because `tryImport` throws a named install error and any
@@ -130,19 +419,29 @@ async function transcodeWithSharp(buffer, outputFormat) {
     // a multi-page TIFF) from being flattened into one tall strip — the first
     // frame is what a vision model should receive.
     const pipeline = sharpModule.default(buffer, { pages: 1 });
+    if (autoOrient && typeof pipeline.rotate !== "function") {
+        throw new Error("the installed sharp package returned a pipeline without a rotate() transform");
+    }
+    // `.rotate()` with no argument auto-orients from the EXIF tag and strips it,
+    // and is applied before the format-specific encoder regardless of which one
+    // runs, so an image needing both a transcode and an orientation fix costs one
+    // decode and one encode rather than two of each — and, for a source sharp
+    // writes lossily (TIFF defaults to JPEG compression), skips a whole
+    // generation of quality loss on the way.
+    const oriented = autoOrient ? pipeline.rotate() : pipeline;
     if (outputFormat === "jpeg") {
         // The instance shape is checked as well as the factory: a build that
         // exports a callable but returns something without `.jpeg()` would
         // otherwise fail as an opaque TypeError inside the backend loop.
-        if (typeof pipeline?.jpeg !== "function") {
+        if (typeof oriented?.jpeg !== "function") {
             throw new Error("the installed sharp package returned a pipeline without a jpeg() encoder");
         }
-        return pipeline.jpeg().toBuffer();
+        return oriented.jpeg().toBuffer();
     }
-    if (typeof pipeline?.png !== "function") {
+    if (typeof oriented?.png !== "function") {
         throw new Error("the installed sharp package returned a pipeline without a png() encoder");
     }
-    return pipeline.png().toBuffer();
+    return oriented.png().toBuffer();
 }
 /**
  * Decode with ffmpeg, which handles what sharp cannot — most importantly HEIC,
@@ -210,10 +509,10 @@ async function transcodeWithFfmpeg(buffer, extension, outputFormat, binaryPath)
  * so when the resolved binary is not already the system one it is retried
  * explicitly rather than reporting a photo as unsupported.
  */
-async function* transcodeBackends(buffer, extension, outputFormat) {
+async function* transcodeBackends(buffer, extension, outputFormat, autoOrient) {
     yield {
         name: "sharp",
-        run: () => transcodeWithSharp(buffer, outputFormat),
+        run: () => transcodeWithSharp(buffer, outputFormat, autoOrient),
     };
     const resolved = await getFfmpegPath().catch(() => "ffmpeg");
     yield {
@@ -237,21 +536,58 @@ async function* transcodeBackends(buffer, extension, outputFormat) {
  * compatibility step becoming a new way for a previously working request to
  * break.
  *
+ * `options.autoOrient` folds an EXIF orientation correction into the same
+ * decode, for a format that needs both (HEIC, HEIF, TIFF, AVIF are in both
+ * sets). The sharp backend honours it explicitly, via `.rotate()`.
+ *
+ * The ffmpeg backends take no flag for it, and `-autorotate` would only
+ * restate a default rather than fix anything — but that is established for
+ * one orientation mechanism only, so read the scope before relying on it.
+ *
+ * **Measured — EXIF-IFD orientation.** A 300x150 JPEG tagged `Orientation=6`
+ * came back 150x300 with the tag consumed on system ffmpeg 8.1.1 and on the
+ * bundled `ffmpeg-static` 6.0, and stayed 300x150 on both only when
+ * `-noautorotate` was forced, which is the control showing the default did
+ * the work. TIFF stores orientation the same way.
+ *
+ * ⚠️ **Not measured — ISOBMFF `irot`/`imir`.** HEIC, HEIF and AVIF carry
+ * orientation as item properties, a structurally different mechanism the
+ * EXIF result says nothing about. That gap matters more than its size
+ * suggests: HEVC-coded HEIC is the main reason this fallback exists at all,
+ * since sharp cannot decode it, whereas the JPEG used above never reaches
+ * ffmpeg in production — JPEG is universal and is never transcoded, so the
+ * fixture demonstrates the binaries' behaviour rather than a path a request
+ * takes. Whether an `irot`-bearing HEIC is corrected here is untested in
+ * both directions; treat it as unknown rather than working.
+ *
+ * `autoOrient` is in any case a request rather than a guarantee, exactly like
+ * `converted`: a source no backend can decode is returned untouched.
+ *
+ * ⚠️ Two further things would quietly break the measured case, and neither
+ * fails a test, because the fused path reports `converted: true` either way.
+ * Passing `-noautorotate`, or an ffmpeg build defaulting it off, drops the
+ * rotation. And the sharp-first ordering in {@link transcodeBackends} is what
+ * keeps the two backends' orientation behaviour equivalent rather than merely
+ * similar — sharp strips the tag while ffmpeg's PNG output carries none to
+ * begin with.
+ *
  * @param buffer - Raw image bytes.
  * @param mimeType - Detected MIME type of `buffer`.
- * @param outputFormat - Transcode target. Defaults to `"png"` — see the
- *   module header for why that stays the default for every caller who
- *   doesn't opt into `"jpeg"` explicitly.
+ * @param options - See {@link VisionTranscodeOptions}. `outputFormat`
+ *   defaults to `"png"` — see the module header for why that stays the
+ *   default for every caller who doesn't opt into `"jpeg"` explicitly.
  */
-export async function toVisionCompatibleImage(buffer, mimeType, outputFormat = DEFAULT_VISION_IMAGE_OUTPUT_FORMAT) {
+export async function toVisionCompatibleImage(buffer, mimeType, options) {
     if (!needsVisionTranscode(mimeType)) {
         return { buffer, mimeType, converted: false };
     }
     const normalized = mimeType.split(";")[0].trim().toLowerCase();
     const extension = extensionForMimeType(normalized) ?? ".bin";
+    const outputFormat = options?.outputFormat ?? DEFAULT_VISION_IMAGE_OUTPUT_FORMAT;
     const targetMimeType = outputFormat === "jpeg" ? "image/jpeg" : "image/png";
+    const autoOrient = options?.autoOrient === true;
     const failures = [];
-    for await (const backend of transcodeBackends(buffer, extension, outputFormat)) {
+    for await (const backend of transcodeBackends(buffer, extension, outputFormat, autoOrient)) {
         try {
             // Both backends can stall — sharp on a malformed stream, ffmpeg on a
             // container it half-understands — and this runs inline on the request
@@ -275,6 +611,82 @@ export async function toVisionCompatibleImage(buffer, mimeType, outputFormat = D
         `Tried ${failures.join("; ")}`);
     return { buffer, mimeType, converted: false };
 }
+/**
+ * Auto-orient an image from its EXIF/XMP tag and strip the tag, so a photo
+ * that was stored rotated (the common case for phone cameras, since the
+ * sensor is read in one fixed orientation and rotation is recorded as a flag
+ * rather than baked into the pixels) is sent upright instead of sideways.
+ *
+ * Three costs are guarded deliberately, matching how `toVisionCompatibleImage`
+ * guards its own:
+ * - **Cost**: `mayCarryExifOrientation` skips formats that cannot carry the
+ *   tag; `probeExifOrientation` then settles the formats that can from their
+ *   own header bytes, so the overwhelmingly common orientation-less JPEG or
+ *   WebP never loads sharp at all. Only a container the probe cannot rule
+ *   out reaches a `metadata()` call, and only a tag that is present and not
+ *   the already-upright value `1` reaches the decode-and-re-encode.
+ * - **Availability**: sharp is an optional dependency (the ffmpeg fallback
+ *   path above exists precisely because it can be absent). Any failure —
+ *   missing package, malformed pixels, a timeout — is caught here and
+ *   degrades to returning the original bytes unchanged, never throwing.
+ * - **Size**: re-encoding changes byte length. This function only returns the
+ *   new bytes; it does not itself re-validate size limits. Callers that
+ *   re-encode must re-run their size guard on the returned buffer.
+ *
+ * Never throws for image reasons — mirrors `toVisionCompatibleImage`.
+ *
+ * @param buffer - Raw image bytes.
+ * @param mimeType - Detected MIME type of `buffer`.
+ */
+export async function normalizeImageOrientation(buffer, mimeType) {
+    if (!mayCarryExifOrientation(mimeType)) {
+        return { buffer, normalized: false };
+    }
+    // Only "absent" is actionable here. "inconclusive" means the parse ran out
+    // of container it understands, which is a question for the decoder rather
+    // than a no — see {@link probeExifOrientation}.
+    if (probeExifOrientation(buffer, mimeType) === "absent") {
+        return { buffer, normalized: false };
+    }
+    try {
+        const sharpModule = await tryImport("sharp", "EXIF orientation normalization");
+        if (typeof sharpModule?.default !== "function") {
+            throw new Error("the installed sharp package does not expose a callable default export");
+        }
+        // One shared deadline for the metadata read and the conditional re-encode,
+        // not one each. Both awaits are sequential, so two independent budgets
+        // are additive rather than shared: a metadata read that merely takes
+        // close to the full budget, followed by a rotate that stalls to its own
+        // full budget, costs close to double `IMAGE_TRANSCODE_TIMEOUT_MS` for one
+        // image before falling back — and that multiplies per image, since
+        // callers process `input.images` sequentially to preserve ordering. A
+        // single race caps the whole operation at one budget, matching every
+        // other timeout in this module (one per backend attempt).
+        const result = await withTimeout((async () => {
+            const metadata = await sharpModule.default(buffer).metadata();
+            // 1 is "already upright" (and the implicit value when the tag is
+            // absent altogether) — nothing to correct, so skip the re-encode
+            // entirely.
+            if (!metadata.orientation || metadata.orientation === 1) {
+                return { buffer, normalized: false };
+            }
+            const rotated = await sharpModule.default(buffer).rotate().toBuffer();
+            if (rotated.length === 0) {
+                throw new Error("auto-orient produced an empty image");
+            }
+            logger.debug(`[imageFormatSupport] Normalized EXIF orientation ${metadata.orientation} for ` +
+                `${mimeType} (${buffer.length} → ${rotated.length} bytes)`);
+            return { buffer: rotated, normalized: true };
+        })(), IMAGE_TRANSCODE_TIMEOUT_MS, new Error(`EXIF auto-orient exceeded ${IMAGE_TRANSCODE_TIMEOUT_MS}ms`));
+        return result;
+    }
+    catch (error) {
+        logger.warn(`[imageFormatSupport] Could not normalize EXIF orientation for ${mimeType} — ` +
+            `sending the original bytes as-is: ` +
+            `${error instanceof Error ? error.message : String(error)}`);
+        return { buffer, normalized: false };
+    }
+}
 /**
  * Whether an `input.images` entry is the `{ data, altText }` wrapper.
  *