Clip with z-index: -1 silently does not render (snapshot and render); z-index 0 and 1 siblings are fine

Fechada
  • Algo errado?
#4,366 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

@user-github-me já está trabalhando nisso.

Desde 8/10/2026.

  • #5201 de @user-github-me — aberto

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
48/100
Tipo de issue
Bug
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
css, html, typescript
Domínio
frontend, web-dev

Direção de pesquisa

Read docs/AGENTS.md first, then verify the plain-browser control and the HyperFrames snapshot/render commands. Inspect docs/concepts/data-attributes.mdx and docs/reference/html-schema.mdx alongside the paint-order guidance; done requires an agreed documentation-versus-diagnostic scope, verified examples, and passing documentation validation and link checks.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

triage/needs-design

Summary

A clip with z-index: -1 does not render. Sibling clips with z-index: 0 and z-index: 1, identical in every other respect, render correctly. The element is silently absent — no warning from lint, validate or render, and the render exits 0.

This affects both snapshot and render, so it is not capture-specific.

Affected

[email protected].

Reproduce

index.html — three absolutely-positioned full-width bands, identical class="clip" attributes, differing only in z-index:

<!doctype html>
<html lang="en">
  <head><meta charset="UTF-8" /><meta name="viewport" content="width=640, height=360" />
    <style>
      * { margin:0; padding:0; box-sizing:border-box; }
      html, body { width:640px; height:360px; overflow:hidden; background:#0a0a0a; }
      #root { width:100%; height:100%; }
      #underA { position:absolute; left:0; top:0;     width:640px; height:180px; background:#f5e6c8; z-index:-1; }
      #underB { position:absolute; left:0; top:180px; width:640px; height:180px; background:#20a0f0; z-index:0;  }
      #over   { position:absolute; left:20px; top:20px; width:60px; height:60px; background:#d02020; z-index:1;  }
    </style>
  </head>
  <body>
    <div id="root" data-composition-id="main" data-start="0" data-duration="1" data-width="640" data-height="360">
      <div id="underA" class="clip" data-start="0" data-duration="1" data-track-index="0"></div>
      <div id="underB" class="clip" data-start="0" data-duration="1" data-track-index="1"></div>
      <div id="over"   class="clip" data-start="0" data-duration="1" data-track-index="2"></div>
    </div>
  </body>
</html>

hyperframes snapshot . --at 0.5 --no-end -o snap --describe false
hyperframes render . -o out.mp4

Measured

Mean RGB sampled inside each band:

element authored snapshot render
z-index: -1 (245,230,200) (10,10,10) (7,9,9)
z-index: 0 (32,160,240) (32,160,240) (29,157,238)
z-index: 1 (208,32,32) (208,32,32) (206,30,27)

(10,10,10) is the bare body background — the band is not drawn at all, rather than drawn and covered. The z-index: 0 and z-index: 1 bands land on their authored values in both paths (the small render deltas are encode rounding).

Expected

Either the band renders, or something says why it does not. Per CSS painting order a negative-z-index child paints above the canvas background and below its parent's content, so on a transparent #root over a dark body the band should be visible.

If clips are composited such that negative z-index is deliberately out of range, that is a reasonable design choice — but it is currently undocumented and silent, and the failure is invisible at every gate: lint passes, validate passes, the render exits 0, and the output is a plausible-looking file with an element missing.

Suggested

Whichever way it is resolved, the valuable half is a diagnostic: flag a negative z-index on a clip at lint time, or warn at render when a declared element contributes zero pixels. Silent omission is the expensive failure mode — an absent element is indistinguishable from one that was authored wrong, so debugging effort goes to the composition rather than to the pipeline.

Workaround for anyone hitting this: express paint order with DOM order (insertBefore) rather than negative z-index. Positive values behave correctly.

Triage follow-up — September 23, 2026

A plain-browser control reproduces the essential symptom without HyperFrames. In Chrome 150.0.7871.24, the supplied negative-z-index band over the opaque body background yields RGB (10,10,10) at (200,80). Adding isolation: isolate to #root changes that pixel to the expected band RGB (245,230,200).

This is evidence of CSS stacking behavior, not by itself evidence that HyperFrames drops an element. The isolated control has not yet been compared across HyperFrames snapshot/render, so this issue is not being closed.

Decision needed

The smallest contribution candidate is documenting negative-z-index stacking and a minimal before/after example beside the paint-order guidance in docs/concepts/data-attributes.mdx and docs/reference/html-schema.mdx. A diagnostic is a separate scope decision: blanket rejection of negative z-index would reject valid CSS.

For a documentation task, verify the example in a plain browser and HyperFrames snapshot/render, explain that track order is not paint order, and run the documentation validation/link checks. Read docs/AGENTS.md first. Difficulty remains unset on this broader issue until the documentation-versus-diagnostic scope is selected.

Linguagem predominante
TypeScript
Estrelas
54.1k
Forks
4.9k
Merge médio
6h 8min
PRs com merge (30d)
797

Preparar o ambiente

Este projeto não oferece contêiner de desenvolvimento, Dockerfile nem guia de contribuição, então a configuração fica por sua conta: comece pelo README e veja nosso guia da primeira contribuição para os passos gerais.

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de heygen-com/hyperframes

Todas as issues de heygen-com/hyperframes

Issues semelhantes

Mais issues de TypeScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.