From 5de5df7fbb759de8005d7409b2378419a3bf72a3 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 22 Apr 2026 16:56:17 -0700
Subject: [PATCH] refactor(types): tighten type safety, dedupe
 HfTransitionMeta, prune dead LUT export (#366)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Four small, mechanical type-safety cleanups across `engine`, `producer`, and `shader-transitions`. Zero behavior change — pure pre-cleanup so the rest of the stack ships against a tighter baseline.

## Why

`Chunk 6` of `plans/hdr-followups.md`. Several non-null assertions and a duplicate interface had accumulated as rebase artifacts and leftover work-in-progress; lands first because it touches files later chunks edit and removes friction during review.

## What changed

- `renderOrchestrator.ts`: replace `layers[layerIdx]!` with a `for (const [layerIdx, layer] of layers.entries())` so both index and element come from the iterator.
- `engine/types.ts`: drop the duplicate `HfTransitionMeta` interface (rebase artifact); the original definition above it is the documented one. The orphaned doc comment now 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 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.

## Test plan

- [x] `bun run --filter @hyperframes/engine typecheck`
- [x] `bun run --filter @hyperframes/producer typecheck`
- [x] `bun run --filter @hyperframes/shader-transitions typecheck`
- [x] `bun run --filter @hyperframes/engine test` — 308/308 pass (no test changes; assertions removed in code only).

## Stack

Chunk 6 of `plans/hdr-followups.md`. Mechanical cleanup landed early per the suggested merge order.
---
 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;