@hyperframes/engine 0.6.118 → 0.6.120

package/src/config.ts

@@ -1,417 +0,0 @@
-/**
- * Engine Configuration
- *
- * Typed configuration for the rendering pipeline. Replaces the PRODUCER_*
- * env var sprawl with a structured interface. Env vars still work as
- * fallbacks for backward compatibility during migration.
- */
-
-import {
-  getSystemTotalMb,
-  isLowMemorySystem,
-  LOW_MEMORY_TOTAL_MB_THRESHOLD,
-} from "./services/systemMemory.js";
-import { DEFAULT_VP9_CPU_USED, normalizeVp9CpuUsed } from "./services/vp9Options.js";
-
-/**
- * Full engine configuration. All fields are wired through the config
- * object; env vars serve as backward-compatible fallbacks resolved
- * in `resolveConfig()`.
- */
-export interface EngineConfig {
-  // ── Rendering ────────────────────────────────────────────────────────
-  fps: 24 | 30 | 60;
-  quality: "draft" | "standard" | "high";
-  format: "jpeg" | "png";
-  jpegQuality: number;
-
-  // ── Parallelism ──────────────────────────────────────────────────────
-  /** Max worker count. "auto" uses CPU-based heuristic. */
-  concurrency: number | "auto";
-  /** CPU cores allocated per worker. */
-  coresPerWorker: number;
-  /** Minimum frames before parallel workers are used. */
-  minParallelFrames: number;
-  /** Frame count threshold for "large render" heuristics. */
-  largeRenderThreshold: number;
-
-  // ── Browser ──────────────────────────────────────────────────────────
-  chromePath?: string;
-  disableGpu: boolean;
-  /**
-   * Chrome/WebGL rendering backend.
-   * - "software": SwiftShader (CPU-only). Always works; ~5-50× slower than GPU.
-   * - "hardware": host GPU via platform-native ANGLE backend (Metal/D3D11/EGL).
-   *   Errors if no usable GPU is reachable from Chrome.
-   * - "auto": probe Chrome for WebGL availability on first launch in this
-   *   process; fall back to software if hardware-mode WebGL is unavailable.
-   *   Cost: one extra Chrome launch (~1-2 s) per process; result cached.
-   */
-  browserGpuMode: "software" | "hardware" | "auto";
-  enableBrowserPool: boolean;
-  browserTimeout: number;
-  protocolTimeout: number;
-  /** Expected Chromium major version (optional validation). */
-  expectedChromiumMajor?: number;
-  /** Force screenshot capture mode (skip BeginFrame even on Linux). */
-  forceScreenshot: boolean;
-  /**
-   * Static-frame dedup: reuse byte-identical frames instead of re-seeking +
-   * re-screenshotting (anchor-verified at init). Default ON; disable via
-   * `HF_STATIC_DEDUP` in {false,0,off}. Only arms in screenshot capture mode.
-   */
-  staticFrameDedup: boolean;
-  /**
-   * Low-memory render profile. When `true`, the orchestrator collapses the
-   * pipeline to its cheapest shape on memory-constrained hosts: it skips the
-   * throwaway auto-worker calibration browser, pins capture to a single
-   * worker (unless the user passed an explicit `--workers`), and prefers
-   * screenshot capture over BeginFrame. Resolved automatically from total
-   * RAM (`isLowMemorySystem()`); force on/off via `PRODUCER_LOW_MEMORY_MODE`
-   * or the `--low-memory-mode` CLI flag.
-   */
-  lowMemoryMode: boolean;
-  /**
-   * Opt-in: page-side shader-transition compositing.
-   *
-   * When `true`, shader transitions for SDR compositions run their blend
-   * inside Chrome via WebGL on a page-side compositor canvas instead of
-   * Node-side per-pixel blending (the hf#677 layered pipeline). The engine
-   * then captures ONE opaque RGB frame per output frame via the streaming
-   * capture path, skipping per-scene transparent screenshots and the
-   * Node-side shader-blend worker pool entirely.
-   *
-   * The feature stacks on top of the hf#677 chain — it does not undo it.
-   * When this flag is OFF (the default), behaviour is byte-identical to the
-   * current path. When ON and the composition has no shader transitions or
-   * has HDR content (which forces the layered path regardless), this flag
-   * is a no-op.
-   *
-   * Mac viability: Chrome on Mac accelerates page-side WebGL canvases via
-   * Metal/CoreAnimation natively. This is the lever for Mac users who
-   * cannot use `--enable-begin-frame-control` (Chromium structural limit,
-   * crbug.com/40656275).
-   *
-   * Determinism: page-side WebGL is f32, not f64. Byte-equality fixture
-   * pins are NOT compatible with this path; the new path's correctness
-   * pin is PSNR-based. Default OFF preserves the existing pins for the
-   * hf#677 chain.
-   *
-   * Env fallback: `HF_PAGE_SIDE_COMPOSITING=true`.
-   */
-  enablePageSideCompositing: boolean;
-
-  // ── Encoding ─────────────────────────────────────────────────────────
-  /**
-   * libvpx-vp9 speed/quality tradeoff. Higher values encode faster with a
-   * larger quality/size tradeoff. FFmpeg accepts integer values from -8 to 8.
-   */
-  vp9CpuUsed: number;
-  enableChunkedEncode: boolean;
-  chunkSizeFrames: number;
-  enableStreamingEncode: boolean;
-  /**
-   * Max composition duration eligible for streaming encode (seconds).
-   * Mirrors GSAP rendering's 4-minute streaming guard: production has seen
-   * ffmpeg's streaming pipe hit FFMPEG_STREAMING_TIMEOUT_MS on longer videos.
-   */
-  streamingEncodeMaxDurationSeconds: number;
-
-  // ── FFmpeg timeouts ──────────────────────────────────────────────────
-  /** Timeout for FFmpeg frame encoding (ms). Default: 600_000 */
-  ffmpegEncodeTimeout: number;
-  /** Timeout for FFmpeg mux/faststart processes (ms). Default: 300_000 */
-  ffmpegProcessTimeout: number;
-  /**
-   * Inactivity timeout for FFmpeg streaming encode (ms). The timer resets on
-   * every successful `writeFrame` call, so this caps the duration of a
-   * single "no frame arrived" gap (capture hang, dead Chrome), not the total
-   * render time. Default: 600_000 (10 minutes without any frame = dead).
-   */
-  ffmpegStreamingTimeout: number;
-
-  // ── HDR ──────────────────────────────────────────────────────────────
-  /** HDR output transfer function. false = SDR output (default). */
-  hdr: { transfer: "hlg" | "pq" } | false;
-  /** Auto-detect HDR from video sources when hdr is not explicitly set. */
-  hdrAutoDetect: boolean;
-
-  // ── Media ────────────────────────────────────────────────────────────
-  audioGain: number;
-  /**
-   * Hard upper bound on entries kept in the video frame data URI cache.
-   * Acts as a sanity cap; the byte budget below normally fires first on
-   * high-resolution renders. At 1080p with ~6 MB per JPEG frame the default
-   * 256 entries fit inside ~1.5 GB. At 4K the byte budget evicts long
-   * before this cap is reached.
-   */
-  frameDataUriCacheLimit: number;
-  /**
-   * Memory budget for the cache, in megabytes. Eviction kicks in once the
-   * sum of cached data-URI string lengths exceeds this. Sized so a worker
-   * stays comfortably under a few GB even at 4K (where each PNG frame is
-   * ~25 MB and the base64 data URI is ~33 MB).
-   */
-  frameDataUriCacheBytesLimitMb: number;
-
-  // ── Timeouts ─────────────────────────────────────────────────────────
-  playerReadyTimeout: number;
-  renderReadyTimeout: number;
-  /**
-   * Puppeteer `page.goto()` navigation timeout for the entry HTML, in ms.
-   * The browser must reach `domcontentloaded` within this budget — heavy
-   * compositions (many videos, large fonts, hundreds of asset requests)
-   * can blow past the default 60s on cold cache. Default: 60_000.
-   *
-   * Env fallback: `PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS`.
-   * CLI flag: `--browser-timeout <seconds>`.
-   */
-  pageNavigationTimeout: number;
-
-  // ── Runtime ──────────────────────────────────────────────────────────
-  /** Verify Hyperframe runtime SHA256 checksums. */
-  verifyRuntime: boolean;
-  /** Custom manifest path for Hyperframe runtime. */
-  runtimeManifestPath?: string;
-
-  // ── Cache ────────────────────────────────────────────────────────────
-  /**
-   * Directory where the content-addressed extraction cache persists frame
-   * bundles keyed on (path, mtime, size, mediaStart, duration, fps, format).
-   * Undefined disables caching — extraction runs into the render's workDir
-   * and cleanup removes it when the render ends, preserving the pre-cache
-   * behaviour.
-   *
-   * **Single-writer.** The cache is not safe for concurrent renders pointing
-   * at the same directory. A `.hf-complete` sentinel prevents another render
-   * from serving an entry that hasn't finished extracting, but individual
-   * frame files are written non-atomically — a second render reading during
-   * the write window can observe a truncated frame. Give each concurrent
-   * render pipeline its own `extractCacheDir`, or gate with an external mutex.
-   *
-   * **Network filesystems.** `mtime` resolution on NFS/SMB mounts can be
-   * coarser than expected (seconds rather than nanoseconds), which may
-   * produce spurious cache hits if a source file is overwritten within the
-   * same mtime tick. Local filesystems are the intended deployment target.
-   *
-   * Env fallback: `HYPERFRAMES_EXTRACT_CACHE_DIR`.
-   */
-  extractCacheDir?: string;
-
-  // ── Debug ────────────────────────────────────────────────────────────
-  debug: boolean;
-}
-
-/** Default configuration — sensible for Hyperframes compositions. */
-export const DEFAULT_CONFIG: EngineConfig = {
-  fps: 30,
-  quality: "standard",
-  format: "jpeg",
-  jpegQuality: 80,
-
-  concurrency: "auto",
-  coresPerWorker: 2.5,
-  minParallelFrames: 120,
-  largeRenderThreshold: 1000,
-
-  disableGpu: false,
-  browserGpuMode: "software",
-  enableBrowserPool: true,
-  browserTimeout: 120_000,
-  protocolTimeout: 300_000,
-  forceScreenshot: false,
-  staticFrameDedup: true,
-  // Auto-detected per host in `resolveConfig`; defaults off for the raw
-  // DEFAULT_CONFIG (used directly by tests and worker-sizing fallbacks).
-  lowMemoryMode: false,
-  enablePageSideCompositing: true,
-
-  vp9CpuUsed: DEFAULT_VP9_CPU_USED,
-  enableChunkedEncode: false,
-  chunkSizeFrames: 360,
-  enableStreamingEncode: true,
-  streamingEncodeMaxDurationSeconds: 240,
-
-  ffmpegEncodeTimeout: 600_000,
-  ffmpegProcessTimeout: 300_000,
-  ffmpegStreamingTimeout: 600_000,
-
-  hdr: false,
-  hdrAutoDetect: true,
-
-  audioGain: 1,
-  frameDataUriCacheLimit: 256,
-  frameDataUriCacheBytesLimitMb: 1500,
-
-  playerReadyTimeout: 45_000,
-  renderReadyTimeout: 15_000,
-  pageNavigationTimeout: 60_000,
-
-  verifyRuntime: true,
-
-  debug: false,
-};
-
-function memoryAdaptiveCacheLimit(): number {
-  const total = getSystemTotalMb();
-  if (total < 4096) return 32;
-  if (total <= LOW_MEMORY_TOTAL_MB_THRESHOLD) return 64;
-  return DEFAULT_CONFIG.frameDataUriCacheLimit;
-}
-
-function memoryAdaptiveCacheBytesMb(): number {
-  const total = getSystemTotalMb();
-  if (total < 4096) return 128;
-  if (total <= LOW_MEMORY_TOTAL_MB_THRESHOLD) return 256;
-  return DEFAULT_CONFIG.frameDataUriCacheBytesLimitMb;
-}
-
-/**
- * Resolve configuration by merging: defaults ← env vars ← explicit overrides.
- * Env vars provide backward compatibility during migration; explicit config
- * takes precedence over everything.
- */
-export function resolveConfig(overrides?: Partial<EngineConfig>): EngineConfig {
-  const env = (key: string): string | undefined => process.env[key];
-  const envNum = (key: string, fallback: number): number => {
-    const raw = env(key);
-    if (raw === undefined || raw === "") return fallback;
-    const n = Number(raw);
-    return Number.isFinite(n) ? n : fallback;
-  };
-  const envBool = (key: string, fallback: boolean): boolean => {
-    const raw = env(key);
-    if (raw === undefined) return fallback;
-    return raw === "true";
-  };
-  const envVp9CpuUsed = (): number => {
-    const raw = env("PRODUCER_VP9_CPU_USED");
-    if (raw === undefined || raw === "") return DEFAULT_CONFIG.vp9CpuUsed;
-    return normalizeVp9CpuUsed(Number(raw));
-  };
-  const envBrowserGpuMode = (): EngineConfig["browserGpuMode"] => {
-    const raw = env("PRODUCER_BROWSER_GPU_MODE");
-    if (raw === "hardware" || raw === "software" || raw === "auto") return raw;
-    return DEFAULT_CONFIG.browserGpuMode;
-  };
-  // Tri-state: explicit on/off via env, otherwise auto-detect from total RAM.
-  const resolveLowMemoryMode = (): boolean => {
-    const raw = env("PRODUCER_LOW_MEMORY_MODE")?.toLowerCase();
-    if (raw === "true" || raw === "on" || raw === "1") return true;
-    if (raw === "false" || raw === "off" || raw === "0") return false;
-    return isLowMemorySystem();
-  };
-  // Opt-OUT: default ON, disabled only by an explicit falsey value.
-  const resolveStaticFrameDedup = (): boolean => {
-    const raw = env("HF_STATIC_DEDUP")?.trim().toLowerCase();
-    return !(raw === "false" || raw === "off" || raw === "0");
-  };
-
-  // Env-var layer (backward compat)
-  const fromEnv: Partial<EngineConfig> = {
-    concurrency: env("PRODUCER_MAX_WORKERS") ? Number(env("PRODUCER_MAX_WORKERS")) : undefined,
-    coresPerWorker: envNum("PRODUCER_CORES_PER_WORKER", DEFAULT_CONFIG.coresPerWorker),
-    minParallelFrames: envNum("PRODUCER_MIN_PARALLEL_FRAMES", DEFAULT_CONFIG.minParallelFrames),
-    largeRenderThreshold: envNum(
-      "PRODUCER_LARGE_RENDER_THRESHOLD",
-      DEFAULT_CONFIG.largeRenderThreshold,
-    ),
-
-    chromePath: env("PRODUCER_HEADLESS_SHELL_PATH"),
-    disableGpu: envBool("PRODUCER_DISABLE_GPU", DEFAULT_CONFIG.disableGpu),
-    browserGpuMode: envBrowserGpuMode(),
-    enableBrowserPool: envBool("PRODUCER_ENABLE_BROWSER_POOL", DEFAULT_CONFIG.enableBrowserPool),
-    browserTimeout: envNum("PRODUCER_PUPPETEER_LAUNCH_TIMEOUT_MS", DEFAULT_CONFIG.browserTimeout),
-    protocolTimeout: envNum(
-      "PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS",
-      DEFAULT_CONFIG.protocolTimeout,
-    ),
-    expectedChromiumMajor: env("PRODUCER_EXPECTED_CHROMIUM_MAJOR")
-      ? Number(env("PRODUCER_EXPECTED_CHROMIUM_MAJOR"))
-      : undefined,
-
-    forceScreenshot: envBool("PRODUCER_FORCE_SCREENSHOT", DEFAULT_CONFIG.forceScreenshot),
-    staticFrameDedup: resolveStaticFrameDedup(),
-    lowMemoryMode: resolveLowMemoryMode(),
-    enablePageSideCompositing: envBool(
-      "HF_PAGE_SIDE_COMPOSITING",
-      DEFAULT_CONFIG.enablePageSideCompositing,
-    ),
-
-    vp9CpuUsed: envVp9CpuUsed(),
-    enableChunkedEncode: envBool(
-      "PRODUCER_ENABLE_CHUNKED_ENCODE",
-      DEFAULT_CONFIG.enableChunkedEncode,
-    ),
-    chunkSizeFrames: Math.max(
-      120,
-      envNum("PRODUCER_CHUNK_SIZE_FRAMES", DEFAULT_CONFIG.chunkSizeFrames),
-    ),
-    enableStreamingEncode: envBool(
-      "PRODUCER_ENABLE_STREAMING_ENCODE",
-      DEFAULT_CONFIG.enableStreamingEncode,
-    ),
-    streamingEncodeMaxDurationSeconds: Math.max(
-      0,
-      envNum(
-        "PRODUCER_STREAMING_ENCODE_MAX_DURATION_SECONDS",
-        DEFAULT_CONFIG.streamingEncodeMaxDurationSeconds,
-      ),
-    ),
-
-    ffmpegEncodeTimeout: envNum("FFMPEG_ENCODE_TIMEOUT_MS", DEFAULT_CONFIG.ffmpegEncodeTimeout),
-    ffmpegProcessTimeout: envNum("FFMPEG_PROCESS_TIMEOUT_MS", DEFAULT_CONFIG.ffmpegProcessTimeout),
-    ffmpegStreamingTimeout: envNum(
-      "FFMPEG_STREAMING_TIMEOUT_MS",
-      DEFAULT_CONFIG.ffmpegStreamingTimeout,
-    ),
-
-    hdr: (() => {
-      const raw = env("PRODUCER_HDR_TRANSFER");
-      if (raw === "hlg" || raw === "pq") return { transfer: raw };
-      return false;
-    })(),
-    hdrAutoDetect: envBool("PRODUCER_HDR_AUTO_DETECT", DEFAULT_CONFIG.hdrAutoDetect),
-
-    audioGain: envNum("PRODUCER_AUDIO_GAIN", DEFAULT_CONFIG.audioGain),
-    frameDataUriCacheLimit: Math.max(
-      32,
-      envNum("PRODUCER_FRAME_DATA_URI_CACHE_LIMIT", memoryAdaptiveCacheLimit()),
-    ),
-    frameDataUriCacheBytesLimitMb: Math.max(
-      64,
-      envNum("PRODUCER_FRAME_DATA_URI_CACHE_BYTES_MB", memoryAdaptiveCacheBytesMb()),
-    ),
-
-    playerReadyTimeout: envNum(
-      "PRODUCER_PLAYER_READY_TIMEOUT_MS",
-      DEFAULT_CONFIG.playerReadyTimeout,
-    ),
-    renderReadyTimeout: envNum(
-      "PRODUCER_RENDER_READY_TIMEOUT_MS",
-      DEFAULT_CONFIG.renderReadyTimeout,
-    ),
-    pageNavigationTimeout: envNum(
-      "PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS",
-      DEFAULT_CONFIG.pageNavigationTimeout,
-    ),
-
-    verifyRuntime: env("PRODUCER_VERIFY_HYPERFRAME_RUNTIME") !== "false",
-    runtimeManifestPath: env("PRODUCER_HYPERFRAME_MANIFEST_PATH"),
-
-    extractCacheDir: env("HYPERFRAMES_EXTRACT_CACHE_DIR"),
-  };
-
-  // Remove undefined values so they don't override defaults
-  const cleanEnv = Object.fromEntries(Object.entries(fromEnv).filter(([, v]) => v !== undefined));
-
-  const merged = {
-    ...DEFAULT_CONFIG,
-    ...cleanEnv,
-    ...overrides,
-  };
-  return {
-    ...merged,
-    vp9CpuUsed: normalizeVp9CpuUsed(merged.vp9CpuUsed),
-  };
-}

