feat(core): let a vfx ref read another host's output

[vanceingalls]

Stacked on #4804. Base is fix/4405-vfx-nested-capture; retarget to main once #4804 merges.

What

A vfx ref param (map / matte) that names a host running its own data-vfx-chain now binds that host's finished .hf-vfx-out texture directly.

Why

Item 1 of #4405. A ref to a layer that runs its own kernel could only be expressed by wrapping it in a second layoutsubtree capture canvas, which nests two capture canvases and hangs drawElementImage. Reading the host's output needs no second capture, so nothing nests.

How

• Each host has its own WebGL2 context and textures don't cross contexts, so the referencing host uploads the target's .hf-vfx-out canvas into its own texture with texImage2D (preserveDrawingBuffer: true keeps it readable).
• Ordering: initVfx links host refs after every host registers and orders the registry so a host comes after every host it reads. The engine path and the inline paint path walk that order. In the preview path a referencing host waits for the referenced host's capture and paint, and always takes the deferred path even if it captures nothing itself.
• Cycles and missing hosts: a ref cycle, anything waiting on one, and a ref to a host that failed to register are dropped with reportVfxError and their GL resources released. The placement loop only places a host once its dependencies are placed, so it cannot loop.
• data-vfx-ref-visible does nothing for a host ref: the host already paints itself. A host outside its window reads as a 1x1 transparent texture, matching the existing hidden-source rule.
• A ref whose target is not a chain host (a wrapper containing a canvas.hf-vfx-src) is unchanged, including data-vfx-ref-visible.

Behavior change

Host binding is automatic, not opt-in. A ref that names an element with data-vfx-chain used to read that element's own .hf-vfx-src (its raw layer). It now reads the host's processed output. Anything that relied on the raw reading (for example retro-wave Logo Anim layer 5, the data-vfx-ref-visible-on-a-chain-host shape) must reference a separate wrapper around the raw layer instead; docs/guides/vfx-chain.mdx says so.

This also supersedes part of #4804's M3 change. With host refs, a chain host is never captured through the ref path, so the "one canvas reached both ways gets two opposite visible flags" case can no longer occur. resolveCaptureSource is back to visible: false, and only the wrapper-ref path reads the attribute. The M3 test is replaced with one that pins the new behavior.

Test plan

• src/runtime: 65 files, 1736 tests pass; tsc clean. vfx.test.ts has 67 tests.
• vfxDeterminism.test.ts: all 29 browser tests pass on a rebuilt bundle.
  • Processed-output test: host #a (luma matte) names host #b; #b's raw pixels are opaque white and its output carries alpha strips, and #a's alpha follows the strips.
  • Old data-vfx-ref-visible shape is covered.
  • Ordering test: the preview path is suppressed so the engine resolve is the only painter, and #a precedes #b in the DOM on a cold frame, so #a reads #b's output only if the registry order is right.
• Mutation-tested: host branch off (12 failures), wrapper visible read (5), host source reading visible (2), skipping hosts that have their own capture canvas (10), treating every ref as a host (15). In the browser suite, removing the registry sort fails only the ordering test; turning the host branch off and removing the upload fail all three new browser tests.
• Not verified: the exporter side (wrapAsVfxRefSource and ref-layer emission need checking against the new default), and the original hang on the AE-export machine (this change avoids the nest by construction).
• The intermittent 10 s afterAll browser.close() timeout showed up once in a filtered run; the file passed cleanly on rerun.

Part of #4405 (item 1).

🤖 Generated with Claude Code

[miguel-heygen]

Reviewed 5bf82ca56d13f8dccae240a6e8c8e952972fa42e incrementally on #4804. Registry dependency ordering, cycle/missing-host removal and per-context output uploads work in the authored controls.

Blocker — a referenced host hidden by an ancestor still supplies its stale frame (packages/core/src/runtime/vfx.ts:999). isPaintableHost(ref.host) checks the host’s own computed display, which remains block under a display:none parent. The referenced host then has zero layout size and does not repaint, but its preserved output canvas still has its previous dimensions/pixels, so this condition uploads that old output. This breaks the stated transparent-hidden-source rule for nested/timed composition layers.

I reproduced it on the freshly built runtime in real Chrome: paint a visible referenced host, then hide its parent and seek again. The referenced host reports display:block, offsetWidth:0; the receiving matte’s alpha stays 255, rather than becoming 0. Setting the host itself to hidden is a successful negative control (alpha 0). A separate actual-runtime unit witness also records the stale canvas upload. Check effective ancestor visibility/current layout before accepting a host output; cover the live→ancestor-hidden transition in both paint paths.

67 authored runtime cases and all 29 authored browser cases pass. The two independent witnesses fail on the newly covered ancestor-hidden case; they are preserved separately from the source tree. Browser bundle SHA256 cdb1bcb5f878afae7ad114e879d5a08622d8d15aa3e1561c941411700b0cdc10. Cached Vitest3.2.4/Chrome152 were reused, with pinned checkout parser source for the build; no installs or external services. No exporter-side or original AE-machine hang validation claimed.

CI’s optional Comments check still fails on the new 14-line block (base limit12); its actual log identifies the comment-length ratchet. Other current checks pass. No prior review findings at refresh. Read the four-file incremental diff, dependency linking/preview/engine ordering and resource cleanup plus the behavior-change docs; author-owned exporter compatibility remains unverified. No merge or retarget action. The clean disposable worktree is retiring after this stacked review.

— Magi

Verdict: REQUEST CHANGES
Reasoning: Processed-output binding works for normal hosts, but ancestor-hidden references retain stale pixels instead of the promised transparent output.

[miguel-heygen]

Blocker: under a display:none ancestor, this host still computes display:block, but has offsetWidth0 and skips repainting. Its preserved out canvas retains the last frame, so this condition uploads stale pixels. Fresh-runtime Chrome live→ancestor-hidden witness leaves receiving alpha255 (expected0); own-hidden control correctly gives0. Require effective visibility/current layout before reading host output and cover this transition.

[vanceingalls]

Pushed 4786c60cf for both items:

• Ancestor-hidden stale frame: the host-output upload now requires the referenced host to be on screen: visible by its own style, a non-zero layout box, and displayed through every ancestor. Otherwise the receiving host reads the 1x1 transparent texture. The ancestor display walk is one helper shared with isPaintableSource. Tests cover the live to ancestor-hidden transition in both the engine-resolve and preview-barrier paths (unit and browser, receiving alpha goes from [0,85,170,255] to [0,0,0,0]), plus an own-hidden control. Removing the guard fails both ancestor browser tests and both unit tests.
• Comments check: trimmed the two new blocks that were over the 12-line limit (13 and 14) and rewrote a stale comment that still described the removed opt-in. scripts/comment-ratchet.mjs passes locally against the merge-base.

src/runtime: 1738 tests pass, tsc clean, vfxDeterminism: 33 browser tests pass on a rebuilt bundle.