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

Geschlossen
  • Stimmt etwas nicht?
#4,366 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

@user-github-me arbeitet bereits daran.

Seit 08.10.2026.

  • #5201 von @user-github-me — offen

Bewertung

Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Anfängerfreundlichkeit
48/100
Issue-Typ
Bug
Klarheit
Größtenteils klar
Aktivitätsstatus
Aktiv
Tech-Stack
css, html, typescript
Bereich
frontend, web-dev

Rechercherichtung

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.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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.

Vorherrschende Sprache
TypeScript
Sterne
54.1k
Forks
4.9k
Ø Merge
6 Std. 28 Min.
Gemergte PRs (30 T.)
799

Entwicklungsumgebung

Dieses Projekt bietet weder Dev-Container noch Dockerfile noch Beitragsleitfaden – die Einrichtung liegt bei Ihnen. Beginnen Sie mit der README; die allgemeinen Schritte stehen in unserem Leitfaden für den ersten Beitrag.

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus heygen-com/hyperframes

Alle Issues in heygen-com/hyperframes

Ähnliche Issues

Weitere Issues zu TypeScript

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.