From a9f4fad3564de241fe746afb66dfefae9de23e19 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Tue, 21 Apr 2026 03:27:00 -0700
Subject: [PATCH 1/2] refactor(types): tighten type safety, dedupe
 HfTransitionMeta, prune dead LUT export

Four focused cleanups across engine, producer, and shader-transitions.

* renderOrchestrator: replace `layers[layerIdx]!` non-null assertion with
  `for (const [layerIdx, layer] of layers.entries())` so both index and
  element come from the iterator and the assertion goes away.
* engine/types.ts: remove duplicate `HfTransitionMeta` interface that
  arrived as a rebase artifact; the original definition above it is the
  one with documentation. The orphaned doc comment now correctly
  precedes `HfProtocol`.
* shader-transitions/hyper-shader.ts: keep the local `HfTransitionMeta`
  declaration (the package ships as a standalone CDN bundle and must not
  depend on @hyperframes/engine) but add a sync comment pointing at the
  source-of-truth definition in engine/src/types.ts.
* alphaBlit.ts + engine/index.ts: drop `export` from `getSrgbToHdrLut`
  and remove its re-export. It was only ever called by the internal
  `blitRgba8OverRgb48le`; the public surface was dead code.

Verified with `bun run --filter @hyperframes/engine typecheck`,
`bun run --filter @hyperframes/producer typecheck`,
`bun run --filter @hyperframes/shader-transitions typecheck`,
and `bun run --filter @hyperframes/engine test` (308 pass).
---
 packages/engine/src/index.ts                         | 1 -
 packages/engine/src/types.ts                         | 9 ---------
 packages/engine/src/utils/alphaBlit.ts               | 2 +-
 packages/producer/src/services/renderOrchestrator.ts | 3 +--
 packages/shader-transitions/src/hyper-shader.ts      | 3 +++
 5 files changed, 5 insertions(+), 13 deletions(-)

diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts
index 4eef7b247..01c897981 100644
--- a/packages/engine/src/index.ts
+++ b/packages/engine/src/index.ts
@@ -170,7 +170,6 @@ export {
   blitRgb48leRegion,
   blitRgb48leAffine,
   parseTransformMatrix,
-  getSrgbToHdrLut,
   roundedRectAlpha,
   resampleRgb48leObjectFit,
   normalizeObjectFit,
diff --git a/packages/engine/src/types.ts b/packages/engine/src/types.ts
index 86141d249..81920d270 100644
--- a/packages/engine/src/types.ts
+++ b/packages/engine/src/types.ts
@@ -65,15 +65,6 @@ export interface HfTransitionMeta {
  * GSAP, Framer Motion, CSS animations, Three.js — anything works as long
  * as `seek()` produces deterministic visual output for a given time.
  */
-export interface HfTransitionMeta {
-  time: number;
-  duration: number;
-  shader: string;
-  ease: string;
-  fromScene: string;
-  toScene: string;
-}
-
 export interface HfProtocol {
   /** Total duration of the composition in seconds */
   duration: number;
diff --git a/packages/engine/src/utils/alphaBlit.ts b/packages/engine/src/utils/alphaBlit.ts
index 53143c30a..7b4dd4acb 100644
--- a/packages/engine/src/utils/alphaBlit.ts
+++ b/packages/engine/src/utils/alphaBlit.ts
@@ -292,7 +292,7 @@ const SRGB_TO_HLG = buildSrgbToHdrLut("hlg");
 const SRGB_TO_PQ = buildSrgbToHdrLut("pq");
 
 /** Select the correct sRGB→HDR LUT for the given transfer function. */
-export function getSrgbToHdrLut(transfer: "hlg" | "pq"): Uint16Array {
+function getSrgbToHdrLut(transfer: "hlg" | "pq"): Uint16Array {
   return transfer === "pq" ? SRGB_TO_PQ : SRGB_TO_HLG;
 }
 
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index 423e1e33b..3a886d38a 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -1562,8 +1562,7 @@ export async function executeRenderJob(
           }
 
           // Composite layers bottom-to-top
-          for (let layerIdx = 0; layerIdx < layers.length; layerIdx++) {
-            const layer = layers[layerIdx]!;
+          for (const [layerIdx, layer] of layers.entries()) {
             if (layer.type === "hdr") {
               const before = shouldLog ? countNonZeroRgb48(canvas) : 0;
               const isHdrImage = nativeHdrImageIds.has(layer.element.id);
diff --git a/packages/shader-transitions/src/hyper-shader.ts b/packages/shader-transitions/src/hyper-shader.ts
index 1fc8aafe1..c393d4c04 100644
--- a/packages/shader-transitions/src/hyper-shader.ts
+++ b/packages/shader-transitions/src/hyper-shader.ts
@@ -113,6 +113,9 @@ export function init(config: HyperShaderConfig): GsapTimeline {
     }
   }
 
+  // Locally redeclared (not imported) because @hyperframes/shader-transitions
+  // ships as a standalone CDN bundle and must not depend on @hyperframes/engine.
+  // Keep this in sync with HfTransitionMeta in packages/engine/src/types.ts.
   interface HfTransitionMeta {
     time: number;
     duration: number;

From 478d5cf29940fd908a97481ae8cc96d4d5060873 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 22 Apr 2026 16:25:30 -0700
Subject: [PATCH 2/2] force