Skip to content

Commit 9af8ec2

Browse files
feat(lint): warn on negative z-index, which renders invisibly behind the root
Rebased onto main now that #4412 has landed, and carries the conditional wording. No behaviour change from the rebase. `composition.ts` applied cleanly — the negative-z rule and the zoom rule sit at different insertion points. The collision was the test file only: both describe blocks append at the same position in the outer describe. Both purely additive, so the resolution keeps both and edits neither. Verified against c5f454b, the head under review: 82 lines this PR added to composition.ts -> 0 absent after the rebase 81 lines this PR added to composition.test.ts -> 0 absent after the rebase every non-blank line of main -> 0 absent after the rebase Both files parse with zero syntax errors and are oxfmt-clean. The message under review is unchanged by the rebase: the mechanism stated as fact, the hiding conditional on an opaque root background, and the transparent-root case named explicitly, because with a transparent root the element is visible at full coverage. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 201c829 commit 9af8ec2

2 files changed

Lines changed: 223 additions & 0 deletions

File tree

‎packages/lint/src/rules/composition.test.ts‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2297,4 +2297,125 @@ describe("composition rules", () => {
22972297
expect(codes(result)).not.toContain("root_zoom_rescales_a_fixed_canvas");
22982298
});
22992299
});
2300+
2301+
describe("negative z-index", () => {
2302+
const wrap = (
2303+
head: string,
2304+
body: string,
2305+
) => `<!doctype html><html><head><style>${head}</style></head><body>
2306+
<div id="root" data-composition-id="main" data-no-timeline data-width="640" data-height="360" data-start="0" data-duration="1">
2307+
${body}
2308+
</div>
2309+
</body></html>`;
2310+
2311+
it("flags a negative z-index in a style block and names the selector", async () => {
2312+
const result = await lintHyperframeHtml(
2313+
wrap(
2314+
"#under { position:absolute; z-index: -1; }",
2315+
` <div id="under" class="clip" data-start="0" data-duration="1"></div>`,
2316+
),
2317+
);
2318+
const finding = result.findings.find((f) => f.code === "negative_z_index");
2319+
expect(finding).toBeDefined();
2320+
expect(finding?.severity).toBe("warning");
2321+
expect(finding?.selector).toBe("#under");
2322+
expect(finding?.message).toContain("z-index: -1");
2323+
});
2324+
2325+
// Reviewed nit, confirmed on rendered pixels at 0.8.72: the element is only
2326+
// dropped when its nearest ancestor stacking context is the composition root.
2327+
// One frame carried the same `z-index: -1` band under isolation:isolate,
2328+
// transform, opacity<1, filter, contain:paint and will-change -- all six
2329+
// PRESENT at full coverage, the no-stacking-context control ABSENT at zero.
2330+
// This rule matches CSS text and cannot resolve the cascade, so it fires on
2331+
// both shapes; the message must therefore stay conditional.
2332+
it("states the stacking-context CONDITION rather than asserting absence", async () => {
2333+
const result = await lintHyperframeHtml(
2334+
wrap(
2335+
"#under { position:absolute; z-index: -1; }",
2336+
` <div id="under" class="clip" data-start="0" data-duration="1"></div>`,
2337+
),
2338+
);
2339+
const finding = result.findings.find((f) => f.code === "negative_z_index");
2340+
expect(finding?.message).toContain("behind its nearest stacking context");
2341+
// Reviewer's edge case: with a TRANSPARENT composition root the element is
2342+
// VISIBLE (measured), so the hiding must be stated as CONDITIONAL on an opaque
2343+
// background, never asserted outright.
2344+
expect(finding?.message).toContain("an opaque background there hides it");
2345+
expect(finding?.message).toContain("A transparent root leaves it visible");
2346+
expect(finding?.message).not.toContain("renders invisibly unless");
2347+
// The cause is painting order, not a tool failure. Both phrasings below imply
2348+
// the renderer dropped the element, which the pixels refute.
2349+
expect(finding?.message).not.toContain("is silently dropped");
2350+
expect(finding?.message).not.toContain("zero exit code");
2351+
});
2352+
2353+
it("offers a stacking context as the measured remedy, not only DOM reordering", async () => {
2354+
const result = await lintHyperframeHtml(
2355+
wrap(
2356+
"#under { position:absolute; z-index: -1; }",
2357+
` <div id="under" class="clip" data-start="0" data-duration="1"></div>`,
2358+
),
2359+
);
2360+
const finding = result.findings.find((f) => f.code === "negative_z_index");
2361+
expect(finding?.fixHint).toContain("isolation: isolate");
2362+
expect(finding?.fixHint).toContain("DOM order");
2363+
});
2364+
2365+
it("flags a negative z-index in an inline style attribute", async () => {
2366+
const result = await lintHyperframeHtml(
2367+
wrap(
2368+
"",
2369+
` <div id="under" class="clip" style="position:absolute;z-index:-2" data-start="0" data-duration="1"></div>`,
2370+
),
2371+
);
2372+
const finding = result.findings.find((f) => f.code === "negative_z_index");
2373+
expect(finding).toBeDefined();
2374+
expect(finding?.selector).toBe("#under");
2375+
});
2376+
2377+
it("does not flag zero or positive z-index", async () => {
2378+
const result = await lintHyperframeHtml(
2379+
wrap(
2380+
"#a { z-index: 0; } #b { z-index: 1; } #c { z-index: 999; }",
2381+
` <div id="a"></div>`,
2382+
),
2383+
);
2384+
expect(result.findings.some((f) => f.code === "negative_z_index")).toBe(false);
2385+
});
2386+
2387+
it("does not flag a custom property whose name ends in z-index", async () => {
2388+
// Regression: /\bz-index\b/ treats the hyphen as a word break, so a plain
2389+
// boundary matches `--panel-z-index: -1`, which declares a variable and
2390+
// stacks nothing.
2391+
const result = await lintHyperframeHtml(
2392+
wrap("#a { --z-index: -1; --panel-z-index: -3; }", ` <div id="a"></div>`),
2393+
);
2394+
expect(result.findings.some((f) => f.code === "negative_z_index")).toBe(false);
2395+
});
2396+
2397+
it("does not flag a negative z-index inside a CSS comment", async () => {
2398+
const result = await lintHyperframeHtml(
2399+
wrap(
2400+
"#a { /* z-index: -1; was dropped by the renderer */ z-index: 2; }",
2401+
` <div id="a"></div>`,
2402+
),
2403+
);
2404+
expect(result.findings.some((f) => f.code === "negative_z_index")).toBe(false);
2405+
});
2406+
2407+
it("does not flag -0, which is not a negative stacking level", async () => {
2408+
const result = await lintHyperframeHtml(
2409+
wrap("#a { z-index: -0; }", ` <div id="a"></div>`),
2410+
);
2411+
expect(result.findings.some((f) => f.code === "negative_z_index")).toBe(false);
2412+
});
2413+
2414+
it("flags every negative declaration, not just the first", async () => {
2415+
const result = await lintHyperframeHtml(
2416+
wrap("#a { z-index: -1; } #b { z-index: -2; }", ` <div id="a"></div>`),
2417+
);
2418+
expect(result.findings.filter((f) => f.code === "negative_z_index")).toHaveLength(2);
2419+
});
2420+
});
23002421
});

‎packages/lint/src/rules/composition.ts‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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-index\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+
416464
export 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

Comments
 (0)