package/src/index.ts

@@ -1,273 +0,0 @@
-/**
- * @hyperframes/engine
- *
- * Seekable web page to video rendering engine.
- * Framework-agnostic: works with GSAP, Lottie, Three.js, CSS animations,
- * or any web content that implements the window.__hf seek protocol.
- *
- * ## Error Convention
- *
- * Engine services use three error strategies depending on the operation type:
- *
- * - **Orchestration services throw on failure.** Browser launch, session init,
- *   frame capture, and CDP operations propagate errors as thrown exceptions.
- *   Callers are expected to catch and handle (e.g. frameCapture, browserManager,
- *   screenshotService, videoFrameExtractor.extractVideoFramesRange).
- *
- * - **FFmpeg process wrappers return `{ success, error? }` result objects.**
- *   Encoding, muxing, audio mixing, and streaming encode operations never reject.
- *   They resolve with a result that includes `success: boolean` and an optional
- *   `error` string (e.g. chunkEncoder, audioMixer, streamingEncoder).
- *
- * - **Cleanup and teardown functions never throw.** Browser close, session close,
- *   temp directory removal, and resource release swallow errors via `.catch(() => {})`
- *   to avoid masking the original failure (e.g. releaseBrowser, closeCaptureSession,
- *   FrameLookupTable.cleanup).
- *
- * - **Optional lookups return `T | undefined` or `T | null`.**
- *   Functions that may legitimately find nothing (resolveHeadlessShellPath,
- *   getFrameAtTime, detectGpuEncoder) return a nullable value instead of throwing.
- *
- */
-
-// ── Protocol types ─────────────────────────────────────────────────────────────
-export type {
-  HfProtocol,
-  HfMediaElement,
-  HfTransitionMeta,
-  CaptureOptions,
-  CaptureVideoMetadataHint,
-  CaptureResult,
-  CaptureBufferResult,
-  CapturePerfSummary,
-} from "./types.js";
-
-// ── Configuration ──────────────────────────────────────────────────────────────
-export { resolveConfig, DEFAULT_CONFIG, type EngineConfig } from "./config.js";
-export {
-  DEFAULT_VP9_CPU_USED,
-  MAX_VP9_CPU_USED,
-  MIN_VP9_CPU_USED,
-  normalizeVp9CpuUsed,
-} from "./services/vp9Options.js";
-export {
-  getSystemTotalMb,
-  isLowMemorySystem,
-  LOW_MEMORY_TOTAL_MB_THRESHOLD,
-} from "./services/systemMemory.js";
-
-// ── Browser management ─────────────────────────────────────────────────────────
-export {
-  acquireBrowser,
-  releaseBrowser,
-  drainBrowserPool,
-  resolveHeadlessShellPath,
-  resolveBrowserGpuMode,
-  buildChromeArgs,
-  ENABLE_BROWSER_POOL,
-  type BuildChromeArgsOptions,
-  type CaptureMode,
-  type AcquiredBrowser,
-} from "./services/browserManager.js";
-
-// ── Frame capture pipeline ──────────────────────────────────────────────────────
-export {
-  createCaptureSession,
-  initializeSession,
-  closeCaptureSession,
-  captureFrame,
-  captureFrameToBuffer,
-  discardWarmupCapture,
-  getCompositionDuration,
-  getCapturePerfSummary,
-  prepareCaptureSessionForReuse,
-  type CaptureSession,
-  type BeforeCaptureHook,
-  type DiscardWarmupInnerCapture,
-} from "./services/frameCapture.js";
-
-// ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────
-export {
-  beginFrameCapture,
-  pageScreenshotCapture,
-  getCdpSession,
-  injectVideoFramesBatch,
-  syncVideoFrameVisibility,
-  cdpSessionCache,
-  initTransparentBackground,
-  captureAlphaPng,
-  applyDomLayerMask,
-  removeDomLayerMask,
-  DOM_LAYER_MASK_STYLE_ID,
-  type BeginFrameResult,
-} from "./services/screenshotService.js";
-
-// ── Encoding ───────────────────────────────────────────────────────────────────
-export {
-  buildEncoderArgs,
-  encodeFramesFromDir,
-  encodeFramesChunkedConcat,
-  muxVideoWithAudio,
-  applyFaststart,
-  detectGpuEncoder,
-  ENCODER_PRESETS,
-  getEncoderPreset,
-  type GpuEncoder,
-} from "./services/chunkEncoder.js";
-export type { EncoderOptions, EncodeResult, MuxResult } from "./services/chunkEncoder.types.js";
-
-export {
-  spawnStreamingEncoder,
-  createFrameReorderBuffer,
-  type StreamingEncoder,
-  type StreamingEncoderOptions,
-  type StreamingEncoderResult,
-  type FrameReorderBuffer,
-} from "./services/streamingEncoder.js";
-
-// ── Media processing ───────────────────────────────────────────────────────────
-export {
-  parseVideoElements,
-  parseImageElements,
-  extractVideoFramesRange,
-  extractAllVideoFrames,
-  resolveProjectRelativeSrc,
-  getFrameAtTime,
-  createFrameLookupTable,
-  FrameLookupTable,
-  type VideoElement,
-  type ImageElement,
-  type ExtractedFrames,
-  type ExtractionOptions,
-  type ExtractionResult,
-  type ExtractionPhaseBreakdown,
-  type VideoFrameFormat,
-  VIDEO_FRAME_FORMATS,
-  isVideoFrameFormat,
-} from "./services/videoFrameExtractor.js";
-
-export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
-
-export { parseAudioElements, processCompositionAudio } from "./services/audioMixer.js";
-export type {
-  AudioElement,
-  AudioTrack,
-  AudioVolumeKeyframe,
-  MixResult,
-} from "./services/audioMixer.types.js";
-
-// ── Parallel rendering ─────────────────────────────────────────────────────────
-export {
-  calculateOptimalWorkers,
-  distributeFrames,
-  executeParallelCapture,
-  mergeWorkerFrames,
-  getSystemResources,
-  type WorkerTask,
-  type WorkerResult,
-  type ParallelProgress,
-} from "./services/parallelCoordinator.js";
-
-// ── File server ────────────────────────────────────────────────────────────────
-export {
-  createFileServer,
-  type FileServerOptions,
-  type FileServerHandle,
-} from "./services/fileServer.js";
-
-// ── Utilities ──────────────────────────────────────────────────────────────────
-export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
-
-export {
-  assertSwiftShader,
-  readWebGlVendorInfo,
-  SwiftShaderAssertionError,
-  BROWSER_GPU_NOT_SOFTWARE,
-} from "./utils/assertSwiftShader.js";
-
-export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
-
-export {
-  extractMediaMetadata,
-  extractVideoMetadata,
-  extractAudioMetadata,
-  analyzeKeyframeIntervals,
-  type VideoMetadata,
-  type AudioMetadata,
-  type KeyframeAnalysis,
-} from "./utils/ffprobe.js";
-
-export { assertPublicHttpsUrl, downloadToTemp, isHttpUrl } from "./utils/urlDownloader.js";
-export {
-  runFfmpeg,
-  formatFfmpegError,
-  type RunFfmpegOptions,
-  type RunFfmpegResult,
-} from "./utils/runFfmpeg.js";
-export {
-  assertConfiguredFfmpegBinariesExist,
-  getFfmpegBinary,
-  getFfprobeBinary,
-  FFMPEG_PATH_ENV,
-  FFPROBE_PATH_ENV,
-} from "./utils/ffmpegBinaries.js";
-
-export { trackChildProcess, killTrackedProcesses } from "./utils/processTracker.js";
-
-export {
-  decodePng,
-  decodePngToRgb48le,
-  blitRgba8OverRgb48le,
-  blitRgb48leRegion,
-  blitRgb48leAffine,
-  parseTransformMatrix,
-  roundedRectAlpha,
-  resampleRgb48leObjectFit,
-  normalizeObjectFit,
-  type ObjectFit,
-} from "./utils/alphaBlit.js";
-
-export { groupIntoLayers, type CompositeLayer } from "./utils/layerCompositor.js";
-
-// ── Shader transitions ────────────────────────────────────────────────────────
-export {
-  type TransitionFn,
-  TRANSITIONS,
-  crossfade,
-  sampleRgb48le,
-  hdrToLinear,
-  linearToHdr,
-  convertTransfer,
-} from "./utils/shaderTransitions.js";
-
-export {
-  initHdrReadback,
-  uploadAndReadbackHdrFrame,
-  float16ToPqRgb,
-  buildHdrChromeArgs,
-  launchHdrBrowser,
-} from "./services/hdrCapture.js";
-
-export { captureScreenshotWithAlpha } from "./services/screenshotService.js";
-
-export {
-  hideVideoElements,
-  showVideoElements,
-  queryVideoElementBounds,
-  queryElementStacking,
-  type VideoElementBounds,
-  type ElementStackingInfo,
-} from "./services/videoFrameInjector.js";
-
-export {
-  isHdrColorSpace,
-  detectTransfer,
-  getHdrEncoderColorParams,
-  analyzeCompositionHdr,
-  DEFAULT_HDR10_MASTERING,
-  type HdrTransfer,
-  type HdrEncoderColorParams,
-  type CompositionHdrInfo,
-  type HdrMasteringMetadata,
-} from "./utils/hdr.js";
-export type { VideoColorSpace } from "./utils/ffprobe.js";