@hyperframes/engine 0.6.118 → 0.6.120

package/package.json

@@ -1,19 +1,36 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.6.118",
+  "version": "0.6.120",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
     "url": "https://github.com/heygen-com/hyperframes",
     "directory": "packages/engine"
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./alpha-blit": "./src/utils/alphaBlit.ts",
-    "./shader-transitions": "./src/utils/shaderTransitions.ts"
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./alpha-blit": {
+      "import": "./dist/utils/alphaBlit.js",
+      "types": "./dist/utils/alphaBlit.d.ts"
+    },
+    "./shader-transitions": {
+      "import": "./dist/utils/shaderTransitions.js",
+      "types": "./dist/utils/shaderTransitions.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
     "@hono/node-server": "^1.13.0",
@@ -21,7 +38,7 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^24.0.0",
     "puppeteer-core": "^24.39.1",
-    "@hyperframes/core": "^0.6.118"
+    "@hyperframes/core": "^0.6.120"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",

package/scripts/generate-lut-reference.py

@@ -1,168 +0,0 @@
-#!/usr/bin/env python3
-"""
-Regenerate the sRGB → BT.2020 (HLG/PQ) LUT reference values pinned by
-packages/engine/src/utils/alphaBlit.test.ts.
-
-This is a paste-helper for the *very rare* case the LUT genuinely needs to
-shift — e.g. a spec update changes one of the OETF constants, or we change
-the SDR-white reference level in the PQ branch. The reference values in
-alphaBlit.test.ts are byte-exact integers, and updating ~12 hand-edited
-literals (or all 256 of them, if the test grows) is exactly the kind of
-mechanical churn we want to keep out of the diff.
-
-Usage:
-    # Regenerate the probe table that lives in alphaBlit.test.ts (paste over
-    # the SRGB_TO_HDR_REFERENCE literal):
-    python3 packages/engine/scripts/generate-lut-reference.py --probes
-
-    # Dump the full 256-entry LUTs as JSON (for ad-hoc analysis or new tests):
-    python3 packages/engine/scripts/generate-lut-reference.py
-
-    # Override the probe set:
-    python3 packages/engine/scripts/generate-lut-reference.py --probes \
-        --probe-indices 0,32,64,128,192,255
-
-## How to use this when the LUT changes
-
-1. Edit buildSrgbToHdrLut() in packages/engine/src/utils/alphaBlit.ts.
-2. Mirror the same edit here (constants, branch logic — keep them in sync).
-3. Run with --probes and paste the output over SRGB_TO_HDR_REFERENCE in
-   alphaBlit.test.ts. Update the asymmetric-R/G/B and BT.2408-invariant
-   tests by hand if those probe values shifted.
-4. Re-run `bun test src/utils/alphaBlit.test.ts` to confirm the engine LUT
-   and the test-pinned values still agree.
-
-## Why Python (not TS)?
-
-A standalone script avoids dragging the engine's bun/Node/build environment
-into a one-off codegen flow, and matches the existing fixture-generation
-pattern at packages/producer/tests/hdr-regression/scripts/generate-hdr-photo-pq.py.
-Python's math.log / math.pow are libm-backed and produce IEEE-754-equivalent
-results to JS's Math.log / Math.pow for these inputs — see js_round_nonneg
-below for the one rounding quirk we have to match by hand.
-
-## Drift contract
-
-This file MIRRORS buildSrgbToHdrLut() in alphaBlit.ts. If the two diverge,
-this script silently emits wrong values. Any change to one MUST be reflected
-in the other; run the script and the test suite together to catch drift.
-"""
-
-import argparse
-import json
-import math
-import sys
-from collections.abc import Iterable
-
-# HLG OETF constants (Rec. 2100) — keep in sync with alphaBlit.ts
-HLG_A = 0.17883277
-HLG_B = 1 - 4 * HLG_A
-HLG_C = 0.5 - HLG_A * math.log(4 * HLG_A)
-
-# PQ (SMPTE 2084) OETF constants — keep in sync with alphaBlit.ts
-PQ_M1 = 0.1593017578125
-PQ_M2 = 78.84375
-PQ_C1 = 0.8359375
-PQ_C2 = 18.8515625
-PQ_C3 = 18.6875
-PQ_MAX_NITS = 10000.0
-SDR_NITS = 203.0  # BT.2408 SDR-reference white in PQ
-
-
-def js_round_nonneg(x: float) -> int:
-    """
-    Match JS Math.round semantics for non-negative inputs.
-
-    JS Math.round rounds half toward +∞ (Math.round(0.5) === 1). Python's
-    built-in round() uses banker's rounding (round half to even, so
-    round(0.5) === 0 and round(2.5) === 2), which would diverge from
-    Math.round for the ~ten or so probe values that fall on a half-integer
-    after signal*65535. This helper is only correct for x >= 0 — that's
-    fine because signal is always in [0, 1] here.
-    """
-    return int(math.floor(x + 0.5))
-
-
-def srgb_eotf(i: int) -> float:
-    """sRGB 8-bit code value → linear light in [0, 1] relative to SDR white."""
-    v = i / 255
-    return v / 12.92 if v <= 0.04045 else math.pow((v + 0.055) / 1.055, 2.4)
-
-
-def hlg_oetf(linear: float) -> float:
-    if linear <= 1 / 12:
-        return math.sqrt(3 * linear)
-    return HLG_A * math.log(12 * linear - HLG_B) + HLG_C
-
-
-def pq_oetf(linear: float) -> float:
-    # Place SDR-reference white at 203 nits within the 10000-nit PQ peak.
-    # This is what reserves headroom for HDR highlights above SDR-white.
-    lp = max(0.0, (linear * SDR_NITS) / PQ_MAX_NITS)
-    lm1 = math.pow(lp, PQ_M1)
-    return math.pow((PQ_C1 + PQ_C2 * lm1) / (1.0 + PQ_C3 * lm1), PQ_M2)
-
-
-def build_lut(transfer: str) -> list[int]:
-    out: list[int] = []
-    for i in range(256):
-        linear = srgb_eotf(i)
-        signal = hlg_oetf(linear) if transfer == "hlg" else pq_oetf(linear)
-        out.append(min(65535, js_round_nonneg(signal * 65535)))
-    return out
-
-
-# Mirror SRGB_TO_HDR_REFERENCE indices in alphaBlit.test.ts. Endpoints
-# (0, 1, 254, 255) catch off-by-one regressions; mid-range values (32, 64,
-# 96, 128, 160, 192, 224) sample the middle of both transfer curves.
-DEFAULT_PROBES: tuple[int, ...] = (0, 1, 10, 32, 64, 96, 128, 160, 192, 224, 254, 255)
-
-
-def emit_json(hlg: list[int], pq: list[int]) -> None:
-    print(json.dumps({"size": 256, "hlg": hlg, "pq": pq}, indent=2))
-
-
-def emit_probes(hlg: list[int], pq: list[int], probes: Iterable[int]) -> None:
-    # Output is paste-ready TS for SRGB_TO_HDR_REFERENCE in alphaBlit.test.ts.
-    print("const SRGB_TO_HDR_REFERENCE: readonly SrgbHdrProbe[] = [")
-    for i in probes:
-        if not 0 <= i <= 255:
-            raise ValueError(f"probe index {i} out of range [0, 255]")
-        print(f"  {{ srgb: {i}, hlg: {hlg[i]}, pq: {pq[i]} }},")
-    print("];")
-
-
-def parse_indices(s: str) -> list[int]:
-    return [int(x.strip()) for x in s.split(",") if x.strip()]
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(
-        description="Regenerate sRGB → BT.2020 (HLG/PQ) LUT reference values.",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-    )
-    parser.add_argument(
-        "--probes",
-        action="store_true",
-        help="Emit a TS snippet ready to paste over SRGB_TO_HDR_REFERENCE.",
-    )
-    parser.add_argument(
-        "--probe-indices",
-        type=parse_indices,
-        default=list(DEFAULT_PROBES),
-        help="Comma-separated probe indices (default mirrors alphaBlit.test.ts).",
-    )
-    args = parser.parse_args()
-
-    hlg = build_lut("hlg")
-    pq = build_lut("pq")
-
-    if args.probes:
-        emit_probes(hlg, pq, args.probe_indices)
-    else:
-        emit_json(hlg, pq)
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/scripts/test-fitTextFontSize-browser.ts

@@ -1,135 +0,0 @@
-/**
- * Browser integration test for fitTextFontSize.
- *
- * Launches headless Chrome, loads the runtime IIFE into a page,
- * and verifies that window.__hyperframes.fitTextFontSize produces
- * correct results with real canvas measureText.
- *
- * Requires: puppeteer (dep of @hyperframes/engine)
- * Run: cd packages/engine && npx tsx scripts/test-fitTextFontSize-browser.ts
- */
-
-import { buildHyperframesRuntimeScript } from "../../core/src/inline-scripts/hyperframesRuntime.engine";
-
-function assert(condition: unknown, message: string): void {
-  if (!condition) {
-    throw new Error(`FAIL: ${message}`);
-  }
-}
-
-async function main() {
-  // Dynamic import — puppeteer is a monorepo dep, not a core dep
-  let puppeteer;
-  try {
-    puppeteer = (await import("puppeteer")).default;
-  } catch {
-    console.log(
-      JSON.stringify({
-        event: "fitTextFontSize_browser_test_skipped",
-        reason: "puppeteer not available",
-      }),
-    );
-    return;
-  }
-
-  const runtimeSource = buildHyperframesRuntimeScript({ minify: false });
-  assert(
-    runtimeSource !== null,
-    "buildHyperframesRuntimeScript returned null — entry.ts not found",
-  );
-
-  const html = `<!DOCTYPE html>
-<html><head>
-<style>
-  @import url('https://fonts.googleapis.com/css2?family=Outfit:wght@900&display=block');
-</style>
-</head><body>
-<script>${runtimeSource}</script>
-<script>
-  window.__testResults = {};
-
-  // Test 1: Short text should fit at base size
-  var r1 = window.__hyperframes.fitTextFontSize("HI");
-  window.__testResults.shortText = r1;
-
-  // Test 2: Wide text should shrink below base size but still fit at 1600px
-  var r2 = window.__hyperframes.fitTextFontSize(
-    "CONGRATULATIONS TO EVERYBODY IN THE WORLD",
-    { fontFamily: "sans-serif", fontWeight: 900, maxWidth: 1600 }
-  );
-  window.__testResults.wideText = r2;
-
-  // Test 3: Extremely wide text that can't fit should return minFontSize
-  var r3 = window.__hyperframes.fitTextFontSize(
-    "WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW",
-    { fontFamily: "sans-serif", fontWeight: 900, maxWidth: 400 }
-  );
-  window.__testResults.extremeText = r3;
-
-  // Test 4: Function exists and is callable
-  window.__testResults.exists = typeof window.__hyperframes.fitTextFontSize === "function";
-</script>
-</body></html>`;
-
-  const browser = await puppeteer.launch({
-    headless: true,
-    args: ["--no-sandbox", "--disable-setuid-sandbox"],
-  });
-
-  try {
-    const page = await browser.newPage();
-    await page.setContent(html, { waitUntil: "networkidle0", timeout: 10000 });
-
-    // Wait for font to potentially load (best effort — sans-serif fallback is fine for testing)
-    await new Promise((r) => setTimeout(r, 1000));
-
-    const results = await page.evaluate(() => (window as any).__testResults);
-
-    // Test 1: Short text fits at base size (78px default)
-    assert(results.exists === true, "fitTextFontSize should exist on window.__hyperframes");
-    assert(
-      results.shortText.fits === true,
-      `Short text should fit, got fits=${results.shortText.fits}`,
-    );
-    assert(
-      results.shortText.fontSize === 78,
-      `Short text should use base size 78, got ${results.shortText.fontSize}`,
-    );
-
-    // Test 2: Wide text should shrink below base size
-    assert(
-      results.wideText.fits === true,
-      `Wide text should still fit, got fits=${results.wideText.fits}`,
-    );
-    assert(
-      results.wideText.fontSize < 78,
-      `Wide text should shrink below 78, got ${results.wideText.fontSize}`,
-    );
-
-    // Test 3: Extreme text should hit floor
-    assert(
-      results.extremeText.fontSize === 42,
-      `Extreme text should hit minFontSize 42, got ${results.extremeText.fontSize}`,
-    );
-    assert(
-      results.extremeText.fits === false,
-      `Extreme text should not fit, got fits=${results.extremeText.fits}`,
-    );
-
-    console.log(
-      JSON.stringify({
-        event: "fitTextFontSize_browser_test_passed",
-        shortText: results.shortText,
-        wideText: results.wideText,
-        extremeText: results.extremeText,
-      }),
-    );
-  } finally {
-    await browser.close();
-  }
-}
-
-main().catch((err) => {
-  console.error(err.message);
-  process.exit(1);
-});

package/src/cdp-headless-experimental.d.ts

@@ -1,54 +0,0 @@
-/**
- * Type augmentation for Chrome's HeadlessExperimental CDP domain.
- *
- * Puppeteer's CDPSession.send() is typed against devtools-protocol's
- * ProtocolMapping.Commands, which does not include HeadlessExperimental.
- * This module augmentation adds proper types so we can call these methods
- * without unsafe `as any` casts.
- */
-
-/** Parameters for HeadlessExperimental.beginFrame */
-interface HeadlessExperimentalBeginFrameRequest {
-  /** Timestamp in milliseconds since epoch for the frame */
-  frameTimeTicks: number;
-  /** Interval in milliseconds between frames */
-  interval: number;
-  /** If true, do not produce display updates (warmup mode) */
-  noDisplayUpdates?: boolean;
-  /** Optional screenshot configuration */
-  screenshot?: {
-    format: "jpeg" | "png";
-    quality?: number;
-    optimizeForSpeed?: boolean;
-  };
-}
-
-/** Response from HeadlessExperimental.beginFrame */
-interface HeadlessExperimentalBeginFrameResponse {
-  /** Whether the compositor reported visual damage */
-  hasDamage: boolean;
-  /** Base64-encoded screenshot data (present only when screenshot was requested and hasDamage is true) */
-  screenshotData?: string;
-}
-
-export {};
-
-declare module "devtools-protocol/types/protocol-mapping.js" {
-  // Merge into the existing ProtocolMapping namespace
-  export namespace ProtocolMapping {
-    interface Commands {
-      "HeadlessExperimental.enable": {
-        paramsType: [];
-        returnType: void;
-      };
-      "HeadlessExperimental.disable": {
-        paramsType: [];
-        returnType: void;
-      };
-      "HeadlessExperimental.beginFrame": {
-        paramsType: [HeadlessExperimentalBeginFrameRequest];
-        returnType: HeadlessExperimentalBeginFrameResponse;
-      };
-    }
-  }
-}

package/src/config.test.ts

@@ -1,213 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { resolveConfig, DEFAULT_CONFIG } from "./config.js";
-import { isLowMemorySystem } from "./services/systemMemory.js";
-
-describe("resolveConfig", () => {
-  const savedEnv = new Map<string, string | undefined>();
-
-  function setEnv(key: string, value: string) {
-    savedEnv.set(key, process.env[key]);
-    process.env[key] = value;
-  }
-
-  beforeEach(() => {
-    savedEnv.clear();
-  });
-
-  afterEach(() => {
-    for (const [key, value] of savedEnv) {
-      if (value === undefined) {
-        delete process.env[key];
-      } else {
-        process.env[key] = value;
-      }
-    }
-  });
-
-  it("returns defaults when no overrides or env vars are set", () => {
-    const config = resolveConfig();
-    expect(config.fps).toBe(30);
-    expect(config.quality).toBe("standard");
-    expect(config.format).toBe("jpeg");
-    expect(config.jpegQuality).toBe(80);
-    expect(config.browserGpuMode).toBe("software");
-    expect(config.enableStreamingEncode).toBe(true);
-    expect(config.streamingEncodeMaxDurationSeconds).toBe(240);
-    expect((config as Record<string, unknown>).vp9CpuUsed).toBe(4);
-    expect(config.audioGain).toBe(1);
-    expect(config.debug).toBe(false);
-  });
-
-  it("applies explicit overrides over defaults", () => {
-    const config = resolveConfig({ fps: 60, debug: true });
-    expect(config.fps).toBe(60);
-    expect(config.debug).toBe(true);
-    // Non-overridden fields remain at defaults
-    expect(config.quality).toBe("standard");
-  });
-
-  it("reads numeric env vars with PRODUCER_ prefix", () => {
-    setEnv("PRODUCER_MAX_WORKERS", "4");
-    setEnv("PRODUCER_CORES_PER_WORKER", "3");
-
-    const config = resolveConfig();
-    expect(config.concurrency).toBe(4);
-    expect(config.coresPerWorker).toBe(3);
-  });
-
-  it("reads boolean env vars (true/false strings)", () => {
-    setEnv("PRODUCER_DISABLE_GPU", "true");
-    setEnv("PRODUCER_ENABLE_BROWSER_POOL", "true");
-
-    const config = resolveConfig();
-    expect(config.disableGpu).toBe(true);
-    expect(config.enableBrowserPool).toBe(true);
-  });
-
-  it("lets env vars opt out of default streaming encode", () => {
-    setEnv("PRODUCER_ENABLE_STREAMING_ENCODE", "false");
-
-    const config = resolveConfig();
-    expect(config.enableStreamingEncode).toBe(false);
-  });
-
-  it("reads the streaming encode duration cutoff from env", () => {
-    setEnv("PRODUCER_STREAMING_ENCODE_MAX_DURATION_SECONDS", "120");
-
-    const config = resolveConfig();
-    expect(config.streamingEncodeMaxDurationSeconds).toBe(120);
-  });
-
-  it("clamps negative streaming encode duration cutoff env values to zero", () => {
-    setEnv("PRODUCER_STREAMING_ENCODE_MAX_DURATION_SECONDS", "-1");
-
-    const config = resolveConfig();
-    expect(config.streamingEncodeMaxDurationSeconds).toBe(0);
-  });
-
-  it("reads VP9 cpu-used from env", () => {
-    setEnv("PRODUCER_VP9_CPU_USED", "6");
-
-    const config = resolveConfig();
-    expect((config as Record<string, unknown>).vp9CpuUsed).toBe(6);
-  });
-
-  it("falls back to the VP9 cpu-used default for invalid env values", () => {
-    setEnv("PRODUCER_VP9_CPU_USED", "fast");
-
-    const config = resolveConfig();
-    expect((config as Record<string, unknown>).vp9CpuUsed).toBe(4);
-  });
-
-  it("clamps VP9 cpu-used env values to libvpx's supported range", () => {
-    setEnv("PRODUCER_VP9_CPU_USED", "99");
-    expect((resolveConfig() as Record<string, unknown>).vp9CpuUsed).toBe(8);
-
-    process.env.PRODUCER_VP9_CPU_USED = "-99";
-    expect((resolveConfig() as Record<string, unknown>).vp9CpuUsed).toBe(-8);
-  });
-
-  it("treats non-'true' boolean env vars as false", () => {
-    setEnv("PRODUCER_DISABLE_GPU", "yes");
-
-    const config = resolveConfig();
-    expect(config.disableGpu).toBe(false);
-  });
-
-  it("reads browser GPU mode from env", () => {
-    setEnv("PRODUCER_BROWSER_GPU_MODE", "hardware");
-
-    const config = resolveConfig();
-    expect(config.browserGpuMode).toBe("hardware");
-  });
-
-  it("accepts 'auto' as a valid browser GPU mode env value", () => {
-    setEnv("PRODUCER_BROWSER_GPU_MODE", "auto");
-
-    const config = resolveConfig();
-    expect(config.browserGpuMode).toBe("auto");
-  });
-
-  it("falls back to software browser GPU mode for invalid env values", () => {
-    setEnv("PRODUCER_BROWSER_GPU_MODE", "native");
-
-    const config = resolveConfig();
-    expect(config.browserGpuMode).toBe("software");
-  });
-
-  it("explicit overrides take precedence over env vars", () => {
-    setEnv("PRODUCER_CORES_PER_WORKER", "5");
-
-    const config = resolveConfig({ coresPerWorker: 8 });
-    expect(config.coresPerWorker).toBe(8);
-  });
-
-  it("falls back to defaults for invalid numeric env vars", () => {
-    setEnv("PRODUCER_CORES_PER_WORKER", "not-a-number");
-
-    const config = resolveConfig();
-    expect(config.coresPerWorker).toBe(DEFAULT_CONFIG.coresPerWorker);
-  });
-
-  it("clamps chunkSizeFrames to minimum of 120", () => {
-    setEnv("PRODUCER_CHUNK_SIZE_FRAMES", "50");
-
-    const config = resolveConfig();
-    expect(config.chunkSizeFrames).toBe(120);
-  });
-
-  it("clamps frameDataUriCacheLimit to minimum of 32", () => {
-    setEnv("PRODUCER_FRAME_DATA_URI_CACHE_LIMIT", "10");
-
-    const config = resolveConfig();
-    expect(config.frameDataUriCacheLimit).toBe(32);
-  });
-
-  describe("enablePageSideCompositing (HF_PAGE_SIDE_COMPOSITING)", () => {
-    it("defaults to true", () => {
-      const config = resolveConfig();
-      expect(config.enablePageSideCompositing).toBe(true);
-    });
-
-    it("disabled when HF_PAGE_SIDE_COMPOSITING=false", () => {
-      setEnv("HF_PAGE_SIDE_COMPOSITING", "false");
-      const config = resolveConfig();
-      expect(config.enablePageSideCompositing).toBe(false);
-    });
-
-    it("explicit override wins over the env var", () => {
-      setEnv("HF_PAGE_SIDE_COMPOSITING", "true");
-      const config = resolveConfig({ enablePageSideCompositing: false });
-      expect(config.enablePageSideCompositing).toBe(false);
-    });
-  });
-
-  describe("lowMemoryMode", () => {
-    it("forces on for truthy PRODUCER_LOW_MEMORY_MODE values", () => {
-      setEnv("PRODUCER_LOW_MEMORY_MODE", "true");
-      for (const v of ["true", "on", "1", "TRUE"]) {
-        process.env.PRODUCER_LOW_MEMORY_MODE = v;
-        expect(resolveConfig().lowMemoryMode).toBe(true);
-      }
-    });
-
-    it("forces off for falsy PRODUCER_LOW_MEMORY_MODE values", () => {
-      setEnv("PRODUCER_LOW_MEMORY_MODE", "false");
-      for (const v of ["false", "off", "0", "OFF"]) {
-        process.env.PRODUCER_LOW_MEMORY_MODE = v;
-        expect(resolveConfig().lowMemoryMode).toBe(false);
-      }
-    });
-
-    it("auto-detects from total RAM when the env var is unset", () => {
-      setEnv("PRODUCER_LOW_MEMORY_MODE", "");
-      delete process.env.PRODUCER_LOW_MEMORY_MODE;
-      expect(resolveConfig().lowMemoryMode).toBe(isLowMemorySystem());
-    });
-
-    it("explicit override beats both env and auto-detection", () => {
-      setEnv("PRODUCER_LOW_MEMORY_MODE", "true");
-      expect(resolveConfig({ lowMemoryMode: false }).lowMemoryMode).toBe(false);
-    });
-  });
-});