Skip to content

Write HTML. Render video. Built for agents.

fix(lint): flag seek-unsafe CSS transitions (#3797)

maopishouzzzf2eb6d9cc140
diff --git a/docs/packages/lint.mdx b/docs/packages/lint.mdx
index 2a4e10fc68..414f9b3fd9 100644
--- a/docs/packages/lint.mdx
+++ b/docs/packages/lint.mdx
@@ -116,6 +116,8 @@ Detected issues include:
reachable from timeline callbacks (`gsap_callback_dom_measurement`), and
non-deterministic values like `gsap.utils.random()` / `"random(...)"`
(`non_deterministic_code`)
+- CSS `transition` declarations, which run on the browser clock and restart on a cold
+ render worker (`css_transition_used`, a warning); `none` and all-zero durations are allowed
- SVG draw-on pitfalls: GSAP `strokeDasharray` writes on elements whose CSS declares a
multi-component `stroke-dasharray` (`svg_drawon_css_dasharray_conflict`),
`getTotalLength()` on paths with no `d` yet (`svg_measure_before_path_d`), and
diff --git a/packages/lint/src/rules/core.test.ts b/packages/lint/src/rules/core.test.ts
index a9474c44e0..384af0246f 100644
--- a/packages/lint/src/rules/core.test.ts
+++ b/packages/lint/src/rules/core.test.ts
@@ -821,6 +821,70 @@ describe("core rules", () => {
expect(finding).toBeUndefined();
});
+ describe("css_transition_used", () => {
+ it.each([
+ ["transition", "opacity 0.5s ease"],
+ ["transition-duration", "0.5s"],
+ ["transition-delay", "100ms"],
+ ["transition-property", "opacity"],
+ ["-webkit-transition", "opacity 0.5s ease"],
+ ["-webkit-transition-duration", "0.5s"],
+ ["transition", "opacity 0s linear 1s"],
+ ["transition-duration", "0s, .2s"],
+ ["transition-duration", "var(--speed)"],
+ ])("warns for %s declarations in style blocks", async (property, value) => {
+ const result = await lintHyperframeHtml(
+ compositionWithBodyPrefix(`<style>.card { ${property}: ${value}; }</style>`),
+ );
+ const finding = result.findings.find((item) => item.code === "css_transition_used");
+
+ expect(finding).toMatchObject({ severity: "warning", selector: ".card" });
+ expect(finding?.message).toContain(property);
+ expect(finding?.fixHint).toContain("paused GSAP timeline");
+ });
+
+ it("warns for an inline transition and identifies its element", async () => {
+ const result = await lintHyperframeHtml(
+ compositionWithBodyPrefix(
+ "",
+ '<div id="card" style="transition: opacity 0.5s ease"></div>',
+ ),
+ );
+ const finding = result.findings.find((item) => item.code === "css_transition_used");
+
+ expect(finding).toMatchObject({ severity: "warning", elementId: "card" });
+ expect(finding?.snippet).toContain('id="card"');
+ });
+
+ it.each([
+ ["transition", "none"],
+ ["transition-property", "none"],
+ ["-webkit-transition", "none"],
+ ["-webkit-transition-property", "NONE"],
+ ["transition-duration", "0s"],
+ ["transition-delay", "0ms, 0s"],
+ ["-webkit-transition-duration", "0s"],
+ ["transition", "opacity 0s ease 0s"],
+ ])("allows %s: %s", async (property, value) => {
+ const result = await lintHyperframeHtml(
+ compositionWithBodyPrefix(`<style>.card { ${property}: ${value} !important; }</style>`),
+ );
+
+ expect(result.findings.find((item) => item.code === "css_transition_used")).toBeUndefined();
+ });
+
+ it("ignores custom properties that contain transition in their name", async () => {
+ const result = await lintHyperframeHtml(
+ compositionWithBodyPrefix(
+ '<div id="card" style="--transition-speed: 0.5s"></div>',
+ "<style>.card { --transition-easing: ease; opacity: 1; }</style>",
+ ),
+ );
+
+ expect(result.findings.find((item) => item.code === "css_transition_used")).toBeUndefined();
+ });
+ });
+
describe("non_deterministic_code", () => {
it("gives randomness guidance for crypto and clock guidance for wall time", async () => {
const result = await lintHyperframeHtml(`<html><body>
diff --git a/packages/lint/src/rules/core.ts b/packages/lint/src/rules/core.ts
index adcf8c93ca..e844038f74 100644
--- a/packages/lint/src/rules/core.ts
+++ b/packages/lint/src/rules/core.ts
@@ -257,6 +257,44 @@ function ruleForcesOpacityZero(rule: postcss.Rule): boolean {
return forcesOpacityZero;
}
+const CSS_TRANSITION_PROPERTY_PATTERN = /^(?:-webkit-)?transition(?:-[a-z][a-z-]*)?$/i;
+const TRANSITION_NONE_PROPERTIES = new Set(["transition", "transition-property"]);
+const TRANSITION_TIME_PROPERTIES = new Set([
+ "transition",
+ "transition-duration",
+ "transition-delay",
+]);
+
+// All-zero times (the reduced-motion / render-lock reset) never run on the browser clock.
+function hasNonZeroTime(value: string): boolean {
+ const times = value.match(/[+-]?(?:\d*\.)?\d+m?s\b/g) ?? [];
+ return value.includes("var(") || times.some((time) => Number.parseFloat(time) !== 0);
+}
+
+function isSeekUnsafeTransition(declaration: postcss.Declaration): boolean {
+ const property = declaration.prop.trim().toLowerCase();
+ if (!CSS_TRANSITION_PROPERTY_PATTERN.test(property)) return false;
+
+ const name = property.replace(/^-webkit-/, "");
+ const value = declaration.value.trim().toLowerCase();
+ if (value === "none" && TRANSITION_NONE_PROPERTIES.has(name)) return false;
+ return !TRANSITION_TIME_PROPERTIES.has(name) || hasNonZeroTime(value);
+}
+
+function cssTransitionFinding(
+ declaration: postcss.Declaration,
+ details: Pick<HyperframeLintFinding, "selector" | "elementId" | "snippet">,
+): HyperframeLintFinding {
+ return {
+ code: "css_transition_used",
+ severity: "warning",
+ message: `CSS declaration \`${declaration.prop}: ${declaration.value}\` runs on the browser clock and cannot be seeked deterministically across render workers.`,
+ fixHint:
+ "Keep the class or attribute swap for state; put the visual change on the paused GSAP timeline.",
+ ...details,
+ };
+}
+
function isStudioTimelineElement(tag: { raw: string; name: string }): boolean {
if (["script", "style", "link", "meta", "template", "noscript"].includes(tag.name)) {
return false;
@@ -608,6 +646,55 @@ export const coreRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
return findings;
},
+ // css_transition_used
+ ({ styles, tags }) => {
+ const findings: HyperframeLintFinding[] = [];
+
+ for (const style of styles) {
+ if (!/transition/i.test(style.content)) continue;
+ let root: postcss.Root;
+ try {
+ root = postcss.parse(style.content);
+ } catch {
+ // The CSS syntax rule reports malformed style blocks separately.
+ continue;
+ }
+ root.walkDecls((declaration) => {
+ if (!isSeekUnsafeTransition(declaration)) return;
+ const selector =
+ declaration.parent?.type === "rule" ? declaration.parent.selector : undefined;
+ findings.push(
+ cssTransitionFinding(declaration, {
+ selector,
+ snippet: truncateSnippet(declaration.toString()),
+ }),
+ );
+ });
+ }
+
+ for (const tag of tags) {
+ const inlineStyle = readDecodedAttr(tag.raw, "style");
+ if (!inlineStyle || !/transition/i.test(inlineStyle)) continue;
+ let root: postcss.Root;
+ try {
+ root = postcss.parse(inlineStyle);
+ } catch {
+ continue;
+ }
+ root.walkDecls((declaration) => {
+ if (!isSeekUnsafeTransition(declaration)) return;
+ findings.push(
+ cssTransitionFinding(declaration, {
+ elementId: readDecodedAttr(tag.raw, "id") || undefined,
+ snippet: truncateSnippet(tag.raw),
+ }),
+ );
+ });
+ }
+
+ return findings;
+ },
+
// CSS selector safety
({ styles, locate }) => {
const findings: HyperframeLintFinding[] = [];
diff --git a/registry/examples/product-promo/compositions/scene2-4-canvas.html b/registry/examples/product-promo/compositions/scene2-4-canvas.html
index 2c9537337a..cf2ee20710 100644
--- a/registry/examples/product-promo/compositions/scene2-4-canvas.html
+++ b/registry/examples/product-promo/compositions/scene2-4-canvas.html
@@ -184,7 +184,6 @@
align-items: center;
justify-content: center;
padding-bottom: 100px;
- transition: transform 0.8s cubic-bezier(0.34, 1.56, 0.64, 1);
}
.hero-heading {