docs(engine): document __name polyfill and add regression test

[vanceingalls]

Summary

Document why the window.__name polyfill in frameCapture.ts is necessary, expand the inline comment with the full per-runtime matrix, and add a regression test that surfaces transpiler behavior on the next failure.

Outcome of the Chunk 12 investigation: keep the polyfill.

Why

Chunk 12 of plans/hdr-followups.md. The polyfill had a vague comment and no test, so it was unclear whether it was still needed or could be deleted.

Empirical findings

Probe in /tmp/hf-name-probe:

Runtime / build	Injects __name(fn, "name") wrappers in Function.prototype.toString()?
bun (TS loader)	No — verified for top-level and nested named functions / arrow expressions.
tsx (esbuild loader, keepNames=true)	Yes for nested named functions / arrows; observed crash mode in dev/test.
tsc (noEmit and emit)	No — does not inject the helper.
tsup for @hyperframes/cli (noExternal: ["@hyperframes/engine"])	Polyfill definition is bundled, but __name(...) call sites are absent in packages/cli/dist/cli.js (grepped).

Root cause. @hyperframes/engine's package.json exports raw TypeScript (main/exports → ./src/index.ts), so every consumer's transpiler decides whether to inject __name. Anything that runs through tsx (producer parity-harness, ad-hoc dev scripts, bun run --filter @hyperframes/engine test via Vitest's loader) will serialize wrapped function bodies into page.evaluate(...) and crash with ReferenceError: __name is not defined.

Decision. Keep the no-op window.__name shim. Cost is one evaluateOnNewDocument call. The alternative (rewriting every page.evaluate(fn) site to page.addScriptTag({ content: "..." }), like packages/cli/src/commands/contrast-audit.browser.js already does) is far more invasive and easy to regress.

What changed

• Expanded the inline comment in packages/engine/src/services/frameCapture.ts to explain the per-runtime matrix above and point to the script-tag alternative.
• New packages/engine/src/services/frameCapture-namePolyfill.test.ts — a pure unit test (matches the rest of the engine package's no-browser-launch convention) that:
  1. Asserts the polyfill is wired up via evaluateOnNewDocument and runs before the first awaited browser.version() call.
  2. Probes the active Vitest transpiler for __name(...) injection so the next maintainer can see at a glance whether the upstream behavior has shifted.

Test plan

• bun run --filter @hyperframes/engine test → 408/408 pass (3 new tests in this file).
• bunx tsc --noEmit -p packages/engine clean.
• bunx oxlint and bunx oxfmt --check clean on edited files.

Stack

Chunk 12 of plans/hdr-followups.md. Independent of all other chunks; closes out the investigation item.

[vanceingalls]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• docs(engine): document __name polyfill and add regression test #385 👈 (View in Graphite)
• 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
• 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.