@hyperframes/engine 0.4.10 → 0.4.11

package/src/services/frameCapture.ts

@@ -87,6 +87,19 @@ export async function createCaptureSession(
   const { browser, captureMode } = await acquireBrowser(chromeArgs, config);
 
   const page = await browser.newPage();
+  // Polyfill esbuild's keepNames helper inside the page. Tools like tsx/Bun
+  // transform this engine's source on the fly and wrap every named function
+  // with `__name(fn, "name")`. When `page.evaluate()` serializes a callback
+  // and ships it to the browser, those `__name(...)` calls would crash with
+  // `__name is not defined` because the helper only exists in Node. Defining
+  // a no-op shim once per page makes the engine work uniformly whether it is
+  // imported from compiled dist (no helper) or from source via tsx.
+  await page.evaluateOnNewDocument(() => {
+    const w = window as unknown as { __name?: <T>(fn: T, _name: string) => T };
+    if (typeof w.__name !== "function") {
+      w.__name = <T>(fn: T, _name: string): T => fn;
+    }
+  });
   const browserVersion = await browser.version();
   const expectedMajor = config?.expectedChromiumMajor;
   if (Number.isFinite(expectedMajor)) {
@@ -240,10 +253,14 @@ export async function initializeSession(session: CaptureSession): Promise<void>
     }
 
     // Wait for all video elements to have loaded metadata (dimensions + duration)
-    // Without this, frame 0 captures videos at their 300x150 default size
+    // Without this, frame 0 captures videos at their 300x150 default size.
+    // skipReadinessVideoIds excludes natively-extracted videos (e.g. HDR HEVC
+    // sources) whose frames come from ffmpeg out-of-band — Chromium may not be
+    // able to decode them at all (e.g. HEVC on Linux headless-shell).
+    const skipIdsLiteral = JSON.stringify(session.options.skipReadinessVideoIds ?? []);
     const videosReady = await pollPageExpression(
       page,
-      `document.querySelectorAll("video").length === 0 || Array.from(document.querySelectorAll("video")).every(v => v.readyState >= 1)`,
+      `(() => { const skip = new Set(${skipIdsLiteral}); const vids = Array.from(document.querySelectorAll("video")).filter(v => !skip.has(v.id)); return vids.length === 0 || vids.every(v => v.readyState >= 1); })()`,
       pageReadyTimeout,
     );
     if (!videosReady) {
@@ -318,11 +335,13 @@ export async function initializeSession(session: CaptureSession): Promise<void>
 
   // Wait for all video elements to have loaded metadata (dimensions + duration).
   // Without this, frame 0 captures videos at their 300x150 default size.
+  // See screenshot-mode comment above for why skipReadinessVideoIds exists.
+  const beginframeSkipIdsLiteral = JSON.stringify(session.options.skipReadinessVideoIds ?? []);
   const videoDeadline =
     Date.now() + (session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout);
   while (Date.now() < videoDeadline) {
     const videosReady = await page.evaluate(
-      `document.querySelectorAll("video").length === 0 || Array.from(document.querySelectorAll("video")).every(v => v.readyState >= 1)`,
+      `(() => { const skip = new Set(${beginframeSkipIdsLiteral}); const vids = Array.from(document.querySelectorAll("video")).filter(v => !skip.has(v.id)); return vids.length === 0 || vids.every(v => v.readyState >= 1); })()`,
     );
     if (videosReady) break;
     await new Promise((r) => setTimeout(r, 100));

package/src/services/videoFrameExtractor.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { parseVideoElements } from "./videoFrameExtractor.js";
+import { parseVideoElements, parseImageElements } from "./videoFrameExtractor.js";
 
 describe("parseVideoElements", () => {
   it("parses videos without an id or data-start attribute", () => {
@@ -32,3 +32,52 @@ describe("parseVideoElements", () => {
     });
   });
 });
+
+describe("parseImageElements", () => {
+  it("parses images with data-start and data-duration", () => {
+    const images = parseImageElements(
+      '<img id="photo" src="hdr-photo.png" data-start="0" data-duration="3" />',
+    );
+
+    expect(images).toHaveLength(1);
+    expect(images[0]).toEqual({
+      id: "photo",
+      src: "hdr-photo.png",
+      start: 0,
+      end: 3,
+    });
+  });
+
+  it("generates stable IDs for images without one", () => {
+    const images = parseImageElements(
+      '<img src="a.png" data-start="0" data-end="2" /><img src="b.png" data-start="1" data-end="4" />',
+    );
+
+    expect(images).toHaveLength(2);
+    expect(images[0]!.id).toBe("hf-img-0");
+    expect(images[1]!.id).toBe("hf-img-1");
+  });
+
+  it("defaults start to 0 and end to Infinity when attributes missing", () => {
+    const images = parseImageElements('<img src="photo.png" />');
+
+    expect(images).toHaveLength(1);
+    expect(images[0]).toMatchObject({
+      src: "photo.png",
+      start: 0,
+      end: Infinity,
+    });
+  });
+
+  it("ignores img elements without src", () => {
+    const images = parseImageElements('<img data-start="0" data-end="3" />');
+    expect(images).toHaveLength(0);
+  });
+
+  it("uses data-end over data-duration when both present", () => {
+    const images = parseImageElements(
+      '<img src="a.png" data-start="1" data-end="5" data-duration="10" />',
+    );
+    expect(images[0]!.end).toBe(5);
+  });
+});

package/src/services/videoFrameExtractor.ts

@@ -97,6 +97,48 @@ export function parseVideoElements(html: string): VideoElement[] {
   return videos;
 }
 
+export interface ImageElement {
+  id: string;
+  src: string;
+  start: number;
+  end: number;
+}
+
+export function parseImageElements(html: string): ImageElement[] {
+  const images: ImageElement[] = [];
+  const { document } = parseHTML(html);
+
+  const imgEls = document.querySelectorAll("img[src]");
+  let autoIdCounter = 0;
+  for (const el of imgEls) {
+    const src = el.getAttribute("src");
+    if (!src) continue;
+
+    const id = el.getAttribute("id") || `hf-img-${autoIdCounter++}`;
+    if (!el.getAttribute("id")) {
+      el.setAttribute("id", id);
+    }
+
+    const startAttr = el.getAttribute("data-start");
+    const endAttr = el.getAttribute("data-end");
+    const durationAttr = el.getAttribute("data-duration");
+
+    const start = startAttr ? parseFloat(startAttr) : 0;
+    let end = 0;
+    if (endAttr) {
+      end = parseFloat(endAttr);
+    } else if (durationAttr) {
+      end = start + parseFloat(durationAttr);
+    } else {
+      end = Infinity;
+    }
+
+    images.push({ id, src, start, end });
+  }
+
+  return images;
+}
+
 export async function extractVideoFramesRange(
   videoPath: string,
   videoId: string,

package/src/services/videoFrameInjector.ts

@@ -244,20 +244,34 @@ export interface ElementStackingInfo {
   isHdr: boolean;
   transform: string; // CSS transform matrix string, e.g. "matrix(1,0,0,1,0,0)" or "none"
   borderRadius: [number, number, number, number]; // [tl, tr, br, bl] in CSS px from nearest clipping ancestor
+  /**
+   * CSS `object-fit` value for replaced elements (`<img>`, `<video>`).
+   * One of: `fill` (default), `cover`, `contain`, `none`, `scale-down`.
+   * The HDR compositor uses this to resample image/video buffers into the
+   * element's layout box the same way the browser would.
+   */
+  objectFit: string;
+  /**
+   * CSS `object-position` value (e.g. `"50% 50%"`, `"center top"`).
+   * Falls back to the CSS default `"50% 50%"` (center) when unset.
+   */
+  objectPosition: string;
 }
 
 /**
  * Query Chrome for ALL timed elements' stacking context.
- * Returns z-index, bounds, opacity, and whether each element is a native HDR video.
+ * Returns z-index, bounds, opacity, and whether each element is a native HDR source.
  *
  * Queries every element with `data-start` (not just videos) so the layer compositor
- * can determine z-ordering between DOM content and HDR video elements.
+ * can determine z-ordering between DOM content and HDR video/image elements.
+ *
+ * @param nativeHdrIds Combined set of HDR-tagged element IDs (videos AND images).
  */
 export async function queryElementStacking(
   page: Page,
-  nativeHdrVideoIds: Set<string>,
+  nativeHdrIds: Set<string>,
 ): Promise<ElementStackingInfo[]> {
-  const hdrIds = Array.from(nativeHdrVideoIds);
+  const hdrIds = Array.from(nativeHdrIds);
   return page.evaluate((hdrIdList: string[]): ElementStackingInfo[] => {
     const hdrSet = new Set(hdrIdList);
     const elements = document.querySelectorAll("[data-start]");
@@ -454,6 +468,11 @@ export async function queryElementStacking(
         // elements, the element-level transform is sufficient for reference.
         transform: isHdrEl ? getViewportMatrix(el) : style.transform || "none",
         borderRadius: isHdrEl ? getEffectiveBorderRadius(el) : [0, 0, 0, 0],
+        // `getComputedStyle` returns "" when the property doesn't apply (e.g.
+        // for non-replaced elements); normalize to the CSS defaults so callers
+        // can rely on a populated value.
+        objectFit: style.objectFit || "fill",
+        objectPosition: style.objectPosition || "50% 50%",
       });
     }
     return results;

package/src/types.ts

@@ -94,6 +94,18 @@ export interface CaptureOptions {
   format?: "jpeg" | "png";
   quality?: number;
   deviceScaleFactor?: number;
+  /**
+   * Video element IDs to exclude from the in-page readiness check that waits
+   * for `video.readyState >= 1` before capture starts.
+   *
+   * Use for videos whose frames are supplied out-of-band (e.g. native HDR
+   * frame extraction via ffmpeg). The DOM `<video>` element is then only
+   * needed for layout (`getBoundingClientRect` / `offsetWidth`), which works
+   * at `readyState=0`. Without this, codecs that headless Chromium can't
+   * decode (HEVC on Linux `headless-shell`) cause a fatal timeout even
+   * though we never asked the browser to play the video.
+   */
+  skipReadinessVideoIds?: readonly string[];
 }
 
 export interface CaptureResult {

package/src/utils/alphaBlit.test.ts

@@ -8,6 +8,8 @@ import {
   blitRgb48leAffine,
   parseTransformMatrix,
   roundedRectAlpha,
+  resampleRgb48leObjectFit,
+  normalizeObjectFit,
 } from "./alphaBlit.js";
 
 // ── PNG construction helpers ─────────────────────────────────────────────────
@@ -991,3 +993,155 @@ describe("blitRgb48leAffine with borderRadius", () => {
     expect(Buffer.compare(canvas1, canvas2)).toBe(0);
   });
 });
+
+// ── normalizeObjectFit ──────────────────────────────────────────────────────
+
+describe("normalizeObjectFit", () => {
+  it("returns supported values verbatim", () => {
+    expect(normalizeObjectFit("fill")).toBe("fill");
+    expect(normalizeObjectFit("cover")).toBe("cover");
+    expect(normalizeObjectFit("contain")).toBe("contain");
+    expect(normalizeObjectFit("none")).toBe("none");
+    expect(normalizeObjectFit("scale-down")).toBe("scale-down");
+  });
+
+  it("trims whitespace and lowercases input", () => {
+    expect(normalizeObjectFit("  COVER  ")).toBe("cover");
+  });
+
+  it("falls back to fill for unsupported values", () => {
+    expect(normalizeObjectFit(undefined)).toBe("fill");
+    expect(normalizeObjectFit("")).toBe("fill");
+    expect(normalizeObjectFit("inherit")).toBe("fill");
+    expect(normalizeObjectFit("garbage")).toBe("fill");
+  });
+});
+
+// ── resampleRgb48leObjectFit ────────────────────────────────────────────────
+
+function readRgb16(buf: Buffer, width: number, x: number, y: number): [number, number, number] {
+  const off = (y * width + x) * 6;
+  return [buf.readUInt16LE(off), buf.readUInt16LE(off + 2), buf.readUInt16LE(off + 4)];
+}
+
+describe("resampleRgb48leObjectFit", () => {
+  it("returns the same buffer unchanged for identity fill resample", () => {
+    const src = makeHdrFrame(4, 4, 40000, 30000, 20000);
+    const out = resampleRgb48leObjectFit(src, 4, 4, 4, 4, "fill");
+
+    // Fast path returns the same Buffer reference, not a copy
+    expect(out).toBe(src);
+  });
+
+  it("returns the source untouched on degenerate dimensions", () => {
+    const src = makeHdrFrame(4, 4, 1, 2, 3);
+    expect(resampleRgb48leObjectFit(src, 0, 4, 8, 8, "cover")).toBe(src);
+    expect(resampleRgb48leObjectFit(src, 4, 4, 0, 8, "cover")).toBe(src);
+  });
+
+  it("fills a larger box with stretched content (fit=fill)", () => {
+    const src = makeHdrFrame(2, 2, 50000, 40000, 30000);
+    const out = resampleRgb48leObjectFit(src, 2, 2, 8, 4, "fill");
+
+    expect(out.length).toBe(8 * 4 * 6);
+    // Every output pixel should be the source color (uniform input → uniform output)
+    for (let y = 0; y < 4; y++) {
+      for (let x = 0; x < 8; x++) {
+        const [r, g, b] = readRgb16(out, 8, x, y);
+        expect(r).toBe(50000);
+        expect(g).toBe(40000);
+        expect(b).toBe(30000);
+      }
+    }
+  });
+
+  it("covers the destination box (cover) — fills entire box, no black bars", () => {
+    // 4×2 source into a 6×6 dst: cover scales by 6/2 = 3 → rendered 12×6, cropped horizontally
+    const src = makeHdrFrame(4, 2, 65000, 0, 0);
+    const out = resampleRgb48leObjectFit(src, 4, 2, 6, 6, "cover");
+
+    // No pillarbox/letterbox black anywhere
+    for (let y = 0; y < 6; y++) {
+      for (let x = 0; x < 6; x++) {
+        const [r] = readRgb16(out, 6, x, y);
+        expect(r).toBe(65000);
+      }
+    }
+  });
+
+  it("contains the source (contain) and letterboxes with opaque black", () => {
+    // 4×2 source into a 6×6 dst: contain scales by 6/4 = 1.5 → rendered 6×3, vertically centered
+    const src = makeHdrFrame(4, 2, 65000, 65000, 65000);
+    const out = resampleRgb48leObjectFit(src, 4, 2, 6, 6, "contain");
+
+    // Top and bottom rows should be black (letterbox)
+    for (const y of [0, 5]) {
+      for (let x = 0; x < 6; x++) {
+        expect(readRgb16(out, 6, x, y)).toEqual([0, 0, 0]);
+      }
+    }
+    // Middle band (rows 2–3) should be the source color
+    for (const y of [2, 3]) {
+      for (let x = 0; x < 6; x++) {
+        const [r, g, b] = readRgb16(out, 6, x, y);
+        expect(r).toBe(65000);
+        expect(g).toBe(65000);
+        expect(b).toBe(65000);
+      }
+    }
+  });
+
+  it("none preserves source size and centers it on a black background", () => {
+    // 2×2 source into a 6×6 dst with default object-position 50%/50%
+    const src = makeHdrFrame(2, 2, 40000, 30000, 20000);
+    const out = resampleRgb48leObjectFit(src, 2, 2, 6, 6, "none");
+
+    // Center 2×2 region (rows 2–3, cols 2–3) holds the source
+    for (let y = 2; y < 4; y++) {
+      for (let x = 2; x < 4; x++) {
+        const [r, g, b] = readRgb16(out, 6, x, y);
+        expect(r).toBe(40000);
+        expect(g).toBe(30000);
+        expect(b).toBe(20000);
+      }
+    }
+    // Corners should be black
+    expect(readRgb16(out, 6, 0, 0)).toEqual([0, 0, 0]);
+    expect(readRgb16(out, 6, 5, 5)).toEqual([0, 0, 0]);
+  });
+
+  it("respects object-position for none-fit alignment", () => {
+    // 2×2 source into a 6×6 dst, anchored top-left
+    const src = makeHdrFrame(2, 2, 40000, 30000, 20000);
+    const out = resampleRgb48leObjectFit(src, 2, 2, 6, 6, "none", "0% 0%");
+
+    // Top-left 2×2 block holds the source
+    for (let y = 0; y < 2; y++) {
+      for (let x = 0; x < 2; x++) {
+        const [r] = readRgb16(out, 6, x, y);
+        expect(r).toBe(40000);
+      }
+    }
+    // Bottom-right corner stays black
+    expect(readRgb16(out, 6, 5, 5)).toEqual([0, 0, 0]);
+    // Just below the source band should be black
+    expect(readRgb16(out, 6, 0, 2)).toEqual([0, 0, 0]);
+    expect(readRgb16(out, 6, 2, 0)).toEqual([0, 0, 0]);
+  });
+
+  it("scale-down behaves like none when source fits in dst", () => {
+    const src = makeHdrFrame(2, 2, 40000, 30000, 20000);
+    const noneOut = resampleRgb48leObjectFit(src, 2, 2, 6, 6, "none");
+    const sdOut = resampleRgb48leObjectFit(src, 2, 2, 6, 6, "scale-down");
+
+    expect(Buffer.compare(noneOut, sdOut)).toBe(0);
+  });
+
+  it("scale-down behaves like contain when source overflows dst", () => {
+    const src = makeHdrFrame(8, 4, 40000, 30000, 20000);
+    const containOut = resampleRgb48leObjectFit(src, 8, 4, 6, 6, "contain");
+    const sdOut = resampleRgb48leObjectFit(src, 8, 4, 6, 6, "scale-down");
+
+    expect(Buffer.compare(containOut, sdOut)).toBe(0);
+  });
+});

package/src/utils/alphaBlit.ts

@@ -622,6 +622,233 @@ export function blitRgb48leAffine(
   }
 }
 
+/**
+ * CSS `object-fit` values supported by the HDR image/video resampler.
+ *
+ * Matches the CSS spec subset that browsers actually render for replaced
+ * elements (`<img>`, `<video>`). `scale-down` is normalized to whichever of
+ * `none` or `contain` produces the smaller rendered size, mirroring the spec.
+ */
+export type ObjectFit = "fill" | "cover" | "contain" | "none" | "scale-down";
+
+/**
+ * Parse a single axis of a CSS `object-position` string into a fraction in
+ * `[0, 1]` (proportion of the slack space along that axis).
+ *
+ * Defaults to 0.5 (centered) for unrecognized inputs to match CSS, which
+ * resolves invalid `object-position` values to the initial value (`50% 50%`).
+ */
+function parseObjectPositionAxis(value: string, axis: "x" | "y"): number {
+  const lower = value.trim().toLowerCase();
+  if (lower === "left" || lower === "top") return 0;
+  if (lower === "right" || lower === "bottom") return 1;
+  if (lower === "center" || lower === "") return 0.5;
+  if (lower.endsWith("%")) {
+    const pct = parseFloat(lower) / 100;
+    return Number.isFinite(pct) ? Math.max(0, Math.min(1, pct)) : 0.5;
+  }
+  // Pixel values (e.g. "10px") aren't fractional; without the slack-space
+  // numerator we can't honor them precisely. Fall back to center — this is
+  // strictly worse than the browser but matches what we'd render today.
+  if (axis === "x" || axis === "y") return 0.5;
+  return 0.5;
+}
+
+/**
+ * Parse a CSS `object-position` string like `"50% 50%"`, `"center top"`, or
+ * `"25% 75%"` into normalized `[0, 1]` fractions for X and Y.
+ *
+ * The fractions express how the slack space (the portion of the layout box
+ * not covered by the rendered content) should be distributed between the
+ * leading and trailing edges. `0` aligns to the left/top, `1` to the
+ * right/bottom, `0.5` (the default) centers the content.
+ */
+function parseObjectPosition(css: string | undefined): { x: number; y: number } {
+  if (!css || !css.trim()) return { x: 0.5, y: 0.5 };
+  const tokens = css.trim().split(/\s+/);
+  if (tokens.length === 1) {
+    const single = tokens[0] ?? "";
+    const v = parseObjectPositionAxis(single, "x");
+    return { x: v, y: 0.5 };
+  }
+  return {
+    x: parseObjectPositionAxis(tokens[0] ?? "", "x"),
+    y: parseObjectPositionAxis(tokens[1] ?? "", "y"),
+  };
+}
+
+/**
+ * Compute the rendered rectangle for an `object-fit` value.
+ *
+ * Returns the destination box (`dx`, `dy`, `dw`, `dh`) where the source image
+ * lands inside the layout box. For `cover` the rectangle extends past the
+ * layout box on the crop axis; the resampler clamps that overflow to the
+ * destination buffer bounds.
+ */
+function computeObjectFitRect(
+  srcW: number,
+  srcH: number,
+  dstW: number,
+  dstH: number,
+  fit: ObjectFit,
+  pos: { x: number; y: number },
+): { dx: number; dy: number; dw: number; dh: number } {
+  let renderedW = dstW;
+  let renderedH = dstH;
+  if (fit === "fill") {
+    return { dx: 0, dy: 0, dw: dstW, dh: dstH };
+  }
+  if (fit === "none") {
+    renderedW = srcW;
+    renderedH = srcH;
+  } else if (fit === "scale-down") {
+    // Pick the smaller of `none` and `contain` rendered sizes.
+    const scale = Math.min(dstW / srcW, dstH / srcH, 1);
+    renderedW = srcW * scale;
+    renderedH = srcH * scale;
+  } else if (fit === "cover") {
+    const scale = Math.max(dstW / srcW, dstH / srcH);
+    renderedW = srcW * scale;
+    renderedH = srcH * scale;
+  } else {
+    // contain
+    const scale = Math.min(dstW / srcW, dstH / srcH);
+    renderedW = srcW * scale;
+    renderedH = srcH * scale;
+  }
+  const dx = (dstW - renderedW) * pos.x;
+  const dy = (dstH - renderedH) * pos.y;
+  return { dx, dy, dw: renderedW, dh: renderedH };
+}
+
+/**
+ * Resample an `rgb48le` image buffer into a destination box of `dstW × dstH`,
+ * honoring CSS `object-fit` and `object-position` semantics.
+ *
+ * Used at HDR-image setup so the per-frame blit can treat the buffer as if it
+ * were sized to the element's layout box, mirroring how browsers render
+ * `<img object-fit:…>` for SDR content. Pixels that fall outside the rendered
+ * rectangle (the letterboxed/pillarboxed area for `contain` and `none`) are
+ * filled with opaque black, matching the default background for replaced
+ * elements without a transparent canvas.
+ *
+ * Sampling is bilinear, which is what `blitRgb48leAffine` already uses for
+ * its on-canvas affine scale, so a one-time resample here matches the visual
+ * quality the rest of the pipeline produces.
+ *
+ * Returns the source buffer unchanged when `dstW === srcW && dstH === srcH`
+ * and `fit === "fill"`, so callers can call this unconditionally without
+ * paying for an unnecessary copy.
+ */
+export function resampleRgb48leObjectFit(
+  source: Buffer,
+  srcW: number,
+  srcH: number,
+  dstW: number,
+  dstH: number,
+  fit: ObjectFit = "fill",
+  objectPosition?: string,
+): Buffer {
+  if (srcW <= 0 || srcH <= 0 || dstW <= 0 || dstH <= 0) {
+    return source;
+  }
+  if (fit === "fill" && srcW === dstW && srcH === dstH) {
+    return source;
+  }
+
+  const pos = parseObjectPosition(objectPosition);
+  const rect = computeObjectFitRect(srcW, srcH, dstW, dstH, fit, pos);
+  const dst = Buffer.alloc(dstW * dstH * 6); // pre-zeroed → opaque black background
+
+  const stride = dstW * 6;
+  // For each destination pixel that lies inside the rendered rect, sample
+  // the source bilinearly. Pixels outside the rect are left as the
+  // pre-zeroed black background (letterbox/pillarbox area).
+  const xMin = Math.max(0, Math.floor(rect.dx));
+  const yMin = Math.max(0, Math.floor(rect.dy));
+  const xMax = Math.min(dstW, Math.ceil(rect.dx + rect.dw));
+  const yMax = Math.min(dstH, Math.ceil(rect.dy + rect.dh));
+
+  if (rect.dw <= 0 || rect.dh <= 0) {
+    return dst;
+  }
+
+  const invScaleX = srcW / rect.dw;
+  const invScaleY = srcH / rect.dh;
+
+  for (let dy = yMin; dy < yMax; dy++) {
+    const rowOff = dy * stride;
+    const sy = (dy + 0.5 - rect.dy) * invScaleY - 0.5;
+    const syc = Math.max(0, Math.min(srcH - 1, sy));
+    const y0 = Math.floor(syc);
+    const y1 = Math.min(y0 + 1, srcH - 1);
+    const fy = syc - y0;
+    const ify = 1 - fy;
+
+    for (let dx = xMin; dx < xMax; dx++) {
+      const sx = (dx + 0.5 - rect.dx) * invScaleX - 0.5;
+      const sxc = Math.max(0, Math.min(srcW - 1, sx));
+      const x0 = Math.floor(sxc);
+      const x1 = Math.min(x0 + 1, srcW - 1);
+      const fx = sxc - x0;
+      const ifx = 1 - fx;
+
+      const off00 = (y0 * srcW + x0) * 6;
+      const off10 = (y0 * srcW + x1) * 6;
+      const off01 = (y1 * srcW + x0) * 6;
+      const off11 = (y1 * srcW + x1) * 6;
+
+      const w00 = ifx * ify;
+      const w10 = fx * ify;
+      const w01 = ifx * fy;
+      const w11 = fx * fy;
+
+      const r =
+        source.readUInt16LE(off00) * w00 +
+        source.readUInt16LE(off10) * w10 +
+        source.readUInt16LE(off01) * w01 +
+        source.readUInt16LE(off11) * w11;
+      const g =
+        source.readUInt16LE(off00 + 2) * w00 +
+        source.readUInt16LE(off10 + 2) * w10 +
+        source.readUInt16LE(off01 + 2) * w01 +
+        source.readUInt16LE(off11 + 2) * w11;
+      const b =
+        source.readUInt16LE(off00 + 4) * w00 +
+        source.readUInt16LE(off10 + 4) * w10 +
+        source.readUInt16LE(off01 + 4) * w01 +
+        source.readUInt16LE(off11 + 4) * w11;
+
+      const dstOff = rowOff + dx * 6;
+      dst.writeUInt16LE(Math.round(r), dstOff);
+      dst.writeUInt16LE(Math.round(g), dstOff + 2);
+      dst.writeUInt16LE(Math.round(b), dstOff + 4);
+    }
+  }
+
+  return dst;
+}
+
+/**
+ * Coerce a CSS `object-fit` value to the supported subset. Anything else
+ * (including `inherit`, `initial`, the empty string, or vendor-prefixed
+ * values) collapses to `"fill"` — the CSS default for replaced elements.
+ */
+export function normalizeObjectFit(value: string | undefined): ObjectFit {
+  switch ((value ?? "").trim().toLowerCase()) {
+    case "cover":
+      return "cover";
+    case "contain":
+      return "contain";
+    case "none":
+      return "none";
+    case "scale-down":
+      return "scale-down";
+    default:
+      return "fill";
+  }
+}
+
 /**
  * Parse a CSS `matrix(a,b,c,d,e,f)` string into a 6-element array.
  * Returns null for "none", empty, or unsupported formats (matrix3d).