@@ -413,6 +413,54 @@ function isInsideInertTemplate(tag: OpenTag, tags: readonly OpenTag[]): boolean
413413 ) ;
414414}
415415
416+ // `(?<![\w-])` not `\b`: the hyphen in a custom property is a word break, so a
417+ // plain boundary matches `--z-index: -1` and `--panel-z-index: -1`, which
418+ // declare variables and stack nothing. `-0` is excluded because it is not a
419+ // negative stacking level; `-01` and `-0.5` are.
420+ const NEGATIVE_Z_INDEX = / (?< ! [ \w - ] ) z - i n d e x \s * : \s * - (? ! 0 (?: \s * [ ; } ] | \s * $ ) ) ( [ \d . ] + ) / g;
421+
422+ // Name the selector that owns the declaration so the finding points at
423+ // something the author can search for.
424+ function cssOwnerSelector ( content : string , matchIndex : number ) : string | undefined {
425+ const blockStart = content . lastIndexOf ( "{" , matchIndex ) ;
426+ if ( blockStart === - 1 ) return undefined ;
427+ const previousBlockEnd = content . lastIndexOf ( "}" , blockStart ) ;
428+ const lines = content
429+ . slice ( previousBlockEnd + 1 , blockStart )
430+ . trim ( )
431+ . split ( "\n" ) ;
432+ return lines [ lines . length - 1 ] ?. trim ( ) || undefined ;
433+ }
434+
435+ function elementSelector ( tag : OpenTag ) : string | undefined {
436+ const elementId = readAttr ( tag . raw , "id" ) ;
437+ return elementId ? `#${ elementId } ` : undefined ;
438+ }
439+
440+ function negativeZIndexFinding (
441+ match : RegExpExecArray ,
442+ selector : string | undefined ,
443+ ) : HyperframeLintFinding {
444+ const level = match [ 1 ] ?? "" ;
445+ return {
446+ code : "negative_z_index" ,
447+ severity : "warning" ,
448+ ...( selector ? { selector } : { } ) ,
449+ message :
450+ `\`z-index: -${ level } \` paints the element behind its nearest stacking context's own content. ` +
451+ "With no stacking-context ancestor that context is the composition root itself, so an opaque " +
452+ "background there hides it entirely: in the DOM, laid out, and absent from the picture. " +
453+ "A transparent root leaves it visible. Siblings at `z-index: 0` or above are unaffected." ,
454+ fixHint :
455+ "Give the element's parent a stacking context - `isolation: isolate` is the cheapest, and " +
456+ "`transform`, `filter`, `opacity` below 1, `contain: paint` and `will-change` all work too. " +
457+ "The negative-z child then paints above that parent's background and renders normally. " +
458+ "Or express paint order through DOM order - an earlier sibling paints behind a " +
459+ "later one - and raise the elements that should sit in front rather than lowering this one." ,
460+ snippet : truncateSnippet ( match [ 0 ] ) ,
461+ } ;
462+ }
463+
416464export const compositionRules : Array < ( ctx : LintContext ) => HyperframeLintFinding [ ] > = [
417465 // duplicate_composition_id catches meta-tag/root collisions that create duplicate composition entries.
418466 ( { tags } ) => {
@@ -803,6 +851,60 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
803851 ] ;
804852 } ,
805853
854+ // negative_z_index
855+ // An element at a negative z-index is silently absent from both `snapshot`
856+ // and `render`, while siblings differing only in the sign of z-index render
857+ // exactly (heygen-com/hyperframes#4366). lint, validate and render all exit 0
858+ // and report nothing, so the first suspicion falls on the author's own CSS.
859+ // NOT A RENDERER DEFECT -- ORDINARY CSS PAINTING ORDER, measured at 0.8.72.
860+ // The element is PAINTED; it is simply painted beneath something opaque. Remove
861+ // every opaque background above it and the same `z-index: -1` band renders at
862+ // full coverage, identically to the same band with `z-index` deleted. A negative-z
863+ // descendant paints at step 2 of its nearest stacking context -- above that
864+ // context root's own background, but below the context's positioned in-flow
865+ // content -- so a `position: relative` composition root with an opaque background
866+ // paints over it. That is the shape #4366 reports; nothing is dropped and the
867+ // renderer has no say in it.
868+ //
869+ // Kept as a warning because authors hit it and nothing explains why: the element
870+ // is in the DOM, laid out, and invisible. The message therefore names the CAUSE
871+ // and the remedy rather than implying the tool failed.
872+ //
873+ // THE CONDITION IS LOAD-BEARING AND THE MESSAGE STATES IT. The element is only
874+ // dropped when its nearest ancestor stacking context is the composition root,
875+ // which is the shape #4366 reports. Give any ancestor a stacking context and it
876+ // renders correctly: measured at 0.8.72 on ONE frame carrying the same
877+ // `z-index: -1` band under six triggers -- isolation:isolate, transform,
878+ // opacity below 1, filter, contain:paint, will-change -- all six PRESENT at full
879+ // coverage, against the no-stacking-context control ABSENT at zero coverage.
880+ // That is ordinary CSS painting order: a negative-z child paints above its
881+ // stacking context root's own background, so only the root case is hidden.
882+ //
883+ // This rule matches CSS TEXT and does not resolve the cascade, so it cannot know
884+ // whether an ancestor forms a stacking context and fires on both shapes. That is
885+ // why the message is CONDITIONAL rather than an assertion of absence: an
886+ // unconditional "silently dropped" is false for every isolated case, and a lint
887+ // message that overclaims is how authors learn to disregard the rule.
888+ ( { tags, styles } ) => {
889+ const findings : HyperframeLintFinding [ ] = [ ] ;
890+ for ( const style of styles ) {
891+ const content = stripCssComments ( style . content ) ;
892+ NEGATIVE_Z_INDEX . lastIndex = 0 ;
893+ let match : RegExpExecArray | null ;
894+ while ( ( match = NEGATIVE_Z_INDEX . exec ( content ) ) !== null ) {
895+ findings . push ( negativeZIndexFinding ( match , cssOwnerSelector ( content , match . index ) ) ) ;
896+ }
897+ }
898+ for ( const tag of tags ) {
899+ const inline = readAttr ( tag . raw , "style" ) ;
900+ if ( ! inline ) continue ;
901+ NEGATIVE_Z_INDEX . lastIndex = 0 ;
902+ const match = NEGATIVE_Z_INDEX . exec ( inline ) ;
903+ if ( match ) findings . push ( negativeZIndexFinding ( match , elementSelector ( tag ) ) ) ;
904+ }
905+ return findings ;
906+ } ,
907+
806908 // requestanimationframe_in_composition
807909 ( { scripts, rawSource, options } ) => {
808910 if ( isRegistrySourceFile ( options . filePath ) || isRegistryInstalledFile ( rawSource ) ) return [ ] ;
0 commit comments