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

Cerrado
  • ¿Algo no está bien?
#4,366 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@user-github-me ya está trabajando en esto.

Desde el 8/10/2026.

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

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
48/100
Tipo de issue
Error
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
css, html, typescript
Área
frontend, web-dev

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
TypeScript
Estrellas
54.1k
Forks
4.9k
Merge medio
6 h 8 min
PR fusionados (30 d)
797

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de heygen-com/hyperframes

Todos los issues de heygen-com/hyperframes

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.