tsc (noUncheckedIndexedAccess) types marked[i]/orphaned[i] as
Element | undefined; vitest passed but bun run build failed. Narrow
before the isStylable predicate and regenerate the render-inline IIFE.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Follow-up on Miga's review of #2512. The regression fixture
`escape-hatch-fatal-fallback` is tagged `field-signal-reproducer` and
`known-broken` so it's skipped from the default sweep via
`--exclude-tags transparency,field-signal-reproducer` in the
`test:regression*` scripts in packages/producer/package.json. But
`Dockerfile.test`'s ENTRYPOINT invoked the harness directly (`bunx tsx
src/regression-harness.ts -- --sequential`), bypassing those scripts —
so `bun run docker:test*` and the aws-lambda smoke tests would still
try to run the known-broken fixture and fail. CI's own regression sweep
was insulated only because it hardcodes per-shard positional test names
that don't include this fixture, but that's incidental, not by design.
Bake the exclude-tags into the Dockerfile.test ENTRYPOINT itself so
every user of the image (local `docker:test*`, aws-lambda smoke, any
adopter running the reference image) picks up the same skip contract.
Docker CMD args appended after the entrypoint (e.g. matrix shard
positional test names in .github/workflows/regression.yml, or
`--mode=distributed-simulated`) still parse correctly — the harness
applies excludeTags after testNames-filtering (see discoverTestSuites
in regression-harness.ts).
Also exports `parseArgs()` from regression-harness.ts and adds
regression-harness-parse.test.ts to pin the `--exclude-tags` comma-parse
contract, so any future change to the parser or the values baked into
the Dockerfile / package.json will trip a red test rather than silently
diverging.
Verification A (harness comma-parses `--exclude-tags transparency,
field-signal-reproducer`) already worked pre-fix; the new test file
codifies it. Verification B (Docker ENTRYPOINT propagates the same
skip) is what this commit fixes.
Signed-off-by: Via
Field-signal baseline: >=2 fallbacks/hr on darwin/arm64 from filter:blur
and filter:drop-shadow triggers. Fallback path perf is currently untimed,
so we can't know if the overhead is 10% or 10x. This PR adds opt-in
per-frame timing (HF_PROFILE_FALLBACK_CAPTURE=true) that emits p50/p95/p99
+ trigger reason via the observeRenderStage telemetry channel extended in
#2510. Diagnostic surface only -- no perf fix, no behavior change on
healthy paths.
Stack: PR #9 (final) of 9 (base via/escape-hatch-fallback-reproducer).
Signed-off-by: Via
Field signal ts=1784039841 (win32/x64, CLI 0.7.57): shifted-DOM-image-
layer bug at frame 120 reproduces with BOTH PRODUCER_FORCE_SCREENSHOT=true
AND HF_DE_PARALLEL_ROUTER=false set. First case where both known escape
hatches fail simultaneously. Standalone 1920x1080 GSAP paused timeline,
absolute PNG layers, 4 independent scenes.
Ships a skipped regression fixture to codify the shape. NOT a fix — no
root cause identified. The composition is preserved so a future
diagnostic pass has a real, checked-in repro and a proposed fix can be
validated against the same shape the field reported.
Skip mechanism (belt-and-suspenders):
1. meta.json tagged `field-signal-reproducer` and `known-broken`;
producer/package.json test:regression* scripts add the tag to
--exclude-tags alongside the existing `transparency` skip.
2. Not registered in any .github/workflows/regression.yml shard's
args, so the CI regression sweep won't pick it up either.
Un-skip when a fix lands: drop the tags from meta.json AND add the
fixture id to a shard's args in the workflow. See src/README.md for
the field-signal envelope and diagnostic starting points.
Stack: PR #8 of 9 (base via/gpu-parity-gate).
Signed-off-by: Via
Field signals ts=1784049136 (hardware-GPU intermittent black rectangles →
resolved with --no-browser-gpu --low-memory-mode --workers 1) and
ts=1784032286 (clip-path animated image → intermittent black rectangles →
resolved with deterministic precompose). Pattern: hardware-GPU writes
solid-black on some composition shapes; software-GPU / screenshot bypass
restores correctness. Raw per-pixel diff alone false-positives on every
compositor jitter frame; the diagnostic-grade signal is asymmetric
black-only-in-A pixels (solid-black where B has content).
Adds `packages/engine/src/utils/gpuParityDiff.ts`: pure helpers
(`diffGpuParityFrames`, `diffGpuParityPngs`, `verifyGpuParity`) that
compare two RGBA frames captured via different GPU paths, count per-pixel
diffs above a tolerance, and isolate black-only-in-A / black-only-in-B
pixel counts + bounding boxes. Symmetric black regions (real black content
present in both captures) are NOT flagged. PNG wrapper preserves the
underlying decode error as Error.cause on either side. All exposed via
`@hyperframes/engine`'s package index for downstream wiring.
19 unit tests cover identity, per-pixel tolerance, the field-bug shape,
the shared-black no-op case, bounding-box tightness across multiple
regions, the inverse pattern, dimension mismatch, data-length mismatch,
overlapping threshold rejection, custom tolerance, verdict output, PNG
end-to-end, and cause-preservation on both A and B decode failures.
Reduced-scope first pass. Wiring a `hyperframes verify-gpu-parity` CLI
command, dual-mode capture orchestration, and integration coverage against
a known-bad composition is intentionally deferred to a follow-up so the
diagnostic primitive can land and be exercised in isolation. The exported
surface is stable — a follow-up need only add the capture-and-diff driver.
Stack: PR #7 of 9 (base via/parallel-capture-observability).
Signed-off-by: Via
Field signals ts=1784019503 (heartbeat reports 0 frames during 64s
browser calibration — reads as broken but is healthy) and ts=1784042064
(1292s Windows render hard-exited during video frame extraction with
no final error string — silent worker crash).
Add calibrating/capturing state to heartbeat labels; surface synthetic
terminal error on unexpected worker exit when no explicit error was
emitted.
Stack: PR #6 of 9 (base via/overlay-count-lint).
Signed-off-by: Via <vance@heygen.com>
Field signal ts=1784040753 (#hyperframes-cli-feedback): a composition
with ~40 heavy overlay DOM elements — `filter:blur`, oversized
`radial-gradient`, and `clip-path` animations — captures solid-black for
the first ~half of the render, recovering near the end. Reproduces
identically via drawElement AND forced --no-browser-gpu screenshot
capture AND `snapshot`, so the capture layer itself is the offender, not
encoder/mux. Independent of duration (padding the timeline grows the bad
zone proportionally, doesn't shift it). Presence alone matters — even
opacity:0 / visibility:hidden / unused overlays contribute. Reporter's
workaround was splitting into per-transition mini-compositions +
FFmpeg concat.
Add compositionCheck rule `composition_heavy_overlay_count_high`
(warning). Counts DOM elements that carry any of: inline
`style` filter:blur / clip-path (non-none) / radial-gradient, or a
class/id whose top-level CSS rule body sets one of those. `display:none`
elements are counted-out (removed from render tree); opacity:0 /
visibility:hidden overlays are counted-in per the field-signal repro
shape. Warns at 25 to give lead time before the observed 40-element bad
zone. Skips registry source and installed-block files, mirroring
`composition_file_too_large`. Includes a `ts=1784040753` reference in
fixHint so authors can trace the risk shape.
Stack: PR #5 of 9 (base via/parity-telemetry-gate).
Signed-off-by: Via
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Field signal ts=1784146416 (darwin/arm64, CLI 0.7.58, 7/10): host
page.goto hit Navigation timeout of 60000ms twice on a CSS 3D + audio
composition; Docker rendered the same composition successfully.
Puppeteer's stock "Navigation timeout of 60000 ms exceeded" text names
none of HyperFrames' existing escape hatches, so the reporter had no
signal that the failure had knobs.
Wraps main-render Puppeteer `page.goto` errors matching
/Navigation timeout|net::ERR_TIMED_OUT/i with an augmented message that
names:
- The effective timeout currently applied (`cfg.pageNavigationTimeout`).
- Raise-the-timeout: `PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS` env,
`--browser-timeout` CLI flag (seconds).
- Browser-binary escape hatch: `HYPERFRAMES_BROWSER_PATH` env.
- Field-signal shape: darwin/arm64 + CSS 3D + audio compound Docker
hint — gated on all three inputs being explicitly true; falls back
to generic hints when any input is unknown.
Mirrors #2443's HYPERFRAMES_BROWSER_PATH surfacing pattern (which
covered download-time failures) at the runtime `page.goto` layer.
Non-matching errors flow through unchanged. Original error preserved
via `err.cause`.
Wired into `renderOrchestrator.executeRenderJob`'s top-level catch,
composed after `augmentProtocolTimeoutError` so the two augmenters
never both fire on the same error (mutually exclusive regexes).
Current wire-up passes no `hasCss3D` / `hasAudio` context — no
compile-time CSS-3D signal is threaded through the render pipeline,
and `hasAudio` is block-scoped inside the try. Per the helper's
fallback docs, unknown flags route to the generic env + browser-path
hints. A future compile-time CSS-3D scan can thread both flags to
enable the full compound Docker hint without touching this helper's
signature.
Stack: PR #3 of 9 (base via/win32-streaming-encode-autodisable).
Signed-off-by: Via <vance@heygen.com>
Field signal ts=1784131903 (win32/x64, CLI 0.7.58, 156s UI-heavy):
stable ONLY with four flags together — --workers 1 --no-browser-gpu
--low-memory-mode + PRODUCER_ENABLE_STREAMING_ENCODE=false. Since
--no-browser-gpu and --low-memory-mode already imply screenshot
capture, three of the four flags are structurally coupled. Auto-detect
the compound at resolveConfig time and disable streaming-encode on
the caller's behalf; user explicit-set (PRODUCER_ENABLE_STREAMING_ENCODE
or overrides.enableStreamingEncode) always wins.
Composition duration is not known at the config layer, so the wire-up
passes compositionDurationSec:undefined and the helper reduces to the
three-condition compound (platform + softwareGpuForced + workers=1).
The 4-arg helper stays exported for downstream callers that DO know
duration (e.g., renderOrchestrator) and want the >120s guard.
Trade-off documented in code + PR body: false positives possible for
short (~<120s) Windows software-GPU single-worker renders. Mitigation
is the explicit opt-in escape hatch.
Emits a single [hyperframes] log line naming the trigger + how to opt
back in, so operators can tell an auto-disable apart from an explicit
opt-out. Adds streamingEncodeAutoDisabledOnWin32Compound internal
provenance for downstream telemetry.
Stack: PR #2 of 9 (base via/protocol-timeout-discoverability).
Signed-off-by: Via
Field signal ts=1784047847 (darwin/arm64, 8GB M1, 9 videos + 22 images):
reporter hit Runtime.callFunctionOn timeout and switched to FFmpeg
because the error didn't surface HyperFrames' existing knobs
(PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS env, --protocol-timeout CLI).
Wraps main-render Puppeteer errors matching /Runtime\.callFunctionOn
timed out|Target closed|protocolTimeout/i with an augmented message that
names the effective timeout, the env var, the CLI flag, and the
field-signal shape. Non-matching errors pass through unchanged
(returned as the same instance). Original error preserved via err.cause.
Also adds a dedicated --protocol-timeout row to the CLI docs Flags table
so PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS is discoverable via search.
Signed-off-by: Via <noreply@heygen.com>
Review feedback on #2473: HF_DE_PARALLEL_STALL_MS had no backwards-compat
shim after the rename to HF_DE_STALL_MS, and a parent abort during a wedged
sequential capture would surface as "stalled" instead of "aborted" in
downstream logs/telemetry (functionally harmless since isCancellation is
gated on abortSignal.aborted, not message text, but misleading to read).
* docs(registry,skills): surface code-highlight 0-based indexing and opacity-reveal sweep guidance
From the 2026-07-14 CLI feedback digest (skills-owner action): a user
building code teaching videos hit two authoring gaps.
1. code-highlight's `line` is intentionally zero-based (`line: 1` =
second displayed line) but the warning lived only in pr-to-video's
code-vocabulary reference — nowhere an author actually touches the
value. Call it out at the block-use sites: the `__BLOCK` declaration
itself, the registry-item description, and the motion-graphics
catalog map.
2. Opacity-only code-typing tripped `sweep_static` for that user, who
worked around it with a slow host y-drift. The sweep fingerprint
does include per-element opacity, so document the actual trap (a
reveal that settles before the sampled window, then holds a static
frame) and the idiomatic fixes (spread the reveal / keep a blinking
caret alive) in the check reference — and pin the fingerprint's
opacity sensitivity with a regression test covering both the
visibility-floor crossing and a mid-fade value change.
* docs(catalog): regenerate code-highlight page from updated registry-item description
Only the code-highlight page is committed: a full generate-catalog-pages
run also surfaces ~34 blocks missing from the git-tracked catalog index
(pre-existing drift on main), which belongs in its own chore PR.
Miguel Ángel