@hyperframes/engine 0.5.5 → 0.6.0-alpha.2

package/src/services/videoFrameInjector.ts

@@ -15,91 +15,28 @@ import { type BeforeCaptureHook } from "./frameCapture.js";
 import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
 
 export interface VideoFrameInjectorOptions extends Partial<
-  Pick<EngineConfig, "frameDataUriCacheLimit" | "frameDataUriCacheBytesLimitMb">
+  Pick<EngineConfig, "frameDataUriCacheLimit">
 > {
   frameSrcResolver?: (framePath: string) => string | null;
 }
 
-interface FrameSourceCacheStats {
-  entries: number;
-  bytes: number;
-  /** Total entries evicted since cache creation. A high count vs a small
-   * composition signals the byte budget is too tight (cache thrash). */
-  evictions: number;
-  /** Total inserts rejected because the entry alone exceeds bytesLimit.
-   * Non-zero means a single frame is bigger than the configured budget —
-   * raise `frameDataUriCacheBytesLimitMb` if it recurs in production. */
-  oversizedRejections: number;
-}
-
-interface FrameSourceCache {
-  get: (framePath: string) => Promise<string>;
-  /** Exposed for tests + telemetry; reflects current cache occupancy. */
-  stats: () => FrameSourceCacheStats;
-}
-
-/**
- * Two-bound LRU keyed by frame path. Either bound triggers eviction of the
- * oldest entry — entry count protects against pathological many-tiny-frames
- * cases, and the byte budget keeps memory bounded when the per-frame data
- * URI grows (4K PNG frames are ~33 MB once base64-encoded).
- *
- * If a single entry's data URI exceeds `bytesLimit`, we skip caching it
- * (returning the URI directly to the caller). Without this guard, the
- * post-insert eviction loop would drop the entry we just inserted and the
- * cache would degrade into a CPU hot path — every subsequent `get()` would
- * re-read from disk and re-base64 the same frame.
- *
- * **Invariant**: cached values MUST be strings whose `.length` equals the
- * byte count we account for at insertion. We derive size on demand via
- * `cache.get(key)?.length` rather than maintaining a parallel `Map<string, number>`.
- * If you ever wrap the value (e.g. cache a Buffer or an object), the byte
- * accounting silently breaks — switch to a parallel size map first.
- */
 function createFrameSourceCache(
-  entryLimit: number,
-  bytesLimit: number,
+  cacheLimit: number,
   frameSrcResolver?: (framePath: string) => string | null,
-): FrameSourceCache {
+) {
   const cache = new Map<string, string>();
   const inFlight = new Map<string, Promise<string>>();
-  let totalBytes = 0;
-  let evictions = 0;
-  let oversizedRejections = 0;
-
-  function evictOldest(): void {
-    const oldestKey = cache.keys().next().value;
-    if (!oldestKey) return;
-    // Snapshot the value before deleting so the byte-size derivation can't
-    // accidentally read post-delete (a future reorder would silently lose
-    // accounting and surface as `totalBytes` drifting out of sync).
-    const dropped = cache.get(oldestKey);
-    cache.delete(oldestKey);
-    totalBytes = Math.max(0, totalBytes - (dropped?.length ?? 0));
-    evictions++;
-  }
 
   function remember(framePath: string, dataUri: string): string {
-    // Skip caching entries that alone exceed the byte budget. Caching them
-    // would trigger immediate self-eviction on insert and pollute LRU order
-    // by displacing the previous entry's slot.
-    if (dataUri.length > bytesLimit) {
-      oversizedRejections++;
-      // Drop any stale prior version so the caller sees consistent state.
-      if (cache.has(framePath)) {
-        totalBytes = Math.max(0, totalBytes - (cache.get(framePath)?.length ?? 0));
-        cache.delete(framePath);
-      }
-      return dataUri;
-    }
     if (cache.has(framePath)) {
-      totalBytes = Math.max(0, totalBytes - (cache.get(framePath)?.length ?? 0));
       cache.delete(framePath);
     }
     cache.set(framePath, dataUri);
-    totalBytes += dataUri.length;
-    while ((cache.size > entryLimit || totalBytes > bytesLimit) && cache.size > 0) {
-      evictOldest();
+    if (cache.size > cacheLimit) {
+      const oldestKey = cache.keys().next().value;
+      if (oldestKey) {
+        cache.delete(oldestKey);
+      }
     }
     return dataUri;
   }
@@ -133,19 +70,9 @@ function createFrameSourceCache(
     return pending;
   }
 
-  return {
-    get,
-    stats: () => ({
-      entries: cache.size,
-      bytes: totalBytes,
-      evictions,
-      oversizedRejections,
-    }),
-  };
+  return { get };
 }
 
-export const __testing = { createFrameSourceCache };
-
 /**
  * Creates a BeforeCaptureHook that injects pre-extracted video frames
  * into the page, replacing native <video> elements with frame images.
@@ -156,16 +83,11 @@ export function createVideoFrameInjector(
 ): BeforeCaptureHook | null {
   if (!frameLookup) return null;
 
-  const entryLimit = Math.max(
+  const cacheLimit = Math.max(
     32,
     config?.frameDataUriCacheLimit ?? DEFAULT_CONFIG.frameDataUriCacheLimit,
   );
-  const bytesLimitMb = Math.max(
-    64,
-    config?.frameDataUriCacheBytesLimitMb ?? DEFAULT_CONFIG.frameDataUriCacheBytesLimitMb,
-  );
-  const bytesLimit = bytesLimitMb * 1024 * 1024;
-  const frameCache = createFrameSourceCache(entryLimit, bytesLimit, config?.frameSrcResolver);
+  const frameCache = createFrameSourceCache(cacheLimit, config?.frameSrcResolver);
   const lastInjectedFrameByVideo = new Map<string, number>();
 
   return async (page: Page, time: number) => {

package/src/utils/alphaBlit.test.ts

@@ -511,16 +511,6 @@ describe("blitRgba8OverRgb48le", () => {
     expect(canvas.readUInt16LE(4)).toBe(0);
   });
 
-  it("fully opaque DOM with srgb transfer expands 8-bit channels to 16-bit SDR", () => {
-    const canvas = makeHdrFrame(1, 1, 10000, 20000, 30000);
-    const dom = makeDomRgba(1, 1, 255, 128, 1, 255);
-    blitRgba8OverRgb48le(dom, canvas, 1, 1, "srgb");
-
-    expect(canvas.readUInt16LE(0)).toBe(65535);
-    expect(canvas.readUInt16LE(2)).toBe(128 * 257);
-    expect(canvas.readUInt16LE(4)).toBe(257);
-  });
-
   it("sRGB→HLG: black stays black, white stays white", () => {
     const canvasBlack = makeHdrFrame(1, 1, 0, 0, 0);
     const domBlack = makeDomRgba(1, 1, 0, 0, 0, 255);

package/src/utils/alphaBlit.ts

@@ -249,7 +249,7 @@ export function decodePngToRgb48le(buf: Buffer): { width: number; height: number
  * bt2020). For neutral/near-neutral content (text, UI) the gamut difference
  * is negligible.
  */
-function buildSrgbToSignalLut(transfer: "hlg" | "pq" | "srgb"): Uint16Array {
+function buildSrgbToHdrLut(transfer: "hlg" | "pq"): Uint16Array {
   const lut = new Uint16Array(256);
 
   // HLG OETF constants (Rec. 2100)
@@ -267,11 +267,6 @@ function buildSrgbToSignalLut(transfer: "hlg" | "pq" | "srgb"): Uint16Array {
   const sdrNits = 203.0;
 
   for (let i = 0; i < 256; i++) {
-    if (transfer === "srgb") {
-      lut[i] = i * 257;
-      continue;
-    }
-
     // sRGB EOTF: signal → linear (range 0–1, relative to SDR white)
     const v = i / 255;
     const linear = v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
@@ -293,15 +288,12 @@ function buildSrgbToSignalLut(transfer: "hlg" | "pq" | "srgb"): Uint16Array {
   return lut;
 }
 
-const SRGB_TO_SRGB_16 = buildSrgbToSignalLut("srgb");
-const SRGB_TO_HLG = buildSrgbToSignalLut("hlg");
-const SRGB_TO_PQ = buildSrgbToSignalLut("pq");
+const SRGB_TO_HLG = buildSrgbToHdrLut("hlg");
+const SRGB_TO_PQ = buildSrgbToHdrLut("pq");
 
 /** Select the correct sRGB→HDR LUT for the given transfer function. */
-function getSrgbToSignalLut(transfer: "hlg" | "pq" | "srgb"): Uint16Array {
-  if (transfer === "pq") return SRGB_TO_PQ;
-  if (transfer === "hlg") return SRGB_TO_HLG;
-  return SRGB_TO_SRGB_16;
+function getSrgbToHdrLut(transfer: "hlg" | "pq"): Uint16Array {
+  return transfer === "pq" ? SRGB_TO_PQ : SRGB_TO_HLG;
 }
 
 // ── Alpha compositing ─────────────────────────────────────────────────────────
@@ -325,10 +317,10 @@ export function blitRgba8OverRgb48le(
   canvas: Buffer,
   width: number,
   height: number,
-  transfer: "hlg" | "pq" | "srgb" = "hlg",
+  transfer: "hlg" | "pq" = "hlg",
 ): void {
   const pixelCount = width * height;
-  const lut = getSrgbToSignalLut(transfer);
+  const lut = getSrgbToHdrLut(transfer);
 
   for (let i = 0; i < pixelCount; i++) {
     const da = domRgba[i * 4 + 3] ?? 0;

package/src/utils/ffprobe.test.ts

@@ -225,46 +225,6 @@ describe("ffprobe missing-binary fallback", () => {
     expect(meta.hasAlpha).toBe(true);
   });
 
-  // Regression: newer libavformat builds (and the output of `hyperframes
-  // remove-background` itself) write the VP9-alpha sidecar tag as
-  // `ALPHA_MODE` (uppercase). The lowercase-only check classified those
-  // files as having no alpha, the producer extracted them as JPGs, and
-  // the injected <img> overlays were fully opaque rectangles that hid
-  // every static element below them on the z-stack. The bug was silent —
-  // studio preview rendered correctly via native <video> playback while
-  // production renders covered headlines and captions with the avatar.
-  it("extractMediaMetadata detects ALPHA_MODE (uppercase) streams from newer ffmpeg builds", async () => {
-    const { spawn } = createSpawnSpy([
-      {
-        kind: "exit",
-        code: 0,
-        stdout: JSON.stringify({
-          streams: [
-            {
-              codec_type: "video",
-              codec_name: "vp9",
-              width: 320,
-              height: 180,
-              r_frame_rate: "30/1",
-              avg_frame_rate: "30/1",
-              pix_fmt: "yuv420p",
-              tags: { ALPHA_MODE: "1" },
-            },
-          ],
-          format: { duration: "1.5" },
-        }),
-      },
-    ]);
-    vi.resetModules();
-    vi.doMock("child_process", () => ({ spawn }));
-
-    const { extractMediaMetadata: extractMediaMetadataMocked } = await import("./ffprobe.js");
-    const meta = await extractMediaMetadataMocked("/tmp/alpha-uppercase.webm");
-
-    expect(meta.videoCodec).toBe("vp9");
-    expect(meta.hasAlpha).toBe(true);
-  });
-
   it("extractMediaMetadata rethrows ffprobe-missing error for non-image files without fallback", async () => {
     const { spawn } = createSpawnSpy([{ kind: "missing" }]);
     vi.resetModules();

package/src/utils/ffprobe.ts

@@ -203,21 +203,6 @@ function extractStillImageMetadata(filePath: string): StillImageMetadata | null
   }
 }
 
-/**
- * Read an ffprobe tag case-insensitively. ffmpeg/libavformat versions disagree
- * on tag casing — VP9 alpha is `alpha_mode` in older builds and `ALPHA_MODE`
- * in newer ones; HDR tags vary similarly. Use this for any sidecar tag where
- * you want to be resilient across muxer versions.
- */
-function readTagCI(tags: Record<string, string | undefined> | undefined, name: string): string {
-  if (!tags) return "";
-  const target = name.toLowerCase();
-  for (const [key, value] of Object.entries(tags)) {
-    if (key.toLowerCase() === target && typeof value === "string") return value;
-  }
-  return "";
-}
-
 function parseFrameRate(frameRateStr: string | undefined): number {
   if (!frameRateStr) return 0;
   const parts = frameRateStr.split("/");
@@ -292,7 +277,7 @@ export async function extractMediaMetadata(filePath: string): Promise<VideoMetad
         : null;
     const colorSpace = ffprobeColorSpace ?? stillImageMeta?.colorSpace ?? null;
     const pixelFormat = videoStream.pix_fmt || "";
-    const alphaMode = readTagCI(videoStream.tags, "alpha_mode");
+    const alphaMode = videoStream.tags?.alpha_mode || "";
     const hasAlpha =
       /(^|[^a-z])yuva|rgba|argb|bgra|gbrap|gray[a-z0-9]*a/i.test(pixelFormat) || alphaMode === "1";
 

package/src/services/screenshotService.test.ts

@@ -1,92 +0,0 @@
-// @vitest-environment node
-import { describe, it, expect, vi } from "vitest";
-import { type Page } from "puppeteer-core";
-import { pageScreenshotCapture, cdpSessionCache } from "./screenshotService.js";
-
-// Stub a Page + CDPSession just enough that pageScreenshotCapture can call
-// `client.send("Page.captureScreenshot", ...)` and we can inspect the args.
-function makeFakePageWithCdp(send: (method: string, params: object) => Promise<{ data: string }>) {
-  const fakeSession = { send } as unknown as import("puppeteer-core").CDPSession;
-  // Stub a Page object — the WeakMap cache is the only Page-thing used in the
-  // path under test, so we can pre-seed it and skip page.createCDPSession().
-  const fakePage = {} as Page;
-  cdpSessionCache.set(fakePage, fakeSession);
-  return fakePage;
-}
-
-describe("pageScreenshotCapture supersample plumbing", () => {
-  // Minimal 1×1 transparent PNG, base64. The function returns Buffer.from(data, "base64")
-  // and we never inspect the bytes — only the params we pass to client.send.
-  const ONE_PIXEL_PNG_B64 =
-    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkAAIAAAoAAv/lxKUAAAAASUVORK5CYII=";
-
-  it("omits `clip` when deviceScaleFactor is undefined (default 1)", async () => {
-    const send = vi.fn().mockResolvedValue({ data: ONE_PIXEL_PNG_B64 });
-    const page = makeFakePageWithCdp(send);
-
-    await pageScreenshotCapture(page, {
-      width: 1920,
-      height: 1080,
-      fps: 30,
-      format: "jpeg",
-      quality: 80,
-    });
-
-    expect(send).toHaveBeenCalledWith(
-      "Page.captureScreenshot",
-      expect.not.objectContaining({ clip: expect.anything() }),
-    );
-  });
-
-  it("omits `clip` when deviceScaleFactor is exactly 1", async () => {
-    const send = vi.fn().mockResolvedValue({ data: ONE_PIXEL_PNG_B64 });
-    const page = makeFakePageWithCdp(send);
-
-    await pageScreenshotCapture(page, {
-      width: 1920,
-      height: 1080,
-      fps: 30,
-      format: "jpeg",
-      deviceScaleFactor: 1,
-    });
-
-    const params = send.mock.calls[0]?.[1] as { clip?: unknown };
-    expect(params.clip).toBeUndefined();
-  });
-
-  it("passes `clip` with `scale = dpr` when deviceScaleFactor > 1 (the supersample contract)", async () => {
-    const send = vi.fn().mockResolvedValue({ data: ONE_PIXEL_PNG_B64 });
-    const page = makeFakePageWithCdp(send);
-
-    await pageScreenshotCapture(page, {
-      width: 1920,
-      height: 1080,
-      fps: 30,
-      format: "jpeg",
-      deviceScaleFactor: 2,
-    });
-
-    expect(send).toHaveBeenCalledWith(
-      "Page.captureScreenshot",
-      expect.objectContaining({
-        clip: { x: 0, y: 0, width: 1920, height: 1080, scale: 2 },
-      }),
-    );
-  });
-
-  it("propagates a non-2 supersample factor (e.g. 720p → 4K = 3×)", async () => {
-    const send = vi.fn().mockResolvedValue({ data: ONE_PIXEL_PNG_B64 });
-    const page = makeFakePageWithCdp(send);
-
-    await pageScreenshotCapture(page, {
-      width: 1280,
-      height: 720,
-      fps: 30,
-      format: "jpeg",
-      deviceScaleFactor: 3,
-    });
-
-    const params = send.mock.calls[0]?.[1] as { clip?: { scale: number } };
-    expect(params.clip?.scale).toBe(3);
-  });
-});

package/src/services/videoFrameInjector.test.ts

@@ -1,145 +0,0 @@
-// @vitest-environment node
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { __testing } from "./videoFrameInjector.js";
-import { DEFAULT_CONFIG } from "../config.js";
-
-const { createFrameSourceCache } = __testing;
-
-const SHARED_STATS = { evictions: 0, oversizedRejections: 0 };
-
-describe("frame source cache eviction", () => {
-  let dir: string;
-
-  beforeEach(() => {
-    dir = mkdtempSync(join(tmpdir(), "hf-frame-cache-test-"));
-  });
-
-  afterEach(() => {
-    rmSync(dir, { recursive: true, force: true });
-  });
-
-  // Each PNG is base64-encoded into the data URI, so the cached string is
-  // ~4/3 the file size plus a small `data:image/png;base64,` prefix. Build
-  // distinct files so eviction has predictable victims.
-  function writeFrame(name: string, sizeBytes: number): string {
-    const filePath = join(dir, name);
-    writeFileSync(filePath, Buffer.alloc(sizeBytes, 0));
-    return filePath;
-  }
-
-  it("evicts oldest entry when entry count exceeds limit", async () => {
-    const cache = createFrameSourceCache(2, Number.MAX_SAFE_INTEGER);
-    const a = writeFrame("a.png", 16);
-    const b = writeFrame("b.png", 16);
-    const c = writeFrame("c.png", 16);
-
-    await cache.get(a);
-    await cache.get(b);
-    expect(cache.stats().entries).toBe(2);
-
-    await cache.get(c);
-    expect(cache.stats().entries).toBe(2);
-    expect(cache.stats().evictions).toBe(1);
-
-    // Verify the *oldest* entry (a) was the victim — the LRU contract.
-    // A later get(a) is a miss-then-insert, which would also evict whichever
-    // entry is now oldest. We instrument the eviction counter to detect it.
-    const evictionsBefore = cache.stats().evictions;
-    await cache.get(a);
-    expect(cache.stats().evictions).toBe(evictionsBefore + 1);
-    // After re-inserting `a`, `b` is the next oldest. `c` is now newest.
-    // Touch `b` (move-to-front) → next eviction would be `c`, not `b`.
-  });
-
-  it("evicts oldest entry when byte budget is exceeded", async () => {
-    // 1 KB raw frame → ~1.4 KB base64 + ~22-byte data URI prefix. Pick a
-    // budget that comfortably fits two URIs but not three, so the third
-    // get() forces eviction even though the entry-count cap (100) is far
-    // from the limit.
-    const cache = createFrameSourceCache(100, 4 * 1024);
-    const a = writeFrame("a.png", 1024);
-    const b = writeFrame("b.png", 1024);
-    const c = writeFrame("c.png", 1024);
-
-    await cache.get(a);
-    await cache.get(b);
-    expect(cache.stats().entries).toBe(2);
-
-    await cache.get(c);
-    const afterC = cache.stats();
-    // The byte budget is the contract — the cache MUST stay under it after
-    // an insert that would otherwise overflow. Entry count is incidental.
-    expect(afterC.bytes).toBeLessThanOrEqual(4 * 1024);
-    expect(afterC.entries).toBeLessThan(3);
-  });
-
-  it("returns the served URL untouched when frameSrcResolver yields one", async () => {
-    let served: string | null = "/served/frame.png";
-    const cache = createFrameSourceCache(4, 64 * 1024, () => served);
-    const file = writeFrame("a.png", 256);
-
-    expect(await cache.get(file)).toBe("/served/frame.png");
-    // Cache stays empty because the resolver short-circuits the read.
-    expect(cache.stats()).toMatchObject({ entries: 0, bytes: 0 });
-
-    served = null;
-    const dataUri = await cache.get(file);
-    expect(dataUri.startsWith("data:image/png;base64,")).toBe(true);
-    expect(cache.stats().entries).toBe(1);
-  });
-
-  it("treats a re-read as a cache hit (no second file read)", async () => {
-    const cache = createFrameSourceCache(2, Number.MAX_SAFE_INTEGER);
-    const a = writeFrame("a.png", 64);
-
-    const first = await cache.get(a);
-    const second = await cache.get(a);
-    expect(second).toBe(first);
-    expect(cache.stats().entries).toBe(1);
-  });
-
-  it("skips caching an entry that alone exceeds the byte budget (no self-eviction)", async () => {
-    // 64 KB raw → ~88 KB base64 + prefix. Budget of 32 KB rejects this entry.
-    // The contract: caller still gets the data URI; cache stays empty so
-    // future inserts aren't blocked by the rejected entry's bookkeeping.
-    const cache = createFrameSourceCache(100, 32 * 1024);
-    const big = writeFrame("big.png", 64 * 1024);
-
-    const dataUri = await cache.get(big);
-    expect(dataUri.startsWith("data:image/png;base64,")).toBe(true);
-    expect(cache.stats().entries).toBe(0);
-    expect(cache.stats().bytes).toBe(0);
-    expect(cache.stats().oversizedRejections).toBe(1);
-    expect(cache.stats().evictions).toBe(0);
-
-    // A subsequent normal-sized entry must cache cleanly — the rejection
-    // path didn't pollute internal state.
-    const small = writeFrame("small.png", 1024);
-    await cache.get(small);
-    expect(cache.stats().entries).toBe(1);
-  });
-
-  it("at the production default (1500 MB), 1080p frames stay cached", async () => {
-    // Regression for the post-PR-#662 default: previously the cache held up
-    // to 256 entries × ~8 MB ≈ 2 GB at 1080p. The new byte-budget default of
-    // 1500 MB caps it tighter (~187 entries at 1080p ≈ 6s @ 30fps). This
-    // test pins the math so a future tweak to the default is visible.
-    const oneEightyP_jpegSize = 8 * 1024 * 1024; // ~8 MB JPEG (data URI)
-    const defaultBytesLimit = DEFAULT_CONFIG.frameDataUriCacheBytesLimitMb * 1024 * 1024;
-    const expectedMaxEntries = Math.floor(defaultBytesLimit / oneEightyP_jpegSize);
-    expect(expectedMaxEntries).toBeGreaterThanOrEqual(180);
-    expect(expectedMaxEntries).toBeLessThanOrEqual(200);
-    // At 30fps that's at least 6 seconds of look-ahead. Sequential access is
-    // strictly cheaper, so the cache helps any seek-back ≤ 6s.
-    expect(expectedMaxEntries / 30).toBeGreaterThanOrEqual(6);
-  });
-
-  // Suppress unused-import warning when the SHARED_STATS sentinel is dropped.
-  it("stats() exposes counters used by telemetry", async () => {
-    const cache = createFrameSourceCache(1, Number.MAX_SAFE_INTEGER);
-    expect(cache.stats()).toMatchObject({ ...SHARED_STATS, entries: 0, bytes: 0 });
-  });
-});