@hyperframes/lint 0.7.42 → 0.7.44

package/dist/index.js

@@ -2009,6 +2009,127 @@ ${right.raw}`)
     }
     return findings;
   },
+  // gsap_non_transform_motion — animating layout props (left/top/right/bottom/margin*)
+  // or using roundProps snaps motion to integer device pixels. On the seek-by-frame
+  // capture engine this looks smooth at high per-frame deltas (fast tweens) but visibly
+  // stutters at low deltas (slow tweens / ease-out tails): sub-pixel movement rounds to
+  // the same pixel for several frames, then jumps a whole pixel. Transforms (x/y/scale)
+  // interpolate sub-pixel and stay smooth.
+  //
+  // EXEMPTION: elements rasterized via the html-in-canvas API — those under a
+  // `<canvas layoutsubtree>` ancestor (e.g. the liquid-glass blocks) — are NOT laid out
+  // by the browser compositor. The canvas lib reads getComputedStyle().left/top (a
+  // sub-pixel value) and draws the element to a bitmap, so animating a layout prop on
+  // them does not integer-snap and does not stutter. We resolve each tween's target to
+  // its element(s) and skip the finding only when EVERY target is html-in-canvas; a
+  // grouped tween that also touches a plain-DOM element (which does stutter) still fires.
+  //
+  // No suppression by design: there is intentionally no per-line/per-file opt-out (unlike
+  // eslint-disable). The stance is fix-the-motion, not silence-the-rule — a plain-DOM
+  // layout-prop animation always has a faithful transform equivalent (per-glyph x for
+  // spacing, scale for size, x/y for position). An author who has consciously accepted a
+  // stutter still has no flag to flip; that is deliberate, not a missing feature.
+  async ({ scripts, tags, source }) => {
+    const findings = [];
+    const layoutSubtreeRanges = tags.filter((t) => t.name.toLowerCase() === "canvas" && /\blayoutsubtree\b/i.test(t.raw)).map((t) => ({ start: t.index, end: findTagEnd(source, t) }));
+    const isHtmlInCanvas = (tag) => layoutSubtreeRanges.some((r) => tag.index > r.start && tag.index < r.end);
+    const tagsByToken = /* @__PURE__ */ new Map();
+    const addToken = (token, tag) => {
+      const list = tagsByToken.get(token);
+      if (list) list.push(tag);
+      else tagsByToken.set(token, [tag]);
+    };
+    for (const tag of tags) {
+      const id = readAttr(tag.raw, "id");
+      if (id) addToken(`#${id}`, tag);
+      for (const cls of readAttr(tag.raw, "class")?.split(/\s+/).filter(Boolean) ?? [])
+        addToken(`.${cls}`, tag);
+    }
+    const allTargetsHtmlInCanvas = (selector) => {
+      if (layoutSubtreeRanges.length === 0) return false;
+      const matched = [...targetedSelectorTokens(selector)].flatMap(
+        (token) => tagsByToken.get(token) ?? []
+      );
+      return matched.length > 0 && matched.every(isHtmlInCanvas);
+    };
+    const LAYOUT_FIX = {
+      left: ["x"],
+      right: ["x"],
+      top: ["y"],
+      bottom: ["y"],
+      margin: ["x", "y"],
+      marginLeft: ["x"],
+      marginRight: ["x"],
+      marginTop: ["y"],
+      marginBottom: ["y"]
+    };
+    const REFLOW_PROPS = ["letterSpacing", "wordSpacing", "fontSize"];
+    const parseGsapScript = await loadParseGsapScript();
+    for (const script of scripts) {
+      if (!/gsap\.timeline/.test(script.content)) continue;
+      const parsed = parseGsapScript(script.content);
+      const calls = [
+        ...parsed.animations.map((anim) => ({
+          method: anim.method,
+          selector: anim.targetSelector,
+          // Union the from-vars: a fromTo() can animate a layout/reflow prop that appears
+          // only in its first ("from") object, which is just as stutter-prone as the to-vars.
+          properties: [
+            .../* @__PURE__ */ new Set([
+              ...Object.keys(anim.properties),
+              ...Object.keys(anim.fromProperties ?? {})
+            ])
+          ],
+          raw: synthesizeWindowRaw(parsed.timelineVar, anim)
+        })),
+        ...extractStandaloneGsapTransformCalls(stripJsComments(script.content))
+      ];
+      for (const call of calls) {
+        if (call.method === "set") continue;
+        let layoutProps = call.properties.filter((p) => Object.hasOwn(LAYOUT_FIX, p));
+        const reflowProps = call.properties.filter((p) => REFLOW_PROPS.includes(p));
+        const usesRoundProps = call.properties.includes("roundProps");
+        if (layoutProps.length > 0 && allTargetsHtmlInCanvas(call.selector)) layoutProps = [];
+        if (layoutProps.length === 0 && reflowProps.length === 0 && !usesRoundProps) continue;
+        const flagged = [...layoutProps, ...reflowProps, ...usesRoundProps ? ["roundProps"] : []];
+        const message = `GSAP tween on "${call.selector}" uses motion that snaps to integer device pixels: ${flagged.join(", ")}. Layout and text-reflow properties snap during browser layout; roundProps rounds the tween value. Slow motion or an ease-out tail then stutters under the seek-by-frame capture engine \u2014 animate transforms (x/y/scale/opacity) instead.`;
+        const fixes = [];
+        if (layoutProps.length > 0) {
+          const tokens = [...new Set(layoutProps.flatMap((p) => LAYOUT_FIX[p] ?? []))];
+          fixes.push(
+            `replace ${layoutProps.join("/")} with the transform equivalent (${tokens.join(", ")}) \u2014 e.g. tl.fromTo("${call.selector}", { x: -1300 }, { x: 0, ...yourAnimation })`
+          );
+        }
+        if (reflowProps.length > 0) {
+          const sizing = reflowProps.filter((p) => p === "fontSize");
+          const spacing = reflowProps.filter((p) => p !== "fontSize");
+          const parts = [];
+          if (sizing.length > 0) {
+            parts.push(`replace ${sizing.join("/")} with scale (same visual, no reflow)`);
+          }
+          if (spacing.length > 0) {
+            parts.push(
+              `for ${spacing.join("/")}, split the text into per-character elements and animate each glyph's x (the spread) \u2014 uniform scale is NOT equivalent \u2014 or hold the final value statically`
+            );
+          }
+          fixes.push(
+            `do not animate ${reflowProps.join("/")} (they reflow text and snap glyph positions): ` + parts.join("; ")
+          );
+        }
+        if (usesRoundProps) fixes.push("remove roundProps");
+        const fixHint = `${fixes.join("; ")}. Transforms interpolate sub-pixel and stay smooth at any speed.`;
+        findings.push({
+          code: "gsap_non_transform_motion",
+          severity: "error",
+          message,
+          selector: call.selector,
+          fixHint,
+          snippet: truncateSnippet(call.raw)
+        });
+      }
+    }
+    return findings;
+  },
   // gsap_group_selector_keyframes
   ({ scripts }) => {
     const findings = [];
@@ -3702,6 +3823,7 @@ async function lintProject(projectDir) {
       const html = readFileSync(filePath, "utf-8");
       const compSrcPath = `compositions/${file}`;
       allHtmlSources.push({ html, compSrcPath });
+      if (isSnippetFragment(html)) continue;
       const result = await lintHyperframeHtml(html, {
         filePath,
         isSubComposition: true,
@@ -3984,6 +4106,11 @@ function lintMissingOrEmptySubComposition(projectDir, rootHtml) {
   }
   return findings;
 }
+function isSnippetFragment(html) {
+  const firstTag = html.match(/<[a-zA-Z][^>]*>/);
+  if (!firstTag) return false;
+  return /\bdata-hf-snippet\b/.test(firstTag[0]);
+}
 export {
   lintHyperframeHtml,
   lintMediaUrls,