refactor(types): tighten type safety, dedupe HfTransitionMeta, prune dead LUT export

[vanceingalls]

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

• bun run --filter @hyperframes/engine typecheck
• bun run --filter @hyperframes/producer typecheck
• bun run --filter @hyperframes/shader-transitions typecheck
• 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.

[vanceingalls]

• docs(engine): document __name polyfill and add regression test #385
• perf(producer): cache transfer-converted hdr image buffers per render job #384
• perf(producer): gate per-frame debug meta via optional isLevelEnabled #383
• perf(producer): hdr benchmark harness — --tags filter, peak heap/RSS tracking, bench:hdr script #382
• test(producer): extract frameDirMaxIndexCache to its own module and pin cross-job isolation #381
• test(engine): cover spawnStreamingEncoder lifecycle and cleanup paths #380
• test(engine): add ffprobe-unavailable fallback regression tests #379
• test(shader-transitions): add midpoint (p=0.5) regression invariants for all shaders #378
• test(engine): lock down sRGB→BT.2020 LUT with byte-exact reference values #377
• build(lfs): track tests/*/src/*.png via Git LFS #376
• test(hdr-regression): tighten Window F maxFrameFailures budget after Chunk 4 fix #375
• fix(engine,shader): handle matrix3d transforms and hide non-first scenes #374
• refactor(producer): extract HDR compositing helpers and rename media metadata #373
• fix(producer): wire --crf and --video-bitrate CLI overrides into encoders #372
• fix(producer): tighten resource lifecycle and harden file server #371
• feat(engine): wire options.hdr through chunkEncoder + dynamic SDR→HDR transfer #370
• test(hdr-regression): tighten Window C maxFrameFailures budget after Chunk 1 fix #369
• fix(engine): stop clobbering native <video> opacity in HDR pipeline #368
• refactor(shader-transitions): extract DEFAULT_DURATION and DEFAULT_EASE constants #367
• refactor(types): tighten type safety, dedupe HfTransitionMeta, prune dead LUT export #366 👈 (View in Graphite)
• test(producer): add hdr-regression and hdr-hlg-regression test suites #365
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[jrusso1020]

Clean dedupe + hygiene. HfTransitionMeta was genuinely declared twice in the same file (the second declaration a duplicate of the first) — Typescript accepted it because the shapes matched but any future drift would have been a silent landmine. Pruning getSrgbToHdrLut from the package exports is fine — the LUT tables are still used internally via the two cached instances. The for..of entries() refactor in renderOrchestrator reads equivalently and avoids the non-null assertion.

One substantive note worth calling out: the comment you added on the shader-transitions local HfTransitionMeta ("Locally redeclared because @hyperframes/shader-transitions ships as a standalone CDN bundle and must not depend on @hyperframes/engine") is load-bearing. That kind of "this is the shape contract between two packages that deliberately don't share types" gotcha is exactly the thing that rots silently unless it's documented in code. Glad it's pinned in the diff.

Approved.

— Rames Jusso

[vanceingalls]

Thanks. The local-redeclare comment on HfTransitionMeta in @hyperframes/shader-transitions is intentional and load-bearing — shader-transitions ships as a standalone CDN bundle (per its package design) and can't take a dep on @hyperframes/engine, so the type duplication is the documented escape hatch rather than an oversight to clean up later. Will keep that note in the diff.

[vanceingalls]

Merge activity

• Apr 22, 11:56 PM UTC: @vanceingalls merged this pull request with Graphite.